summer-engine 3.0.0 → 3.2.0

package/library/skills/ai-characters-in-games/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: ai-characters-in-games
+description: "Safe AI characters in published games: no keys in the build, replies via Summer's player AI gateway, moderation, spend caps, offline brain and a report button."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: ai-and-npcs
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_add_node summer_set_prop summer_connect_signal summer_save_scene summer_get_script_errors
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# AI Characters in Games
+
+## Overview
+
+A talking flower, a shopkeeper who answers questions, a companion who reacts to what the player says. Players, often children, type or speak to it and it answers in character.
+
+**Core principle:** the game never talks to an AI provider. It asks Summer, as the signed-in player, for a reply from a persona the developer declared. Summer holds the keys (you never bring your own), moderates both directions, charges the cost to the developer's Summer credits and can switch the feature off per game. The game treats every AI answer as optional flavour on top of an offline brain that always works.
+
+**Status: preview.** `Summer.client.ai` ships with an upcoming Summer Engine release. The example checks for it at runtime and reads the `capabilities` of `status()` before using a call, and uses the offline brain whenever either is missing, so a game written this way ships today and gains AI replies when the platform turns them on.
+
+## When to use
+
+- A character, creature or object answers free-form player text or speech.
+- You are about to put a model name, a provider SDK or a key into a game project. Stop and use this instead.
+
+Not for scripted dialogue trees (design-npc) or for enemy behaviour.
+
+## The rules, and why
+
+| Rule | Why |
+| --- | --- |
+| No provider key, provider URL or provider SDK in the project | Anything in a build can be extracted. A leaked key is spent by strangers on your account, and there is no way to take it back from builds already installed. |
+| Call the Summer gateway as the player | The player's own credential identifies who is talking, so limits, age policy and reports attach to a real person, not to the game. |
+| Personas live in the game's AI settings; the game sends only a persona id | If the client could send system text, anyone could turn your flower into a general chatbot. Persona text is moderated when the developer saves it. |
+| History is kept by the gateway | A client that sends its own history can forge what the character "said" before. Send a conversation id instead. |
+| Moderation runs on player text and on the reply, and fails closed | Young audience. A flagged turn returns the persona's safe line (`moderated: true`); show it like any other reply. |
+| Handle every refusal code by falling back, never by retrying in a loop | The limit and the kill switch are how cost and incidents are contained. A retry loop turns them into spend and noise. |
+| Hold-to-talk plus a typed box | Many players cannot or will not use a microphone. Speech is transcribed to text and then goes through the same reply path. |
+| Offline brain always present | The gateway can be off, over its limit, unavailable for the player's age or unreachable. The game must still be good. |
+| AI replies never change game state directly | A model can be talked into anything. If a reply should matter (a mood, a gift), derive a small bounded effect from the player's words on the authority, the same way the offline brain does. |
+| A report button on every AI reply | App store rules for user-facing generated content. The report names the exchange id, so the stored text is the evidence, not a screenshot. |
+| Never ask for or keep personal details | Summer strips contact details before the model sees them; do not store transcripts in saves either. |
+| Label AI characters as AI | Players must know they are talking to generated replies (EU AI Act transparency duties apply from August 2026). A small "AI" tag on the bubble is enough; store listings such as Steam also ask you to disclose live-generated content. |
+| Ask before using the microphone, and say audio is not stored | Consent is expected, and it is true: Summer transcribes and discards the clip. |
+| No voice cloning or speaker identification on player audio | Biometric laws (for example Illinois BIPA) treat voiceprints as protected data. Characters speak only in voices you chose. |
+| Keep characters off mental health, self-harm and romance | Companion-chatbot rules (for example California SB 243) target exactly these. Write it into the persona description and rely on the safe line. |
+
+## Top up and set limits
+
+AI characters are paid from the Summer credits of the developer who turned them on: usage is billed from your Summer credits. Cost depends on the models and voices you choose. Your dashboard shows spend as it happens, and your limits cap it. Players never pay. There is nothing to configure in the game project.
+
+1. In Summer Studio, open the game and its **AI characters** section.
+2. Add a persona per character: name, a plain-words description, an optional voice, reply length, a safe line in character, and the model (from the models the game allows, each marked fast or smart).
+3. Set limits per player per day, per game per day and per month, optional per-model caps, and the refill amount; see your dashboard for the ranges.
+4. Turn **Enable** on. Saving makes you the funding developer: Summer moves your credits into the game's AI balance in refill-sized chunks as it runs low.
+5. Top up credits from the billing page when the balance is low. **Withdraw unused AI credits** returns what no call has reserved.
+
+When credits or a limit run out, players get `credits_exhausted` or `limit_exceeded` and the game falls back to its offline brain; nothing crashes. **Enable** off is the kill switch and applies to the next request. Children and players who have not declared an age are excluded.
+
+## The SDK
+
+`Summer.client.ai` exists only on engines that include it; everywhere else it is `null`. Every method returns a `SummerOperation`. Await it race-free:
+
+```gdscript
+var op: Object = ai.reply(persona_id, text)
+var r: SummerResult = await op.get_result_or_completed_signal()
+```
+
+`r.ok`, `r.code` and `r.retryable` say how it went; the answer itself is on the operation, a `SummerAIOperation` (`op.text`, `op.audio`, ...), because replies and voice clips are larger than a result's `details`. Type it as `Object` so the script still parses on engines without that class. The engine creates request ids itself.
+
+| Call | Set on the operation on success |
+| --- | --- |
+| `status()` | `available: bool`, `reason: String` (`""` or one of the failure codes below: `ai_disabled`, `age_policy`, `credits_exhausted`, `limit_exceeded`, `unavailable`, `unsupported`), `personas: Array` of `{id, name, has_voice}`, `capabilities: PackedStringArray` (`"reply"`, `"transcribe"`, `"speak"`, `"report"`), `version: String`. `status` never fails for policy reasons. |
+| `reply(persona_id, text, conversation_id = "")` | `exchange_id`, `persona_id`, `text`, `moderated: bool`. `text` is 1 to 500 characters. |
+| `transcribe(audio: PackedByteArray, mime_type, language = "")` | `text`. At most 240 KiB and 15 seconds (compressed `audio/ogg` or `audio/webm` fits more speech than WAV), as `audio/wav`, `audio/ogg`, `audio/mpeg`, `audio/webm` or `audio/mp4`. Audio is not stored. |
+| `speak(exchange_id)` | `exchange_id`, `mime_type` (`audio/mpeg`), `audio: PackedByteArray`. Only the player's own reply, within an hour of it. Voice is the largest cost: speak only for personas with `has_voice`, and consider voicing on tap. |
+| `report(exchange_id, reason, details = "")` | `report_id`, `status`. The player's own reply, within 30 days. |
+
+`moderated: true` is not an error: the persona's safe line replaced the answer. Show it like any reply. Names are snake_case in GDScript (`op.exchange_id`, `persona.has_voice`). After `limit_exceeded` or `rate_limited`, `op.retry_after_seconds` says when asking again can succeed.
+
+In multiplayer, never broadcast text a client sent you. The dedicated authority verifies the exchange and broadcasts the text Summer returns:
+
+```gdscript
+var ai: Object = Summer.authority.get("ai")
+var check: Object = ai.verify_exchange(session, exchange_id)
+var r: SummerResult = await check.get_result_or_completed_signal()
+if r.ok:
+	broadcast_line(check.persona_id, check.text)  # exactly what that player was shown; check.player_id said it
+# not_found: forged, another player's, or older than an hour. Drop it.
+```
+
+Failure codes (`r.ok == false`):
+
+| Code | Meaning | Game does |
+| --- | --- | --- |
+| `ai_disabled` | AI is switched off for this game | Offline brain for the session |
+| `age_policy` | Child or undeclared age | Offline brain for the session |
+| `credits_exhausted` | The developer's AI credits ran out | Offline brain for the session |
+| `limit_exceeded` | A player, game or model limit is used up | Offline brain for the session |
+| `provider_error`, `unavailable`, `rate_limited` | Transient (`retryable` is true) | Offline brain for this line |
+| `not_signed_in`, `unsupported` | No player session, or no AI in this build | Offline brain |
+| `persona_unknown`, `invalid_request` | Bug: the persona id or the input | Fix the game or the settings |
+| `not_found` | `report` or `speak` named an exchange that is not the player's own, or is too old | Hide the button |
+
+## Steps
+
+1. **Write the offline brain first.** Keyword intents plus a few lines per personality, deterministic per (character, text) so every client agrees. This is the shipped experience when AI is unavailable.
+2. **Declare personas in the game's AI characters settings** (see Top up and set limits), not in scripts: one per character, a short description in plain words, a safe line in character ("Let's talk about sunshine instead!").
+3. **Add the talk UI**: a typed box, a hold-to-talk button that only appears when the microphone is allowed, the reply bubble, and a small report button on every AI reply.
+4. **Route through one character script** (below): gateway when `status` says available, offline brain otherwise and on every refusal.
+5. **Keep effects on the authority.** If talking changes something, the authority computes it from the player's words with the offline rules and clamps it.
+6. **Verify** (below).
+
+## Example
+
+```gdscript
+class_name TalkingCharacter
+extends Node
+## One AI character. Answers through Summer's player AI gateway when it is
+## available and falls back to the offline brain for everything else.
+
+signal replied(text: String, exchange_id: String, from_ai: bool)
+
+## Codes after which asking again this session only wastes calls.
+const STOP_CODES := [&"ai_disabled", &"age_policy", &"credits_exhausted", &"limit_exceeded", &"not_signed_in", &"unsupported"]
+
+@export var persona_id := "cheerful"
+@export var personality := "cheerful"
+
+var _conversation_id := ""
+var _ai_ready := false
+var _can_speak := false
+
+func _ready() -> void:
+	_conversation_id = "c%d" % (Time.get_ticks_usec() % 1000000000)
+	_ai_ready = await _gateway_available()
+
+func say(player_text: String) -> void:
+	var text := player_text.strip_edges().left(500)
+	if text.is_empty():
+		return
+	var ai := _gateway()
+	if _ai_ready and ai != null:
+		var op: Object = ai.reply(persona_id, text, _conversation_id)
+		var r: SummerResult = await op.get_result_or_completed_signal()
+		if r.ok:
+			replied.emit(op.text, op.exchange_id, true)
+			return
+		# Transient codes (provider_error, unavailable, rate_limited) fall through
+		# for this line only.
+		if r.code in STOP_CODES:
+			_ai_ready = false
+	replied.emit(OfflineBrain.answer(personality, text), "", false)
+
+## Voice a reply, for example when the player taps the bubble.
+func speak(exchange_id: String, player: AudioStreamPlayer) -> void:
+	var ai := _gateway()
+	if not _can_speak or ai == null or exchange_id == "":
+		return
+	var op: Object = ai.speak(exchange_id)
+	var r: SummerResult = await op.get_result_or_completed_signal()
+	if r.ok:
+		var stream := AudioStreamMP3.new()
+		stream.data = op.audio
+		player.stream = stream
+		player.play()
+
+func report(exchange_id: String) -> void:
+	var ai := _gateway()
+	if exchange_id != "" and ai != null:
+		await ai.report(exchange_id, "inappropriate").get_result_or_completed_signal()
+
+func _gateway_available() -> bool:
+	var ai := _gateway()
+	if ai == null:
+		return false
+	var op: Object = ai.status()
+	var r: SummerResult = await op.get_result_or_completed_signal()
+	if not r.ok or not op.available or not "reply" in op.capabilities:
+		return false
+	for p in op.personas:
+		if p.id == persona_id:
+			_can_speak = p.has_voice and "speak" in op.capabilities
+	return true
+
+## The only place that knows how the engine exposes the gateway. Engines
+## without it return null and the character stays offline.
+func _gateway() -> Object:
+	if not Engine.has_singleton("Summer") or Summer.client == null:
+		return null
+	var ai: Object = Summer.client.get("ai")
+	if ai == null or not ai.has_method("reply") or not ai.has_method("status"):
+		return null
+	return ai
+```
+
+`OfflineBrain.answer(personality, text)` is your step 1 script. Keep the report button visible only when `exchange_id` is not empty, since offline lines are your own text.
+
+## Verify
+
+- `grep` the project for provider names, model ids and anything key-shaped: none.
+- With the gateway absent (every engine today), every character answers from the offline brain and no error is shown.
+- Typed input works with the microphone denied.
+- Each failure code in the table leads to an offline answer, and the session-level codes stop further gateway calls.
+- With Enable off, or the game's AI credits withdrawn, the game still plays and every character answers offline.
+- `credits_exhausted` leads to an offline answer with no error shown.
+- A reply marked `moderated` shows the safe line.
+- AI replies carry an "AI" label, and the microphone is only used after the player agreed.
+- In multiplayer, the authority broadcasts only text returned by `verify_exchange`.
+- A reply never grants items, currency or progress by itself; the authority applies any effect.
+- Every AI reply shows a report button that sends its exchange id.
+
+## Common mistakes
+
+- Sending the persona description from the client "just for testing". It ships.
+- Treating `moderated: true` as an error. It is a normal reply.
+- Retrying on `limit_exceeded` or `credits_exhausted`. The limit is the product working.
+- Putting a provider key in the project "until Summer is live". There is no bring-your-own-key path; keys in builds leak.
+- Letting the model decide rewards because "it only suggests". It will be talked into suggesting everything.

package/library/skills/ai-characters-in-games/resource.yaml

@@ -0,0 +1,30 @@
+id: skill/ai-characters-in-games
+kind: skill
+version: 0.3.0
+summary: "Safe AI characters in published games: no keys in the build, replies via Summer's player AI gateway, moderation, spend caps, offline brain and a report button."
+use_when:
+  - a character, creature or object should answer free-form player text or speech in a published game (talking flowers, shopkeepers, companions)
+  - about to put a model name, a provider SDK or a provider key into a game project
+  - handling AI refusals (ai_disabled, age_policy, credits_exhausted, limit_exceeded) or adding the report button for AI replies
+  - topping up Summer credits, setting AI limits or the kill switch for a game's AI characters
+do_not_use_when:
+  - scripted dialogue trees or enemy behaviour — design-npc
+facets:
+  lifecycle:
+    - build
+  domains:
+    - ai
+    - npc
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/design-npc
+    - skill/multiplayer-state
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/ambient-bed/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ambient-bed
-description: Use when generating a long looping location ambience — forest at dawn, dungeon air, city street, spaceship hum, cave drip. Non-melodic, low-energy, never draws attention. Wires as a looping AudioStreamPlayer on the Ambient bus with a marked seamless loop. Trigger on "ambient bed", "room tone", "background ambience", "forest ambience", "dungeon air", "make it sound like a cave".
+description: "Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/animated-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animated-loop
-description: Use when generating a short looping video clip — splash screen background, animated logo backdrop, idle title-screen footage, looping environment ambience. Output must loop seamlessly and is wired as a VideoStreamPlayer with autoplay and loop set true. Trigger on "looping background", "splash loop", "title screen video", "animated backdrop", "menu background loop", "ambient loop video", "looping clip", "seamless loop".
+description: "Generate a short seamlessly-looping video clip — splash background, animated logo backdrop, idle title-screen footage — wired as a looping VideoStreamPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video

package/library/skills/animation-tree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animation-tree
-description: Use when the user has clips on a character and needs them to play in response to gameplay — idle/walk/run blend, attacks that interrupt locomotion, hit reactions that override everything. Designs and wires Summer Engine AnimationTree state machines and blend trees. Trigger on "AnimationTree", "state machine", "blend tree", "transition", "play animation when", "character keeps T-posing", "wire animations".
+description: "Design and wire AnimationTree state machines and blend trees so clips respond to gameplay — locomotion blends, attack interrupts, hit reactions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

package/library/skills/art-direction/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: art-direction
-description: Use when defining the visual style of the game — references, palette, mood, lighting plan, post-processing, do/don't list. Outputs an art bible at `.summer/art-bible.md`. Trigger on "art direction", "art bible", "visual style", "color palette", "what should it look like", "the look".
+description: "Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting

package/library/skills/asset-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: asset-strategy
-description: Use when planning asset creation, picking an asset pipeline, or routing an "I need a [thing]" request to the right specialist skill. Disambiguates between 2D / 3D / audio / video / VFX / animation pipelines and dispatches via the Skill tool. Trigger on "assets", "asset pipeline", "make a model", "I need a sound", "create concept art", "generate something", broad creative requests.
+description: "Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline
@@ -84,6 +84,7 @@ Polycount targets (hero 8k–15k, grunt 3k–6k, mobile 1k–3k, cinematic 20k
 | Request | Skill |
 |---|---|
 | Idle / walk / run / attack — new clip | `generate-motion` |
+| Custom action or non-humanoid rig (flower, creature, prop) — clip from text | `text-to-motion` |
 | Apply library to a different character | `retarget` |
 | Blend tree / state machine | `animation-tree` |
 | Look-at / IK / foot placement | `procedural-animation` |

package/library/skills/asset-strategy/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/asset-strategy
 kind: skill
-version: 1.0.2
+version: 1.0.3
 summary: Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines.
 use_when:
   - planning asset creation, picking an asset pipeline, or routing an 'I need a [thing]' request to the right specialist skill
@@ -35,6 +35,7 @@ related:
     - skill/animation-tree
     - skill/facial-and-lipsync
     - skill/generate-motion
+    - skill/text-to-motion
     - skill/procedural-animation
     - skill/retarget
     - skill/adaptive-music

package/library/skills/audio-direction/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audio-direction
-description: Use when defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan. Outputs an audio bible at `.summer/audio-bible.md`. Trigger on "audio direction", "audio bible", "music style", "sound design", "what should it sound like", "dynamic music".
+description: "Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/auto-fire-targeting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: auto-fire-targeting
-description: Use when designing or fixing the targeting system for an auto-fire weapon (survivors-genre, top-down ARPG, tower-defense). Covers the pending-damage pattern that prevents over-commit when bullet flight time is longer than fire rate. Trigger on "auto-fire", "auto-aim", "weapon targeting", "targeting", "wasted bullets", "overkill", "damage prediction", "survivors weapon".
+description: "Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics

package/library/skills/brainstorm-game/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-game
-description: Use when the user wants help deciding what game to make, scoping a new project, or turning a vague idea into a buildable plan. Walks through genre, scope, core loop, mechanics, and art direction, then writes a 1-page brief to `.summer/GameSoul.md`. Trigger on "brainstorm a game", "what should I make", "I want to make a game", "help me scope", "new game idea".
+description: "Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

package/library/skills/brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: "Use when starting creative work — designing a game, picking a mechanic, building features or components, modifying behavior. Explores user intent, requirements, and design before implementation. MUST run before any creative work."
+description: "Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior."
 ---
 
 # Brainstorming Ideas Into Designs

package/library/skills/browse-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse-templates
-description: Use when the user wants to see available Summer Engine project templates, start from an existing template, or asks "what templates exist?" — lists the pinned template registry via `summer list templates`, presents the choices, and creates a project from the chosen template via `summer create <slug> <project-name>`. Trigger on "templates", "starter", "boilerplate", "from a template", "what's available", "show me templates", "third-person", "platformer", "multiplayer starter".
+description: "List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -11,7 +11,7 @@ paths: ["**/project.godot"]
 
 # /browse-templates — Pick a registry template and create a project from it
 
-Summer's templates are the pin manifests in `library/templates/<slug>/resource.yaml`, compiled into `registry/generated/templates-registry.json`: `3d-third-person-controller`, `3d-lan-multiplayer-starter`, `2d-platformer`, and so on. Each pinned template names a repo, an exact commit, and a tree digest; the two built-ins (`empty`, `3d-basic`) are generated locally. They're working starter projects — open in Summer Engine and play immediately.
+Summer's templates are the pin manifests in `library/templates/<slug>/resource.yaml`, compiled into `registry/generated/templates-registry.json`: `3d-third-person-controller`, `2d-platformer`, and so on. Each pinned template names a repo, an exact commit, and a tree digest; the two built-ins (`empty`, `3d-basic`) are generated locally. They're working starter projects — open in Summer Engine and play immediately.
 
 ## When to use this skill
 
@@ -99,7 +99,7 @@ Confirm it opens. Then invoke `play` to verify the template runs as expected bef
 Once the project is created and running, hand off cleanly. The next skill that fires depends on the template:
 
 - Third-person controller → likely `scene-composition` or `gdscript-patterns` next.
-- Multiplayer starter → `setup-multiplayer` or `host-authoritative-state`.
+- Multiplayer starter → `multiplayer` (it routes to `multiplayer-project`).
 - 2D platformer → `design-mechanic` for the platforming feel, then `design-level`.
 
 Don't auto-fire the next skill — wait for the user to say what they want to change first.

package/library/skills/browse-templates/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/browse-templates
 kind: skill
-version: 1.0.4
+version: 1.0.5
 summary: List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create.
 use_when:
   - the user wants to see available Summer Engine project templates, start from an existing template, or asks what templates exist

package/library/skills/camera-rigs/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: camera-rigs
+description: "Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: scene-and-project
+user-invocable: false
+allowed-tools: Read Grep summer_get_scene_tree summer_inspect_node summer_add_node summer_set_prop summer_batch summer_save_scene summer_screenshot summer_play summer_stop summer_get_diagnostics
+paths: ["**/*.tscn", "**/*.gd"]
+---
+
+# Camera Rigs
+
+One rule above all: exactly ONE camera is active. In 3D that is the single
+`Camera3D` with `current = true`; two current cameras = flicker or the wrong
+view, and a scene with no current camera renders nothing in the game. In 2D a
+`Camera2D` is active when `enabled = true` (the default) and it is in the tree;
+with several enabled cameras, call `make_current()` on the one you want.
+
+Trigger phrases: "black screen on play", "camera shows past the level edge",
+"jerky follow", "wrong FOV", "I need a top-down / isometric / orbit camera".
+
+Ops use engine variant strings (`"Vector3(0, 5, 10)"`), never JSON objects
+(`{x: 0, y: 5, z: 10}` fails). Every mutation names its scene: pass the exact
+`scenePath` (e.g. `res://main.tscn`). One `summer_batch` per rig saves the scene
+once; the examples below use it.
+
+## 2D follow camera
+
+Add the `Camera2D` as a CHILD of the player so it follows for free, then smooth
+it and clamp it to the level.
+
+```
+summer_batch(scenePath="res://main.tscn", ops=[
+  {"op": "AddNode", "parent": "./Player", "type": "Camera2D", "name": "Camera"},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "position_smoothing_enabled", "value": true},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "position_smoothing_speed", "value": 6.0},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "limit_left", "value": 0},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "limit_right", "value": 1920},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "limit_top", "value": 0},
+  {"op": "SetProp", "path": "./Player/Camera", "key": "limit_bottom", "value": 1080}
+])
+```
+
+- Smoothing speed 5-8 feels responsive; higher = tighter, lower = drifty.
+- Set limits to the actual level bounds (the numbers above are placeholders).
+  `limit_smoothing_enabled = true` avoids a hard stop at the edge.
+- Zoom `Vector2(2, 2)` zooms IN (bigger), `Vector2(0.5, 0.5)` zooms OUT (top-down).
+
+## 2D top-down camera
+
+Same as above minus the platformer edge-lock urgency. Zoom out to show the field
+(`Vector2(0.5, 0.5)`). Keep it centered on the player; no vertical bias.
+
+## 3D first-person camera
+
+Camera is a child of a `Head` node on the player. Body yaws, Head pitches. See
+the `character-movement` skill (its `../character-movement/references/movement-3d.md`) or
+`fps-controller` for the look script. FOV 70-75, near 0.05.
+
+```
+summer_batch(scenePath="res://main.tscn", ops=[
+  {"op": "AddNode", "parent": "./Player/Head", "type": "Camera3D", "name": "Camera"},
+  {"op": "SetProp", "path": "./Player/Head/Camera", "key": "fov", "value": 72.0},
+  {"op": "SetProp", "path": "./Player/Head/Camera", "key": "near", "value": 0.05},
+  {"op": "SetProp", "path": "./Player/Head/Camera", "key": "current", "value": true}
+])
+```
+
+## 3D third-person camera (spring arm)
+
+The `SpringArm3D` pushes the camera in when a wall is behind the player, so it
+never clips through geometry. This is the correct third-person rig - do not just
+park a Camera3D behind the player.
+
+```
+summer_batch(scenePath="res://main.tscn", ops=[
+  {"op": "AddNode", "parent": "./Player", "type": "SpringArm3D", "name": "SpringArm"},
+  {"op": "SetProp", "path": "./Player/SpringArm", "key": "position", "value": "Vector3(0, 2, 0)"},
+  {"op": "SetProp", "path": "./Player/SpringArm", "key": "spring_length", "value": 4.5},
+  {"op": "SetProp", "path": "./Player/SpringArm", "key": "collision_mask", "value": 2},
+  {"op": "AddNode", "parent": "./Player/SpringArm", "type": "Camera3D", "name": "Camera"},
+  {"op": "SetProp", "path": "./Player/SpringArm/Camera", "key": "current", "value": true}
+])
+```
+
+Set `collision_mask` to the LEVEL layer only. If it includes the player layer the
+arm collapses to length 0 and you see inside the character (a controller script
+can also call `add_excluded_object(get_rid())` on the arm).
+
+## Orthographic top-down 3D (twin-stick, strategy, isometric)
+
+```
+summer_batch(scenePath="res://main.tscn", ops=[
+  {"op": "SetProp", "path": "./Camera", "key": "projection", "value": 1},
+  {"op": "SetProp", "path": "./Camera", "key": "size", "value": 20.0},
+  {"op": "SetProp", "path": "./Camera", "key": "position", "value": "Vector3(0, 20, 0)"},
+  {"op": "SetProp", "path": "./Camera", "key": "rotation_degrees", "value": "Vector3(-90, 0, 0)"}
+])
+```
+
+`projection = 1` is orthogonal. `size` is the vertical world units shown - bigger
+= more zoomed out. For isometric, rotate ~(-30, 45, 0) instead of straight down.
+
+## FOV guidance
+
+- 60-75: most 3D games. 90+: fast FPS (feels faster, more peripheral).
+- Under 40 or over 110 distorts. Never animate FOV wildly; a small kick (+8 on
+  sprint, tweened back) reads as speed.
+
+## Verify
+
+A camera is only proven by a frame. After the rig is in, `summer_play`, then
+`summer_screenshot` with `target: "game"`, then `summer_stop`; or save frames
+from a `RunVerification` probe while the player moves (see
+`playtesting-a-feature`). An editor `viewport` screenshot shows the editor's
+camera, not the game's.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Black screen | No current/enabled camera | 3D: `current = true` on exactly one; 2D: one enabled Camera2D in the tree |
+| Camera inside geometry | Spawned inside a wall/player | Move it out; spring arm for 3P |
+| Jerky follow | Smoothing off/too slow | Enable smoothing, speed 6-10 |
+| Shows past level edge | No 2D limits | Set `limit_*` to level bounds |
+| Wrong facing (3D) | rotation.y off | y: 0 = forward, 180 = backward |
+| Everything tiny/huge (ortho) | `size` wrong | Tune `size`, not `position.y` |

package/library/skills/camera-rigs/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/camera-rigs
+kind: skill
+version: 1.0.0
+summary: "Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance."
+use_when:
+  - black screen on play, or the camera shows past the level edge
+  - jerky camera follow, wrong FOV, or the third-person camera clips into walls
+  - need a top-down, isometric, orthographic, orbit, or spring-arm camera
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - 2d
+  modalities:
+    - scenes
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/character-movement
+    - skill/fps-controller
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/celeste-momentum-platforming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: celeste-momentum-platforming
-description: "Use when building or tuning Celeste-style momentum-based precision platformer movement in SummerEngine (Godot 4): tuned gravity/fall, run acceleration, variable-height jumps with coyote time, dashes, wall jumps/slides, climb stamina, and pixel-scale corner correction, using the exact tuning constants extracted from Celeste's open-source Player class."
+description: "Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction."
 license: MIT
 category: game-feel
 tags:

package/library/skills/character-animation-wiring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: character-animation-wiring
-description: Use when a rigged, animated character is in the scene (Meshy rig + generated clips, or an imported GLB) and needs to be wired end to end — inspect the clips and bones that actually arrived, build idle/walk/run locomotion with blend times, method-track footsteps and attack frames, still poses and head tracking, blend-shape facial keys, root motion. Trigger on "wire the character", "hook up the animations", "make it walk around", "the GLB has animations", "footstep events", "attack frame", "root motion", "character slides while walking".
+description: "Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

package/library/skills/character-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: character-model
-description: Use when generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion. Generates a T-pose reference image, gates an un-rigged preview past the user, then runs the Meshy auto-rig pass and wires the result as a CharacterBody3D (movement) or Node3D (cinematic). Trigger on "make a character", "generate the player", "I need an enemy model", "create an NPC", "rigged humanoid", "character with a skeleton", "model for animation".
+description: "Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets