> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools Reference
> All 52 Summer Engine MCP tools: scene editing, debugging, project context, asset library search, AI generation, and Summer Cloud project sync.
## Overview
The Summer Engine MCP server exposes 52 tools across six categories: **Scene** (14), **Debug and Play** (10), **Project** (9), **Asset Library** (6), **Generation** (6), and **Summer Cloud** (7).
Scene, Debug, and Project tools talk to the running engine on `localhost:6550` and require Summer Engine to be open with a project loaded. If the engine is not running, those tools return a clear error and a `summer run` hint. Asset Library, Generation, and Summer Cloud tools call the Summer Engine cloud and require you to be signed in (run `npx summer-engine login` once); the import side of asset tools needs the engine running too. Summer Cloud tools work on the project directory directly and do not need a running engine.
**Critical: value formats.** Properties like `position`, `rotation_degrees`, and `mesh` use engine string syntax, not raw JSON objects. See [Value Formats](#value-formats) below.
***
## Value Formats
When setting properties via `summer_set_prop` or `summer_set_resource_property`, use these formats:
| Type | Format | Example |
| ----------- | ------------------------------------- | --------------------------------------------------- |
| Vector3 | `"Vector3(x, y, z)"` | `"Vector3(0, 10, 0)"` |
| Vector2 | `"Vector2(x, y)"` | `"Vector2(100, 200)"` |
| Color | `"Color(r, g, b, a)"` RGBA 0.0 to 1.0 | `"Color(1, 0.5, 0, 1)"` |
| Transform3D | `"Transform3D(...)"` basis + origin | `"Transform3D(1,0,0, 0,1,0, 0,0,1, 0,5,0)"` |
| Resource | Class name, auto-instantiated | `"BoxMesh"`, `"SphereMesh"`, `"StandardMaterial3D"` |
| Number | Native JSON | `1.5`, `42` |
| Boolean | Native JSON | `true`, `false` |
| String | Native JSON | `"hello"` |
**Wrong:** `"position": {x: 0, y: 10, z: 0}` stays a Dictionary and fails.
**Right:** `"position": "Vector3(0, 10, 0)"` parses to a Vector3.
Node paths use a `./` prefix for relative paths from the scene root. For example, `./World/Player` means the `Player` child of the `World` node.
***
## Scene Tools (14)
### summer\_create\_scene
Create a new empty scene file. To prevent accidental destructive edits you must explicitly pass `allow_temporary_scene_mutation=true`; the tool opens a template scene, removes its children, saves to the new path, then restores the previous scene.
| Parameter | Type | Required | Description |
| -------------------------------- | ------- | -------- | -------------------------------------------------------- |
| `path` | string | Yes | New scene path, e.g. `res://scenes/empty_level.tscn` |
| `rootName` | string | No | Root node name for the new scene (default `Main`) |
| `allow_temporary_scene_mutation` | boolean | No | Safety gate. Must be `true` to proceed (default `false`) |
***
### summer\_add\_node
Add a new node to the scene tree.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------------- |
| `parent` | string | Yes | Parent path, e.g. `./World` or `./World/Enemies` |
| `type` | string | Yes | Node type, e.g. `MeshInstance3D`, `CharacterBody3D` |
| `name` | string | Yes | Name for the new node |
**Common node types:** Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D, Camera3D, DirectionalLight3D, OmniLight3D, SpotLight3D, WorldEnvironment, CollisionShape3D, Area3D, Node2D, Sprite2D, CharacterBody2D, Camera2D, TileMapLayer, Control, Label, Button, VBoxContainer, HBoxContainer, AudioStreamPlayer, AudioStreamPlayer3D.
**Example:** `summer_add_node(parent="./", type="DirectionalLight3D", name="Sun")`
***
### summer\_set\_prop
Set a property on a node. The primary way to configure nodes after adding them.
| Parameter | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------------------------------------- |
| `path` | string | Yes | Node path, e.g. `./World/Player` |
| `key` | string | Yes | Property name, e.g. `position`, `mesh`, `visible` |
| `value` | string \| number \| boolean | Yes | Value in engine string format for complex types |
**Common properties:** `position`, `rotation_degrees`, `scale`, `visible`, `mesh`, `shadow_enabled`, `light_energy`, `fov`.
**Example:** `summer_set_prop(path="./World/Player", key="position", value="Vector3(0, 1, 0)")`
***
### summer\_set\_resource\_property
Set a nested property on a resource attached to a node (e.g., a CollisionShape3D shape size or a material color).
| Parameter | Type | Required | Description |
| ------------------ | --------------------------- | -------- | -------------------------------------------------------------------- |
| `nodePath` | string | Yes | Node path |
| `resourceProperty` | string | Yes | Resource property on node, e.g. `shape`, `mesh`, `material_override` |
| `subProperty` | string | Yes | Property on the resource, e.g. `size`, `radius`, `albedo_color` |
| `value` | string \| number \| boolean | Yes | Value in engine string format |
**Example:** `summer_set_resource_property(nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="size", value="Vector3(1, 2, 1)")`
***
### summer\_remove\_node
Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive: do not delete multiple top-level nodes unless the user explicitly asks for destructive changes.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| `path` | string | Yes | Node path to remove |
***
### summer\_replace\_node
Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for swapping a StaticBody3D for a RigidBody3D, or a placeholder for a proper prefab.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------- |
| `path` | string | Yes | Node path to replace |
| `type` | string | No | New node type, e.g. `RigidBody3D` |
| `scene` | string | No | Scene to replace with, e.g. `res://enemies/boss.tscn` |
***
### summer\_save\_scene
Save the current scene to disk. Call after making changes to persist them. Without saving, changes only exist in the editor's memory.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------ |
| `path` | string | No | Save-as path for a new scene file, e.g. `res://levels/level2.tscn` |
***
### summer\_open\_scene
Open a scene file in the editor. Use to switch between scenes. Prefer `summer_get_project_context` and `summer_open_main_scene` over guessing paths.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------- |
| `path` | string | Yes | Scene path, e.g. `res://main.tscn` |
***
### summer\_instantiate\_scene
Add an existing scene or 3D model as a child node. Use for `.tscn` prefabs or `.glb`/`.gltf` models. The scene must already exist in the project; import external sources first with `summer_import_from_url`.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------------------------------- |
| `parent` | string | Yes | Parent node path |
| `scene` | string | Yes | Scene/model path, e.g. `res://player.tscn` or `res://models/tree.glb` |
| `name` | string | No | Override the instance name |
***
### summer\_connect\_signal
Connect a signal between two nodes. The receiver must have a script with the specified method.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| `emitter` | string | Yes | Node that fires the signal |
| `signal` | string | Yes | Signal name, e.g. `body_entered`, `pressed`, `timeout` |
| `receiver` | string | Yes | Node with the handler script |
| `method` | string | Yes | Method name in the receiver's script |
**Common signals:** `body_entered`, `body_exited`, `pressed`, `timeout`, `area_entered`, `input_event`.
***
### summer\_select\_node
Select a node in the editor's scene tree and show it in the inspector panel.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------- |
| `nodePath` | string | Yes | Node path to select |
| `scenePath` | string | No | Open this scene first, then select the node |
***
### summer\_inspect\_node
Get all editable properties of a node with their current values, types, and resource info. Returns every property the inspector would show. Call this before modifying a node to understand its current state.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------ |
| `path` | string | Yes | Node path from the scene tree, e.g. `Player`, `World/Enemies/Boss` |
***
### summer\_inspect\_resource
Get all properties of a resource (material, mesh, shape, environment, etc). Use when you need the sub-properties of a resource attached to a node.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `path` | string | Yes | Resource path, e.g. `res://materials/ground.tres` or `res://models/player.glb` |
***
### summer\_batch
Execute multiple operations in a single call, grouped into one undo step. The user can undo everything with a single Ctrl+Z. Use when building something that involves multiple nodes and properties at once.
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | -------------------------------------------------------------- |
| `ops` | array | Yes | Array of operation objects, each with `op` plus its parameters |
Each op uses the same shape as the individual tools:
```json theme={null}
[
{ "op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor" },
{ "op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh" },
{ "op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)" }
]
```
***
## Debug and Play Tools (10)
### summer\_get\_diagnostics
Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message. **Call this first** before diving into the console or debugger details.
| Parameters | None |
| ---------- | ---- |
**Workflow:** call `summer_get_diagnostics`; if there are errors, read `summer_get_console`, `summer_get_debugger_errors`, or `summer_get_debugger_warnings`; fix; then call `summer_get_diagnostics` again to verify.
***
### summer\_get\_console
Read recent messages from the editor's Output panel. Output is deduped for token economy: consecutive identical messages collapse into one entry with a `(xN)` count, and the response carries a `_filter` summary of what was hidden.
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `max_lines` | number | No | Max lines to return after dedupe (default 100) |
| `filter` | string | No | Only return lines containing this string |
| `type` | enum | No | Filter by message type: `error`, `warning`, `std`, `editor` |
| `errors_only` | boolean | No | Drop info/std noise, keep errors and warnings (default `true`) |
| `strict_errors` | boolean | No | Drop warnings too, return errors only (default `false`) |
| `raw` | boolean | No | Bypass dedupe and level filtering, return engine output verbatim (default `false`) |
***
### summer\_clear\_console
Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.
| Parameters | None |
| ---------- | ---- |
***
### summer\_get\_debugger\_errors
Read runtime errors from the debugger (null references, missing nodes, physics errors). These occur while the game is running and are distinct from console output. Deduped: identical errors firing every frame collapse into one entry with a `(xN)` count.
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | -------------------------------------------------------------- |
| `max_errors` | number | No | Max errors to return after dedupe (default 50) |
| `include_stack` | boolean | No | Include stack traces for each error |
| `raw` | boolean | No | Bypass dedupe, return engine output verbatim (default `false`) |
For warning text, use `summer_get_debugger_warnings`.
***
### summer\_get\_debugger\_warnings
Read runtime warnings from the debugger: missing optional resources, dead signal connections, deprecated API use, large allocations, physics warnings. Same structured shape as `summer_get_debugger_errors`, filtered to severity `warning`. Use this when `summer_get_diagnostics` shows a non-zero `debugger.warnings` count.
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | ------------------------------------------------ |
| `max_warnings` | number | No | Max warnings to return after dedupe (default 50) |
| `include_stack` | boolean | No | Include stack traces (default `true`) |
| `raw` | boolean | No | Bypass dedupe (default `false`) |
***
### summer\_get\_script\_errors
Check a GDScript file for parse/compile errors without running the game. Returns line numbers, error messages, and severity. Much faster than running the game to discover script errors. Use after writing or editing a `.gd` file.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------- |
| `path` | string | Yes | Script path, e.g. `res://scripts/player.gd` |
***
### summer\_play
Start running the game in the engine. The game runs inside Summer Engine's viewport. After starting, use `summer_get_diagnostics` to check for runtime errors. You can run a specific scene instead of the main scene.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| `scene` | string | No | Scene to run instead of the main scene, e.g. `res://levels/test_level.tscn` |
***
### summer\_stop
Stop the running game. Call before making scene changes; some operations require the game to be stopped.
| Parameters | None |
| ---------- | ---- |
***
### summer\_is\_running
Check if the game is currently running. Returns the active scene path if running.
| Parameters | None |
| ---------- | ---- |
***
### summer\_screenshot
Capture a frame from the running Summer Engine and return it as an image the MCP client can see directly. Use to visually verify scene layout, asset placement, and gameplay state. Captures the editor viewport by default, or the running game with `target="game"`.
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ---------------------------------------------------------------------- |
| `target` | enum | No | What to capture: `viewport` (editor, default) or `game` (running game) |
***
## Project Tools (9)
### summer\_start\_game\_task
The router to call at the start of any substantial AI game-building task. Takes the user's goal and returns the recommended Summer workflow: skill routes, MCP tool groups, host-file boundaries, asset policy, user confirmation gates, and verification steps.
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `goal` | string | Yes | The user's game-building goal or task |
| `mode` | enum | No | Task mode override (default `auto`) |
| `target` | enum | No | Content/system target override (default `auto`) |
| `assetPolicy` | enum | No | How aggressively to use paid generation (default `ask-before-paid-generation`) |
| `verification` | enum | No | How much engine verification to plan for (default `full`) |
***
### summer\_get\_agent\_playbook
The AI-first operating guide for Summer Engine MCP. Call at the start of a fresh chat before touching scenes. Returns the safe workflow, anti-patterns, and recovery steps.
| Parameters | None |
| ---------- | ---- |
***
### summer\_get\_project\_context
Get essential project context before editing: engine health, project name and path, current scene path, main scene path from project settings, and a lightweight `.summer` project memory summary. Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.
| Parameters | None |
| ---------- | ---- |
***
### summer\_open\_main\_scene
Open the project's configured main scene from project settings. Safer than guessing scene names like `main.tscn` or `Main.tscn`. Call this when you get "no scene open".
| Parameters | None |
| ---------- | ---- |
***
### summer\_get\_scene\_tree
Get the full scene tree of the currently open scene. Use before structural edits (add/remove/replace). If you get "no edited scene", call `summer_open_main_scene` first.
| Parameters | None |
| ---------- | ---- |
***
### summer\_project\_setting
Set a project setting in `project.godot`.
| Parameter | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------------------------------------ |
| `key` | string | Yes | Setting key path, e.g. `application/config/name` |
| `value` | string \| number \| boolean | Yes | Setting value |
**Common settings:** `application/config/name`, `application/run/main_scene`, `rendering/renderer/rendering_method`, `display/window/size/viewport_width`, `physics/3d/default_gravity`.
***
### summer\_input\_map\_bind
Set up input controls. Creates the action if it does not exist, then binds events to it.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------- |
| `name` | string | Yes | Action name, e.g. `jump`, `move_forward`, `interact` |
| `events` | array | Yes | Array of input event objects |
**Event format:** `{ type: "key", key: "W" }` or `{ type: "mouse_button", button: 1 }` (1=left, 2=right, 3=middle).
***
### summer\_import\_from\_url
Download a file from a URL and import it into the project. Triggers the engine's full import pipeline: generates `.import` files, extracts textures from `.glb` models, creates materials. Use for 3D models (`.glb`, `.gltf`, `.obj`), textures (`.png`, `.jpg`, `.webp`), and audio (`.ogg`, `.wav`, `.mp3`).
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `url` | string | Yes | HTTP(S) URL to download from |
| `path` | string | No | Target path, e.g. `res://assets/player.glb`. Auto-inferred from the URL if omitted. |
***
### summer\_import\_from\_url\_batch
Download multiple files from URLs in one operation. Performs a single filesystem scan after all downloads, which is faster than importing one at a time.
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------------ |
| `imports` | array | Yes | Array of `{url, path}` objects |
***
## Asset Library Tools (6)
The public asset library is free for all signed-in users, with per-user rate limits. These tools need you signed in (`npx summer-engine login`); the import tools also need the engine running.
### summer\_search\_assets
Search the Summer Engine asset library and your own assets. Hybrid search combines keywords and semantic similarity, so it finds assets by name and by meaning. Returns names, types, preview URLs, and import-ready file URLs.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `query` | string | Yes | Natural language search, e.g. `low-poly tree`, `sci-fi weapon`. For `my_assets`, can be empty to list recent. |
| `assetType` | enum | No | `2d_image`, `animation`, `3d_model`, `audio`, `music`, or `all` (default `all`) |
| `limit` | number | No | Max results, 1 to 20 (default 10) |
| `source` | enum | No | `library` (public 25k+), `my_assets`, or `all` (default `library`) |
***
### summer\_import\_asset
Search the asset library and import the best match into the project in one step. Use when the user wants a specific asset added: "Add a tree to the scene", "Import a wooden barrel". Searches, picks the top result, downloads and imports it, then optionally adds it to the scene.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `query` | string | Yes | What to find, e.g. `low-poly tree`, `wooden crate` |
| `parent` | string | No | Parent node path to add the asset under, e.g. `./World`. Omit to import only. |
| `assetType` | enum | No | Preferred asset type (default `3d_model`) |
| `source` | enum | No | `library`, `my_assets`, or `all` (default `all`) |
***
### summer\_import\_asset\_by\_id
Import an exact Summer asset ID into the current project. Unlike `summer_import_asset`, this does not search or guess: it fetches the asset by ID, downloads it, and runs the import pipeline. Use it right after generation, after picking from `summer_list_my_assets`, or after a search.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
| `assetId` | string | Yes | Summer asset ID |
| `path` | string | No | Target `res://` path. Inferred from asset type and filename if omitted. |
| `parent` | string | No | Parent node path. For 3D models, imports and instantiates under this node. |
| `name` | string | No | Scene node name when `parent` is provided |
***
### summer\_list\_my\_assets
List or search the signed-in user's generated and uploaded assets. Use after generation jobs complete, or when the user refers to "the model I made" or "my last character". Returns exact asset IDs plus file and import URLs.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `query` | string | No | Search term. Empty string lists recent assets (default empty) |
| `assetType` | enum | No | `2d_image`, `animation`, `3d_model`, `audio`, `music`, or `all` (default `all`) |
| `limit` | number | No | Max results, 1 to 20 (default 10) |
***
### summer\_get\_asset
Fetch one asset by exact Summer asset ID. Use after a generation job returns `assetId`/`rigAssetId`/`animationAssetId`, or after search results, when you need the stable file URL, download URL, viewer URL, metadata, license, visibility, or provider details.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------- |
| `assetId` | string | Yes | Summer asset ID |
***
### summer\_get\_asset\_download\_url
Get a downloadable URL for a specific asset file. Prefer this over handing users a raw `fileUrl` when they explicitly ask to download; the response shape is future-proofed for signed URLs.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------- |
| `assetId` | string | Yes | Summer asset ID |
| `role` | enum | No | `primary` or `thumbnail` (default `primary`) |
***
## Generation Tools (6)
Generation runs in Summer Engine Studio and consumes credits. These tools need you signed in (`npx summer-engine login`). Confirm with the user before spending on paid generation, then import results into the project with `summer_import_asset_by_id` or `summer_import_from_url`.
### summer\_generate\_image
Generate an image with AI models. Supports text-to-image (just pass `prompt`) and image-to-image editing (pass `prompt` plus `referenceImageUrl`). Returns the asset with a hosted `fileUrl` and a temp `localPath` on disk you can read to show the user for approval.
| Parameter | Type | Required | Description |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `prompt` | string | Yes | Description of the image to generate |
| `model` | string | No | Model name or full provider ID (default `nano-banana-2`) |
| `style` | string | No | Style preset: `realistic` (default), `cartoon`, `anime`, or `none` |
| `referenceImageUrl` | string | No | Source image URL for image-to-image / edit mode |
| `options` | object | No | Provider-specific params (`guidance_scale`, `seed`, `image_size`, `negative_prompt`, etc.) |
**Known models:** `nano-banana-2` (default), `gemini-flash`, `flux-2`, or any fal-ai model ID as a passthrough.
***
### summer\_generate\_3d
Generate a 3D model. Returns a `jobId`; by default the tool waits for completion (up to 5 minutes) and returns the result directly. Set `wait=false` to poll manually with `summer_check_job`.
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `prompt` | string | No | Description of the model, e.g. `a low-poly treasure chest` (required for `text-to-3d`) |
| `kind` | string | No | `text-to-3d` (default), `image-to-3d`, or `texture` |
| `model` | string | No | `hunyuan` (default), `trellis`, `meshy`, or any fal-ai model ID |
| `imageUrl` | string | No | Source image URL for `image-to-3d` or `texture` |
| `wait` | boolean | No | Wait for completion (default `true`). Set `false` to get the `jobId` immediately. |
| `options` | object | No | Provider-specific params (`target_polycount`, `topology`, `art_style`, etc.) |
**Optional rig pass (`image-to-3d` only):** set `options.rig = true` to add an auto-rig pass. The job result includes a `rigAssetId` you can feed to `summer_generate_motion` to add animation clips.
***
### summer\_generate\_audio
Generate audio. The `capability` selects the mode; `options` is passed through to the provider for fine control (`stability`, `similarity_boost`, `style`, `speed`, etc.).
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ----------------------------------------------------------------- |
| `capability` | string | Yes | `text_to_speech`, `sound_effects`, `music`, or `text_to_dialogue` |
| `text` | string | No | Text for TTS, or description for sound effects |
| `prompt` | string | No | Music description (for `music`) |
| `voiceId` | string | No | Voice ID for TTS |
| `modelId` | string | No | Provider model ID, e.g. `eleven_multilingual_v2` |
| `durationSeconds` | number | No | Duration for SFX or music |
| `inputs` | array | No | Dialogue lines `{text, voiceId}` for `text_to_dialogue` |
| `options` | object | No | Provider-specific params |
***
### summer\_generate\_video
Generate a video. Text-to-video by default; if `imageUrl` is provided, switches to image-to-video mode.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `prompt` | string | Yes | Description of the video content |
| `model` | string | No | `ltx` (default), `kling`, `kling-turbo`, `minimax`, `veo3`, or any new model |
| `imageUrl` | string | No | Source image URL; if provided, uses image-to-video mode |
| `duration` | number | No | Duration in seconds, 5 or 10 (default 5) |
| `aspectRatio` | string | No | `16:9` (default), `9:16`, `1:1`, `4:3` |
| `options` | object | No | Provider-specific params (`negative_prompt`, `num_frames`, etc.) |
***
### summer\_generate\_motion
Generate an animation clip for a rigged humanoid character. Requires a rigged target whose `rigAssetId` came from a prior `summer_generate_3d` call with `options.rig=true`. Picks a clip from a curated mocap set by name. Waits for completion by default; set `wait=false` to poll with `summer_check_job`.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------------ |
| `rigAssetId` | string | Yes | Asset ID of a rigged character |
| `motionName` | string | Yes | Curated motion name: `walk`, `run`, `attack_sword`, `idle`, `jump`, etc. |
| `backend` | enum | No | `meshy-library` (the only option today) |
| `wait` | boolean | No | Wait for completion (default `true`) |
| `options` | object | No | Backend-specific passthrough |
**Common motion names:** idle, idle\_alert, idle\_combat, walk, walk\_back, run, sprint, crouch\_idle, crouch\_walk, jump, jump\_loop, jump\_land, attack\_sword, attack\_punch, attack\_kick, attack\_bow, attack\_cast, block, dodge\_left, dodge\_right, hit\_react, death, wave, dance, sit\_idle.
***
### summer\_check\_job
Check the status of an async generation job. Use when you called a generation tool with `wait=false`, or to re-check a job that timed out. Status values: `waiting`, `active`, `completed`, `failed`, `delayed`, `unknown`.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------- |
| `jobId` | string | Yes | The job ID returned by an async generation tool |
***
## Summer Cloud Tools (7)
Content-addressed project sync: the whole project tree, including big binary assets, syncs across machines without Git. These tools mirror the `summer cloud` CLI commands 1:1 and operate on the project directory on disk plus the Summer Cloud API; they do not require a running engine. All of them accept an optional `project` parameter (project root path, defaults to the current working directory) and return a JSON result with a message, notices, and details. See the [Summer Cloud guide](/guides/summer-cloud) for the sync model and the [Cloud CLI Reference](/mcp/cloud-cli) for command-line equivalents.
### summer\_cloud\_init
Enable Summer Cloud for a project. Creates the cloud project at version 0 and writes `summer-cloud.json` (the project's cloud binding, the only cloud file that belongs in Git) at the project root. Safe to call on an already-bound project.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `project` | string | No | Project root path (defaults to the current working directory) |
***
### summer\_cloud\_status
Show sync status: what a sync would push, pull, or delete, plus any conflicts. Read-only.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------- |
| `project` | string | No | Project root path |
***
### summer\_cloud\_push
Push local project changes to Summer Cloud. Hashes the tracked tree, uploads only missing blobs, and commits a new manifest version. Pulls remote changes first if needed so the pushed version reflects a converged tree.
| Parameter | Type | Required | Description |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project` | string | No | Project root path |
| `confirmDeletes` | boolean | No | Required `true` when the push would delete many cloud files (more than 10, at least 20% of the project, or all of it). Default `false` |
| `bootstrap` | string | No | First-sync choice when both local tree and cloud have content but no sync history exists on this machine: `keep-cloud`, `keep-local`, or `merge` |
| `adoptPath` | boolean | No | Accept that the project folder moved on disk and update the recorded path |
***
### summer\_cloud\_pull
Pull Summer Cloud changes into the local project. Stages downloads, verifies every blob's sha256, writes a local checkpoint before touching existing files, then applies changes atomically.
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | ------------------------------------------------------------------------- |
| `project` | string | No | Project root path |
| `bootstrap` | string | No | First-sync choice: `keep-cloud`, `keep-local`, or `merge` |
| `adoptPath` | boolean | No | Accept that the project folder moved on disk and update the recorded path |
***
### summer\_cloud\_restore
Restore a retained cloud version (creates a new head version with that version's contents, then pulls; history is never rewritten), or roll the local tree back to a pre-sync checkpoint via `checkpointStamp`.
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| `project` | string | No | Project root path |
| `version` | number | No | Cloud version number to restore |
| `checkpointStamp` | string | No | Local checkpoint stamp (see `summer_cloud_checkpoints`) |
***
### summer\_cloud\_checkpoints
List local pre-sync checkpoints. Before any sync modifies or deletes existing files, a full-tree checkpoint is written; the last 20 are kept. Returns the stamps that `summer_cloud_restore` accepts.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------- |
| `project` | string | No | Project root path |
***
### summer\_cloud\_conflicts
List local conflict sets, or restore a preserved conflict file with `restorePath`. When concurrent edits collide, the cloud version wins the path and the losing local bytes are preserved; this tool recovers them as a fresh local edit. Push afterwards to make the restored file canonical.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `project` | string | No | Project root path |
| `restorePath` | string | No | Project-relative path to restore from the conflict sets |
| `set` | string | No | Conflict set stamp (defaults to the newest set containing the path) |
***
## Next Steps
Step-by-step: how an AI builds a full game with these tools
Connect Cursor, Claude Code, Devin Desktop, and more
***
Need help or have questions? Reach out to our founders at [founders@summerengine.com](mailto:founders@summerengine.com) or join our community on [Discord](https://discord.gg/yUpgtxnZky) for fast responses.