summer-engine 3.1.0 → 3.2.0

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 94 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 116 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -11,23 +11,23 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [2d](#2d) (10)
 - [3d](#3d) (6)
 - [agent-workflow](#agent-workflow) (17)
-- [ai](#ai) (1)
-- [animation](#animation) (6)
+- [ai](#ai) (2)
+- [animation](#animation) (7)
 - [assets](#assets) (3)
 - [audio](#audio) (6)
-- [character-controller](#character-controller) (1)
+- [character-controller](#character-controller) (2)
 - [debug](#debug) (1)
 - [deployment](#deployment) (2)
 - [editor](#editor) (1)
-- [gameplay](#gameplay) (3)
+- [gameplay](#gameplay) (6)
 - [level-design](#level-design) (2)
-- [multiplayer](#multiplayer) (3)
+- [multiplayer](#multiplayer) (16)
 - [navigation](#navigation) (1)
 - [performance](#performance) (1)
-- [rendering](#rendering) (4)
+- [rendering](#rendering) (5)
 - [runtime](#runtime) (1)
-- [scenes](#scenes) (11)
-- [scripting](#scripting) (1)
+- [scenes](#scenes) (12)
+- [scripting](#scripting) (2)
 - [ui](#ui) (1)
 - [vfx](#vfx) (9)
 - [video](#video) (3)
@@ -84,6 +84,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
+| [*ai-characters-in-games*](./ai-characters-in-games/SKILL.md) (preview) | 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. | npc |
 | [design-npc](./design-npc/SKILL.md) ★ | Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree. | npc |
 
 ## animation
@@ -96,6 +97,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [generate-motion](./generate-motion/SKILL.md) ★ | Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer. | 3d |
 | [procedural-animation](./procedural-animation/SKILL.md) | Runtime bone modification on top of clips — head look-at, foot IK, hand-grabs-prop, additive lean, recoil. Code-and-modifier patterns, not generation. | 3d |
 | [retarget](./retarget/SKILL.md) | Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration. | 3d |
+| [*text-to-motion*](./text-to-motion/SKILL.md) (preview) | Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props. | generate, 3d |
 
 ## assets
 
@@ -120,6 +122,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
+| [*character-movement*](./character-movement/SKILL.md) (preview) | Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state. | gameplay, 2d, 3d |
 | [fps-controller](./fps-controller/SKILL.md) ★ | Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling. | gameplay |
 
 ## debug
@@ -147,7 +150,10 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [auto-fire-targeting](./auto-fire-targeting/SKILL.md) | Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill. | game-design |
 | [*celeste-momentum-platforming*](./celeste-momentum-platforming/SKILL.md) (preview) | Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction. | character-controller, game-design |
+| [*combat-basics*](./combat-basics/SKILL.md) (preview) | Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles. | scripting, game-design |
 | [design-mechanic](./design-mechanic/SKILL.md) ★ | Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub. | game-design |
+| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy. | scripting, game-design |
+| [*web-and-touch-input*](./web-and-touch-input/SKILL.md) ★ (preview) | Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions. | ui |
 
 ## level-design
 
@@ -160,9 +166,22 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [host-authoritative-state](./host-authoritative-state/SKILL.md) ★ | Design the state layer of a multiplayer game — what the host owns, how clients request changes, and how the host validates and broadcasts. | game-design |
-| [peer-to-peer-multiplayer](./peer-to-peer-multiplayer/SKILL.md) ★ | Start a multiplayer game from scratch with peer-to-peer host authority — network architecture built top-down, before writing game logic. | project |
-| [setup-multiplayer](./setup-multiplayer/SKILL.md) ★ | Add multiplayer to an existing game — LAN/online co-op, PvP, lobbies — via MultiplayerAPI, MultiplayerSpawner, and MultiplayerSynchronizer. | scripting |
+| [multiplayer](./multiplayer/SKILL.md) ★ | Start here for Summer multiplayer: how the authority, clients, Worlds and Sessions fit, and which skill comes next. | project |
+| [multiplayer-movement](./multiplayer-movement/SKILL.md) | Client-side movement in Summer multiplayer: owners move instantly, others glide, the authority checks each pose. | character-controller, scripting |
+| [multiplayer-project](./multiplayer-project/SKILL.md) | Set up a Summer multiplayer project: both entry scenes, World and queue files, joining, and a first Local Play run. | project, scripting |
+| [*multiplayer-publish*](./multiplayer-publish/SKILL.md) (preview) | Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build. | deployment |
+| [multiplayer-state](./multiplayer-state/SKILL.md) | Authority-owned game state in Summer multiplayer: shared and private State groups, validated Commands, and Events. | game-design, scripting |
+| [multiplayer-testing](./multiplayer-testing/SKILL.md) | Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows. | playtest, verification |
+| [*summer-analytics*](./summer-analytics/SKILL.md) (preview) | Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay. | scripting |
+| [*summer-friends*](./summer-friends/SKILL.md) (preview) | Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only. | ui |
+| [*summer-leaderboards*](./summer-leaderboards/SKILL.md) (preview) | Leaderboards in a Summer game: queue ratings from matches, and Game rankings your authority scores. | ui |
+| [summer-match-results](./summer-match-results/SKILL.md) | End a Summer match: report each player's win, loss or draw, show results on clients, then close the World. | gameplay |
+| [*summer-matchmaking*](./summer-matchmaking/SKILL.md) (preview) | Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures. | ux |
+| [*summer-parties*](./summer-parties/SKILL.md) (preview) | Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only. | ui |
+| [summer-player-data](./summer-player-data/SKILL.md) | Save a player's progress so it follows them to every match: authority load and commit, autosave, safe retries. | scripting |
+| [*summer-store*](./summer-store/SKILL.md) (preview) | Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks. | gameplay |
+| [*summer-world-chat*](./summer-world-chat/SKILL.md) (preview) | Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only. | ui |
+| [*summer-world-saves*](./summer-world-saves/SKILL.md) (preview) | Keep a persistent Summer World between restarts: checkpoint saves, restore before join, the final save. | scripting |
 
 ## navigation
 
@@ -184,6 +203,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [art-direction](./art-direction/SKILL.md) ★ | 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. | lighting |
 | [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
 | [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
+| [*web-compatibility-look*](./web-compatibility-look/SKILL.md) ★ (preview) | Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance. | 2d, 3d |
 
 ## runtime
 
@@ -197,14 +217,15 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [brainstorm-game](./brainstorm-game/SKILL.md) ★ | 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. | project |
 | [browse-templates](./browse-templates/SKILL.md) ★ | List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create. | project |
+| [*camera-rigs*](./camera-rigs/SKILL.md) (preview) | Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance. | 3d, 2d |
 | [make-game](./make-game/SKILL.md) ★ | Orchestration spine for 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship — delegates to specialist skills. | project |
 | [new-project](./new-project/SKILL.md) ★ | Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty. | project |
 | [play](./play/SKILL.md) ★ | Run the project in Summer Engine, wait briefly, then report what's happening — clean run, errors, or warnings. | project |
 | [scene-composition](./scene-composition/SKILL.md) ★ | Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. | project |
 | [*scene-hierarchy-design*](./scene-hierarchy-design/SKILL.md) (preview) | Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic. | project, agent-workflow |
 | [*scene-scripting*](./scene-scripting/SKILL.md) ★ (preview) | One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot. | scripting, 2d, ui, agent-workflow |
-| [*spatial-placement*](./spatial-placement/SKILL.md) ★ (preview) | Place and verify 3D objects with Starcast evidence — inspect, place, starcast, correct, verify; floor, shelf, wall, alcove recipes and overlap repair. | 3d, world-building, level-design, verification |
-| [*verifying-scenes*](./verifying-scenes/SKILL.md) ★ (preview) | Prove scene work landed — snapshot before, diff + screenshot after (bookmarked viewpoint, labels), live runtime reads during playtests — then claim. | verification, agent-workflow |
+| [*spatial-placement*](./spatial-placement/SKILL.md) ★ (preview) | Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes. | 3d, world-building, level-design, verification |
+| [*verifying-scenes*](./verifying-scenes/SKILL.md) ★ (preview) | Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms. | verification, agent-workflow |
 | [*world-building-3d*](./world-building-3d/SKILL.md) ★ (preview) | Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified. | 3d, world-building, level-design, verification |
 
 ## scripting
@@ -212,6 +233,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | skill | when to use | also |
 |---|---|---|
 | [gdscript-patterns](./gdscript-patterns/SKILL.md) ★ | GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming. | conventions |
+| [*save-load*](./save-load/SKILL.md) (preview) | Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks. | gameplay |
 
 ## ui
 

package/library/skills/adaptive-music/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adaptive-music
-description: Use when wiring music stems to game state — combat / explore / boss / tension crossfades on a shared bus. Pairs generated stems with a state machine and AudioBus structure. Trigger on "adaptive music", "dynamic music", "music changes when combat starts", "layered music", "vertical music", "wire stems".
+description: "Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/agent-playtesting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-playtesting
-description: Use when proving a gameplay feature, reproducing a bug, or comparing two variants by driving the LIVE running game yourself — deterministic launch (seed, fixed_fps, offscreen instances), frame-stamped probes before and after every action, exact frame stepping, scripted or recorded input. The doctrine behind summer_game_probe, summer_game_input, summer_game_control and the summer_runtime_* tools.
+description: "Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input."
 ---
 
 # Agent Playtesting

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