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 codeengine_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
Callsummer_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.,
./Worldor./for root) - Avoid duplicate names
- Understand what already exists
2. One Script for Three or More Edits
For one or two edits, usesummer_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. Usesummer_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”). Onesummer_run_script with scenePath="res://main.tscn" adds all three:
Player with Physics
For a CharacterBody3D player, write the movement script first withsummer_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:- Add
ControlorCanvasLayeras root for UI - Add
MarginContainer,VBoxContainer, orHBoxContainerfor layout - Add
Button,Label, etc. as children - Use
summer_connect_signalto wirepressedto handler methods
Importing Assets
Single Asset
summer_import_from_url(url="https://example.com/tree.glb"). Path is auto-inferred from filename.- Or specify path:
summer_import_from_url(url="...", path="res://assets/tree.glb") - After import, add to scene:
summer_instantiate_scene(scenePath="res://main.tscn", parent="./World", scene="res://assets/tree.glb", name="Tree1")
Multiple Assets
Usesummer_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
- First:
summer_get_diagnostics. Tells you if there are console errors, debugger errors, or warnings. - If console issues:
summer_get_consolewith optionalfilterortype - If runtime issues:
summer_get_debugger_errors(game must have been run)
Run and Inspect
When you do need it running:summer_play. Start the game.summer_is_running. Confirm the game is up.summer_screenshot(target="game"). Capture what the player sees.summer_get_diagnostics. Check for runtime errors.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.Input and Project Settings
Input Actions
summer_input_map_bind creates an action and binds events:
Main Scene
summer_project_setting(key="application/run/main_scene", value="res://main.tscn")
Common Pitfalls
- Wrong path format: Use
./World/Player, notWorld/Playeror/World/Player - Game running during edits: Stop the game with
summer_stopbefore scene changes - Vector/Color as JSON: Use
"Vector3(0, 10, 0)"not{x:0, y:10, z:0} - Missing target: Pass the exact
scenePathon every scene mutation.summer_open_scenedoes not establish it. - Broken scene dependency: If a target cannot load, inspect and repair the exact missing or invalid file named by the receipt, then retry.
- Instantiate vs mesh: Use
summer_instantiate_scenefor .tscn/.glb files; usesummer_set_propwithmeshfor built-in meshes (BoxMesh, SphereMesh, etc.) - Chains of single edits: For 3 or more edits to one scene, run one
summer_run_scriptwithscenePath
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.

