zandronum-mcp

Send a raw console command to a running, bridge-patched Zandronum instance and return its captured output.

Run `dumpactors` and return the registered DECORATE/actor classes as structured data.

Spawn an actor of the given class at the player's position.

Give an inventory item to the player.

Remove an inventory item from the player.

Load a map by its lump name (e.g. MAP01, E1M1).

Run `scriptstat` and return the currently running ACS scripts and their states.

Run (puke) an ACS script by number or name, with optional integer arguments.

Take a screenshot of the game and return it as an image so it can be viewed.

Send a single menu navigation key (GUI key event) to the active menu.

Send a sequence of menu keys (e.g. ["down","down","enter"]) with a small delay between each.

Type a string into the active menu text-entry field (e.g. the player name box after pressing enter on it), one character at a time.

Move the pointer to a screen position, in pixels from the top-left of the game window. Drives hover-only UI -- tooltips, hot states -- which nothing else here can reach.

Press and release the left button at a position. Give toX/toY to DRAG: press at the first point, move through it, release at the second. `double` sends a double-click.

Wheel notches at the current pointer position. Positive scrolls up, negative down.

Open a menu (via a console command like `menu_options`), apply navigation steps, then return a screenshot to verify it.

Set the engine's master pause flag directly. Use this to resume a backgrounded instance that auto-paused on focus loss, so the simulation keeps advancing while the MCP drives it.

Resume the game, let it run for the given number of tics (35 tics = 1 second), then pause again. Lets you advance the simulation a deterministic-ish amount to observe time-based effects (charging, projectiles, animations) without keeping the window focused.

Read an ACS world or global variable by index.

Write an ACS world or global variable by index.

Run `dumpacsvars` and return all non-zero ACS world/global variables, optionally filtered by scope.

Parse a directory of .acs source files and return symbol counts (scripts, functions, numeric defines). Reads files directly; no game needed.

Resolve a script number or a script/function name to its symbol(s) — name, number, file:line. Turns a profiler 'script 1017' into a source location.

Read function and named-script names from a mod's compiled ACS (BEHAVIOR/library lumps) in a WAD or PK3 — for source-less mods. Numbered scripts have no names in bytecode (use find_acs_symbol with source for those).

List .zds savegames in the save directory with metadata (title, map, engine, game wad, creation time) read from each save's PNG text chunks. No running game needed.

Run `save` to write a savegame (single-player / cooperative only). NOTE: saving heavily-scripted mods can crash the engine — All-out-War crashes on save; vanilla and simple maps save fine.

Run `load` to restore a savegame by name.

Run `playdemo` to play back a recorded .lmp demo. (Recording is via the -record launch arg, not a console command.)

Run `currentpos` and return the player's position, angle, floor height, sector, and light level.

Run `dumpactor` and return an actor's live state: class, health, position, current DECORATE state (sprite/frame/tics, e.g. TNT1 A 0), inventory, and (for players) ready weapon + morph status. Defaults to the player; pass a TID for any actor.

Run `dumphud` and return everything the engine painted last frame: HUD text strings (with screen x/y), images (by texture name + position), and active ACS HUD messages (full composed text, layer, position, remaining tics). Captures menus too.

Run `actorsnear` and return actors within a radius (map units, default 512) of the player: class, health, position, and current sprite.

Run `linetarget` and return the actor the player is aiming at (class, health, spawn health).

Run `dumpscripts` and return every script across loaded modules (module, number, name, type, arg count).

Run `dumpfunctions` and return named ACS functions across loaded modules.

Run `acsprofile` and return per-script/function execution stats (total instructions, runs, avg/min/max).

Clear ACS profiling, wait N seconds, then return what ran during that window — `what's hot right now` rather than cumulative since map start.

Run `dumpmodules` and return the loaded ACS modules (id + name). Map vars live only while a map is loaded.

Read a map-scope ACS variable by name (searched across loaded modules).

Write a map-scope ACS variable by name.

Read one element of a map-scope ACS array by name and index.

Write one element of a map-scope ACS array by name and index.

Active backend (software/opengl), GL vendor/shader model, resolution, fullscreen/vsync.

The 3D view window rect (x/y/width/height) and screenblocks size.

Status bar Y position, status bar / HUD scale, alt HUD, crosshair.

Read a map from a WAD and return its format (doom/hexen/udmf) and entity counts. Reads the file directly — the game need not be running.

Return one sector's properties by index (all fields, format-native keys).

Return one linedef by index, with its referenced sidedefs (textures + offsets) resolved.

Return all sectors whose tag/id matches (binary `tag` or UDMF `id`).

Spawn a bridge-enabled Zandronum process with the given options and attach to it. Requires ZANDRONUM_EXE to be set.

Connect to a bridge-patched Zandronum that is ALREADY running — one you launched by hand, or from a terminal — and bind it to an instance number for the other tools. Only needed for engines this session didn't launch: launch_instance binds automatically. Defaults to this instance's conventional port.

Stop a launched instance and detach from it. Asks the engine to quit itself first (a hard kill mid-render can wedge macOS GPU teardown and leave an unkillable process), then force-kills if it doesn't exit.

Kill every instance this session launched, and reap engines ORPHANED by earlier sessions (whose launcher is gone) that could otherwise squat bridge ports. Engines belonging to another running editor window are left alone. Pass all:true to also kill those — only do that if you know no other session is using this engine build.

Read the engine's captured console log for an instance and surface DECORATE/ACS compile errors and fatal startup errors. Works even when the bridge never came up (e.g. the engine aborted on a bad script) — exactly when the other tools can't connect.

Return the signal, faulting address, and symbolized backtrace the bridge's crash handler captured the last time the engine crashed (segfault/abort/bus error/etc.). Use this when an instance dies unexpectedly — e.g. run_command reports the bridge closed. Empty if the instance has not crashed.