A playbook for the development shard of the Quick Start, driven from the service dashboard (the dashboard's command line, or run_command of its MCP server, see the agent playbook). Worked example: the Ring terminals of Silan and the twenty classic newbie towns, added to the core4 leveldesign on a running shard.
The Paths of pipeline\shard_dev\local.cfg include the leveldesign checkout itself (<root>/leveldesign), so the services read the primitives (primitives/**/*.primitive, primitives.cfg, file_index.cfg) and the translations (translation/translated/*) straight from the working copy. The sheets are different: the services load the packed sheets and sheet_id.bin that the build pipeline writes into pipeline/install and pipeline/shard.
| Change | What it takes |
|---|---|
| A primitive file the AI service already loaded | Unload, load and spawn it on that service: nothing restarts. |
| A new primitive file | Register it, then restart the AI services that load its map. The rest of the shard keeps running. |
| Phrases, words, bot names | Reload them on the IOS; bots spawned before keep their name until they spawn again. |
| A new or changed sheet (creature, item, ...) | The leveldesign projects of the build pipeline, then a shard restart; the client needs the new sheets too. |
primitives/primitives.cfg puts each file in a map ("MAP fyros_newbieland", "FILE ring_entry_fyros_newbie.primitive") of a continent. Each AI service runs a set of continents, given by the -m option of its command line in patchman/shard_ctrl_definitions.txt (ais_fyros: -mCommon:Indoors:Fyros:FyrosNewbie:FyrosIsland:Post, ais_newbieland: -mCommon:Newbieland:Post), and each of these names a block StartCommandsWhenMirrorReady<Name> in patchman/default/ai_service.cfg that loads the maps of a continent (loadMapsFromCommon fyros_newbie_all). So the classic newbie continents are run by the AI service of their race, and Silan by ais_newbieland.
On the AI service that loaded it:
unloadPrimitiveFile ring_entry_zorai_newbie.primitive
loadPrimitiveFile ring_entry_zorai_newbie.primitive
spawnManagers ring_entry_zorai_newbie
unloadPrimitiveFile removes the managers and regions of the file (1 manager removed, 0 region removed). loadPrimitiveFile reads it again; the binary cache (primitive_cache/<file>.binprim in the service's write folder) is skipped when the XML is newer. The managers of a file loaded this way are not spawned: at start-up the service spawns its instances after loading everything, a load later does not. Without spawnManagers <manager name> (once per npc_manager of the file) the bots exist on the service, listBots lists them, and nobody sees them in game.
Failed to open file '<file>', error 2 on each load is the service trying the bare name in its working folder before the search paths; the next line names the file it found.
primitives/file_index.cfg, after the last one, and raise Last used file alias. The number is the file part of every alias in the file and must never change once used. Taking it above the last number of the classic index as well keeps the two apart."FILE <name>.primitive" line to the map that should load it in primitives/primitives.cfg.restart_process ({"process": "ais_zorai", "wait_seconds": 120}). Players stay connected; the bots of that service go away and come back, and creatures spawned by event commands on it are gone for good.A running service reads file_index.cfg only at start, so it cannot give a new file its alias base; and loadMapsFromCommon keeps a set of the files it loaded at start-up. That is why a new file needs the restart.
On the IOS:
smReload
loadBotNames bot_names.txt 1
smReload reloads the phrases and words of every language (reload done.). loadBotNames reloads bot_names.txt, the table that maps bot names from the primitives to their display names (1 drops the table first). A bot shows the name it had when it spawned: respawn it (above) to see a new one.
A bot shows its own name (ring_entry_sheng_wo) when bot_names.txt has no line for it. Reusing a name that has one is often the simplest: the classic Ring terminals are all device_ring_warp (and ring_entry_newbieland on Silan), which bot_names.txt maps to the title $gn_device_ring_warp$, translated in every title_words_<lang>.txt ("Ring Terminal").
A creature or item sheet that does not exist yet, or a changed one, goes through the leveldesign projects of the build pipeline (the sheets and sheet_id processes, as _configure.bat runs them), and the shard has to restart to load the new packed sheets. The development client reads the installed data directly; a client from a patch needs a new patch. Check first whether the sheet is there: the Ring terminal look object_karavan_device_neutrl_sel.creature was already in core4 (leveldesign/game_elem/creature/objects/karavan/, and in pipeline/install/data_leveldesign/sheet_id.bin), so the terminals needed no sheet work.
Without a Ring terminal, players cannot reach Ring sessions. The core4 leveldesign had none, while classic has them in Silan and the capitals. A terminal is an npc_bot with chat_parameters web: MENU_RING_ENTRY ring_access_point=1 (the client turns a web page whose URL has ring_access_point=1 into the Ring session window), is_stuck true and sheet_client object_karavan_device_neutrl_sel, in an npc_manager > npc_zone (ai_activity no_change, ai_movement stand_on_start_point) > npc_group. The core4 files are primitives/newbieland/ring_entry_newbieland.primitive (Silan, at the place of the classic terminal) and primitives/<race>/nland/ring_entry_<race>_newbie.primitive (five towns each, next to the newbie spawn point of each town, facing it). They went live by restarting the five AI services once (new files), and a later change to them by unloading, loading and spawning on each service.