List every scene in the active project. Returns id, name, type, width/height (in tiles), backgroundId, and actor/trigger counts. Use this for orientation before reading a specific scene.

Return the full structured representation of one scene: metadata, actors[], triggers[], and scene-level scripts (script, playerHit1Script, playerHit2Script, playerHit3Script). Does NOT include backgrounds, palettes, or sprites — fetch those separately if needed.

List all actors in a scene with id, name, position, sprite sheet, and per-actor script presence flags (hasInteractScript / hasStartScript / hasUpdateScript / hasHit1Script / …). Use read_script to fetch event bodies.

Return the ScriptEvent[] for a given owner and key. Each event has shape { id, command, args?, children? } where children is a Record<branchName, ScriptEvent[]> for composite events (if/switch/group). See the gbvm-scripting skill for command semantics.

Apply an ordered list of structured operations (insert / replace / delete) to a ScriptEvent[] array. Full-array replacement is intentionally unsupported — use delete + insert. Operations apply sequentially: each op's index refers to the array state AFTER all prior ops in this call. Persists the edited scene/customEvent to disk atomically. Before writing, the resulting tree is checked against the dialogue width budget (default 18 chars/line for EVENT_TEXT/EVENT_MENU/EVENT_CHOICE strings); violations refuse the write unless force: true.

Ensure a variable is initialised to value at game start by inserting/updating a VARIABLE_SET_TO_VALUE event at the top of the START SCENE's onInit script (GB Studio 4.x has no default-value field on Variable). Value must fit signed 16-bit (-32768..32767). The variable must already exist — to add a new variable, call create_variable first. For in-game variable changes during play, use patch_script instead.

Invoke upstream gb-studio-cli (make:rom) to compile the project. Captures stdout+stderr to the configured compile log (read via read_compile_log). Returns { success, exitCode, romPath?, elapsedMs, stderrTail }. ALWAYS call this after structural edits before declaring work done. Requires GBS_CLI_PATH env var OR an installed GB Studio app in a standard location.

Launch the ROM via the bundled libmgba-linked gbs-mgba-runner with a scripted input timeline. Captures a PNG at the end (and optionally mid-run). Returns { success, screenshotPath, midScreenshotPath?, exitCode, elapsedMs, stderrTail }. Retrieve the image via the screenshot tool. Build the runner once with mcp-server/native/build.sh (needs a local mGBA checkout); or set GBS_MGBA_RUNNER to an absolute path.

Return an emulator screenshot as an image content block (base64 PNG). Call AFTER run_emulator. Defaults to the latest.png from run_emulator's final frame; pass filename to read a different file in the screenshot dir.

Read the full stdout+stderr captured from the last build_rom invocation. Use this INSTEAD of guessing when a build fails. Optionally returns only the last N lines via tailLines.

Create a new scene folder + scene.gbsres under project/scenes/. Name is slugified for the on-disk folder; collisions get _2/_3 suffixes. Scene type must be uppercase (TOPDOWN, PLATFORM, ADVENTURE, POINTNCLICK, SHMUP, LOGO) — changing type later resets engine configuration, so pick deliberately. Size defaults to 20×18 tiles (one screen); scenes >20×18 scroll. Does not create a background — pass backgroundId of an existing background, or set it empty and add one later.

Append a new actor file under project/scenes//actors/. Enforces GB Studio hardware caps: up to MAX_ACTORS=20 per normal scene, MAX_ACTORS_SMALL=10 when scene width*height <= 160 tiles. Coordinates default to tiles. Pass spriteSheetId of an existing sprite, or leave empty (actor will not render until set).

Append a new trigger file under project/scenes//triggers/. Triggers are rectangular zones that fire script on player enter and leaveScript on exit. Enforces MAX_TRIGGERS=30 per scene. Coordinates and size are in tiles.

Append a new Variable entry to project/variables.gbsres. Id is auto-assigned as the next numeric string. Symbol is auto-derived from name (camelCase → snake_case, e.g. 'curQ' → 'cur_q'). GB Studio variables are 16-bit signed (-32768..32767); set initial value via set_variable.

Create a new script resource file under project/scripts/. Custom events are reusable scripts that can be called from scenes/actors/triggers. The script body starts empty — use patch_script with an ownerType: 'customEvent' locator to populate it.

Patch startSceneId in project/settings.gbsres so the game boots into the given scene. Preserves every other setting field. The sceneId must resolve to an existing scene on disk, or build_rom will fail.

Recursively delete a scene folder (scene.gbsres + actors/ + triggers/). Refuses if the scene is the start scene, or if any other script references this sceneId (e.g. EVENT_SWITCH_SCENE) — pass force: true to override the reference check (the start-scene guard is unconditional). Use list_scenes to find target ids. There is no undo; commit your work first.

Delete one actor file from a scene's actors/ directory. Refuses if any script references this actorId (including via property paths like <actorId>:x_pos); pass force: true to override. The actor's own scripts are not counted as external references — they are deleted with the file.

Delete one trigger file from a scene's triggers/ directory. Triggers are rarely referenced by other scripts (they only run on enter/leave), but the cross-reference check still runs for safety. Pass force: true to override. The trigger's own onEnter / onLeave scripts go away with the file.

Delete one custom-event (script resource) file under project/scripts/. Refuses if any script references this customEventId (typically via EVENT_CALL_CUSTOM_EVENT). Pass force: true to override. The custom event's own body is deleted with the file.

Remove a Variable entry from project/variables.gbsres. Refuses if any script references the variable (e.g. VARIABLE_SET_TO_VALUE / IF_VARIABLE_VALUE; ScriptValue {type:"variable", value:<id>}). Pass force: true to override — but expect compile errors on the next build_rom unless every reference is repaired.

Generate a GB Studio sprite from a text prompt. Calls the configured image-generation provider (SPRITE_PROVIDER env var ∈ {openai, gemini, replicate, fal}; default openai), runs the result through a 4-colour DMG quantiser, and writes (sprite.png + sprite.png.gbsres) under assets/sprites/. Returns a spriteSheetId you can pass to create_actor immediately. Frames are 16×16; for multi the provider is called 3× (one per direction), for multi_movement 6× (idle + walk per direction). After quantisation a heuristic quality check runs; degenerate outputs refuse to save unless force: true.

Read a local PNG/JPG and convert it to a 4-colour DMG-quantised GB Studio sprite. For animationType=fixed the image is treated as one frame. For animationType=multi/multi_movement the input MUST already be a sprite sheet (3 frames wide for multi, 6 frames wide for multi_movement) — single-frame inputs cannot be expanded to multiple directions. After quantisation a heuristic quality check runs: degenerate outputs (near-empty, single-shade, low-detail) refuse to write unless force: true. No API key required.