Skip to main content

For AI Agents

This page is a playbook for building games with Summer Engine’s MCP tools. Follow it when the user asks you to create or modify a game. The tools execute operations in the engine: scenes, nodes, properties, imports, and debugging. So you can build real games from natural language requests. Summer Engine is the game engine built for AI. Prerequisites: Summer Engine must be running with a project open. If the engine is not running, a tool answers with the error code engine_not_running and one next step: open the project in Summer Engine (or run npx summer-engine run <project-path>), then retry the same call.

Skills (Best-Practice Guides)

Skills contain patterns for scene structure, GDScript, and tool usage. npx -y summer-engine@latest setup <agent> --yes installs the whole library where your agent reads skills. To add one: npx -y summer-engine@latest skills install <name> --agent <agent>. Read a skill at ~/.agents/skills/<name>/SKILL.md (Cursor, Codex and most agents) or ~/.claude/skills/<name>/SKILL.md (Claude Code), and follow its patterns.

Core Workflow

0. Look It Up First

For a new task, plan first: summer_call with {"op": "docs.plan", "input": {"goal": "<the user's goal>"}} returns the skills, tools and checks to use. For a vague “make a game”, use the brainstorm-game skill: it writes .summer/GameSoul.md, which the other skills read. Search Summer’s docs and skills before you build: summer_docs_search, then summer_docs_read on the best hit. For work outside the engine (assets, plans, the store, prices, analytics), call summer_search with the job in plain words, then summer_call with the op and input it returns. Long work, such as a 3D model, answers with a job: call summer_jobs_wait until it is done. See How Summer answers.

1. Identify the Exact Scene

Call summer_get_project_context, choose the exact res:// scene path, then pass it to summer_get_scene_tree. You’ll get node paths, types, and hierarchy. Use this to:
  • Find the correct parent path for new nodes (e.g., ./World or ./ for root)
  • Avoid duplicate names
  • Understand what already exists
Opening a scene only changes the visible editor tab. It does not select the mutation target.

2. One Script for Three or More Edits

For one or two edits, use summer_add_node or summer_set_prop with scenePath: summer_set_prop(scenePath="res://main.tscn", path="./Player", key="position", value="Vector3(0, 1, 0)") For 3 or more edits to one scene, write one GDScript and run it once with summer_run_script and scenePath. One script replaces a long chain of single edits, and it can compute placement (loops, grids, scatter). Call ctx.set_owner_recursive(node) on every node you create, or it is not saved. Then check the result with summer_snapshot_diff and summer_screenshot(target="scene"). For one nested resource property (e.g., collision shape size, material color), use summer_set_resource_property.

3. Use Engine Value Formats

Properties use engine string syntax, not JSON objects:

4. Trust the Receipt

Dedicated scene mutation tools append one final save automatically. Treat the returned engine receipt as the result: if it succeeded, the exact target was persisted; if it failed, read the named reason, repair or reread the affected state, and retry. Use summer_save_scene(scenePath="res://main.tscn") only for a standalone save or save-as.

Scene Setup Patterns

Basic 3D Scene

A minimal playable 3D scene needs a camera, a light and a floor under the root (usually a Node3D named “World”). One summer_run_script with scenePath="res://main.tscn" adds all three:

Player with Physics

For a CharacterBody3D player, write the movement script first with summer_write_file (for example res://player.gd). Then one summer_run_script with scenePath builds the player and attaches it:

UI Layout

For menus and HUD:
  1. Add Control or CanvasLayer as root for UI
  2. Add MarginContainer, VBoxContainer, or HBoxContainer for layout
  3. Add Button, Label, etc. as children
  4. Use summer_connect_signal to wire pressed to handler methods

Importing Assets

Single Asset

  1. summer_import_from_url(url="https://example.com/tree.glb"). Path is auto-inferred from filename.
  2. Or specify path: summer_import_from_url(url="...", path="res://assets/tree.glb")
  3. After import, add to scene: summer_instantiate_scene(scenePath="res://main.tscn", parent="./World", scene="res://assets/tree.glb", name="Tree1")

Multiple Assets

Use summer_import_from_url_batch with an array of {url, path}. One scan after all downloads. Faster than importing one by one.

Debugging Workflow

Check for Errors

  1. First: summer_get_diagnostics. Tells you if there are console errors, debugger errors, or warnings.
  2. If console issues: summer_get_console with optional filter or type
  3. If runtime issues: summer_get_debugger_errors (game must have been run)

Run and Inspect

Running the game costs time. summer_play plays quietly by default: the game runs embedded in the editor, and the editor keeps its tab and focus, so the user keeps working. Pass focus: true only when the user is watching and asked to see it. For a parallel run nobody sees, pass mode: "offscreen" with a named instance.Prefer the checks that need no running game:
  • summer_screenshot with target="scene" renders a scene offscreen without touching the visible tab or starting the game. Use this for “does it look right”.
  • summer_get_diagnostics answers “is anything broken” without running anything.
Reach for summer_play when you genuinely need the game running (real physics, real input, real runtime state), not as a default way of looking at your work.
When you do need it running:
  1. summer_play. Start the game.
  2. summer_is_running. Confirm the game is up.
  3. summer_screenshot(target="game"). Capture what the player sees.
  4. summer_get_diagnostics. Check for runtime errors.
  5. summer_stop. Stop before making scene changes.
One screenshot proves less than you think. A still frame shows that something rendered, not that the game works. Booting the game after every change is expensive and mostly tells you nothing new. A check that catches the failure you were actually worried about is worth more than a screenshot taken out of habit.For behaviour rather than appearance, a RunVerification op through summer_batch runs a GDScript probe against the live game and can assert over time (node state, counts, group membership, property values) rather than leaving you to squint at a frame.
Stop before editing. Some scene operations require the game to be stopped. Call summer_stop before adding/removing nodes or changing properties.

Input and Project Settings

Input Actions

summer_input_map_bind creates an action and binds events:
For WASD movement:

Main Scene

summer_project_setting(key="application/run/main_scene", value="res://main.tscn")

Common Pitfalls

  1. Wrong path format: Use ./World/Player, not World/Player or /World/Player
  2. Game running during edits: Stop the game with summer_stop before scene changes
  3. Vector/Color as JSON: Use "Vector3(0, 10, 0)" not {x:0, y:10, z:0}
  4. Missing target: Pass the exact scenePath on every scene mutation. summer_open_scene does not establish it.
  5. Broken scene dependency: If a target cannot load, inspect and repair the exact missing or invalid file named by the receipt, then retry.
  6. Instantiate vs mesh: Use summer_instantiate_scene for .tscn/.glb files; use summer_set_prop with mesh for built-in meshes (BoxMesh, SphereMesh, etc.)
  7. Chains of single edits: For 3 or more edits to one scene, run one summer_run_script with scenePath

Concurrent Agents

Multiple agents can work at the same time because every mutation names its exact project and scene. There is no routine whole-project writer lock. When two edits touch the same file, file writes use content receipts. A stale overwrite is refused instead of silently replacing newer work. The agent should reread the file, review the new content, and retry only if its edit still applies.

Tool Selection Quick Reference


Next Steps

Operations reference

Full parameter reference for the current MCP tool set

MCP Setup

Connect your IDE to Summer Engine

Need help? Ask in Discord first. That is where you get the fastest reply and support. For concrete help, email support@summerengine.com or founders@summerengine.com.