@pix3/cli 1.6.3 → 2.0.0-alpha.0

package/kit/files/.claude/skills/pix3-scene-format/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pix3-scene-format
-description: The .pix3scene YAML format — file header, node shape (id/type/name/properties/children/components), component shape, 2D transform and layout blocks, res:// references, textures, prefab instances and overrides, scenes/ui overlays and the visible/initiallyVisible split, plus how to translate design/recipe.md tool names into file edits. Use BEFORE creating or editing any .pix3scene file (scene, prefab or overlay) in this project.
+description: The .pix3scene YAML format — file header, node shape (id/type/name/properties/children/components), component shape, 2D transform and layout blocks, res:// references, textures, prefab instances and overrides, scenes/ui overlays and the visible/initiallyVisible split; `.pix3anim` flipbooks (and `pix3 character-compile`) in `pix3anim.md` beside it; creating, renaming, moving, deleting files, extracting a branch into a prefab, locales, `pix3project.yaml` and build options in `project-files.md` beside it. Use BEFORE creating or editing any .pix3scene file (scene, prefab or overlay) in this project.
 ---
 
-<!-- Pix3 agent kit 1.6.3 -->
+<!-- Pix3 agent kit 2.0.0-alpha.0 -->
 # `.pix3scene` format
 
 Scenes, prefabs and overlays are the same file type: YAML with a `.pix3scene` extension.
@@ -14,19 +14,16 @@ The engine's own statement of the format (principles, skinned UI controls, Spine
 
 ## Before you write
 
-- Re-read the file you are about to change — the human may have edited it in the editor.
-- Change only the lines you mean to change. A whole-file rewrite from memory drops what the
-  human (or the editor) wrote since you last read it.
-- If your tools support it, write to a temporary file and rename it over the target. Not
-  required for correctness — the editor waits for the file to stop changing — but cleaner.
-- Then `pix3 check` (see `pix3-verify`).
+Sync, re-read the file, change only the lines you mean to change, then `pix3 check` (`AGENTS.md`
+rules 2 and 4). If your tools support it, write to a temporary file and rename it over the
+target — not required (the editor waits for the file to stop changing), but cleaner.
 
 ## File
 
 ```yaml
 version: 1.0.0                 # the only format version; copy it
 metadata:                      # optional, free-form
-  author: Pix3 Recipe
+  author: Pix3
   description: Tapper gameplay — falling objects
 root:                          # list of root nodes; at least one
   - id: game-root
@@ -64,7 +61,7 @@ root:                          # list of root nodes; at least one
 Rules:
 
 - **`id`**: short, readable, kebab-case, unique (`combo-label`, `spawner-bonus`). Two nodes
-  with the same id fail the load. Never rename an id the recipe lists as stable — scripts
+  with the same id fail the load. Never rename an id other scripts use — scripts
   find nodes by id; rename `name` instead.
 - **`type`**: must be a real node type. An unknown or misspelled type does **not** fail the
   load — the node becomes an inert placeholder that draws and does nothing.
@@ -83,8 +80,8 @@ transform:
   rotation: 0           # DEGREES in YAML; positive = counter-clockwise (Y is up)
 ```
 
-2D space: origin at the centre of the screen/parent, **X right, Y up**. The recipes use a
-1080 x 1920 portrait design (top edge y = 960, bottom y = -960); other projects read
+2D space: origin at the centre of the screen/parent, **X right, Y up**. A portrait game uses e.g. a
+1080 x 1920 design (top edge y = 960, bottom y = -960); other projects read
 `viewportBaseSize` / `projectType` in `pix3project.yaml` — a `3d` project may have loose
 top-level 2D nodes (a HUD) and no 2D root at all, so position new HUD relative to the HUD
 nodes that are already there. Scripts see the rotation in
@@ -102,17 +99,28 @@ layout:
   enabled: true
   horizontalAlign: left      # left | center | right | stretch
   verticalAlign: top         # top | center | bottom | stretch
+  left: 40                   # margins, px from the parent's edge to the node's same edge:
+  top: 30                    # `left` keeps `left`, `right` keeps `right`, `stretch` keeps both
 ```
 
-The node keeps its authored distance to that edge of its parent when the parent resizes
-(a different screen aspect). `stretch` keeps both margins and resizes the node. Position is
-still authored in `transform.position`. HUD widgets anchor to screen edges; full-screen
-backgrounds and roots use `stretch` on both axes.
+An anchored axis is placed by its margin, and keeps it when the parent resizes (a different
+screen aspect, a container resized in the editor). On that axis the `transform.position`
+component is ignored — write `0` — and under `stretch` the node's `width` / `height` is derived
+from the two margins, so leave it out (a `Checkbox2D`'s `size` / `Joystick2D`'s `radius` too: its
+side is the stretched span). A centred axis has no margin: `position` places it, as
+for any node. A file with the anchors but **no margins** still loads: the margins are read off
+the rect, and the editor rewrites the node in the margin form the first time it saves the file.
+`pix3 tree <scene>` prints the margins and the rect they give at the design size —
+`pos=(-400,900) size=200x60 layout=left/top(left=40,top=30)` — so to move such a node, change
+its margin, not its `position`.
+HUD widgets anchor to screen edges; full-screen backgrounds and roots use `stretch` on both
+axes (a root's reference is `viewportBaseSize`, so a root keeps its full rect, no margins).
 
 **A new HUD node must not overlap the HUD that is already there.** Before you place it, read
 the `position`, `width`/`height` and anchoring of its siblings and pick a free spot (a combo
-label placed "top-right" once landed under the game's Shop button). With the live channel,
-confirm it with a `viewport_screenshot` while the game runs; without it, ask the human to look.
+label placed "top-right" once landed under the game's Shop button). With the editor open,
+confirm it with `pix3_screenshot` + `take_screenshot` while the game runs (`pix3-editor`);
+without it, ask the human to look.
 
 Flow (stack children in a row/column) is a separate block:
 `flow: { enabled: true, direction: vertical, gap: 16, paddingX: 0, paddingY: 0, align: start, autoSize: false }`.
@@ -126,7 +134,7 @@ are ignored — `pix3 validate` says so); on an **instance** node they are the o
 - **Colour**: a quoted hex string, `color: "#141a2e"`. Always quote — an unquoted `#` starts
   a YAML comment and the value becomes empty.
 - **Asset path**: `res://` + path from the project root (the folder with `pix3project.yaml`),
-  whatever the layout: `res://sprites/ph-target.png` in a recipe, `res://src/assets/textures/x.png`
+  whatever the layout: `res://sprites/ph-target.png` in a new project, `res://src/assets/textures/x.png`
   in a project that keeps assets under `src/`. Follow the folders the project already has; a
   new project from `pix3 new` uses one folder per type at the root (`sprites/`, `audio/`,
   `fonts/`, `models/`, `spine/`, `scripts/`, `scenes/`).
@@ -134,6 +142,9 @@ are ignored — `pix3 validate` says so); on an **instance** node they are the o
   `textureNormal`, `textureFill`, …). The saver always writes this form; a bare
   `texturePath: 'res://…'` string is only read for compatibility.
 - **Strings** with `:` `#` `{` or leading spaces: quote them (`label: "SCORE 0"`).
+- **Flipbook**: an `AnimatedSprite2D` points at a `.pix3anim` (`animationResourcePath`) — a JSON
+  file of named clips; its fields and defaults are in `pix3anim.md` beside this file. A character
+  with variants and states is compiled, not hand-written: `pix3 character-compile`.
 
 ### Shader effects (`Sprite2D`, `AnimatedSprite2D`, `Button2D` only)
 
@@ -143,7 +154,7 @@ effects:
     params: { color: "#7ee787", amount: 1 }
 ```
 
-`core:tint` multiplies a near-white placeholder PNG to the colour — this is how recipe
+`core:tint` multiplies a near-white placeholder PNG to the colour — this is how
 placeholders get their palette. Also `core:adjust`, `core:grayscale`, `core:flash`,
 `core:uv-scroll`, `core:dissolve`. Other 2D nodes do not read `effects` (a `ColorRect2D` takes
 its colour from `color`). On a `GeometryMesh` the stack lives at `material.effects`.
@@ -181,9 +192,10 @@ its colour from `color`). On a `GeometryMesh` the stack lives at `material.effec
   stays the instance's own id). `findByName('Result Overlay')` finds the instance above, not
   the name written in `result.pix3scene`; omit `name` to keep the prefab's.
 - Instance `properties` are applied to the prefab's root through its **schema names**:
-  `visible`, `opacity`, `width`, `layoutEnabled`, `horizontalAlign`, … plus a `transform` block
-  (`position`, `rotation`, `scale`). The `layout:` / `flow:` blocks of a plain node are not read
-  here — write `layoutEnabled: true` + `horizontalAlign: right` instead.
+  `visible`, `opacity`, `width`, `layoutEnabled`, `horizontalAlign`, the margins `layoutLeft` /
+  `layoutRight` / `layoutTop` / `layoutBottom`, … plus a `transform` block (`position`,
+  `rotation`, `scale`). The `layout:` / `flow:` blocks of a plain node are not read here — write
+  `layoutEnabled: true` + `horizontalAlign: right` + `layoutRight: 20` instead.
 - Do **not** add `components` or `children` to an instance node — they are ignored (the
   content comes from the prefab). To change what is inside, edit the prefab file itself, or
   override one inner node's properties:
@@ -199,9 +211,11 @@ its colour from `color`). On a `GeometryMesh` the stack lives at `material.effec
   them by id (`retry-button` inside `scenes/ui/result.pix3scene` is found as `retry-button`).
 - A prefab carries fixed defaults only (e.g. its `core:Hitbox2D` group). Tunables live on
   plain nodes in the host scene.
-- Where prefabs live: `scenes/prefabs/` (the recipes) or a top-level `prefabs/` — the export
+- Where prefabs live: `scenes/prefabs/` or a top-level `prefabs/` — the export
   treats both (and `scenes/ui/`) as prefabs, never as a boot scene.
 - Spawned at runtime with `await this.scene.instantiate('res://scenes/prefabs/x.pix3scene', { parent })`.
+- Turning a branch of a scene into a prefab (the editor has no "Save as Prefab"):
+  `project-files.md` → "Extract a branch into a prefab".
 
 ## Full-screen UI lives in `scenes/ui/`
 
@@ -215,23 +229,6 @@ scene with `properties: { visible: false }`. Two different flags, both needed:
 
 Never put a full-screen dimmer/panel inline in `main.pix3scene`.
 
-## Recipe tool names → file edits
-
-`design/recipe.md` was written for the in-editor agent. Without its tools:
-
-| recipe.md says | you do |
-| --- | --- |
-| tunable with `component: "user:X"` | edit `config.<property>` of the component with `type: user:X` on the node with that `id` |
-| tunable without `component` | edit `properties.<property>` on the node with that `id` (in the `transform` / `layout` / `flow` block where it belongs) |
-| `set_property` | edit `properties` in the YAML |
-| `set_component_property` | edit the component's `config` |
-| `create_node` / `add_component` | add the node / component entry to the YAML |
-| `fs_write` (+ `overwrite: true`) | write the file |
-| `play_start`, `game_input`, `game_observe`, `game_run` | the same tools over the live channel when it is connected (`pix3-verify`); otherwise `pix3 check`, then `pix3 smoke <the scene you changed>`, then ask the human to press Play and tell them what to look for |
-
-Values out of a tunable's `min`/`max` load as written (`pix3 validate` warns); the script's
-schema `setValue` may clamp them.
-
 ## Known gaps
 
 - `metadata.description` is free text; nothing reads it but humans.

package/kit/files/.claude/skills/pix3-scene-format/pix3anim.md

@@ -0,0 +1,185 @@
+<!-- Pix3 agent kit 2.0.0-alpha.0 — the .pix3anim format. Generated by pix3 kit; pix3 kit --update replaces it unless you edited it. -->
+# `.pix3anim` — flipbook animation resources
+
+A `.pix3anim` is **JSON**: a set of named clips, each a list of frames. `AnimatedSprite2D`
+plays one: `animationResourcePath: res://…/foo.pix3anim`, `currentClip`, `isPlaying`,
+`sizeMode`, `freeOnFinish` (the node's properties are in `pix3-nodes`; `AnimatedSprite3D` takes
+its own `frames` list instead). The loader
+reads the resource and every frame texture it names, also for a node that arrives through a
+prefab or `scene.instantiate`. **Every field may be omitted**: the loader fills in the default
+in the tables below, so hand-write only what you mean.
+
+Keep a flipbook in its own folder, the frames beside it — `sprites/<name>/<name>.pix3anim` +
+`sprites/<name>/<clip>_<nnnn>.png` (the editor's Sprite Editor writes and reads that layout and
+shows the folder as one item). Nothing enforces it: any `res://` path works.
+
+## Create one and bind it
+
+The editor does not create a `.pix3anim` (its inspector binds an existing one); you write it:
+
+1. Frames into one folder: `sprites/<name>/<clip>_0001.png`, `<clip>_0002.png`, … (or SVGs —
+   by the rules of AGENTS.md rule 5; `pix3 validate` checks the frames a `.pix3anim` names like
+   a scene's sprites: `E_SVG_*`, reported on the `.pix3anim`).
+2. `sprites/<name>/<name>.pix3anim`: `version`, `texturePath: ""` and one clip per animation,
+   each frame naming its image — the example under "Two modes" below; leave out every field
+   whose default (the tables) is what you want.
+3. Bind it on the `AnimatedSprite2D` node:
+
+   ```yaml
+   - id: coin-spin
+     type: AnimatedSprite2D
+     name: Coin Spin
+     properties:
+       width: 96
+       height: 96
+       animationResourcePath: res://sprites/coin/coin.pix3anim
+       currentClip: spin
+       isPlaying: true
+   ```
+
+   A script switches clips with `sprite.play('spin')`.
+4. `pix3 check`: a wrong `animationResourcePath` is `E_MISSING_RESOURCE`, a frame path that
+   points nowhere `E_MISSING_FRAME`, a file that is not JSON `E_ANIM_JSON`; then
+   `pix3 smoke <the scene>`.
+
+## Two modes
+
+- **Sequence** (one image per frame — the usual case): every frame sets `texturePath`; the
+  top-level `texturePath` stays `""`.
+- **Spritesheet**: the top-level `texturePath` is the sheet; each frame leaves its own
+  `texturePath` empty and sets the UV rect `offset` + `repeat` (fractions of the sheet). Both
+  default to `{ "x": 0, "y": 0 }`, which samples nothing — required in this mode.
+
+```json
+{
+  "version": "1.0.0",
+  "texturePath": "",
+  "clips": [
+    {
+      "name": "burst",
+      "fps": 30,
+      "loop": false,
+      "frames": [
+        { "texturePath": "res://sprites/burst/burst_0001.png" },
+        { "texturePath": "res://sprites/burst/burst_0002.png", "durationMultiplier": 2 }
+      ]
+    }
+  ]
+}
+```
+
+## The fields
+
+Types are the runtime's (`AnimationResource.ts`); "Omitted →" is what the loader fills in. A
+field marked `?` is optional in the file format itself.
+
+### `AnimationResource`
+
+The file.
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `version` | `string` | `"1.0.0"` | The only version; copy it |
+| `texturePath` | `string` | `""` | Spritesheet mode: `res://` of the sheet. Sequence mode: `""` |
+| `clips` | `AnimationClip[]` | `[]` | Clip names must be unique — scripts address clips by name |
+
+### `AnimationClip`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `name` | `string` | `clip-<n>` (1-based position) | What `currentClip` and `sprite.play(name)` use |
+| `frames` | `AnimationFrame[]` | `[]` | In play order |
+| `fps` | `number` | `12` | Frames per second; positive |
+| `loop` | `boolean` | `true` | `false`: holds the last frame, `isPlaying` turns false, the node emits `animation-finished` (`freeOnFinish: true` then removes it) |
+| `playbackMode` | `AnimationPlaybackMode` | `"normal"` | `"normal"` or `"ping-pong"` |
+
+### `AnimationFrame`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `textureIndex` | `number` | `0` | Legacy; leave it 0 |
+| `offset` | `AnimationVector2` | `{"x":0,"y":0}` | Spritesheet mode: UV origin of the frame in the sheet |
+| `repeat` | `AnimationVector2` | `{"x":0,"y":0}` | Spritesheet mode: UV size of the frame in the sheet |
+| `durationMultiplier` | `number` | `1` | This frame lasts `durationMultiplier / fps` seconds |
+| `anchor` | `AnimationVector2` | `{"x":0.5,"y":0.5}` | The point of the frame (0–1, **y from the top**) that lands on the node's position — the feet for a character |
+| `texturePath` | `string` | `""` | Sequence mode: `res://` of this frame's image |
+| `boundingBox` | `AnimationBoundingBox` | `{"x":0,"y":0,"width":0,"height":0}` | Frame rect in source pixels |
+| `collisionPolygon` | `AnimationPolygonPoint[]` | `[]` | Optional outline in frame space |
+| `events?` | `AnimationFrameEvent[]` | `[]` | Signals the node emits when play enters this frame |
+| `sourceSize?` | `AnimationSize` | the `boundingBox` size | Pixel size of the frame image; `sizeMode: native` lays the node out from it (`0×0` = unknown → stretch) |
+| `points?` | `AnimationFramePoint[]` | `[]` | Named sockets (a muzzle, a hand) that move across frames; `core:PointAttachment` parks a child on one |
+
+### `AnimationVector2`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `x` | `number` | — | |
+| `y` | `number` | — | |
+
+### `AnimationBoundingBox`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `x` | `number` | — | From the frame's left edge, pixels |
+| `y` | `number` | — | From the frame's top edge, pixels |
+| `width` | `number` | — | |
+| `height` | `number` | — | |
+
+### `AnimationPolygonPoint`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `x` | `number` | — | |
+| `y` | `number` | — | |
+
+### `AnimationFrameEvent`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `signal` | `string` | — | Emitted on the node; an empty signal drops the event |
+| `args` | `string` | — | Raw text, parsed when it fires (same convention as the keyframe event track) |
+
+### `AnimationSize`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `width` | `number` | — | |
+| `height` | `number` | — | |
+
+### `AnimationFramePoint`
+
+| Field | Type | Omitted → | Notes |
+| --- | --- | --- | --- |
+| `name` | `string` | — | Unique within the frame (the first wins) |
+| `x` | `number` | — | 0–1 of the frame width |
+| `y` | `number` | — | 0–1 of the frame height, from the top |
+| `angle?` | `number` | — | Degrees, clockwise, 0 = pointing right |
+
+`AnimationPlaybackMode` is `"normal" | "ping-pong"`.
+
+## A character with variants and states
+
+One `.pix3anim` whose clips are named `<variant>.<state>` (`sword.idle`, `sword.attack`,
+`bow.idle`; a clip without the dot is a variant-less state such as `die`), an `AnimatedSprite2D`
+prefab root with `sizeMode: native`, and `core:CharacterVisual2D` on it (`variant`, `state`).
+Game code calls `playState('attack', { restart: true })` and `setVariant('bow')` and never spells
+a clip name. Do not write it by hand — compile it from the frame images:
+
+```bash
+pix3 character-compile art/goblin.yaml --dry-run   # the plan
+pix3 character-compile art/goblin.yaml             # sprites/goblin/…, scenes/prefabs/Goblin.pix3scene
+```
+
+```yaml
+# art/goblin.yaml — frame paths are relative to this file; frames must be PNG
+name: Goblin
+anchor: { x: 0.5, y: 0.9 }   # the feet
+clips:
+  - { variant: sword, state: idle, fps: 10, frames: [sword/idle_1.png, sword/idle_2.png] }
+  - { variant: sword, state: attack, fps: 15, sequence: sword/attack }  # sword/attack_<n>.png
+  - { state: die, sequence: die/die }
+```
+
+It refuses to overwrite a file with other content (`--force` to replace) and prints the defaults
+it chose (fps 12, one-shot `attack`/`die`/`hit`) as warnings. Then instance the prefab
+(`instance: res://scenes/prefabs/Goblin.pix3scene`) and run `pix3 check`.

package/kit/files/.claude/skills/pix3-scene-format/project-files.md

@@ -0,0 +1,244 @@
+<!-- Pix3 agent kit 2.0.0-alpha.0 — project files the editor leaves to you. Generated by pix3 kit; pix3 kit --update replaces it unless you edited it. -->
+# Project files the editor leaves to you
+
+The Pix3 editor edits a project that is already open: nodes, properties, what is inside a
+prefab, the clips of a `.pix3anim`, the entries of a locale table. It **never creates, renames,
+moves or deletes a file, never edits `pix3project.yaml` and never builds**. When the human asks
+for one of those, you do it — by writing files and running the CLI. The editor follows the disk
+on its own. After every recipe: `pix3 check`, then (editor open) `pix3_sync` with `expect` =
+the sha256 of every file you wrote, or (no editor) `pix3 smoke <the scene>`.
+
+| The human asks for | Recipe |
+| --- | --- |
+| a new scene, a copy of a scene ("Save As") | [New scene](#new-scene) |
+| a folder | create it; the asset panel shows it |
+| a script | `export class X extends Script` in `scripts/X.ts` — `pix3-scripts` |
+| an asset renamed, moved or deleted | [Rename, move, delete](#rename-move-delete) |
+| a branch of a scene turned into a prefab ("Save Branch as Prefab") | [Extract a branch into a prefab](#extract-a-branch-into-a-prefab) |
+| a flipbook for an `AnimatedSprite2D` | `pix3anim.md` → "Create one and bind it" |
+| a language added or removed | [Add or remove a locale](#add-or-remove-a-locale) |
+| project settings (resolution, entry scene, quality, fonts …) | [`pix3project.yaml`](#pix3projectyaml) |
+| a build, an export | `npm run build` → `dist/` — [Build options](#build-options) |
+| an image | write an SVG (AGENTS.md rule 5), or the human generates one in the editor's Generate panel and saves it into the project |
+
+## New scene
+
+1. Copy the entry scene (`defaultExportScenePath` in `pix3project.yaml`) to
+   `scenes/<name>.pix3scene` — it carries the root sized from `viewportBaseSize`. Keep the root
+   and what every screen has (a background), drop the root's `components` and the children that
+   are the other scene's game, and update `metadata.description` and the header comment. Ids
+   only have to be unique **within** a scene, so a copy keeps them.
+2. A scene under `scenes/` that is not under `scenes/prefabs/`, `prefabs/` or `scenes/ui/` is a
+   playable scene: reach it with `await this.scene.changeScene('res://scenes/<name>.pix3scene')`.
+   To make the game boot into it, set `defaultExportScenePath: scenes/<name>.pix3scene` — and
+   give it a way on (a menu's button script calls `changeScene` to the game).
+3. Under `scenes/prefabs/`, `prefabs/` or `scenes/ui/` the file is a prefab or an overlay: it is
+   instanced, never booted.
+
+## Rename, move, delete
+
+Everything refers to files by path, and nothing rewrites those paths for you.
+
+1. Find every reference first, in every text file of the project (not `node_modules/`,
+   `.pix3/`, `dist/`, `.git/`, and not the kit's own docs in `.claude/`):
+   `grep -rn "sprites/coin.png" --exclude-dir={node_modules,.pix3,dist,.git,.claude} .` — for
+   a folder, search it with its trailing slash (`sprites/coin/`), which `sprites/coins/` does
+   not match.
+   — scenes and prefabs (`res://…`), `.pix3anim` frame paths, `locales/*.json` `sprites`,
+   scripts, and `pix3project.yaml` (which writes paths **without** `res://`:
+   `defaultExportScenePath`, `fonts[].path`). Search the folder name too: a path a script builds
+   at runtime (`` `res://levels/${n}.pix3scene` ``) has no literal to find.
+2. Move the file (`git mv` when git tracks it, else `mv`) and rewrite every reference; a folder
+   move rewrites the prefix. A flipbook folder keeps its `<name>/<name>.pix3anim` pairing:
+   renaming `sprites/coin/` to `sprites/coins/` renames `coin.pix3anim` to `coins.pix3anim` too.
+   To delete, first remove or replace the references, then the file.
+3. `pix3 check` names a reference that still points nowhere: a scene's (`E_MISSING_RESOURCE`,
+   `E_MISSING_PREFAB`), a `.pix3anim` frame (`E_MISSING_FRAME`) and a locale table's `sprites`
+   image (`E_MISSING_LOCALE_SPRITE`); `pix3 smoke` on a scene reports a missing file only when
+   it loads, as the **warning** `W_SMOKE_MISSING_RESOURCE` (exit 0).
+
+A script's file name is free to change: `type: user:Mover` names the exported class. Renaming
+the class means rewriting every `type: user:Mover` and every `import`.
+
+## Extract a branch into a prefab
+
+The branch: a node of the host scene with everything under it, e.g. in `scenes/main.pix3scene`
+
+```yaml
+      - id: coin-hud
+        type: Group2D
+        name: Coin HUD
+        properties:
+          width: 260
+          height: 80
+          transform: { position: [0, 0], scale: [1, 1], rotation: 0 }
+          layout: { enabled: true, horizontalAlign: left, verticalAlign: top, left: 60, top: 40 }
+        children:
+          - id: coin-icon
+            type: ColorRect2D
+            name: Coin Icon
+            properties: { width: 64, height: 64, color: "#f5c542", transform: { position: [-80, 0] } }
+          - id: coin-count
+            type: Label2D
+            name: Coin Count
+            properties: { label: "0", labelFontSize: 48, transform: { position: [40, 0] } }
+```
+
+1. Sync and re-read the host scene (AGENTS.md rule 2).
+2. Write `scenes/prefabs/CoinHud.pix3scene`: `version: 1.0.0` and a `root:` with **exactly one**
+   node — the branch root, cut with everything under it (`properties`, `components`, `groups`,
+   `children`) and indented back to the top level.
+3. The prefab root keeps its size but not its placement: set its `transform` to
+   `{ position: [0, 0], scale: [1, 1], rotation: 0 }` and drop its `layout:` block. Where it
+   sits is the instance's business (step 5).
+4. Ids. Keep the branch's ids — the prefab root's `id` as it was, the inner ones unique in the
+   file. In the host scene the instance node's id becomes the root's id, and every inner node
+   keeps its prefab id **when that id is free in the host scene**; otherwise the loader renames
+   it `<id>-1`, `<id>-2`, … — which is what happens to the second instance of the same prefab.
+   So a lookup by id (`findNode('coin-count')`) finds the first instance's node only; to reach
+   an inner node of each instance, go through the instance — a second copy is one more instance
+   node with an id and name you choose (`coin-hud-2`, "Coin HUD 2"), its inner `coin-count`
+   becomes `coin-count-1`: `this.findNode('coin-hud-2')?.findByName('Coin Count')` (names never
+   change; the renamed id is its `nodeId`). A `node` property of a component inside the prefab that names another
+   node of the prefab is re-pointed per instance by the loader.
+5. Replace the branch in the host scene, at the same place in `children` (tree order is paint
+   order), with one instance node: the branch root's `id` (scripts that find it keep finding
+   it) and `name`, `instance: res://scenes/prefabs/CoinHud.pix3scene`, and `properties` with the
+   root's `transform` and its anchoring in the **flat** names an instance reads —
+   `layoutEnabled`, `horizontalAlign`, `verticalAlign` and the margins `layoutLeft` /
+   `layoutRight` / `layoutTop` / `layoutBottom` (scene-format "Prefab instance"). No `type`,
+   no `components`, no `children`:
+
+   ```yaml
+      - id: coin-hud
+        name: Coin HUD
+        instance: res://scenes/prefabs/CoinHud.pix3scene
+        properties:
+          transform: { position: [0, 0] }
+          layoutEnabled: true
+          horizontalAlign: left
+          verticalAlign: top
+          layoutLeft: 60
+          layoutTop: 40
+   ```
+
+6. A value that differed per copy goes into the instance: on the root as above, on an inner
+   node in `overrides.byLocalId` (`coin-count: { properties: { label: "10" } }`, keyed by the
+   prefab's ids). These are node **properties** and the values a copy starts with: a script
+   inside the prefab that sets the same property in `onStart` wins, and a component's `config`
+   cannot differ per copy (no component overrides) — make the script read the node property,
+   or keep the tunable on a plain node of the host scene. Components start parent first, so a
+   host script's `onStart` sees an inner node before the prefab's own scripts touched it. A
+   label with a `labelKey` shows that key's text, whatever `label` says: per copy, override the
+   `labelKey` (one key per copy) instead.
+7. `pix3 check` — `E_PREFAB_ROOT` (not one root), `E_DUPLICATE_ID`, `E_MISSING_PREFAB`,
+   `E_UNKNOWN_OVERRIDE_TARGET` name the slips — then sync with `expect` of both files and look
+   at it running.
+
+## Add or remove a locale
+
+A locale is a table `locales/<id>.json` at the project root — `strings` (key → text, `{name}`
+placeholders) and `sprites` (key → `res://` image for art with baked-in text). Nodes and
+scripts name **keys** (`labelKey` on a UI control, `textureKey` on a `Sprite2D`,
+`this.scene.localization.tr('menu.play')`), never a locale.
+
+```json
+{
+  "$meta": { "locale": "de", "name": "Deutsch" },
+  "strings": { "menu.play": "Spielen" },
+  "sprites": {}
+}
+```
+
+Add one:
+
+0. No table yet: write the default one first — `locales/en.json` with the keys the game uses
+   (`labelKey` on the nodes; keep `label` as well, it is what shows while there is no table) —
+   and declare it alone (`locales: [en]`, step 2).
+1. Copy the default locale's table to `locales/<id>.json`, set `$meta.locale` and `$meta.name`
+   (`"direction": "rtl"` for a right-to-left language) and translate the values. Keep every key;
+   one you cannot translate yet stays `""` and falls back to the fallback locale, then to the key.
+2. Declare it in `pix3project.yaml`, creating the block if there is none:
+
+   ```yaml
+   localization:
+     defaultLocale: en
+     locales: [en, de]
+   ```
+
+   Without a block every `locales/*.json` is a locale (`en` the default when there is one);
+   with it, only the tables it names count — the build ships those and no other.
+
+Remove one:
+
+1. Never the `defaultLocale` or the `fallbackLocale` — point those at another locale first.
+2. Drop the id from `localization.locales`, delete `locales/<id>.json`, and grep the scripts for
+   the id (`setLocale('de')`). An image only that table's `sprites` used is now unreferenced
+   (`pix3 check` lists those under `sprites/` as `W_UNUSED_ASSET`).
+
+`pix3 check` checks the tables: a declared locale without its file (`E_LOCALE_MISSING` for the
+default or fallback locale, `W_LOCALE_MISSING` for another), a table that is not JSON
+(`E_`/`W_LOCALE_JSON`), a value that is not a string (`E_`/`W_LOCALE_VALUE` — keys are flat,
+`"menu.play"`, never nested), a `sprites` image that does not exist (`E_MISSING_LOCALE_SPRITE`),
+a `labelKey` the default locale has no text for (`E_LOCALE_KEY`: the node would show the key
+itself), a key a script passes as a literal — `tr('menu.play')`, `setTextKey('…')`,
+`trPlural('…')` — with no text (`E_LOCALE_SCRIPT_KEY`), and a `textureKey` /
+`stateTextureKeys` / `trSprite('…')` key with no `sprites` entry (`E_`/`W_LOCALE_SPRITE_KEY`).
+A key the script builds at run time (`` tr(`shop.${id}`) ``, `tr(key)`) is not checked — read
+those back yourself (or look at the running game).
+
+In a script, `this.scene.localization`: `tr(key, { name: value })` (fills `{name}`),
+`trPlural(key, count)`, `trSprite(key)`, `has(key)`, `locale`, `locales`, `setLocale(id)`,
+`onChange(fn)`; a node shows `tr(node.labelKey)` when it has a key.
+
+## `pix3project.yaml`
+
+The manifest. Change a key only when the human asks for that setting (or a recipe above says
+so), keep every key you do not know, and copy the style of the file.
+
+| Key | What |
+| --- | --- |
+| `version` | `1.0.0`; leave it |
+| `defaultExportScenePath` | the scene the game boots into (no `res://`) |
+| `viewportBaseSize` | `{ width, height }` — the design resolution 2D layout is authored against |
+| `projectType` | `2d` or `3d` |
+| `targetPlatform` | `mobile`, `desktop` or `universal` |
+| `textureFiltering` | `linear` (smooth) or `nearest` (pixel art) for 2D textures |
+| `ambientOcclusion` | `off`, `baked`, `realtime` or `adaptive` — the project default |
+| `quality` | `{ antialias, shadows, maxPixelRatio }` |
+| `localization` | `{ defaultLocale, fallbackLocale?, locales }` — above |
+| `fonts` | `[{ family, path, weight, style, unicodeRange? }]` — font files registered before the first frame; `path` without `res://` |
+| `autoloads` | `[{ singleton, scriptPath, enabled }]` — game-wide script singletons that survive `changeScene` (recipe below); `[]` when there are none |
+| `metadata` | the editor's and `pix3 kit`'s bookkeeping (`projectId`, `agentKit`) — do not edit |
+
+### An autoload (state or a service for the whole game)
+
+State that must outlive a scene change (score across levels, settings, a music player) is an
+autoload: one script instance per game session, built before the first scene starts, kept
+across every `changeScene`, the same in the editor's play, `npm run dev` and the build.
+
+1. `scripts/GameState.ts`: `export class GameState extends Script { … }` — the class is named
+   like the file (that is how the autoload finds it).
+2. In `pix3project.yaml`:
+   ```yaml
+   autoloads:
+     - singleton: GameState
+       scriptPath: scripts/GameState.ts
+   ```
+3. Any script: `const state = this.scene.getAutoload(GameState)` (import the class) or
+   `this.scene.getAutoload<GameState>('GameState')`; null when it is not declared.
+
+It runs `onStart`/`onUpdate` like a scene script, before the scene's every frame, and has no
+node in any scene (it draws nothing; give the visuals to a scene). Commands it registers with
+`scene.commands` belong to the scene and go with it. `pix3 check` reports an autoload that does
+not resolve (`E_AUTOLOAD`).
+
+## Build options
+
+`npm run build` writes `dist/index.html` (one self-contained file) and
+`dist/<name>.report.json` (what it weighs and why). How it builds is `pix3()` in
+`vite.config.ts`, not the manifest: `pix3({ build: 'zip' })` (a zip to host instead of one
+file), `pix3({ compress: true })` (gzip inside the page, about two thirds smaller),
+`pix3({ entryScene: 'scenes/level-1.pix3scene' })` (boot another scene than
+`defaultExportScenePath`), `pix3({ strip: { keep: [...] } })` (when the build says a library
+needs runtime classes it cannot see).