This page is for agents (Claude Code and others) working on the development shard of the Quick Start package on Windows. Everything below goes through the service dashboard MCP server and plain HTTP, so it needs no window and no client. Each command on this page was run against a real development shard.
client_dev.bat, shard_*.bat, cmd_*.bat) set PATH from .nel\path_config.bat..nel, code, pipeline (for example Y:\ryzomcore). Paths below are relative to it.In the quick start root, .mcp.json registers _servdash_mcp.bat, the MCP server of the dashboard tool the shard scripts use. A session started in the root has the tools directly. From another folder, a small stdio client does the same. It needs the externals on PATH only through the batch file it starts:
# mcp_call.py <tool> [json-args] : one MCP tool call against every running dashboard of the user
import json, subprocess, sys, os
ROOT = "Y:\\ryzomcore"
tool = sys.argv[1]
args = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}
env = dict(os.environ)
env.pop("NoDefaultCurrentDirectoryInExePath", None)
proc = subprocess.Popen([ "cmd", "/c", ROOT + "\\_servdash_mcp.bat" ], cwd=ROOT, env=env,
stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
def send(obj):
proc.stdin.write(json.dumps(obj) + "\n"); proc.stdin.flush()
def recv(want):
while True:
line = proc.stdout.readline()
if not line:
sys.exit("server closed")
msg = json.loads(line) if line.strip() else {}
if msg.get("id") == want:
return msg
send({ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "probe", "version": "1" } } })
recv(1)
send({ "jsonrpc": "2.0", "method": "notifications/initialized" })
send({ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": tool, "arguments": args } })
res = recv(2)
for c in res.get("result", {}).get("content", []):
print(c.get("text", ""))
if "error" in res:
print("ERROR", json.dumps(res["error"]))
proc.stdin.close(); proc.terminate()
Run it with the Python of the externals package, C:\2026q4_external_v143_x64\python315\python.exe -I mcp_call.py list_dashboards. That Python runs isolated (no site): use sys.exit, not exit.
A new MCP server answers only once it holds the whole state of the dashboards (protocol 3 and later), so the first call of a one-shot client sees every process, its held log lines and its command table.
Start the web first, then the unifier, then the mainland (and the Ring when needed), from the root: web_on.bat, shard_unifier.bat, shard_mainland.bat. Each opens a dashboard that starts its services by priority.
When an agent shell starts these scripts through cmd, clear NoDefaultCurrentDirectoryInExePath first: agent shells often set it, and then cmd refuses to run the root's _configure.bat, _r_check.bat and the other scripts that the quick start calls by bare name ("is not recognized as an internal or external command"). Scripts that may stop at pause or a Retry/Skip/Abort choice get their answers from a file on stdin.
Wait for a whole dashboard instead of polling:
wait_for_state { "dashboard": "Mainland", "state": "ready", "wait_seconds": 600 }
-> Every process of 'Mainland' (...) is ready (19 processes, waited 38.8 s).
The wait returns early when a process exits, crashes or is relaunched, with its last lines. The argument is wait_seconds (60 by default). list_processes shows the boot facts per process (start count 1, ready after 21.3 s, last exit: ...), and one call collects every error of a dashboard since its start:
get_log { "dashboard": "Mainland", "levels": ["ERR", "AST"], "since_start": true }
On a first start of a fresh shard the EGS logs Failed to parse buffer due to invalid header for save files that do not exist yet; that is expected.
shutdown_dashboard stops the services of a dashboard and exits it. Stop in the reverse order: Ring, Mainland, Unifier, Web.
shutdown_dashboard { "dashboard": "Mainland", "wait_seconds": 240 }
The client logs in over HTTP in two steps, and an agent can do the same to prove the web, the login service, the shard unifier and the welcome service work together:
ASK=$(curl -s "http://localhost:9042/login/r2_login.php?cmd=ask&cp=2&login=<login>&lg=en") # 1:<salt>
HASH=$(php -r 'echo crypt($argv[1], $argv[2]);' '<password>' "${ASK#1:}")
curl -s -G http://localhost:9042/login/r2_login.php --data-urlencode cmd=login --data-urlencode login=<login> \
--data-urlencode "password=$HASH" --data-urlencode clientApplication=dev --data-urlencode cp=2 --data-urlencode lg=en
# 1#<cookie>#<host>:<fes port>#http://<host>:9042/ring/web_start.php#http://<host>:9042/ring/
clientApplication is the domain of the client (dev for the development client, from Application in its client.cfg). 3007 means the application name does not match; 3003 means the web could not reach the login service or the session manager at the addresses of the domain row (nel.domain), which for the development domain are 127.0.0.1:46993 and 127.0.0.1:46994. Use the PHP of the externals package with -c pipeline\shard_dev\web\php\php.ini.
The EGS lists the characters online with their entity id:
run_command { "dashboard": "Mainland", "process": "egs_mainland", "command": "displayPlayers" }
-> Player: 13 Name: Liaihao(Mainland) ID: (0x00000000d0:00:00:8e) FE: 142 Sheet: zorai.race_stats ... Pos: 7773,-4870,-15 Session: 901
Position and heading come from the mirror, through the GPMS. X and Y are in metres, Theta is the heading in radians (0 faces +X, east):
run_command { "dashboard": "Mainland", "process": "gpms_mainland", "command": "displayMirrorRow", "args": ["(0x00000000d0:00:00:8e)"] }
-> X: 7773.480 ... Y: -4870.979 ... Theta: -3.10558 ...
The event* commands of the EGS are the live event toolkit of the Event Managers, the EM privilege of client_commands_privileges.txt (eventCreateNpcGroup :DEV:SGM:GM:EM:). They are in the 2007 Nevrax/Gameforge tree. There, eventCreateNpcGroup had no position: it spawned the group where the Event Manager stood. The orientation, name, position, client sheet and place options came later from Winch Gate.
The rest of the family shows how they were used:
eventNpcSay, eventSetNpcGroupEmote and eventSetBotFacing make the NPCs act.eventSetBotName, eventSetBotScale and eventSetBotSheet dress them up.eventSetBotFaction, eventSetBotFameByKill and eventSetBotURL give them a side, a fame reward and a web menu.eventGiveControl and eventLeaveControl let the Event Manager move a bot like their own character.eventNpcGroupScript runs an AI script on the group, which is how a group gets its behaviour.An event group is therefore a blank puppet, an NPC group with a creature sheet:
A carnivore sheet changes the look and the stats, not the behaviour. This is not a bug.
The EGS command eventCreateNpcGroup asks the AI service of the player's area for a group:
eventCreateNpcGroup <player eid> <nbBots> <sheet> [<dispersionRadius=10>] [<spawnBots=true>] [<orientation=random|self|degrees>] [<name>] [<x>] [<y>] [<z>] [<client sheet>]
.creature. The EGS then warns SHEETID: The sheet '<code>' is not in sheet_id.bin, and retries with the extension: the warning is harmless.Stucked !): it stands, and players standing against it do not push it away or turn it. Several creatures with a radius of 0 each get their own spot on a small circle around the point, the first two side by side facing the given direction. A larger radius lets them wander within that radius; a creature turns toward where it walks, and a player pushing it only moves it aside.self takes the player's own heading, so the creature looks the same way the player does.x and y are in metres. In front of the player at a distance d: x + d·cos(Theta), y + d·sin(Theta).run_command { "dashboard": "Mainland", "process": "egs_mainland", "command": "eventCreateNpcGroup",
"args": ["(0x00000000d0:00:00:8e)", "1", "chdfb5", "0", "true", "2.1", "Vince the Ninja Yubo", "7767.48", "-4871.20"] }
To check it spawned, list the bots of each AI service until one has it:
run_command { "dashboard": "Mainland", "process": "ais_zorai", "command": "listBots" }
-> AIS_138:i2:m1:g0:b0 NPC bot 'Vince the Ninja Yubo'
leveldesign/translation/translated/creature_words_en.txt: the second column is the sheet code, the third the name (chdlb4 Sprightly Yubo).leveldesign/game_elem/creature/fauna/<ecosystem>/<code>.creature. Not every name of the translation file has a sheet in the core leveldesign.a1 the weakest. The weakest jungle creatures, for the Zorai newbie towns: chdja1 Suckling Yubo, chhja1 Suckling Mektoub, cbbja1 Fledgling Izam, cceja1 Weeny Ragus, ccjja1 Fledgling Javing, ckhja1 Weeny Kipee.3d data.Scale in the sheet is the size. The largest yubo is chdfb5 at 2.3; the common adults are 1.6 to 1.8._dag_lac.creature for the lake yubos): Lacustre/Low Quality/Young 0, Desert/Medium Quality/Normal 1, Jungle/High Quality/Old 2, PrimR 3, goo 4 (DFN/game_elem/_creature/_creature_texture_equipment.typ). The textures are in pipeline/install/fauna_maps (tr_, fy_, ju_, pr_mo_<skeleton>.dds); the prime roots one (PrimR) is the pale, nearly white one.An event group is built as NPC bots, and a bot with a creature sheet does not show the name it was created with: the AI service leaves the name to the creature sheet (ForceDisplayCreatureName) unless the bot has the Ring keyword FAUNA_BOT_USE_BOTNAME. The client then shows a name generated for the NPC. The AI script function rename sends the name to the IOS anyway. Run it for the group with script2, whose filter is the exact name of a bot of the group:
run_command { "dashboard": "Mainland", "process": "ais_zorai", "command": "script2",
"args": ["Vince the Ninja Yubo", "()rename(\"Vince the Ninja Yubo\");"] }
No bot correspond to name ... in the AI service log means the filter did not match a whole bot name, or the bot is on another AI service; do script on groups containing bot '...' means it ran.
An event creature never attacks first, whatever its sheet, a Ragus or a Kipee as much as a Yubo. It fights back when it is hit, nothing more. The AI service builds every event group as an NPC group (CAIInstance::eventCreateNpcGroup in ai_instance.cpp), not as a fauna group:
bandit, guard, faction, squad in ai_profile_npc.cpp), and an event group keeps the default normal activity, which looks for none.To have a group attack players, switch its activity to bandit with the AI script function setActivity, on the AI service that has it:
run_command { "dashboard": "Mainland", "process": "ais_zorai", "command": "script2",
"args": ["ring_cceja1_3", "()setActivity(\"bandit\");"] }
A bandit group attacks the players within its aggro range, DefaultBanditAggroRange of the AI service (15 m when the cfg does not set it). eventSetNpcGroupAggroRange does not make a group attack: it sends ()setAggro(range, 0);, the range that the faction activity reads. Give each group a bot name of its own when spawning, so that script2 reaches only that group: the filter is an exact bot name, and a name shared with bots of the primitives would change those too. Switch only the predators to keep the area natural; the herbivores can keep wandering. Like every event group, these groups are gone when their AI service restarts.
Primitives and translations can change on a running shard; see Changing Leveldesign on a Running Development Shard. In short: a loaded primitive file is unloadPrimitiveFile, loadPrimitiveFile, then spawnManagers <manager> on its AI service; a new file needs its AI services restarted; a new sheet needs the pipeline and a shard restart. New item and NPC sheets come from the generators of the leveldesign: Adding Item and NPC Sheets to the Core Leveldesign.
| Symptom | Cause |
|---|---|
'_configure.bat' is not recognized when an agent runs a root script |
NoDefaultCurrentDirectoryInExePath is set in the agent shell; clear it in the calling script. |
| A wait ends after 60 s | The argument is wait_seconds. |
Login answers 3003 |
The domain row names services the web cannot reach; for a development domain configured before setup version 14, run the setup upgrade. |
Login answers 3007 |
clientApplication is not the domain of the client (dev). |
| A spawned creature shows another name | Creature sheet on an NPC bot: rename it with the AI script. |
No bot correspond to name |
script2 takes the whole bot name, on the AI service that has the bot. |
| Spawned creatures never attack | Event groups are NPC groups with the normal activity: setActivity("bandit") on the group. |
cbEntityTeleportation(): cell=... should be zero or negative in the GPMS log, once per spawned bot |
Reported for every event bot; the bots spawn anyway. Not investigated. |