# Agent Setup Source: https://docs.summerengine.com/agent-setup Point an AI coding agent at the canonical Summer Engine prompt: build a multiplayer Summer game in GDScript and submit it for review. An AI coding agent can use Summer Engine to build a multiplayer **Summer game** in **GDScript**, integrate the **Summer SDK**, validate it locally, and submit it through the live submission API. A human reviews every submission before its catalog status can become `published`; published catalog status does not make an uploaded game playable yet. ## Point your agent at Summercraft Paste this into any coding agent: ```text theme={null} Fetch https://docs.summerengine.com/agent-setup/prompt.md and follow it exactly, top to bottom. It is the canonical instruction set for building a multiplayer Summer game in GDScript with Summer Engine and the Summer SDK, then publishing it to Summercraft. Context you need before you start: - Summercraft (https://summercraft.ai) accepts Summer SDK games for review. The submission API lives at https://summercraft.ai/api/*; uploaded games are not playable on the platform yet. - You will install and use Summer Engine, build a GDScript-only game that extends SummerGame, export a .pck with the Summer Engine binary, and publish it in four API calls: create game -> get presigned upload URL -> PUT the .pck -> finalize (the server re-verifies your sha256). - Publishing needs a Summercraft access token in SUMMERCRAFT_ACCESS_TOKEN. Build and export first; stop and ask me for the token before the publish step. The prompt contains the instructions to show me for getting one. - Each publish step is limited to 1 request per hour per account, so validate everything locally before touching the API. - After finalize the release is "pending_review" in a manual human review queue. There is no auto-publish, and browser/desktop play of uploaded Summer games is not live yet - say so honestly when you report back. - Any docs page is fetchable as raw markdown by adding .md to its URL; the index is at https://docs.summerengine.com/llms.txt. If the prompt URL is unreachable, stop and tell me instead of improvising. ``` The prompt at [/agent-setup/prompt](/agent-setup/prompt) is the canonical, always-current version — served as plain markdown at `https://docs.summerengine.com/agent-setup/prompt.md` so agents can fetch it directly. It contains a complete, export-verified multiplayer game template (king-of-the-hill, host-authoritative, 1–8 players), the local validation steps, the exact publish calls with every error explained, and the honest post-submission status. ## What the agent will do 1. **Check prerequisites** — Summer Engine for local validation/export, `curl`, a sha256 tool, and (only at publish time) your access token. 2. **Build a multiplayer-native game** — `extends SummerGame`, all gameplay authority on server paths, player state via `set_synced`, local SDK stubs so everything parses and smoke-runs without the platform runtime. 3. **Validate locally** — headless smoke run, banned-API self-check, pack-content check. The upload budget is 1/hour, so the prompt front-loads every check. 4. **Export a game-only `.pck`** — the preset excludes stubs and project config; ships GDScript as readable source. 5. **Publish through the live API** — create game → presigned upload → server-verified finalize. See [Exporting and Uploading](/api-reference/summer-sdk/exporting-and-uploading-your-game) for the full reference. 6. **Report honestly** — release `pending_review` in the manual queue; approval changes its catalog status to `published`, but does not make it playable yet. Rejection comes with a reason on [summercraft.ai/creator](https://summercraft.ai/creator). ## The one thing the agent cannot do: sign in Agents must never handle your password. Create your account and session yourself: 1. Sign up / sign in at [summercraft.ai](https://summercraft.ai). 2. In that tab, open dev tools → Application → Cookies → `summercraft.ai` and find the cookie whose name ends in `-auth-token` (possibly chunked into `.0`/`.1` — concatenate the values in order). 3. URL-decode the value; if it starts with `base64-`, base64-decode the rest. The JSON inside has an `access_token` field — that string is the Bearer token. 4. Hand it to your agent as the `SUMMERCRAFT_ACCESS_TOKEN` environment variable. It expires after about an hour — enough for one publish. Re-extract it when it expires. There is no dedicated token page yet; this manual step is the current path. The publish API accepts `Authorization: Bearer ` on every endpoint. ## Platform status The release API, browser submission with static scanning, manual review queue, and authenticated release downloads are deployed. That does not make an approved game playable. Use the single canonical [Product source & platform status](/knowledge-base/source-status) table for every Live / Scaffold / Planned decision. It covers playback, hosted servers, matchmaking, the runtime sandbox, and the transport contract without duplicating a second status table here. If documentation and reality disagree, trust the API's own error text and mail [founders@summerengine.com](mailto:founders@summerengine.com). ## For agents reading this page directly Fetch `https://docs.summerengine.com/agent-setup/prompt.md` and follow it. Every page here is markdown-addressable: append `.md` to any URL. Index: `https://docs.summerengine.com/llms.txt` (or `llms-full.txt` for full content). # Agent Prompt Source: https://docs.summerengine.com/agent-setup/prompt Canonical instructions for an AI coding agent to build a multiplayer Summer game in GDScript with Summer Engine and publish it for review. You are an AI coding agent. Your job is to use **Summer Engine** and the **Summer SDK** to build a multiplayer **Summer game** in **GDScript**, export a game-only `.pck`, and publish it to Summercraft for review. Follow this document top to bottom. Where a platform capability is not live yet, this document says so explicitly. Any page of these docs is fetchable as raw markdown by appending `.md` to its URL. The full page index is at `https://docs.summerengine.com/llms.txt`. ## 1. What Summercraft is Summercraft (`https://summercraft.ai`) is the platform where Summer games built with the Summer SDK are submitted. Use Summer Engine, extend the SDK base class `SummerGame`, export a `.pck` containing only game files, and submit it through the publish API. A human reviews every submission before its catalog status can become `published`. There is no auto-publish, and a published catalog release is not playable yet. * The publish API lives at `https://summercraft.ai/api/*`. * Docs live at `https://docs.summerengine.com`. * The Summer SDK contract defines `Summer`, `SummerGame`, `SummerPlayer`, and `SummerCharacter3D`. Local stubs let the project parse, and the export excludes those stubs. A future production runtime is intended to provide the real classes, but uploaded games cannot launch there today. **What is live today:** creating a game record, direct-to-storage artifact upload with server-side sha256 verification, the manual review queue, and authenticated release downloads. **What is not live yet (do not promise these to your operator):** playing uploaded Summer games in the browser or desktop shell, hosted dedicated game servers for uploaded games, automatic matchmaking, and the automated runtime sandbox. The examples use a host-authoritative model, but no production transport is live. `SummerMultiplayerPeer` (stock `@rpc` / `MultiplayerSynchronizer` compatibility) is a scaffolded contract still being built. ## 2. Prerequisites — check all three before writing any code 1. **Summer Engine.** If it is missing, install it with `npx -y summer-engine@latest install`. Resolve the installed executable and set `SUMMER_ENGINE` to its path. On macOS the default is `/Applications/Summer.app/Contents/MacOS/Summer`. Run `"$SUMMER_ENGINE" --version` before continuing. 2. **A Summercraft access token.** Check for a `SUMMERCRAFT_ACCESS_TOKEN` environment variable or ask your operator for one. Without it every publish call returns `401 sign_in_required`. **Stop and ask before step 6 if you do not have it** — you can build and export everything first. Show your operator this if they do not know how to get one: > Sign in at `https://summercraft.ai` (create the account yourself — never let an agent handle your password). Then open your browser dev tools on that tab: Application → Cookies → `summercraft.ai`, and find the cookie whose name ends in `-auth-token` (it may be split into `.0`/`.1` chunks — concatenate their values in order). URL-decode the value; if the result starts with `base64-`, base64-decode the rest. Inside the JSON is an `access_token` field: that string is the Bearer token. It expires after about an hour, which is enough for one publish. There is no dedicated token page yet; this manual step is the current path. 3. **`curl` and a sha256 tool** (`shasum -a 256` or `sha256sum`). A bare upstream binary is not the default path. On locked CI infrastructure where Summer Engine cannot be installed, use the explicitly labeled compatibility escape hatch in [local testing](/api-reference/summer-sdk/testing-your-game-locally). It can validate file-format behavior only and does not prove Summer SDK runtime compatibility. Auth model, exactly: every publish endpoint accepts `Authorization: Bearer ` (or a signed-in browser session cookie). A present-but-invalid Bearer token is a hard `401` — it never falls back to a cookie. If you get `401` with a token set, the token has expired: ask your operator for a fresh one. ## 3. Know the rules before you build Your `.pck` must contain **only your game**. The platform enforces, at review and in the browser submit scanner: * **GDScript only.** No `.gdextension`, `.so`, `.dll`, `.dylib`, `.framework`, `.res` files. * **No banned APIs** anywhere in your scripts, even in dead or conditional branches. The blocklist includes `OS.execute`, `OS.shell_open`, `OS.create_process`, `FileAccess`, `DirAccess`, `HTTPRequest`, `HTTPClient`, `JavaScriptBridge`, `ClassDB.instantiate`, `Thread.new`, `Expression`, raw sockets (`StreamPeerTCP`, `PacketPeerUDP`, `TCPServer`, `UDPServer`, `WebSocketPeer`), reflection calls (`.call(`, `.callv(`, `.call_deferred(`, `Callable(`), `Engine.get_singleton`, `Marshalls.base64_to_variant`, `ResourceSaver`, `ProjectSettings.load_resource_pack`, and root-tree escapes (`get_node("/root`, `get_tree().root`). Full list with rationale: `https://docs.summerengine.com/api-reference/summer-sdk/banned-apis-reference.md`. Your code targets the scaffolded `Summer.data` and `Summer.economy` contracts instead of owning I/O or networking; production persistence and economy backends are not live yet. * **No reserved paths** in the pack: `res://sdk/`, `res://core/`, `res://server/`, `res://client/`, `res://official_games/`, `res://bootstrap.*`, `res://project.godot`, `res://summer.cfg`, `res://test_runner.*`. The export preset below keeps them out automatically. * **`manifest.json` at the pack root** with required keys `id`, `name`, `version`, `summer_sdk` (`"1.0"`), `entry_scene`, `min_players`, `max_players`. The entry scene's root script must `extends SummerGame` to satisfy submission review and the future runtime contract; no production runtime currently loads uploaded packs. * **Host-authoritative multiplayer is the only mode.** All gameplay decisions run on server paths guarded by `Summer.is_server()`. Clients render synced state via `set_synced`/`get_synced`; they never decide outcomes. ## 4. Build the game — multiplayer-native template Build multiplayer by default: `min_players: 1` so it works solo, `max_players: 8` so it works with friends, all authority server-side. The template below is a complete king-of-the-hill arena. Run every Summer Engine validation step before publishing; adapt the gameplay, but keep the structure. Create this exact layout in a fresh directory: ```text theme={null} hold-the-hill/ ├── project.godot # local dev config — never shipped ├── export_presets.cfg # export preset — never shipped ├── manifest.json # shipped at pack root ├── main.gd # your game, extends SummerGame ├── main.tscn # entry scene ├── player.tscn # player scene (SummerCharacter3D template) └── sdk/ # LOCAL STUBS, excluded from export ├── summer.gd ├── summer_game.gd ├── summer_player.gd └── summer_character_3d.gd ``` The `sdk/` folder holds **local stubs** that mirror the SDK contract so your code parses and smoke-runs without a Summercraft runtime. The export preset excludes `sdk/*`, so the stubs never ship. The future runtime is intended to provide real classes at the same paths, but that production path is not live. Do not add behavior to the stubs — they are compile shims, not the SDK. `project.godot`: ```ini theme={null} ; Engine configuration file. config_version=5 [application] config/name="Hold the Hill" run/main_scene="res://main.tscn" config/features=PackedStringArray("4.7") [autoload] Summer="*res://sdk/summer.gd" [rendering] renderer/rendering_method="mobile" ``` `manifest.json`: ```json theme={null} { "id": "hold-the-hill", "name": "Hold the Hill", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "main.tscn", "player_scene": "player.tscn", "min_players": 1, "max_players": 8, "description": "King-of-the-hill arena. Stand in the gold circle to score. First to 100 points wins.", "genre": "action", "tags": ["multiplayer", "arena", "king-of-the-hill"] } ``` Change `id`, `name`, and the descriptive fields for your game. `entry_scene` and `player_scene` are relative to the manifest (pack root). `main.gd` — the game. Every decision happens on the server path: ```gdscript theme={null} extends SummerGame const ROUND_SECONDS := 180.0 const MOVE_SPEED := 7.0 const GRAVITY := 20.0 const WIN_SCORE := 100 const HILL_RADIUS := 4.0 const POINT_INTERVAL := 1.0 var _hill_center := Vector3.ZERO var _tick := 0.0 var _round_over := false func _game_init() -> void: var spawn_root := get_node_or_null("SpawnPoints") if spawn_root: for child in spawn_root.get_children(): if child is Node3D: spawn_points.append(child.global_position) var hill := get_node_or_null("Hill") if hill is Node3D: _hill_center = hill.global_position func _game_start() -> void: _round_over = false Summer.set_time_limit(ROUND_SECONDS) Summer.send_announcement("Hold the hill! First to %d points wins." % WIN_SCORE) func _game_end() -> void: _round_over = true var best = null var best_score := -1 for p in get_players(): var s := _score_of(p) if s > best_score: best_score = s best = p if best != null: Summer.send_announcement("%s wins with %d points." % [str(best.display_name), best_score]) func _player_joined(player) -> void: player.set_synced("score", 0) if player.has_method("respawn"): player.respawn(get_random_spawn_point()) func _player_left(_player) -> void: pass func _process(delta: float) -> void: super._process(delta) if not Summer.is_server() or _round_over: return for p in get_players(): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) _tick += delta if _tick < POINT_INTERVAL: return _tick = 0.0 for p in get_players(): if p is Node3D and p.global_position.distance_to(_hill_center) <= HILL_RADIUS: var s := _score_of(p) + 1 p.set_synced("score", s) if s >= WIN_SCORE: Summer.send_announcement("%s takes the crown!" % str(p.display_name)) end_game() return func _score_of(player) -> int: var raw = player.get_synced("score") return int(raw) if raw != null else 0 ``` `main.tscn` — entry scene: floor, hill marker, four spawn points, light, camera: ```text theme={null} [gd_scene load_steps=6 format=3] [ext_resource type="Script" path="res://main.gd" id="1"] [sub_resource type="BoxShape3D" id="floor_shape"] size = Vector3(40, 1, 40) [sub_resource type="BoxMesh" id="floor_mesh"] size = Vector3(40, 1, 40) [sub_resource type="CylinderMesh" id="hill_mesh"] top_radius = 4.0 bottom_radius = 4.0 height = 0.2 [sub_resource type="StandardMaterial3D" id="hill_mat"] albedo_color = Color(0.95, 0.7, 0.2, 1) [node name="Main" type="Node3D"] script = ExtResource("1") [node name="Floor" type="StaticBody3D" parent="."] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, -0.5, 0) [node name="CollisionShape3D" type="CollisionShape3D" parent="Floor"] shape = SubResource("floor_shape") [node name="MeshInstance3D" type="MeshInstance3D" parent="Floor"] mesh = SubResource("floor_mesh") [node name="Hill" type="MeshInstance3D" parent="."] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.1, 0) mesh = SubResource("hill_mesh") material_override = SubResource("hill_mat") [node name="SpawnPoints" type="Node3D" parent="."] [node name="Spawn1" type="Node3D" parent="SpawnPoints"] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 12, 1, 12) [node name="Spawn2" type="Node3D" parent="SpawnPoints"] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -12, 1, 12) [node name="Spawn3" type="Node3D" parent="SpawnPoints"] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 12, 1, -12) [node name="Spawn4" type="Node3D" parent="SpawnPoints"] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, -12, 1, -12) [node name="Players" type="Node3D" parent="."] [node name="Sun" type="DirectionalLight3D" parent="."] transform = Transform3D(1, 0, 0, 0, 0.642788, 0.766044, 0, -0.766044, 0.642788, 0, 10, 0) shadow_enabled = true [node name="Camera3D" type="Camera3D" parent="."] transform = Transform3D(1, 0, 0, 0, 0.819152, 0.573576, 0, -0.573576, 0.819152, 0, 18, 26) ``` `player.tscn` — references the runtime's 3D character template script. The reference is expected; the file itself must never be in your pack: ```text theme={null} [gd_scene load_steps=4 format=3] [ext_resource type="Script" path="res://sdk/summer_character_3d.gd" id="1"] [sub_resource type="CapsuleShape3D" id="player_shape"] [sub_resource type="CapsuleMesh" id="player_mesh"] [node name="Player" type="CharacterBody3D"] script = ExtResource("1") [node name="CollisionShape3D" type="CollisionShape3D" parent="."] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0) shape = SubResource("player_shape") [node name="MeshInstance3D" type="MeshInstance3D" parent="."] transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0) mesh = SubResource("player_mesh") ``` The four stub files. `sdk/summer.gd`: ```gdscript theme={null} # LOCAL STUB - excluded from export, never uploaded. extends Node func end_game() -> void: pass func set_time_limit(_seconds: float) -> void: pass func get_time_remaining() -> float: return 0.0 func get_players() -> Array: return [] func get_player_count() -> int: return 0 func get_max_players() -> int: return 8 func send_announcement(text: String) -> void: print("[Summer stub] announce: ", text) func is_server() -> bool: return true func is_client() -> bool: return false ``` `sdk/summer_game.gd`: ```gdscript theme={null} # LOCAL STUB - excluded from export, never uploaded. class_name SummerGame extends Node3D var spawn_points: Array = [] func _ready() -> void: _game_init() _game_start() func _process(_delta: float) -> void: pass func _game_init() -> void: pass func _game_start() -> void: pass func _game_end() -> void: pass func _player_joined(_player) -> void: pass func _player_left(_player) -> void: pass func end_game(_from_timer: bool = false) -> void: _game_end() func set_time_limit(_seconds: float) -> void: pass func get_time_remaining() -> float: return 0.0 func get_players() -> Array: return [] func get_player_count() -> int: return 0 func get_max_players() -> int: return 8 func get_random_spawn_point() -> Vector3: if spawn_points.is_empty(): return Vector3.ZERO return spawn_points[randi() % spawn_points.size()] func apply_default_movement(_player, _delta: float, _move_speed: float = 7.0, _gravity: float = 20.0) -> void: pass ``` `sdk/summer_player.gd`: ```gdscript theme={null} # LOCAL STUB - excluded from export, never uploaded. class_name SummerPlayer extends Node var peer_id: int = 0 var player_id: String = "" var display_name: String = "Player" var avatar: Dictionary = {} var _synced: Dictionary = {} func set_synced(key: String, value) -> void: _synced[key] = value func get_synced(key: String): return _synced.get(key) ``` `sdk/summer_character_3d.gd`: ```gdscript theme={null} # LOCAL STUB - excluded from export, never uploaded. class_name SummerCharacter3D extends CharacterBody3D var peer_id: int = 0 var player_id: String = "" var display_name: String = "Player" var avatar: Dictionary = {} var health: float = 100.0 var max_health: float = 100.0 var is_alive: bool = true var _synced: Dictionary = {} func set_synced(key: String, value) -> void: _synced[key] = value func get_synced(key: String): return _synced.get(key) func respawn(position_in: Vector3 = Vector3.ZERO) -> void: global_position = position_in health = max_health is_alive = true func damage(amount: float) -> void: health = maxf(0.0, health - amount) is_alive = health > 0.0 func heal(amount: float) -> void: health = minf(max_health, health + amount) func kill() -> void: health = 0.0 is_alive = false func teleport(position_in: Vector3) -> void: global_position = position_in ``` `export_presets.cfg` — this is what keeps stubs and project config out of the pack: ```ini theme={null} [preset.0] name="Summer Game PCK" platform="Linux" runnable=true advanced_options=false dedicated_server=false custom_features="" export_filter="all_resources" include_filter="manifest.json" exclude_filter="sdk/*" export_path="game.pck" patches=PackedStringArray() encryption_include_filters="" encryption_exclude_filters="" seed=0 encrypt_pck=false encrypt_directory=false script_export_mode=0 [preset.0.options] custom_template/debug="" custom_template/release="" debug/export_console_wrapper=1 binary_format/embed_pck=false texture_format/s3tc_bptc=true texture_format/etc2_astc=false binary_format/architecture="x86_64" ssh_remote_deploy/enabled=false ``` `script_export_mode=0` ships your GDScript as readable text — required so review can read your source. If you add asset folders, they are included automatically (`all_resources`); add non-resource data files (e.g. extra `.json`) to `include_filter` as a comma-separated list. ## 5. Validate and export Run all four checks. `$SUMMER_ENGINE` is the installed Summer Engine executable. ```bash theme={null} # 5a. Import resources (first run only; expect exit 0) "$SUMMER_ENGINE" --headless --path . --import # 5b. Smoke run: scene loads, hooks fire, no script errors (expect exit 0, # and the announcement line printed by the stub) "$SUMMER_ENGINE" --headless --path . --quit-after 120 # 5c. Banned-API self-check: must print nothing grep -rnE "OS\.(execute|shell_open|create_process|create_instance|kill)|FileAccess|DirAccess|HTTPRequest|HTTPClient|JavaScriptBridge|ClassDB\.instantiate|Thread\.new|Mutex\.new|Semaphore\.new|StreamPeerTCP|PacketPeerUDP|TCPServer|UDPServer|WebSocketPeer|\.callv?\(|\.call_deferred\(|Callable\(|Engine\.get_singleton|Expression|Marshalls\.base64_to_variant|ResourceSaver|ProjectSettings\.load_resource_pack|get_node\(\"/root|get_tree\(\)\.root" \ --include="*.gd" --include="*.tscn" --include="*.tres" . | grep -v "^\./sdk/" # 5d. Export the pack (no export templates needed for --export-pack) "$SUMMER_ENGINE" --headless --path . --export-pack "Summer Game PCK" game.pck ``` Notes on the checks: the pass condition for 5c is **empty output** — `grep` exits non-zero when it finds nothing, so do not treat its exit code as a failure. If the smoke run prints `SCRIPT ERROR`, fix it before exporting. Review requires parseable source, but no production platform runtime currently loads or refuses submitted packs. Then measure the artifact and keep the values for step 6: ```bash theme={null} ls -l game.pck # must be >= 1024 bytes and <= 536870912 (512 MiB) SHA256=$(shasum -a 256 game.pck | cut -d' ' -f1) # Linux: sha256sum game.pck | cut -d' ' -f1 SIZE_BYTES=$(wc -c < game.pck | tr -d ' ') echo "$SHA256 $SIZE_BYTES" ``` ## 6. Publish through the live API Base URL `https://summercraft.ai`. All requests JSON unless stated. Every step needs `Authorization: Bearer $SUMMERCRAFT_ACCESS_TOKEN`. **Budget warning:** each of the three write steps (create game, upload-url, finalize) has its own limit of **1 request per hour per account**. Validation failures (4xx before the limit check) do not spend it, but a successful call does. You get one full publish attempt per hour — do not experiment against these endpoints; get steps 4–5 right first. ### 6a. Create the game record (once per game, not per version) ```bash theme={null} curl -sS -X POST "https://summercraft.ai/api/games/engine" \ -H "Authorization: Bearer $SUMMERCRAFT_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Hold the Hill"}' ``` * `201 { "gameId": "", "slug": "hold-the-hill", "kind": "engine", "status": "draft", "uploadUrlEndpoint": "/api/games//releases/upload-url" }`. Save it: `GAME_ID=`. * Optional body field `"slug"`: an explicit slug fails with `409 slug_taken` if taken; without it the server derives one and walks around collisions. * `401 sign_in_required` → token missing/expired. (This endpoint's 401 text mentions only the session cookie — Bearer tokens are accepted here all the same.) `429 rate_limited` → body includes `retryAt`; wait. `409 slug_taken` → pick another slug. * Skip this step for updates to an existing game — reuse its `gameId`. ### 6b. Request the presigned upload URL Declare exactly what you measured in step 5. `version` must match `[A-Za-z0-9][A-Za-z0-9._-]{0,31}` with no `..`; `sha256` is the lowercase hex digest; `sizeBytes` the exact byte count. ```bash theme={null} curl -sS -X POST "https://summercraft.ai/api/games/$GAME_ID/releases/upload-url" \ -H "Authorization: Bearer $SUMMERCRAFT_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"version\": \"1.0.0\", \"sha256\": \"$SHA256\", \"sizeBytes\": $SIZE_BYTES}" ``` * `200 { "uploadUrl", "method": "PUT", "headers": { "content-type": "application/octet-stream", "if-none-match": "*" }, "objectKey", "maxBytes", "expiresAt", "finalizeUrl" }`. * The URL expires in 1 hour. **Both returned headers are folded into the URL's signature** — the PUT must send them exactly, nothing extra that conflicts, or storage answers `403 SignatureDoesNotMatch`. * Errors: `404 game_not_found_or_forbidden` (wrong `gameId` or not your game) · `409 not_a_godot_game` (that `gameId` is a web game) · `409 version_exists` (bump `version`; released versions are immutable) · `413 artifact_too_large` · `429 rate_limited`. ### 6c. PUT the artifact ```bash theme={null} curl -sS -X PUT "$UPLOAD_URL" \ -H "Content-Type: application/octet-stream" \ -H "If-None-Match: *" \ --data-binary @game.pck ``` * Success is an empty `200`. No `Authorization` header here — the URL itself is the credential. * `412 Precondition Failed` → an object already exists at this key (the key is write-once). If your earlier PUT half-landed, finalize will detect and delete a corrupt one; a clean object under the same (version, sha256) means this exact artifact was already uploaded — just finalize. * `403 SignatureDoesNotMatch` → your headers differ from the two returned ones. ### 6d. Finalize — the server verifies your bytes ```bash theme={null} curl -sS -X POST "https://summercraft.ai/api/games/$GAME_ID/releases/finalize" \ -H "Authorization: Bearer $SUMMERCRAFT_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"version\": \"1.0.0\", \"sha256\": \"$SHA256\", \"changelog\": \"Initial release.\"}" ``` The server HEADs the stored object, streams it through sha256, and compares against your declaration. Nothing you claim is trusted. * `201 { "releaseId", "gameId", "version", "sha256", "sizeBytes", "pckUrl", "status": "pending_review", "adminNotified", "detail" }` — you are done; the release is queued for human review. * `409 no_upload_intent` → you skipped 6b, or the declaration differs from what 6b recorded. * `409 artifact_missing` → the PUT never landed; redo 6c. * `400 checksum_mismatch` / `400 size_mismatch` → the stored object was corrupt; it has been deleted so the key is free — redo 6c with the same URL if unexpired, then finalize again. * `429 rate_limited` → finalize has its own hourly budget; wait for `retryAt`. * `changelog` is optional, max 2000 chars. ## 7. After submission — what to tell your operator Report exactly this, no more: 1. The game record exists at status `draft`; release `` is `pending_review` in the manual review queue. A human reviews every submission; there is no automatic publish and no guaranteed review time. 2. When approved, the game and active release receive `published` catalog status; if rejected, the reason appears for the creator on `https://summercraft.ai/creator`. Published catalog status does not make the uploaded game playable yet. 3. The owner (and admins) can verify the stored artifact any time — response includes a short-lived (5 min) download URL plus the server-verified `sha256`: ```bash theme={null} curl -sS "https://summercraft.ai/api/games/$GAME_ID/releases/1.0.0/download-url" \ -H "Authorization: Bearer $SUMMERCRAFT_ACCESS_TOKEN" ``` Other signed-in users can fetch it only after the game is published. 4. Playing uploaded Summer games in the browser or desktop shell, hosted game servers, automatic matchmaking, and the runtime sandbox are not live yet — publishing today means entering the catalog pipeline, not instant playability. Do not claim otherwise. The canonical status is `https://docs.summerengine.com/knowledge-base/source-status.md#platform-capability-status`. ## 8. Updating the game later Releases are immutable. To ship a fix: bump `manifest.json` `version` **and** use the same new version string in 6b/6d, re-export, and repeat 6b → 6c → 6d with the same `gameId`. Every update goes through review again. Remember the 1/hour budgets. ## 9. If something here does not match reality Error bodies from this API are self-describing: `{ "error": "", "detail": "" }` — trust the `detail` text. For anything else, fetch the full reference: `https://docs.summerengine.com/api-reference/summer-sdk/exporting-and-uploading-your-game.md` and `https://docs.summerengine.com/api-reference/summer-sdk/submission-guide.md`. Report doc bugs to `founders@summerengine.com`. # Design Mode. Draw on your game to build it Source: https://docs.summerengine.com/ai-tools/design-mode Click nodes or draw on your 2D and 3D viewport to tell Summer what to change. Design Mode and Fullscreen Iteration Mode keep you in the scene while the same chat runs underneath. Design Mode is how you build without living in the sidebar. You stay in your 2D or 3D scene, point at what matters, and Summer does the work in the same chat you already have. This is not a separate AI or a stripped-down prompt box. The floating bar on the viewport sends messages into your main conversation. Same model, same history, same project context. ## Two ways to use it **Design Mode** keeps the editor layout as-is. Select a node and a small bar appears near your selection. Describe the change and send. The bar clears when the turn starts because the sidebar already shows progress. Select another node any time to target again. **Fullscreen Iteration Mode** fills the window with your scene and pins a bar at the bottom center. Use it when you want the viewport front and center. The bar stays visible and shows a working indicator while Summer runs. Both modes work on 2D and 3D main screens. ## Getting in **Design Mode** * `Cmd+Shift+D` on Mac, `Ctrl+Shift+D` on Windows * Select a node first and the bar appears with that node already targeted **Fullscreen Iteration Mode** * Collapse the chat sidebar while a 2D or 3D scene is open * Click the **Full Screen** chip in the top-right of the viewport * `Cmd+Shift+M` on Mac, `Ctrl+Shift+M` on Windows * Distraction-free on a scene view (`Ctrl+Shift+F11`) Press `Esc` to exit either mode. Explicit fullscreen entries restore your layout exactly. ## Click to target Click a node and it becomes a target chip in the bar. Shift-click to add more targets. Each chip shows the node name. Clear a chip with × or deselect in the editor to hide the Design Mode bar. Your message goes out with the node paths attached, the same way scene references work in the sidebar chat. ## Draw on the viewport Drag on the viewport to draw an annotation. Circle an area, mark a spot, sketch where something should go. One drawing equals one message. Starting a new drawing clears the previous one. When you release, Summer captures a cropped screenshot of your drawing and shows a thumbnail in the bar. Type your instruction and send. The screenshot rides along as an image attachment so the AI sees what you marked. Examples that work well: ``` Add a tree here Move this platform down The lighting is too dark in this corner Put the spawn point inside this circle ``` Esc steps through cancel stroke, clear drawing, exit mode. ## What you see while Summer works In Design Mode the bar clears on send. Follow the turn in the sidebar chat. In Fullscreen Iteration Mode the bar shows a spinner, the current action, and elapsed time, then a "Worked for Xs" chip when the turn finishes. ## Same chat, dumb overlay The sidebar chat is the only place the AI runs. The viewport bar is a lightweight composer that forwards your text, targets, and screenshots into that chat. There is no second stream and no duplicate history. Selection changes in the editor push to the bar automatically. Turn status flows back so Fullscreen Iteration Mode can show progress. ## Tips Be specific about what you want and why. A drawing plus "make this feel more ominous" beats "fix it." If you need the full conversation visible, expand the sidebar. Nothing is lost. Attach reference images from the overlay bar when you want a style reference alongside your drawing. ## Related The team of agents that builds your game Teach Summer repeatable ways of building What Summer can do inside your project Get started building with Summer *** Need help or have questions? Reach out at [founders@summerengine.com](mailto:founders@summerengine.com) or join [Discord](https://discord.gg/yUpgtxnZky). # MCP Asset Search Source: https://docs.summerengine.com/ai-tools/mcp-asset-search Search and import 25,000+ game assets from your IDE using AI-powered hybrid search ## Overview The Asset Search MCP tools let AI agents (running in Cursor, Claude Code, Devin Desktop, or any MCP-compatible IDE) discover and import game assets directly into your Summer Engine project. Instead of switching to the Summer app to browse the asset store, you describe what you need in natural language and the agent finds it, imports it, and optionally adds it to your scene. **What makes it powerful:** Hybrid search combines keyword matching with semantic understanding. A query like "sci-fi weapon" finds assets named "Blaster A" *and* assets described as "futuristic gun" or "space shooter." Results are diversified across asset packs so you get variety, not ten variations of the same model. **Pro subscription required.** Asset search via MCP is a Pro feature. Run `summer login` to authenticate. Free users can use all other MCP tools (scene editing, project settings, import from URL) without restriction. ## Prerequisites 1. **Summer Engine** installed and running (for import and scene placement) 2. **MCP configured** in your IDE to use the Summer Engine MCP server 3. **Logged in** with a Pro account: `summer login` 4. **Scene open** in the editor (for adding assets to the scene tree) ## Tools ### summer\_search\_assets Searches the asset library by description. Returns asset names, types, preview URLs, and import-ready file URLs. Use this when you need to explore options before committing to an import, or when the user asks "what trees do you have?" or "show me some low-poly characters." **Parameters:** | Parameter | Type | Default | Description | | ----------- | ------ | ---------- | ------------------------------------------------------------------------------ | | `query` | string | *required* | Natural language search, e.g. "low-poly tree", "wooden crate", "sci-fi weapon" | | `assetType` | enum | `"all"` | Filter: `2d_image`, `animation`, `3d_model`, `audio`, `music`, or `all` | | `limit` | number | `10` | Max results (1–20) | **Example responses:** ```json theme={null} { "assets": [ { "id": "abc123", "title": "Tree Oak", "type": "3d_model", "fileUrl": "https://res.cloudinary.com/.../tree-oak.glb", "thumbnailUrl": "https://res.cloudinary.com/.../preview.png", "pack": "Nature Kit", "similarity": 0.87 } ], "count": 10, "summary": "3 from Nature Kit (3d model), 2 from Forest Pack (3d model), ...", "message": "Found 10 assets matching \"low-poly tree\"" } ``` **When to use:** Before importing, when the user wants to see options, or when you need to pick the best match from several results. *** ### summer\_import\_asset Searches the asset library and imports the best match in one step. Use when the user's intent is clear: "Add a tree to the scene," "Import a wooden barrel," "Put a low-poly character in `./World`." **Parameters:** | Parameter | Type | Default | Description | | ----------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------ | | `query` | string | *required* | What to find, e.g. "low-poly tree", "wooden crate" | | `parent` | string | *optional* | Parent node path to add the asset under, e.g. `./World`. If omitted, only imports (no scene placement) | | `assetType` | enum | `"3d_model"` | Preferred type: `2d_image`, `animation`, `3d_model`, `audio`, `music`, or `all` | **Behavior:** 1. Searches the library (up to 5 results) 2. Picks the top match by relevance 3. Downloads and imports the file into the project (triggers the engine's import pipeline) * **Kenney 3D assets:** Imports texture first (`Textures/colormap.png`), then the GLB, using pack-scoped paths (`res://assets/models/kenney/{packSlug}/`). This prevents texture collisions when multiple packs are imported. Each pack keeps its own texture folder. 4. If `parent` is provided and the asset is a 3D model, instantiates it under that node **Example success response:** ```json theme={null} { "success": true, "asset": "Tree Oak", "type": "3d_model", "importedTo": "res://assets/models/kenney/nature-kit/tree-oak.glb", "addedToScene": true, "parent": "./World", "message": "Imported \"Tree Oak\" and added to ./World" } ``` **When to use:** When the user wants a specific asset added and the description is unambiguous. For compound requests ("add trees, rocks, and a fence"), call `summer_import_asset` multiple times or use `summer_search_assets` first to curate, then import selected assets via `summer_import_from_url`. *** ## Search Quality Tips The hybrid search works best when you match how assets are described in the library: * **Be specific:** "low-poly wooden crate" beats "crate" * **Use style terms:** "cartoon", "realistic", "stylized", "sci-fi", "fantasy" * **Mention context:** "platformer tiles", "FPS weapon", "RPG character" * **Pack names help:** If you know a pack (e.g. "Nature Kit"), include it Results are diversified: you won't get ten assets from the same pack. Each result includes a `pack` field so you can group or filter by asset pack. *** ## Error Handling | Error | Cause | Resolution | | -------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- | | `Not logged in` | No auth token | Run `summer login` | | `upgrade_required` | Free plan | Upgrade to Pro at [summerengine.com/dashboard](https://summerengine.com/dashboard) | | `Invalid or expired token` | Token expired or invalid | Run `summer login --force` | | `No results` | Query didn't match any assets | Try different keywords or broaden the search | | `Engine error` | Summer Engine not running | Open Summer Engine first | | `Import failed` | Download or import pipeline failed | Check engine logs; verify asset URL is accessible | *** ## Workflow Examples ### Single asset, add to scene User: "Add a low-poly tree to my World node" Agent calls: `summer_import_asset({ query: "low-poly tree", parent: "./World", assetType: "3d_model" })` ### Browse before importing User: "What sci-fi weapons do you have?" Agent calls: `summer_search_assets({ query: "sci-fi weapon", assetType: "3d_model", limit: 15 })` Agent presents results, user picks one. Agent then uses `summer_import_from_url` with the chosen asset's `fileUrl` and `summer_instantiate_scene` to add it. ### Multiple assets, same type User: "Add some wooden crates and barrels to the warehouse" Agent calls `summer_import_asset` twice (or uses `summer_search_assets` + `summer_import_from_url_batch` for bulk import). *** ## Asset Library The search covers **25,000+ assets** from the Kenney asset collection: 3D models, 2D sprites, UI elements, and audio. All assets are CC0 (public domain) and free to use in commercial projects. Browse the full collection at [summerengine.com/asset-store](https://summerengine.com/asset-store). See [Art System Licensing](/art-system/licensing) for details. Create, browse, and manage assets in the Summer app Configure MCP in Cursor, Claude Code, and other IDEs # Memory. How Summer Remembers Your Project Source: https://docs.summerengine.com/ai-tools/memory Summer remembers the decisions you make about your game and carries them across every chat, so you never have to re-explain your art style, your mechanics, or the way you like things done. Every game has a set of decisions that sit underneath everything else. The art style. The core mechanic. How you name things. Whether it is 2D or 3D. The kind of feel you are going for. Summer remembers those decisions so you do not have to say them twice. This is what memory is. A running record of what your project is and how you like it built, kept per project and pulled into every new chat automatically. ## What Summer remembers When you make a real decision about your game, Summer writes it down. Not every passing comment, but the things that shape the whole project. If you settle on a pixel-art look, or decide the game is a top-down roguelike, or pick a naming convention for your scenes, that goes into memory as a short note. From then on, every chat starts already knowing it. A new conversation three weeks later does not ask you what kind of game this is. It already knows, because the decision is remembered. ## Telling Summer to remember Most of the time this happens on its own. But you can also make it explicit. If you say remember this, or do not forget, or from now on always do it this way, Summer takes that as a direct instruction to write it down rather than just nod along. A one-line fact or preference becomes a memory note. Something bigger, like a repeatable way of building a whole system, becomes a [skill](/ai-tools/skills) instead, because that is really a workflow and not just a fact. Summer knows the difference and files each in the right place. The point is simple. When you tell Summer to remember something, it actually persists it. It does not just say got it and forget by the next chat. ## Seeing your project's memory You can read everything Summer remembers about a project. Open your avatar menu, go to Settings, and pick Memory. There you will see the notes Summer has kept, in plain language. If you are working in the desktop app with a project open, this shows the live memory for that project. It is a window onto exactly what Summer reads at the start of every chat, so there are no surprises about what it does and does not know. ## Memory, skills, and context together Memory is one of three ways Summer holds onto knowledge, and they fit together. Memory holds the facts and decisions about this specific project. [Skills](/ai-tools/skills) hold the how, the repeatable ways of building that you want followed. And Summer's [project intelligence](/ai-tools/rag-search) reads and indexes your actual files so it always knows the current state of your game. Between the three, Summer shows up to each chat knowing what your game is, how you like it built, and what is currently in it. ## Related Teach Summer repeatable ways of building How Summer reads and searches your project The team of agents that builds your game Get started building with Summer *** Need help or have questions? Reach out at [founders@summerengine.com](mailto:founders@summerengine.com) or join [Discord](https://discord.gg/yUpgtxnZky). # AI Operations Source: https://docs.summerengine.com/ai-tools/operations What Summer Engine's AI can do in your project ## Meet Your AI Game Development Team Summer Engine works like a small studio. You talk to one agent, and behind the scenes it hands the hands-on work to a fixed team of specialists. ### The specialists You do not create specialists, and you cannot ask for one by name. The main agent picks from the team below based on the task, and often runs several at once. **A researcher** reads your project read-only and answers questions about how something is wired, with file and node anchors. Fast and cheap. **A general worker** handles multi-step tasks that need file reads and writes, like scaffolding scripts or research-then-apply edits. **A builder** builds scenes and gameplay end to end: writes scripts and scene files, sets the main scene, binds input actions, changes project settings, and compile-checks the result. **An asset maker** creates images, 3D models, audio, rigged characters, and animations from a brief. One variant returns assets for you to review; another also imports them, places them in your scene, and wires up what they need. **A verifier** traces the actual scene, scripts, signals, and editor state to confirm a feature works, and reports back honestly when it does not. **An advisor** is the second opinion the main agent turns to when it is stuck or unsure. There is no 3D specialist and no audio specialist. Ask for realistic forest lighting or a horror sound mix and the main agent takes it on directly, delegating to the team above as needed. ### How specialists work Specialists are not separate conversation threads. They run inside the same conversation as tools the main agent calls, and they do not persist between chats. You can watch one work live in your chat as its own clean thread. When it finishes, it folds a short summary back into the main chat and the details stay tucked away if you ever want to look. See [Subagents](/ai-tools/subagents) for the full picture. ### What Summer Engine Can Build For You Summer Engine doesn't just talk about game development - it actively builds things in your project. Here's what it can create: **Game Code That Works** Summer Engine writes production-ready GDScript that integrates with your existing codebase. Not just snippets, but complete systems: * Character controllers with proper physics integration * Inventory systems with UI and data persistence * AI behaviors that work with your game's mechanics * Network synchronization for multiplayer features **Visual Assets You Need** When you need game art but don't have an artist yet: * UI textures and button graphics * Environment backgrounds and tilesets * Character sprites and animations * Special effects and particle textures **Audio That Fits Your Game** Sound design that's tailored to your game's atmosphere: * Background music that matches your game's mood * Sound effects for specific game actions * Ambient audio loops for different environments * Voice acting prompts for professional recording **Documentation That Helps** Summer Engine creates living documentation that stays current: * Code comments that explain complex systems * Design documents that capture your game vision * Technical guides for your team members * Player-facing content like tutorials and lore ### Summer Engine's Knowledge Library Think of Summer Engine as having instant access to a vast game development library. When you're stuck on a technical problem, Summer Engine can research and find the right solution. **Built-in Engine Expertise** Summer Engine knows the engine inside and out. When you ask "How do I create a third-person camera that follows the player smoothly?", Summer Engine doesn't guess. It knows the exact Camera3D setup, the right script structure, and the physics considerations. **Real-Time Research** Summer Engine can search current tutorials, documentation, and community resources while you work. Need to implement a specific shader effect? Summer Engine finds the latest examples and adapts them to your project. **Learning From Your Code** Summer Engine analyzes your existing code patterns and suggests improvements. If you have a consistent way of handling player input, Summer Engine learns that pattern and applies it to new features. **Context-Aware Help** Unlike generic AI that gives broad advice, Summer Engine understands your specific game. When you ask for help with collision detection, Summer Engine looks at how you've implemented it elsewhere in your project and gives tailored advice. ### Working Directly in Your Project Summer Engine doesn't just suggest changes. It can implement them directly in your project. This means you can describe what you want and see it appear in your game. **Safe File Operations** Summer Engine creates and modifies files with care. When you ask Summer Engine to "add a health system to my player", it: 1. Creates a new script file with the health logic 2. Adds the necessary variables and functions 3. Connects it to your existing player scene 4. Sets up any required UI elements **Smart Project Understanding** Summer Engine knows how your project is organized. It understands: * Which scenes connect to which scripts * How your assets are structured * What naming conventions you use * How your game's systems work together **Seamless Asset Integration** When Summer Engine generates an asset for you (like a texture or sound), it automatically places it in the right folder and connects it to your scenes. No manual importing required. **AI Asset Import** Summer Engine imports assets from Summer Studio directly into your project. Describe what you need (a low-poly tree, a wooden crate, footsteps on gravel) and Summer Engine searches the store, picks a match, downloads it, and runs the import pipeline. The asset appears in your project and is ready to place in your scene. No copy-paste, no manual download, no wondering where the file went. For scenes that need many assets at once (a village, a forest, a city block), Summer Engine supports bulk import. It plans the full set, downloads and imports everything in one batch, runs a single filesystem scan, and tells you when it is done. One wait instead of many. Your computer may lag briefly during large imports, but you get a heads-up first. The assets are there when Summer Engine needs them, and it can start placing them in your scene right away. **Undo and Exact Receipts** Scene operations integrate with Ctrl+Z. File operations are applied atomically and return exact receipts, so Summer can detect stale state and recover without pretending an edit landed. ## Which AI Models Power Summer Engine? The operations on this page are driven by whichever model is selected in the chat composer. ### Choosing the chat model Auto is the default and is available on every plan. MAX routes to a frontier model on paid plans. You can also pick a specific model yourself — the selector carries models from OpenAI, Anthropic, DeepSeek, GLM, Kimi, Grok, and Qwen, and it is the live list rather than anything written here. See [Models](/auto-mode/models). ### Generation Models Asset generation runs on separate backends, chosen per job rather than by your chat model: hosted image models for 2D art, Meshy / Rodin / Tripo / Hunyuan / Trellis for 3D, ElevenLabs for voice, dialogue, sound effects and music, and Veo / Kling / Seedance for video. See [Which AI models does Summer use?](/knowledge-base/ai-models). Unlike free-form file editing, Summer Engine uses specific operations that ensure your project stays stable and nothing breaks unexpectedly. **What it does**: Creates new nodes in your scene **Example prompts**: * "Add a CharacterBody2D named Player" * "Create a Button under the UI node" * "Add a CollisionShape2D to the Player" **How it works**: * AI specifies the parent node and node type * Node is created with a unique name * Automatically selected in the scene tree * Fully undoable with Ctrl+Z **What it does**: Changes node properties and values **Example prompts**: * "Set the Player's position to (100, 200)" * "Make the Button text say 'Start Game'" * "Change the sprite texture to player.png" **How it works**: * AI reads current property values * Sets new values through the inspector * Changes appear immediately in the editor * Each property change is undoable **What it does**: Connects node signals to methods **Example prompts**: * "Connect the Button's pressed signal to start\_game" * "Wire up the player's body\_entered signal" **How it works**: * AI finds the signal and target method * Creates the connection in the editor * Generates method stubs if needed * Opens external editor for code editing **What it does**: Imports 3D models, textures, and audio from Summer Studio into your project **Example prompts**: * "Import a low-poly tree for my forest" * "Add wooden crates and barrels for my warehouse scene" * "Build a village: houses, trees, fences, and props" **How it works**: * AI searches Summer Studio (25k+ assets) by semantic and keyword * Single asset: downloads, writes, runs import, ready to place * Bulk: imports many assets in one batch, one scan, then places them in your scene * Summer Engine tells you before large imports that the computer may lag briefly ## Project Operations AI can also modify project-level settings: **What it does**: Changes project configuration **Example prompts**: * "Set the main scene to MainMenu.tscn" * "Add a new layer to the physics layers" * "Configure the window size to 1920x1080" **What it does**: Manages input action mappings **Example prompts**: * "Add a 'jump' action mapped to Space" * "Create movement actions for WASD" * "Set up controller input for player 2" **What it does**: Attaches scripts and opens editors **Example prompts**: * "Attach a script to the Player node" * "Open the player script in my editor" * "Create a new script for the UI manager" **Note**: For substantial code editing, Summer Engine opens your external editor (VS Code, Cursor, etc.) ## Reading Your Project Before making changes, AI can read your project structure: ### Project Intelligence * **File tree scanning** - AI sees all your scripts, scenes, and assets * **Scene structure reading** - Understands node hierarchies and relationships * **Property inspection** - Reads current values before making changes * **Script content** - Analyzes your existing code for context ### What This Enables AI understands your project structure and suggests appropriate changes References existing nodes, scripts, and assets in its responses Avoids naming conflicts and maintains scene integrity Builds on your existing work rather than starting from scratch ## Tools, search & execution ### Shell commands require approval **All shell commands require your approval before they run.** The agent can suggest commands (e.g. run tests, install dependencies, run scripts), but nothing executes until you explicitly approve it. This keeps your system safe and gives you full control over what runs. ### Grep search Summer Engine uses **grep-style search** (ripgrep) across your codebase for faster, more precise discovery. The agent can find code patterns, symbols, and references without loading entire files, which improves both search quality and performance. ### Glob file discovery Summer Engine can **find files by pattern** (e.g. `*.gd`, `**/scripts/*.tscn`). When the AI needs to discover which files exist before reading or editing, it uses glob to quickly list matching paths. This is faster than scanning the full tree when you know the file type or location pattern. ### Code editing tools Summer Engine chooses the right edit tool for each job: **strReplace** for small, surgical changes and **writeFile** for complete new content. File tools return exact receipts. If a file changed after the AI read it, a stale edit is refused so the AI can reread and adapt instead of overwriting newer work. ### Explicit scene targets Scene operations name the exact `res://` target with `scenePath`. The scene does not need to be the visible editor tab, and opening a scene is navigation only. A successful mutation includes an engine receipt and one final automatic save. If a scene cannot load, Summer returns the concrete reason, such as a missing or invalid dependency. The AI can inspect that file, repair it, and retry the same scene rather than treating every tool failure as unrecoverable. ### Concurrent work The main agent and subagents can work concurrently without a routine whole-project writer lock. Exact project, file, and scene targets keep work scoped. The engine orders operations that must run on its main thread, while content receipts prevent stale same-file overwrites. ### Infrastructure (Vercel) Search and AI infrastructure runs on **Vercel**. Where applicable, services are hosted in the EU for privacy and low latency. This is already implemented and in use. ### Subagents The agent can **spawn subagents**: specialized background assistants that run in their own context. Summer Engine uses them automatically to rapidly research your codebase (the **Explore** agent) or execute complex multi-step tasks (the **General Purpose** agent) in parallel. You can watch subagents work live in the chat via an interleaved transcript of their thoughts and tool usage, keeping the main conversation clean while they handle the heavy lifting. See [Subagents](/ai-tools/subagents) for how they work and when to use them. ## Safety & Limitations ### What's Safe * **Explicit targets** - Every mutation identifies the project file or scene it changes * **Exact receipts** - Summer reports what the engine actually applied and saved * **Conflict-aware file edits** - Stale overwrites are refused with a reason the AI can recover from * **Scene undo support** - Scene operations integrate with the editor's undo history ### Current Limitations * **No batch code refactors** - Large refactors across many files are not supported yet (bulk asset import is supported) * **Limited import settings** - Asset import options are mostly manual for now * **One explicit scene at a time** - Cross-scene work is supported, but each scene mutation names its own target ### Best Practices Always check what the AI plans to do before confirming operations. The change review panel shows exactly what will be modified. Scene mutation tools save their explicit target automatically. Use a standalone save only when you intentionally need to save or save-as without another mutation. Don't hesitate to undo AI changes that aren't quite right. You can always ask for a different approach. ## Getting Started Learn how to effectively communicate with Summer Engine's AI Understand how AI reads and indexes your project Parallel and specialized AI assistants Solutions for common issues and questions *** 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. # Project Intelligence Source: https://docs.summerengine.com/ai-tools/rag-search How Summer Engine understands and indexes your entire project ## How It Works Summer Engine automatically analyzes and indexes your project to understand: * **Code structure** - Classes, functions, variables, and their relationships * **Scene hierarchy** - Node trees, components, and connections * **Asset relationships** - Textures, models, sounds, and where they're used * **Project patterns** - Your coding style, naming conventions, and architecture ## Automatic Indexing When you open a project, Summer Engine: Analyzes scripts, scenes, resources, and project settings Creates connections between different parts of your project Learns your patterns and project-specific logic Continuously updates as you make changes ## What Summer Engine Knows ### Code Understanding ```gdscript theme={null} # Summer Engine knows this is a player controller extends CharacterBody3D class_name Player @export var speed: float = 5.0 @export var jump_velocity: float = 4.5 func _physics_process(delta): # Summer Engine understands this handles movement handle_movement(delta) ``` When you ask "make the player faster", Summer Engine knows: * Which script controls the player * That `speed` is the relevant variable * How to modify it safely ### Scene Relationships ``` Main Scene ├── Player (CharacterBody3D) │ ├── MeshInstance3D │ └── CollisionShape3D ├── Environment └── UI ├── HealthBar └── Score ``` Summer Engine understands these connections and can: * Add UI elements that reference the player * Create enemies that target the player node * Modify scenes while preserving relationships ## Smart Suggestions Based on project analysis, Summer Engine can suggest: "I noticed you're using get\_node() in \_process. Let me cache those references." "This signal connection could be done in the editor instead of code." "Adding null checks here would prevent crashes when nodes are freed." "Consider using a state machine for this enemy behavior." ## Per-Project Indexing & Caching Summer Engine uses **per-project indexing** with **intelligent caching**, similar to how Cursor indexes a repo. Each project has its own isolated search index. When you open a project, Summer Engine scans and indexes your codebase, then uses RAG (Retrieval-Augmented Generation) to find relevant context when you ask questions. **Smart caching** means Summer Engine remembers what it learned between sessions *within that project*. The index persists so you don't start from scratch every time you open Summer Engine. **New chats start fresh**: Each new chat does not automatically include a summary of your other chats. If you want context from a previous conversation, you need to inject it (for example, by referencing specific files or summarizing what you discussed). ## Privacy & Performance **How your code is stored**: Indexing runs server-side. Source chunks and their embeddings are stored so search can run over them. Privacy Mode, available on paid plans, stops your code being used to train models. See [Security Overview](/security/overview). **Incremental Updates**: Only changed files are re-analyzed, keeping things fast. ## Customizing Intelligence You can guide Summer Engine's understanding: ### Project Comments ```gdscript theme={null} # SUMMER: This is the main game manager singleton extends Node # SUMMER: Handle player spawning and respawning func spawn_player(): pass ``` ### Ignore Patterns Create a `.summerignore` file: ``` # Don't analyze generated files .import/ builds/ temp/ # Skip third-party code addons/third_party/ ``` ## Working with Large Projects For projects with thousands of files: * **Prioritization**: Summer Engine focuses on recently modified files * **Selective indexing**: You can specify which folders are most important * **Background processing**: Analysis happens without blocking your work ## Next Steps See how project intelligence powers Summer Engine's AI operations # Skills. Teach Summer Your Way of Building Source: https://docs.summerengine.com/ai-tools/skills Skills are short guides that make Summer better at building your game. Summer ships a library of them, and you can write your own for a single project or all of them. Trigger any skill with a slash command right from the chat. A skill is a short guide that teaches Summer how to do something well. Lighting a 3D scene, building a survivors game, wiring up a save system, keeping your art consistent. Summer reads the right one at the right moment and follows it, so you get the good version of a thing instead of a first guess. Summer ships with a library of skills covering the whole game-dev workflow, and you can add your own. That is the part that makes Summer feel like yours. Once you have taught it how you like something done, it does it that way every time, on every project. This page is about skills inside the Summer app. If you are using Summer through the command line or an external agent like Cursor or Claude Code, see [Skills for the CLI and MCP](/mcp/skills). ## Why skills matter Without skills, an AI agent leans on whatever it happened to learn during training. That is fine for common patterns and shaky for the specific, hard-won details that make a game feel good. Skills fix that. They carry the exact steps, the right order to do them in, and the traps to avoid, so Summer does not have to rediscover them every time. They also keep your chats short. Instead of you re-explaining how your project works in every message, the knowledge lives in a skill and Summer pulls it in when the moment calls for it. You write less and get more. ## The built-in library Summer comes with a set of skills for the things people build most. Making a game from a genre, character movement, combat, cameras, lighting, asset pipelines, multiplayer, menus, debugging, and performance, among others. You do not install or configure them. Summer sees the whole library and reaches for the one that fits what you are doing. You never have to name a skill for it to help. If you ask for a horror game, Summer already knows to reach for the lighting and atmosphere guidance on its own. ## Slash commands When you do want to point Summer at a specific skill, type a slash in the chat box. A menu appears with the skills you can trigger, and picking one loads its guidance for that message. ``` /debug the player falls through the floor /make-game a cozy fishing game /optimize the frame rate drops in the forest ``` Whatever you type after the command is context for the skill. So `/debug the enemies stop spawning after wave 3` gives the debugging skill both the playbook and the exact problem to work on. Slash commands are the fastest way to get Summer into the right mode for the task in front of you. ## Writing your own skills The library is a starting point. The real power is teaching Summer the way you build. Say you always structure your inventory a certain way, or you have a house art style, or a checklist you run before calling a level done. Turn any of that into a skill and Summer follows it from then on. You can scope a skill to a single project when it is specific to that game, or make it universal so it applies to everything you build. There are two ways to create one. The easy way is to let Summer write it. After you finish something you liked, tell it to remember how you did that, or say you always want it done this way. Summer drafts a skill and shows it to you in a card. Nothing is saved until you approve it, so you are always the one deciding what becomes a rule. The hands-on way is the skills editor. Open it from your avatar menu, go to Settings, and pick Skills. There you can read every built-in skill, customize one to fit your style, or write a new one from scratch. Customizing a built-in skill quietly replaces it with your version, and you can reset back to the original any time. ## How skills stay out of your way You might wonder whether a big library of skills slows Summer down or clutters its thinking. It does not. Summer only ever sees a short one-line summary of each skill by default, and reads the full guide only when it actually needs it. Your custom skills sit on top of the built-in ones, so when a skill of yours shares a name with a Summer default, yours wins. This is why you can teach Summer as much as you want without it getting confused or expensive. The knowledge is there when it is relevant and invisible when it is not. ## Skills and your team Skills are also how a team levels up together. One person works out the right way to build a boss fight or set up a shader, saves it as a skill, and now everyone building in that project gets the same quality. The senior's workflow becomes the whole team's baseline, without anyone having to remember it. ## Related Click nodes or draw on your viewport to build in the scene How Summer remembers your decisions across chats The team of agents that builds your game The skill library for external agents and the command line What Summer can do inside your project *** Need help or have questions? Reach out at [founders@summerengine.com](mailto:founders@summerengine.com) or join [Discord](https://discord.gg/yUpgtxnZky). # How Summer's AI Agents Build Your Game Source: https://docs.summerengine.com/ai-tools/subagents Summer Engine builds games with a team of AI agents. One agent plans and talks to you, specialist agents do the hands-on work, and you stay in charge of all of it. Here is how the team works and how to get the most out of it. Summer works a lot like a small game studio. You talk to one agent, and behind the scenes it hands the actual work to specialists. You never have to manage that team. You just describe the game you want, and the right people show up for the job. This page explains what that team looks like, why it is built this way, and how to steer it so you get better games faster. ## The agent you talk to Everything starts with the main agent. It is the one reading your messages, asking questions when something is unclear, and writing the plan for what to build next. Think of it as the lead on your project. The important thing to know is that the main agent spends most of its time thinking and directing, not typing out code itself. When you ask for a jump mechanic or a new enemy or a whole game, it works out what needs to happen, breaks it into pieces, and hands those pieces to the specialists best suited to each one. That keeps the planning focused and lets the hands-on work run cheaply and in parallel. You will sometimes see it stop to consult an advisor before committing to a plan. That is a good sign. It means the agent hit something tricky and wanted a second opinion before spending your credits building the wrong thing. ## The specialists Summer keeps a team of specialist agents, each shaped for one kind of work. You do not pick them. The main agent chooses based on the task, and often runs several at once. Here is the team in plain terms. **A researcher** reads your project and answers questions about it. When the main agent needs to know how something is wired before it changes anything, this is who it asks. Read only, fast, and cheap. **A builder** does the hands-on construction. It writes scripts, edits scenes, sets the main scene, binds input actions, and runs compile checks. When you ask for a new game or a feature slice, this is who builds it end to end. **An asset maker** creates art, models, audio, and animations, then hands them back for you to review before anything lands in your project. **A verifier** checks that things actually work. It traces the scene, scripts, and running game to confirm a feature does what it should, and reports back honestly when something is broken. **An advisor** is the one the main agent turns to when it is stuck or unsure. It reasons more carefully than the others and is happy to say when it does not know, which is exactly what you want from a second opinion. You can also use [Design Mode](/ai-tools/design-mode) to click nodes or draw on your 2D and 3D viewport while this team works. The viewport bar feeds into the same chat the orchestrator supervises. We keep the exact lineup and the models behind it flexible on purpose, because we are always improving it. What stays the same is the shape. A lead that plans, and specialists that execute. ## Work runs in parallel Because the specialists each keep their own focused context, Summer can run several of them at the same time. While one builds your player controller, another can be generating the enemy art, and a third can be researching how your save system works. None of them block the others, and none of them clutter your main chat with the details of their work. You get the finished results stitched back together, not the mess of getting there. ## You can watch them work When a specialist is running, you see it live in your chat as its own clean thread. You can follow what it is doing and thinking in real time without it taking over the conversation. When it finishes, it folds a short summary back into the main chat and the details stay tucked away in that thread if you ever want to look. This is the balance we care about. Full transparency when you want it, and a calm, uncluttered chat when you do not. ## Working with the team You do not manage the agents directly, but the way you talk to the main agent shapes how well the team performs. Be specific about what you want and why. The clearer your intent, the better the brief the main agent can write, and the better the specialists execute it. If you have a reference image or a particular feel in mind, say so early. If a specialist is heading in the wrong direction, tell the main agent. It supervises the work and can redirect a running specialist mid task, or stop one that has gone off the rails and start fresh with a better approach. You do not have to wait for a bad result to land before course correcting. And when something genuinely does not work, say that plainly. The verifier exists for exactly this, and the main agent would rather run a real check than take its own word for it. ## When Summer works alone Not everything needs the full team. For a quick single edit, a direct answer to a question, or a small tweak, the main agent just handles it. Delegation kicks in when the work is bigger than that. A multi step build, art generation, a wide search across your project, or anything that benefits from running several things at once. You never have to decide which path applies. Summer makes that call for you, and you can always nudge it either way. ## You approve anything risky Summer keeps you in control of the actions that matter. Pick a **permission mode** in the composer to set how much runs automatically. Manual approves every edit and generation. Accept edits auto-runs file changes but asks before spending credits. Auto approve (default) runs edits and generation but still blocks destructive actions. Bypass runs everything except hard safety blocks. Shell commands, file deletions, and credit-spending generation respect the mode you chose. The building and editing happen freely when you want speed, and the irreversible steps wait for you when you want control. ## Related Click nodes or draw on your viewport to build in the scene Teach Summer your way of building and reuse it across every project How Summer remembers your decisions across chats What Summer can do inside your project How Summer indexes and searches your project *** Need help or have questions? Reach out at [founders@summerengine.com](mailto:founders@summerengine.com) or join [Discord](https://discord.gg/yUpgtxnZky). # MCP API Reference Source: https://docs.summerengine.com/api-reference/mcp Summer Engine MCP API. Connect Cursor, Claude Code, Devin Desktop. Tools for scene, debug, project, assets, and generation. ## MCP API Reference Summer Engine's Model Context Protocol (MCP) integration is live. Connect Cursor, Claude Code, or Devin Desktop to control the engine from your IDE. Add nodes, set properties, import assets, run the game, and debug, all through natural language. Prerequisites, one-click Cursor install, manual config for any IDE ## What You Get * **Focused tools**: Scene manipulation, debugging, project settings, asset search, asset import, and generation * **Same operations as built-in chat**: AddNode, SetProp, SaveScene, ImportFromUrl. Identical behavior. * **Lazy connection**: MCP server starts when your IDE starts; connects to the engine on first tool call * **No API keys**: Engine uses local tokens. Run `summer login` once for account features. ## Quick Links Cursor setup: one-click or manual Claude Code MCP configuration CLI quick start All commands: install, run, create, mcp Every MCP tool with parameters AI agent playbook for building games *** [MCP overview](/mcp/overview) · [MCP setup](/mcp/setup) # Summer SDK Source: https://docs.summerengine.com/api-reference/summer-sdk The lifecycle hub for adding Summer SDK capabilities to a Summer game, testing locally, submitting for review, and updating. ## Add platform capabilities to your Summer game The **Summer SDK** is the creator-facing platform contract for a **Summer game**. Your GDScript owns the gameplay, worlds, rules, and presentation. The SDK documents multiplayer, player, persistence, economy, and submission interfaces. An interface being documented does not mean its hosted runtime is production-live. Use only the capabilities your game needs. Templates are examples, not requirements. ## Lifecycle Start from the minimal SummerGame lifecycle and manifest. Select player, teams, score, persistence, economy, UI, and audio surfaces. Use Summer Engine first and validate before spending a publish request. Produce a game-only pack and verify its digest and contents. Choose the API or browser path and follow the human review state. Keep the game identity stable, bump the version, retest, and resubmit. ## What is available now * Create a Summer game record. * Upload a game-only `.pck` directly to storage with server-side checksum verification. * Enter the manual human review queue. * Download releases through the authenticated release endpoint. ## What remains a contract or planned capability * Summer SDK lifecycle, player, sync, persistence, economy, teams, score, UI, and audio interfaces are a creator contract under implementation. * Player-facing browser and desktop-shell playback is not live. * Hosted dedicated game servers and automatic matchmaking are not live. * The automated production runtime sandbox is not live. * `SummerMultiplayerPeer` is a published compatibility contract still being built. See [Product source & platform status](/knowledge-base/source-status#platform-capability-status) for the single canonical status table. Do not infer deployment status from an SDK reference page or example. ## What You Build Your game remains responsible for its creative and gameplay layer: * **Core Gameplay:** Your unique mechanics, controls, and game loops. * **Worlds & Scenes:** Environments, levels, and visual rendering. * **Rules & Logic:** Win/loss conditions and genre-specific systems (whether that's 3D, 2D, RTS, card, or puzzle games). * **Presentation:** UI, audio, and overall game feel. ## Platform Contract The minimum integration contract: 1. `extends SummerGame` 2. implement lifecycle hooks (`_game_init`, `_game_start`, `_game_end`, `_player_joined`, `_player_left`) 3. use player synced state (`set_synced` / `get_synced`) 4. keep authority on server paths (`Summer.is_server()`) 5. provide valid `manifest.json` and export/upload flow. ## Templates Are Optional Templates are examples, not requirements. * `SummerCharacter3D` is the optional 3D character template path. * For 2D/RTS/card/turn-based games, extend `SummerPlayer` directly and sync your own game model. ## Capability and reference pages Point any AI coding agent at one prompt: build, export, and submit through the live API Migrating from Crafty: every renamed class, autoload, manifest key, and path Match control, player queries, spawning, server/client checks, subsystem access Required base class, lifecycle hooks, and practical game structure Minimal player contract: identity, synced vars, input, and optional 3D template path Optional platform modules: teams, score, data, economy, UI, audio, and signals Golden-path tutorial from blank project to .pck submission Full Coin Collector-style example with timer, collectibles, and scoring RPG/quest example with player saves, progression, and economy Teams, auto-balance, team spawns, and team scoring Extend SummerPlayer for 2D state sync and server-authoritative logic Sync turn order, hand/board state, and validate all actions on server Every field, required keys, and validated examples One linear path for fresh AI/dev sessions: integrate, test, export, submit Export .pck, scanner rules, upload flow, review lifecycle, and updates Summer Engine smoke checks, optional loopback testing, and the limits of local validation Game-only PCK export preset, upload pipeline, and update workflow Complete blocked pattern list, rationale, and safe alternatives Required file contract, banned API rules, and acceptance checklist for AI-generated games ## Versioning Games declare a `summer_sdk` version in `manifest.json`. SDK changes are intended to be additive and backward-compatible. Return to the minimal GDScript and manifest contract. Validate the Summer game with Summer Engine before export. # AI Agent Playbook Source: https://docs.summerengine.com/api-reference/summer-sdk/ai-agent-playbook Output contract for AI-generated Summer SDK integrations: Summer-first framing, required files, submission checks, and runtime-status limits. ## Why This Exists Fresh AI sessions must be able to generate code that: * conforms to the Summer SDK runtime contract, * passes static analysis + submission checks, * stays server-authoritative, * does not assume 3D template-only architecture. This page is the strict output contract. It does not claim that player-facing playback, hosted servers, matchmaking, or the production runtime sandbox is live. See [platform capability status](/knowledge-base/source-status#platform-capability-status). This page is the *output contract* (what generated code must look like). The *end-to-end instruction set* — build, validate, export, and publish through the live API — is the canonical agent prompt at [/agent-setup](/agent-setup), raw at `https://docs.summerengine.com/agent-setup/prompt.md`. Point agents there first. ## Platform-First Rule Treat Summercraft as a platform layer: * Build Summer game logic in Summer Engine. * Integrate `SummerGame` lifecycle + player synced state. * Use templates only when they fit the genre. Never frame the SDK as “3D framework required.” ## Required Output (Minimum Valid Pack) Generate these files: * `manifest.json` * `main.gd` (`extends SummerGame`) * `main.tscn` (`entry_scene`) * `player.tscn` (player root script) If any file is missing, output is invalid. ## Player Model Decision (Required) Pick one path explicitly: 1. **3D template path**: player root script is `SummerCharacter3D` 2. **Custom path**: player root script extends `SummerPlayer` and defines custom synced game model Do not mix assumptions from both paths. ## Required `manifest.json` Keys `manifest.json` must contain: * `id` (string) * `name` (string) * `version` (string) * `summer_sdk` (string, for now `"1.0"`) * `entry_scene` (string, for example `"main.tscn"`) * `min_players` (number) * `max_players` (number) Strongly recommended: * `player_scene` (string, for example `"player.tscn"`) If `player_scene` is present, it must point to a real scene in the project. ## Scene + Script Contract `main.gd` must: * extend `SummerGame` * implement: * `_game_init()` * `_game_start()` * `_game_end()` * `_player_joined(player)` * `_player_left(player)` * run authority logic server-side (`if not Summer.is_server(): return` in `_process` when needed) `main.tscn` should include: * a `SpawnPoints` node with at least 2 child spawn nodes for multiplayer testing * a `Players` node (recommended) `player.tscn` should: * use either: * `res://sdk/summer_character_3d.gd`, or * your own script that extends `SummerPlayer` * include collision + visible mesh so test runs are obvious ## Allowed vs Blocked APIs ### Allowed (use these) * Summer SDK systems (`Summer`, `SummerGame`, `SummerPlayer`, score/teams/data/economy APIs) * normal gameplay node logic (`Node`, `Node3D`, movement, physics, animation, signals) ### Blocked (never generate these in game scripts) * `OS.execute` * `OS.shell_open` * `OS.create_process` * `FileAccess` * `DirAccess` * `HTTPRequest` * `HTTPClient` * `JavaScriptBridge` * `ClassDB.instantiate` * `Thread.new` Reason: submission scanner blocks these patterns and upload fails. For the complete and current blocked-pattern set, see: * [Banned APIs Reference](/api-reference/summer-sdk/banned-apis-reference) ## Definition Of Done (AI Output) An AI-generated game is "done" only if all checks pass: 1. `manifest.json` has all required fields and valid types. 2. `entry_scene` exists and loads. 3. `player_scene` exists (if present) and loads. 4. Main script extends `SummerGame`. 5. Player path chosen explicitly (3D template or custom `SummerPlayer` subclass). 6. No blocked APIs appear in any `.gd` file. 7. Server-authoritative gameplay logic is on server paths. 8. Game can be exported to `.pck` and submitted through the [release API](/api-reference/summer-sdk/exporting-and-uploading-your-game) (release reaches `pending_review`). ## Safe Starter Prompt (for AI systems) The canonical, always-current agent prompt — including a verified project template, local validation steps, and the live publish calls — is served raw at: ```text theme={null} https://docs.summerengine.com/agent-setup/prompt.md ``` Use [/agent-setup](/agent-setup) to hand it to any agent. If you only need the generation rules inline: ```text theme={null} Create a minimal multiplayer Summer game with these files only: manifest.json, main.gd, main.tscn, player.tscn. Rules: - main.gd must extend SummerGame and implement all lifecycle hooks. - Include at least 4 spawn points in main.tscn. - Keep authoritative gameplay state on server paths only. - Multiplayer-native defaults: min_players 1, max_players 8. - Include player_scene in manifest.json and make sure it matches player.tscn. - Choose one player model: - 3D template: use SummerCharacter3D in player.tscn - custom model: extend SummerPlayer and sync game-specific state with set_synced/get_synced - DO NOT use blocked APIs: OS.execute, OS.shell_open, OS.create_process, FileAccess, DirAccess, HTTPRequest, HTTPClient, JavaScriptBridge, ClassDB.instantiate, Thread.new. - Target summer_sdk "1.0". ``` # Banned APIs Reference Source: https://docs.summerengine.com/api-reference/summer-sdk/banned-apis-reference Complete list of blocked APIs/patterns during Summercraft submission, with rationale and safer alternatives. ## Why These APIs Are Blocked Summercraft's submission policy is designed for creator code that may eventually run inside a shared production sandbox. The static scanner and human review enforce these boundaries today even though the automated production runtime sandbox is not live yet. To protect platform security and stability, submission blocks patterns that enable: * shell/process execution, * uncontrolled filesystem/network access, * runtime reflection/eval bypasses, * loading or embedding unsafe native/binary resources. ## Important: Scanner Is Pattern-Based If a blocked pattern appears in submitted source, upload fails, even when: * it is in an editor/debug branch, * it is inside dead code, * it is conditionally executed. ## Full Blocked Pattern List | Pattern | Why it is blocked | Use instead | | ------------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `OS.execute` | Executes arbitrary system commands on server hosts. | Use Summer SDK gameplay/data APIs. | | `OS.shell_open` | Opens external shells/URLs and escapes runtime boundaries. | Use in-game UI flow; no direct OS shell access. | | `OS.create_process` | Spawns unmanaged processes from game code. | Submitted packs cannot own process control; no production platform runtime is live yet. | | `OS.create_instance` | Creates new runtime instances outside allowed flow. | Use standard scene instantiation and SDK systems. | | `OS.kill` | Can terminate infrastructure or peer processes. | Use gameplay lifecycle APIs only. | | `FileAccess` | Unrestricted read/write to filesystem. | Target the scaffolded `Summer.data` contract; production persistence is not live yet. | | `DirAccess` | Directory traversal/manipulation on host filesystem. | Target the scaffolded `Summer.data` contract; production storage is not live yet. | | `HTTPRequest` | Arbitrary outbound HTTP from game logic. | Target the scaffolded `Summer.data` / `Summer.economy` contracts; their production backends are not live yet. | | `HTTPClient` | Low-level custom network egress from untrusted scripts. | Use SDK networking and platform endpoints only. | | `JavaScriptBridge` | Bridge escape to browser/JS runtime. | Keep logic in GDScript + SDK only. | | `ClassDB.instantiate` | Dynamic class loading can bypass allowed surfaces. | Instantiate explicit scene/resources you control. | | `Thread.new` | Unmanaged concurrency can impact determinism/stability. | Use deterministic main-loop gameplay logic. | | `Mutex.new` | Same as above, often paired with unsafe concurrency patterns. | Keep gameplay state updates on main thread. | | `Semaphore.new` | Same as above; can hide blocking/synchronization hazards. | Use frame/tick-driven state machines. | | `StreamPeerTCP` | Raw socket networking bypasses the platform contract. | Use the Summer SDK transport contract when the production path is available. | | `PacketPeerUDP` | Raw UDP bypasses platform-level auth/routing. | Use the Summer SDK transport and replication contract. | | `TCPServer` | Opens custom server sockets inside creator game scripts. | Keep server ownership outside the submitted game pack. | | `UDPServer` | Same as above for UDP. | Keep networking outside the submitted game pack. | | `WebSocketPeer` | Arbitrary socket communication channel. | Use the Summer SDK transport contract when available. | | `.call(` | Reflection can be used to bypass direct API checks. | Explicit method calls on known safe objects. | | `.callv(` | Same reflection bypass risk. | Explicit typed calls. | | `.call_deferred(` | Reflection/deferred execution can hide unsafe paths. | Use explicit logic flow and signals. | | `Callable(` | Dynamic invocation surface for bypass patterns. | Direct signal/method wiring with known methods. | | `Engine.get_singleton` | Accesses internal engine singletons outside approved API. | Use Summer SDK abstractions. | | `Expression.new` | Runtime expression eval can execute dynamic untrusted code. | Static, explicit gameplay logic. | | `Expression(` | Same runtime eval surface. | Static logic and pre-defined scripts. | | `Marshalls.base64_to_variant` | Unsafe/deserialization abuse vector for crafted payloads. | Use validated JSON and typed schema checks. | | `ResourceSaver` | Writes resource files at runtime; persistence boundary risk. | Target the scaffolded `Summer.data` contract; production persistence is not live yet. | | `ProjectSettings.load_resource_pack` | Runtime pack loading from game scripts is not allowed. | Pack loading belongs to a future runtime; no production loader is live yet. | | `get_node("/root` | Root traversal can reach infrastructure internals. | Use scoped scene tree access in your game subtree. | | `get_node(\"/root` | Same root traversal risk (escaped quote variant). | Use local node paths. | | `get_tree().root` | Global root access to internals outside game boundary. | Access only local game nodes and SDK APIs. | ## Reserved Paths (Blocked In .pck) Packs are rejected if they include infrastructure paths, including: * `res://sdk/` * `res://core/` * `res://server/` * `res://client/` * `res://official_games/` * `res://bootstrap.gd`, `res://bootstrap.tscn` * `res://project.godot` * `res://summer.cfg` * `res://export_presets.cfg` * `res://test_runner.gd`, `res://test_runner.tscn` ## Blocked Native/Binary Resource Extensions Packs are also rejected if they include: * `.gdextension` * `.so` * `.dll` * `.dylib` * `.framework` * `.res` ## Practical Guidance For AI-Generated Code When generating code from prompts: 1. Never generate “debug fallback” branches with blocked APIs. 2. Prefer SDK primitives (`Summer.data`, `Summer.economy`, score/teams/sync helpers). 3. Keep all file/network/process interactions out of creator game scripts. 4. Use explicit method calls instead of reflective invocation helpers. The alternatives in this table are contract guidance, not a deployment-status promise. Check [platform capability status](/knowledge-base/source-status#platform-capability-status) before promising hosting, matchmaking, transport, persistence, or economy behavior. ## Related Docs * [Exporting and Uploading Your Game](/api-reference/summer-sdk/exporting-and-uploading-your-game) * [Submission Guide](/api-reference/summer-sdk/submission-guide) * [AI Agent Playbook](/api-reference/summer-sdk/ai-agent-playbook) # Build Your First Summer Game Source: https://docs.summerengine.com/api-reference/summer-sdk/build-your-first-summer-game Build a multiplayer-native Summer game in GDScript with the Summer SDK, then continue to local testing and review. ## Multiplayer by default The Summer SDK contract is multiplayer-native. The default example is host-authoritative: the server runs the rules, clients render synced state, and a `min_players` of 1 means the same build is also a solo game. You write `SummerGame` hooks and synced state in GDScript; the Summer SDK defines the creator-facing contract. The SDK/runtime surfaces on this page are scaffolded, not a deployed hosted gameplay path. Check [platform capability status](/knowledge-base/source-status#platform-capability-status) before making production promises. What you build here: * extends `SummerGame`, * server-authoritative gameplay updates (`Summer.is_server()`), * player-visible state via `set_synced`, * 1–8 players from the same code path, * passes local testing and the submission pipeline. Want an AI agent to run this whole page for you? Point it at [/agent-setup](/agent-setup) — the prompt there contains a complete verified template (project files, local SDK stubs, export preset) and the publish calls. ## Step 1: Create `manifest.json` ```json theme={null} { "id": "first-summer-game", "name": "First Summer Game", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "main.tscn", "player_scene": "player.tscn", "min_players": 1, "max_players": 8 } ``` `min_players: 1, max_players: 8` is the multiplayer-native default — ship it unless your design demands otherwise. Paths are relative to the manifest at the pack root. ## Step 2: Choose Your Player Path ### 3D Action Template (fastest start) * set `player.tscn` root script to `res://sdk/summer_character_3d.gd` * use `apply_default_movement(...)` from `SummerGame`. ### Custom Genre Path (2D/card/RTS/puzzle) * make your own script extending `SummerPlayer` * sync your own state model (`set_synced("hand_count", ...)`, etc.). Either way the authority rule is identical: the server writes synced state, clients read it. ## Step 3: Build `main.gd` ```gdscript theme={null} extends SummerGame const ROUND_SECONDS := 120.0 const MOVE_SPEED := 7.0 const GRAVITY := 20.0 func get_prediction_params() -> Dictionary: return {"move_speed": MOVE_SPEED, "gravity": GRAVITY} func _game_init() -> void: var spawn_root := get_node_or_null("SpawnPoints") if spawn_root: for child in spawn_root.get_children(): if child is Node3D: spawn_points.append(child.global_position) func _game_start() -> void: Summer.set_time_limit(ROUND_SECONDS) Summer.send_announcement("Round started") func _game_end() -> void: Summer.send_announcement("Game over") func _player_joined(player) -> void: if player.has_method("respawn"): player.respawn(get_random_spawn_point()) player.set_synced("score", 0) func _player_left(_player) -> void: pass func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): if p.has_method("respawn"): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) ``` Give `main.tscn` a `SpawnPoints` node with at least 4 child `Node3D` spawn markers and a `Players` node — the multiplayer defaults assume them. ## Step 4: Add One Multiplayer Rule Example scoring rule — note it runs only on the server path, and clients see it through `set_synced`: ```gdscript theme={null} func score_point(player) -> void: var current := int(player.get_synced("score") if player.get_synced("score") != null else 0) current += 1 player.set_synced("score", current) Summer.send_announcement("%s scored (%d)" % [str(player.get("display_name")), current]) ``` ## Step 5: Local Test Start with the canonical one-process Summer Engine smoke checks. If your starter project includes the optional loopback runner, also use it to exercise a local server/client path: * the canonical agent prompt validates import, parsing, smoke execution, banned patterns, and pack contents with local SDK stubs; * the optional loopback runner starts a local headless server and connects a client to localhost; * neither path validates production platform services, ticket redemption, or hosted matchmaking. Guide: [Testing Your Game Locally](/api-reference/summer-sdk/testing-your-game-locally). Building outside Summer Engine (agent/CLI workflow)? The same page covers stub-based validation, and the [/agent-setup](/agent-setup) prompt automates it. ## Step 6: Export and Publish Export a game-only `.pck`, then publish it through the live release API (create game → presigned upload → server-verified finalize → manual review): * [Exporting and Uploading Your Game](/api-reference/summer-sdk/exporting-and-uploading-your-game) * [Submission Guide](/api-reference/summer-sdk/submission-guide) A human reviews every release. Approval assigns `published` catalog status and makes the release available under the documented authenticated download rules. Browser and desktop-shell play of uploaded Summer games are not live yet. ## What "Done" Looks Like * [ ] All lifecycle hooks implemented. * [ ] Server authority enforced (`Summer.is_server()`). * [ ] Player-visible state comes from `set_synced`. * [ ] Works with 1 player and with several (`min_players: 1`). * [ ] Canonical Summer Engine smoke checks pass. * [ ] Optional local loopback runner passes when present. * [ ] Export contains only game files; release enters `pending_review`. Return to project creation and the GDScript starting point. Use the lifecycle hub to select the SDK systems your game needs. # Export and Upload Your Summer Game Source: https://docs.summerengine.com/api-reference/summer-sdk/exporting-and-uploading-your-game Use Summer Engine to export a game-only .pck, then upload it through the live release API for human review. ## Goal Produce a `.pck` that contains only your game content, then submit it for review. There are two deployed submission paths: * **The release API** (this page, recommended — what agents and CI use): four HTTP calls against `https://summercraft.ai`, artifact limit 512 MiB. * **The browser submit page** at [summercraft.ai/submit](https://summercraft.ai/submit): upload `.pck` + `manifest.json` in the UI, artifact limit 2 GB, runs an automated static scanner at upload time. See [Submission Guide](/api-reference/summer-sdk/submission-guide). Both end in the same place: a human reviews the release before its catalog status can become `published`. No auto-publish, and no player-facing playback yet. Working agent-first? [/agent-setup](/agent-setup) has a paste-prompt that walks any coding agent through this entire page, including a verified project template. ## 1) Export a game-only .pck Use a preset that ships your game and nothing else: * name: `Summer Game PCK` * `export_filter="all_resources"` * `include_filter="manifest.json"` (non-resource files must be listed here) * `exclude_filter` covering infrastructure and local stubs (`sdk/*`, plus `core/*,server/*,client/*` if you develop inside the Summer Engine starter template) * `script_export_mode=0` — ship GDScript as readable text so review can read your source Export with the same Summer Engine executable used for local testing (no export templates are required for a pack export): ```bash theme={null} "$SUMMER_ENGINE" --headless --path . --export-pack "Summer Game PCK" game.pck ``` Checks after export: * `manifest.json` is at the pack root and current ([reference](/api-reference/summer-sdk/manifest-json-reference)), * the entry scene's root script `extends SummerGame`, * no [reserved paths or banned APIs](/api-reference/summer-sdk/banned-apis-reference) in the pack, * size between 1024 bytes and 536870912 bytes (512 MiB) for the API path. Then measure what you will declare: ```bash theme={null} shasum -a 256 game.pck # 64-char lowercase hex digest (Linux: sha256sum) wc -c game.pck # exact byte count ``` ## 2) Authentication Every endpoint accepts two forms, Bearer first: * `Authorization: Bearer ` — what agents, CI, and native clients use. See [/agent-setup](/agent-setup#the-one-thing-the-agent-cannot-do-sign-in) for how a signed-in human extracts their token. * The web session cookie — what the browser uses. A present-but-invalid Bearer token is a hard `401`; it never falls through to a cookie session. Tokens expire after about an hour. ## 3) Rate limits — read before calling Create-game, upload-url, and finalize each have **their own budget of 1 request per hour per account** (window and count are policy values and may widen). Order of checks is deliberate: validation and ownership run first, so a typo never spends your budget — but a successful call does. A `429` body tells you when to come back: ```json theme={null} { "error": "rate_limited", "detail": "…", "limit": 1, "windowSeconds": 3600, "retryAt": "2026-07-28T12:00:00.000Z" } ``` Validate everything locally before touching these endpoints. ## 4) `POST /api/games/engine` — create the game record Once per game, not per version. Creates a Summer game record (`kind: "engine"`) as metadata; the artifact arrives through the release endpoints. Request: ```json theme={null} { "name": "Hold the Hill", "slug": "hold-the-hill" } ``` * `name` required, 1–80 chars. `slug` optional: explicit slugs collide loudly (`409 slug_taken`); omitted, the server derives one from the name and walks around collisions. Success `201`: ```json theme={null} { "gameId": "9f0c1e6a-…", "slug": "hold-the-hill", "kind": "engine", "status": "draft", "uploadUrlEndpoint": "/api/games/9f0c1e6a-…/releases/upload-url" } ``` (`uploadUrlEndpoint` is included when the slug was derived.) Errors: `401 sign_in_required` · `400 invalid_request` · `409 slug_taken` · `429 rate_limited` · `502 create_failed`. ## 5) `POST /api/games/{gameId}/releases/upload-url` — mint the presigned PUT Declare exactly what you measured: ```json theme={null} { "version": "1.0.0", "sha256": "<64-char lowercase hex>", "sizeBytes": 10536 } ``` * `version`: 1–32 chars of `[A-Za-z0-9._-]`, first char alphanumeric, no `..`. Immutable once released. * `sha256`: lowercase hex, no `sha256:` prefix. * `sizeBytes`: positive integer, 1024–536870912. * `contentType` optional; if sent it must be `"application/octet-stream"`. Success `200`: ```json theme={null} { "uploadUrl": "https://…r2.cloudflarestorage.com/…", "method": "PUT", "headers": { "content-type": "application/octet-stream", "if-none-match": "*" }, "objectKey": "releases///.pck", "maxBytes": 536870912, "expiresAt": "…", "finalizeUrl": "/api/games//releases/finalize" } ``` * The URL expires after 1 hour. * **Both returned headers are folded into the URL's signature.** Send them verbatim on the PUT or storage answers `403 SignatureDoesNotMatch`. * `if-none-match: *` makes the object key **write-once**: a release artifact can never be swapped after it has been checksummed. A second PUT to the same key answers `412 Precondition Failed`. Errors: `401 sign_in_required` · `400 invalid_request` · `413 artifact_too_large` · `404 game_not_found_or_forbidden` (wrong id or not yours) · `409 not_a_godot_game` (web games publish via their own flow) · `409 version_exists` (bump the version) · `429 rate_limited` · `503 r2_not_configured` · `502 upload_url_failed`. ## 6) PUT the artifact to `uploadUrl` ```bash theme={null} curl -sS -X PUT "$UPLOAD_URL" \ -H "Content-Type: application/octet-stream" \ -H "If-None-Match: *" \ --data-binary @game.pck ``` Success is an empty `200`. No `Authorization` header — the presigned URL is the credential. `412` means the key already holds an object (see write-once above); if that object is the same verified artifact, skip to finalize. ## 7) `POST /api/games/{gameId}/releases/finalize` — server-verified record ```json theme={null} { "version": "1.0.0", "sha256": "", "changelog": "Initial release." } ``` Nothing you claim is trusted: the server checks its own presign-time intent record, HEADs the stored object, streams it through sha256, and compares digest and size against the declaration. Only then does a release row exist — and it is immutable from that moment. Success `201`: ```json theme={null} { "releaseId": "…", "gameId": "…", "version": "1.0.0", "sha256": "…", "sizeBytes": 10536, "pckUrl": "r2:///releases///.pck", "status": "pending_review", "adminNotified": true, "detail": "Release recorded and queued for review. It goes live when an admin approves it." } ``` The release is `pending_review`: it is available only to the owner and admins until an admin approves it and the game's active version moves. Approval changes catalog/download access; it does not make the game playable on the platform. On a `checksum_mismatch` or `size_mismatch` the stored object is deleted (so the write-once key is free again for a correct re-upload) and no row is written. Errors: `401 sign_in_required` · `400 invalid_request` · `404 game_not_found_or_forbidden` · `409 not_a_godot_game` · `409 no_upload_intent` (call upload-url first; declarations must match it exactly) · `409 artifact_missing` (the PUT never landed) · `413 artifact_too_large` · `400 size_mismatch` · `400 checksum_mismatch` · `409 version_exists` · `429 rate_limited` (its own budget) · `503 r2_not_configured` · `502 finalize_failed`. Errors are self-describing — `{ "error", "detail" }` where `detail` names the next action. Trust it. ## 8) `GET /api/games/{gameId}/releases/{version}/download-url` — verify what you shipped Auth required, never anonymous. The game's owner and admins can fetch any release, including pending ones; any other signed-in user only the approved release of a published game. Everything unauthorized answers `404` (not `403`), so release existence cannot be probed. Success `200`: ```json theme={null} { "url": "…", "sha256": "…", "sizeBytes": 10536, "version": "1.0.0", "releaseId": "…", "isActive": false, "expiresAt": "…" } ``` `url` is a presigned GET valid for \~5 minutes; `sha256` is read back from the content-addressed key so you can re-verify the bytes after download. ## 9) Review lifecycle 1. Finalize → release `pending_review`; the admin queue is pinged. 2. A human reviews. Approval re-verifies the stored bytes against the checksum pinned at finalize, then points the game's active version at the release and assigns `published` catalog status. Rejection records a reason, shown to you on [summercraft.ai/creator](https://summercraft.ai/creator); the previously approved catalog release stays active. 3. There is no automated publish, no runtime sandbox yet, and no guaranteed review time. **What approval does not (yet) mean:** browser play, desktop shell play, and hosted game servers for uploaded Summer games are not live. Approved releases are distributed through the authenticated download endpoint; play surfaces are in development. The canonical table is [platform capability status](/knowledge-base/source-status#platform-capability-status). ## 10) Updating your game Releases are immutable — updating means a new one: 1. Keep the same `gameId` (and `manifest.id`). 2. Bump `manifest.version`, and use that same new string as `version` in upload-url and finalize. 3. Re-export, then repeat steps 5–7. Each update goes through review again. Return to the Summer Engine validation loop. Choose a submission path and understand review states. # Guide: Making A 2D Game Multiplayer Source: https://docs.summerengine.com/api-reference/summer-sdk/guides/making-a-2d-game-multiplayer Integrate Summercraft into a 2D game by extending SummerPlayer and syncing your own state. ## Platform Framing You are building a 2D **Summer game** in **GDScript** and integrating the **Summer SDK** platform contract: * host-authoritative game rules and synced state, * player, data, economy, teams, and score interfaces, * a submission contract for review. The hosted multiplayer runtime, automatic matchmaking, and player-facing play surfaces are not production-live yet. See the canonical [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Recommended Player Model For 2D games, create your own 2D player class that extends `SummerPlayer`. ```gdscript theme={null} extends SummerPlayer @export var speed := 220.0 var local_position := Vector2.ZERO var is_alive := true func _ready() -> void: set_synced("x", local_position.x) set_synced("y", local_position.y) set_synced("anim", "idle") ``` ## Server Authority Loop ```gdscript theme={null} extends SummerGame func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): _step_2d_player(p, delta) func _step_2d_player(player, delta: float) -> void: var move: Vector2 = player.input.movement player.local_position += move.normalized() * player.speed * delta player.set_synced("x", player.local_position.x) player.set_synced("y", player.local_position.y) player.set_synced("anim", "run" if move.length() > 0 else "idle") ``` ## Client Render Pattern On clients, render from synced state: ```gdscript theme={null} func _process(_delta: float) -> void: var x = get_synced("x") var y = get_synced("y") if x != null and y != null: $Sprite2D.global_position = Vector2(float(x), float(y)) ``` ## Joining / Leaving ```gdscript theme={null} func _player_joined(player) -> void: player.set_synced("x", 0.0) player.set_synced("y", 0.0) player.set_synced("hp", 100) func _player_left(player) -> void: pass ``` ## Optional Subsystems Use only what you need: * `Summer.score` for score/rank, * `Summer.teams` for team modes, * `Summer.data` for persistent inventory/progress, * `Summer.economy` for currency. ## Common Mistakes * Running movement authority on clients. * Mutating score/economy from client paths. * Treating `set_synced` as client-owned state. ## Production Checklist (2D) * [ ] `Summer.is_server()` gates all authoritative state updates. * [ ] 2D state is synced via `set_synced`. * [ ] Client only renders synced values. * [ ] Required manifest fields valid. * [ ] Canonical Summer Engine smoke checks pass. * [ ] Optional local loopback runner passes when present. # Guide: Making A Turn-Based Or Card Game Multiplayer Source: https://docs.summerengine.com/api-reference/summer-sdk/guides/making-a-turn-based-or-card-game-multiplayer Use SummerPlayer synced state for turn order, hand data, board state, and authoritative turn actions. ## Platform Framing The Summer SDK contract supports turn-based and card-game models without requiring a 3D character template. The hosted runtime and player-facing play surfaces are not production-live yet. Use: * `SummerGame` for match lifecycle, * `SummerPlayer` for the future player-identity and synced-state shape, * `set_synced` for turn/board/hand summaries. No 3D character system is required. This is a scaffolded contract example; it does not run on a production hosted runtime today. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Minimal Player Setup ```gdscript theme={null} extends SummerPlayer func _ready() -> void: set_synced("hand_count", 0) set_synced("mana", 0) set_synced("ready", false) ``` ## Authoritative Turn State Store canonical game state on server: ```gdscript theme={null} extends SummerGame var _turn_order: Array = [] var _active_turn_index := 0 var _board_state := {} func _game_init() -> void: _board_state = {"round": 1, "stack_size": 0} func _player_joined(player) -> void: _turn_order.append(player) player.set_synced("hand_count", 5) player.set_synced("mana", 1) _sync_turn_state() func _player_left(player) -> void: _turn_order.erase(player) _active_turn_index = clamp(_active_turn_index, 0, max(_turn_order.size() - 1, 0)) _sync_turn_state() ``` ## Turn Progression ```gdscript theme={null} func end_turn(player) -> void: if not Summer.is_server(): return if _turn_order.is_empty(): return var active = _turn_order[_active_turn_index] if player != active: return _active_turn_index = (_active_turn_index + 1) % _turn_order.size() _board_state["round"] = int(_board_state.get("round", 1)) + 1 _sync_turn_state() func _sync_turn_state() -> void: for i in _turn_order.size(): var p = _turn_order[i] p.set_synced("turn_active", i == _active_turn_index) p.set_synced("round", _board_state.get("round", 1)) ``` ## Action Validation Pattern Every turn action should be server-validated: ```gdscript theme={null} func play_card(player, card_id: String, target_id: String) -> void: if not Summer.is_server(): return if _turn_order[_active_turn_index] != player: return if not _is_legal_card_play(player, card_id, target_id): return _apply_card_effect(player, card_id, target_id) _sync_turn_state() ``` ## What To Sync Sync only what clients need for rendering: * `turn_active` * `round` * `hand_count` * public board/stack data * timers or action windows Keep hidden/private data server-side unless intentionally exposed. ## Optional Platform Modules * `Summer.data`: persistent deck/profile/MMR. * `Summer.economy`: card packs, tournament entry, rewards. * `Summer.score`: ranked points or win tally. ## Production Checklist (Turn-Based/Card) * [ ] All turn actions validated server-side. * [ ] Synced state is minimal and intentional. * [ ] Hidden game information not leaked to all clients. * [ ] Join/leave logic preserves turn order safely. * [ ] Reconnect flow restores synced state correctly. # Game Guide: Multiplayer FFA (Coin Collector) Source: https://docs.summerengine.com/api-reference/summer-sdk/guides/multiplayer-ffa-coin-collector Build a 3D Summer game against the multiplayer SDK contract using the optional SummerCharacter3D template. ## What This Guide Covers This is a full `SummerGame` example for a multiplayer free-for-all: * Round timer * Collectible objects via `Summer.spawn_object` * Scoring via `Summer.score` * Announcements via `Summer.send_announcement` * End-of-round winner announcement This guide uses the optional 3D template path (`player.tscn` rooted with `SummerCharacter3D`). It demonstrates the SDK contract; it does not prove hosted runtime, matchmaking, or player-facing play deployment. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Scene Setup Create `coin_collector.tscn` with: * Root: `Node3D` (`CoinCollector`) * Child: `Node3D` (`SpawnPoints`) with multiple spawn transforms Create collectible scene `coin.tscn` (root script should extend `SummerObject`). ## Complete Game Script (`coin_collector.gd`) ```gdscript theme={null} extends SummerGame const MOVE_SPEED := 15.0 const GRAVITY := 20.0 const COIN_COUNT := 10 const COIN_RESPAWN_TIME := 5.0 const COINS_TO_WIN := 10 const ROUND_SECONDS := 90.0 var _coin_scene: PackedScene var _respawn_queue: Array[Dictionary] = [] func get_prediction_params() -> Dictionary: return {"move_speed": MOVE_SPEED, "gravity": GRAVITY} func _game_init() -> void: _coin_scene = load("res://coin.tscn") as PackedScene if not _coin_scene: push_error("[CoinCollector] Could not load coin scene") var spawn_node := get_node_or_null("SpawnPoints") if spawn_node: for child in spawn_node.get_children(): if child is Node3D: spawn_points.append(child.global_position) if spawn_points.is_empty(): spawn_points = [ Vector3(-20, 1, -20), Vector3(20, 1, -20), Vector3(-20, 1, 20), Vector3(20, 1, 20) ] func _game_start() -> void: Summer.set_time_limit(ROUND_SECONDS) Summer.object_collected.connect(_on_coin_collected) Summer.send_announcement("Collect %d coins to win" % COINS_TO_WIN) _spawn_initial_coins() func _game_end() -> void: if Summer.object_collected.is_connected(_on_coin_collected): Summer.object_collected.disconnect(_on_coin_collected) var leaderboard := Summer.score.get_leaderboard() if leaderboard.is_empty(): Summer.send_announcement("Round over: no winner") return var winner = leaderboard[0].player var score := int(leaderboard[0].score) Summer.send_announcement("%s wins with %d coins!" % [str(winner.get("display_name")), score]) func _player_joined(player) -> void: if player.has_method("respawn"): player.respawn(get_random_spawn_point()) Summer.score.set_score(player, 0) player.set_synced("score", 0) func _player_left(_player) -> void: pass func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) _tick_coin_respawns(delta) func _spawn_initial_coins() -> void: for i in range(COIN_COUNT): _spawn_coin_at(_random_coin_pos()) func _spawn_coin_at(pos: Vector3) -> void: if not _coin_scene: return var coin := Summer.spawn_object(_coin_scene, pos) if coin: coin.set_synced("active", true) func _random_coin_pos() -> Vector3: return Vector3( randf_range(-25.0, 25.0), 1.0, randf_range(-25.0, 25.0) ) func _tick_coin_respawns(delta: float) -> void: var i := 0 while i < _respawn_queue.size(): _respawn_queue[i].t -= delta if _respawn_queue[i].t <= 0.0: _spawn_coin_at(_respawn_queue[i].pos) _respawn_queue.remove_at(i) else: i += 1 func _on_coin_collected(player, _obj: SummerObject) -> void: Summer.score.add(player, 1) var score := Summer.score.get_score(player) player.set_synced("score", score) if score >= COINS_TO_WIN: end_game(false) return _respawn_queue.append({ "pos": _random_coin_pos(), "t": COIN_RESPAWN_TIME }) ``` ## If You Are Not Building A 3D Action Game Do not use this movement pattern. Use `SummerPlayer` directly and sync your own state model (for example turn state, board state, inventory, cursor targets). ## Suggested `manifest.json` ```json theme={null} { "id": "coin-collector", "name": "Coin Collector", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "coin_collector.tscn", "player_scene": "player.tscn", "min_players": 1, "max_players": 8, "tick_rate": 60, "description": "Collect coins before the timer expires.", "tags": ["ffa", "collect", "arcade"] } ``` # Contract Example: RPG Persistence and Economy Source: https://docs.summerengine.com/api-reference/summer-sdk/guides/multiplayer-persistence-rpg Author an RPG against the scaffolded Summer.data and Summer.economy interfaces without implying a live backend. ## What This Guide Covers This guide is a future-contract example for a persistent multiplayer game loop: * express player-data loads and saves, * model inventory, quest progress, and level, * issue periodic contract-level save calls, * model awards and spends through `Summer.economy`. There is no production gameplay runtime, persistence backend, economy rail, autosave, or backend flush for uploaded games today. This example is not executable proof of those services. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Input Actions Used Configure actions in your project/manifest: * `quest_complete` * `buy_potion` ## Complete Game Script (`quest_arena.gd`) ```gdscript theme={null} extends SummerGame const MOVE_SPEED := 7.0 const GRAVITY := 20.0 const AUTO_SAVE_INTERVAL := 15.0 const QUEST_XP_REWARD := 25 const QUEST_CRAFTIES_REWARD := 10 const POTION_COST := 8 var _auto_save_accum := 0.0 func get_prediction_params() -> Dictionary: return {"move_speed": MOVE_SPEED, "gravity": GRAVITY} func _game_init() -> void: var spawn_root := get_node_or_null("SpawnPoints") if spawn_root: for child in spawn_root.get_children(): if child is Node3D: spawn_points.append(child.global_position) if spawn_points.is_empty(): spawn_points = [ Vector3(-6, 1, -6), Vector3(6, 1, -6), Vector3(-6, 1, 6), Vector3(6, 1, 6) ] func _game_start() -> void: Summer.set_time_limit(1800.0) Summer.send_announcement("Quest Arena started") func _game_end() -> void: for p in get_players(): _save_player_snapshot(p) Summer.send_announcement("Quest Arena session saved") func _player_joined(player) -> void: if player.has_method("respawn"): player.respawn(get_random_spawn_point()) _load_player_snapshot(player) _sync_player_hud_fields(player) func _player_left(player) -> void: _save_player_snapshot(player) func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) _handle_player_actions(p) _auto_save_accum += delta if _auto_save_accum >= AUTO_SAVE_INTERVAL: _auto_save_accum = 0.0 for p in get_players(): _save_player_snapshot(p) func _handle_player_actions(player) -> void: if player.input.is_action_just_pressed("quest_complete"): _complete_quest(player) if player.input.is_action_just_pressed("buy_potion"): _buy_potion(player) func _complete_quest(player) -> void: var progress := Summer.data.load(player, "quest_progress") if progress == null: progress = {"main": 0} progress["main"] = int(progress.get("main", 0)) + 1 Summer.data.save(player, "quest_progress", progress) var xp := int(Summer.data.load(player, "xp") if Summer.data.load(player, "xp") != null else 0) xp += QUEST_XP_REWARD Summer.data.save(player, "xp", xp) var level := 1 + int(xp / 100) Summer.data.save(player, "level", level) var awarded := await Summer.economy.award(player, QUEST_CRAFTIES_REWARD, "quest_complete") if awarded: Summer.send_announcement("%s completed a quest (+%d crafties)" % [str(player.get("display_name")), QUEST_CRAFTIES_REWARD]) _sync_player_hud_fields(player) func _buy_potion(player) -> void: var purchased := await Summer.economy.spend(player, POTION_COST, "potion_purchase") if not purchased: Summer.send_announcement("%s cannot afford a potion" % str(player.get("display_name"))) return var inventory := Summer.data.load(player, "inventory") if inventory == null: inventory = {"potions": 0} inventory["potions"] = int(inventory.get("potions", 0)) + 1 Summer.data.save(player, "inventory", inventory) Summer.send_announcement("%s bought a potion" % str(player.get("display_name"))) _sync_player_hud_fields(player) func _load_player_snapshot(player) -> void: var level = Summer.data.load(player, "level") if level == null: level = 1 var xp = Summer.data.load(player, "xp") if xp == null: xp = 0 var inventory = Summer.data.load(player, "inventory") if inventory == null: inventory = {"potions": 0} var quest_progress = Summer.data.load(player, "quest_progress") if quest_progress == null: quest_progress = {"main": 0} Summer.data.save(player, "level", level) Summer.data.save(player, "xp", xp) Summer.data.save(player, "inventory", inventory) Summer.data.save(player, "quest_progress", quest_progress) func _save_player_snapshot(player) -> void: # Contract example only: no production persistence backend or flush is live. var level = Summer.data.load(player, "level") var xp = Summer.data.load(player, "xp") var inventory = Summer.data.load(player, "inventory") var quest_progress = Summer.data.load(player, "quest_progress") Summer.data.save(player, "level", 1 if level == null else level) Summer.data.save(player, "xp", 0 if xp == null else xp) Summer.data.save(player, "inventory", {"potions": 0} if inventory == null else inventory) Summer.data.save(player, "quest_progress", {"main": 0} if quest_progress == null else quest_progress) func _sync_player_hud_fields(player) -> void: var level := int(Summer.data.load(player, "level")) var xp := int(Summer.data.load(player, "xp")) var inventory := Summer.data.load(player, "inventory") var quest_progress := Summer.data.load(player, "quest_progress") var balance := await Summer.economy.get_balance(player) player.set_synced("level", level) player.set_synced("xp", xp) player.set_synced("potions", int(inventory.get("potions", 0))) player.set_synced("quest_main", int(quest_progress.get("main", 0))) player.set_synced("crafties", balance) ``` ## Suggested `manifest.json` ```json theme={null} { "id": "quest-arena", "name": "Quest Arena", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "quest_arena.tscn", "player_scene": "player.tscn", "min_players": 1, "max_players": 12, "tick_rate": 60, "description": "Persistent quest progression with economy rewards.", "tags": ["rpg", "quest", "persistence"], "input_actions": { "quest_complete": {"keyboard": "Q", "gamepad": "Y"}, "buy_potion": {"keyboard": "B", "gamepad": "X"} } } ``` # Contract Example: Team-Based Multiplayer Source: https://docs.summerengine.com/api-reference/summer-sdk/guides/team-based-game Author a team-mode model against the scaffolded Summer.teams and Summer.score interfaces. ## What This Guide Covers This guide illustrates a red-vs-blue team-mode contract: * Team creation with `Summer.teams.create` * Team assignment and auto-balance * Team-specific spawn points * Team score via `Summer.score.add_team` The hosted gameplay runtime, player connection flow, team service, and score service are not production-live. The code is an authoring example for scaffolded interfaces, not runtime proof. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Scene Setup Create `team_arena.tscn`: * Root `Node3D` named `TeamArena` * Child `Node3D` named `SpawnPointsRed` with several spawn transforms * Child `Node3D` named `SpawnPointsBlue` with several spawn transforms ## Complete Game Script (`team_arena.gd`) ```gdscript theme={null} extends SummerGame const MOVE_SPEED := 8.0 const GRAVITY := 20.0 const ROUND_SECONDS := 300.0 const TEAM_SCORE_TO_WIN := 15 const RED_GOAL_X_MIN := 22.0 const BLUE_GOAL_X_MAX := -22.0 var _red_spawns: Array[Vector3] = [] var _blue_spawns: Array[Vector3] = [] func get_prediction_params() -> Dictionary: return {"move_speed": MOVE_SPEED, "gravity": GRAVITY} func _game_init() -> void: Summer.teams.create("red", {"color": Color.RED, "max_size": 16}) Summer.teams.create("blue", {"color": Color.BLUE, "max_size": 16}) var red_root := get_node_or_null("SpawnPointsRed") if red_root: for child in red_root.get_children(): if child is Node3D: _red_spawns.append(child.global_position) var blue_root := get_node_or_null("SpawnPointsBlue") if blue_root: for child in blue_root.get_children(): if child is Node3D: _blue_spawns.append(child.global_position) if _red_spawns.is_empty(): _red_spawns = [Vector3(-15, 1, -8), Vector3(-15, 1, 8)] if _blue_spawns.is_empty(): _blue_spawns = [Vector3(15, 1, -8), Vector3(15, 1, 8)] func _game_start() -> void: Summer.teams.auto_balance() Summer.set_time_limit(ROUND_SECONDS) Summer.send_announcement("Red vs Blue started") func _game_end() -> void: var red_score := Summer.score.get_team("red") var blue_score := Summer.score.get_team("blue") if red_score > blue_score: Summer.send_announcement("Red wins %d - %d" % [red_score, blue_score]) elif blue_score > red_score: Summer.send_announcement("Blue wins %d - %d" % [blue_score, red_score]) else: Summer.send_announcement("Draw %d - %d" % [red_score, blue_score]) func _player_joined(player) -> void: var assigned := _assign_team(player) var spawn := _team_spawn_for(assigned) if player.has_method("respawn"): player.respawn(spawn) player.set_synced("team", assigned) func _player_left(player) -> void: Summer.teams.remove_player(player) func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) _check_goal_score(p) func _assign_team(player) -> String: var red_count := Summer.teams.get_members("red").size() var blue_count := Summer.teams.get_members("blue").size() var target := "red" if red_count <= blue_count else "blue" if not Summer.teams.assign(player, target): target = "blue" if target == "red" else "red" Summer.teams.assign(player, target) return target func _team_spawn_for(team_id: String) -> Vector3: if team_id == "red": return _red_spawns.pick_random() return _blue_spawns.pick_random() func _check_goal_score(player) -> void: var team_id := Summer.teams.get_team(player) if team_id == "": return if team_id == "red" and player.position.x >= RED_GOAL_X_MIN: _award_team_score("red", player) elif team_id == "blue" and player.position.x <= BLUE_GOAL_X_MAX: _award_team_score("blue", player) func _award_team_score(team_id: String, scorer) -> void: Summer.score.add_team(team_id, 1) var score := Summer.score.get_team(team_id) Summer.send_announcement("%s team scored (%d/%d) by %s" % [team_id.capitalize(), score, TEAM_SCORE_TO_WIN, str(scorer.get("display_name"))]) var current_team := Summer.teams.get_team(scorer) scorer.teleport(_team_spawn_for(current_team)) if score >= TEAM_SCORE_TO_WIN: end_game(false) ``` ## Genre Note This team model can be adapted for: * 3D objective shooters, * 2D objective games, * turn-based team tactics, * card games with team play. ## Suggested `manifest.json` ```json theme={null} { "id": "team-arena", "name": "Team Arena", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "team_arena.tscn", "player_scene": "player.tscn", "min_players": 2, "max_players": 16, "tick_rate": 60, "description": "Red vs Blue objective mode.", "tags": ["teams", "pvp", "objective"] } ``` # manifest.json Reference Source: https://docs.summerengine.com/api-reference/summer-sdk/manifest-json-reference Complete manifest.json field reference for Summer games submitted to Summercraft: required keys, optional keys, and validated examples. ## Overview Every Summer game submitted to Summercraft must include a `manifest.json` file at the root of the game pack. The browser submission flow validates required keys and types at upload time. The release API records and verifies the artifact; human review currently checks the game contract. The production runtime and automated sandbox are not live, so the runtime rules below are contract requirements rather than deployed enforcement: * `entry_scene` and `player_scene` are resolved **relative to the manifest's location** in the pack (manifest at the root means `"main.tscn"` → `res://main.tscn`). * The entry scene's root script must `extends SummerGame` for the future runtime contract. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Required Fields These fields are required by submission validation: | Field | Type | Required | Description | | ------------- | ------ | -------- | ----------------------------------------------------------------- | | `id` | string | Yes | Stable game identifier. Used for slug generation and updates. | | `name` | string | Yes | Display name shown in platform surfaces. | | `version` | string | Yes | Semantic or creator-defined version string (for example `1.0.0`). | | `summer_sdk` | string | Yes | SDK version your game targets (for example `1.0`). | | `entry_scene` | string | Yes | Main scene path/name designated for the runtime contract. | | `min_players` | number | Yes | Minimum players required before start flow. | | `max_players` | number | Yes | Maximum concurrent players for a match. | ## Optional Fields | Field | Type | Required | Description | | --------------- | --------- | -------- | --------------------------------------------------------------------- | | `player_scene` | string | No | Player scene path/name used by server/client spawning logic. | | `description` | string | No | Short game description. | | `tags` | string\[] | No | Category/search tags. | | `genre` | string | No | Primary genre label. | | `tick_rate` | number | No | Future server-sync hint; no production runtime currently consumes it. | | `preview` | string | No | Preview asset path/name for discovery UI. | | `input_actions` | object | No | Input action metadata for UX/docs tooling. | ## Minimal Valid Example ```json theme={null} { "id": "coin-collector", "name": "Coin Collector", "version": "1.0.0", "summer_sdk": "1.0", "entry_scene": "coin_collector.tscn", "min_players": 1, "max_players": 8 } ``` ## Full Example ```json theme={null} { "id": "quest-arena", "name": "Quest Arena", "version": "1.2.0", "summer_sdk": "1.0", "entry_scene": "quest_arena.tscn", "player_scene": "player.tscn", "min_players": 1, "max_players": 12, "tick_rate": 60, "description": "Persistent multiplayer quests and progression.", "preview": "preview.png", "genre": "rpg", "tags": ["rpg", "quest", "persistence"], "input_actions": { "quest_complete": {"keyboard": "Q", "gamepad": "Y"}, "buy_potion": {"keyboard": "B", "gamepad": "X"} } } ``` ## Validation Rules That Cause Rejection * Missing any required key * Wrong type for required string fields * `min_players` or `max_players` not numeric * Invalid JSON ## Versioning and Updates When you submit a new `.pck`: * Keep the same `id` for the same game * Increase `version` * Re-submit through the [publish flow](/api-reference/summer-sdk/exporting-and-uploading-your-game) On the API release path, use the manifest's `version` string as the release `version` too — it must match `[A-Za-z0-9][A-Za-z0-9._-]{0,31}` (no `..`), and released versions are immutable: an update is always a new version. The platform stores versions and routes review/publishing from your newest submission. # Summer SDK Naming Source: https://docs.summerengine.com/api-reference/summer-sdk/naming The Crafty to Summer symbol map: every renamed class, autoload, manifest key, and path, plus the identifiers that deliberately did not move. ## Why This Page Exists The platform used to be called Crafty. It is now **Summercraft**, and the thing you build against is the **Summer SDK**. The rename reached the code, not just the copy, so games written against the old names need a mechanical pass. This page is the single authority for what each old identifier became. If another document, comment, or older repository disagrees with the table below, the table wins. Names in this mapping define the SDK contract; they do not imply a live hosted runtime. See [platform capability status](/knowledge-base/source-status#platform-capability-status). Renaming is mechanical but not free. `summer_sdk` is a **required** manifest key and `SummerGame` is a **required** base class. A game that still declares `crafty_sdk` or extends `CraftyGame` fails submission validation rather than degrading quietly. ## Autoload Singleton | Old | New | Where | | --------------------- | --------------------- | ------------------------------------- | | `Crafty` | `Summer` | Autoload registered at `/root/Summer` | | `res://sdk/crafty.gd` | `res://sdk/summer.gd` | Autoload script path | `Summer` is the singleton defined by the Summercraft runtime contract for an approved Summer game. Production playback is not live yet, so “defined by the contract” is not a claim that uploaded games can currently launch. The singleton is unrelated to **Summer Engine**, the editor you build in — the two never appear in the same script. ## Classes Every SDK class drops the `Crafty` prefix for `Summer`. | Old | New | Documented in | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `CraftyGame` | `SummerGame` | [SummerGame](/api-reference/summer-sdk/summer-game) | | `CraftyPlayer` | `SummerPlayer` | [SummerPlayer](/api-reference/summer-sdk/summer-player) | | `CraftyCharacter3D` | `SummerCharacter3D` | [SummerPlayer](/api-reference/summer-sdk/summer-player), [Multiplayer FFA guide](/api-reference/summer-sdk/guides/multiplayer-ffa-coin-collector) | | `CraftyObject` | `SummerObject` | [Summer Singleton](/api-reference/summer-sdk/summer), [Multiplayer FFA guide](/api-reference/summer-sdk/guides/multiplayer-ffa-coin-collector) | | `CraftyNPC` | `SummerNPC` | [Summer Singleton](/api-reference/summer-sdk/summer) | | `CraftyTeams` | `SummerTeams` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyScore` | `SummerScore` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyData` | `SummerData` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyEconomy` | `SummerEconomy` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyUI` | `SummerUI` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyAudio` | `SummerAudio` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyInput` | `SummerInput` | [Subsystems and Signals](/api-reference/summer-sdk/subsystems-signals) | | `CraftyMCP` | `SummerMCP` | Not documented publicly | Subsystems are reached through the singleton (`Summer.teams`, `Summer.score`, `Summer.data`, `Summer.economy`, `Summer.ui`, `Summer.audio`, `Summer.input`). The handle names did not change — only the singleton in front of them. **Method names, signal names, and signatures are unchanged.** `set_synced`, `is_server()`, `player_killed`, and the rest all keep their names. ## Manifest, Config, and Paths | Old | New | Documented in | | ---------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `crafty_sdk` | `summer_sdk` | [manifest.json Reference](/api-reference/summer-sdk/manifest-json-reference) | | `res://crafty.cfg` | `res://summer.cfg` | [Banned APIs Reference](/api-reference/summer-sdk/banned-apis-reference) | | `res://sdk/crafty_character_3d.gd` | `res://sdk/summer_character_3d.gd` | [Build Your First Summercraft Game](/api-reference/summer-sdk/build-your-first-summer-game), [AI Agent Playbook](/api-reference/summer-sdk/ai-agent-playbook) | | `sdk/crafty_*.gd` | `sdk/summer_*.gd` | SDK source layout | ## Web Runtime The browser-side surface of the Summer SDK renames alongside a protocol version bump. The old names are removed rather than aliased. | Old | New | | -------------------------------------------------- | ------------------------------------------------ | | `crafty.webview.v1` | `summer.webview.v2` | | `playcrafty.preview` | `summer.preview.v2` | | `CraftyRuntime` | `SummerRuntime` | | `crafty-runtime.js` | `summer-runtime.js` | | `@playcrafty/game-kit` | `@summercraft/game-kit` | | `https://playcrafty.games/contracts/*.schema.json` | `https://summercraft.ai/contracts/*.schema.json` | There is no `v1` compatibility shim and no `CraftyRuntime` alias. A page still speaking `crafty.webview.v1` after the cutover is not talking to anything. **`v2` is a rename and a version bump, not a protocol redesign.** Message shapes are unchanged from `v1`, including the legacy normalization that still accepts a bare event name — `{type: "game_over"}` remains equivalent to `{type: "summer:event", event: "game_over"}`. If your game already spoke `v1` correctly, the only edit it needs is the protocol string and the runtime global. Nothing about how you construct or handle messages changes. ## Player Currency The in-game currency is **Crafties** (display name), `crafties` on the wire and in code. | Concept | Name | | ------------------------------ | ---------- | | Player currency, display | Crafties | | Player currency, wire and code | `crafties` | **"Credits" is not the player currency.** In Summer Engine, credits are the compute billing unit you spend on AI generation. The two never mix, and no balance is ever converted between them. If you are writing about something a *player* earns or spends inside a game, the word is crafties. Amounts passed to and returned from `Summer.economy` are crafties. Note that "credits" also appears in the docs in its ordinary English sense — crediting an asset's creator, and the in-game credits roll. Neither is a currency. ## Domains | Old | New | | ------------------ | ---------------- | | `playcrafty.games` | `summercraft.ai` | `summercraft.ai` is the canonical domain. `playcrafty.games` survives only as a legacy redirect, not as a second address for the same content. ## What Deliberately Did Not Move Not every `crafty` string is a branding leftover. These are load-bearing and stay as they are: * **`crafty-production-5a7c.up.railway.app`** — the deployed platform-api host that serves `POST /games/submit`. It is a Railway-generated hostname, it is what actually answers, and rewriting it in documentation would publish a submission endpoint that does not exist. It changes only if the service is redeployed under a new name. * **`crafty-game-server`** — the live Fly.io application name, which is also the base for the game-server image tag and its `.fly.dev` hostname. Same reasoning: an app name is a deployed identity, not a label. * **`c`-prefixed database tables** (`cFeedItems`, `cGamePublicStats`, and siblings) — internal, invisible to creators, and renaming them would churn every policy, view, and foreign key for no user-visible gain. * **The `games.playcrafty.mobile` bundle id** — app-store identity cannot be renamed in place on an existing listing. The rule these share: a name that some live system resolves is not copy, and it moves only when that system moves. # Production Launch Runbook Source: https://docs.summerengine.com/api-reference/summer-sdk/production-launch-runbook Single linear runbook for fresh AI/dev sessions: integrate the SDK contract, validate locally, export safely, and submit for review. ## Use This When You Need A Reliable End-To-End Path This page is the shortest safe route from “new game” to “submitted for review.” ## Current Publishing Checklist (Most Important) * Build your creator gameplay scripts in `GDScript` for the current Summercraft publishing flow. * **Recommended release API:** submit a game-only `.pck` containing `manifest.json`; size must be 1 KiB–512 MiB. * **Browser submission:** upload the `.pck` and a separate `manifest.json`; the browser path accepts up to 2 GB and runs the static scanner at upload time. * Choose one path before exporting. A 2 GB browser limit does not raise the release API's 512 MiB limit. ## Step 1: Validate Project Contract * `main.gd` extends `SummerGame`. * `manifest.json` includes required keys. * `player_scene` points to a valid scene. * gameplay scripts are authored in `GDScript`. * choose player model: * `SummerCharacter3D` (3D template), or * custom script extending `SummerPlayer`. ## Step 2: Validate Authority Boundaries * gameplay outcomes run under `if not Summer.is_server(): return`. * clients render synced state (`get_synced`) only. * no score/economy/data writes on client paths. ## Step 3: Validate Scanner Safety * no blocked APIs in scripts/resources. * no reserved infrastructure paths in export scope. * no blocked binary/native resource extensions in pack. Reference: * [/api-reference/summer-sdk/banned-apis-reference](/api-reference/summer-sdk/banned-apis-reference) ## Step 4: Local Runtime Validation Run the canonical Summer Engine smoke checks. If the starter project includes the optional loopback runner, run that separately and confirm: * local server starts + local client connects, * player join/leave stable, * gameplay loop runs for 10+ minutes, * reconnect path works. This is local loopback validation only. It does not prove production ticket redemption, platform hosting, matchmaking, or the runtime sandbox. Reference: * [/api-reference/summer-sdk/testing-your-game-locally](/api-reference/summer-sdk/testing-your-game-locally) ## Step 5: Export Validation * use game-only `.pck` preset. * update include filter to game folder. * confirm exported `.pck` includes only intended content. * for the recommended release API, confirm package size is 1 KiB–512 MiB and that `manifest.json` is inside the pack; * for browser submission, confirm the `.pck` is at most 2 GB and keep the matching `manifest.json` as the second upload; * if neither path fits, contact [founders@summerengine.com](mailto:founders@summerengine.com) before spending a submission attempt. Reference: * [/api-reference/summer-sdk/exporting-and-uploading-your-game](/api-reference/summer-sdk/exporting-and-uploading-your-game) ## Step 6: Submission Validation Choose one submission path: * **Release API:** create game → mint upload URL → PUT `.pck` → finalize; expect `pending_review`. * **Browser:** upload `.pck` + separate `manifest.json`; expect status `review`, a submission id, and no static-analysis violations. Neither path makes the game playable. Follow the canonical [platform capability status](/knowledge-base/source-status#platform-capability-status). Reference: * [/api-reference/summer-sdk/submission-guide](/api-reference/summer-sdk/submission-guide) ## Top 10 Failure Modes (And Fixes) 1. **`entry_scene` invalid** * Fix `manifest.json` path and re-export. 2. **`player_scene` invalid** * Fix scene path, confirm script setup, re-export. 3. **Client-authoritative logic** * Move outcome logic to server path. 4. **Missing synced fields** * Use `set_synced` for client-visible state. 5. **Scanner blocked pattern** * Remove blocked API usage. 6. **Reserved path in pack** * Correct include/exclude export filters. 7. **File too large** * Optimize assets and remove unused files. 8. **Manifest type mismatch** * Enforce required key types. 9. **Template mismatch** * 3D helper methods used without `SummerCharacter3D`. 10. **Reconnect instability** * Reinitialize player synced state on join. ## Launch Ready Criteria * [ ] Contract checks pass * [ ] Authority checks pass * [ ] Scanner checks pass * [ ] Local runtime checks pass * [ ] Export checks pass * [ ] Submission accepted into review If all are true, the build is ready for production review launch. # Submit Your Summer Game for Review Source: https://docs.summerengine.com/api-reference/summer-sdk/submission-guide Choose a deployed submission path for a Summer game, understand validation and human review, then follow the update loop. ## Before you submit * Creator gameplay scripts authored in GDScript * Valid [`manifest.json`](/api-reference/summer-sdk/manifest-json-reference) at the pack root * Entry scene root `extends SummerGame` * No [banned APIs or reserved paths](/api-reference/summer-sdk/banned-apis-reference) * [Local testing](/api-reference/summer-sdk/testing-your-game-locally) passes ## The two deployed submission paths ### Path A — the release API (recommended; agents and CI) Four JSON/HTTP calls against `https://summercraft.ai`: create game → presigned upload URL → PUT the `.pck` → finalize with server-side sha256 verification. Artifact limits: 1024 bytes – 512 MiB. Each write step is limited to 1 request per hour per account. Full request/response reference: [Exporting and Uploading Your Game](/api-reference/summer-sdk/exporting-and-uploading-your-game). Agent bootstrap: [/agent-setup](/agent-setup). ### Path B — the browser submit page Go to [summercraft.ai/submit](https://summercraft.ai/submit) signed in, and upload two files: * the `.pck` (multipart field `pck`) * `manifest.json` (multipart field `manifest`, file or JSON text) The page posts a multipart request to the platform API: ```bash theme={null} curl -X POST "https://crafty-production-5a7c.up.railway.app/games/submit" \ -H "Authorization: Bearer " \ -F "pck=@./game.pck" \ -F "manifest=@./manifest.json;type=application/json" ``` (The Railway hostname is the deployed platform-api identity — it is correct as written.) This path validates at upload time: * auth and creator identity, * required manifest fields and basic typing, * max upload size (2 GB on this path), * **automated static analysis** of `.gd` files and scripts embedded in `.tscn`/`.tres`: banned APIs, reserved paths, blocked binary/native extensions. Failures return `error: "Static analysis failed"` with a `violations` list (file, line, pattern). On success it returns `ok: true`, `gameId`, `submissionId`, `status: "review"`. The static scanner is pattern-based. A banned API inside a dead branch, an editor-only check, or a comment-adjacent string still fails. Do not generate "fallback" code paths that use blocked APIs. On Path A there is no automated scanner at upload time — the same rules are enforced by human review instead, so a violation costs you a review round-trip rather than an instant error. ## Review lifecycle — both paths Every submission is reviewed by a human. No auto-publish. | State | Meaning | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `draft` | Game record exists, nothing submitted or approved yet | | `pending_review` / `review` | A release/submission is in the admin queue | | `published` | Approved catalog state — the release is active and downloadable under the documented access rules, but not yet playable on the platform | | `rejected` | Rejected with a written reason, shown to you on [summercraft.ai/creator](https://summercraft.ai/creator) | On Path A, approval re-verifies the stored artifact against the checksum pinned at finalize before the game's active version moves — verification at upload is not trusted at approval time. A rejected update leaves the previously approved catalog release active. **Honest status:** approval publishes your game on the platform and makes its release downloadable through the authenticated [download endpoint](/api-reference/summer-sdk/exporting-and-uploading-your-game). Playing uploaded Summer games in the browser or desktop shell, and hosted dedicated game servers, automatic matchmaking, and the runtime sandbox are not live yet — do not tell players otherwise. See the canonical [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Updating an existing game Released versions are immutable. 1. Keep `manifest.id` (and on Path A the `gameId`) stable. 2. Bump `manifest.version`; on Path A pass the same new version string to upload-url and finalize. 3. Re-export and re-submit. Each update goes through review again. The previously approved catalog release stays active while its update waits. ## Common submission errors Path A errors are self-describing JSON (`{ "error", "detail" }`) — the `detail` names the fix. The full table is in [Exporting and Uploading](/api-reference/summer-sdk/exporting-and-uploading-your-game). Path B errors: * `Missing .pck file (multipart field: pck)` * `Uploaded file must be a .pck` * `PCK file too large (... max 2GB)` — trim assets, or contact [founders@summerengine.com](mailto:founders@summerengine.com) for large-upload onboarding * `Invalid manifest. Required: id, name, version, summer_sdk, entry_scene, min_players, max_players` * `Static analysis failed` (with violations list) Return to pack creation and the release API reference. Keep the identity stable, bump the version, retest, and resubmit. # Subsystems and Signals Source: https://docs.summerengine.com/api-reference/summer-sdk/subsystems-signals Optional platform modules (teams, score, data, economy, UI, audio, input) and runtime signals. ## What Are Subsystems? Subsystems are optional tools. Use only what your game needs. This is the core platform framing: * your game logic stays yours, * Summer SDK subsystems define multiplayer/platform interfaces. These are contract reference examples. The hosted gameplay runtime, persistence/economy rail, matchmaking, and dedicated servers are not production-live yet. Check [platform capability status](/knowledge-base/source-status#platform-capability-status) before treating a documented method as a deployed hosted service. ## Teams ```gdscript theme={null} Summer.teams.create("red", {"color": Color.RED, "max_size": 4}) Summer.teams.create("blue", {"color": Color.BLUE, "max_size": 4}) Summer.teams.assign(player, "red") var team = Summer.teams.get_team(player) var members = Summer.teams.get_members("red") Summer.teams.auto_balance() ``` Methods: * `create(team_id: String, config: Dictionary) -> void` * `assign(player, team_id: String) -> bool` * `remove_player(player) -> void` * `get_team(player) -> String` * `get_members(team_id: String) -> Array` * `auto_balance() -> void` ## Score ```gdscript theme={null} Summer.score.add(player, 1) Summer.score.set_score(player, 12) var score = Summer.score.get_score(player) var leaderboard = Summer.score.get_leaderboard() Summer.score.add_team("red", 2) var team_score = Summer.score.get_team("red") ``` Methods: * `add(player, points: int) -> void` * `set_score(player, points: int) -> void` * `get_score(player) -> int` * `get_leaderboard() -> Array` * `add_team(team_id: String, points: int) -> void` * `get_team(team_id: String) -> int` ## Data Persistent player data: ```gdscript theme={null} Summer.data.save(player, "level", 5) var level = Summer.data.load(player, "level") var all_data = Summer.data.load_all(player) Summer.data.delete(player, "legacy_key") ``` Methods: * `save(player, key: String, value: Variant) -> void` * `load(player, key: String) -> Variant` * `load_all(player) -> Dictionary` * `delete(player, key: String) -> void` ## Economy ```gdscript theme={null} var awarded = await Summer.economy.award(player, 5, "match_win") var spent = await Summer.economy.spend(player, 3, "buy_hint") var balance = await Summer.economy.get_balance(player) var can_pay = await Summer.economy.has_balance(player, 10) ``` Methods: * `get_balance(player) -> int` * `award(player, amount: int, reason: String) -> bool` * `spend(player, amount: int, reason: String) -> bool` * `has_balance(player, amount: int) -> bool` ## UI ```gdscript theme={null} Summer.ui.show_scoreboard() Summer.ui.hide_scoreboard() Summer.ui.show_timer(60) Summer.ui.show_announcement("Final minute!", 3.0) Summer.ui.show_kill_feed(killer, victim) ``` Optional helper UI. Creators can still build fully custom UI. ## Audio ```gdscript theme={null} Summer.audio.play_at(sound, Vector3(0, 1, 0)) Summer.audio.play_global(sound) Summer.audio.play_for(player, sound) ``` ## Input `Summer.input` and per-player `player.input` provide server-readable control state. Use server-authoritative checks for outcomes. ## Signals (Gameplay Events) Connect game logic to platform gameplay signals: ```gdscript theme={null} Summer.player_killed.connect(_on_player_killed) Summer.player_damaged.connect(_on_player_damaged) Summer.player_respawned.connect(_on_player_respawned) Summer.timer_expired.connect(_on_timer_expired) Summer.object_collected.connect(_on_object_collected) Summer.npc_killed.connect(_on_npc_killed) Summer.return_to_hub_requested.connect(_on_return_to_hub_requested) Summer.play_again_requested.connect(_on_play_again_requested) ``` Available signals: * `player_killed` * `player_damaged` * `player_respawned` * `timer_expired` * `object_collected` * `npc_killed` * `return_to_hub_requested` * `play_again_requested` ## Production Notes * Connect/disconnect signals in predictable lifecycle points. * Keep score/data/economy mutations on server paths. * Treat UI/audio helpers as optional convenience, not hard dependencies. # Summer Singleton Contract Source: https://docs.summerengine.com/api-reference/summer-sdk/summer Scaffolded Summer SDK entrypoint for lifecycle helpers, players, spawning, context checks, and subsystem interfaces. ## What Is `Summer`? `Summer` is the autoload singleton defined by the Summer SDK contract. The methods below are scaffolded interface examples. Uploaded games cannot currently launch in a production platform runtime, and hosted multiplayer, persistence, economy, matchmaking, and sandboxing are not live. Use this page to author against the future contract, not as evidence that a hosted service exists. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## `Summer` vs Player Object * Use `Summer` for match-wide actions (timer, announcements, spawning, subsystem access). * Use the player object (`SummerPlayer` or `SummerCharacter3D`) for per-player synced state and input. ## Core Methods (Signatures) ```gdscript theme={null} end_game() -> void set_time_limit(seconds: float) -> void get_time_remaining() -> float get_players() -> Array get_player_count() -> int get_max_players() -> int send_announcement(text: String) -> void spawn_npc(scene: PackedScene, position: Vector3) -> SummerNPC spawn_object(scene: PackedScene, position: Vector3) -> SummerObject spawn_projectile(scene: PackedScene, origin: Vector3, direction: Vector3, speed: float) -> SummerObject is_server() -> bool is_client() -> bool ``` ## Match Flow ```gdscript theme={null} Summer.set_time_limit(300) Summer.send_announcement("Round started") if Summer.get_time_remaining() <= 0.0: Summer.end_game() ``` ## Players ```gdscript theme={null} var players = Summer.get_players() var current = Summer.get_player_count() var max_players = Summer.get_max_players() ``` ## Announcements ```gdscript theme={null} Summer.send_announcement("Sudden death starts now!") ``` ## Spawning ```gdscript theme={null} var npc = Summer.spawn_npc(npc_scene, Vector3(0, 0, 0)) var pickup = Summer.spawn_object(pickup_scene, Vector3(2, 0, 2)) var projectile = Summer.spawn_projectile(bullet_scene, origin, direction, 30.0) ``` ## Runtime Context ```gdscript theme={null} if Summer.is_server(): # scoring, persistence, win conditions update_game_state() ``` The contract uses `is_server()` and `is_client()` to express server authority. Local stubs and loopback tests do not prove production authority enforcement. ## Subsystems The `Summer` contract defines optional subsystem handles: * `Summer.teams` * `Summer.score` * `Summer.data` * `Summer.economy` * `Summer.ui` * `Summer.audio` * `Summer.input` See `/api-reference/summer-sdk/subsystems-signals` for subsystem APIs. # SummerGame Source: https://docs.summerengine.com/api-reference/summer-sdk/summer-game Required base class for the Summer SDK game-lifecycle contract. ## What Is `SummerGame`? Every Summer game submitted through the Summer SDK contract must extend `SummerGame`. `SummerGame` is the contract between your game and the platform: * game lifecycle, * player join/leave callbacks, * timer/match control helpers, * server-authoritative movement helper for 3D templates. This page documents an interface, not production deployment status. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ```gdscript theme={null} extends SummerGame ``` ## Required Lifecycle Hooks Override these in your game script: ```gdscript theme={null} func _game_init() -> void: pass func _game_start() -> void: pass func _game_end() -> void: pass func _player_joined(player) -> void: pass func _player_left(player) -> void: pass ``` Use untyped `player` for maximum compatibility across: * `SummerCharacter3D` players (3D action template), * custom `SummerPlayer` subclasses (2D/RTS/card/turn-based). ## Common Platform Methods On `SummerGame` ```gdscript theme={null} end_game(from_timer: bool = false) -> void set_time_limit(seconds: float) -> void get_time_remaining() -> float get_players() -> Array get_player_count() -> int get_max_players() -> int get_random_spawn_point() -> Vector3 apply_default_movement(player, delta, move_speed := 7.0, gravity := 20.0) -> void ``` ## Hook Responsibilities * `_game_init()`: one-time setup (spawn points, static data, signal wiring). * `_game_start()`: begin active match flow. * `_game_end()`: finalize and cleanup. * `_player_joined(player)`: future-runtime hook for attaching defaults when a player joins. * `_player_left(player)`: cleanup per-player transient state. ## Server-Authoritative Pattern ```gdscript theme={null} func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return # authoritative gameplay logic here ``` ## 3D Template Pattern (Optional) If your player scene uses `SummerCharacter3D`, you can use the built-in movement helper: ```gdscript theme={null} const MOVE_SPEED := 8.0 const GRAVITY := 20.0 func _process(delta: float) -> void: super._process(delta) if not Summer.is_server(): return for p in get_players(): apply_default_movement(p, delta, MOVE_SPEED, GRAVITY) ``` For non-3D games, ignore `apply_default_movement` and implement your own state model with `set_synced`. ## Minimal Example ```gdscript theme={null} extends SummerGame func _game_start() -> void: Summer.set_time_limit(180.0) Summer.send_announcement("Match started") func _player_joined(player) -> void: player.set_synced("score", 0) ``` # SummerPlayer Contract Source: https://docs.summerengine.com/api-reference/summer-sdk/summer-player Scaffolded player interface for peer identity, synced state, and server-read input, plus an optional SummerCharacter3D template. ## What Is `SummerPlayer`? `SummerPlayer` is the scaffolded platform contract for a future connected-player record. The production gameplay runtime and transport are not live, so the signatures below are authoring targets rather than deployed connection behavior. See [platform capability status](/knowledge-base/source-status#platform-capability-status). It is intentionally game-agnostic: * no required 3D movement model, * no required health model, * no required scene structure. The contract is intended to support card games, RTS, 2D games, and 3D action games without forcing one movement model. ## Core Contract (Signatures) ```gdscript theme={null} # identity peer_id: int player_id: String display_name: String avatar: Dictionary # custom synced vars (server writes, clients read) set_synced(key: String, value: Variant) -> void get_synced(key: String) -> Variant ``` ## Identity The future runtime contract assigns identity fields during connection: ```gdscript theme={null} var peer = player.peer_id var id = player.player_id var name = player.display_name var avatar = player.avatar ``` * `peer_id: int` * `player_id: String` * `display_name: String` * `avatar: Dictionary` ## Custom Synced Variables `set_synced` and `get_synced` are the core data sync mechanism. Use them for any gameplay data your clients need: * card hand summaries, * turn state, * unit stats, * score, * custom RPG state. ```gdscript theme={null} player.set_synced("score", 10) # server path player.set_synced("hand_count", 5) # server path player.set_synced("turn_active", true) # server path var score = player.get_synced("score") # client or server ``` * `set_synced(key: String, value: Variant) -> void` * `get_synced(key: String) -> Variant` Keep authoritative game logic on server paths (`Summer.is_server()`). Clients should render synced state, not decide outcomes. ## Input (Read On Server) The future runtime contract gives a connected player an input proxy for server-side reads: ```gdscript theme={null} var move = player.input.movement var look = player.input.look_direction if player.input.is_action_just_pressed("interact"): handle_interact(player) ``` * `player.input.movement -> Vector2` * `player.input.look_direction -> Vector2` * `player.input.is_action_pressed(action: String) -> bool` * `player.input.is_action_just_pressed(action: String) -> bool` ## `SummerCharacter3D` (Optional 3D Template) For 3D action games, use `SummerCharacter3D` in your `player.tscn`. The template contract includes: * `CharacterBody3D` movement-compatible node type, * health fields (`health`, `max_health`, `is_alive`), * helpers (`respawn`, `damage`, `heal`, `kill`, `teleport`), * same synced API (`set_synced` / `get_synced`). Example: ```gdscript theme={null} func _player_joined(player) -> void: if player.has_method("respawn"): player.respawn(get_random_spawn_point()) ``` ## Practical Rule If your game needs built-in 3D character behavior, use `SummerCharacter3D`. If your game is not a 3D character game, extend `SummerPlayer` directly and sync your own state model. # Test Your Summer Game Locally Source: https://docs.summerengine.com/api-reference/summer-sdk/testing-your-game-locally Use Summer Engine smoke checks and an optional local loopback runner; understand what neither path proves about production. ## Why This Matters Local testing should match production behavior as closely as possible. The canonical agent workflow exercises: * Summer Engine, * local Summer SDK stubs, * project import, parsing, smoke execution, banned-pattern checks, and pack contents. It does **not** exercise the production Summer SDK runtime, ticket redemption, platform services, or a destination game server. The separate starter-template loopback runner can exercise a local server/client path, but it still does not prove those production paths. See [platform capability status](/knowledge-base/source-status#platform-capability-status). ## Optional starter-template loopback workflow If your Summer Engine starter project includes its loopback runner: * `test_runner.gd` launches a headless server process. * It waits for startup. * It launches/loads the client flow and connects to `localhost:7777`. This gives you a local multiplayer loop. It does not connect to Summercraft, redeem a launch ticket, or validate hosted matchmaking, hosting, or sandboxing. Use the loopback runner when it is present, but report it as local loopback validation, not production-like or end-to-end platform validation. ## Agent and CLI workflow with Summer Engine The [/agent-setup](/agent-setup) prompt installs and invokes Summer Engine directly, supplies local SDK stubs for parsing, and runs a single-process import/smoke pass plus banned-API and pack-content checks. It does not invoke the starter-template loopback runner. 1. Keep local **SDK stubs** in `sdk/` and exclude them from export. 2. Run Summer Engine headlessly and fail on any `SCRIPT ERROR`. 3. Check game scripts against the [blocked pattern list](/api-reference/summer-sdk/banned-apis-reference). 4. Export and confirm the `.pck` contains only game files plus `manifest.json`. This validates structure, parsing, and packaging — not gameplay against a production Summer SDK runtime. Review is currently human; uploaded games are not executed by a production runtime or automated sandbox. Treat the smoke run as a structural floor, not platform or gameplay proof. ## Advanced compatibility escape hatch On locked CI infrastructure where Summer Engine cannot be installed, an operator may supply a bare upstream Godot binary for syntax, import, and pack-format checks. This is an advanced compatibility path, not creator onboarding: * match the **current upstream base** shown in the [generated compatibility reference](/reference/compatibility); * do not treat that number as a Summer Engine product version or a measured project minimum; * set `UPSTREAM_ENGINE` explicitly rather than silently falling back from Summer Engine; * do not claim this validates Summer SDK runtime behavior. ```bash theme={null} "$UPSTREAM_ENGINE" --headless --path . --quit-after 120 ``` ## What the optional loopback runner does When you run a starter project that includes the loopback runner: 1. The runner detects your game slug from `manifest.json`. 2. It starts Summer Engine in headless mode with server args: * `--server` * `--game-id ` * `--port 7777` 3. It waits for the server to begin listening. 4. It starts the client path and quick-connects to `localhost:7777`. 5. On stop/exit, it kills the spawned server process. ## Project Requirements To make local testing reliable: * Keep `manifest.json` valid and present. * Ensure `entry_scene` points to a real scene. * Set `player_scene` and keep it in sync with your player scene path (`SummerCharacter3D` for 3D templates, or your own `SummerPlayer` subclass for other genres). * Keep server-authoritative logic in server paths (`Summer.is_server()` checks where needed). ## Multiplayer Testing (2+ Players) You have two practical options: ### Option A: First client via an available loopback runner, additional clients from editor 1. Start the first instance with the loopback runner (starts server + client). 2. Launch another editor instance. 3. Run the client scene and connect to `localhost:7777` using your quick-connect flow. ### Option B: Team testing on same network 1. One teammate runs the loopback runner (hosts local server). 2. Share host IP and port. 3. Other teammates run client mode and connect to that host. Do not start multiple local servers on the same port. For parallel server tests, use different ports. ## Fast Local QA Checklist Before exporting: * [ ] Game starts without script errors. * [ ] Players spawn correctly. * [ ] Movement and game rules are server-authoritative. * [ ] Scoring/round end/win conditions trigger correctly. * [ ] Reconnect/disconnect behavior is stable. * [ ] Match can run for at least 10+ minutes without critical errors. ## Common Local Testing Problems ### Server starts, but game scene does not load Usually one of: * `manifest.json` missing or invalid. * `entry_scene` path wrong. * scene root does not extend `SummerGame`. ### Player spawns fail Usually one of: * `player_scene` path wrong. * player scene does not use `SummerPlayer`. * game scene missing expected spawn/player nodes. ### Local behavior differs from expected production behavior Check: * your game rules are not accidentally client-side, * no editor-only assumptions in gameplay code, * no banned/blocked APIs used by generated code. Return to the capability and lifecycle hub. Produce and verify a game-only pack. # Update an Existing Summer Game Source: https://docs.summerengine.com/api-reference/summer-sdk/updating-your-game Keep a Summer game identity stable, bump its version, retest with Summer Engine, and submit a new immutable release for review. Released artifacts are immutable. An update is a new reviewed release for the same **Summer game**, not a replacement of the bytes already approved. Keep the **Summer SDK** contract and stable identifiers while changing the versioned game content. ## Update loop 1. Keep `manifest.id` stable. On the release API path, reuse the same `gameId`. 2. Bump `manifest.version`; pass the same version to upload-url and finalize. 3. Make the GDScript or asset changes needed for the update. 4. Run the [Summer Engine local test flow](/api-reference/summer-sdk/testing-your-game-locally). 5. Re-export the game-only `.pck` and recompute its SHA-256 and byte count. 6. Submit the new version through the [review flow](/api-reference/summer-sdk/submission-guide). Each update goes through human review. The previously approved release stays active while the update is pending or if the new release is rejected. Review submission paths and platform states. Return to the test loop before exporting another release. # AI Asset Generation Source: https://docs.summerengine.com/art-system/ai-generation Create, upload, organize, and import game assets (AI-generated or your own) directly into your games ## AI Assets for Game Development Summer Engine's **Studio** lets you create assets, upload and organize your own existing ones, and have Summer Engine import any asset directly into your games on command. AI asset generation is designed for **game development**: getting your game playable and testable quickly. **Realistic Expectations:** * AI assets work best for simple, clear concepts * Complex or stylized assets may need refinement * Perfect for placeholders and iteration * Not suitable for polished, commercial releases **What AI Assets Do Well:** * Basic character sprites and animations * Simple environment backgrounds * UI elements and buttons * Concept exploration and mood boards **What Needs Human Artists:** * Complex character designs with personality * Detailed environment art * Brand-consistent visual style * High-quality promotional materials ## Getting Started In Summer, go to Studio and use the Create tabs: 2D, 3D, Audio, or Video Select from preset styles like Realistic, Cartoon, Anime, Pixel Art, Low-Poly, or Fantasy Describe what you want to create in natural language Click Generate and iterate until you get the perfect result ## Writing Effective Prompts ### Basic Structure Start with the main subject, then add details about style, mood, and composition: ``` [Subject] + [Style] + [Mood/Lighting] + [Composition] ``` ### Examples **Character Sprites** ``` A brave knight in silver armor, cartoon style, bright cheerful lighting, facing forward for game sprite ``` **Environment Textures** ``` Seamless stone brick texture, medieval fantasy style, weathered and moss-covered, tileable pattern ``` **UI Elements** ``` Wooden game button with gold trim, fantasy RPG style, glowing hover effect, ornate carved details ``` **Concept Art** ``` Mystical forest clearing, anime style, soft magical lighting, ancient ruins in background ``` ## Style Presets Each style is optimized for different game genres and aesthetics: ### Realistic * **Best for**: Modern games, simulators, realistic environments * **Characteristics**: Photorealistic rendering, detailed textures, natural lighting * **Example**: "Realistic brick wall texture with subtle wear and weathering" ### Cartoon * **Best for**: Family games, mobile games, casual titles * **Characteristics**: Bright colors, simplified shapes, friendly appearance * **Example**: "Cartoon treasure chest with golden coins spilling out" ### Anime * **Best for**: JRPGs, visual novels, character-focused games * **Characteristics**: Stylized proportions, vibrant colors, expressive features * **Example**: "Anime-style magical girl character with flowing blue hair" ### Pixel Art * **Best for**: Retro games, indie titles, 2D platformers * **Characteristics**: Sharp pixels, limited color palettes, nostalgic feel * **Example**: "16-bit pixel art sword with glowing enchantment effect" ### Low-Poly * **Best for**: Mobile games, minimalist aesthetics, performance-focused titles * **Characteristics**: Flat colors, geometric shapes, clean edges * **Example**: "Low-poly mountain landscape with simple geometric trees" ### Fantasy * **Best for**: RPGs, adventure games, medieval settings * **Characteristics**: Magical elements, medieval themes, rich details * **Example**: "Fantasy spell book with glowing runes and leather binding" ## Advanced Features ### Prompt Enhancement Summer Engine can automatically improve your prompts using AI: **Original**: "A sword"\ **Enhanced**: "A gleaming medieval longsword with ornate crossguard, leather-wrapped grip, and polished steel blade reflecting light, fantasy RPG style" ### Reference Images Upload reference images to guide the style and composition: * **Style Reference**: Match the artistic style of an existing image * **Composition Reference**: Use the layout and structure as a guide * **Color Reference**: Extract color palettes from reference images ### Regeneration Options * **Regenerate**: Create a completely new version with the same prompt * **Refine**: Make subtle adjustments to the current result * **Variations**: Generate multiple versions to choose from ## Asset Metadata When creating assets, provide detailed information for better discoverability: ### Required Information * **Title**: Clear, descriptive name for your asset * **Asset Type**: 2D Image, Texture, Sprite, UI Element, etc. * **Tags**: Keywords that help others find your asset ### Optional Details * **Description**: Detailed explanation of the asset and its intended use * **License**: How others can use your asset (Free, Commercial, Attribution, Contact) * **Visibility**: Public (visible to all) or Private (only visible to you) ## Best Practices ### For Game Sprites * Specify the intended use: "for 2D platformer game" * Include pose/direction: "facing right, idle pose" * Mention transparency needs: "on transparent background" ### For Textures * Always specify "seamless" or "tileable" for repeating textures * Include resolution hints: "high resolution", "detailed" * Mention intended surface: "for stone walls", "metal armor texture" ### For UI Elements * Specify the UI context: "game menu button", "health bar design" * Include state variations: "normal, hover, and pressed states" * Mention size considerations: "scalable vector style" ### For Concept Art * Set the scene: "wide landscape shot", "character portrait" * Include mood descriptors: "mysterious", "heroic", "peaceful" * Specify viewing angle: "from below", "bird's eye view" ## Common Issues and Solutions ### Blurry or Low-Quality Results * Add "high quality", "detailed", or "sharp" to your prompt * Try regenerating with a more specific style preset * Use reference images for better guidance ### Wrong Style or Aesthetic * Be more specific about the art style you want * Try different style presets * Include negative prompts: "not cartoon style" or "avoid realistic rendering" ### Unwanted Elements * Be specific about what you don't want: "no text", "no people", "clean background" * Use composition terms: "centered", "isolated object", "simple background" ### Inconsistent Results * Save successful prompts for reuse * Use reference images for consistency * Create variations of working prompts rather than starting over ## Integration with Projects Assets (whether AI-generated, uploaded, or from the Store) flow directly into your games: 1. **Direct Import**: Ask Summer to add any asset to your game; it places it in the right folder and wires it up 2. **My Assets Library**: Create, upload, and organize your assets in Studio; Summer Engine can import any of them on command 3. **Prototype Workflow**: Perfect for rapid prototyping and testing gameplay mechanics 4. **Transition Planning**: Summer Engine can help you identify which AI assets to replace with human-created assets later **Pro Tip**: Use AI assets to get your game playable quickly, then gradually replace key assets with human-created work as you approach release. This hybrid approach lets you validate your game concept without upfront art costs. ## Next Steps Explore what others have created for inspiration Save your favorite assets for easy access # Asset Collections Source: https://docs.summerengine.com/art-system/collections Organize and manage your favorite game assets with collections ## What are Collections? Collections are personalized folders that help you organize and manage your favorite assets from the Summer Studio. Think of them as curated playlists for game assets - you can create collections for specific projects, art styles, or asset types. ## Creating Collections Go to Art → My Collections in Summer or visit your profile on summerengine.com/art Click "New Collection" and give it a descriptive name Choose whether your collection is Public (visible to all) or Private (only you can see it) Write a brief description explaining what the collection contains ## Adding Assets to Collections ### From the Studio When browsing assets in the gallery: 1. Click the bookmark icon on any asset 2. Select which collection(s) to add it to 3. Create new collections on-the-fly if needed ### From Asset Pages On individual asset pages: 1. Click "Add to Collection" 2. Choose from existing collections or create a new one 3. Assets are saved instantly ### Bulk Operations Select multiple assets and add them to collections in batch: 1. Use checkboxes to select multiple assets 2. Click "Add Selected to Collection" 3. Choose your target collection ## Collection Organization Ideas ### By Project Create collections for each of your games: * "Medieval RPG Assets" * "Space Shooter Graphics" * "Puzzle Game UI Elements" ### By Asset Type Organize by the type of content: * "Character Sprites" * "Environment Textures" * "UI Components" * "Sound Effects" ### By Art Style Group assets with similar aesthetics: * "Pixel Art Collection" * "Low-Poly Models" * "Hand-Drawn Illustrations" * "Realistic Textures" ### By Development Stage Organize by when you'll use them: * "Prototype Assets" * "Production Ready" * "Polish Phase" * "Marketing Materials" ## Managing Collections ### Collection Settings Each collection has configurable options: **Visibility** * **Public**: Anyone can view and follow your collection * **Private**: Only you can see and access the collection **Collaboration** * **Team Shared**: Available to your team members * **Read-Only**: Others can view but not modify * **Full Access**: Team members can add/remove assets ### Editing Collections * **Rename**: Update collection names as your projects evolve * **Reorder**: Drag and drop to organize assets within collections * **Remove Assets**: Clean up collections by removing outdated assets * **Merge Collections**: Combine similar collections to reduce clutter ## Sharing Collections ### Public Collections When you make a collection public: * Other users can discover it in the community section * People can follow your collection to get updates * Your collection appears on your public profile * Others can fork your collection (create their own copy) ### Collection URLs Each public collection gets a shareable URL: ``` summerengine.com/art/collections/username/collection-name ``` Share these links with: * Team members and collaborators * Community forums and social media * Game development blogs and tutorials ## Using Collections in Projects ### Direct Import Import entire collections into Summer projects: 1. Right-click on a collection in Summer 2. Select "Import All to Project" 3. Choose which project folder to import to 4. Assets maintain their organization structure ### Smart Suggestions Summer Engine's AI uses your collections to make better suggestions: * Recommends similar assets based on your collection patterns * Suggests complementary assets for your existing collections * Learns your style preferences from collection choices ### Project Templates Create reusable asset packages: 1. Build a collection with all assets for a specific game type 2. Use it as a template for new projects 3. Share templates with the community ## Collection Analytics ### Personal Insights Track how you use your collections: * **Most Used**: Which collections you access frequently * **Growth**: How your collections evolve over time * **Favorites**: Your most-liked assets across collections ### Public Collection Stats For public collections, see: * **Followers**: How many people follow your collection * **Forks**: How many copies others have made * **Popular Assets**: Which assets in your collection get the most attention ## Advanced Features ### Smart Collections Automatically populated collections based on rules: * "Recently Downloaded": Assets you've grabbed in the past week * "Highly Rated": Assets with 4+ stars that match your interests * "Trending in My Style": Popular assets similar to your existing collections ### Collection Recommendations Get suggestions for: * **Missing Assets**: Gaps in your collections that could be filled * **Similar Collections**: Public collections that match your interests * **New Assets**: Recently uploaded assets that fit your existing collections ## Best Practices ### Naming Conventions Use clear, descriptive names: * ✅ "Sci-Fi UI Elements - Blue Theme" * ✅ "Medieval Characters - NPCs" * ❌ "My Collection 1" * ❌ "Random Stuff" ### Regular Maintenance Keep collections organized: * Remove assets you no longer need * Update descriptions as collections evolve * Merge similar collections to reduce clutter * Archive completed project collections ### Community Contribution Share useful collections publicly: * Create themed collections for specific game genres * Curate high-quality assets for beginners * Build comprehensive asset libraries for common use cases ## Troubleshooting ### Can't Add Asset to Collection * Ensure you're signed in to your Summer account * Check that the asset isn't already in that collection * Verify you have permission to modify the collection ### Collection Not Syncing * Check your internet connection * Sign out and back in to Summer * Contact support if issues persist ### Missing Collections * Check if you're viewing the right account * Look in archived collections if you've hidden them * Verify collection visibility settings ## Next Steps Find assets to add to your collections Create unique assets for your collections # Summer Studio Source: https://docs.summerengine.com/art-system/gallery Browse, search, and discover game assets created by the Summer community ## Human-Created Art Community The Summer Studio showcases **human-created game assets** from our community of artists and developers. We believe AI has a place in prototyping, but human creativity produces the art that makes games memorable. **What You'll Find:** * Professional-quality sprites and animations * Hand-crafted textures and materials * UI elements with attention to detail * Unique artistic styles and interpretations **Our Standards:** * All assets are created by real artists * Quality reviews ensure professional standards * Clear licensing for commercial use * Support for artists through fair compensation ## Accessing the Summer Studio Navigate to Art → Browse Studio in the Summer application Visit store.summerengine.com to browse online ## Browsing Assets ### Filter by Asset Type Use the filter panel to narrow down your search: * **2D Images**: General artwork, concept art, backgrounds * **Sprites**: Character sprites, animations, game objects * **Textures**: Seamless textures, materials, surface patterns * **UI Elements**: Buttons, icons, panels, HUD components * **3D Models**: Characters, props, environment pieces ### Filter by Creation Method We believe in transparency, so every asset is clearly labeled: * **Human-Created**: Assets made by real artists with their unique creativity and style * **AI-Generated**: Assets created using AI tools, perfect for prototyping and placeholders * **Hybrid**: Assets that combine AI generation with human refinement and editing ### Search Functionality The search system looks through: * Asset titles and descriptions * Creator names and profiles * Tags and categories * File metadata **Search Tips:** * Use specific terms: "medieval sword" instead of just "weapon" * Try multiple keywords: "pixel art character sprite" * Search by style: "cartoon", "realistic", "anime" * Look for use cases: "platformer", "RPG", "mobile game" ## Sorting Options ### Recent Shows the newest uploads first - great for discovering fresh content and staying current with community trends. ### Popular Displays assets with the most likes and downloads. These are community-tested assets that other developers have found useful. ### Trending Highlights assets gaining popularity recently. Perfect for finding what's hot in the community right now. ## Asset Information Each asset displays comprehensive metadata: ### Basic Info * **Title**: Asset name chosen by the creator * **Creator**: Username and profile of the person who made it * **Creation Method**: Clearly labeled as "Human-Created", "AI-Generated", or "Hybrid" * **Upload Date**: When the asset was added to the gallery * **File Size**: Download size information ### Engagement Metrics * **Likes**: Community appreciation counter * **Downloads**: Usage popularity indicator * **Views**: How many people have seen this asset ### Technical Details * **Asset Type**: Category (2D, 3D, Texture, etc.) * **File Format**: PNG, JPEG, OBJ, GLTF, etc. * **Tags**: Keywords for discoverability * **License**: Usage rights and restrictions ## Licensing System Understanding asset licenses is crucial for proper usage: ### Free License * ✅ Use in personal projects * ✅ Use in commercial games * ✅ Modify and adapt * ❌ No attribution required ### Attribution License * ✅ Use in personal projects * ✅ Use in commercial games * ✅ Modify and adapt * ✅ Must credit the creator ### Commercial License * ✅ Use in commercial games * ✅ Modify and adapt * ❌ Contact creator for personal projects * ✅ May require attribution (check details) ### Contact License * ❌ Must contact creator before use * ❌ Custom licensing terms * ❌ Usage rights negotiated individually Always check the license before using an asset in your project. When in doubt, contact the creator directly. ## Downloading Assets Use filters and search to locate the perfect asset Verify the licensing terms match your project needs Click the download button to save the asset In Summer, assets are automatically available in your project browser ## Community Interaction ### Liking Assets Show appreciation for community creations by liking assets you find useful or inspiring. This helps creators understand what the community values. ### Following Creators Build connections with talented artists by following their profiles. You'll be notified when they upload new assets. ### Providing Feedback Leave constructive comments and suggestions to help creators improve their work and build a supportive community. ## Quality and Curation ### Community Standards The Summer community maintains high standards for asset quality: * **Technical Quality**: Assets should be properly formatted and optimized * **Originality**: Original creations or properly licensed derivatives * **Usefulness**: Assets should serve a clear game development purpose * **Proper Metadata**: Accurate titles, descriptions, and tags ### Reporting Issues If you encounter assets that violate community guidelines: 1. Use the report button on the asset page 2. Provide specific details about the issue 3. The moderation team will review and take appropriate action ## Tips for Effective Browsing ### Use Multiple Filters Combine asset type, style, and keyword filters to narrow down results effectively. ### Check Creator Portfolios If you like one asset from a creator, check their profile for similar high-quality work. ### Save to Collections Use collections to organize assets by project, style, or theme for easy retrieval. ### Regular Browsing New assets are uploaded daily. Regular browsing helps you stay current with community trends. ## Mobile and Responsive Design The gallery works seamlessly across devices: * **Desktop**: Full-featured browsing with detailed previews * **Tablet**: Touch-optimized interface with gesture navigation * **Mobile**: Streamlined experience perfect for inspiration on-the-go ## Integration with Summer Projects Assets from the gallery integrate directly into your Summer workflow: ### Automatic Import Downloaded assets appear in your project's asset browser immediately. ### Smart Organization Summer automatically categorizes assets based on type and suggests appropriate folders. ### AI Context Summer Engine's AI learns from your asset choices to make better suggestions for future generations. ### Version Tracking Asset usage is tracked with your project's version control system. ## Supporting Human Artists The Summer community values and supports human creativity: ### Discover Human Artists * Use the "Human-Created" filter to find assets made by real artists * Browse artist profiles to see their full portfolios * Follow your favorite artists to stay updated on their new work ### Fair Compensation * Artists can set commercial licensing fees for their work * Revenue sharing ensures artists get paid when their work is used commercially * Direct tip/support options for artists you want to encourage ### Community Recognition * Featured artist spotlights highlighting exceptional work * Community voting for "Artist of the Month" * Special badges and recognition for top human contributors **Support the Community**: When you use human-created assets in a successful game, consider reaching out to thank the artist or hire them for custom work. Building these relationships strengthens the entire game dev ecosystem. ## Next Steps Browse and support human-created assets Save and organize your favorite finds # Asset Licensing Guide Source: https://docs.summerengine.com/art-system/licensing Understanding licensing options for game assets in Summer ## Overview The Summer Studio provides clear licensing options to help creators share their work while protecting their rights, and to help developers understand how they can use community assets in their projects. ## License Types ### Free License **Perfect for**: Open-source projects, learning, experimentation ✅ **You can:** * Use in personal projects * Use in commercial games * Modify and adapt the asset * Redistribute modified versions * Use without attribution ❌ **You cannot:** * Claim original ownership * Sell the unmodified asset as your own ### Attribution License **Perfect for**: Supporting creators while using their work ✅ **You can:** * Use in personal projects * Use in commercial games * Modify and adapt the asset * Redistribute modified versions ✅ **You must:** * Credit the original creator * Include attribution in your game credits * Maintain attribution in derivative works ❌ **You cannot:** * Use without proper attribution * Claim original ownership ### Commercial License **Perfect for**: Professional game development ✅ **You can:** * Use in commercial games and products * Modify and adapt for commercial use * Include in paid games and applications ❌ **Restrictions:** * May require attribution (check specific terms) * Usually restricted to commercial use only * Contact creator for personal/educational use 💰 **Note:** Some commercial licenses may require payment or revenue sharing ### Contact License **Perfect for**: Custom licensing arrangements ❌ **Requires:** * Direct contact with the creator before use * Negotiated terms for each use case * Custom licensing agreement 💬 **Best for:** * High-value commercial projects * Exclusive usage rights * Custom modifications or adaptations ## Choosing the Right License for Your Assets ### As a Creator When uploading your assets, consider: **Free License** - Choose when you want: * Maximum adoption and usage * To contribute to the open-source community * To build your reputation and portfolio * No ongoing maintenance or attribution tracking **Attribution License** - Choose when you want: * Credit for your work * To track how your assets are being used * To build recognition while sharing freely * A balance between openness and recognition **Commercial License** - Choose when you want: * To monetize your creative work * To restrict usage to serious commercial projects * To maintain more control over usage * Professional licensing arrangements **Contact License** - Choose when you want: * Full control over each usage * Custom terms for different use cases * To negotiate payment or revenue sharing * Exclusive licensing opportunities ## Using Licensed Assets ### Attribution Requirements When using Attribution Licensed assets, include credits in: **In-Game Credits** ``` Art Assets: - "Fantasy Sword Sprite" by ArtistName (Summer Studio) - "Stone Texture Pack" by CreatorName (Summer Studio) ``` **Documentation** ``` Third-Party Assets Used: - Character sprites from Summer user "PixelMaster" - UI elements by "GameArtist" under Attribution License ``` **README Files** ```markdown theme={null} ## Assets This game uses assets from the Summer Studio: - Background music by MusicCreator (Attribution License) - Sound effects by AudioPro (Free License) ``` ### Best Practices for Attribution **Be Specific** * Include the exact asset name * Mention the creator's Summer username * Note that it came from Summer Studio **Be Visible** * Place attributions where players can easily find them * Include in main game credits, not just documentation * Consider in-game attribution for heavily featured assets **Keep Records** * Save license information when downloading * Track which assets require attribution * Update credits if you modify or remove assets ## License Compliance ### Before Using an Asset Carefully review the license terms on the asset page Ensure the license works with your project type (personal/commercial) If attribution is required, plan how you'll credit the creator Keep records of what you've downloaded and under what license ### Common Compliance Mistakes ❌ **Using Commercial-Only assets in personal projects** * Always check if commercial licenses allow personal use ❌ **Forgetting attribution requirements** * Set up your credits system early in development ❌ **Assuming "Free" means "No restrictions"** * Even free licenses have terms about ownership and redistribution ❌ **Not keeping license records** * Track what you've used to ensure compliance at release ## Licensing for Teams ### Team Projects When working in teams, ensure: * All team members understand licensing requirements * Someone is responsible for tracking asset licenses * Credits and attribution are consistently managed * License compliance is checked before release ### Client Work For client projects: * Verify that licenses allow commercial use by third parties * Transfer appropriate usage rights to clients * Document all asset licenses in project handover * Consider client's ongoing licensing obligations ## Dispute Resolution ### If You Think Your Rights Were Violated 1. **Contact the User**: Try direct communication first 2. **Document the Violation**: Screenshots, links, evidence 3. **Report to Summer**: Use the report system on the platform 4. **Legal Action**: For serious cases, consult legal counsel ### If Someone Claims You Violated Their Rights 1. **Review Your Usage**: Check the license terms you agreed to 2. **Communicate Openly**: Respond to concerns promptly 3. **Make Corrections**: Fix attribution or usage if needed 4. **Seek Mediation**: Use Summer Engine's dispute resolution if available ## International Considerations ### Copyright Laws * Asset licenses operate under copyright law * Different countries have different copyright terms * Summer Engine's licenses are designed to work internationally * When in doubt, consult local legal experts ### Commercial Use Across Borders * Commercial licenses generally work internationally * Some creators may restrict usage by geographic region * Check for any territorial restrictions in license terms * Consider local business licensing requirements ## Additional License Features * **Revenue Sharing**: Automatic percentage sharing for commercial licenses * **Usage Analytics**: See how your licensed assets are being used * **License Templates**: Standardized license options for creators * **Bulk Licensing**: License entire collections with single agreements ## Getting Help ### License Questions * **Asset Page**: Check the detailed license information on each asset * **Creator Contact**: Message creators directly for clarification * **Community Forums**: Ask the Summer community for advice * **Support Team**: Contact Summer support for platform-specific questions ### Legal Advice Summer provides licensing tools but cannot provide legal advice. For complex licensing situations or legal concerns, consult with qualified legal professionals. ## Next Steps Find assets with the right license for your project Create and share your own licensed assets # Summer Studio Source: https://docs.summerengine.com/art-system/overview Create, share, and discover game assets with AI-powered generation ## What is Summer Studio? Summer Studio is a comprehensive platform for creating, sharing, and discovering game assets - both AI-generated and human-crafted. We believe the future of game development includes both human creativity and AI assistance working together, not replacing each other. **Our Philosophy**: AI assets are a tool, like Photoshop or Blender. They can help developers prototype faster and create placeholder assets, but they will never replace the unique vision, style, and intentionality that human artists bring to games. We're transparent about what's AI-generated and what's human-made, because both have their place in game development. Whether you need sprites, textures, UI elements, or concept art, you can create them in Studio (2D, 3D, Audio, Video tabs), upload and organize your own assets, or browse community-created assets, then have Summer import any asset directly into your games on command. ## Key Features Create, upload, organize assets in Studio. Summer Engine imports any asset into your games on command Browse and support thousands of assets created by real human artists in our community Every asset is clearly marked as "AI-Generated" or "Human-Created" - no confusion Fair licensing that protects human artists while enabling AI-assisted prototyping ## Asset Types Supported ### 2D Assets * **Sprites**: Character sprites, animations, UI elements * **Textures**: Seamless textures, materials, backgrounds * **UI Graphics**: Buttons, icons, panels, HUD elements * **Concept Art**: Character designs, environment concepts ### 3D Assets * **Models**: Characters, props, environment pieces * **Textures**: PBR materials, normal maps, diffuse textures * **Archives**: Multi-file asset packages ### Supported Formats **Images**: PNG, JPEG, WebP, GIF, SVG\ **3D Models**: OBJ, GLTF/GLB, FBX, Blend, DAE\ **Textures**: TGA, HDR\ **Archives**: ZIP, RAR (for multi-file assets) **File Size Limit**: Up to 500MB per asset to support high-quality game development needs. ## Getting Started In Summer, open Studio to create assets (2D, 3D, Audio, Video), manage My Assets, or browse the Store Explore the community gallery using filters, search, and categories Use Studio's Create tabs (2D, 3D, Audio, Video) to generate or upload assets Save your favorite assets to collections for easy organization ## Art Styles Available When generating AI assets, choose from these optimized styles: Photorealistic renders and detailed artwork Stylized, family-friendly cartoon aesthetics Japanese animation-inspired character art Retro pixel-perfect sprites and textures Minimalist 3D-style with flat colors Magical, medieval, and fantastical themes ## Supporting the Dev Community ### Transparency First * **Clear Labeling**: Every asset shows "AI-Generated" or "Human-Created" prominently * **Creation Method**: See exactly how each asset was made * **Artist Attribution**: Human artists get full credit and recognition * **AI Disclosure**: AI-generated content is never hidden or misrepresented ### Artist Support * **Fair Compensation**: Revenue sharing for commercial licenses on human-created assets * **Portfolio Building**: Artists can showcase their work and build their reputation * **Community Recognition**: Highlighting exceptional human creativity and craftsmanship * **Anti-Theft Protection**: Tools to report unauthorized use of human artwork ### Ethical AI Use * **Prototyping Focus**: AI tools positioned as prototyping aids, not final art solutions * **Style Respect**: AI generation avoids mimicking specific living artists' styles * **Education**: Resources on when to use AI vs. hiring human artists * **Transition Support**: Help developers move from AI prototypes to human-created final art ## Integration with Summer Assets from Summer Studio integrate seamlessly with Summer Engine's game development workflow: * **Direct Import**: Import assets directly into your Summer projects * **AI Context**: Summer Engine's AI understands your asset choices for better suggestions * **Project Organization**: Assets are automatically organized in your project structure * **Version Control**: Asset changes are tracked with your project history ## Next Steps Generate your first AI-powered game asset Browse the community asset library Search the full asset store on summerengine.com # Auto Source: https://docs.summerengine.com/auto-mode/auto Balanced quality and speed for everyday tasks Auto allows Summer Engine to select models that balance intelligence, cost efficiency, and reliability. It is useful for everyday tasks. Auto is the default model for new chats and is available on every plan, including Free. ## When to Use Auto * Day-to-day game development: gameplay code, UI, scenes, small refactors. * Asking questions about your project. * Quick edits, prototyping, and exploration. ## When to Use MAX Instead For the hardest problems — long agentic tasks, complex multi-file refactors, deep reasoning — switch to MAX. See [MAX](/auto-mode/premium). ## Picking a Specific Model You can also pick a specific model from the selector instead of Auto or MAX. Paid plans can pick any model; free accounts get a small set of directly selectable models alongside Auto. See [Models](/auto-mode/models). Auto routing is opaque on purpose: the underlying model may change as we improve quality, cost, and reliability. If you need a specific model, pick it directly from the selector. # Models Source: https://docs.summerengine.com/auto-mode/models How model choice works: Auto, MAX, or a specific model you pick Summer gives you three ways to choose which model does the work: * **[Auto](/auto-mode/auto)** — Summer picks for you. The default for new chats, available on every plan. * **[MAX](/auto-mode/premium)** — Summer picks from the frontier models, billed at the API pricing of whatever it selects. Paid plans only. * **A specific model** — you pick one yourself from the model selector. ## The selector is the list The model selector in the chat composer is the source of truth for what you can pick right now. It is rendered from the live model catalog, so it is current in a way a documentation page cannot be. Open it and you will see every model, grouped by provider, with its context window and any cost warning attached. Models are added and retired regularly. Anything named on this page is a snapshot of a moving list; the selector is not. ## What each plan can pick | | Models you can select | | -------------- | ----------------------------------------------------------------------------------------- | | **Signed out** | Auto, plus one directly selectable OpenAI model (currently Luna Extra High) | | **Free plan** | Auto, plus two directly selectable models (currently Luna Extra High and DeepSeek V4 Pro) | | **Paid plans** | Auto, MAX, and every model in the selector | Auto is not the only thing a free account can use. The two concrete models are selectable on purpose, for people who would rather name their model than hand the choice to Auto's routing. Models your plan does not cover still appear in the selector, muted and marked with a lock. Picking one opens the upgrade prompt rather than switching your chat. ## Which providers are in the selector On a paid plan you can pick directly from every provider represented in the selector: | Provider | What it is good for | | ------------------- | ---------------------------------------------------------------- | | **OpenAI** | Everyday coding and agentic work, plus a coding-specialist model | | **Anthropic** | Hard coding, long-horizon agentic tasks, and planning | | **DeepSeek** | Long-context coding when you want more building time per dollar | | **GLM (Z.ai)** | Large projects and long-running agentic work at 1M context | | **Kimi (Moonshot)** | Long-context reasoning with native vision | | **Grok (xAI)** | Fast coding, knowledge work, and STEM reasoning | | **Qwen (Alibaba)** | Long-running agentic work and tool use | Individual model names and versions live in the selector — hover one to see its description, context window, and any cost warning. Some frontier models will burn a \$20 plan quickly; those carry a "Higher cost" marker and an estimate of how many messages your balance has left at that model's rate. If you do not want to think about any of this, leave it on Auto. It is the default for a reason and it is what we recommend for most work. # MAX Source: https://docs.summerengine.com/auto-mode/premium The most capable models, for the most complex tasks MAX allows Summer Engine to select the most capable models for you, recommended for the most complex tasks. It maxes out context windows and tool calls, and it is billed at the API pricing of the models it picks. MAX is available on all paid plans. In the model selector it appears as **MAX**, next to Auto. ## When to Use MAX * Long agentic tasks that span many files. * Complex refactors and architecture work. * Hard reasoning problems where quality matters more than speed or cost. ## When Auto Is Enough For everyday tasks — small features, quick edits, questions about your project — [Auto](/auto-mode/auto) is faster and cheaper. ## Picking a Specific Model If you want a specific model rather than letting MAX pick, see [Models](/auto-mode/models). MAX routing is opaque on purpose: the underlying model may change as new flagship models ship. If you need a specific model, pick it directly from the selector. # Authoring Project Data Source: https://docs.summerengine.com/automation/authoring Writing project files directly instead of clicking through the editor: where user:// really lives, how feature-tag overrides hide from get_setting, which translation formats load without an import pass, and the point at which hand-writing a .tscn stops working. Most of a Summer project is text you can write yourself. Scenes, resources, project settings and translations are all authorable from a script or straight from disk, which is what makes an agent able to build a game without a person clicking anything. This page is about **what to write**. [Headless Scripting](/automation/headless) covers how to *run* the engine from a shell to write it — the script template, exit codes, the import pass. Read that one first if you have not. Four places the "just write the file" approach stops working, all of them measured against the shipped binary rather than reasoned about: | Topic | The trap | | -------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [`user://`](#where-user-actually-goes) | The path on disk has `Godot` in it, not `Summer` | | [Feature-tag overrides](#project-settings-and-feature-tag-overrides) | `get_setting()` reports the base value while the engine uses the override | | [Translations](#localisation-three-formats-three-rules) | Loading the `.csv` you wrote returns null forever, silently | | [Tilemaps](#tilemaps-where-hand-writing-a-tscn-stops) | Cells are a packed byte blob, not readable text | ## The failure shape to watch for Nearly every trap on this page has the same signature, and it is worth naming because once you recognise it you will start catching the others yourself: > **Your own read-back confirms a change that did not take.** Not an error. Not a crash. You set a value, you read it back to check, the check passes, and the thing you asked for did not happen: * `ProjectSettings.set_setting()` returns fine and reads back fine, and the value is gone next run because nothing called `save()`. * A feature-tag override is live and driving the engine, while `get_setting()` reports the base value and tells you it did not apply. * `PathFollow2D.progress` set before the node is in the tree reads back exactly what you set, and the node never moves. * `PackedScene.pack()` and `ResourceSaver.save()` both return success and write a scene with your nodes missing. * `FontFile.load_dynamic_font()` returns error code 0 having loaded zero faces. This is a worse class of bug than a loud failure, because the natural instinct — *verify by reading it back* — is precisely what fails. **Verify by the effect, not by the value.** Did the node move? Does the reloaded scene have the child? Does the exported build actually contain the file? Those questions cannot be answered by the same in-memory state that lied to you. ## Where `user://` actually goes A save file written to `user://save.json` lands here: ``` /Users//Library/Application Support/Godot/app_userdata/ ``` Note **`Godot`**, not `Summer`. This is the same surprise as the export-template directory described on the [headless page](/automation/headless) — our product name is not in the path. "I wrote a save file and it is not there" almost always ends here. The `` segment comes from `config/name` in `project.godot`, so it changes when the project is renamed. Do not construct the path. Ask the engine: ```gdscript theme={null} print(OS.get_user_data_dir()) # /Users/you/Library/Application Support/Godot/app_userdata/AuthoringProbe ``` That is measured output for a project whose `config/name` is `AuthoringProbe`. ## Project settings and feature-tag overrides `project.godot` supports per-platform overrides with a feature-tag suffix — `difficulty.macos` overrides `difficulty` when running on macOS. They work. They are also invisible to the most obvious way of checking them. Given a `project.godot` containing: ```ini theme={null} difficulty=3 difficulty.macos=99 hard.macos=1 ``` running on macOS: ``` difficulty=3 <- get_setting() returns the BASE value with_override difficulty=99 <- override applied hard= hard.macos=1 <- an override alone does NOT create the base key ``` **`ProjectSettings.get_setting()` does not apply feature-tag overrides. `get_setting_with_override()` does.** This is nastier than a plain gotcha because the engine's own internal reads *do* apply the override. The setting genuinely works at runtime while your verification step reports that it did not. **It fails by disagreeing with your check, not by breaking** — so the usual response is to "fix" a setting that was already correct. Measured on `4.6.1.stable.mono.custom_build.b708b1182`. Two rules: 1. **Read effective values with `get_setting_with_override()`.** Use plain `get_setting()` only when you specifically want the unoverridden base value. 2. **Always define a base key alongside any override.** An override on its own leaves the base key null — `hard.macos=1` exists, `hard` does not. Anything reading `hard` gets `null`, including `get_setting_with_override()` on a platform that is not macOS. ```gdscript theme={null} # Effective value, override applied. var difficulty = ProjectSettings.get_setting_with_override("difficulty") # Safe read of a key that may be missing entirely. var hard = ProjectSettings.get_setting("hard", false) ``` ## Localisation: three formats, three rules Three file formats reach the same place by different routes, and only one of them is comfortable to write by hand. **This is the format an agent should use.** Write it, load it, done. No import pass, no sidecar, no `.godot/` directory. ```po theme={null} msgid "" msgstr "" "Language: de\n" msgid "HELLO" msgstr "Hallo" msgid "BYE" msgstr "Tschuess" ``` Loading it directly returns a real `Translation`: ``` PO=(res://de.po): locale=de msg=Hallo count=2 ``` The locale is read from the `Language:` header, so a `.po` file carries its own locale and you do not declare it anywhere else. A translation `.csv` has a `keys` column and one column per locale: ```csv theme={null} keys,en,es HELLO,Hello,Hola BYE,Bye,Adios ``` It requires an import pass, and the importer writes **sibling files**, one per locale: ``` strings.csv strings.csv.import strings.en.translation strings.es.translation ``` **Load the sibling, never the `.csv`.** See the warning below — this is the silent one. Compiled output, not source. `file` reports it as binary, and the loaded resource is an `OptimizedTranslation` rather than a plain `Translation`: ``` ES_sibling=(res://strings.es.translation): ``` You cannot hand-write one. Write a `.po`, or write a `.csv` and import it. **Loading a translation `.csv` returns null forever — and gets quieter after you import it.** ``` # before the import pass ERROR: No loader found for resource: res://strings.csv (expected type: unknown) CSV_direct= # after the import pass CSV_direct= <- no error at all now ES_sibling=(res://strings.es.translation): ``` Before importing, at least you get an error line. **After importing, it returns null with no error whatsoever**, because the importer registered the file as handled — so the state that looks most like success is the one that tells you least. The cause is in the sidecar. `strings.csv.import` has no `path=` key, only `dest_files`: ```ini theme={null} [remap] importer="csv_translation" type="Translation" [deps] files=["res://strings.en.translation", "res://strings.es.translation"] source_file="res://strings.csv" dest_files=["res://strings.en.translation", "res://strings.es.translation"] ``` A single-output importer writes `path=`, which is what lets `load()` on the source file resolve to the compiled product. A translation `.csv` produces *many* outputs, so there is no single path to remap to, and `load("res://strings.csv")` has nothing to resolve. **An agent must load the file the importer generated, not the file it wrote.** Measured on `4.6.1.stable.mono.custom_build.b708b1182`. Register translations through the `internationalization/locale/translations` project setting. Both `.po` and `.translation` files can be listed: ```ini theme={null} [internationalization] locale/translations=PackedStringArray("res://de.po", "res://strings.es.translation") ``` Measured result — both locales load, and `tr()` resolves against whichever is current: ``` SETTING=["res://de.po", "res://strings.es.translation"] LOADED=["de", "es"] de tr(HELLO)=Hallo es tr(HELLO)=Hola ``` **The default locale is the OS locale, not `"en"`.** It measured as `en_DK` on the test machine — a locale for which you almost certainly have no translation, and which is not the one you assumed. Set it explicitly if any behaviour depends on it: ```gdscript theme={null} TranslationServer.set_locale("en") ``` The `.csv` route is the only one here that needs the import pass. Running it is not free and not always safe — see [importing assets](/automation/headless#importing-assets) for the `--import` hazard, which matters if an editor is open. **Writing a `.po` avoids the question entirely**, which is the main reason to prefer it. ## Saving scenes from a script `ResourceSaver.save(PackedScene)` is the reliable way to produce a `.tscn`. It has one requirement that is easy to miss and fails quietly. **Every child must have its `owner` set before `pack()`, or it is not saved.** `PackedScene.pack()` only serialises nodes owned by the node being packed. Miss it and the save still returns `0`: ``` [with owner] children=1 [no owner] children=0 ``` Same code, same success code, an empty scene. Nothing reports a failure at any point. ```gdscript theme={null} var root := Node2D.new() root.name = "Level" var child := Sprite2D.new() child.name = "Player" root.add_child(child) child.owner = root # REQUIRED. Without it the saved scene is empty. var packed := PackedScene.new() packed.pack(root) var err := ResourceSaver.save(packed, "res://level.tscn") if err != OK: push_error("[scene] save failed: %d" % err) ``` The root itself does not need an owner. Nested children take the **scene root** as owner, not their immediate parent. ## Tilemaps: where hand-writing a `.tscn` stops An agent can hand-write most of a `.tscn`. It cannot hand-write a tilemap. `TileMapLayer` cells do not serialise as readable text. The entire layer — every cell, its source, its atlas coordinate and its alternative — is one packed byte array on the node called `tile_map_data`. This is what it looks like in a real saved scene: ```ini theme={null} [node name="Ground" type="TileMapLayer" parent="."] tile_map_data = PackedByteArray(0, 0, 253, 255, 7, 0, 0, 0, 2, 0, 1, 0, 0, 0, 11, 0, 254, 255, 0, 0, 1, 0, 3, 0, 0, 0) ``` That is two cells. **Do not try to patch this blob with a text edit.** There is no string in it to match on. Editing a cell means changing bytes at a computed offset, which a find-and-replace cannot express, and a real tilemap's array runs to many thousands of characters — past the point where tolerant edit matching applies at all. A near-miss produces a misaligned array that still parses into *some* set of cells, so the failure arrives as garbled level geometry rather than an error. **Use `set_cell()` and let the engine write the bytes.** This is the whole job: ```gdscript theme={null} extends SceneTree func _init() -> void: var layer := TileMapLayer.new() layer.name = "Ground" layer.tile_set = load("res://tiles.tres") # set_cell(coords, source_id, atlas_coords, alternative_tile) layer.set_cell(Vector2i(-3, 7), 5, Vector2i(2, 9), 4) layer.set_cell(Vector2i(11, -2), 8, Vector2i(6, 1), 3) var root := Node2D.new() root.name = "Level" root.add_child(layer) layer.owner = root # or the layer is not saved at all var packed := PackedScene.new() packed.pack(root) var err := ResourceSaver.save(packed, "res://level.tscn") if err != OK: push_error("[tilemap] save failed: %d" % err) quit(1) print("[tilemap] wrote res://level.tscn") quit(0) ``` Round-tripped through the shipped binary, `get_used_cells()` on the reloaded scene returns `[(-3, 7), (11, -2)]` — coordinates, sources, atlas positions and alternatives all intact. Documented so you can **read** a blob — to diff two scenes, or to check what an editor-produced layer actually contains. It is not an invitation to write one by hand. A ` Array: var out := [] if data.size() < 2: return out var version := data.decode_u16(0) assert(version == 0, "unknown tile_map_data format version") var offset := 2 while offset + 12 <= data.size(): out.append({ "cell": Vector2i(data.decode_s16(offset), data.decode_s16(offset + 2)), "source_id": data.decode_u16(offset + 4), "atlas": Vector2i(data.decode_s16(offset + 6), data.decode_s16(offset + 8)), "alternative": data.decode_u16(offset + 10), }) offset += 12 return out ``` Run against a 26-byte layer holding two cells with distinct sources, distinct non-zero alternatives and negative coordinates in both axes: ``` size=26 { "cell": (-3, 7), "source_id": 5, "atlas": (2, 9), "alternative": 4 } { "cell": (11, -2), "source_id": 8, "atlas": (6, 1), "alternative": 3 } ``` Which is exactly the layer that produced it. ## Ordering and serialisation rules Two more rules that share the shape of everything else on this page: the operation appears to succeed, or fails opaquely, rather than telling you what is wrong. ### A `Path2D` must be in the tree before you position a `PathFollow2D` **`progress` set before the `Path2D` is in the scene tree is accepted and does nothing.** The two properties fail differently, and the quiet one is the one you are more likely to use: | Property | Set before the `Path2D` is in the tree | | ---------------- | -------------------------------------------------------------------------- | | `progress_ratio` | **Errors**, value discarded — reads back `0.0` | | `progress` | **No error.** Reads back `50.0`. Node never moves, position stays `(0, 0)` | The error you get from `progress_ratio`: ``` ERROR: Can only set progress ratio on a PathFollow2D that is the child of a Path2D which is itself part of the scene tree. at: set_progress_ratio (scene/2d/path_2d.cpp:472) ``` `progress` prints nothing at all. The property holds the value you assigned, so reading it back as a check confirms a placement that never happened. Measured on `4.6.1.stable.mono.custom_build.b708b1182`. Add the `Path2D` to the tree, let a frame pass, then set the position: ```gdscript theme={null} var curve := Curve2D.new() curve.add_point(Vector2(0, 0)) curve.add_point(Vector2(100, 0)) var path := Path2D.new() path.curve = curve var follow := PathFollow2D.new() path.add_child(follow) get_root().add_child(path) await process_frame # per the headless page: in-tree APIs need a frame follow.progress = 50.0 print(follow.position) # (50.0, 0.0) ``` Without the `add_child` and the frame, that last line prints `(0.0, 0.0)`. ### A `Resource` defined as an inner class cannot be serialised **An inner-class `Resource` saves with error `0` and reloads with its script gone.** ``` ERROR: Failed to encode a path to a custom script. at: encode_variant (core/io/marshalls.cpp:1785) inner var_to_bytes len=0 inner save err=0 inner reloaded class=Resource script= ``` `var_to_bytes_with_objects` returns a **zero-length** array, and `ResourceSaver.save` reports success while writing something that comes back as a bare `Resource` with every exported property lost. An inner class has no resource path, so there is nothing to record. Measured on `4.6.1.stable.mono.custom_build.b708b1182`. Give the resource its own script file with a `class_name`: ```gdscript theme={null} # res://inner_data.gd extends Resource class_name InnerData @export var hp := 10 ``` ```gdscript theme={null} var d := InnerData.new() d.hp = 42 ResourceSaver.save(d, "user://inner.tres") # round-trips with the script intact ``` ## For AI agents Authoring project data directly works well. These are the parts that will burn you, and as on the [headless page](/automation/headless), every one of them fails by *appearing to succeed*: 1. **`user://` is under `Godot`, not `Summer`.** Call `OS.get_user_data_dir()` rather than building the path. The `` segment is `config/name` and changes with the project. 2. **`get_setting()` hides feature-tag overrides.** Use `get_setting_with_override()` for the effective value. The engine applies the override internally, so a naive check disagrees with reality and tempts you to "fix" a setting that was already right. 3. **Always write a base key next to any override.** `foo.macos=1` alone leaves `foo` null. 4. **Write `.po`, not `.csv`.** `.po` loads directly with no import pass. `load()` on a translation `.csv` returns null before *and* after import — and after import it returns null with no error at all. Load the generated `res://..translation` sibling instead. 5. **Set the locale explicitly.** The default is the OS locale, measured `en_DK`, not `"en"`. 6. **Set `owner` on every child before `pack()`.** Otherwise `ResourceSaver.save` returns `0` and writes an empty scene. 7. **Never text-edit `tile_map_data`.** Call `set_cell()` and save a `PackedScene`. The blob is fixed-width binary with no strings to match on, and a misaligned edit yields plausible-looking garbage rather than an error. 8. **Put the `Path2D` in the tree before setting `progress`.** Setting it early is silently ignored while the property still reads back the value you assigned. 9. **Never declare a `Resource` as an inner class.** It saves with error `0` and reloads with its script and all exported properties gone. Give it a file and a `class_name`. # Headless Scripting Source: https://docs.summerengine.com/automation/headless Run Summer from a shell with no window: bake navmeshes, generate collision and LODs, author resources, import assets, and export builds from a plain GDScript file. Summer's engine binary runs without a window. Point it at a project and a script, and it will execute that script with the whole engine available — physics, resources, importing, exporting, the lot. This is how you automate work that has no reason to involve a person clicking through the editor. ```bash theme={null} /Applications/Summer.app/Contents/MacOS/Summer --headless --path /path/to/project -s res://task.gd ``` **`--headless` produces no pixels. None.** There is no rendering. `viewport.get_texture()` returns a healthy-looking `ViewportTexture` with a plausible size, and then `get_image()` on it returns **null**: ``` ERROR: Parameter "t" is null. at: texture_2d_get (servers/rendering/dummy/storage/texture_storage.h:106) ``` Every readback route fails the same way: the root viewport, a `SubViewport` set to `UPDATE_ALWAYS`, calling `RenderingServer.force_draw()` first, and `RenderingServer.texture_2d_get()`. `--write-movie` does not rescue you either — under `--headless` it **crashes with signal 11**. If you do not null-check, `save_png()` is never reached, no file is written, and nothing reports a failure. Your script exits 0 and you believe it worked. **Any plan of the form "run headless and take a screenshot" is dead on arrival.** Headless can simulate. It cannot see. ## The script template Copy this. It is the exact file used to verify the behaviour on this page. ```gdscript theme={null} extends SceneTree # Entry point for: Summer --headless --path -s res://task.gd # _init() is the entry point. _run() is NEVER called and will hang the process. func _init() -> void: var exit_code := 0 print("[task] start") # Nodes added here are NOT in the tree until at least one frame passes. var n := Node3D.new() get_root().add_child(n) await process_frame # required before physics / in-tree APIs print("[task] node in tree: ", n.is_inside_tree()) # ... do work ... var ok := true if not ok: push_error("[task] FAILED: reason here") exit_code = 1 print("[task] done") quit(exit_code) # REQUIRED. Without it the process hangs forever. ``` **`_init()` is the entry point, not `_run()`.** `_run()` belongs to `EditorScript`, which cannot be instantiated outside the editor. A script using `_run()` with `-s` **hangs forever and prints absolutely nothing** — no error, no warning, no output at all. `--quit-after` does not rescue it. This is the single easiest way to lose an afternoon. If your headless script produces no output and never returns, check this first. Only two base classes work. Everything else hangs silently: | Script shape | Result | | ------------------------------------------------------------------- | ------------------------------------------------- | | `extends SceneTree` + `_init()` | **Works** | | `extends MainLoop` + `_initialize()` / `_process()` / `_finalize()` | **Works** — return `true` from `_process` to quit | | `extends SceneTree` + `_run()` only | Hangs, zero output | | `extends Node`, `extends Object`, `extends RefCounted` | Hangs forever, zero output | `@tool` on a `-s` script is a no-op — `Engine.is_editor_hint()` is `false` here. ## Exit codes lie **Only an explicit `quit(N)` produces a non-zero exit code — and a runtime error produces no exit code at all.** | What happened | Result | | ------------------------------------- | ------------------------------------------------ | | `quit(0)` | exits 0 | | `quit(42)` | exits 42 | | GDScript **parse** error | exits **0** | | **Script file does not exist at all** | exits **0** | | `push_error()` | exits **0** | | GDScript **runtime** error | **hangs forever. No exit, no crash, no timeout** | Two separate failure modes, and you need a defence against each. A typo in your script path exits 0, so CI reports success on a script that never ran. Guard against that by reading stderr. A runtime error — a null dereference, a division by zero, an out-of-bounds index — prints its error and then **sits there indefinitely**, because `quit()` was never reached. Reading stderr does not save you, because the process never returns to be inspected. **Every script you run unattended needs an external wall-clock timeout.** Gate on stderr, not on `$?`. Streams are cleanly separated: `print()` goes to stdout; `printerr()`, `push_error()`, `push_warning()` and all engine `ERROR:` / `WARNING:` lines go to stderr. Grep for `SCRIPT ERROR`, `Parse Error`, `Can't load script`, and `ERROR:`. **Check syntax before you run anything.** `--check-only` parses a script without executing it, in well under a second — the cheapest possible gate, and it catches the parse errors that would otherwise exit 0 and look like success: ```bash theme={null} Summer --headless --path . --check-only -s res://task.gd ``` The exit code is still 0, so read stderr. But it costs almost nothing and it runs no code, so it cannot hang. **Never pass `--quiet`.** It swallows your script's own `print()` output, so a script that ran correctly looks like a script that produced nothing. One benign exception: `WARNING: ObjectDB instances leaked at exit` prints on **every** run, including fully successful ones. Do not gate on it. ## Finding the binary The binary is **not** called `godot`. `godot --headless` fails on every user's machine because no such binary is installed. On macOS the engine is at `/Applications/Summer.app/Contents/MacOS/Summer`. From inside a running script, ask the engine directly rather than guessing: ```gdscript theme={null} print(OS.get_executable_path()) # /Applications/Summer.app/Contents/MacOS/Summer ``` That path is the real executable, not the `.app` wrapper, so it is safe to re-invoke directly for self-spawning work. ## What works Verified by running each against the shipped binary. `create_trimesh_shape()` and `create_convex_shape()` both work and round-trip through `.tres` losslessly. A `BoxMesh` produces 36 face vec3s (12 triangles) trimesh and an 8-point convex hull. Simplification is effective: a 32x16 sphere gives a 514-point convex hull, or **32 points** with `create_convex_shape(true, true)`. Use `NavigationServer3D.bake_from_source_geometry_data(nav_mesh, source_geometry)`. `NavigationServer2D` has the same method. Prefer building `NavigationMeshSourceGeometryData3D` procedurally with `add_faces()` / `add_mesh()`. Parsing a live scene tree also works, but only **after** a frame has passed — before that you get `The root node needs to be inside the SceneTree` and a silent zero-poly bake. Parsing visual meshes also triggers a real performance warning, because it reads mesh data back from the RenderingServer. Bakes save to `.tres` and reload with identical vertex and polygon counts. `ImporterMesh` is instantiable outside the editor. In Summer the signature takes **three** arguments: ```gdscript theme={null} importer_mesh.generate_lods(normal_merge_angle, normal_split_angle, bone_transform_array) ``` The two-argument form is a parse error. A 4,224-triangle sphere produced **9 LOD levels** down to 8 triangles in 3ms. `get_mesh()` returns an `ArrayMesh` that saves and reloads cleanly. Note `generate_shadow_mesh` is not exposed. Value, bezier, method, position\_3d and rotation\_3d tracks can all be created programmatically, saved to `.tres`, and reloaded intact. Bezier handles, method names **and their argument arrays**, loop mode, step and length all survive exactly. `AnimationLibrary` round-trips too. Track type integers: `0` value, `1` position\_3d, `2` rotation\_3d, `5` method, `6` bezier. All four author and round-trip through `.tres`. `TileSet` keeps atlas sources, physics layers, terrain sets, navigation layers, custom data layers and per-tile collision polygons. One gotcha: `add_physics_layer()`, `add_terrain_set()`, `add_navigation_layer()` and `add_custom_data_layer()` return **void**, not the new index, so `var i := ts.add_physics_layer()` is a parse error. `Shader` source survives byte-identical and uniforms introspect correctly — but this is **parsing, not GPU compilation**. The dummy renderer never compiles the shader, so headless will not catch driver-level compile errors. `AudioBusLayout` works with the Dummy audio driver; bus volumes, mutes and effects all persist. This is the real story: **headless can simulate, it just cannot see.** Physics is entirely CPU-side and completely unaffected by the dummy renderer. 3D and 2D `intersect_ray`, `intersect_point` and `intersect_shape` all work, returning full hit dictionaries with position, normal, collider and RID. Rigid bodies actually fall under gravity. Prerequisite: `await physics_frame` after `add_child()`, or `direct_space_state` returns nothing. ## Importing assets **A file written directly to disk cannot be loaded until an import pass runs.** ``` ERROR: No loader found for resource: res://raw.png (expected type: unknown) at: _load (core/io/resource_loader.cpp:358) ``` This is the most common way agent-written assets fail. `ResourceLoader.exists()` returns `false` and `load()` returns null. **The best fix is to need no import at all.** Two routes avoid this entirely, and both are described under [shipping assets](#do-not-ship-a-game-that-depends-on-raw-source-files) below: * **`ResourceSaver.save()` to `.tres` or `.res`** — no import pass, no editor, no `.godot/`. * **Write a `.dds` or a `.po`** — the formats that load raw and ship as-is. Prefer those. They are simpler, faster, and free of the hazard below. When you do need the importer — it is the only shell route that generates `.import` sidecars — run the import pass: ```bash theme={null} /Applications/Summer.app/Contents/MacOS/Summer --headless --path /path/to/project --import ``` This writes the `.import` file next to your asset and the compiled `.ctex` into `.godot/imported/`. Afterwards `load()` returns a `CompressedTexture2D` and everything behaves normally. **Never run `--import` against a project whose editor is open.** `--import` is a full editor boot. It starts the local API server, which takes the machine's engine binding and mints a fresh auth token — so a client that believes it is talking to the open project can have its writes **land in the project you imported instead**, with no error. When the import exits, it leaves the binding pointing at a dead port, and the user's editor stays unreachable until something restarts. See [the binding hazard](#what-does-not-work) below for the full mechanism. Plain `--headless -s script.gd` is unaffected and completely safe. **`-s` script runs never create `.godot/` at all.** Only `--import` (or a normal editor or game run) builds the import database. If you have only ever run scripts, the directory does not exist yet. `--import` costs roughly 5 seconds even with nothing to do, about 15x a trivial script run. It is a **full editor boot** — it loads the editor layout and starts the local API server, with the binding consequences described above. Do not run it speculatively. **A long-lived headless editor does not notice files created after it booted.** `--headless --editor` is not a filesystem watcher. Its rescan is driven by the application receiving focus, and a headless process never gets a focus event. Assets added twelve seconds after boot were still unimported forty-five seconds later — none of them loadable. So a headless editor kept alive as a worker serves a **boot-time snapshot of the project, silently, for as long as it runs.** Either keep the process short-lived and start a fresh one per task, or call `EditorInterface.get_resource_filesystem()` and rescan explicitly. See [Editor Plugins](/extending/editor-plugins) for the working rescan sequence — the naive one is a silent no-op while a scan is already in flight. This is also the deeper cause of the familiar "the AI wrote my asset but the editor never registered it" problem. ### Do not ship a game that depends on raw source files There is a tempting shortcut: `Image.load_from_file("res://raw.png")` reads the file directly and needs no import pass at all. Equivalents exist for audio (`AudioStreamOggVorbis.load_from_file`), fonts (`FontFile.load_dynamic_font`) and models (`GLTFDocument.append_from_file`). **Exporting strips your raw source files. Every one of these loaders returns null in the shipped game.** The importer's *product* ships — the `.ctex`, the `.translation`, the imported scene — and ordinary `load()` finds it. The original `.png`, `.ogg`, `.ttf` or `.glb` does not ship at all, so anything reading the raw file fails. ``` # inside the exported pack res://assets/raw.png file_exists=false Image.load_from_file => ResourceLoader.load => CompressedTexture2D # the .ctex, works fine ``` `FontFile.load_dynamic_font` is the worst case: when the file is missing it returns **error code 0 with zero faces**. Success, and no font. Nothing fails at authoring time. Use these loaders for tooling and one-off scripts. Do not build a shipping game on them. **`--main-pack` is silently ignored if the current directory contains a `project.godot`.** The local project wins, the pack is never mounted, and nothing warns you. So the obvious way to check whether your exported game still works — run it against the pack from your project folder — **reports a false pass**, because it is reading your development files the whole time. Identical command, only the working directory differs: ```bash theme={null} cd my-project && Summer --headless --main-pack build/game.pck -s res://probe.gd # file_exists=true Image.load_from_file => Image <- reading the DEV project cd /tmp/empty && Summer --headless --main-pack ~/my-project/build/game.pck -s res://probe.gd # file_exists=false Image.load_from_file => <- the truth ``` **Always verify a pack from a directory that has no `project.godot` in it.** Three routes that survive export: 1. **Author a real resource and save it.** `ResourceSaver.save()` to `.tres` or `.res` needs no import pass, no editor, and no `.godot/` at all, and the result ships correctly. Verified for `ImageTexture`, `Image`, `AudioStreamWAV`, `AudioStreamOggVorbis`, `AudioStreamMP3`, `FontFile` (which embeds the whole TTF), `ArrayMesh`, `Translation` and `AudioBusLayout`. One trap: `PortableCompressedTexture2D` saves with error 0 and reloads **empty** — use `ImageTexture`. 2. **Import properly**, then use ordinary `load()`. The compiled `.ctex` always ships. 3. **Write a `.dds` directly.** It is the one image format that needs no import pass, loads raw, decodes to real pixels, and **ships as-is inside the pack** — a 128-byte header plus pixel data, emittable from a few lines of script. Load it with `ResourceLoader.load()`, which returns an `ImageTexture`; note `Image.load_from_file()` does *not* read DDS and returns null for it. `.godot/imported/` is **load-bearing, not a disposable cache.** Delete it and every imported asset returns null, even with all the `.import` files still present. Ignore any advice that tells you to clean it. ## Exporting a build Export works headless from a hand-written `export_presets.cfg`. Summer bundles macOS export templates inside the app, so no download is needed for a Mac build: ```bash theme={null} mkdir -p build /Applications/Summer.app/Contents/MacOS/Summer --headless --path . \ --export-release "macOS" build/game.zip ``` The resulting artifact genuinely runs, as a real template build with `OS.has_feature("template") == true` and `Engine.is_editor_hint() == false`. `--export-pack` produces a `.pck` instead. **Only the macOS template ships with the app.** Windows, Linux, Android and iOS exports all fail with "No export template found" until you supply templates yourself. Templates are searched for in `Summer.app/Contents/Resources/export_templates/` and then in `~/Library/Application Support/Godot/export_templates/` — note **`Godot`**, not `Summer`. A `~/Library/Application Support/Summer/export_templates/` directory may exist on your machine; the engine never reads it. Putting templates there does nothing. Web export is not available on this build at all. Summer ships as a Mono (C#/.NET) build, and Godot 4 does not support exporting to Web from a Mono build. This is an architectural property of the binary, not a missing template. Use `export_filter="all_resources"`. The dependency-based `resources` filter exits non-zero and produces an empty 112-byte pack for a project whose main scene has no resource dependencies. Be aware `all_resources` packs everything, including every stray `.gd` file in the project. Two errors print at the start of every export and are harmless: `Parent node is busy setting up children, add_child() failed` and `Condition "!is_inside_tree()" is true` from `http_request.cpp`. ## What does not work | Capability | Status | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Rendering, screenshots, any pixel readback | **Impossible headless.** See the warning at the top | | `--write-movie` | **Crashes** with signal 11 under `--headless` | | Performance measurement | Meaningless. Draw calls read `0.0`, FPS reads `1.0`, video adapter name is empty | | UI and Control layout measurement | **Wrong.** The headless viewport is not your configured size — it reports a small placeholder that `--resolution` does not override, while `ProjectSettings` still reports the real one. Every anchor, margin and global position measured headless is meaningless | | `LightmapGI.bake()` | **Does not exist** in the scripting API. The node instantiates and every property setter is exposed, but `bake` is absent from the method list — calling it is a *parse-time* failure | | `OccluderInstance3D.bake_single_node()` | Same. Not exposed | | `EditorScript`, `EditorPlugin`, `EditorInterface`, `EditorFileSystem` | `can_instantiate()` is false for all of them outside the editor | `Engine.has_singleton("EditorInterface")` returns **true** while `Engine.get_singleton("EditorInterface")` fails with `Can't retrieve singleton 'EditorInterface' outside of editor`. Do not use `has_singleton` as your guard — use `Engine.is_editor_hint()`. Anything needing editor context has a supported route. Adding `--editor` gives you a live `EditorNode` and the full `EditorInterface` — 70 bound methods including `save_scene`, `open_scene_from_path` and `get_resource_filesystem()` — even under `--headless`, and even with no plugin installed: ```bash theme={null} Summer --headless --editor --path /path/to/project -s res://tool.gd ``` **`--editor` is not safe to run casually. Plain `--headless` is.** On current builds, adding `--editor` starts Summer's local API server, which **overwrites `~/.summer/api-port` and regenerates `~/.summer/api-token`**. That pair is how the CLI and your agent find a running editor. A headless editor takes the binding for itself, rotates the token underneath whatever was already running, and on exit leaves the file pointing at a dead port. **This is not only a broken lookup — a client can write into the wrong project.** The identity check rejects a request that declares which project it means, but **accepts one that does not declare anything**, and applies it to whichever project currently holds the binding. There is no error and no warning. Work silently lands in someone else's project. `--import` and `--export-*` do the same thing. They are full editor boots, not lightweight passes. Running `--import` on one project was measured rotating the token while another project held the binding. Which invocations are affected, measured: | Invocation | Takes the binding | | ------------------------------------ | ----------------- | | `--headless -s script.gd` | **No — safe** | | `--headless --editor …` | Yes | | `--headless --import` | Yes | | `--export-release` / `--export-pack` | Yes | Plain `-s` headless scripting — the bulk of this page — is unaffected. The hazard is specific to the invocations that boot the editor. If your agent reports the engine as disconnected while it is plainly running, this is the first thing to check. Restarting the real editor republishes the binding. A later build suppresses this for batch-mode instances; until you have confirmed your build does, assume it does not. Plain `--headless -s script.gd` never starts that server and has none of these effects. See [Editor Plugins](/extending/editor-plugins) for the full editor-context story, including the enable routes and what `EditorInterface` unlocks. Draw calls and the video adapter name are useful liveness probes. If `Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME)` reads `0.0` or `RenderingServer.get_video_adapter_name()` is empty, you are not rendering and never will be. ## Performance Startup overhead is roughly 0.3 to 0.4 seconds, low enough to call the binary in a tight loop. | Command | Typical | | --------------------------------- | ------- | | Trivial `-s` script | 0.41s | | Script doing collision generation | 0.63s | | `--import` with nothing to do | 5.6s | | `--export-release`, 50MB zip | 6.4s | ## For AI agents If you are an agent automating Summer, the things that will silently burn you — note that every one of them fails by *appearing to succeed*: 1. **`--headless` renders nothing.** `get_texture()` looks fine; `get_image()` returns null. Never plan around a headless screenshot. 2. **Use `_init()`, never `_run()`.** `_run()` hangs with zero output. 3. **Exit code 0 means nothing, and a runtime error means no exit code at all.** Parse errors and missing script files exit 0, so grep stderr. Runtime errors hang the process forever, so also impose an external wall-clock timeout — stderr cannot help you if the process never returns. 4. **`await process_frame` after `add_child()`**, or in-tree and physics APIs fail before the node is really in the tree. 5. **Write a file, then `--import` it**, or `load()` will not find it. 6. **Never read a raw source file at runtime.** Exporting strips them. `Image.load_from_file` and friends return null in the shipped game, and `FontFile.load_dynamic_font` returns error 0 with zero faces. 7. **Verify a pack from an empty directory.** `--main-pack` is silently ignored when the working directory holds a `project.godot`, so checking your export from the project folder reports a false pass. Find your own binary with `OS.get_executable_path()` rather than assuming a path, and never assume it is called `godot`. # Changelog Source: https://docs.summerengine.com/changelog/overview What's new in Summer Engine. Release notes and updates. ## Crafty is now Summercraft, and the Crafty SDK is now the Summer SDK The publishing platform is called **Summercraft** and the SDK you build games against is the **Summer SDK**. Code symbols moved with the copy: the `Crafty` autoload is now `Summer`, `CraftyGame` is now `SummerGame`, and the `crafty_sdk` manifest key is now `summer_sdk`. Existing games need a mechanical rename — the [Summer SDK Naming](/api-reference/summer-sdk/naming) page maps every old identifier to its replacement. Every previously published SDK URL redirects to its new address. This is a naming change, not an engine release. No Summer Engine behavior changed. ## The right edit, even with a team at work Summer now targets scene changes at the exact file you asked for instead of depending on whichever editor tab happens to be open. Scene operations carry an explicit target, save once at the transaction boundary, and report evidence of what actually changed. ## Safer parallel work Multiple agents can work across a project without routine project-wide blocking. Broad restores and Studio imports keep their stronger safety boundaries, while ordinary edits can continue concurrently. File writes stage and verify complete content before replacing the live file. ## Cleaner stops and reconnects Stopping an agent no longer leaves later messages waiting behind stale running state. Completed results remain attached to the request that produced them through reconnects, and failed scene dependencies report the exact path so Summer can repair and retry. This release brings macOS to the same 0.5.55 desktop version as Windows. It includes the latest bridge and MCP reliability fixes; there are no project migrations or new settings. ## Your work survives the reconnect Summer now keeps completed edits and their results attached to the correct editor and project when the chat or desktop bridge reconnects. If the embedded web interface reloads after an operation was accepted, Summer can recover the original result instead of losing it or guessing whether the change happened. ## Safer project changes Requests now carry the exact project identity and connection generation that accepted them. Completed operations keep durable receipts, so an uncertain retry cannot apply the same scene or file mutation twice. Stale requests from an older connection are rejected instead of reaching the open project. ## Clearer progress after interruptions Live progress and completed steps remain visible through temporary connection failures. Scene files opened from chat or the FileSystem dock also reveal the correct 2D or 3D workspace more reliably. This is a required desktop reliability update for Windows and macOS. There are no new settings or migration steps; install the update and continue working in the same projects and chats. ## Build games by drawing on them Design Mode is a new way to work inside your scene. Click a node in 2D or 3D and a chat bar floats on the viewport. Describe what you want changed and the message goes into the same chat you already have in the sidebar. Same model, same history, same project context. You can also draw on the viewport. Circle an area, sketch where something should go, mark a problem spot. Summer captures a screenshot of your annotation and sends it with your message. The AI sees your point of view, not a generic scene dump. Fullscreen Iteration Mode fills the window with your scene and keeps a bar at the bottom. Collapse the chat sidebar or press Cmd+Shift+M (Ctrl+Shift+M on Windows). You stay in the game view while the conversation continues underneath. ## Skills teach Summer how you build Skills are short playbooks Summer reads when the moment calls for it. Lighting a 3D scene, scaffolding a survivors game, debugging physics, shipping performance fixes. Summer ships a library covering the full game dev workflow. Type `/` in the chat to trigger a skill. `/make-game`, `/debug`, `/optimize`, and `/assets` are built in. Open Settings → Skills to read any playbook, customize it for your style, or write a new one. Skills scoped to a project override your global skills, which override Summer defaults. When you say "remember how we did this," Summer can draft a skill and show it in a card. Nothing saves until you approve. Facts about your game go to Memory. Repeatable workflows become skills. ## A rebuilt agent team The main agent is the orchestrator. It plans, talks to you, and hands work to specialists that run in parallel. **Explore** reads your project and answers focused questions. **Builder** is the hands-on expert for scenes and gameplay. It writes scripts, edits scenes, sets the main scene, binds input, and runs compile checks. **Studio Asset Agent** generates images, 3D, audio, and animation. **Summer expert** verifies engine work and repairs what is broken. **General Advisor** is the slower second opinion when the plan is unclear. Each specialist streams live in a side panel. You can follow the transcript, continue a thread, steer mid-run, or stop a run. Results fold back into the main chat as summaries. Long asset jobs still run on background workers and wake the chat when they finish. ## Permission modes You choose how much runs without asking. **Manual** approves every edit, command, and generation. **Accept edits** auto-runs file changes but asks before spending credits. **Auto approve** (default) runs edits and generation but still blocks destructive actions. **Bypass** runs everything except hard safety blocks like protected files and catastrophic shell commands. ## Everything else in 0.5.47 **Context breakdown.** See how much of the context window goes to system prompt, tools, rules, skills, subagents, and conversation. **Dictation.** Hold the mic in the composer, speak your prompt, release to insert. **Work visibility.** The chat shows what Summer is doing right now, including when it is waiting on a subagent. **Reliability.** Expert runs persist across reloads. Chat history finds projects by fingerprint. The update banner tracks slow applies correctly. Design Mode overlay stays transparent on Windows WebView2. **Under the hood.** AI SDK 7, a custom in-process expert harness, first-class OpenAI-family adapters, and Auto mode on GPT-5.6 Luna at high reasoning. The old queued delegation path is gone. Railway now handles long asset generation only. ## Summer can see its own work We rebuilt the whole loop of making a change, looking at it, and fixing it. Summer now verifies its work with the lightest tool for the job: does it compile, does it look right, does it run, is it interactive. It boots your game quietly instead of grabbing your editor tab, reads the real errors, looks at an actual frame, and tells you what it sees. When it can't see something, it says so instead of guessing, so you no longer get a confident "done" on a broken screen. Game capture now works reliably in the engine and through MCP and Claude Code. ## It works on its own for 30 minutes to 2 hours Long builds used to hit a wall after about 12 minutes. Now Summer keeps working unattended for 30 minutes up to around 2 hours, continuing across steps automatically without you clicking anything. The run loop is hardened so it can't get stuck or repeat work on resume. ## More reliable * The most common error, "engine disconnected," was wrong most of the time. The engine was alive and we wrongly reported the connection as dead. Summer now confirms the engine is actually gone before showing the error, and retries busy operations instead of giving up. * If the engine drops mid-run, your chat history and work in progress are still there when you reopen. * Fixed crashes some users hit when importing 2D and 3D assets. ## Chat and models * The "Continue" button no longer shows up everywhere. You get at most one clear action on the newest message, and a dropped engine shows a real "Reconnecting" state. * Shell command approvals now work like Claude Code: safe read-only commands run automatically, others show the reason with a countdown and an "always allow" option, and skipping never freezes the turn. * The model picker shows the cost and how many messages you have left before you switch to a premium model. * Scrolling is smooth again, and snapshot cards are collapsed by default so chats stay light. ## Asset store * Click any asset for an instant in-place preview. No more jumping to a separate page. * Fixed a crash that could happen while scrolling the store. * 50,000 free assets in the library. ## Billing * You are charged only for the usage your models actually bill us for. A run that crashes with no cost is free. * Upgrading now changes your plan in place instead of creating a second subscription. * A slow balance check no longer shows paying users a false "out of credits" message. * "Upgrade / Manage plan" is now easy to find in your account menu, and USD top-ups support Link and PayPal. ## Security and privacy * Fixed an issue where an AI-edited image could be served to the wrong user. Image storage is now isolated per account. # Troubleshooting Source: https://docs.summerengine.com/desktop/troubleshooting Solutions to common Summer Engine issues ## Installation Issues ### Summer Engine won't start **Symptoms**: Application crashes on launch or shows error dialog **Solutions**: * Update your graphics drivers * Run as administrator (Windows) or with sudo (Linux) * Check system requirements are met * Disable antivirus temporarily during installation ### Missing dependencies **Symptoms**: "DLL not found" or library errors **Solutions**: * Install Visual C++ Redistributables (Windows) * Update to latest macOS version (macOS) * Install required packages: `sudo apt install libgl1-mesa-dev` (Ubuntu) ## AI Chat Issues ### AI not responding **Symptoms**: Chat shows "Thinking..." indefinitely **Solutions**: * Check internet connection * Verify account authentication * Restart Summer Engine * Check if you've hit usage limits ### Poor AI responses **Symptoms**: AI doesn't understand requests or makes wrong changes **Solutions**: * Be more specific in your requests * Provide context: "In the player script, make the jump higher" * Break complex requests into smaller parts * Check if project indexing is complete ## Performance Issues ### Slow project loading **Symptoms**: Long delays when opening projects **Solutions**: * Close other resource-intensive applications * Exclude project from antivirus scanning * Use SSD storage for better performance * Clear Summer Engine's cache: `~/.summer/cache/` ### High memory usage **Symptoms**: System becomes sluggish with Summer Engine open **Solutions**: * Close unused projects * Reduce viewport quality in settings * Limit concurrent AI operations * Increase system RAM if possible ## Project Issues ### Changes not applying **Symptoms**: AI says it made changes but nothing happened **Solutions**: * Check if files are read-only * Ensure you have write permissions * Look for errors in the output panel * Try manual undo/redo to refresh ### Lost work **Symptoms**: Recent changes disappeared **Solutions**: * Check version control history * Look in `~/.summer/backups/` folder * Use Summer Engine's built-in recovery tool * Enable auto-save in preferences ## Authentication Problems ### Can't sign in **Symptoms**: Login fails with valid credentials **Solutions**: * Reset password on website * Clear stored credentials in Summer Engine * Check firewall isn't blocking Summer Engine * Try signing in through browser first ### API key issues **Symptoms**: API calls fail with authentication errors **Solutions**: * Regenerate API key in dashboard * Check key format (no extra spaces/characters) * Verify account tier supports API access * Test with curl first to isolate issues ## Getting Help If these solutions don't work: Get help from other users and the Summer Engine team Direct support from our team ## Bug Reports When reporting bugs, include: * Summer Engine version * Operating system * Steps to reproduce * Error messages or logs * Project details (if relevant) **Log locations**: * Windows: `%APPDATA%/Summer/logs/` * macOS: `~/Library/Application Support/Summer/logs/` * Linux: `~/.local/share/Summer/logs/` # Account & Billing Source: https://docs.summerengine.com/essentials/account-billing Manage your Summer account, subscription, billing, and spend limits ## Overview Manage your Summer account through the [Dashboard](https://summerengine.com/dashboard). From there you can view your subscription, update payment details, set spend limits, and access your projects. Go to summerengine.com/dashboard to manage your account ## Billing ### How do I access billing settings? Access the billing portal through the [Dashboard](https://summerengine.com/dashboard) by clicking **Billing & Invoices** in the left sidebar. The **Spending** tab lets you view your plan, included usage, and on-demand settings. The **Manage** button opens Stripe's secure portal for payment method, subscription, and invoice management. ### What are Summer Engine's billing cycles? Billing cycles run monthly, starting on your subscription date. Included AI usage resets at renewal. ### Where can I find my invoices? Find all billing history in the Stripe portal. Click **Manage** on the Spending page, then view and download current and past invoices from the portal. ### How do I update my billing information? Update payment method, address, and tax information through the Stripe portal (opened via **Manage** on the Spending page). We use Stripe for secure transactions. Changes only affect future invoices. ### How do I cancel my subscription? Cancel through the Billing & Invoices page by clicking **Manage subscription** then **Cancel subscription** in the Stripe portal. Access continues until the end of your current billing period. ### I'm having other billing issues. How can I get help? For billing questions, email [founders@summerengine.com](mailto:founders@summerengine.com) from the email linked to your account. Include your account details and concerns. ## Spend Limits Set spending limits to control costs and prevent unexpected charges. Spend limits help you manage usage and stay within budget. Spend limits apply to **on-demand usage only**. Included usage in your plan does not count towards spend limits. ### Viewing spend limits View your current spend limits in the [Dashboard](https://summerengine.com/dashboard) under the **Spending** tab. On-demand usage must be enabled to view and set spend limits. Free users must upgrade to a paid plan first before they can enable on-demand. ### Updating spend limits You can update spending limits at any time: * **Increase limits**: Takes effect immediately * **Decrease limits**: Takes effect immediately, but won't affect usage that has already occurred * **Remove limits**: Set limit to "Unlimited" to remove on-demand limits ### Spend limit behavior When your spending limit is reached: * AI features stop working until the next billing cycle * You see a notification indicating your limit was reached * Usage resumes automatically at the start of the next billing cycle ### Individual plans Customers with Pro, Pro+, and Ultra subscriptions can set monthly spend limits for on-demand usage. Free users must upgrade before enabling on-demand. ## Need Help? For billing questions, account issues, or feature requests: * **Email**: [founders@summerengine.com](mailto:founders@summerengine.com). We respond personally * **Discord**: [Join our community](https://discord.gg/yUpgtxnZky) for quick answers Include your account email and any relevant details so we can help faster. # Authentication Source: https://docs.summerengine.com/essentials/authentication Set up your Summer Engine account and API access ## Creating Your Account Summer Engine requires an account to access AI features and sync your projects. Visit [summerengine.com](https://summerengine.com) and create a free account. Check your email and click the verification link. In Summer Engine, open any project and navigate to the 'Chat' menu in the sidebar. This will open a deeplink to authenticate your account automatically. ## Authentication Process Summer Engine uses a streamlined authentication system: 1. **Open a Project**: Create or open any project in Summer Engine 2. **Access Chat**: Click on the 'Chat' menu in the sidebar 3. **Automatic Authentication**: Summer Engine will open a secure deeplink to authenticate your account 4. **Return to Summer Engine**: Once authenticated, you'll be redirected back to Summer Engine with full access ## API Key Setup For advanced integrations and API access: ```bash Terminal theme={null} # Set your API key as an environment variable export SUMMER_API_KEY="your-api-key-here" ``` ```javascript JavaScript theme={null} // Use in your applications const summer = new SummerAPI({ apiKey: process.env.SUMMER_API_KEY }); ``` ## Account Tiers * Limited agent use and AI asset creations * Local MCP workflows stay free * Community support * Extended agent usage and higher AI asset creation limits * Local MCP workflows stay free * Asset search across the library * Priority support See [Pricing](/essentials/pricing) for full plan details including Pro+ and Ultra tiers. ## Troubleshooting **Can't sign in?** * Check your email and password * Ensure your account is verified * Try resetting your password **API key not working?** * Verify the key is correctly set * Check your account tier supports API access * Ensure the key hasn't expired Need help? Contact us at [founders@summerengine.com](mailto:founders@summerengine.com). For billing, subscription changes, or payment updates, see [Account & Billing](/essentials/account-billing). # Frequently Asked Questions Source: https://docs.summerengine.com/essentials/faq Answers to common questions about Summer. Browse by topic or search. ## FAQ Overview Common questions about Summer, organized by topic. Each question links to a detailed answer. ## About Summer The AI game engine. Build games by describing them in natural language. Unified experience, safe operations, specialist agents, and project intelligence. AI directly modifies your game. Summer is for everyone. Vibe coders and professional developers alike. Yes. We shipped Don't Pray on Steam in 2.5 months. It's a commercial product. Gentle to advanced. Vibe coding has near-zero curve. Master the engine with AI as your tutor. Summer is designed for indie and mid-scale projects. Sweet spot: 3-12 months for projects that traditionally take 1-7 years. Summer is a full game engine, not an AI addon. Deeper integration, better context, safer operations. ## Technical Summer uses familiar formats, but project compatibility ranges are not fully measured. Commit first and verify imports, plugins, native extensions, and exports. Open a committed copy in Summer Engine and review the first import. Version-sensitive plugins and native extensions need explicit testing. Claude, GPT-5, Gemini, Meshy, ElevenLabs, and more. Choose your models in settings. Great for prototyping and indie games. Learn the tradeoffs and when to use human artists. Yes. Describe what you want and Summer Engine writes the code. AI game dev and vibe coding for games. Expert AI agents for 3D modeling, audio design, and complex systems. Brought in on demand. AI indexes and understands your entire codebase, scenes, assets, and relationships automatically. AI changes go through safe APIs. Some tasks still require manual work. Learn what works well and what doesn't. Yes, with limitations. Basic multiplayer networking works with AI assistance. Yes. Import your own 2D art, 3D models, and audio. AI generation is optional. Yes. Export to HTML5/WebAssembly. Deploy to itch.io, your website, or any static host. Use AI to research your project, create a plan, then rebuild in Summer Engine. Fresh projects: easy. Large projects: more planning. ## Account & Support Encrypted in transit and at rest. Privacy Mode stops us using your code to train our models, and is available on paid plans. It is off by default. Free to download and try. Free tier with core AI features. Premium features available through subscription. Founders respond personally. Email, Discord, and more. Download Summer Engine, create a project, describe what you want. No coding required. AI does the rest. Export your game, then submit to Steam. \$100 Steam Direct fee, 1-3 day approval. Full guide inside. Enable ETC2 ASTC texture format, create mobile export preset, configure signing. iOS requires Mac and Apple Developer account. *** 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. # Your First AI Chat Source: https://docs.summerengine.com/essentials/first-chat Learn how to use Summer Engine's AI to build game elements through conversation ## Starting Your First Chat Once you have Summer installed and a project open, you can start using AI to build your game. Click the chat icon in the toolbar or press `Ctrl+Shift+A` (Windows/Linux) or `Cmd+Shift+A` (macOS). Type a natural language description of what you want to add or change in your game. Summer will show you what it plans to do. Click "Apply" to make the changes. ## Example Conversations Here are some examples to get you started: ### Adding Objects ``` You: Add a red cube to the center of the scene Summer: I'll create a MeshInstance3D with a BoxMesh and red material at position (0,0,0). ``` ### Setting Properties ``` You: Make the player move twice as fast Summer: I'll find your player script and increase the speed variable from 5.0 to 10.0. ``` ### Creating Scripts ``` You: Add a health system to the player that starts at 100 Summer: I'll create a health.gd script with health = 100 and damage/heal functions. ``` ## Best Practices **Be specific**: Instead of "make it better", try "increase the jump height" or "add a blue glow effect". **Ask for explanations**: Add "and explain what you did" to understand the changes. **Review changes**: Always check what Summer did before continuing. Use Ctrl+Z to undo if needed. ## Understanding AI Responses Summer will typically: 1. **Analyze** your request and current project state 2. **Plan** the specific changes needed 3. **Execute** the changes through the editor 4. **Explain** what was done and why ## Common Patterns ### Scene Manipulation * "Add a \[object] to the scene" * "Move the \[object] to \[position]" * "Scale the \[object] by \[factor]" ### Code Generation * "Create a script that \[does something]" * "Add a function to \[do something]" * "Fix the bug where \[describe issue]" ### Project Organization * "Create a new scene for \[purpose]" * "Organize these nodes into groups" * "Add this to the autoload" ## Next Steps Learn about all the things Summer Engine's AI can do Understand how Summer Engine learns about your project # Install Summer Engine Source: https://docs.summerengine.com/essentials/installation Install Summer Engine on macOS or Windows, verify the editor, and continue to your first Summer game. ## System Requirements Summer runs on Windows and macOS with the following minimum requirements: * **OS**: Windows 10+ or macOS 10.14+ * **RAM**: 4GB minimum, 8GB recommended * **Storage**: 2GB available space * **Graphics**: OpenGL 3.3 support ## Download Summer Engine Get the latest Summer Engine installer from our website. ### Alternative: Install via CLI If you use Cursor, Claude Code, or any MCP-compatible AI tool, you can install Summer Engine from the command line: ```bash theme={null} npx -y summer-engine@latest install ``` This downloads and installs Summer Engine (macOS: `/Applications/Summer.app`; Windows: the installer-selected location). No global npm install is required. After installation: ```bash theme={null} npx -y summer-engine@latest login npx -y summer-engine@latest run ``` For MCP setup (connecting your IDE to Summer Engine), see [MCP Setup](/mcp/setup). ## Installation Steps Visit [summerengine.com](https://summerengine.com) and download the installer for your operating system. Double-click the downloaded file and follow the installation wizard. Open Summer Engine from your applications folder or Start menu. Click "New Project" and choose a template to get started. ## Verify Installation Once installed, you can verify everything is working by: 1. Opening Summer 2. Creating a new project from a template 3. Testing the AI chat with a request such as “Add a cube to the scene” If you encounter any issues, check our [troubleshooting guide](/desktop/troubleshooting) or reach out on [Discord](https://discord.gg/yUpgtxnZky). ## Existing-project compatibility Summer Engine uses standard project files. Compatibility, migration, extensions, and the measured upstream base live in the dedicated [compatibility reference](/reference/compatibility). Do not infer a project-version minimum from a copied setup guide. Review the complete creator journey. Create a project and begin with GDScript. # Pricing Source: https://docs.summerengine.com/essentials/pricing Summer Engine plans, included AI usage, free local MCP workflows, and what happens when you hit your AI usage limit You can try Summer Engine for free or purchase an individual plan. Go to summerengine.com/pricing to choose a plan ## Individual Plans | Plan | Price | AI Usage | Local MCP | | --------- | -------- | ------------------------------------------------------------- | --------- | | **Free** | Free | Limited hosted agent use + limited AI asset creations | Free | | **Basic** | \$5/mo | \$5 of hosted AI usage each renewal | Free | | **Pro** | \$20/mo | Extended hosted agent usage + higher AI asset creation limits | Free | | **Pro+** | \$60/mo | 3x Pro usage | Free | | **Ultra** | \$200/mo | 10x Pro usage | Free | Yearly billing saves 20% on Pro, Pro+, and Ultra. Basic is monthly only. All plans include the free desktop app and local MCP tools (Cursor, Claude Code, Devin Desktop, etc.). Paid plans increase hosted Summer AI and generation limits. Basic is a live paid plan, but it is not shown on the public pricing page. You will see it inside the app — at upgrade prompts and in the billing screen, where it is also offered as an alternative to cancelling. It counts as a paid plan, so it unlocks the paid model selector and Summer Studio. ## Summer Cloud storage Every plan includes [Summer Cloud](/guides/summer-cloud) storage for syncing projects across machines (Summer Cloud is currently in research preview): | Plan | Cloud storage | | ----- | ------------- | | Free | 1 GiB | | Basic | 5 GiB | | Pro | 20 GiB | | Pro+ | 100 GiB | | Ultra | 500 GiB | Storage counts the distinct bytes your projects reference (duplicate files cost once). Hitting the limit blocks new pushes; downloads and restores always work, and your data is never deleted for billing reasons. ## How usage works ### AI usage limits AI usage is consumed when you use Summer Agent (chat, code generation, asset generation) or cloud MCP tools like asset search. Different models cost different amounts. View your usage in the [Dashboard](https://summerengine.com/dashboard) under **Spending**. ### Local MCP Local MCP workflows stay free. MCP lets an external agent operate the desktop app through tools like `summer_add_node`, `summer_set_prop`, and `summer_play`. Hosted AI and generation features still use your plan's AI usage. ## What happens when I reach my limit? ### When you reach your AI usage limit When you exceed your included usage, you'll be notified in the editor and can choose to: * **Add on-demand usage** — Continue using Summer at the same API rates with pay-as-you-go billing * **Upgrade your plan** — Move to a higher tier for more included usage On-demand usage is billed monthly. Requests are never downgraded in quality or speed. See [Account & Billing](/essentials/account-billing) for how to set spend limits. ## Need help? * **Email**: [founders@summerengine.com](mailto:founders@summerengine.com) * **Discord**: [Join our community](https://discord.gg/yUpgtxnZky) # Editor Plugins Source: https://docs.summerengine.com/extending/editor-plugins Write a @tool EditorPlugin in Summer to get full EditorInterface: force reimports of agent-written files, bake occluders, save scenes from code, register autoloads. Templates, the three ways to enable a plugin, and the traps. An editor plugin is the supported way to reach engine capability that ordinary scripts cannot touch. Two small files and one line in `project.godot` give you the whole `EditorInterface`: the resource filesystem, forced reimports, scene saving, autoload registration, and the built-in editor plugins that do bakes. If you are automating Summer and have hit "that API is not exposed to scripting", this page is the way through. For everything that works *without* editor context, see [Headless Scripting](/automation/headless) first — it is cheaper and has no editor to keep alive. ## The minimal plugin Two files. Copy both exactly. These are the files used to verify everything on this page. `addons/summer_demo/plugin.cfg`: ```ini theme={null} [plugin] name="Summer Demo" description="Example plugin." author="you" version="1.0" script="plugin.gd" ``` `addons/summer_demo/plugin.gd`: ```gdscript theme={null} @tool extends EditorPlugin func _enter_tree() -> void: print("plugin loaded") func _exit_tree() -> void: print("plugin unloaded") func _enable_plugin() -> void: # Fires only on a live enable, NOT on editor startup. Register autoloads here. pass ``` **`@tool` is mandatory and the base class must be `EditorPlugin`.** Without `@tool` the script never runs in the editor. Neither mistake produces an error the enabling caller can see — see [Verification is not optional](#verification-is-not-optional). The `script=` value in `plugin.cfg` is resolved relative to the `plugin.cfg` directory, so `script="plugin.gd"` means `addons/summer_demo/plugin.gd`. ## Enabling a plugin Writing the files does nothing on its own. There are three ways to enable one, and they are not interchangeable. | | Route A: write `project.godot` | Route B: `EnableEditorPlugin` operation | Route C: `set_plugin_enabled()` | | -------------------------- | ------------------------------ | --------------------------------------------------------------- | ----------------------------------------- | | Called from | Any file write | Summer's AI, against a running editor | GDScript, inside an already-loaded plugin | | Editor must be running | No | **Yes** | Yes | | Takes effect | Next editor start | Deferred, one idle frame | Immediately | | `_enable_plugin()` fires | **No** (measured) | Same code path as the Plugins checkbox; not measured end-to-end | **Yes** (measured) | | Autoloads register | **No** | See above | **Yes** (measured) | | Failure reported to caller | No | **No** — see below | Yes, in the same script | ### Route A — write `editor_plugins/enabled` into `project.godot` Add this section to `project.godot`: ```ini theme={null} [editor_plugins] enabled=PackedStringArray("res://addons/summer_demo/plugin.cfg") ``` At the next editor start the plugin loads, `_enter_tree()` fires, and `EditorInterface` and `get_resource_filesystem()` are live. **`_enable_plugin()` does not fire on a startup enable.** Reproduced on every startup-enable run. Anything you put in `_enable_plugin()` — most importantly `add_autoload_singleton()` — never executes, so the autoload is never registered and scripts referencing it fail to parse. Put work you need on every load in `_enter_tree()`. Use `_enable_plugin()` only for one-time registration, and enable via Route B or Route C when you need it to run. **Never write `[editor_plugins]` into a project that has never been opened.** A brand-new project that has `[editor_plugins]` present and no `.godot/` cache directory aborts during startup, before `EditorNode` exists: ``` ERROR: Parameter "singleton" is null. at: is_cmdline_mode (editor/editor_node.cpp:8048) ``` Reproduced twice. The fix is ordering: open the project once **without** the plugin entry so the cache is built, then add the section. That works every time. ### Route B — the `EnableEditorPlugin` operation This is the path Summer's own AI takes when you ask it to enable a plugin. It takes one argument, `pluginPath`. A bare name normalises — `summer_demo` becomes `res://addons/summer_demo/plugin.cfg` — and a full `res://` path passes through unchanged. It requires a live editor. Without one it returns `EditorNode not available (engine not in editor mode?)`. It is idempotent: an already-enabled plugin returns `{ok: true, alreadyEnabled: true}` rather than an error. Pre-checks run synchronously and return structured errors you can act on: | `code` | Meaning | | ------------------- | ---------------------------------------------------- | | `CFG_MISSING` | No `plugin.cfg` at that path | | `CFG_PARSE_FAILED` | The `plugin.cfg` is not valid config-file syntax | | `NO_SCRIPT_KEY` | No `script=` entry under `[plugin]` | | `EMPTY_SCRIPT_PATH` | `script=` is present but empty | | `SCRIPT_MISSING` | The script named by `script=` does not exist on disk | **`ok: true` means "queued", not "loaded".** The actual enable is deferred to the next idle frame and the response is already on the wire before it runs — the reply carries `{ok: true, deferred: true, addonPath: ...}`. If the deferred enable then fails — a script parse error, a missing `@tool`, the wrong base class — **the caller is never told**. The failure is logged to the editor console and the `ok: true` is not retracted. What you observe instead is a GDScript parse error on an autoload identifier, one or two tool calls later, with nothing pointing back at the plugin. Treat the acknowledgement as a receipt for a request, and verify separately. **Enabling a plugin through Summer's AI rewrites the whole plugin list.** `editor_plugins/enabled` is a `PackedStringArray` that is **replaced**, not merged. The in-app enable path writes the array and then dispatches the operation. If the array it writes does not contain the user's other plugins, those plugins are silently disabled. Read `project.godot` first, collect every existing entry, and pass them through so they are preserved. This applies to Route A by hand as well: you are writing the entire list, not appending to it. ### Route C — `EditorInterface.set_plugin_enabled()` from GDScript Called from inside a plugin that is already loaded, this enables a further plugin with `_enable_plugin()` firing. Measured: the second plugin's `_enter_tree()`, `_enable_plugin()` and its `add_autoload_singleton()` all ran, and `project.godot` on disk gained the second entry. ```gdscript theme={null} @tool extends EditorPlugin func _enter_tree() -> void: EditorInterface.set_plugin_enabled("res://addons/other_plugin/plugin.cfg", true) print("other enabled: ", EditorInterface.is_plugin_enabled("res://addons/other_plugin/plugin.cfg")) ``` One bootstrapping plugin can therefore enable as many further plugins as it likes, correctly, from GDScript, with no editor restart. If you need `_enable_plugin()` semantics and want the result in the same script where you can check it, this is the route. ## Verification is not optional None of the enable routes reliably tell you the plugin actually loaded. Route A defers to the next startup, Route B acknowledges before the work runs, and a broken plugin produces an editor that behaves exactly as if nothing was asked for. After enabling, verify with one of these: * Dispatch the sibling operation **`IsEditorPluginEnabled`** with the same `pluginPath`. It reports the editor's live state and returns `{ok: true, enabled: , addonPath: ...}`. * Read `project.godot` back and confirm your path is in `editor_plugins/enabled`. * From GDScript inside the editor, call `EditorInterface.is_plugin_enabled(path)`. A plugin that prints something recognisable in `_enter_tree()` also gives you a second, independent signal in the editor console. ## What EditorInterface unlocks Everything below was measured against the shipped binary. | Capability | Status | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `get_resource_filesystem().scan()` registering an agent-written `.png` | **Works.** The `.import` file appears, `ResourceLoader.load` returns a `CompressedTexture2D`, and `resources_reimported` fires | | `reimport_files()` on a registered file | **Works** | | `reimport_files()` on a file the filesystem has never seen | **Blocked**: `ERROR: Can't find file '...' during file reimport.` | | `scan()` while a scan is already in flight | **Silently dropped.** The call is a no-op with no error | | `EditorInterface.save_scene()` persisting nodes added from code | **Works** | | `open_scene_from_path()`, `get_open_scenes()`, `save_all_scenes()` | **Works** | | `EditorFileSystem.scan_changes()` from GDScript | **Not bound.** C++ only | | `LightmapGI.bake()` from GDScript | **Not bound**, in the editor or at runtime. This is upstream Godot behaviour, not a Summer change | | `OccluderInstance3D.bake_single_node()` / `bake_scene()` | **Not bound** | | Occluder baking via the built-in `OccluderInstance3DEditorPlugin` | **Works**, including headless with no GPU | | Lightmap baking via the built-in `LightmapGIEditorPlugin` | **Reachable**, but fails under `--headless`. Unverified in the GUI editor — see below | The bound methods on `EditorFileSystem` are `scan`, `reimport_files`, `update_file`, `get_filesystem`, `get_file_type`, `is_scanning` and `get_scanning_progress`. Anything else you have seen in the C++ is not callable from GDScript. `EditorInterface` itself exposes 70 bound methods, including `save_scene`, `save_scene_as`, `save_all_scenes`, `open_scene_from_path`, `reload_scene_from_path`, `close_scene`, `edit_node`, `edit_resource`, `set_plugin_enabled` and `get_editor_undo_redo`. ## Recipe: registering a file you just wrote A file written straight to disk is invisible to the engine until the import database knows about it. The obvious version of this — call `scan()` and wait — does not reliably work, because a `scan()` issued while another scan is running is dropped without a word. This is the version that works: ```gdscript theme={null} var efs := EditorInterface.get_resource_filesystem() if not efs.is_scanning(): efs.scan() # Unconditional from here. update_file registers the path even if the scan was dropped. efs.update_file(path) efs.reimport_files(PackedStringArray([path])) await efs.resources_reimported ``` `update_file()` before `reimport_files()` is the part people leave out. Reimporting a path the filesystem has never registered fails with `Can't find file '...' during file reimport.` Outside the editor there is a separate route for the same problem: run the binary with `--import`. See [Headless Scripting](/automation/headless#importing-assets). ## Recipe: baking occluders from code `OccluderInstance3D.bake_single_node()` is not exposed to scripting, but the editor plugin that implements the Bake button is reachable, and calling it works — verified headless, with no GPU, producing a real 8-vertex `ArrayOccluder3D` from a cube. Two things will stall or break this if you skip them. **Pre-assign a saved resource path before baking.** With no occluder resource assigned, `_bake` takes the "ask the user where to save" branch and opens an `EditorFileDialog` that nothing can answer headless: ``` ERROR: Attempting to make child window exclusive... @EditorFileDialog@14267 ``` The process then sits there. Save an empty resource first and assign it. **`plugin.call("edit", node)` does not work.** The C++ `edit()` is not script-exposed: ``` SCRIPT ERROR: Invalid call. Nonexistent function 'edit (via call)' in base 'LightmapGIEditorPlugin'. ``` Use `EditorInterface.edit_node()` to make the node current instead. The traversal that finds a built-in editor plugin, verbatim: ```gdscript theme={null} func _find_all(n, cls: String, out: Array) -> void: # n is deliberately untyped: the walk climbs out of the Control subtree # into EditorNode and then a Window. A `Control` type hint here is a # runtime error. if n.get_class() == cls: out.append(n) for c in n.get_children(): _find_all(c, cls, out) ``` And the bake itself, from inside a `@tool EditorPlugin`: ```gdscript theme={null} @tool extends EditorPlugin func _enter_tree() -> void: # The built-in editor plugins are NOT in the tree yet during _enter_tree. _bake_occluder.call_deferred() func _bake_occluder() -> void: await get_tree().process_frame await get_tree().process_frame # Walk from the editor's base control up to the true tree root (a Window). var top = EditorInterface.get_base_control() while top.get_parent() != null: top = top.get_parent() var op: Array = [] _find_all(top, "OccluderInstance3DEditorPlugin", op) if op.is_empty(): push_error("OccluderInstance3DEditorPlugin not found") return # `occ` is your OccluderInstance3D, already in the edited scene. # The occluder resource MUST exist on disk before baking. var oc := ArrayOccluder3D.new() ResourceSaver.save(oc, "res://occ.occ") occ.occluder = ResourceLoader.load("res://occ.occ") EditorInterface.edit_node(occ) await get_tree().process_frame op[0].call("_bake") ``` Two frame awaits before the traversal, and one more between `edit_node()` and `_bake()`. The built-in plugins are not in the tree during `_enter_tree()`, which is why the work is `call_deferred()`. Whether the await between `edit_node()` and `_bake()` can be dropped was not tested — keep it. The same traversal finds `LightmapGIEditorPlugin`, `MeshInstance3DEditorPlugin`, `MultiMeshEditorPlugin` and `Node3DEditorPlugin`, one match each. There is no `NavigationMeshEditorPlugin` under that class name in 4.6.1 — searching for it returns nothing. This was measured from inside a `@tool EditorPlugin` under `--headless --editor`. It was not tested from a `-s` script or in the GUI editor. **Lightmap baking is not documented as working, because it has not been seen to work.** The `LightmapGIEditorPlugin` handle is obtainable by the same traversal and `_bake` is callable — it gets past the save-path and no-meshes guards into the real bake, then dies on the dummy renderer: ``` ERROR: Condition "images.is_empty()" is true. Returning: BAKE_ERROR_CANT_CREATE_IMAGE ``` Whether it succeeds in the GUI editor with a real renderer is **unverified**. Do not build an automated pipeline on the assumption that it does. ## Traps Measured across a runtime error, a parse error and a type mismatch: the editor booted and carried on every time. That is good for stability and bad for feedback. The real failure mode is a **silent no-op** — the enable returned `ok: true`, the editor looks healthy, and none of your plugin's code ever ran. If a plugin appears to do nothing, do not assume it is not enabled and do not re-enable it. Check the editor console for the load error, then verify with `IsEditorPluginEnabled`. `Engine.has_singleton("EditorInterface")` returns **true** even outside the editor, while `Engine.get_singleton("EditorInterface")` fails with `Can't retrieve singleton 'EditorInterface' outside of editor`. Guard on `Engine.is_editor_hint()`, never on `has_singleton`. A second `scan()` issued while one is in flight is dropped with no error and no return value to check. Code that scans and then waits for `resources_reimported` will wait forever. Guard with `is_scanning()` and always call `update_file()` + `reimport_files()` unconditionally, as in the [recipe above](#recipe-registering-a-file-you-just-wrote). Summer serialises writes by `res://` path across AI tool operations, editor autosave, asset import and Git operations. **User plugins are outside that mechanism.** A plugin that writes files on a timer can race an AI file write to the same path, and neither side will know. Prefer writing on an explicit user action — a button, a menu item, a signal you control — over background timers, and keep plugin writes confined to paths the AI is not working in. ## The headless editor `Summer --headless --editor --path ` boots the editor with no window, loads enabled plugins, and exits 0 on `--quit`. `Engine.is_editor_hint()` is true and `EditorInterface` resolves. This is how plugin behaviour is verified without a person clicking anything. There is also a route with no plugin at all: ```bash theme={null} /Applications/Summer.app/Contents/MacOS/Summer --headless --editor --path -s res://tool.gd ``` With `tool.gd` as `extends SceneTree`, you get a live `EditorNode` and full `EditorInterface` — no plugin, no `plugin.cfg`, no `project.godot` edit. `EditorScript` becomes instantiable and `EditorInterface.save_scene()` persists nodes the script added. The script's loop replaces the editor's `SceneTree` but is still a `SceneTree`, so `EditorNode` is constructed as usual. **`--headless --editor` hijacks your running editor's connection. Do not run it against a project a user has open.** Adding `--editor` starts Summer's local API server, which overwrites `~/.summer/api-port` and **regenerates `~/.summer/api-token`**. Those two files are how the CLI, the MCP server and Summer's own orchestrator find your running editor. Measured on **macOS, Summer 0.5.55**: throwaway headless editors took ports 6550, 6551 and 6552 across successive runs and rewrote both files while the user's real editor was running. On exit, the port file points at a dead port, so nothing can find the real editor any more. Windows ships under a different version number and was not tested — a higher number there does not mean a later build than the one measured. A future build may suppress this for batch-mode instances; assume it does not unless your version's [changelog](/changelog/overview) says so. **Plain `--headless -s script.gd`, with no `--editor`, never starts the local API server and is completely safe.** If you do not need editor context, do not ask for it — see [Headless Scripting](/automation/headless). If you must run an editor-headless job, run it against a scratch project, and expect to restart the user's editor afterwards to republish a valid port and token. ## For AI agents To author and enable a plugin, in order. Step 4 is not optional. Check that `.godot/` exists in the project root. If it does not, **stop** — writing `[editor_plugins]` into a never-opened project aborts the editor at startup. Have the project opened once first. `addons//plugin.cfg` and the script it names. The script must start with `@tool` and extend `EditorPlugin`. Use the [templates above](#the-minimal-plugin) verbatim. Collect every path already in `editor_plugins/enabled`. The array is replaced, not merged — anything you omit is silently disabled. Your new path goes in alongside them, not instead of them. Enable through whichever route fits (`EnableEditorPlugin` against a live editor; otherwise `project.godot` plus a restart). Then **verify**: dispatch `IsEditorPluginEnabled`, or read `project.godot` back. An `ok: true` from the enable operation only means the request was queued. If the plugin failed to load, nothing will tell you, and the symptom arrives later as an unrelated parse error on an autoload name. `_enable_plugin()` does not fire on a startup enable, so autoloads registered there never register. If you need `_enable_plugin()` semantics, enable from inside an already-loaded plugin with `EditorInterface.set_plugin_enabled()`. `update_file()` then `reimport_files()`, unconditionally, guarding only the `scan()` with `is_scanning()`. A dropped `scan()` reports nothing. The four that will burn you silently: 1. **`ok: true` does not mean loaded.** Verify every enable. 2. **The enabled list is replaced, not merged.** Read it first or you will disable the user's plugins. 3. **`--headless --editor` rewrites `~/.summer/api-port` and `~/.summer/api-token`**, and breaks the connection to a running editor. Use plain `--headless` unless you truly need editor context. 4. **A broken plugin does not crash anything.** It produces an editor that quietly ignores you. ## Next steps The three extension paths and which one to pick Everything that works with no editor at all: baking, importing, exporting Native libraries, when GDScript is not enough What Summer's AI can do inside your project *** 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. # GDExtension Source: https://docs.summerengine.com/extending/gdextension Build native extensions against Summer's current Godot 4.7.2 base, and distinguish current guidance from historical 4.6.1 measurements. ## The short version Summer Engine's current upstream technical base is **Godot 4.7.2-stable**. Generate `gdextension_interface.h` and `extension_api.json` from the installed Summer binary, build against that exact interface, and load-test the result on every target platform. The current GDExtension compatibility range is unmeasured; do not assume a precompiled 4.6 binary is compatible just because it loaded in the previous release. The detailed probe, ABI hashes, class counts, and plugin observations below were measured on the previous `4.6.1.stable.mono.custom_build.b708b1182` macOS binary. They remain useful as a historical method and entitlement check, but they are not proof for the 4.7.2 release. Repeat the probe with the current binary before relying on a native extension. *** ## Historical 4.6.1 ABI measurement `gdextension_interface.json` is the file the whole GDExtension ABI is generated from. In the Summer tree it is unchanged from upstream 4.6.1: ``` sha256 34d7058f31af186d36b84567e70a9f9543da0d74f25cfe5266d4fe2d27e090f0 ``` That hash is the same on both `4.6.1-stable` and Summer's `HEAD`. Alongside it: | Measurement | Result | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `git merge-base HEAD 4.6.1-stable` | Exactly the `4.6.1-stable` tag commit — a clean branch off the tag | | Diff of `core/extension/` vs the tag | 7 added lines of logging in `gdextension_library_loader.cpp`, plus one stale generated header | | Stock class bindings removed across `scene/`, `servers/`, `core/`, `editor/`, `platform/`, `drivers/` | Zero. Every binding delta is additive | | Classes in the live API dump | 1032, of which 8 are Summer additions | | Engine singletons added by Summer | Zero. All 39 singletons in the dump are stock Godot | The historical consequence was: build for Godot 4.6.1, then test in that Summer release. Do not carry this conclusion forward to 4.7.2 without a fresh API comparison and load test. *** ## Historical proof: a third-party library running inside shipped Summer macOS hardened runtime normally refuses to load a library that is not signed by the host application's team. Summer ships with `com.apple.security.cs.disable-library-validation` set to `true` (confirmed with `codesign -d --entitlements -` on the installed, Developer-ID-signed, notarized, stapled app). Entitlements are a claim. Here is the measurement. A minimal GDExtension written in plain C, compiled with a bare `clang -shared` — so the dylib is ad-hoc signed, `TeamIdentifier=not set`, genuinely third-party — loaded into the shipped binary: ``` [SE] GDExtension: loading library path=".../bin/libprobe.macos.template_debug.dylib" (from res://bin/probe.gdextension) PROBE: entry symbol reached. PROBE: host reports 4.6.1 status=stable build=custom_build PROBE: initialize callback fired at level 0 ``` The entry symbol resolved, `get_godot_version2` resolved through the interface function table, and the initialization callback fired. **GDExtension is fully functional in the shipped macOS editor.** You can reproduce that exact result in about a minute — the recipe is below and needs nothing but `clang`. *** ## Build and load a probe extension This remains the fastest way to confirm your toolchain and the installed Summer binary agree, before you invest in a real extension. It uses no bindings library at all, only the C header the binary emits. The recorded output below came from 4.6.1; rerun it and require the host to report 4.7.2 before treating the result as current evidence. ```bash theme={null} mkdir -p ~/probe/src ~/probe/bin ~/probe/.godot cd ~/probe cat > project.godot <<'EOF' config_version=5 [application] config/name="probe" config/features=PackedStringArray("4.7") EOF ``` ```bash theme={null} cd ~/probe/src /Applications/Summer.app/Contents/MacOS/Summer --headless --dump-gdextension-interface ``` This writes `gdextension_interface.h` into the current working directory. Use this file. Do **not** copy a `gdextension_interface.h` from anywhere else — see [Do not trust a checked-in header](#do-not-trust-a-checked-in-header). Save as `~/probe/src/probe.c`: ```c theme={null} #include "gdextension_interface.h" #include static void probe_initialize(void *userdata, GDExtensionInitializationLevel level) { printf("PROBE: initialize callback fired at level %d\n", (int)level); fflush(stdout); } static void probe_deinitialize(void *userdata, GDExtensionInitializationLevel level) {} GDExtensionBool probe_library_init( GDExtensionInterfaceGetProcAddress p_get_proc_address, GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) { printf("PROBE: entry symbol reached.\n"); GDExtensionInterfaceGetGodotVersion2 get_version = (GDExtensionInterfaceGetGodotVersion2)p_get_proc_address("get_godot_version2"); if (get_version) { GDExtensionGodotVersion2 v; get_version(&v); printf("PROBE: host reports %d.%d.%d status=%s build=%s\n", v.major, v.minor, v.patch, v.status, v.build); } r_initialization->minimum_initialization_level = GDEXTENSION_INITIALIZATION_SCENE; r_initialization->userdata = NULL; r_initialization->initialize = probe_initialize; r_initialization->deinitialize = probe_deinitialize; fflush(stdout); return 1; } ``` Save as `~/probe/bin/probe.gdextension`: ```ini theme={null} [configuration] entry_symbol = "probe_library_init" compatibility_minimum = "4.1" [libraries] macos.debug = "res://bin/libprobe.macos.template_debug.dylib" macos.release = "res://bin/libprobe.macos.template_release.dylib" ``` ```bash theme={null} echo 'res://bin/probe.gdextension' > ~/probe/.godot/extension_list.cfg ``` **Do not skip this step for a headless run.** A `.gdextension` file on its own loads nothing. See [extension\_list.cfg](#the-extension_listcfg-trap). ```bash theme={null} cd ~/probe clang -shared -fPIC -I src -o bin/libprobe.macos.template_debug.dylib src/probe.c cp bin/libprobe.macos.template_debug.dylib bin/libprobe.macos.template_release.dylib /Applications/Summer.app/Contents/MacOS/Summer --headless --path ~/probe --quit ``` Expect the four `PROBE:` and `[SE]` lines shown in [Proof](#proof-a-third-party-library-running-inside-shipped-summer). The run then exits with `Can't run project: no main scene defined in the project.` — that is expected and unrelated; the extension has already loaded and initialized by that point. *** ## Historical godot-cpp 4.6 gap Real extensions use [godot-cpp](https://github.com/godotengine/godot-cpp), the C++ bindings. **There is no godot-cpp for 4.6.** Confirmed against the remote: | Ref | State | | ---------------------------------------- | --------------------- | | `refs/heads/4.5` | Newest release branch | | `refs/tags/godot-4.5-stable` | Newest stable tag | | A `4.6` branch or `godot-4.6-stable` tag | Does not exist | | `master` | Already targeting 4.7 | This was an upstream 4.6 scarcity, not a Summer restriction. For the current release, choose the godot-cpp line intended for Godot 4.7 and still generate against Summer's own API dump. ### Workaround: point godot-cpp at Summer's own API dump godot-cpp's SCons build exposes a `custom_api_file` option — "Path to a custom GDExtension API JSON file (takes precedence over `gdextension_dir` and `api_version`)", defined in `tools/godotcpp.py`. Feed it the API that Summer itself emits: ```bash theme={null} # 1. Dump the API from the shipped binary (verified: writes extension_api.json to cwd) cd /tmp /Applications/Summer.app/Contents/MacOS/Summer --headless --dump-extension-api # 2. Get the bindings git clone https://github.com/godotengine/godot-cpp.git cd godot-cpp # 3. Build against the dumped API scons platform=macos target=template_debug custom_api_file=/tmp/extension_api.json ``` **This recipe is assembled from verified facts but was not executed end to end.** Step 1 is verified — the dump command works and writes a 6.8 MB `extension_api.json` whose header reads `version_major: 4, version_minor: 6, version_patch: 1`. The `custom_api_file` option is verified to exist in godot-cpp. **The SCons build itself was not run.** godot-cpp `master` targets 4.7 and may reference engine symbols that do not exist in 4.6.1 even when pointed at a 4.6.1 API file. If it fails, that is the likely cause. Report what you hit; do not assume this page is right about the outcome. The dumped `extension_api.json` carries `version_full_name: "Summer Engine v4.6.1.stable.mono.custom_build"`, so it is not byte-identical to an upstream 4.6.1 dump even though the ABI contract is. The version string is cosmetic; the function table is what binds. *** ## The `.gdextension` file format Read from `core/extension/gdextension_library_loader.cpp` in the Summer tree, which is unchanged from upstream apart from logging. ### `[configuration]` | Key | Required | Behavior | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entry_symbol` | **Yes** | Hard error and load abort if absent | | `compatibility_minimum` | **Yes** | Hard error if absent. Must be at least `4.1.0` — anything lower is rejected outright. Compared lexicographically against the current host version (`4` / `7` / `2`) | | `compatibility_maximum` | No | Missing version components default to `9999`, so `"4.7"` means "4.7.anything" | | `reloadable` | No | Defaults to `false`. Only read in editor builds | ### `[libraries]` Keys are dot-separated feature tags; values are paths. Relative paths resolve against the directory containing the `.gdextension` file. **The entry with the most matching tags wins, not the first match.** The loader scans every key, keeps the longest fully-satisfied tag set, and only then resolves the path. So `macos.debug.arm64` beats `macos.debug` on an ARM debug host regardless of file order. Ordering your entries does not control selection; tag specificity does. ### `[dependencies]` Extra shared objects to stage alongside the library. **The precedence rule here is the opposite of `[libraries]`:** the loader takes the **first** fully-matching tag set and stops. Order matters in `[dependencies]` and does not in `[libraries]`. ### `[icons]` Optional. Maps a class name to an editor icon path. Relative paths resolve against the `.gdextension` file's directory. *** ## Gotchas that will bite ### The `extension_list.cfg` trap **A `.gdextension` file alone is not enough.** The engine loads extensions from `res://.godot/extension_list.cfg`, a plain list of paths. Only the editor's filesystem scan writes that file. A headless or scripted launch against a project where it does not exist loads nothing — and prints nothing, because there is no error to report; the engine simply has an empty list. Verified by removing the file and re-running: **zero GDExtension output, no warning, no error, silent success.** This is the single most likely way for an agent to conclude an extension works when it never loaded. ```ini theme={null} res://bin/probe.gdextension ``` Write it by hand for any headless workflow, one `res://` path per line. Opening the project in the editor once also produces it. ### Ship a plain `.dylib`, and make its path resolve The path in `[libraries]` must resolve to a real file. Do not rely on Apple's bundle or `@rpath` lookup as a fallback. When the primary load fails, upstream retries with an empty path to let Apple's bundle lookup have a go. In Summer that retry short-circuits: ``` [SE] GDExtension: first load failed (err=19), retrying with empty path for Apple lookup [SE] macOS: open_dynamic_library called with empty path (GDExtension fallback not implemented) ``` A correctly-pathed plain `.dylib` never reaches this code — that is the configuration proven to load, and it is what you should ship. We have not tested a `.framework`-packaged GDExtension in Summer and make no claim either way about it; a plain `.dylib` avoids the question entirely. ### Do not trust a checked-in header Do not trust a header copied from an older source checkout or release. Always get the header from the exact binary you are targeting: ```bash theme={null} /Applications/Summer.app/Contents/MacOS/Summer --headless --dump-gdextension-interface ``` *** ## Platform support The 4.6.1 rows below are a historical test snapshot. For 4.7.2, treat every native target as requiring a fresh load/export test until the compatibility contract records new measurements. | Target | GDExtension | Notes | | ---------------------- | ---------------------------- | ------------------------------------------------------------------ | | macOS editor | Historical proof only | An unsigned third-party dylib loaded on 4.6.1; revalidate on 4.7.2 | | macOS export | Unmeasured on 4.7.2 | See signing caveats below | | Windows / Linux export | Unmeasured on 4.7.2 | Test with the exact current templates | | Web export | **No current support claim** | See below | ### macOS exports and library validation Read from `platform/macos/export/export_plugin.cpp`; not exercised as a full signed export. The macOS export preset defaults `codesign/entitlements/disable_library_validation` to `false`. The export plugin **auto-enables it** when the export is ad-hoc signed *and* carries shared objects, printing "Ad-hoc signed applications require the 'Disable Library Validation' entitlement to load dynamic libraries." **A Developer-ID-signed export does not get that entitlement automatically.** If you sign with a real identity and ship a GDExtension, tick **Disable Library Validation** in the export preset yourself, or the game will fail to load its own extension on a user's machine. Signing with `rcodesign` is unsupported when a dynamic library is embedded; the export plugin reports "'rcodesign' doesn't support signing applications with embedded dynamic libraries." ### Web exports Web GDExtension support requires the engine to be built with WebAssembly dynamic linking. In `platform/web/detect.py`, `dlink_enabled` defaults to `False`, and only that flag switches the build to `-sMAIN_MODULE=1` / `-sSIDE_MODULE=2`. Summer ships no web export template, so a web export uses official Godot templates, which are not built with dlink. **Conclusion: do not plan on GDExtension in a web export.** Inferred from source; we have not run a web export to confirm the failure mode. ### Export templates on other platforms Summer 0.5.65 bundles freshly built macOS templates for the 4.7.2 base. Do not substitute templates from an older release. For every other target, verify the exact installed template and run an exported-build smoke test; no cross-template GDExtension range is currently claimed. *** ## Community plugin compatibility Rules you can apply yourself, rather than a list that will be wrong next month. **Dead.** The loader hard-errors on any `compatibility_minimum` below `4.1.0`. Independently, GDScript 2.0 and the 4.x scene format break 3.x `@tool` addons. There is no path here. **The lower-risk bet.** No native ABI, compilation, or code signing. Use a 4.7-compatible release and still verify that the plugin enables and runs in Summer. See [Editor Plugins](/extending/editor-plugins). **Version-locked.** Require an advertised Godot 4.7 range, a matching platform binary, and an actual load/export test in Summer 0.5.65. Before recommending any GDExtension, resolve the target and test the exact 4.7.2 editor and template combination. Historical 4.6.1 results are not a substitute. **The reader test for a precompiled binary:** does it advertise Godot 4.7 support, and does its `compatibility_minimum` sit at or below `4.7.2` with no `compatibility_maximum` beneath it? Both must be true, and neither replaces a real load test. Open the `.gdextension` file and read the `[configuration]` block—it is the authoritative version declaration. *** ## When a load fails Summer prints `[SE]`-prefixed diagnostics that stock Godot does not. They name the resolved absolute path, every fallback location tried, and the raw `dlerror` string. Search for them first; the stock `ERROR:` lines below them are less specific. A missing library produces this, verbatim: ``` [SE] GDExtension: loading library path=".../bin/libprobe.macos.template_debug.dylib" (from res://bin/probe.gdextension) [SE] macOS: dlopen failed path="..." dlerror=dlopen(..., 0x0002): tried: '...' (no such file) ERROR: Can't open dynamic library: ... Error: dlopen(...): ... (no such file). at: open_dynamic_library (platform/macos/os_macos.mm:440) ERROR: Can't open GDExtension dynamic library: 'res://bin/probe.gdextension'. at: open_library (core/extension/gdextension.cpp:741) ``` | Symptom | Cause | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | No GDExtension output at all | `res://.godot/extension_list.cfg` is missing or does not list your `.gdextension` | | `dlopen ... (no such file)` | The `[libraries]` path does not resolve. Check the tag key actually matched your platform | | `must contain a "configuration/entry_symbol" key` | Missing `entry_symbol` | | `must contain a "configuration/compatibility_minimum" key` | Missing `compatibility_minimum` | | `must be at least 4.1.0` | A 3.x-era or malformed `compatibility_minimum` | | `No GDExtension library found for current OS and architecture` | No `[libraries]` key matched. The error names the `os.arch` pair it wanted | | Entry symbol not found | The symbol name in `[configuration]` does not match the exported symbol. Check with `nm -gU` on the dylib | Hot reload of a `reloadable` extension is enabled in the editor. It is off everywhere else, by design — the flag is only read in editor builds. *** ## Summer's own native classes The live API dump contains 1032 classes; 8 are Summer's: | Class | Availability | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `SummerEngineSettings` | `RefCounted`, `api_type: core`, 15 methods. The only one registered outside `#ifdef TOOLS_ENABLED`, so the only one present in an exported game | | `AuthManager`, `SummerEngineGateway`, `ChatPanel`, `WebViewControl`, `PostHogClient`, `LocalApiServer`, `MutationLease` | Editor-only | These exist to run the editor's own AI surfaces — authentication, the chat panel, the embedded webview, telemetry, the local tool server, edit coordination. They are documented here so you are not surprised to find them in an API dump. **There is no reason to call them from a game.** Relying on any of them makes your project unopenable in stock Godot for no benefit. *** ## Next steps Pure-GDScript `@tool` plugins — no ABI, no compilation, no signing What Summer shares with stock Godot, and what it adds Signing, entitlements, and notarization for shipped games The exact split between open, free, and paid *** 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. # Custom Modules Source: https://docs.summerengine.com/extending/modules How Summer's internal C++ module is built, why external developers cannot add one, and what to use instead. Includes the init-level and TOOLS_ENABLED discipline that decides whether a class survives into an exported game. ## Read this first **You cannot add a custom module to Summer Engine.** Godot C++ modules are compiled into the engine binary, which means adding one requires checking out the engine source and building it. The Summer engine source is not public — `github.com/SummerEngine/SummerEngine` returns 404, verified. There is no workaround, no flag, and no plugin path that changes this. If you are looking to extend Summer, the two real options are: Native C/C++ code loaded at runtime from your project. Summer now uses the Godot 4.7.2 base; generate against the installed binary and test the exact library because the current compatibility range is unmeasured. Pure-GDScript `@tool` plugins. No ABI, no compilation, no code signing. The rest of this page is context: how Summer is actually built, and the module-level lessons that are worth knowing even when you are writing a GDExtension. It is descriptive, not a set of instructions you can follow. For the exact split between what is open, what is free, and what is paid, see [What is open in Summer Engine?](/knowledge-base/source-status). Nothing here should be read as a commitment to publish engine source. *** ## What a Godot module is A module is C++ compiled directly into the engine binary at build time. Unlike a GDExtension, it is not loaded at runtime, cannot be distributed separately, and cannot be added to an engine someone else built. It lives in the `modules/` directory of the engine source tree, and SCons picks it up automatically. The trade is straightforward: a module gets unrestricted access to engine internals and zero ABI constraints, and costs you the ability to ship it to anyone who is not also building the engine. GDExtension makes the opposite trade. Summer's own additions live in one module, `modules/1summer_engine/`. Everything the editor does beyond stock Godot — authentication, the chat panel, the embedded webview, the local tool server that MCP talks to, crash reporting, edit coordination, the updater — is inside it. *** ## Anatomy | File | Role | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.py` | `can_build(env, platform)` gates which platforms compile the module; `configure(env)` adjusts the build environment; `get_doc_classes()` and `get_doc_path()` declare class documentation XML | | `SCsub` | The SCons build script — source globs, per-platform link flags, generated headers, conditional defines | | `register_types.cpp` / `register_types.h` | Registers classes with `ClassDB` at each initialization level, and tears them down in reverse | Summer's module then subdivides by concern — `core/`, `auth/`, `gateway/`, `chat/`, `webview/`, `editor/`, `analytics/`, `api/`, `crash/`, `verify/`, `util/`. *** ## The two disciplines worth stealing These are the parts that generalize. Both are about the same question: **does this code exist in an exported game, or only in the editor?** ### Initialization levels `initialize__module` receives a `ModuleInitializationLevel` and switches on it. Registering at the wrong level either crashes or silently does nothing. | Level | What belongs here | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `MODULE_INITIALIZATION_LEVEL_CORE` | Runs before almost everything. Summer uses it to point `DOTNET_ROOT` at the bundled .NET SDK, which must happen before the mono module initializes | | `MODULE_INITIALIZATION_LEVEL_SERVERS` | Rendering, physics, and audio servers exist | | `MODULE_INITIALIZATION_LEVEL_SCENE` | Where node and resource classes are registered. `GDREGISTER_CLASS` calls belong here | | `MODULE_INITIALIZATION_LEVEL_EDITOR` | Editor-only. `EditorPlugins::add_by_type()` belongs here and nowhere else | `uninitialize__module` mirrors it. Ordering in teardown is not cosmetic — Summer's module unregisters its error handler *before* tearing down the telemetry client it forwards into, and drops a settings `Ref` while `ObjectDB` is still alive, because letting a static `Ref` destruct during process finalization raced `ObjectDB` teardown and crashed on every clean exit. The same shape applies to a GDExtension: `minimum_initialization_level` in your `GDExtensionInitialization` struct is the same axis, and your `initialize` callback is invoked per level. ### `#ifdef TOOLS_ENABLED` decides what ships Export templates are built without `TOOLS_ENABLED`. Anything inside that guard does not exist in an exported game — not the class, not the symbol. This is exactly why, of the 8 classes Summer adds to the engine, only `SummerEngineSettings` is available in an exported game. The other seven are registered inside `#ifdef TOOLS_ENABLED` and are editor-only. See [Summer's own native classes](/extending/gdextension#summers-own-native-classes). Get the guard wrong and you do not get a runtime error, you get a link error in the export template build — which is the good outcome. The bad outcome is next. *** ## One cautionary tale: linking a framework unconditionally Worth reading even if you never write a module, because the same failure is reachable from a GDExtension that links a framework. Summer's macOS auto-updater uses Sparkle. The updater's implementation file is entirely wrapped in `#ifdef TOOLS_ENABLED`, so export templates reference zero Sparkle symbols — the guard was correct. But the `SCsub` linked the framework **unconditionally**: ```python theme={null} env.Append(LINKFLAGS=["-F" + sparkle_framework_dir, "-framework", "Sparkle"]) ``` A `-framework` link flag creates a load-command dependency in the produced binary whether or not any symbol from it is referenced. So every exported macOS game came out depending on `@rpath/Sparkle.framework`. Exports do not bundle it. `dyld` could not resolve it, and the kernel `SIGKILL`ed the game on launch — presenting as a "Report to Apple" crash dialog, not a Gatekeeper prompt, which sent the first round of debugging in entirely the wrong direction. The fix was to gate the link flags on the build type, not only the source: ```python theme={null} if env.editor_build: env_summer_engine.Append(CCFLAGS=["-F" + sparkle_framework_dir]) env_summer_engine.Append(LINKFLAGS=["-F" + sparkle_framework_dir, "-framework", "Sparkle"]) env.Append(LINKFLAGS=["-F" + sparkle_framework_dir, "-framework", "Sparkle"]) ``` **The lesson: `#ifdef` guards your source, not your link line.** If your GDExtension links a system or third-party framework, check the produced binary's load commands with `otool -L` before you ship, and confirm every dependency will actually be present on the user's machine. *** ## If you were going to ask for a module Almost everything a module is reached for can be done another way in Summer: | You want | Use instead | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | A new node or resource type in C++ | [GDExtension](/extending/gdextension) — same C++, loaded at runtime, and distributable | | New editor UI, docks, inspector plugins, import plugins | [Editor plugins](/extending/editor-plugins), or an `EditorPlugin` subclass from a GDExtension | | To drive the editor from outside | [MCP server and CLI](/mcp/overview) | | A third-party native library | Link it into a GDExtension, subject to the `otool -L` warning above | If your case genuinely needs engine internals that GDExtension does not expose, tell us what and why — that is useful signal. [founders@summerengine.com](mailto:founders@summerengine.com) or [Discord](https://discord.gg/yUpgtxnZky). *** ## Next steps The supported native extension path, with a verified end-to-end recipe Pure-GDScript tooling inside the editor Open agent layer, free desktop app, paid hosted services What Summer shares with its current Godot 4.7.2 base *** 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. # Extending Summer Source: https://docs.summerengine.com/extending/overview Summer is an extensible engine. Three ways to add capability: GDScript editor plugins, native GDExtension libraries, and engine modules — what each one can reach, and which to pick. Summer Engine is the product. Its current upstream technical base is Godot Engine 4.7.2-stable. Summer follows upstream continuously; 4.7.2 is a compatibility fact, not the Summer Engine product version. Runtime and project compatibility ranges for this new base remain unmeasured, so treat native extensions as version-sensitive until the exact binary is loaded and exported successfully. There are three of them. They differ in what they can reach, what they cost to build, and whether you can use them at all. | You want to | Use | Language | Needs a compiler | Available to you | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | Drive the editor: bakes, forced reimports, custom docks, registering autoloads, anything under `EditorInterface` | [Editor plugin](/extending/editor-plugins) | GDScript | No | **Yes, today** | | Add fast native types, wrap a C/C++/Rust library, or do heavy per-frame work | [GDExtension](/extending/gdextension) | C++, Rust, others | Yes | **Conditional** — generate against the current 4.7.2 binary and load-test each binary/platform combination | | Change the engine itself: new servers, new core types, editor internals | [Engine module](/extending/modules) | C++ | Yes, plus engine source | **No.** Summer's engine source is not public | If you are an agent, or you are automating Summer, the answer is almost always the first row. An editor plugin is a text file you write and a line you add to `project.godot`. It needs no build step, no signing, and no engine source, and it hands you the entire `EditorInterface` — which is the only way to reach a large set of engine capability that is simply not exposed to ordinary scripts. ## Editor plugins A `@tool` script extending `EditorPlugin`, declared by a `plugin.cfg` in `addons//`, enabled through `project.godot`. It runs inside the editor process with full editor context. This is the path that turns "the API is not exposed to scripting" into "the API is reachable". Occluder baking, forcing the import of a file an agent just wrote, saving a scene from code, registering an autoload — none of those are available to a plain script, and all of them are available from inside an editor plugin. It also works without a window. `Summer --headless --editor` boots the editor, loads enabled plugins, and gives you a live `EditorInterface` from a shell — with one sharp hazard around your running editor that the deep page documents in full. Templates, the three ways to enable a plugin and why they behave differently, what `EditorInterface` actually unlocks, the verification step you must not skip, and the headless-editor hazard ## GDExtension Native shared libraries loaded from a `.gdextension` file. No engine recompile, no custom binary — the same mechanism stock Godot uses. Summer currently follows the 4.7.2-stable base. Generate the interface and API from the installed Summer binary rather than reusing headers from an older release. Match the exact API, architecture, operating system, compiler/runtime dependencies, and signing requirements, then run a real load/export test; the current compatibility range is not yet measured. Building, loading, and shipping native extensions in Summer ## Engine modules C++ compiled directly into the binary. This requires building the engine from source, and [Summer's engine source is not public](/knowledge-base/source-status), so modules are not an option for external developers today. The page exists because the distinction matters when an upstream tutorial describes an extension mechanism. What modules are, why they are internal-only in Summer, and what to use instead ## Using community Godot addons Community addons are candidates, not blanket-compatible inventory. Pure GDScript addons are usually lower-risk than native extensions, but Summer's minimum and recommended project compatibility ranges remain unmeasured. Judge every addon by these rules: * **Godot 4.7 or 4.x, pure GDScript, `@tool` + `EditorPlugin`** — the lower-risk case. No ABI, no compilation, no signing. Install into `addons/` and enable it like any plugin you wrote yourself. * **Godot 4.x with a GDExtension binary** — depends on the addon shipping a build for 4.7 and for your platform. A successful upstream load is useful evidence, not proof of a Summer load or export. Check [GDExtension](/extending/gdextension), then test the exact binary in a committed copy. * **Godot 3.x** — dead. The 3.x plugin API does not exist in 4.x. This is not a Summer limitation; the same addon fails on stock Godot 4. * **Anything shipped as an engine module or a custom engine build** — cannot be used. There is no way to compile it into Summer. Enabling a plugin runs its code inside your editor process with full filesystem access. Read what you are enabling. This is true of stock Godot too, but it is worth saying once. ## Next steps The deep page: templates, enabling, `EditorInterface`, traps Run the engine from a shell with no window: baking, importing, exporting *** 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. # Plugin Library Source: https://docs.summerengine.com/extending/plugin-library A curated list of community addons that fit Summer's current compatibility rules, plus a reusable test for judging any plugin yourself. Summer Engine's current upstream technical base is Godot Engine 4.7.2. Compatible community addons can be used in a Summer project after an exact-version test. Drop one into `addons/`, enable it, and test it against the current Summer Engine release — see [Extending Summer](/extending/overview) for the compatibility rules, and [Editor Plugins](/extending/editor-plugins) for how to write your own. The upstream number is not the Summer Engine product version, and Summer follows upstream continuously. This page is a **curated list, not a marketplace**. There is no installer, no registry and no ranking. It is a short set of addons whose repositories we checked, alongside the rules we used — so that when an entry here goes stale, you can replace it yourself. **What "checked" means, precisely.** Every entry below was verified on **25 July 2026** against its actual repository: the repository exists at the URL given, it is not archived, its license is a real file we read, its most recent release and most recent push are the dates stated, and its stated Godot support and plugin type come from its own `README`, `plugin.cfg` or `.gdextension` file. **This inventory predates the 4.7.2 base and has not been re-run end to end.** We did not install and run each entry inside Summer. Pure-GDScript `@tool` addons remain the lower-risk case; native code must be revalidated against the installed 4.7.2 binary. Treat the dated repository notes below as research evidence, not a current compatibility guarantee. ## How to judge a plugin yourself This is the durable part of the page. Entries age; the test does not. [Godot 3.x addons are dead](/extending/overview#using-community-godot-addons) and no amount of patching brings them back — the 3.x plugin API does not exist in 4.x, GDScript 2.0 is a different language, and the scene format changed. A repository with a `3.x` branch and a `4.x` branch is fine; you want the 4.x one. A repository that only ever supported 3.x is a dead end on stock Godot too. Look in the addon folder. If everything is `.gd` and `.tscn` with a `plugin.cfg`, it is a **GDScript addon** — no ABI, no compilation, no code signing, and the safe case. If you find a `.gdextension` file next to `.dll` / `.so` / `.dylib` / `.framework` files, it is a **GDExtension**, and it is version-locked to whatever Godot version those binaries were built against. Go to the next step. It is the authoritative answer and it takes ten seconds. Open the `[configuration]` block: ```ini theme={null} [configuration] entry_symbol = "..." compatibility_minimum = "4.5" ``` `compatibility_minimum` must be at or below `4.7.2`, and any `compatibility_maximum` must be at or above it. The engine hard-errors on anything below `4.1.0`. Then check `[libraries]` actually names a key matching your platform. The full rules, including the tag-precedence trap, are on [GDExtension](/extending/gdextension#the-gdextension-file-format). "Last commit two weeks ago" is not the question. The question is whether a **released** version targets Godot 4.7. Plenty of addons have a healthy default branch and a newest tag that predates 4.7 entirely — you can still use them, but you are installing an untagged branch head, and you should know that is what you are doing. Read the project's own compatibility table if it has one. Several of the entries below publish one, and it is more reliable than a badge in the README header. No clear license, no entry on this page. Beyond legality: enabling a plugin runs its code inside your editor process with full filesystem access. That is true on stock Godot too, and it is worth saying once per page. Enabling a plugin in Summer can return success and still not load it. A broken plugin does not crash the editor; it produces an editor that quietly ignores you. After enabling, confirm with `IsEditorPluginEnabled` or `EditorInterface.is_plugin_enabled()`. This is not optional and the failure mode is genuinely nasty — [Verification is not optional](/extending/editor-plugins#verification-is-not-optional). The single most common way to conclude "this plugin works" when it never loaded is to trust the enable call's acknowledgement. It means *queued*, not *loaded*. Verify separately, every time. ## Dialogue and narrative | Plugin | What it does | Type | License | State when checked | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -------------- | ------- | ------------------------------------------------------------------ | | [Dialogic](https://github.com/dialogic-godot/dialogic) | Visual editor for dialogue, characters, portraits and timelines; the default choice for visual novels and RPG conversations | GDScript addon | MIT | `2.0-alpha-20`, released 21 Jul 2026. `README` requires Godot 4.3+ | | [Dialogue Manager](https://github.com/nathanhoad/godot_dialogue_manager) | Script-like branching dialogue written as text files, with a stateless runtime — the code-first alternative to Dialogic | GDScript addon | MIT | `v3.10.5`, released 20 Jul 2026. See the version note below | **Dialogue Manager's version split matters.** Its `README` states that Dialogue Manager 4 targets **Godot 4.6+** and lives on the default branch, while the `v3.10` line — which is what the newest *tag*, `v3.10.5`, belongs to — targets Godot 4.4 or 4.5. There is no v4 tag at the time of checking. For Summer, that means installing the default branch rather than the latest release, or taking the Asset Library build if it has caught up. Dialogic has carried an `alpha` label on its 2.0 line for a long time while being one of the most widely used addons in the ecosystem. Treat the label as a versioning habit rather than a warning, but read the changelog before upgrading across alphas. ## Behaviour, state machines and cameras | Plugin | What it does | Type | License | State when checked | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------- | | [Godot State Charts](https://github.com/derkork/godot-statecharts) | Hierarchical state charts — finite state machines without the state explosion; nested and parallel states, history, transition guards | GDScript addon | MIT | `v0.22.5`, released 26 Jun 2026. Supports "Godot 4 or later"; `0.22.5` was itself a Godot 4.7 compatibility fix | | [Beehave](https://github.com/bitbrain/beehave) | Behaviour trees for enemy and NPC AI, with an in-editor debugger that shows the tree evaluating live | GDScript addon | MIT | Newest tag `v2.9.2`, Dec 2025; default branch last pushed 6 Jul 2026. See the release-gap note below | | [Phantom Camera](https://github.com/ramokz/phantom-camera) | Cinemachine-style virtual cameras for `Camera2D` and `Camera3D` — framing, follow modes, blends and priorities without hand-written camera code | GDScript addon | MIT | `v0.11.0.3`, released 19 Jul 2026. README states Godot 4.4+ | | [LimboAI](https://github.com/limbonaut/limboai) | Behaviour trees plus hierarchical state machines, with a visual editor and a blackboard system | **GDExtension** | MIT | `v1.8.0`, released 19 Jun 2026. Ships a GDExtension build labelled for 4.6. See below | **Beehave's newest release predates its own 4.6 guidance.** The project's compatibility table says Godot 4.5+ wants Beehave `2.10+`, but no `2.10` tag exists — the newest tag is `v2.9.2` from December 2025, and the branch `plugin.cfg` reads `2.9.3-dev`. Meanwhile the default branch has commits titled "upgrade project to godot 4.6" (February 2026) and "upgrade deps to Godot 4.7" (July 2026). So the 4.6-ready code exists and the 4.6-ready *release* does not. Install the `godot-4.x` branch head knowingly, or stay on `v2.9.2` and test. **LimboAI ships two different things, and neither should be assumed current without a test.** Its release page carries both a GDExtension archive (named for Godot 4.6) and a set of full custom engine builds for Godot 4.7. The custom engine builds are the module route and [cannot be used with Summer](/extending/modules) — there is no way to compile a module into Summer. The GDExtension archive is the candidate, but its 4.6-labelled binary still needs a 4.7.2 load test. Its `.gdextension` declares `compatibility_minimum = "4.2"` with no maximum, which passes the mechanical [reader test](/extending/gdextension#community-plugin-compatibility) for 4.7.2. Its macOS binaries are `.framework` bundles — see [the macOS caveat](#the-macos-framework-caveat). ## Level, terrain and world tools | Plugin | What it does | Type | License | State when checked | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | [HeightMap Terrain](https://github.com/Zylann/godot_heightmap_plugin) | Heightmap-based 3D terrain with sculpting, texture painting, detail layers and LOD, entirely in GDScript | GDScript addon | MIT | Last pushed 14 Jul 2026. `README` states **Godot 4.6+** explicitly. No tagged releases at all — install from the default branch or the Asset Library | | [SmartShape2D](https://github.com/SirRamEsq/SmartShape2D) | Draw 2D terrain as a spline and get textured edges, corners and collision generated for you | GDScript addon | MIT | `v3.3.1`, Dec 2025; last pushed 21 Jun 2026. Author states support for Godot 4.x; the `README` badge still reads 4.3 | | [Terrain3D](https://github.com/TokisanGames/Terrain3D) | High-performance clipmap terrain with a full sculpting and painting dock — the heavyweight option when GDScript terrain is not fast enough | **GDExtension** | MIT | `v1.0.2-stable`, released 19 May 2026, whose release notes read "This maintenance release brings support for Godot 4.6" | Terrain3D's `.gdextension` declares `compatibility_minimum = 4.5` with no maximum, and the release explicitly states support for Godot 4.4 through 4.6+. That is the cleanest 4.6 story of any prebuilt GDExtension we checked. The macOS caveat below still applies. ## Testing and debugging | Plugin | What it does | Type | License | State when checked | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | [GUT](https://github.com/bitwes/Gut) | Unit testing for GDScript — asserts, doubles, stubs, parameterised tests, an in-editor runner and a CLI for continuous integration | GDScript addon | MIT | `v9.7.1`, 10 Jul 2026. Its own version table maps **Godot 4.6.x to `v9.6.1` or the default branch**; `v9.7.1` is the 4.7 line | | [gdUnit4](https://github.com/godot-gdunit-labs/gdUnit4) | Testing framework covering both GDScript and C#, with an embedded test inspector, mocking and scene testing | GDScript addon (plus C# support) | MIT | `v6.1.3`, Apr 2026; last pushed 25 Jul 2026. `README` badges list 4.6, 4.6.1, 4.6.2 and 4.6.3 explicitly | | [Debug Draw 3D](https://github.com/DmitriySalnikov/godot_debug_draw_3d) | Immediate-mode 3D debug primitives — lines, boxes, spheres, frustums — plus 2D overlays and graphs, drawable from anywhere without leaking nodes | **GDExtension** | MIT | `1.7.3`, released 4 Apr 2026 | **Read GUT's version table before installing.** Summer now uses the 4.7.2 base, so the 4.7.x line is the relevant candidate; the older 4.6.x mapping is historical. Still check for a newer 4.7-compatible release and verify the plugin inside Summer before relying on it. Debug Draw 3D's `.gdextension` declares `compatibility_minimum = "4.4.1"` with no maximum, so it passes the mechanical half of the reader test. Its documentation does not name 4.7 anywhere, so it fails the "does it advertise 4.7" half. Try it, verify it loads, and do not assume. ## The macOS `.framework` caveat Every prebuilt GDExtension on this page — Terrain3D, LimboAI and Debug Draw 3D — ships its macOS binary as a `.framework` bundle rather than a plain `.dylib`. That is simply what the standard bindings produce for macOS, so it is not a mark against any of them. It matters here because **Summer's GDExtension loading has been verified against a plain `.dylib` and has not been tested with `.framework` packaging**, and Summer does not implement upstream's Apple bundle-lookup fallback path. See [Ship a plain `.dylib`](/extending/gdextension#ship-a-plain-dylib-and-make-its-path-resolve). Practically: * On **Windows and Linux**, these three ship plain `.dll` and `.so` files and the question does not arise. * On **macOS**, load them and check the editor console before building anything on top. Summer prints `[SE]`-prefixed diagnostics naming the resolved path and the raw `dlerror` string, which will tell you immediately — [When a load fails](/extending/gdextension#when-a-load-fails). * On **web exports**, no GDExtension works at all, regardless of packaging. If you resolve this either way on macOS, tell us. It is the single most useful missing data point on this page. ## What is not here Some well-known addons were checked and deliberately left out. The reasoning is more useful than the names: * **Anything shipped as an engine module** — the best-known voxel terrain system for Godot is distributed as a module requiring a custom engine build, with GDExtension support still listed as planned work. Summer's engine source is not public, so [modules cannot be used](/extending/modules), and a GDExtension build of the same project is a different artifact you must check separately. * **Addons with open, unresolved reports of breaking on Godot 4.6** — including one popular scattering tool with issues filed specifically against 4.6 on Apple Silicon, and one sprite-import tool with two unresolved 4.6 reports. A plugin that is broken on stock 4.6 is broken on Summer. * **Projects that have moved off GitHub** — at least one major Steam integration now has archived GitHub repositories that redirect elsewhere. Not a judgement on the project; we only list links we fetched. * **Addons whose newest release long predates 4.6 with no compatibility statement.** They may well work. We have no basis for saying so, and a plausible list is worth less than a short verified one. ## Submit a plugin There is no submission form and no automated review. Two routes, both of which reach us: This documentation is a public repository. Propose an entry against `extending/plugin-library.mdx`, or file an issue if you would rather we did the checking The fastest route, and the right one if you want to discuss whether something fits before writing it up Include the repository URL, the license, whether it is a GDScript addon or a GDExtension, and — if it is a GDExtension — the `compatibility_minimum` from its `.gdextension` file. That is most of the verification already done. ## A note on how new this is **Summer-specific plugins do not really exist yet.** We documented Summer's extension surface — [editor plugins](/extending/editor-plugins), [GDExtension](/extending/gdextension), the [headless editor](/automation/headless) — very recently, and nobody has had time to build against it. So this list starts where it honestly can: general Godot 4.x addons that Summer inherits by being a faithful fork. As people build things that use what Summer adds on top — agent-driven editor tooling, generation pipelines, project automation — this page is where they will go. If you are building one, the [editor plugin page](/extending/editor-plugins) is the whole API surface, and Discord is where to tell us it exists. ## Next steps Templates, the three ways to enable one, and the traps that fail silently The three extension paths and which one applies to you Native libraries: the ABI, the loader rules, and how to debug a failed load Driving the engine from a shell with no window *** 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. # Connect Your Project to GitHub Source: https://docs.summerengine.com/guides/github-from-changes-dock Create a GitHub repository, connect it to your Summer project from the Changes dock workflow, and safely commit, push, and sync changes. ## Overview Summer can commit locally right away, but most users should connect their project to GitHub early. That gives you backups, a shared source of truth, and a safer workflow when you start committing often. Git is great for code, but large binary assets (3D models, textures, audio) strain it. If your project carries big assets, or you want the whole project on a second machine without Git setup, use [Summer Cloud](/guides/summer-cloud) alongside GitHub: code stays in Git, the full project tree syncs by content hash. The simplest flow is: 1. Create an empty repository on GitHub 2. Copy the repository URL 3. Paste that URL into Summer chat 4. Ask Summer to connect the current project to that repository 5. Use the `Changes` dock to commit, push, and sync ## Before You Start Make sure: * Git is installed on your machine * Your Summer project already exists locally * You are signed in to GitHub in the browser if you plan to use an HTTPS remote ## Step 1: Create An Empty GitHub Repository Open GitHub and create a new repository. Recommended settings: * Choose a repository name that matches your project * Keep it empty if the project already exists locally * Do not add a README, `.gitignore`, or license during creation Why empty matters: If GitHub creates the first commit for you, your local Summer project and the remote repository start with different histories. That can still be fixed, but it adds extra merge or pull steps you usually do not want for a first-time setup. If you have never created a GitHub repository before, use GitHub's official guide: [Create a new repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) ## Step 2: Copy The Repository URL After the repository is created, copy the repository URL from GitHub. HTTPS is usually the easiest option for most users: ```text theme={null} https://github.com/your-name/your-project.git ``` SSH also works if your machine is already configured for it: ```text theme={null} git@github.com:your-name/your-project.git ``` ## Step 3: Ask Summer To Connect The Project Open your project in Summer. Then open chat and paste the repository URL with a clear instruction, for example: ```text theme={null} Connect this project to GitHub: https://github.com/your-name/your-project.git ``` Or: ```text theme={null} Initialize Git for this project if needed, attach this GitHub repository as origin, and get the project ready for normal commits and pushes: https://github.com/your-name/your-project.git ``` Summer should then help with the setup steps for the current project. ## Step 4: Verify The Connection In The Changes Dock Once the remote is connected, open the `Changes` dock. You should now see a GitHub-backed workflow instead of a local-only state. Useful things to look for: * Your branch name * Sync state when the branch is ahead or behind * Commit and push behavior tied to the remote repository * Graph history that reflects normal user-facing Git history If Summer still shows that commits stay local until you publish, the remote is not connected yet. ## Step 5: Commit And Push After the project is connected: 1. Make a change in your project 2. Open the `Changes` dock 3. Review the changed files 4. Enter a commit message 5. Commit 6. Push or sync if Summer shows outgoing changes ## Understanding The Changes Dock The `Changes` dock shows the current working tree. Common status letters: * `M`: modified * `U`: untracked * `A`: added * `D`: deleted * `R`: renamed Typical behaviors: * Hover a file row to open, discard, stage, or unstage it * Deleted files appear with a strikethrough and a `D` * If your branch is ahead or behind, Summer shows a sync action instead of a normal empty state ## Understanding Sync If Summer shows arrows such as `2↑` or `1↓`, that means your branch and the remote are out of sync. * `↑` means your local branch has commits that are not on the remote yet * `↓` means the remote has commits that are not on your machine yet The sync action helps bring those states back together. ## Best Practice For a smooth workflow: * Connect to GitHub early * Keep the first GitHub repository empty if the project already exists locally * Commit often * Push regularly * Sync before continuing if you are behind ## Troubleshooting ### Summer still says commits are local only That usually means no remote is attached yet. Copy the repository URL again and ask Summer to connect the current project to GitHub. ### I already created a README on GitHub You may need Summer to pull or reconcile the remote history before your first push. ### I am not sure which URL to use Use the repository clone URL shown on GitHub. HTTPS is the safest default for most users. ### I want Summer to do the setup for me That is the intended flow. Paste the repository URL into chat and tell Summer to connect the current project to it. # Large Codebases Source: https://docs.summerengine.com/guides/large-codebases Strategies for working effectively with large projects in Summer Engine ## Overview Working with large codebases presents unique challenges that require different strategies than smaller projects. Based on experience with complex game projects and enterprise codebases, this guide covers proven techniques for managing increased complexity in Summer Engine. ## Understanding Large Codebase Challenges ### Common Issues * **Context Overload**: Too much information for the AI to process effectively * **Scope Creep**: Changes affecting unintended parts of the codebase * **Pattern Inconsistency**: Different coding styles across the project * **Navigation Difficulty**: Finding relevant code in thousands of files ### Summer Engine's Approach Summer Engine's [Project Intelligence](/ai-tools/rag-search) automatically indexes your codebase to understand: * File relationships and dependencies * Code patterns and architectural decisions * Your team's coding conventions * Project-specific context and domain knowledge ## Getting Up to Speed Quickly ### Use Chat for Exploration When joining a large project or exploring unfamiliar code, start with broad questions: ``` What does the combat system architecture look like in this project? Show me how player input flows through the codebase Where is the save/load functionality implemented? ``` ### Follow the Data Flow Understand how data moves through your system: ``` Trace how a player action becomes a game state change Show me the path from @input_handler.gd to @game_state.gd What happens when a player clicks the attack button? ``` ### Map Dependencies Get a high-level view of how systems connect: ``` What files depend on @player_manager.gd? Show me all the systems that use @event_bus.gd Which scripts are called by @level_loader.gd? ``` ## Effective Context Management ### Start Broad, Then Narrow Begin with general questions to understand the landscape: **Step 1: High-level understanding** ``` How is the inventory system organized in this project? ``` **Step 2: Specific implementation details** ``` Looking at @inventory/inventory_manager.gd, how does item stacking work? ``` **Step 3: Focused changes** ``` In @inventory/item.gd, modify the stack_size property to support different stack limits per item type ``` ### Use Rules for Consistency Document your project's patterns and conventions using Summer Engine's Rules system: ```markdown theme={null} --- description: Combat System Patterns --- 1. All combat entities inherit from CombatEntity base class 2. Damage calculations use DamageCalculator.calculate_damage() 3. Status effects are managed through StatusEffectManager 4. Combat events are broadcast via CombatEventBus 5. Health changes trigger UI updates through HealthDisplay component ``` ### Reference Similar Implementations When adding new features, reference existing patterns: ``` Create a new spell system similar to @abilities/melee_ability.gd Follow the same pattern as @abilities/ranged_ability.gd for targeting Use the cooldown system from @systems/cooldown_manager.gd Integrate with the UI like @ui/ability_bar.gd does for other abilities ``` ## Strategic Planning ### Break Down Large Changes Instead of requesting massive changes, plan incrementally: **❌ Too Broad:** ``` Refactor the entire combat system to support multiplayer ``` **✅ Strategic Approach:** ``` 1. First, let's identify all the places where combat state is stored 2. Then we'll extract combat logic into a separate manager class 3. Next, we'll make the combat state serializable for network sync 4. Finally, we'll add network event broadcasting for combat actions ``` ### Use Ask Mode for Planning Before implementing, use Summer Engine's Ask mode to create detailed plans: ``` I need to add a crafting system to this RPG project. Looking at @inventory/, @items/, and @ui/ folders, create a plan for: - Where to place crafting-related scripts - How to integrate with the existing inventory system - What UI components we'll need - How to store crafting recipes Ask me questions if you need clarification about requirements. ``` ## Choosing the Right Tools ### Tool Selection Guide | **Tool** | **Best For** | **Large Codebase Strengths** | **Limitations** | | -------------- | ------------------------------- | --------------------------------------------------------------------------- | --------------------------------- | | **Glob** | Finding files by pattern | Fast discovery (e.g. `*.gd`, `**/scripts/*.tscn`) without loading full tree | Pattern-based only | | **Grep** | Code search | Find symbols, patterns, references across files | Text/regex only | | **strReplace** | Small, surgical edits | Token-efficient; renames, typos, single-spot changes | Exact match required | | **Subagents** | Deep research, multi-step tasks | Can run parallel 'Explore' tasks; keeps main chat context entirely clean | Asynchronous (runs in background) | | **Chat** | Orchestration, high-level logic | Can coordinate subagents and understand project architecture | Requires clear context management | ### Chat Best Practices for Large Projects **Start Fresh Frequently** * Begin new chats for different features or bug fixes * Avoid letting conversations become too long and unfocused * Summarize important context when starting new chats **Provide Architectural Context** ``` I'm working on the player progression system in our RPG. Architecture: @systems/progression/ contains all progression logic Data flow: XP gains → @progression_manager.gd → @player_stats.gd → UI updates Current issue: Level-up rewards aren't being applied correctly ``` **Use Specific File References** ``` Looking at @systems/combat/damage_calculator.gd and @entities/player.gd, I need to add armor penetration mechanics that reduce damage mitigation ``` ## Code Organization Strategies ### Maintain Consistent Patterns Document and enforce architectural patterns: **Singleton Pattern Documentation:** ```markdown theme={null} --- description: Singleton Manager Pattern globs: "**/managers/*.gd" --- 1. All manager classes extend from BaseManager 2. Use @export var for configuration in editor 3. Initialize in _ready(), cleanup in _exit_tree() 4. Provide static get_instance() method 5. Emit signals for state changes, don't call other systems directly ``` ### Component-Based Architecture For large games, organize code into reusable components: ``` Create a new HealthComponent following the pattern in @components/ - Inherits from BaseComponent like @components/movement_component.gd - Provides health, max_health, and damage/heal methods - Emits health_changed and death signals - Can be attached to any entity that needs health ``` ### System Boundaries Define clear boundaries between systems: ``` The inventory system should only: - Manage item storage and retrieval - Handle item stacking and splitting - Emit inventory_changed signals It should NOT: - Update UI directly (that's the UI system's job) - Handle item usage effects (that's the item system's job) - Manage player stats (that's the stats system's job) ``` ## Performance Considerations ### Selective Context Loading For very large projects, be strategic about context: ``` For this UI bug fix, only include context from @ui/ folder Focus on @ui/inventory_panel.gd and related UI scripts Don't load the entire combat system - it's not relevant here ``` ### Incremental Development Build and test changes incrementally: ``` Let's implement the quest system in phases: Phase 1: Basic quest data structure and storage Phase 2: Quest progress tracking Phase 3: UI integration Phase 4: Reward system integration Start with Phase 1 - create the basic QuestData resource class ``` ## Team Collaboration ### Shared Context Rules Create team-wide rules for consistency: ```markdown theme={null} --- description: Team Coding Standards --- 1. Use PascalCase for class names, snake_case for variables 2. All public methods must have documentation comments 3. Use @export for designer-configurable values 4. Prefix private methods with underscore (_private_method) 5. Group related functionality in the same script file ``` ### Documentation Generation Use Summer Engine to maintain documentation: ``` Generate documentation for the @systems/combat/ folder Include class descriptions, public method signatures, and usage examples Format as markdown for our project wiki ``` ## Debugging Large Systems ### Systematic Debugging Approach bugs methodically in large codebases: ``` I have a bug where player stats aren't saving correctly. Let's trace the data flow: 1. Check @player/player_stats.gd - are stats being updated correctly? 2. Look at @systems/save_system.gd - is the save data being serialized? 3. Examine @data/save_data.gd - is the data structure correct? 4. Review @systems/file_manager.gd - are files being written to disk? ``` ### Isolation Testing Test systems in isolation: ``` Create a simple test scene that only loads: - @systems/inventory_manager.gd - @data/item_database.gd - Basic test items This will help us isolate the inventory bug from other systems ``` ## Takeaways * **Start broad, then narrow**: Understand the big picture before diving into specifics * **Use Rules extensively**: Document patterns and conventions for consistency * **Plan before implementing**: Use Ask mode to create detailed plans for large changes * **Choose appropriate tools**: Match the tool to the task complexity * **Maintain clear boundaries**: Keep systems decoupled and responsibilities clear * **Work incrementally**: Break large changes into smaller, testable pieces * **Create fresh contexts**: Start new chats frequently to maintain focus Working effectively with large codebases is a skill that develops over time. The key is balancing comprehensive understanding with focused action, using Summer Engine's intelligence to navigate complexity while maintaining clear architectural principles. # Summer Cloud: Sync Projects Across Machines Source: https://docs.summerengine.com/guides/summer-cloud Summer Cloud syncs your whole game project, including big binary assets, across machines without Git. Content-addressed storage, version history, checkpoints, and conflict recovery. **Summer Cloud is in research preview.** It works and it's safe by design — every version is retained and restorable — but it's early and evolving fast, so expect rough edges and some commands/limits to change. Tell us what you need at [founders@summerengine.com](mailto:founders@summerengine.com) or on [Discord](https://discord.gg/yUpgtxnZky). ## What is Summer Cloud? Summer Cloud syncs your full game project across machines. Run one command on your desktop, one command on your laptop, and both machines have the exact same project: scenes, scripts, settings, and every binary asset, byte for byte. Game projects mix two kinds of files. Small text files (scenes, scripts, config) merge well in Git. Large binary assets (3D models, textures, audio) do not: Git was not built for them, and Git LFS adds bandwidth bills and setup friction. Summer Cloud handles the whole project tree by content hash, so big assets are first-class. If you use Git, your code can keep living there; Summer Cloud and Git do not fight. If you have never touched Git, you do not need to start. It also means a lost or broken laptop no longer means a lost project. ## Quickstart ```bash theme={null} npx -y summer-engine@latest login ``` Summer Cloud uses your Summer Engine account. Login saves a cloud token to `~/.summer/cloud-token`. ```bash theme={null} npx -y summer-engine@latest cloud init ``` Run this from the project directory (or pass `--project `). It binds the project to Summer Cloud and writes one small file, `summer-cloud.json`, containing the project's cloud ID. That file is the only cloud artifact you would ever commit to Git. ```bash theme={null} npx -y summer-engine@latest cloud push ``` Hashes the project, uploads only the bytes the cloud does not already have, and commits a new version. ```bash theme={null} npx -y summer-engine@latest cloud pull ``` In an empty directory next to a `summer-cloud.json` (for example after a Git clone), or in a directory you point at the same project, this downloads and verifies every file. The project converges to the same bytes on both machines. After the first push, `summer cloud status` shows what would sync, and repeated `push` and `pull` runs keep machines converged. ## How Sync Works Summer Cloud is content addressed. Every file is identified by the sha256 hash of its bytes, and every project state is a manifest: a list of paths mapping to hashes. 1. **Hash locally.** The client walks the tracked tree and hashes each file, using a local cache so unchanged files are not re-read. 2. **Upload only missing bytes.** The client asks the API which hashes the cloud already has, then uploads only the missing blobs. Unchanged files, renamed files, and duplicated files cost nothing to push. 3. **Commit a manifest version.** The client commits a new manifest that points at the verified blobs. The server assigns the next version number. Every version is kept within your plan's retention window and can be restored. Sync decisions come from a three-way comparison between the last synced state on this machine, the current local tree, and the cloud head. Two facts worth knowing: * **There are no clocks in the protocol.** When two machines edit concurrently, the first one to sync wins the canonical path, deterministically. It is not "most recent save wins." * **An edit always beats a deletion.** If one machine deletes a file and another edits it, the edited file survives, and the sync result tells you about it. ## What Gets Synced Everything that makes the game run: `project.godot`, scenes and resources (`.tscn`, `.tres`, and friends), scripts, `.import` and `.uid` sidecars, asset binaries, `addons/`, and export presets. Sidecar files travel with their primary file as one unit, so import settings and resource IDs stay consistent across machines. Some paths are hard excluded and never upload: `.godot/`, `.summer/local/`, `.git/`, `node_modules/`, `.env*` files, OS junk like `.DS_Store`, and temp files. ### .summercloudignore To exclude more, create a `.summercloudignore` file at the project root. It uses gitignore syntax and is itself synced, so every machine and teammate shares one ruleset: ```text theme={null} # .summercloudignore renders/ *.blend1 notes/private/ ``` It can only exclude further; it cannot re-include the hard excludes, so secrets and machine-local state stay out by construction. ## Conflicts and Recovery Summer Cloud is built so a sync can never silently destroy your work. ### Conflicts keep both sides When two machines change the same file in different ways, the cloud version wins the canonical path and your local bytes are preserved in a conflict set under `.summer/local/cloud/conflicts/`. The losing bytes are also uploaded to the cloud, so they survive even if the losing machine dies. Inspect and recover with: ```bash theme={null} summer cloud conflicts # list conflict sets summer cloud conflicts restore # bring a preserved file back as a fresh edit ``` A restored conflict file re-enters the project as a normal edit; push it to make it the new canonical version. ### Checkpoints before destructive applies Before a pull modifies or deletes any existing file, the client writes a full local checkpoint of the project. If a sync did something you did not want: ```bash theme={null} summer cloud checkpoints # list local pre-sync checkpoints summer cloud restore --checkpoint # roll the tree back to one ``` Checkpoint restore brings back the bytes of every checkpointed file. It does not delete files a sync added; the command lists those extra files so you can remove them yourself. ### Version history Every push creates a retained version on the server. You can restore any retained version: ```bash theme={null} summer cloud restore --version 42 ``` This never rewrites history. It creates a new head version with the contents of version 42, then pulls it, so the rollback itself is recorded and reversible. ### Guardrails A push that would delete many cloud files (more than 10, more than 20 percent of the project, or the entire project) refuses to run until you pass `--confirm-deletes`. A push from a directory that suddenly reads as empty (an unmounted drive, the wrong folder) aborts outright. Pulls download to a staging area, verify the hash of every blob, and only then move files into place atomically. ## Storage Plans Cloud storage rides your existing Summer Engine plan: | Plan | Cloud storage | | ----- | ------------- | | Free | 1 GiB | | Basic | 5 GiB | | Pro | 20 GiB | | Pro+ | 100 GiB | | Ultra | 500 GiB | Usage counts the distinct bytes your projects reference, so ten copies of the same texture cost one. Quota is enforced when you push; pulls, downloads, and restores are never blocked, even over quota or after a downgrade. Your data is never deleted for billing reasons. Version retention: free plans keep versions for 7 days or the last 25 versions, whichever is more; paid plans keep 90 days or the last 25 versions. The current head version of every project is always kept. ## Using Summer Cloud with Git The two coexist by design. `summer-cloud.json` is the only file Summer Cloud asks Git to carry, and it almost never changes, so it never causes merge conflicts. A common setup for teams: code reviewed through Git and GitHub, the whole project (including assets) synced through Summer Cloud. One caution: switching Git branches changes files on disk, which Summer Cloud reads as local edits. Sync before and after branch operations, or keep cloud-synced projects on a single branch. See [Connect Your Project to GitHub](/guides/github-from-changes-dock) for the Git side. ## For Agents Every Summer Cloud operation is available three ways with the same behavior: CLI commands, MCP tools, and an HTTP API under `/api/cloud/` at [www.summerengine.com](http://www.summerengine.com). An agent can initialize, push, pull, inspect status, list checkpoints, restore versions, and recover conflicts without a UI. Every summer cloud subcommand with flags and examples The seven summer\_cloud\_\* tools for AI agents ## Current Limits * Single files larger than 4.995 GiB are rejected with a clear error. * A dropped connection on a multi-GiB upload restarts that file from zero. * No file locking or presence yet: two people editing the same binary at once produce a conflict. The conflict is deterministic and recoverable, but it is still a conflict. *** 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. # Web Development with Summer Engine Source: https://docs.summerengine.com/guides/web-development Using Summer Engine for web game development and browser-based projects ## Overview Summer Engine excels at web-based game development, whether you're creating browser games, web-based tools, or hybrid applications. This guide covers best practices for web development workflows in Summer Engine. ## Web Game Development ### HTML5 Game Export Summer Engine can help you prepare games for web deployment: ``` Configure my project for HTML5 export Set up the export template with proper threading settings Optimize asset loading for web browsers Add a loading screen with progress indication ``` ### Browser Compatibility Ensure your games work across different browsers: ``` Check this WebGL shader for compatibility with older browsers Add fallbacks for browsers that don't support WebAssembly Implement touch controls for mobile web browsers Test audio loading across Chrome, Firefox, and Safari ``` ### Performance Optimization Web games require special performance considerations: ``` Optimize texture sizes for faster web loading Implement asset streaming for large games Add compression to reduce download sizes Create a progressive loading system for game assets ``` ## Web Technologies Integration ### JavaScript Interop Bridge between your game and web technologies: ```gdscript theme={null} ## Interface with JavaScript for web-specific features ## Handles communication between engine and browser APIs class_name WebInterface extends Node ## Call JavaScript function from GDScript func call_js_function(function_name: String, args: Array = []): if OS.has_feature("web"): JavaScriptBridge.eval(function_name + "(" + str(args) + ")") ## Receive data from JavaScript func _ready(): if OS.has_feature("web"): JavaScriptBridge.eval("window.godot_ready = true") ``` ### Local Storage Integration Manage web browser storage for save data: ``` Create a web-compatible save system using browser localStorage Implement save data encryption for web deployment Add cloud save synchronization for web players Handle storage quota limits gracefully ``` ### Web APIs Access Integrate with browser APIs for enhanced functionality: ``` Add support for Gamepad API for web controller input Implement fullscreen toggle using the Fullscreen API Use the Web Audio API for advanced audio processing Add support for drag-and-drop file uploads ``` ## Development Workflow ### Live Development Set up efficient web development workflows: ``` Configure the built-in web server for testing Set up automatic browser refresh on code changes Create a debug overlay for web-specific information Implement hot-reloading for faster iteration ``` ### Cross-Platform Testing Test across different platforms and browsers: ``` Create automated tests for different browser engines Set up device testing for mobile web browsers Implement feature detection for progressive enhancement Add analytics to track browser compatibility issues ``` ### Deployment Pipeline Streamline your web deployment process: ``` Set up automated builds for web deployment Configure CDN distribution for game assets Implement cache busting for updated content Add monitoring for web performance metrics ``` ## Common Web Development Patterns ### Responsive Design Create games that work on various screen sizes: ``` Implement responsive UI scaling for different screen sizes Add touch-friendly controls for mobile browsers Create adaptive quality settings based on device capabilities Handle orientation changes gracefully ``` ### Progressive Loading Manage asset loading for better user experience: ``` Create a manifest system for asset dependencies Implement priority loading for critical game assets Add background loading for non-essential content Show loading progress with estimated completion times ``` ### Offline Support Make games work without internet connection: ``` Implement service worker for offline gameplay Cache critical game assets locally Add offline detection and user feedback Create a sync system for when connection returns ``` ## Integration with Web Services ### Authentication Integrate with web-based authentication systems: ``` Add OAuth integration for social login Implement JWT token handling for API access Create secure session management for web games Add single sign-on support for web platforms ``` ### Analytics and Metrics Track player behavior and game performance: ``` Integrate Google Analytics for player tracking Add custom event tracking for game-specific metrics Implement A/B testing for game balance changes Create performance monitoring for web deployment ``` ### Monetization Implement web-friendly monetization options: ``` Integrate with web-based payment systems Add support for in-game advertising Implement premium account features Create subscription management for web users ``` ## Best Practices ### Code Organization Structure your web projects effectively: ``` web/ ├── scripts/ # Web-specific GDScript files ├── assets/ # Web-optimized assets ├── templates/ # HTML templates ├── styles/ # CSS stylesheets └── deployment/ # Build and deployment scripts ``` ### Asset Management Optimize assets for web delivery: ``` Use appropriate image formats (WebP, AVIF) for modern browsers Implement fallbacks for older browsers Compress audio files for faster loading Create multiple resolution versions for different devices ``` ### Error Handling Handle web-specific errors gracefully: ``` Add network error handling for online features Implement graceful degradation for missing features Create user-friendly error messages for web issues Add automatic retry logic for failed requests ``` ## Testing and Debugging ### Browser Developer Tools Leverage browser debugging capabilities: ``` Add console logging for web-specific debugging Use browser performance profiler for optimization Implement remote debugging for mobile browsers Create debug commands accessible from browser console ``` ### Automated Testing Set up comprehensive testing for web deployment: ``` Create unit tests for web-specific functionality Add integration tests for browser API usage Implement visual regression testing for UI changes Set up performance benchmarking for web builds ``` ### User Testing Gather feedback from web users: ``` Add in-game feedback collection system Implement crash reporting for web deployment Create user behavior tracking (with privacy considerations) Set up beta testing programs for web users ``` ## Deployment Strategies ### Static Hosting Deploy to static hosting services: ``` Configure builds for GitHub Pages deployment Set up automated deployment to Netlify Create build scripts for AWS S3 hosting Add custom domain configuration ``` ### CDN Integration Use content delivery networks for better performance: ``` Configure CloudFlare for global content delivery Set up AWS CloudFront for asset distribution Implement cache headers for optimal performance Add geographic content optimization ``` ### Continuous Deployment Automate your deployment pipeline: ``` Set up GitHub Actions for automated builds Create staging environments for testing Implement blue-green deployment for zero downtime Add rollback capabilities for failed deployments ``` ## Takeaways * **Web games require special optimization** for loading times and performance * **Browser compatibility testing** is crucial for reaching all users * **Progressive loading and caching** improve user experience significantly * **Integration with web APIs** enables powerful browser-native features * **Responsive design principles** ensure games work across all devices * **Automated testing and deployment** streamline the development process * **Performance monitoring** helps identify and fix web-specific issues Web development with Summer Engine combines the power of game engine development with modern web technologies, creating opportunities for innovative browser-based gaming experiences. # Working with Context Source: https://docs.summerengine.com/guides/working-with-context How to provide effective context to Summer Engine's AI for better results ## What is Context? When Summer Engine generates code suggestions or responds to your requests, "context" refers to the information provided to the AI model that it uses to understand your intent and current situation. Effective context is the foundation of getting great results from Summer Engine's AI assistance. There are two types of context: 1. **Intent Context**: What you want Summer Engine to do - your instructions, goals, and desired outcomes 2. **State Context**: The current state of your project - code, files, error messages, and project structure ## Why Context Matters The more relevant context you provide, the more accurate and helpful Summer Engine's responses will be. Without sufficient context, you may experience: * **Hallucinations**: The AI making assumptions or creating code that doesn't fit your project * **Generic Solutions**: Responses that don't account for your specific codebase patterns * **Inefficient Results**: Having to iterate multiple times to get the right solution Summer Engine automatically gathers context from your current file, project structure, and recent activity. It also has access to specialized knowledge bases and can research current information to provide better assistance. ## Providing Context in Summer Engine ### The @ Symbol The most direct way to provide context is using the `@` symbol in Summer Engine's chat: | Symbol | Example | Use Case | Best For | | ----------- | ---------------- | ---------------------------- | -------------------------------------------- | | `@file` | `@player.gd` | Reference specific files | When you know exactly which file is relevant | | `@folder` | `@scripts/` | Include entire folders | When multiple related files are needed | | `@function` | `@move_player()` | Reference specific functions | When discussing particular code elements | **Example:** ``` Using @player.gd as reference, create a similar enemy.gd script with different movement patterns ``` ### Project Context Summer Engine understands your project structure and can use it effectively: * **Recent Files**: Files you've been working on recently * **Related Code**: Functions and classes that are connected to your current work * **Project Patterns**: Your coding style and architectural decisions * **Error Context**: Current errors and console output ### Conversation Context Summer Engine maintains context throughout your conversation: * **Previous Requests**: Builds on earlier instructions in the same chat * **Established Patterns**: Remembers the style and approach you've requested * **Project Goals**: Keeps track of what you're trying to accomplish ## Best Practices ### Be Specific About Intent Instead of vague requests, provide clear, specific instructions: ❌ **Vague**: "Make this better"\ ✅ **Specific**: "Optimize this function to reduce memory usage and add error handling" ❌ **Vague**: "Fix the player"\ ✅ **Specific**: "Fix the player movement so it doesn't clip through walls when jumping" ### Provide Relevant State Information Include information about the current state of your project: ``` I'm getting this error: "Cannot call method 'move_and_slide' on null instance" The error happens in @player.gd when the player tries to move Looking at @level.gd, I think the issue might be in how we instantiate the player ``` ### Use Examples and References Point to existing code that works as you want: ``` Create a new weapon system similar to @sword.gd but for a bow The bow should have charging mechanics like @magic_staff.gd Use the same damage calculation system as other weapons in @weapons/ ``` ### Break Down Complex Requests For large changes, break them into smaller, focused requests: **Instead of:** ``` Create a complete inventory system with drag-and-drop, item stacking, equipment slots, and save/load functionality ``` **Try:** ``` First, let's create a basic inventory data structure that can hold items Then we'll add the UI for displaying items Finally, we'll implement drag-and-drop functionality ``` ## Context in Different Scenarios ### Debugging When asking for help with bugs: ``` I'm getting a crash when the player dies. Here's the error: [paste error] The crash happens in @game_manager.gd at line 45 The player death is handled in @player.gd around line 120 ``` ### Feature Development When building new features: ``` I want to add a dialogue system to my RPG Look at @npc.gd to see how NPCs are currently structured The UI should match the style of @ui/menu.gd Store dialogue data similar to how @quest_data.gd works ``` ### Code Review and Optimization When asking for improvements: ``` Review @enemy_ai.gd for performance issues This script runs for 50+ enemies simultaneously Focus on the pathfinding in the _process function Consider the patterns used in @player_controller.gd for optimization ideas ``` ## Advanced Context Techniques ### Contextual Conversations Start conversations with comprehensive context: ``` I'm working on a 2D platformer in Summer Engine Main character: @player.gd (uses CharacterBody2D) Level structure: @level_manager.gd handles scene transitions Current issue: Player sometimes falls through moving platforms in @moving_platform.gd I need help fixing the collision detection between player and moving platforms. ``` ### Reference Patterns Use existing code as templates: ``` Create a new enemy type based on @enemies/goblin.gd It should have the same AI structure but different attack patterns Use the health system from @components/health.gd Follow the same naming conventions as other enemies in @enemies/ ``` ### Cross-Project Learning Reference concepts from other projects or frameworks: ``` I want to implement a state machine for my player character Similar to how Unity's Animator Controller works Apply this to @player.gd's current movement system Keep the existing input handling in @input_manager.gd ``` ## Common Context Mistakes ### Too Much Irrelevant Context ❌ Including entire large files when only a small section is relevant\ ✅ Point to specific functions or sections: "Look at the jump logic in @player.gd lines 50-80" ### Too Little Context ❌ "This doesn't work" without showing what "this" is\ ✅ "The enemy pathfinding in @enemy.gd isn't working - enemies get stuck on corners" ### Outdated Context ❌ Referencing old code that's been changed\ ✅ Always reference current file states and recent changes ## Integration with Summer Engine's Features ### Project Intelligence Summer Engine's [Project Intelligence](/ai-tools/rag-search) automatically provides context about: * Your project's architecture and patterns * Related files and dependencies * Your coding style and conventions ### AI Operations When using [AI Operations](/ai-tools/operations), context helps Summer Engine: * Make changes that fit your existing codebase * Follow your established patterns and conventions * Avoid breaking existing functionality ## Takeaways * **Context is crucial**: The quality of Summer Engine's responses directly correlates with the context you provide * **Be specific**: Clear intent and relevant state information lead to better results * **Use @ symbols**: Explicitly reference files, folders, and functions when relevant * **Provide examples**: Show Summer Engine what you want by referencing existing code that works * **Break down complexity**: Large requests work better when split into focused pieces * **Maintain conversation context**: Build on previous requests in the same chat for continuity Effective context management is a skill that improves with practice. The more you understand your project and can communicate that understanding to Summer Engine, the more powerful the AI assistance becomes. # Working with Documentation Source: https://docs.summerengine.com/guides/working-with-documentation Leverage documentation effectively in Summer Engine through external sources and internal context ## Why Documentation Makes Summer Engine Smarter Imagine trying to build a game without knowing what functions are available, what the current best practices are, or how other developers have solved similar problems. That's what Summer Engine faces without good documentation access. **Documentation gives Summer Engine the "missing manual" for game development.** When you ask Summer Engine to help with something, it needs to know: * Which Summer Engine APIs actually exist and how they work * Current best practices that have evolved since its last training * Real examples from working games * Solutions to common problems that other developers have figured out Without documentation access, Summer Engine can only guess. With it, Summer Engine gives you production-ready solutions. ## Types of Documentation Context ### External Documentation * **Official Engine and Framework Docs**: Summer Engine docs first, plus relevant upstream API documentation, Unity manuals, and Unreal Engine docs when the project calls for them * **API References**: Language specifications, library documentation * **Community Resources**: Tutorials, Stack Overflow discussions, GitHub issues ### Internal Documentation * **Project Documentation**: Architecture decisions, setup guides, deployment procedures * **Code Documentation**: Inline comments, docstrings, README files * **Team Knowledge**: Conventions, patterns, troubleshooting guides ## How Summer Engine Uses Documentation Summer Engine has access to a vast library of game development knowledge that it taps into when helping you. Think of it as having an expert researcher who can instantly find the right information. ### Summer Engine's Research Tools **Summer Engine and upstream API documentation** Summer Engine starts with its own documentation. For APIs inherited from its upstream technical base, it can also consult the relevant Godot Engine API documentation. Match that research to the current [compatibility reference](/reference/compatibility) instead of turning an upstream number into the Summer Engine product version. **Community Knowledge Base** Summer Engine has access to curated examples of common engine workflows: * How to set up different camera systems * Material and shader best practices * Physics body configurations * UI layout patterns * Animation system usage **Real-Time Web Research** Summer Engine can search current tutorials, forums, and resources: ``` "Find current Summer Engine shader examples for water effects and verify inherited APIs against the compatibility reference" "Look up multiplayer synchronization techniques" "Search for performance optimization tips for 2D games" ``` **Learning from Your Project** Summer Engine also learns from how you write code, what patterns you use, and how you structure your game. It combines this with external knowledge to give you personalized advice. ### Referencing Specific Documentation When you know specific documentation exists, reference it directly: ``` Following the Summer Engine API documentation for CharacterBody2D, implement a player controller with proper collision detection Use the move_and_slide() method as described in the official docs ``` ### Framework-Specific Patterns Reference documentation patterns for consistency: ``` Create a custom Resource class following Summer Engine's documented patterns Implement the _get_property_list() method as shown in the engine API docs Use @export annotations according to current GDScript best practices ``` ## Internal Documentation Integration ### Project README Files Keep your project documentation accessible to Summer Engine: ```markdown theme={null} # Game Project Structure ## Core Systems - `systems/combat/` - All combat-related logic - `systems/inventory/` - Item management and storage - `systems/progression/` - Player leveling and skills ## Conventions - All managers are singletons following the pattern in `base/singleton_manager.gd` - UI components inherit from `ui/base_ui_component.gd` - Game events use the centralized event bus in `core/event_bus.gd` ``` ### Inline Code Documentation Write comprehensive code documentation that Summer Engine can reference: ```gdscript theme={null} ## Player controller handling movement, jumping, and basic interactions ## ## This class manages all player input and translates it into game actions. ## It follows the standard CharacterBody2D pattern in the Summer Engine API documentation. ## ## Dependencies: ## - InputManager for input handling ## - PlayerStats for movement parameters ## - EventBus for broadcasting player events class_name PlayerController extends CharacterBody2D ## Movement speed in pixels per second ## Configured in the editor, typical values: 200-400 @export var speed: float = 300.0 ## Jump velocity (negative because Y-axis is inverted) ## Higher absolute values = higher jumps @export var jump_velocity: float = -400.0 ``` ### Architecture Documentation Document high-level architectural decisions: ```markdown theme={null} # Combat System Architecture ## Overview The combat system is built around a component-based architecture where entities can have multiple combat-related components. ## Core Components - `HealthComponent`: Manages health, damage, and death - `AttackComponent`: Handles damage dealing and attack timing - `DefenseComponent`: Manages armor, resistances, and damage reduction ## Event Flow 1. Attack initiated → AttackComponent processes 2. Damage calculated → sent to target's HealthComponent 3. Health changed → UI updated via signals 4. Death triggered → cleanup and rewards processed ``` ## Documentation-Driven Development ### Creating Documentation from Code Generate documentation from existing implementations: ``` Analyze @systems/inventory/ and create documentation covering: - How the inventory system works - Public API methods and their parameters - Integration points with other systems - Common usage patterns and examples ``` ### Updating Documentation from Changes Keep documentation current as code evolves: ``` I've refactored the save system in @systems/save_manager.gd Update the documentation in docs/save-system.md to reflect: - New save file format - Changed method signatures - Updated integration with @systems/game_state.gd ``` ### Documentation-First Feature Development Plan features through documentation: ``` Before implementing the quest system, let's create documentation for: - Quest data structure and properties - Quest state management and progression - Integration with dialogue and inventory systems - Save/load functionality for quest progress This will help us design the API before writing code. ``` ## Best Practices for Documentation Context ### Be Specific About Versions When referencing external documentation, specify versions: ``` Using the current Summer Engine compatibility reference and API docs for custom resources Follow the GDScript 2.0 syntax guidelines Reference current engine networking documentation for multiplayer setup ``` ### Link Documentation to Implementation Connect your code to relevant documentation: ```gdscript theme={null} ## Implements the observer pattern as described in our architecture docs ## See: docs/patterns/observer-pattern.md for usage guidelines class_name EventBus extends Node ## Subscribes a callback to an event type ## @param event_type: String identifier for the event ## @param callback: Callable to invoke when event fires ## @param subscriber: Object that owns the callback (for cleanup) func subscribe(event_type: String, callback: Callable, subscriber: Object): # Implementation follows the pattern documented in observer-pattern.md ``` ### Maintain Documentation Currency Regular documentation maintenance: ``` Review and update all documentation in docs/ folder: - Check for outdated API references - Update screenshots and examples - Verify all links still work - Add documentation for new features added this sprint ``` ## Common Documentation Patterns ### API Documentation Document public interfaces clearly: ```gdscript theme={null} ## Inventory management system for handling player items ## ## Provides methods for adding, removing, and querying items in the player's ## inventory. Supports item stacking, weight limits, and category filtering. ## ## Example usage: ## [codeblock] ## var inventory = InventoryManager.get_instance() ## inventory.add_item("health_potion", 5) ## var potion_count = inventory.get_item_count("health_potion") ## [/codeblock] class_name InventoryManager extends Node ``` ### Setup and Configuration Guides Document project setup procedures: ```markdown theme={null} # Development Environment Setup ## Prerequisites - A current Summer Engine release compatible with this project - Git for version control - Recommended: VS Code with GDScript language support ## Project Setup 1. Clone the repository: `git clone [repo-url]` 2. Open `project.godot` in Summer Engine 3. Configure project settings in Project → Project Settings 4. Run the main scene to verify setup ## Common Issues - If assets don't load: Reimport all assets via Project → Reimport Assets - If scripts show errors: Ensure engine version matches requirements ``` ### Troubleshooting Documentation Document common issues and solutions: ```markdown theme={null} # Common Issues and Solutions ## Player Falls Through Floor **Symptoms**: Player character clips through solid platforms **Cause**: Collision detection running at wrong physics step **Solution**: Move collision code from `_process()` to `_physics_process()` ## Save Files Corrupted **Symptoms**: Game crashes when loading saved games **Cause**: Save data format changed without migration **Solution**: Implement save file versioning in `SaveManager.gd` ``` ## Integration with Summer Engine's Features ### Project Intelligence Enhancement Well-documented code helps Summer Engine's [Project Intelligence](/ai-tools/rag-search) understand: * System boundaries and responsibilities * Integration points between components * Your team's conventions and patterns * Historical context for design decisions ### Better AI Suggestions Comprehensive documentation enables Summer Engine to: * Suggest implementations that follow your documented patterns * Avoid breaking established architectural principles * Provide solutions that integrate well with existing systems * Reference your specific conventions and naming schemes ## Documentation Maintenance ### Regular Reviews Schedule regular documentation updates: ``` Monthly documentation review checklist: - Update API documentation for changed methods - Add documentation for new features - Remove documentation for deprecated systems - Verify all examples still work with current code - Check external links for accuracy ``` ### Automated Documentation Generate documentation automatically where possible: ``` Create a script that generates API documentation from GDScript comments Export class diagrams from the current codebase Generate changelog from git commit messages Update README with current project statistics ``` ### Team Documentation Standards Establish team-wide documentation practices: ```markdown theme={null} # Team Documentation Standards ## Code Comments - All public methods must have doc comments - Complex algorithms need explanatory comments - TODO comments must include assignee and date ## Architecture Docs - Document all major design decisions - Include diagrams for complex systems - Update docs when refactoring systems ## README Files - Each major system folder needs a README - Include setup instructions and examples - Document known limitations and future plans ``` ## Takeaways * **Documentation provides crucial context** that improves Summer Engine's understanding and suggestions * **Reference specific versions** when using external documentation to ensure accuracy * **Maintain internal documentation** that explains your project's unique patterns and decisions * **Generate documentation from code** to keep it current and reduce maintenance burden * **Document architecture and design decisions** to help Summer Engine understand your system boundaries * **Use documentation-driven development** to plan features before implementation * **Regular maintenance is essential** to keep documentation valuable and current Effective documentation is an investment that pays dividends in AI assistance quality, team productivity, and long-term project maintainability. The more context you provide through good documentation, the better Summer Engine can assist with your development work. # Summer Engine: Build a Summer game with AI Source: https://docs.summerengine.com/index Install Summer Engine, create a Summer game in GDScript, add Summer SDK capabilities, test locally, and publish. Summer Engine is the AI game engine for building a **Summer game**. Start in the editor, write gameplay in **GDScript**, add the **Summer SDK** capabilities your game needs, then test and publish from one documented path. Describe what you want to build or change in natural language. Summer Engine can work across your scenes, scripts, and assets while you review the changes in the same project. **What makes Summer Engine different:** * **One creator path**: Install, create, integrate the Summer SDK, test, publish, and update. * **GDScript by default**: Start with the creator language used throughout these guides. * **Portable source**: Your project stays yours. Familiar formats improve portability, but editor-version, import, plugin, native-extension, and export compatibility still need verification. * **Project Intelligence**: AI understands your scenes, scripts, assets, and game logic * **Reviewable Operations**: Changes go through editor APIs; review the diff and test the project after each operation * **Privacy controls**: Pro accounts can enable Privacy Mode to opt out of training-data use ## Start here Follow this path in order: Install the editor on macOS or Windows and verify it opens. Create a project and make GDScript your default gameplay language. Add the minimal game structure and connect the Summer SDK. Choose multiplayer, player, persistence, economy, and publishing capabilities. Validate the Summer game before using a limited publish request. Export a game-only pack, submit it for human review, and follow the update path. ## Other ways to start Use the canonical prompt to build a Summer game with Summer Engine and the Summer SDK. Use Summer Agent to draft scenes and GDScript, then review and test the generated work. CLI lets Claude Code, Cursor, Devin Desktop install and run Summer Engine. You chat in your IDE; the AI uses MCP tools. Build and export a Windows game with Summer Agent Build and export a macOS game with Summer Agent Create a browser-playable game with Summer Agent Build and export an iPhone or iPad game with Summer Agent Build and export an Android game with Summer Agent Build a Nintendo Switch, PlayStation, or Xbox game with Summer Agent Build and export a PlayStation game with Summer Agent Rebuild your Unity project in Summer Engine with Summer Agent Rebuild your Unreal project in Summer Engine with Summer Agent Use the compatibility and migration path instead of the new-creator sequence. ## How Do I Make Games with My IDE? Add Summer Engine to Cursor, Claude Code, Devin Desktop, or your favorite AI-powered editor: Add Summer Engine to Cursor. One-click or manual config. Full page. Add Summer Engine to Claude Code. Full setup guide. Add Summer Engine to Devin Desktop. Full setup guide. Add Summer Engine to Antigravity. Full setup guide. Add Summer Engine to Codex. Full setup guide. Add Summer Engine to VS Code or Copilot. Full setup guide. Add Summer Engine to Zed. Full setup guide. ## Learn Deep dives into Summer Engine's capabilities: How to make games with Summer Engine from your IDE. MCP setup, CLI, API reference. How Summer Engine modifies your project safely through natural language How AI understands your entire codebase, scenes, and assets Create 2D art, 3D models, and audio with AI Prepare an export with the templates and toolchains installed for your target. Store submission remains creator-controlled. ## Knowledge Base Common questions about Summer Engine: The AI game engine. Build games by describing them. Commit a copy first, then verify the editor, imports, plugins, native extensions, and exports against the compatibility reference. Privacy Mode is available on paid plans. When enabled, code is never stored by model providers or used for training. Great for prototyping and indie games. Learn the tradeoffs. Start in natural language. Summer Agent can draft scenes and GDScript while you review, test, and integrate the result. Founders respond personally. Discord, email, and more. ## What You Can Do Summer Engine brings AI directly into your game development workflow. Whether you want to describe a game in plain English or dive deep into engine code, Summer Engine adapts to you. Describe scene changes in plain English - "Add a player that can jump" AI understands your entire project - code, scenes, assets, and relationships Expert AI agents for 3D modeling, audio design, and complex systems Generate art, models, and audio - clearly labeled as AI-generated ## For Pros and New Game Devs Summer Engine is designed for everyone who wants to make games. It combines the ease of "vibe coding" with the power of a professional game engine. ### For Creators & Vibe Coders * **Start in natural language**: Ask Summer Agent to draft scenes and GDScript, then review and test the result * **Documented asset workflow**: Follow the asset-generation guide for currently supported providers, licensing, and quality tradeoffs * **Learn as you go**: Watch how Summer Engine builds things to learn game development naturally * **Focus on fun**: Skip the boilerplate and get straight to the gameplay ### For Professional Developers * **Ship commercial games**: We shipped *Don't Pray* on Steam in 2.5 months using Summer Engine * **Full Engine Access**: You have total control over every node and script * **Code Quality**: AI writes clean, structured GDScript that follows best practices * **Accelerated Workflow**: Handle tedious tasks instantly so you can focus on architecture and polish Summer Engine removes boilerplate and accelerates iteration while giving you the option to dive as deep as you want. New models are evaluated before they are exposed; availability is documented instead of promised on a fixed schedule. One editor, one context. Design, code, and playtest without tab juggling. Bring in 3D or Audio AI specialists on demand. Deep help without leaving flow. Engine‑level edits with full undo. No surprise file rewrites. Evaluate a committed copy of an existing project. Familiar formats and concepts reduce migration work; verify imports, plugins, native extensions, and exports against the current Summer Engine release. ## Ready to Build? Get started with the AI game engine today Start from a template: shooter, RPG, platformer, horror, 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. # Can I make AAA games with Summer? Source: https://docs.summerengine.com/knowledge-base/aaa-games Summer is designed for indie and mid-scale projects. Sweet spot: 3-12 months for projects that traditionally take 1-7 years. Summer is designed for indie games, small teams, and professional studios building mid-scale projects. The engine foundation powers commercial games across all platforms. Summer adds AI tooling to accelerate development. **Sweet spot**: Projects that would traditionally take 1-7 years can be built in 3-12 months with Summer. # How good are AI-generated assets? Source: https://docs.summerengine.com/knowledge-base/ai-asset-quality Great for prototyping and indie games. Learn the tradeoffs and when to use human artists. ## Honest Answer: Good for Prototyping and Indie Games AI assets in Summer Engine are designed for rapid iteration and getting your game playable quickly. They work best for simple, clear concepts. Complex or highly stylized assets may need refinement. They are not suitable for polished, commercial AAA releases where every asset must match exact specifications. ## What AI Assets Do Well **Rapid concept exploration.** Try different visual directions without commissioning art. Generate a low-poly tree, a cartoon character, a pixel-art sword. See what fits your game. **Placeholder assets during development.** Need a crate, a barrel, a floor texture? AI generates it in seconds. Your game is playable while you iterate on mechanics. **Quick iteration on visual ideas.** "Make it more weathered." "Add a glow effect." "Change the color to blue." Refine in real time. **Indie game aesthetics.** Many successful indie games use a cohesive AI-assisted or stylized look. Low-poly, pixel art, and cartoon styles work well. **Specific use cases.** Basic character sprites, simple environment backgrounds, UI elements, concept art and mood boards. Summer Engine offers style presets: Realistic, Cartoon, Anime, Pixel Art, Low-Poly, Fantasy. ## What AI Assets Are Not Good For **Final AAA production art.** Big-budget games need art that matches exact specs, passes legal review, and meets studio quality bars. AI assets are not there yet. **Specific, highly detailed character designs.** "A knight with a scar over his left eye, wearing rusted armor, holding a broken shield." AI may get close but often misses fine details. Human artists excel here. **Brand-consistent visual style across many assets.** Maintaining exact style across 100+ assets is hard for AI. Human art direction is better. **High-quality promotional materials.** Key art, trailers, store assets. These need human polish. ## All AI-Generated Assets Are Labeled Summer Engine clearly labels AI-generated assets. We strongly encourage using human artists for final production work when you have the budget. AI is a tool for speed and iteration; human artists are for polish and specificity. ## The Workflow Use AI assets to prototype and iterate. When you're ready to ship, replace key assets with human-created art if your budget allows. Many indies ship with a mix: AI for props and environments, humans for main characters and key art. ## Related Create 2D, 3D, and audio with AI # Can I make a game with just AI, no coding? Source: https://docs.summerengine.com/knowledge-base/ai-game-dev Yes. Describe what you want and Summer Engine writes the code. AI game dev and vibe coding for games. ## Yes: No Coding Required You can build complete games by describing what you want in plain English. Summer Engine writes the code, creates assets, and sets up your game. No coding experience required. This is sometimes called **AI game dev** or **vibe coding for games**. You focus on the creative vision; Summer Engine handles the implementation. ## What You Can Ask For Summer Engine understands natural language. You don't need to be precise. Examples: **Game systems:** "Create a 2D platformer with double jump," "Add a health bar and damage system," "Build a main menu with Start and Settings" **Assets:** "Generate a low-poly tree for my forest," "Create a wooden crate texture," "Add footsteps on gravel" **Mechanics:** "Make the camera follow my player," "Add enemies that chase the player," "Implement a scoring system" **UI:** "Add a pause menu," "Create a settings screen with volume sliders," "Build an inventory panel" ## How It Works 1. You describe what you want. Summer Engine shows you a plan of what it will change. 2. You review and approve. Changes go through safe operations. Nothing breaks unexpectedly. 3. You iterate. "Make the jump higher," "Add more platforms," "Change the enemy speed." 4. Every change is undoable with Ctrl+Z. Summer Engine doesn't just suggest code. It implements directly in your project. When you ask for "a health system for my player," it creates the script, connects it to your player scene, and sets up any required UI. Assets it generates (textures, 3D models, audio) are placed in the right folder and connected automatically. ## What Summer Engine Can Build **Game logic.** Character controllers, inventory systems, AI behaviors, network sync for multiplayer. Production-ready code that integrates with your existing codebase. **Visual assets.** UI textures, tilesets, character sprites, particle effects. AI-generated, clearly labeled. Good for prototyping and indie aesthetics. **Audio.** Background music, sound effects, ambient loops. Summer Engine integrates with ElevenLabs and other providers. **Documentation.** Code comments, design docs, technical guides. Living documentation that stays current. ## Learning as You Go Summer Engine explains what it's doing as it builds. If you want to understand the engine, Summer Engine acts as an infinite tutor. If you just want to ship a game, describe it and let Summer Engine handle the rest. ## Related Full guide to building with AI # Which AI models does Summer use? Source: https://docs.summerengine.com/knowledge-base/ai-models Summer routes across many providers. The model selector is the live list; asset generation picks its own backends. Summer Engine runs on many providers rather than one. Which one handles a given request depends on what you asked for and what you picked in the model selector. ### The chat agent The agent that writes your code and drives the editor is whatever model is selected in the chat composer. * **Auto** (the default, on every plan) routes to a fast long-context coding model chosen for the balance of quality, cost, and reliability. The specific model changes as we improve the routing. * **MAX** (paid plans) routes to a frontier model and maxes out context and tool calls, billed at the API pricing of whatever it selects. * **Picking a model yourself** gives you a specific model from OpenAI, Anthropic, DeepSeek, GLM, Kimi, Grok, or Qwen. The model selector is the live list. It is rendered from the running catalog and it tells you each model's context window and cost warning. See [Models](/auto-mode/models) for how selection and plan access work. ### Asset generation Asset generation does not use the chat model. Each asset type has its own backends, and Summer picks one based on the job: | Asset | How it is generated | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Images** | Several hosted image models — currently Nano Banana, Seedream, Grok Imagine, GPT Image, and Gemini Flash Image, plus FLUX.2 behind the dedicated pixel-art tab. | | **3D models** | Meshy, Rodin, Tripo, Hunyuan, and Trellis, covering text-to-3D, image-to-3D, and multi-view, plus rigging and animation. | | **Audio** | ElevenLabs, for voice, dialogue, sound effects, and music. | | **Video** | Veo, Kling, Seedance, and Gemini Omni Flash, for cutscenes and image-to-video. | In Summer Studio you choose the backend yourself from a picker that shows each model's price. In chat, the agent picks one for the job. Prices differ by orders of magnitude — an image costs cents, a textured 3D model can cost most of a dollar — which is why the picker shows the cost next to every model. ### Choosing models You choose the chat model in the selector next to the composer. Asset backends are chosen per generation inside Summer Studio, where the model list and its prices are shown live. Summer does not accept your own provider API keys for hosted generation — hosted AI runs on your plan's usage. If you want to run your own model against your project, use the [MCP server](/mcp/overview) instead: point Cursor, Claude Code, or any other harness at Summer and drive the editor with whatever model you already pay for. **Staying Current**: When new AI models are released, Summer typically integrates them within 24 hours to ensure you always have access to the latest capabilities. # What are the limitations of AI operations? Source: https://docs.summerengine.com/knowledge-base/ai-operations-limitations AI changes go through safe APIs. Some tasks still require manual work. Learn what works well and what doesn't. ## What Works Well Summer Engine's AI can do a lot directly in your project: **Scene modifications.** Add nodes, set properties, connect signals. "Add a CharacterBody2D named Player." "Set the Button text to 'Start Game'." "Connect the Button's pressed signal to start\_game." Changes appear immediately in the editor. **Script operations.** Create scripts, attach them to nodes, open your external editor for code. Summer Engine writes production-ready code that integrates with your existing codebase. **Asset import.** Import 3D models, textures, and audio from Summer Studio. "Import a low-poly tree for my forest." "Build a village: houses, trees, fences, and props." Summer Engine searches, downloads, runs the import pipeline, and places assets. Bulk import is supported. Many assets in one batch. **Project settings.** Change main scene, physics layers, window size. Add input actions (jump, movement, controller mappings). **Game systems.** Character controllers, inventory systems, AI behaviors, network sync. Summer Engine builds complete systems, not just snippets. Changes go through project-bound tools with explicit targets and exact receipts. Scene operations integrate with the editor's undo history; file operations are applied atomically and reject stale overwrites. ## Things People Expect to Be Limits, But Are Not **Explicit scene targets.** A scene does not need to be open or visible before Summer changes it. Each mutation names one exact `scenePath`, so cross-scene work proceeds scene by scene without relying on whichever editor tab happens to be active. **Recoverable tool failures.** A failed tool call is not automatically a failed task. Summer returns the concrete reason—for example, a missing scene dependency or stale file receipt—so the AI can inspect the current state, repair it, and retry. **Concurrent work.** Main agents and subagents can work at the same time without a routine whole-project writer lock. If two edits collide on the same file, the stale overwrite is refused and the AI must reread before deciding whether to retry. ## Current Limitations **No batch code refactors.** Large refactors across many files (e.g., rename a function in 50 files) are not supported yet. Bulk asset import is supported; bulk code refactors are not. **Limited import settings.** Asset import options are mostly manual for now. You may need to adjust import settings in the editor for some assets. **Shell commands require approval.** Summer Engine can propose shell commands (run tests, install deps, run scripts), but nothing executes until you approve it. This is by design. You stay in control. **A file written to disk is not loadable until it is imported.** Writing `res://raw.png` and then calling `load()` on it fails with `No loader found for resource: res://raw.png`. The editor has to run an import pass before the file becomes a real resource. This is the usual explanation for "the AI wrote my asset but nothing can find it." See [Headless Scripting](/automation/headless) for the import pass and for the resource-authoring route that needs no import at all. **`LightmapGI.bake()` cannot be called from a script.** The method is not bound in the scripting API — upstream Godot behaviour, not a Summer change — so lightmap baking cannot be driven from GDScript, in the editor or at runtime. **`OccluderInstance3D.bake_single_node()` is not bound either.** Occlusion baking is still reachable, through the editor's own built-in plugin. [Editor Plugins](/extending/editor-plugins) has the working recipe. **Anything needing `EditorInterface` is editor-only.** `EditorScript`, `EditorPlugin`, `EditorInterface` and `EditorFileSystem` cannot be instantiated by an ordinary script. The supported route is a `@tool` [editor plugin](/extending/editor-plugins), which gets the whole `EditorInterface`, including forced reimports and saving scenes from code. ## What's Safe * Explicit project, file, and scene targets * Exact engine and file receipts * Conflict-aware file writes that refuse stale content * Editor undo support for scene operations ## Best Practices **Review before applying.** The change review panel shows exactly what will be modified. Check it before confirming. **Trust, then verify receipts.** Scene mutation tools append one final save automatically. If a receipt reports failure, use its exact reason to repair or reread before retrying. **Use undo freely.** Don't hesitate to undo AI changes that aren't quite right. You can always ask for a different approach. ## Related What Summer Engine can do # Is Summer for beginners or professionals? Source: https://docs.summerengine.com/knowledge-base/beginners-or-professionals Summer is for everyone. Vibe coders and professional developers alike. **Summer is for everyone.** We believe making games should be as fun as playing them. * **For Beginners & Vibe Coders**: You can build complete games just by describing them in plain English. Summer Engine handles the code, assets, and scene setup. It's the perfect way to "vibe code" your dream game into existence without needing years of experience. * **For Professionals**: Summer is a production-ready tool that accelerates your workflow. We shipped a commercial Steam game (*Don't Pray*) in 2.5 months using Summer. You get full access to the underlying engine, clean code generation, and complete control over your architecture. # Can I use my own assets? Source: https://docs.summerengine.com/knowledge-base/custom-assets Yes. Import your own 2D art, 3D models, and audio. AI generation is optional. ## Yes: Your Assets Work Summer Engine supports standard asset formats. You can import your own 2D art, 3D models, and audio. AI generation is optional. Many developers use a mix: their own art for key assets, AI for placeholders or iteration. ## How to Import **Drag and drop.** Drag files into the project folder or use the import dialog. Standard formats work: PNG, JPG, WebP for images; OBJ, FBX, glTF for 3D; WAV, OGG, MP3 for audio. **Import dialog.** Use the engine's standard import flow. Summer Engine doesn't change how importing works. It's the same as the underlying engine. **Summer Studio.** You can also upload and organize assets in Summer Studio, then have Summer Engine import them into your project on command. "Import the tree asset from my collection." ## AI Generation Is Optional You don't have to use AI for assets. If you have an artist, use their work. If you buy assets from stores, use those. Summer Engine's AI generation is there when you need placeholders, quick concepts, or iteration, not as a requirement. ## Mixing Your Assets and AI Common workflow: Use AI to generate placeholder art during development. When you're ready to ship, replace key assets with human-created art. Or use AI for props and environments, humans for main characters and key art. Summer Engine doesn't care. It works with whatever assets you have. ## Asset Integrity Summer Engine doesn't modify your source asset files unless you ask it to. When Summer Engine generates an asset, it's clearly labeled as AI-generated. Your imported assets stay yours. The engine handles them the same way regardless of source. ## Related Create assets with AI Search the asset store for CC0 game assets # How do I export to mobile (iOS and Android)? Source: https://docs.summerengine.com/knowledge-base/export-mobile Enable ETC2 ASTC texture format, create mobile export preset, configure signing. iOS requires Mac and Apple Developer account. ## Both iOS and Android Are Supported Summer Engine can export to iOS and Android. The flow is similar for both: enable the right texture format, create an export preset, configure signing, and export. iOS has additional requirements (Mac, Apple Developer account). ## Step 1: Enable Texture Compression Mobile devices use ETC2/ASTC texture format. Before exporting: 1. Project → Project Settings 2. Rendering → Textures → VRAM Compression 3. Enable **Import ETC2 ASTC** 4. Wait for reimport (1-5 minutes depending on project size) ## Step 2: Create Export Preset Project → Export → Add → iOS or Android. You'll see the export configuration panel. ## Step 3: Configure for Your Platform **iOS:** * **Bundle identifier**: Unique ID in reverse-domain format (e.g. `com.yourstudio.yourgame`) * **Provisioning profile**: Required for App Store. You need an Apple Developer account (\$99/year) * **Signing**: Configure in the export panel. Xcode may be involved for final submission **Android:** * **Package name**: Unique identifier (e.g. `com.yourstudio.yourgame`) * **Signing keys**: Required for Google Play. Create a keystore and configure in the export panel ## Step 4: Add Mobile-Specific Features Ask Summer Engine to add touch controls, responsive UI for different screen sizes, and device orientation support. "Add touch controls for mobile." "Implement responsive UI for phones and tablets." "Optimize for mobile performance." ## iOS-Specific Requirements * **Mac required**: iOS export and App Store submission are done from macOS * **Apple Developer account**: \$99/year. Required for App Store distribution * **Provisioning and signing**: Apple's process. Summer Engine's export produces the build; you use Xcode or Transporter for submission ## Android-Specific Notes * **Windows or Mac**: Android export works on both * **Google Play**: Requires a developer account (one-time \$25 fee) and signing keys * **Alternative stores**: You can distribute the APK directly (e.g. itch.io, your website) without Google Play ## Testing Test on real devices before submitting. Emulators don't always match real performance. Use Project → Export → Run to test on a connected device. ## Related Make an iOS game with AI Make an Android game with AI All platforms # Is Summer Engine compatible with my existing project? Source: https://docs.summerengine.com/knowledge-base/godot-compatibility Summer uses familiar upstream-compatible formats, while minimum and recommended project compatibility ranges remain unmeasured. ## Start with the measured compatibility contract Summer Engine uses familiar text scene, resource, script, and project formats. The current upstream technical base is 4.7.2, no next upstream version is currently claimed, and Summer follows upstream continuously. The minimum and recommended project compatibility ranges are not yet measured, so this page does not promise that every historical project opens unchanged. ## What to evaluate **Portable source formats.** `.tscn` scenes, `.gd` scripts, `.tres` resources, and `project.godot` configuration use familiar upstream-derived formats. This is a format fact, not proof that every file produced by every upstream release loads unchanged. Commit before the first open, then review import and configuration changes normally. **Third-party libraries and plugins.** Pure GDScript addons are the safest case. Native extensions, custom editor integrations, and addons pinned to a different upstream version need explicit compatibility testing. **Export targets.** Verify the installed templates and run an exported-build smoke test for each target. Do not infer web, desktop, mobile, or native-extension compatibility from the upstream base alone. **Team workflows.** Mixed-editor teams can share the repository when they pin compatible versions and review generated changes. Shared formats reduce friction; they do not guarantee zero differences between editors or importers. ## What Happens When You Open Your Project 1. **File → Open Project** (or Project Manager) → browse to your project folder → select `project.godot` 2. Summer Engine automatically indexes your project (30 seconds to 2 minutes depending on size) 3. The AI learns your scenes, scripts, assets, and relationships 4. You start chatting. Describe what you want to change; Summer Engine applies it ## Zero Lock-in Your Summer game remains yours: GDScript, text scenes, resources, and assets stay in documented formats. Opening them in another compatible editor may require an import pass and does not carry Summer-only AI or platform surfaces. ## Version Compatibility Use the generated [Compatibility & upstream](/reference/compatibility) page for the current base and measured claims. Projects from Godot Engine 3.x need the upstream 3→4 migration before they can be evaluated against Summer Engine's current base. ## Related Open your project in Summer Engine in 5 minutes # What if I have an existing project? Source: https://docs.summerengine.com/knowledge-base/godot-projects Open a compatible project in Summer Engine, review the first import, and continue building a Summer game. Open a committed copy in Summer Engine and review the first import. GDScript, text scenes, resources, and assets use familiar formats; native extensions, editor plugins, and version-sensitive imports still need compatibility testing. The generated [compatibility reference](/reference/compatibility) is the source of truth. ## Related Open your project in Summer # What's the learning curve? Source: https://docs.summerengine.com/knowledge-base/learning-curve Gentle to advanced. Vibe coding has near-zero curve. Master the engine with AI as your tutor. **Gentle to Advanced.** If you just want to vibe code, the learning curve is near zero. Just chat with the AI. If you want to master the engine, Summer acts as an infinite tutor, explaining how things work as it builds them. It's the fastest way to learn game development. # Does Summer support multiplayer games? Source: https://docs.summerengine.com/knowledge-base/multiplayer Yes, with limitations. Basic multiplayer networking works with AI assistance. **Yes, with limitations.** Summer Engine includes multiplayer APIs and transports for games you run and deploy yourself. Hosted Summercraft multiplayer is a separate platform capability and is not production-live yet. ## What Works Today * **High-level multiplayer API**: `MultiplayerPeer`, `MultiplayerSpawner`, and `MultiplayerSynchronizer` all work in Summer Engine. The AI can help you set them up through natural language. * **ENet and WebSocket transports**: Local LAN multiplayer and WebSocket-based online multiplayer are both supported out of the box. * **RPC and state synchronization**: Remote procedure calls (`@rpc`) and automatic property synchronization work as expected. Ask the AI to set up synchronized variables and it will generate the correct annotations. * **Dedicated server exports**: You can export headless server builds for Linux deployment. ## What the AI Can Help With The AI assistant can generate multiplayer boilerplate, set up lobby systems, configure spawners and synchronizers, and debug common networking issues like authority conflicts and desync problems. For example, you can say "make this character controller work in multiplayer" and the AI will add the necessary RPC calls and authority checks. ## Current Limitations * **No built-in matchmaking or relay servers**: Summer does not yet provide production hosted multiplayer infrastructure. Bring your own server for a game you operate today. * **Complex netcode patterns**: Advanced techniques like client-side prediction, rollback, and lag compensation require manual implementation. The AI can assist but these are inherently complex. * **Testing**: Multiplayer testing requires running multiple instances manually. ## Summer SDK platform contract The [Summer SDK](/api-reference/summer-sdk) documents the creator-facing contract for host-authoritative gameplay, synced state, persistence, economy, and submission. The submission and review APIs are live. Player-facing playback, hosted dedicated game servers, automatic matchmaking, and the production runtime sandbox are not live yet. Track the canonical [platform capability status](/knowledge-base/source-status#platform-capability-status) before making launch promises. # How do I get started with no game dev experience? Source: https://docs.summerengine.com/knowledge-base/no-experience Download Summer Engine, create a project, describe what you want. No coding required. AI does the rest. ## You Don't Need Any Experience Summer Engine is designed for people who've never made a game. You describe what you want in plain English. Summer Engine writes the code, creates assets, and sets up your game. No coding, no engine tutorials, no prior knowledge required. ## The Path **1. Download Summer Engine.** Visit [summerengine.com](https://summerengine.com). Download for Mac or Windows. Free. No credit card. **2. Create an account.** Open Summer Engine, click Sign in. Use Google, GitHub, or email. Takes a minute. **3. New Project.** Click New Project. Give it a name (e.g. "My First Game"). Choose a folder. Click Create & Open. **4. Describe your game.** In the chat panel, type what you want. Examples: * "Create a simple platformer where I can jump" * "Make a clicker game with a counter" * "Build a top-down game where I move with WASD" **5. Iterate.** Summer Engine builds it. You playtest (press Play). Want changes? "Add more platforms." "Make the character jump higher." "Add a score." Summer Engine updates it. ## What You'll Learn Summer Engine explains what it's doing as it builds. You'll see the code it creates, the nodes it adds, the logic it implements. If you want to understand game development, Summer Engine acts as a tutor. If you just want to ship a game, you can stay at the "describe what you want" level. ## The Learning Curve For vibe coding (describe and build), the curve is near zero. For mastering the engine, Summer Engine teaches you as you go. It's one of the fastest ways to learn game development because you're learning by doing, with an AI that can answer any question. ## Common First Steps After your first game is running, try: * "Add a main menu with Start and Quit" * "Generate a character sprite for my player" * "Add sound effects when I jump" * "Make the camera follow my player smoothly" Each request teaches you something new. No need to study first. Just build. ## Related Build a game with just AI Start from a template: shooter, RPG, platformer, horror, and more # Is Summer free? Source: https://docs.summerengine.com/knowledge-base/pricing Free to download and try. Free tier with core AI features. Premium features available through subscription. **Free to download and try.** The desktop app and local MCP workflows are free. Create an account to try hosted Summer AI and asset generation; premium plans (Pro, Pro+, Ultra) increase hosted AI usage limits. See [Pricing](/essentials/pricing) for full plan details, or visit [summerengine.com/pricing](https://summerengine.com/pricing) to subscribe. For the exact open, free, and paid split, see [What is open in Summer Engine?](/knowledge-base/source-status). # Is my code safe? Source: https://docs.summerengine.com/knowledge-base/privacy-and-code-safety Privacy Mode is a Pro feature. When enabled, we guarantee that code data is never stored by our model providers or used for training. ## Privacy Mode **When Privacy Mode is enabled, we guarantee that code data is never stored by our model providers or used for training.** Privacy Mode is included on all paid plans. It is **off by default** for every account, including Pro — you turn it on explicitly in account settings, and from that point forward it applies to all chats and operations sent from your account. Privacy Mode is a paid-plan feature. The Free plan does not include Privacy Mode. ## What Happens When Privacy Mode Is Off Privacy Mode is off by default for all accounts. When Privacy Mode is not enabled, we may use and store prompts, generated outputs, code snippets, editor actions, and other code data to improve our AI features and train our models. Free accounts do not have access to Privacy Mode and operate in this mode by default. ## What's Always True * **Encryption.** All data is encrypted in transit (TLS 1.3) and at rest (AES-256). * **No selling your data.** We do not sell your code, prompts, or game projects to third parties. * **Safety carve-out.** Content flagged for safety or security review may be retained regardless of Privacy Mode. * **Feedback carve-out.** Content you explicitly share with us as Feedback or in a bug report may be reviewed and used to improve Summer Engine, regardless of Privacy Mode. For the full legal text, see our [Privacy Policy](https://summerengine.com/privacy), specifically the section "How we use your prompts and code". ## How to Enable Privacy Mode Privacy Mode is available in your account settings on any paid plan. Once enabled, it applies to all chats and operations sent from your account from that point forward. ## Related Full privacy documentation Legal text on prompts, code, and training-data use # Has Summer been used for production games? Source: https://docs.summerengine.com/knowledge-base/production-games Yes. We shipped Don't Pray on Steam in 2.5 months. It's a commercial product. **Yes.** Summer is built by game developers, for game developers. We shipped *Don't Pray* on Steam, a P2P 3D PvP co-op game with multiplayer networking, combat systems, and Steam integration, in 2.5 months. A project that would have taken us 1-2 years before Summer. It's not a demo; it's a commercial product. # How does project intelligence work? Source: https://docs.summerengine.com/knowledge-base/project-intelligence AI indexes and understands your entire codebase, scenes, assets, and relationships automatically. ## What Project Intelligence Does Summer Engine automatically analyzes and indexes your project when you open it. The AI learns your code structure, scene hierarchies, asset relationships, and project patterns. When you ask a question, Summer Engine uses this index (RAG: Retrieval-Augmented Generation) to find relevant context and give you accurate, project-specific answers. ## What Gets Indexed **Code structure.** Classes, functions, variables, and their relationships. Summer Engine knows which script controls the player, what `speed` does, and how to modify it safely. **Scene hierarchy.** Node trees, components, connections. Summer Engine understands that your Player has a MeshInstance3D and CollisionShape3D, and that the HealthBar UI references the player. **Asset relationships.** Textures, models, sounds, and where they're used. Summer Engine knows which assets are in which scenes. **Project patterns.** Your coding style, naming conventions, architecture. Summer Engine suggests changes that fit how you already work. ## How Indexing Works When you open a project, Summer Engine scans all files (scripts, scenes, resources, project settings), builds a knowledge graph of connections, and learns your patterns. Indexing takes 30 seconds to 2 minutes depending on project size. It runs in the background. **Per-project indexing.** Each project has its own isolated index. When you switch projects, Summer Engine uses that project's index. **Smart caching.** The index persists between sessions. Summer Engine remembers what it learned so you don't start from scratch every time you open Summer Engine. **Incremental updates.** Only changed files are re-analyzed, keeping things fast. ## What This Enables **Context-aware help.** When you ask "add a health bar to my player," Summer Engine knows which player script and scene to modify. It doesn't guess. It looks at your project. **Smart suggestions.** "I noticed you're using get\_node() in \_process. Let me cache those references." "This signal connection could be done in the editor instead of code." "Adding null checks here would prevent crashes." **Conflict prevention.** Summer Engine avoids naming conflicts and maintains scene integrity. It builds on your existing work rather than overwriting it. ## How Your Code Is Processed Project intelligence is a server-side feature. When files change, Summer chunks them, computes embeddings, and stores those chunks together with their file paths so search and context selection can run over them. When you ask Summer to generate or modify code, the relevant context is sent to AI providers. Privacy Mode, available on paid plans, stops your code being used to train models. See [Privacy Mode](/security/privacy-mode) and the full subprocessor list in [Security Overview](/security/overview). ## Large Projects For projects with thousands of files, Summer Engine prioritizes recently modified files, can focus on specific folders, and processes in the background without blocking your work. ## Related Deep dive on RAG search # How do I publish to Steam? Source: https://docs.summerengine.com/knowledge-base/publish-steam Export your game, then submit to Steam. $100 Steam Direct fee, 1-3 day approval. Full guide inside. ## Overview Publishing to Steam involves building your game in Summer Engine, exporting for Windows (and/or Mac), creating a Steamworks account, paying the Steam Direct fee, and submitting your build. Summer Engine includes export templates. You don't need to install anything extra. The export process is the same as for itch.io or direct download; Steam is another distribution channel. ## Step-by-Step **1. Build your game.** Create and polish your game in Summer Engine with AI assistance. **2. Enable texture compression.** Before exporting, go to Project → Project Settings → Rendering → Textures → VRAM Compression. Enable S3TC BPTC for Windows, ETC2 ASTC for Mac. If releasing on both, enable both at once. **3. Export.** Project → Export → Add → Windows Desktop (or macOS). Configure (64-bit, Embed PCK for single .exe), then Export. You get a standalone build. **4. Create Steamworks account.** Go to [partner.steampowered.com](https://partner.steampowered.com). Sign up, pay the \$100 Steam Direct fee (one-time per game). **5. Set up your store page.** App name, description, screenshots, trailer, tags, age rating. Steam has specific requirements for each. **6. Upload your build.** Use the Steamworks upload tools. Configure depots, build IDs, and release branches. Test with the Steam client. **7. Submit for review.** Steam reviews your build and store page. Typically 1-3 days. They check for malware, broken builds, and policy compliance. **8. Release.** Once approved, you choose your release date. You can do a soft launch (visible but not featured) or a full launch. ## Requirements * **Steamworks account**: Free to create * **\$100 Steam Direct fee**: One-time per game, not per update * **Valid business/payment info**: For payouts * **Build that runs**: Test on a clean machine before submitting ## Revenue Share Steam takes 30% of sales. You keep 70%. This is standard for the platform. ## Tips **Test your exported build on a different computer.** Not your dev machine. Catches missing DLLs, wrong paths, and other export issues. **Use the same bundle identifier** across Mac and Windows if you're releasing on both. Important for cloud save continuity. **Start with itch.io** if you want a quicker path to release. No approval process, no fee. Use that to validate, then add Steam later. ## Related Full step-by-step guide Export for PC first Detailed walkthrough with screenshots # Product Source & Platform Status Source: https://docs.summerengine.com/knowledge-base/source-status The canonical status for Summer Engine source access and live, scaffolded, or planned Summercraft platform capabilities. Summer's AI-agent layer is MIT open source. The Summer Engine desktop app is free to download and use, but its source code is not public right now. This page is also the single canonical status source for Summercraft capabilities: reference pages describe contracts, while this page says whether the supporting production path is live. ## What is open today? The public repo is the agent layer: * CLI * MCP server * Agent skills * Hooks * Plugin manifests Repo: [github.com/SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent) ## What is free? The Summer Engine desktop app is free to download and use. Local MCP workflows are free too, including workflows where you bring your existing Claude Code, Cursor, Codex, Gemini, Devin Desktop, or other agent subscription. ## What is paid? Live hosted Summer services are paid because they run cloud infrastructure and model calls: * Hosted Summer AI * Asset generation * Cloud storage * Orchestration Managed multiplayer is planned as a paid hosted service; it is not production-live today. ## Platform capability status | Capability | Status | What that means today | | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | Create Summer game records | **Live** | Authenticated creators can create a game record through the Summercraft API. | | Upload and verify a game-only `.pck` | **Live** | Direct-to-storage upload, server-side SHA-256 verification, and immutable release records are deployed. | | Browser submission and static scanner | **Live** | The signed-in submit page accepts a `.pck` plus `manifest.json` and runs pattern-based static analysis before creating a review submission. | | Manual review queue | **Live** | A submission can enter human review; there is no automatic approval. | | Authenticated release download | **Live** | Owners and admins can retrieve pending releases; published catalog releases follow the documented access rules. | | Summer SDK gameplay and subsystem interfaces | **Scaffold** | The GDScript contract and examples exist, but documented interfaces do not prove the hosted runtime path is deployed. | | `SummerMultiplayerPeer` transport | **Scaffold** | The compatibility contract is published and implementation is in progress. | | Browser or desktop-shell play for uploaded games | **Planned** | A `published` catalog status does not make an uploaded game playable. | | Hosted dedicated game servers | **Planned** | Creators must not promise managed hosting to players. | | Automatic matchmaking and relay | **Planned** | No production matchmaking or relay service is available for uploaded Summer games. | | Automated production runtime sandbox | **Planned** | Submission review is manual; the production sandbox path is still being built. | | Production gameplay runtime | **Planned** | Uploaded and approved packs do not execute in a Summercraft gameplay runtime today. | | Hosted persistence and economy | **Scaffold** | `Summer.data` and `Summer.economy` are contract surfaces; no hosted backend durably stores player data or runs the economy rail today. | Status words are deliberate: * **Live** means the production path is deployed and documented. * **Scaffold** means a contract, adapter, or tested local surface exists without a complete production path. * **Planned** means creators and agents must not promise the capability. See [Summer SDK](/api-reference/summer-sdk) for contracts and [Submit Your Summer Game for Review](/api-reference/summer-sdk/submission-guide) for the currently deployed submission flow. ## Is the engine app open source? No. The desktop app is free proprietary software right now. If Summer publishes engine source later under a no-competing-engine license, the honest term would be source-available, not open source. For the public canonical page, see [summerengine.com/source-status](https://www.summerengine.com/source-status). # How do specialist agents work? Source: https://docs.summerengine.com/knowledge-base/specialist-agents Summer keeps a fixed team of expert agents. The main agent picks them for you, and they run inside your chat. ## What Are Specialist Agents? Specialist agents are expert AI assistants the main agent hands work to. Each one is shaped for a kind of work rather than a subject area, keeps its own focused context, and reports back with a summary. ## The Team The lineup is fixed. You do not configure it, and you cannot ask for a specialist by name. * **Researcher**: read-only investigation of your project. Answers "where is X wired" or "does Y exist" with file and node anchors * **General worker**: multi-step tasks that need file reads and writes, like scaffolding scripts or research-then-apply edits * **Builder**: scenes and gameplay end to end. Scripts, scene files, main scene, input actions, project settings, and a compile check * **Asset maker**: images, 3D models, audio, rigged characters, and animations. One variant returns assets for review; another also imports and places them in your scene * **Verifier**: traces the real scene, scripts, and editor state to confirm a feature works, and says plainly when it does not * **Advisor**: the second opinion the main agent turns to when it is stuck There is no 3D specialist and no audio specialist. Ask for realistic forest lighting or a horror sound mix and the main agent takes it on, delegating to the team above as it sees fit. ## How the Workflow Works 1. You describe what you want in your normal chat 2. The main agent decides whether the work needs a specialist, and which one 3. The specialist runs and you watch it live in your chat as its own clean thread 4. It folds a short summary back into the main chat when it finishes Specialists are not separate conversation threads you switch into, and they do not persist between chats. They run inside the same conversation as tools the main agent calls, which is why you never have to manage them or come back to them later. ## Parallel Execution Because each specialist keeps its own focused context, several can run at the same time. One can build your player controller while another generates enemy art and a third researches how your save system works, without blocking each other or cluttering your main chat. ## Related What Summer Engine can do in your project How specialist agents are orchestrated # What makes Summer Engine different from using ChatGPT? Source: https://docs.summerengine.com/knowledge-base/summer-vs-chatgpt Unified experience, accountable operations, a team of specialist agents, and project intelligence. AI directly modifies your game. ## The Core Difference: AI That Modifies Your Game With ChatGPT, Claude Code, Cursor, Codex, or similar, you get text responses. You copy code, paste it into your project, fix paths and imports, and hope it works. With Summer Engine, you describe what you want and Summer Engine implements it directly in your project. No copy-paste. No context switching. The AI understands your codebase and applies changes through engine APIs. ## Unified Experience **No tool switching.** You're not juggling ChatGPT, Claude Code, Cursor, Codex, or similar + VS Code, and a game engine. Summer Engine is one environment. The chat is next to your project. You ask; Summer Engine modifies. You see changes immediately. **Project context.** Summer Engine indexes your project: scripts, scenes, assets, relationships. When you ask "add a health bar to my player," it knows which player. Those tools don't have access to your project. They guess. Summer Engine looks. ## Safe Operations **Engine APIs where they matter.** Scene work goes through specific operations: add node, set property, connect signal, import asset. Each one names an exact target and returns a receipt, so a change either lands or tells you why it did not. Summer also does ordinary file work. It writes and edits files, deletes, moves and renames them, and can run shell commands, with anything risky gated behind the permission mode you pick. The point is not that Summer refuses to touch your files. It is that every touch is explicit and accounted for. **Undo where undo applies.** Scene operations integrate with the editor's undo history, so Ctrl+Z reverts them. File writes are not editor undo steps: they are applied atomically and return exact receipts, and stale overwrites are refused. For file changes, use the Changes panel and your version control rather than Ctrl+Z. ## Specialist Agents **A team, not one model.** Summer keeps a fixed team of specialists — a researcher, a general worker, a builder, an asset maker, a verifier, and an advisor — and the main agent hands work to them as it goes. They run in parallel, each with its own focused context, and report back. See [How specialist agents work](/knowledge-base/specialist-agents). ## Project Intelligence **RAG over your codebase.** Summer Engine uses retrieval-augmented generation. It searches your project for relevant context before answering. "How does my player handle input?" Summer Engine finds the script, reads it, and gives accurate advice. ChatGPT, Cursor, and similar have no access to your files. ## Summary | | ChatGPT, Cursor, etc. | Summer Engine | | --------------------- | --------------------- | --------------------------------------- | | Modifies your project | No: you copy-paste | Yes: directly | | Knows your codebase | No | Yes: indexed | | Undo support | No | Yes: Ctrl+Z for scene changes | | Specialist agents | No | Yes: a team the main agent delegates to | | Context switching | High | None | ## Related What Summer Engine can do in your project # How does Summer compare to other AI game tools? Source: https://docs.summerengine.com/knowledge-base/summer-vs-other-tools Summer is a full game engine, not an AI addon. Deeper integration, better context, safer operations. **Summer is unique because it's a full game engine**, not just an AI addon. This means: * Deeper integration with the development workflow * Better understanding of project context * More reliable and safe AI operations * Full compatibility with existing ecosystem # How do I get support? Source: https://docs.summerengine.com/knowledge-base/support Founders respond personally. Email, Discord, and more. ## Founders Respond Personally We're a small team. Email [founders@summerengine.com](mailto:founders@summerengine.com) for any questions, bugs, or feature requests. We respond personally to every inquiry, typically within 24 hours. No ticket queues, no bots. ## Where to Get Help **Email.** [founders@summerengine.com](mailto:founders@summerengine.com). Best for detailed technical questions, bug reports, or anything that benefits from a written thread. **Discord.** [discord.gg/yUpgtxnZky](https://discord.gg/yUpgtxnZky). Active community of Summer Engine users. Good for quick questions, sharing work, and getting feedback. The founders are in there too. **Documentation.** You're reading it. The Knowledge Base, quickstarts, and guides cover most common questions. AI agents can also use our docs. Mintlify auto-generates llms.txt for discoverability. ## What to Include When Reaching Out **For bugs:** What you were doing, what you expected, what happened. Screenshots or error messages help. Your OS and Summer Engine version. **For feature requests:** Describe the use case. What are you trying to do? Why would this help? **For general questions:** Just ask. We're happy to help. ## Response Times We aim to respond to email within 24 hours on business days. Discord is often faster. Someone from the community or the team may answer within minutes. # How does Unity or Unreal migration work? Source: https://docs.summerengine.com/knowledge-base/unity-unreal-migration Use AI to research your project, create a plan, then rebuild in Summer Engine. Fresh projects: easy. Large projects: more planning. ## You Rebuild, Not Import Summer Engine uses different project formats than Unity or Unreal. There is no direct import path. Instead, you use Summer Engine's AI to research your existing project, create a migration plan, and rebuild system by system. The AI can read your Unity C# scripts, Unreal Blueprints, level structure, and asset references to guide the rebuild. ## The Workflow **Step 1: Research.** In Summer Engine's chat, ask the AI to use shell and tools to research your project. For example: "Use shell and tools to research my Unity project at \[path]. Analyze the structure, scenes, and scripts. Create a migration plan." **Step 2: Plan.** The AI creates a step-by-step plan: which systems to rebuild first, what order makes sense, what assets you can reuse vs. regenerate. **Step 3: Rebuild.** Describe each system: "Create a 3D character controller like my Unity Rigidbody setup." "Build a level with a ground plane, obstacles, and spawn points." Summer Engine implements it. You already have assets. Import them or use AI generation for placeholders. ## Project Size Matters | Project Size | Difficulty | Approach | | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Fresh / small** | Easy | Often one-shot. Describe the game, AI rebuilds it. | | **Medium** | Moderate | Break into systems. Migrate scene by scene or level by level. | | **Large** | Planning required | AI researches first, creates detailed plan. You have assets. Focus on structure and logic. May need phased migration over weeks. | For a relatively fresh Unity or Unreal project (a few scenes, straightforward systems), migration can often be done in one pass. For a huge project with years of work, the AI creates a phased plan. You migrate in chunks, validating each phase before moving on. ## What the AI Can Read The AI can analyze your existing codebase: C# scripts, Blueprint structure, scene/level files, asset references. It uses this to understand your architecture and suggest the right rebuild order. It does not convert files automatically. You're rebuilding in Summer Engine's format with AI assistance. ## Shell and Tools Summer Engine's AI can run shell commands (with your approval) to scan directories, read files, and gather context. This is how it researches your Unity or Unreal project. You stay in control. Nothing executes without your approval. ## Related Migrate from Unity Migrate from Unreal # Can I use Summer Engine for web games? Source: https://docs.summerengine.com/knowledge-base/web-games Yes. Export to HTML5/WebAssembly. Deploy to itch.io, your website, or any static host. ## Yes: Web Export Is Fully Supported Summer Engine excels at web game development. You build your game with AI assistance, then export to HTML5/WebAssembly. The result runs in any modern browser. No separate web framework needed. Deploy to itch.io, your website, Netlify, GitHub Pages, or any static host. ## The Workflow **1. Build your game.** Create your game in Summer Engine. Describe what you want; Summer Engine implements it. Add touch controls, responsive UI, and web-specific features by asking: "Add touch controls for mobile browsers." "Implement responsive UI scaling for different screen sizes." **2. Configure for web export.** When ready to export, ask Summer Engine: "Configure my project for HTML5 export." "Set up the export template with proper threading settings." "Optimize asset loading for web browsers." "Add a loading screen with progress indication." **3. Export.** Project → Export → Add → Web. Configure if needed, then Export. You get HTML, JavaScript, and WebAssembly files. **4. Deploy.** Upload to any static host. itch.io, Netlify, GitHub Pages, AWS S3, your own server. No special server required. Static files are enough. Players load your game in their browser. ## Web-Specific Considerations **Browser compatibility.** Summer Engine can help with WebGL shaders, fallbacks for older browsers, and cross-browser testing. "Check this WebGL shader for compatibility with older browsers." "Add fallbacks for browsers that don't support WebAssembly." **Performance.** Web games need careful asset optimization. "Optimize texture sizes for faster web loading." "Implement asset streaming for large games." "Add compression to reduce download sizes." **Touch and mobile web.** "Add touch controls." "Implement responsive UI for phones and tablets." "Handle orientation changes gracefully." ## Where to Publish **itch.io.** Popular for indie web games. Upload your build, set a URL, players play in browser. No approval process. **Your website.** Host the files yourself. Full control. You handle distribution and payments if you monetize. **Newgrounds, Kongregate, etc.** Many portals accept HTML5 games. Same export; different upload process. ## Related Make a web game with AI Browser compatibility, performance, deployment # What is Summer Engine? Source: https://docs.summerengine.com/knowledge-base/what-is-summer Summer Engine is the AI game engine where you build a Summer game in GDScript with AI that understands your whole project. ## What is Summer Engine? Summer Engine is **the AI game engine**. It's not just a game engine with a plugin bolted on. It's a professional engine built from the ground up for AI, where the AI understands your entire project and can modify scenes, code, and assets through natural language commands. You make a **Summer game** in **GDScript**. When you need multiplayer, player identity, persistence, economy, or submission surfaces, you integrate the **Summer SDK**. Summer is the product creators install and use; upstream lineage belongs in the [compatibility reference](/reference/compatibility), not in the product name. **Think of it as Cursor for game development.** Instead of juggling ChatGPT, VS Code, and another engine, you work in one unified environment. You describe what you want; Summer Engine writes the code, creates assets, and modifies your game directly. ## How Summer Engine Differs from Other Approaches **Unified experience.** No switching between tools. The AI understands your project context because it indexes your codebase, scenes, and assets. When you ask "add a health bar to my player," it knows which player script and scene to modify. **Safe operations.** AI changes go through engine APIs with full undo support. Nothing breaks unexpectedly. Every change can be reverted with Ctrl+Z. **Project intelligence.** Summer Engine automatically indexes your project when you open it: scripts, scenes, assets, and their relationships. The AI uses this to give context-aware help, not generic advice. **Specialist agents.** For complex tasks (3D modeling, audio design, physics), Summer Engine can bring in domain experts that run in parallel and stay focused on their area. ## Who Is Summer Engine For? Summer Engine is for everyone who wants to make games. Beginners can build complete games by describing them in plain English. Professionals get a production-ready tool that accelerates workflow. We shipped a commercial Steam game in 2.5 months using Summer Engine. You get full access to the underlying engine and complete control over your architecture. ## Related Build a game with just AI, no coding Learn how to use Summer Engine's AI # Every Supported Agent Source: https://docs.summerengine.com/mcp/agents The full list of AI coding agents and IDEs summer setup can configure for Summer Engine, with the exact MCP config file, file shape, and skills folder each one uses. One command configures any of these agents: ```bash theme={null} npx -y summer-engine@latest setup --yes ``` It writes the MCP server entry into the agent's own config file, installs the Summer skill library where that agent reads skills, and runs `summer doctor`. Every path below is what the command writes; paste the snippet yourself if you prefer to edit files by hand. Paths were checked against each product's official documentation on 2026-09-11. Where a vendor's docs are ambiguous, the section says so. **31 active agents.** Agents marked legacy still work but warn on use. Add `--scope project` to write the project-level file instead of the user-level one where the agent has one. Add `--print` to see the snippet without writing anything, `--dry-run` to see the plan. `--channel next` points the entry at a pre-release build. **One skills folder for most agents.** Codex, Cursor, Zed, OpenCode, Copilot in VS Code, Devin Desktop, Amp, Crush, Warp, Kimi Code, Factory Droid, Rovo Dev and Grok Build all read the agentskills.io folder `~/.agents/skills` (and `.agents/skills` inside a project). Setting up any one of them installs the skills for all of them. See [Skills](/mcp/skills). ## Claude Code Full guide: [Claude Code](/mcp/claude-code). The essentials: ```bash theme={null} npx -y summer-engine@latest setup claude-code --yes ``` Id: `claude-code`. Also accepted: `claude`. | | | | -------------------- | ------------------------------------------------------- | | MCP config (user) | `~/.claude.json` · Windows `%USERPROFILE%\.claude.json` | | MCP config (project) | `.mcp.json` | | Skills (user) | `~/.claude/skills` | | Skills (project) | `.claude/skills` | | After setup | Restart Claude Code or run /mcp in a new session. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.claude.json theme={null} { "mcpServers": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Claude Desktop ```bash theme={null} npx -y summer-engine@latest setup claude-desktop --yes ``` Id: `claude-desktop`. Also accepted: `claude-app`, `claudedesktop`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/Library/Application Support/Claude/claude_desktop_config.json` · Linux `~/.config/Claude/claude_desktop_config.json` · Windows `%APPDATA%\Claude\claude_desktop_config.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills | none. Claude Desktop has no skills folder. The MCP server ships summer\_get\_agent\_playbook, so the model can pull Summer guidance in-chat. | | After setup | Quit and reopen Claude Desktop; the summer-engine tools appear under the tools menu in a new chat. | What `summer setup` writes (paste this if you configure by hand): ```json ~/Library/Application Support/Claude/claude_desktop_config.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Codex Full guide: [Codex](/mcp/codex). The essentials: ```bash theme={null} npx -y summer-engine@latest setup codex --yes ``` Id: `codex`. Also accepted: `codex-cli`, `openai-codex`. | | | | -------------------- | ------------------------------------------------------------------- | | MCP config (user) | `~/.codex/config.toml` · Windows `%USERPROFILE%\.codex\config.toml` | | MCP config (project) | `.codex/config.toml` | | Note | Codex only loads project .codex/config.toml from trusted projects. | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Codex or run /mcp in a new session. | What `summer setup` writes (paste this if you configure by hand): ```toml ~/.codex/config.toml theme={null} [mcp_servers.summer-engine] command = "npx" args = ["-y", "summer-engine@latest", "mcp"] ``` ## Cursor Full guide: [Cursor](/mcp/cursor). The essentials: ```bash theme={null} npx -y summer-engine@latest setup cursor --yes ``` Id: `cursor`. | | | | -------------------- | ------------------------------------------------------------------- | | MCP config (user) | `~/.cursor/mcp.json` · Windows `%USERPROFILE%\.cursor\mcp.json` | | MCP config (project) | `.cursor/mcp.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Cursor and enable the summer-engine MCP server if prompted. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.cursor/mcp.json theme={null} { "mcpServers": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Devin Desktop (formerly Windsurf) Full guide: [Devin Desktop (formerly Windsurf)](/mcp/devin-desktop). The essentials: ```bash theme={null} npx -y summer-engine@latest setup windsurf --yes ``` Id: `windsurf`. Also accepted: `devin`, `devin-desktop`, `devindesktop`. | | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.codeium/windsurf/mcp_config.json` · Windows `%USERPROFILE%\.codeium\windsurf\mcp_config.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp\_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command. | Devin's docs say `mcp_config.json` configures the Cascade agent. For the Devin agent, add the same command in the app's MCP settings. What `summer setup` writes (paste this if you configure by hand): ```json ~/.codeium/windsurf/mcp_config.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Antigravity Full guide: [Antigravity](/mcp/antigravity). The essentials: ```bash theme={null} npx -y summer-engine@latest setup antigravity --yes ``` Id: `antigravity`. Also accepted: `agy`, `google-antigravity`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | MCP config (user) | `~/.gemini/config/mcp_config.json` · Windows `%USERPROFILE%\.gemini\config\mcp_config.json` | | MCP config (project) | `.agents/mcp_config.json` | | Skills (user) | `~/.gemini/config/skills` | | Skills (project) | `.agents/skills` | | After setup | In Antigravity open the agent panel's MCP servers view and refresh; summer-engine appears in the list (IDE and CLI share this file). | What `summer setup` writes (paste this if you configure by hand): ```json ~/.gemini/config/mcp_config.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Cline (VS Code) ```bash theme={null} npx -y summer-engine@latest setup cline --yes ``` Id: `cline`. Also accepted: `cline-vscode`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` · Linux `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` · Windows `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.cline/skills` | | Skills (project) | `.cline/skills` | | After setup | Restart VS Code so Cline reloads its MCP config. | What `summer setup` writes (paste this if you configure by hand): ```json ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Cline CLI ```bash theme={null} npx -y summer-engine@latest setup cline-cli --yes ``` Id: `cline-cli`. Also accepted: `clinecli`. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.cline/data/settings/cline_mcp_settings.json` · Windows `%USERPROFILE%\.cline\data\settings\cline_mcp_settings.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.cline/skills` | | Skills (project) | `.cline/skills` | | After setup | Restart the Cline CLI so it reloads its MCP settings. | Cline's own docs name two files for the CLI (`~/.cline/mcp.json` and `~/.cline/data/settings/cline_mcp_settings.json`). Summer writes the one from the CLI configuration page. What `summer setup` writes (paste this if you configure by hand): ```json ~/.cline/data/settings/cline_mcp_settings.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Kilo Code ```bash theme={null} npx -y summer-engine@latest setup kilo-code --yes ``` Id: `kilo-code`. Also accepted: `kilo`, `kilocode`. | | | | -------------------- | -------------------------------------------------------------------- | | MCP config (user) | `~/.config/kilo/kilo.json` · Windows `%APPDATA%\kilo\kilo.json` | | MCP config (project) | `kilo.json` | | Skills (user) | `~/.kilo/skills` | | Skills (project) | `.kilo/skills` | | After setup | Restart Kilo (CLI or the VS Code extension) so it reloads kilo.json. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/kilo/kilo.json theme={null} { "mcp": { "summer-engine": { "type": "local", "command": [ "npx", "-y", "summer-engine@latest", "mcp" ], "enabled": true } } } ``` ## GitHub Copilot CLI Full guide: [GitHub Copilot CLI](/mcp/github-copilot). The essentials: ```bash theme={null} npx -y summer-engine@latest setup github-copilot --yes ``` Id: `github-copilot`. Also accepted: `copilot`, `copilot-cli`, `github-copilot-cli`. | | | | -------------------- | --------------------------------------------------------------------------------- | | MCP config (user) | `~/.copilot/mcp-config.json` · Windows `%USERPROFILE%\.copilot\mcp-config.json` | | MCP config (project) | `.mcp.json` | | Skills (user) | `~/.copilot/skills` | | Skills (project) | `.github/skills` | | After setup | Restart Copilot CLI, or run /mcp reload and /skills reload in the active session. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.copilot/mcp-config.json theme={null} { "mcpServers": { "summer-engine": { "type": "local", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ], "tools": [ "*" ] } } } ``` ## GitHub Copilot in VS Code Full guide: [GitHub Copilot in VS Code](/mcp/vscode). The essentials: ```bash theme={null} npx -y summer-engine@latest setup vscode-copilot --yes ``` Id: `vscode-copilot`. Also accepted: `vscode`, `vs-code`, `vs-code-copilot`, `github-copilot-vscode`. | | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/Library/Application Support/Code/User/mcp.json` · Linux `~/.config/Code/User/mcp.json` · Windows `%APPDATA%\Code\User\mcp.json` | | MCP config (project) | `.vscode/mcp.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode. | What `summer setup` writes (paste this if you configure by hand): ```json ~/Library/Application Support/Code/User/mcp.json theme={null} { "servers": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## GitHub Copilot in Visual Studio ```bash theme={null} npx -y summer-engine@latest setup visual-studio --yes ``` Id: `visual-studio`. Also accepted: `vs`, `vs2026`, `visual-studio-2026`, `visualstudio`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.mcp.json` · Windows `%USERPROFILE%\.mcp.json` | | MCP config (project) | `.mcp.json` | | Skills | none. Visual Studio's Copilot has no skills folder yet; the MCP server ships summer\_get\_agent\_playbook for in-chat guidance. | | After setup | Restart Visual Studio, open Copilot Chat in Agent mode, and enable summer-engine in the tools picker. | Visual Studio also reads `.vs/mcp.json`, `.vscode/mcp.json` and `.cursor/mcp.json` in the solution folder. What `summer setup` writes (paste this if you configure by hand): ```json ~/.mcp.json theme={null} { "servers": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## GitHub Copilot in JetBrains IDEs ```bash theme={null} npx -y summer-engine@latest setup copilot-jetbrains --yes ``` Id: `copilot-jetbrains`. Also accepted: `jetbrains-copilot`, `intellij-copilot`, `copilot-intellij`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | MCP config (user) | `~/.config/github-copilot/intellij/mcp.json` · Windows `%APPDATA%\github-copilot\intellij\mcp.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills | none. Copilot in JetBrains documents no skills folder; the MCP server ships summer\_get\_agent\_playbook for in-chat guidance. | | After setup | Restart the JetBrains IDE and open Copilot Chat in Agent mode; summer-engine shows in the tools list. | The user config path comes from Microsoft's Copilot for JetBrains feedback repository, not from docs.github.com, which only says the file opens from Settings. What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/github-copilot/intellij/mcp.json theme={null} { "servers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## OpenCode Full guide: [OpenCode](/mcp/opencode). The essentials: ```bash theme={null} npx -y summer-engine@latest setup opencode --yes ``` Id: `opencode`. Also accepted: `open-code`. | | | | -------------------- | ------------------------------------------------------------------------------- | | MCP config (user) | `~/.config/opencode/opencode.json` · Windows `%APPDATA%\opencode\opencode.json` | | MCP config (project) | `opencode.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart OpenCode so it reloads opencode.json. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/opencode/opencode.json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "summer-engine": { "type": "local", "command": [ "npx", "-y", "summer-engine@latest", "mcp" ], "enabled": true } } } ``` ## Zed Full guide: [Zed](/mcp/zed). The essentials: ```bash theme={null} npx -y summer-engine@latest setup zed --yes ``` Id: `zed`. Also accepted: `zed-editor`. | | | | -------------------- | ----------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.config/zed/settings.json` · Windows `%APPDATA%\zed\settings.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Zed reloads settings.json live; open the Agent panel and check summer-engine under MCP servers. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/zed/settings.json theme={null} { "context_servers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ], "env": {} } } } ``` ## Kiro ```bash theme={null} npx -y summer-engine@latest setup kiro --yes ``` Id: `kiro`. Also accepted: `kiro-ide`, `aws-kiro`. | | | | -------------------- | ------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.kiro/settings/mcp.json` · Windows `%USERPROFILE%\.kiro\settings\mcp.json` | | MCP config (project) | `.kiro/settings/mcp.json` | | Skills (user) | `~/.kiro/skills` | | Skills (project) | `.kiro/skills` | | After setup | Kiro reloads MCP config on save; open the MCP Servers view to confirm summer-engine is connected. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.kiro/settings/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Goose Full guide: [Goose](/mcp/local-models). The essentials: ```bash theme={null} npx -y summer-engine@latest setup goose --yes ``` Id: `goose`. Also accepted: `block-goose`, `codename-goose`. | | | | -------------------- | ---------------------------------------------------------------------------------- | | MCP config (user) | `~/.config/goose/config.yaml` · Windows `%APPDATA%\Block\goose\config\config.yaml` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.config/agents/skills` | | Skills (project) | `.agents/skills` | | After setup | Restart Goose (CLI or Desktop); summer-engine is listed under Extensions. | What `summer setup` writes (paste this if you configure by hand): ```yaml ~/.config/goose/config.yaml theme={null} extensions: summer-engine: type: stdio name: summer-engine description: "Summer Engine: scenes, scripts, play mode and diagnostics over MCP" cmd: npx args: - -y - summer-engine@latest - mcp enabled: true timeout: 300 env_keys: [] envs: {} ``` ## Hermes Agent ```bash theme={null} npx -y summer-engine@latest setup hermes --yes ``` Id: `hermes`. Also accepted: `hermes-agent`, `nous-hermes`. | | | | -------------------- | --------------------------------------------------------------------- | | MCP config (user) | `~/.hermes/config.yaml` · Windows `%USERPROFILE%\.hermes\config.yaml` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.hermes/skills` | | Skills (project) | `.agents/skills` | | After setup | Run /reload-mcp in Hermes Agent (or restart it). | What `summer setup` writes (paste this if you configure by hand): ```yaml ~/.hermes/config.yaml theme={null} mcp_servers: summer-engine: command: npx args: - -y - summer-engine@latest - mcp ``` ## Trae ```bash theme={null} npx -y summer-engine@latest setup trae --yes ``` Id: `trae`. Also accepted: `trae-ide`, `bytedance-trae`. | | | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | MCP config (user) | none: Trae manages user-level MCP servers in its UI; writing the project file .trae/mcp.json instead. | | MCP config (project) | `.trae/mcp.json` | | Skills | none. Trae documents no skills folder; the MCP server ships summer\_get\_agent\_playbook for in-chat guidance. | | After setup | Restart Trae and open the MCP settings; summer-engine should show as connected. | Trae keeps user-level MCP servers in its UI, so Summer only writes the project file. What `summer setup` writes (paste this if you configure by hand): ```json .trae/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Qwen Code ```bash theme={null} npx -y summer-engine@latest setup qwen-code --yes ``` Id: `qwen-code`. Also accepted: `qwen`, `qwencode`. | | | | -------------------- | --------------------------------------------------------------------- | | MCP config (user) | `~/.qwen/settings.json` · Windows `%USERPROFILE%\.qwen\settings.json` | | MCP config (project) | `.qwen/settings.json` | | Skills (user) | `~/.qwen/skills` | | Skills (project) | `.qwen/skills` | | After setup | Restart Qwen Code or run /mcp in a new session. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.qwen/settings.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Kimi Code CLI ```bash theme={null} npx -y summer-engine@latest setup kimi-code --yes ``` Id: `kimi-code`. Also accepted: `kimi`, `kimi-cli`, `kimicode`. | | | | -------------------- | --------------------------------------------------------------------- | | MCP config (user) | `~/.kimi-code/mcp.json` · Windows `%USERPROFILE%\.kimi-code\mcp.json` | | MCP config (project) | `.kimi-code/mcp.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Kimi Code CLI so it reconnects its MCP servers. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.kimi-code/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Crush ```bash theme={null} npx -y summer-engine@latest setup crush --yes ``` Id: `crush`. Also accepted: `charm-crush`. | | | | -------------------- | ------------------------------------------------------------------------- | | MCP config (user) | `~/.config/crush/crushrc` · Windows `%USERPROFILE%\.config\crush\crushrc` | | MCP config (project) | `.crushrc` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Crush so it reloads crushrc. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/crush/crushrc theme={null} { "mcp": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Amp ```bash theme={null} npx -y summer-engine@latest setup amp --yes ``` Id: `amp`. Also accepted: `sourcegraph-amp`, `ampcode`. | | | | -------------------- | --------------------------------------------------------------------- | | MCP config (user) | `~/.config/amp/settings.json` · Windows `%APPDATA%\amp\settings.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Amp so it reloads settings.json. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.config/amp/settings.json theme={null} { "amp.mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Factory Droid ```bash theme={null} npx -y summer-engine@latest setup factory --yes ``` Id: `factory`. Also accepted: `droid`, `factory-droid`. | | | | -------------------- | ----------------------------------------------------------------- | | MCP config (user) | `~/.factory/mcp.json` · Windows `%USERPROFILE%\.factory\mcp.json` | | MCP config (project) | `.factory/mcp.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart droid or run /mcp in the active session. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.factory/mcp.json theme={null} { "mcpServers": { "summer-engine": { "type": "stdio", "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Junie ```bash theme={null} npx -y summer-engine@latest setup junie --yes ``` Id: `junie`. Also accepted: `jetbrains-junie`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.junie/mcp/mcp.json` · Windows `%USERPROFILE%\.junie\mcp\mcp.json` | | MCP config (project) | `.junie/mcp/mcp.json` | | Skills | none. Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer\_get\_agent\_playbook for in-chat guidance. | | After setup | Restart the JetBrains IDE so Junie reloads its MCP config. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.junie/mcp/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Warp ```bash theme={null} npx -y summer-engine@latest setup warp --yes ``` Id: `warp`. Also accepted: `warp-terminal`. | | | | -------------------- | ------------------------------------------------------------------------------- | | MCP config (user) | `~/.warp/.mcp.json` · Windows `%USERPROFILE%\.warp\.mcp.json` | | MCP config (project) | `.warp/.mcp.json` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Warp detects the file and spawns the server; check Settings > AI > MCP servers. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.warp/.mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Rovo Dev CLI ```bash theme={null} npx -y summer-engine@latest setup rovo-dev --yes ``` Id: `rovo-dev`. Also accepted: `rovodev`, `rovo`, `atlassian-rovo-dev`. | | | | -------------------- | --------------------------------------------------------------------- | | MCP config (user) | `~/.rovodev/mcp.json` · Windows `%USERPROFILE%\.rovodev\mcp.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Rovo Dev CLI so it reconnects its MCP servers. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.rovodev/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ], "transport": "stdio" } } } ``` ## Qoder CLI ```bash theme={null} npx -y summer-engine@latest setup qoder --yes ``` Id: `qoder`. Also accepted: `qoder-cli`. | | | | -------------------- | ------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.qoder/settings.json` · Windows `%USERPROFILE%\.qoder\settings.json` | | MCP config (project) | `.mcp.json` | | Skills (user) | `~/.qoder/skills` | | Skills (project) | `.qoder/skills` | | After setup | Restart Qoder CLI so it reloads its MCP settings (the Qoder IDE manages servers in its UI). | What `summer setup` writes (paste this if you configure by hand): ```json ~/.qoder/settings.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Grok Build ```bash theme={null} npx -y summer-engine@latest setup grok-build --yes ``` Id: `grok-build`. Also accepted: `grok`, `xai-grok`. | | | | -------------------- | ----------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.grok/config.toml` · Windows `%USERPROFILE%\.grok\config.toml` | | MCP config (project) | `.grok/config.toml` | | Skills (user) | `~/.agents/skills` — the shared agentskills.io folder | | Skills (project) | `.agents/skills` | | After setup | Restart Grok Build so it reloads config.toml (it also reads `~/.claude.json` and `.cursor/mcp.json`). | Grok Build also reads `~/.claude.json`, `.cursor/mcp.json` and `.mcp.json`, so a Claude Code or Cursor setup already covers it. What `summer setup` writes (paste this if you configure by hand): ```toml ~/.grok/config.toml theme={null} [mcp_servers.summer-engine] command = "npx" args = ["-y", "summer-engine@latest", "mcp"] ``` ## Mistral Vibe ```bash theme={null} npx -y summer-engine@latest setup mistral-vibe --yes ``` Id: `mistral-vibe`. Also accepted: `vibe`, `mistral`. | | | | -------------------- | ----------------------------------------------------------------- | | MCP config (user) | `~/.vibe/config.toml` · Windows `%USERPROFILE%\.vibe\config.toml` | | MCP config (project) | `.vibe/config.toml` | | Skills (user) | `~/.vibe/skills` | | Skills (project) | `.agents/skills` | | After setup | Restart Vibe so it reloads config.toml. | What `summer setup` writes (paste this if you configure by hand): ```toml ~/.vibe/config.toml theme={null} [[mcp_servers]] name = "summer-engine" transport = "stdio" command = "npx" args = ["-y", "summer-engine@latest", "mcp"] ``` ## LM Studio Full guide: [LM Studio](/mcp/local-models). The essentials: ```bash theme={null} npx -y summer-engine@latest setup lm-studio --yes ``` Id: `lm-studio`. Also accepted: `lmstudio`, `lm_studio`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | MCP config (user) | `~/.lmstudio/mcp.json` · Windows `%USERPROFILE%\.lmstudio\mcp.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills | none. LM Studio has no rules or skills folder. The MCP server ships summer\_get\_agent\_playbook, so the model can pull Summer guidance in-chat. | | After setup | Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher. | What `summer setup` writes (paste this if you configure by hand): ```json ~/.lmstudio/mcp.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Legacy agents These still configure and still warn: the product was retired or shut down. ## Gemini CLI **Legacy.** Gemini CLI was retired for individual accounts on 2026-06-18 and replaced by Antigravity. Use `summer setup antigravity` unless you are on a Workspace/enterprise Gemini CLI. Full guide: [Gemini CLI](/mcp/gemini). The essentials: ```bash theme={null} npx -y summer-engine@latest setup gemini --yes ``` Id: `gemini`. Also accepted: `gemini-cli`. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/.gemini/extensions/summer-engine/gemini-extension.json` · Windows `%USERPROFILE%\.gemini\extensions\summer-engine\gemini-extension.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/.gemini/extensions/summer-engine/skills` | | Skills (project) | user folder only | | After setup | Run `summer skills install --all --agent gemini` if skills were not installed, then restart Gemini CLI (or `gemini extensions enable summer-engine` if it is disabled). | What `summer setup` writes (paste this if you configure by hand): ```json ~/.gemini/extensions/summer-engine/gemini-extension.json theme={null} { "name": "summer-engine", "version": "3.1.0", "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.", "contextFileName": "GEMINI.md", "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } }, "settings": [ { "name": "enable_pre_commit_doctor", "description": "Block git commits when summer doctor needs attention (off by default)", "envVar": "SUMMER_PRE_COMMIT_DOCTOR", "sensitive": false } ] } ``` ## Roo Code **Legacy.** Roo Code shut down on 2026-05-15. The extension may still run, but it is no longer maintained; consider Cline or Kilo Code. ```bash theme={null} npx -y summer-engine@latest setup roo-code --yes ``` Id: `roo-code`. Also accepted: `roo`, `roocode`. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP config (user) | `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json` · Linux `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json` · Windows `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json` | | MCP config (project) | none; a `--scope project` request writes the user file with a warning | | Skills (user) | `~/Documents/Roo/Rules` | | Skills (project) | `.clinerules` | | After setup | Restart VS Code so Roo Code reloads its MCP config. | What `summer setup` writes (paste this if you configure by hand): ```json ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": [ "-y", "summer-engine@latest", "mcp" ] } } } ``` ## Not supported on purpose Checked on 2026-09-11 and left out: * **OpenHands CLI**: its `[mcp] stdio_servers` inline-table array has an upstream write bug; add the server through its own `openhands` config commands. * **Xcode's agent folders**: Apple documents the `ClaudeAgentConfig/` folder but not the file names inside it. * **Pi**: no MCP by design. **Aider, ChatGPT desktop, Replit, Perplexity**: no user-editable stdio MCP config. * **JetBrains AI Assistant, Android Studio, Qoder IDE, Trae user-level**: MCP servers are managed in the UI only. Paste the `mcpServers` snippet from the closest section above into the UI form. * **Continue.dev** (shut down) and **Void** (archived). If your agent reads any of the files above under a different name, run `summer setup --print` and paste the output. *** 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. # Build Games in Antigravity with Summer Engine MCP Source: https://docs.summerengine.com/mcp/antigravity Connect Summer Engine's MCP server to Antigravity and build games with Google's AI-powered IDE driving your engine. ## Summer Engine in Antigravity Antigravity is Google's AI-powered IDE that supports MCP (Model Context Protocol). With Summer Engine's integration, Antigravity's AI can control your game engine: add nodes to scenes, set properties, import assets, run the game, and debug, all from within your coding workflow. This guide covers the configuration. Setup takes about a minute. ## Prerequisites * **Antigravity**: Google's AI-powered IDE or the `agy` CLI * **Node.js**: For running the MCP server (Node 18+) * **Summer Engine**: Installed and running with your project open ## Configuration ### Option 1: One-command setup (recommended) ```bash theme={null} npx -y summer-engine@latest setup antigravity --yes ``` This writes the `summer-engine` server into `~/.gemini/config/mcp_config.json`, the file the Antigravity IDE, the Antigravity CLI (`agy`) and Antigravity 2.0 share, installs the skill library to `~/.gemini/config/skills/`, and runs `summer doctor`. Add `--scope project` to write `.agents/mcp_config.json` and `.agents/skills/` in the project instead. Coming from Gemini CLI? Gemini CLI was retired for individual accounts on 2026-06-18 and Antigravity replaced it. The Summer Gemini extension still works for Workspace and enterprise Gemini CLI users (`summer setup gemini`), but new setups should use Antigravity. ### Option 2: Manual configuration Antigravity uses the `mcpServers` shape. The files are: * **User-level:** `~/.gemini/config/mcp_config.json` * **Project-level:** `.agents/mcp_config.json` in the project root #### Step 1: Create or Edit the Config File Create the file if it doesn't exist. If it already has other MCP servers, add Summer Engine to the existing `mcpServers` object. #### Step 2: Add Summer Engine ```json New file (~/.gemini/config/mcp_config.json) theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": ["-y", "summer-engine@latest", "mcp"] } } } ``` ```json Adding to existing mcpServers theme={null} { "mcpServers": { "other-server": { ... }, "summer-engine": { "command": "npx", "args": ["-y", "summer-engine@latest", "mcp"] } } } ``` ### Step 3: Reload MCP servers In the agent panel open the MCP servers view and refresh, or restart Antigravity. The Summer Engine MCP server starts when Antigravity starts; it connects to the engine on the first tool call. ### Step 4: Verify Check Antigravity's MCP or AI settings to confirm "summer-engine" appears and its tools are listed. Then try a prompt: * "Use Summer Engine to add a MeshInstance3D with a BoxMesh to the scene" If the node appears in Summer Engine, the setup is working. ## Using Summer Engine with Antigravity Once configured, the AI can use Summer Engine's tools when you ask for game-related changes. Example prompts: * "Add a Camera3D and DirectionalLight3D to the scene root" * "Get the scene tree from Summer Engine" * "Import this model and add it to the World node: \[URL]" * "Run the game and capture a screenshot" * "Set the project's main scene to res\://main.tscn" **Engine must be running.** Antigravity's AI talks to Summer Engine over localhost. Open your project in the engine first, or run `npx summer-engine run` from the project directory. ## Troubleshooting ### "Summer Engine is not running" Start Summer Engine and open your project. The MCP server connects to the engine's local API on port 6550. The engine writes a token to `~/.summer/api-token` when it starts. ### MCP server not appearing * **Config path:** Verify `~/.gemini/config/mcp_config.json` (user) or `.agents/mcp_config.json` in the project root. `.vscode/mcp.json` from older guides is VS Code's file, not Antigravity's. * **JSON validity:** Ensure no trailing commas, proper quotes, and valid JSON structure * **Restart:** Fully quit and reopen Antigravity ### Tools return errors See the [Tools Reference](/mcp/tools-reference) for parameter formats. Common issues: wrong node path format (`./World/Player`), invalid property values (use engine string format like `"Vector3(0, 10, 0)"`), or the game running when scene edits are attempted (stop it first with `summer_stop`). ## Next Steps Every MCP tool with parameters and examples How an AI builds a full game using MCP Architecture, prerequisites, and other IDEs summer install, run, create, 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. # Building a Game with MCP Source: https://docs.summerengine.com/mcp/building-a-game Step-by-step guide for AI agents: how to build a complete game using Summer Engine's MCP tools. ## 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:** | Task | Skill | Install command | | -------------------------------------- | ------------------- | ---------------------------------------------------- | | FPS game, first-person movement | `fps-controller` | `npx summer-engine skills install fps-controller` | | Any GDScript, signals, exports | `gdscript-patterns` | `npx summer-engine skills install gdscript-patterns` | | Scene structure, sub-scenes, hierarchy | `scene-composition` | `npx summer-engine skills install scene-composition` | | 3D lighting, environment, shadows | `3d-lighting` | `npx summer-engine skills install 3d-lighting` | | Menus, HUD, health bars, UI | `ui-basics` | `npx summer-engine skills install ui-basics` | | All of the above | (all) | `npx summer-engine skills install --all` | **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-.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//SKILL.md` (with `--as-claude-skill`, `~/.claude/skills//SKILL.md`; with `--as-cursor-skill`, `.cursor/rules/summer-.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: | Property | Correct | Wrong | | -------- | ----------------------- | -------------------------------------------------- | | position | `"Vector3(0, 10, 0)"` | `{x: 0, y: 10, z: 0}` | | color | `"Color(1, 0.5, 0, 1)"` | `{r: 1, g: 0.5, b: 0}` | | mesh | `"BoxMesh"` | `"res://box.glb"` (use InstantiateScene for files) | ### 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: ``` name: "jump" events: [{ type: "key", key: "Space" }] ``` For WASD movement: ``` name: "move_forward" events: [{ type: "key", key: "W" }] ``` ### 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 | Task | Tool | | ----------------------- | ----------------------------------------------------------------------------------- | | Add object | `summer_add_node` with `scenePath` | | Move/scale/rotate | `summer_set_prop` with `scenePath` | | Set mesh type | `summer_set_prop` with `scenePath` (mesh: "BoxMesh", etc.) | | Set collision size | `summer_set_resource_property` with `scenePath` | | Set material color | `summer_set_resource_property` with `scenePath` | | Add prefab/model | `summer_instantiate_scene` with `scenePath` | | Import from URL | `summer_import_from_url` or `summer_import_from_url_batch` | | Wire up button | `summer_connect_signal` with `scenePath` | | Check errors | `summer_get_diagnostics` | | See how a scene looks | `summer_screenshot(target="scene", scenePath=...)` — offscreen, no window | | Run game | `summer_play` → `summer_screenshot(target="game")` → `summer_stop` — opens a window | | Standalone save/save-as | `summer_save_scene(scenePath=...)` | *** ## Next Steps Full parameter reference for the current MCP tool set Connect your IDE to Summer Engine *** 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. # Build Games in Claude Code with Summer Engine MCP Source: https://docs.summerengine.com/mcp/claude-code Connect Summer Engine's MCP server to Claude Code and build games with Claude's coding assistant driving your engine directly. ## Summer Engine in Claude Code Claude Code (Claude for developers) supports MCP servers. With Summer Engine's integration, Claude can modify your game scenes, add nodes, import assets, run the game, and debug, all from the same conversation where you're writing code. This guide covers the configuration steps. The setup takes about a minute. ## Prerequisites * **Claude Code**: The desktop app or IDE integration * **Node.js**: For running the MCP server (Node 18+) * **Summer Engine**: Installed and running with your project open ## Configuration ### Option 1: One-command setup (recommended) ```bash theme={null} npx -y summer-engine@latest setup claude-code --yes ``` This writes the `summer-engine` server into `~/.claude.json` (Claude Code's user-level MCP config), installs the skill library to `~/.claude/skills/`, and runs `summer doctor`. Add `--scope project` to write `.mcp.json` in the project root and `.claude/skills/` instead, so the setup travels with the game. ### Option 2: Manual configuration #### Step 1: Locate the Config File Claude Code reads MCP servers from two places: * **User-level:** `~/.claude.json` (all projects). On Windows: `%USERPROFILE%\.claude.json`. * **Project-level:** `.mcp.json` in the project root (shared with the team through version control; Claude Code asks once before loading it). Create the file if it doesn't exist. If you already have other MCP servers configured, add Summer Engine to the existing `mcpServers` object. Claude Code lists `"type": "stdio"` as required for command-based servers. #### Step 2: Add Summer Engine ```json New file (.mcp.json or ~/.claude.json) theme={null} { "mcpServers": { "summer-engine": { "type": "stdio", "command": "npx", "args": ["-y", "summer-engine@latest", "mcp"] } } } ``` ```json Adding to existing mcpServers theme={null} { "mcpServers": { "other-server": { ... }, "summer-engine": { "type": "stdio", "command": "npx", "args": ["-y", "summer-engine@latest", "mcp"] } } } ``` You can also let Claude Code write it: `claude mcp add summer-engine -- npx -y summer-engine@latest mcp`. ### Step 3: Restart Claude Code Start a new Claude Code session, or run `/mcp` to reload servers. The server starts when Claude Code starts; it connects to the engine on the first tool call. ### Step 4: Verify When you start a conversation, Claude should have access to Summer Engine's tools. You can ask: * "Use Summer Engine to add a Camera3D to the scene" * "Get the scene tree from Summer Engine" If Claude says it doesn't have access to Summer Engine tools, run `/mcp` to see the server list, then check the config file path and that the JSON is valid. `summer doctor` checks the same things from the terminal. ## Using Summer Engine with Claude Claude will use the MCP tools when your requests involve game development. You can be explicit ("Use Summer Engine to...") or implicit ("Add a player character to the scene"). If you're in a game project, Claude may infer that Summer Engine is the right tool. **Example prompts:** * "Add a CharacterBody3D named Player with a CollisionShape3D to the scene" * "Import [https://example.com/barrel.glb](https://example.com/barrel.glb) and add it under `./World/Props`" * "Set up jump and move\_forward input actions for WASD and Space" * "Run the game and tell me if there are any errors in the console" * "Save the current scene to res\://levels/level1.tscn" **Engine must be running.** Claude's tools talk to Summer Engine over localhost. Open your project in the engine first, or run `npx summer-engine run` from the project directory. ## Troubleshooting ### "Summer Engine is not running" The MCP server couldn't connect to the engine. Start Summer Engine, open your project, and try again. The engine runs a local API on port 6550; the MCP server discovers it via `~/.summer/api-token`. ### Config not loading * **Path:** Ensure the file is `~/.claude.json` (user) or `.mcp.json` in the project root (project). `~/.claude/claude_code_config.json` from older guides is not read. * **JSON:** Validate the syntax. No trailing commas, all strings in double quotes * **Restart:** Fully quit Claude Code and reopen ### Claude doesn't use the tools Claude may not always choose MCP tools automatically. If you want to force their use, phrase your request explicitly: "Use the summer\_add\_node tool to add a DirectionalLight3D to the scene." ## Next Steps Every MCP tool with parameters and examples How an AI builds a full game using MCP Architecture, prerequisites, and other IDEs summer install, run, create, 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. # CLI Quick Start Source: https://docs.summerengine.com/mcp/cli Install Summer Engine, create projects, run the engine, and connect your IDE. Claude Code, Cursor, and Devin Desktop use the MCP to control Summer Engine. ## What is the CLI? The Summer Engine CLI lets you install the engine, create projects, run the engine, and connect your AI IDE (Claude Code, Cursor, Devin Desktop) to Summer Engine. Add the MCP config to your IDE and it will spawn the MCP server. You chat with the AI in your IDE, and the AI uses MCP tools to manipulate scenes, run the game, and debug. Use `npx summer-engine` (no install) or `summer` (after global install). ## Install the Engine ```bash theme={null} npx summer-engine install ``` Downloads and installs Summer Engine to your system (macOS: `/Applications/Summer.app`, Windows: default location). No npm global install required. ## Sign In ```bash theme={null} npx summer-engine login ``` Opens your browser to sign in with Google, GitHub, or email. Saves your session and the [Summer Cloud](/guides/summer-cloud) token used for project sync. ## Create a Project ```bash theme={null} npx summer-engine create 3d-basic my-game ``` Creates a new project from a template. Templates: `empty` (minimal 3D) or `3d-basic` (camera, light, floor). ## Run the Engine ```bash theme={null} npx summer-engine run my-game ``` Launches Summer Engine with your project. The engine must be running for MCP tools to work. ## Start MCP (for Cursor, Claude Code, Devin Desktop) Add this to your IDE's MCP config. The IDE spawns `summer mcp` when it connects. You don't run it manually: ```json theme={null} { "mcpServers": { "summer-engine": { "command": "npx", "args": ["-y", "summer-engine@latest", "mcp"] } } } ``` See [MCP setup](/mcp/setup) for IDE-specific instructions. ## Full CLI Reference | Command | Description | | --------------------------------- | ------------------------------------------ | | `summer install` | Download and install Summer Engine | | `summer login` | Sign in via browser | | `summer logout` | Clear auth tokens | | `summer status` | Check engine status, port, auth | | `summer run [path]` | Launch engine, optionally with project | | `summer open ` | Open project in running engine | | `summer create