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. Prerequisites: Summer Engine must be running with a project open. If you get “Summer Engine is not running,” tell the user to start the engine or run npx summer-engine run from the project directory.

​
Skills (Best-Practice Guides)

Before building, install the relevant skill. Skills are bundled with the CLI and contain patterns for scene structure, GDScript, and MCP tool usage. Install them, then read the SKILL.md file and follow its patterns. When to install which skill: For Claude Code: Add --as-claude-skill to install into ~/.claude/skills/. For Cursor: Add --as-cursor-skill to install into the current project’s .cursor/rules/, as summer-<name>.mdc. Cursor gets a rule file, not a SKILL.md, and it is project-scoped rather than written to your home directory. Example: npx summer-engine skills install fps-controller --as-claude-skill After installing: Read the skill file at ~/.summer/skills/<name>/SKILL.md (with --as-claude-skill, ~/.claude/skills/<name>/SKILL.md; with --as-cursor-skill, .cursor/rules/summer-<name>.mdc in the project). Follow the patterns when building.

​
Core Workflow

​
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. Add Nodes, Then Configure

The pattern is: add, then set properties.
  1. Inspect: summer_get_scene_tree(scenePath="res://main.tscn")
  2. Add: summer_add_node(scenePath="res://main.tscn", parent="./", type="MeshInstance3D", name="Player")
  3. Configure: summer_set_prop(scenePath="res://main.tscn", path="./Player", key="position", value="Vector3(0, 1, 0)")
  4. Mesh: summer_set_prop(scenePath="res://main.tscn", path="./Player", key="mesh", value="BoxMesh")
For nested resource properties (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:
  1. Root: Usually a Node3D named “World” (may already exist)
  2. Camera: summer_add_node(scenePath="res://main.tscn", parent="./World", type="Camera3D", name="MainCamera")
  3. Light: summer_add_node(scenePath="res://main.tscn", parent="./World", type="DirectionalLight3D", name="Sun"). Set shadow_enabled: true, light_energy: 1.0
  4. Floor: summer_add_node(scenePath="res://main.tscn", parent="./World", type="MeshInstance3D", name="Floor"). Set mesh: "BoxMesh", use summer_set_resource_property with the same scenePath for BoxMesh size (e.g., Vector3(20, 0.2, 20))

​
Player with Physics

For a CharacterBody3D player:
  1. Add CharacterBody3D named “Player”
  2. Add child CollisionShape3D under Player
  3. Set the shape: summer_set_prop(scenePath="res://main.tscn", path="./Player/CollisionShape3D", key="shape", value="CapsuleShape3D")
  4. Set capsule size: summer_set_resource_property(scenePath="res://main.tscn", nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="radius", value="0.5") and height similarly
  5. Attach a script (user may need to edit in external editor) or use summer_connect_signal for input

​
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

summer_play opens a real window on the user’s screen and takes focus. If you are an agent working while someone else is using their machine, this interrupts them.Prefer the checks that need no window:
  • 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. Wait a moment for the game to load.
  3. summer_screenshot. Capture what the player sees (base64 image).
  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, RunVerification 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. InstantiateScene vs SetProp mesh: Use InstantiateScene for .tscn/.glb files; use SetProp with mesh for built-in meshes (BoxMesh, SphereMesh, etc.)

​
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

Tools Reference

Full parameter reference for the current MCP tool set

MCP Setup

Connect your IDE to Summer Engine
Need help or have questions? Reach out to our founders at founders@summerengine.com or join our community on Discord for fast responses.