Autonomous agent testing

Use the agent testing toolkit to launch the local stack, connect a game client, run actions and inspect results from an external automation harness.

Two pieces, both versioned in the platform repository:

The MCP server is a plain PowerShell 7 script with no dependencies and no build step; it starts with the agent session and ends with it. Screenshots come back as real images in the conversation, so a multimodal agent sees what the player sees.

What this means for server owners#

Open77 development is validated in the running game, not only in unit tests. The loop has been proven end to end: stack launch, enrolment with the master, connection, pristine character load, crossing the "press any key to continue" screen, a server teleport confirmed by reading the player's position, and screenshots at every step — including two clients connected to the same server under two distinct accounts, each seeing the other's puppet and nameplate on screen.

The same toolkit applies to your own RP server and resources. open77_client_connect takes the server endpoint, open77_chat speaks through the real chat pipeline — the thing RP servers are built on — and open77_scenario turns a validation that passed once into a repeatable regression test with assertions and automatic failure screenshots. An agent asked to implement or validate a feature is expected to run this loop itself rather than ask a human to launch the game and report what they see.

The loop#

open77_status          # always first: what is already up, and how much VRAM is left
open77_build           # only after changing C++ — stops clients, builds, verifies deploy (~4 min)
open77_stack_up        # master (8090) + dev server (UDP 11778) + one client + debug bridge
open77_client_connect  # full human login path; returns only when the player is alive in-world
   … act and observe …
open77_down            # stop_game / stop_server to tear down

Changed only Lua? Skip open77_build: open77_resource_sync copies the resource and reloads it. Server-only resources are served live from the repository — nothing to copy.

For a complete script-based example, follow Test RTTI in game. It covers process selection, agent-play.ps1, direct bridge commands, queued results, multiplayer laboratory access, and hook/reference cleanup checks.

The tools#

The authoritative list is the $script:Tools table in scripts/agent-mcp.ps1, which also carries the full input schema of every tool.

Prefer commands over input: they are deterministic and do not need window focus.

How the connection works#

The path is exactly the one a human clicks; nothing is bypassed.

1. The connect step emits open77:shell:autoconnect <endpoint> <master-id> through the debug bridge.
2. The shell resource receives the event and refreshes the given master's catalogue, which enrols the identity with that authority — a certificate is issued by a single authority, so a client enrolled elsewhere is rejected by the local server.
3. The same startConnection the interface runs then executes: character bootstrap reset, Open77.network.connect, signed resource download, character resolution, pristine load, world handoff.
4. Progress is followed on two channels: net.state on the bridge (network phase, playerId, error) and the [shell-transition] log lines (bootstrap, pristine load, handoff).
5. The game then shows "press any key to continue" — sometimes tens of seconds after the handoff. The connect step presses Enter until proof of life: char.state reads alive=no health=0 while the screen holds and alive=yes health=100 once in-game.

Observing — data first, pictures second#

Raw state comes before the image. Position, health, network phase, and entities are read through the bridge; the screenshot only verifies what the player sees.

During an active session the bridge is deliberately restricted to read-only diagnostics and safety hatches. Acting in the world goes through server commands — forwarded automatically by open77_cmd for any unknown command name — under the server's ACL, the same authority path a player follows.

Repeatable scenarios#

open77_scenario turns a manual validation into a regression test the moment it passes:

{"steps": [
  {"name": "session is active", "tool": "open77_cmd",
   "args": {"command": "net.state"}, "assert": "phase=active"},
  {"name": "player is alive", "tool": "open77_cmd",
   "args": {"command": "char.state"}, "assert": "alive=yes"},
  {"name": "chat delivered", "tool": "open77_chat",
   "args": {"text": "regression check"}, "assert": "chat_sent"}
]}

Each step is an open77_* tool call; a failed assertion is reported with the actual output and a PNG of the screen at the moment of failure.

Several players at once#

open77_client_launch with identity_profile gives an instance its own account (player_name names a freshly created one); without it, every instance shares the same identity file, so the same account under the same name. Connect instances one at a time — crossing the continue screen goes through the keyboard, hence the foreground — and pass pid to every subsequent call. Two in-world clients is the practical ceiling on a 12 GB graphics card.

Rules paid for by real failures#

Run the checks below to distinguish a completed operation from an accepted command or a partially loaded world.

• World entry is proven by three things together: the log line worldReady matched pristine transition, a readable position, and char.state alive=yes. An "active" session is not an incarnation, and position already answers in the menu scene.
• Never send a server action (teleport, spawn, …) to a client whose char.state says alive=no. That is the "press any key to continue" gate: a tpc received there crashed the client outright, with CrashInfo.json pointing at the teleport destination. This is why the connect tool refuses to return before proof of life.
• A launched instance takes 60–150 seconds to appear. A process shows up after roughly a minute and its window some ten seconds later. Do not conclude failure early.
• VRAM is the real limit on concurrent clients — roughly 2.7 GiB at the menu and up to 4.2 GiB in-world per instance. Lowering graphics settings barely helps, because the streamer budgets against the card, not the settings. An instance without VRAM dies silently.
• A stray keypress can open a modal panel (the radio, for instance) that then eats all gameplay input. Screenshot to see it; esc or c closes it.
• Deploying a DLL requires every game stopped; Lua-only changes hot-reload.
• Explicit resource reload is refused during an active session — sync before connecting, or disconnect first.
• All instances share one save folder, and autosave starts on world entry. Keep a single client in-world when it matters, and back the folder up before a multi-client session.

Installation#

1. Declare the MCP server#

Declare the server in the .mcp.json your MCP client reads (a complete template ships as .mcp.json.example at the repository root):

{
  "mcpServers": {
    "open77": {
      "type": "stdio",
      "command": "pwsh",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass",
               "-File", "<path-to-repo>/scripts/agent-mcp.ps1"]
    }
  }
}

Under Claude Code, a project .mcp.json must be approved: add "open77" to enabledMcpjsonServers in .claude/settings.local.json.

Prerequisites: PowerShell 7 (pwsh), the OP77_GAME_DIR environment variable pointing at the game installation, and a deployed Open77 client (./scripts/build-all.sh).

2. Install the skill#

.claude/skills/open77-testing/SKILL.md is versioned: a clone of the repository has it already. Claude Code discovers project skills in .claude/skills/ at the session root. If the session is opened on the repository itself, nothing to do.

If the session is opened on a parent folder, make the folder visible from that root — a junction avoids maintaining two copies:

New-Item -ItemType Junction -Path '<session-root>\.claude\skills' `
         -Target '<path-to-repo>\.claude\skills'

To install machine-wide rather than per project, copy the open77-testing folder into ~/.claude/skills/.

Skills are loaded at session start: after installing, open a new session. Verify with /skills, or simply ask for a testing task — the agent should load it on its own.

3. Verify#

In a new session, on the repository:

open77_status

The reply reports the master (8090), the dev server (11778), free VRAM, and any running game instances. From there the whole loop is two calls: open77_stack_up, then open77_client_connect.

Extending the toolkit#

The MCP server is a versioned script: adding a tool means adding an entry to the $script:Tools table in scripts/agent-mcp.ps1 — a description, an inputSchema, a handler — and restarting the session. An agent blocked by a missing tool can therefore create it itself; that is deliberate. Any durable addition deserves a line in the skill and in the reference guide.

Where the details live#

See docs/agent-autonomous-testing.md for the automation reference and docs/agent-setup.md for installation. The MCP server wraps the standalone agent-play.ps1, capture-game.ps1, game-input.ps1 and launch-extra-client.ps1 scripts.