@pix3/cli 1.6.0 → 1.6.3

package/kit/files/.claude/skills/pix3-scripts/reference.md

@@ -1,15 +1,15 @@
-<!-- Pix3 agent kit 1.6.0 — generated from docs/nodes-and-systems.md, src/services/agent/agent-skills/engine-api-map.md and the runtime's component registry. Do not edit: pix3 kit --update regenerates it. -->
-# Script API reference
-
-Generated from the engine's own documentation and code. Grep a heading instead of reading it
-whole. Tool names the in-editor agent uses appear in places: `add_component` /
-`set_component_property` = edit the scene YAML's `components:`; `list_component_types` = the
-"`core:` components" section at the end of this file; `engine_search` / `engine_read` do not
-exist for you — the runtime's declarations are in `.pix3/types/@pix3/runtime/` (or in
-`node_modules/@pix3/runtime` when the project has its own `tsconfig.json`). Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine repository, not of this project.
-
-## The surface a `Script` sees
-
+<!-- Pix3 agent kit 1.6.3 — generated from docs/nodes-and-systems.md, src/services/agent/agent-skills/engine-api-map.md and the runtime's component registry. Do not edit: pix3 kit --update regenerates it. -->
+# Script API reference
+
+Generated from the engine's own documentation and code. Grep a heading instead of reading it
+whole. Tool names the in-editor agent uses appear in places: `add_component` /
+`set_component_property` = edit the scene YAML's `components:`; `list_component_types` = the
+"`core:` components" section at the end of this file; `engine_search` / `engine_read` do not
+exist for you — the runtime's declarations are in `.pix3/types/@pix3/runtime/` (or in
+`node_modules/@pix3/runtime` when the project has its own `tsconfig.json`). Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine repository, not of this project.
+
+## The surface a `Script` sees
+
 Inside any `Script` subclass:
 
 - `this.node` — the owning `NodeBase` (transform, `visible`, `getComponent`, `addComponent`, `connect`/`emit`, `findById`/`findByName`/`findByPath`, `children`, `parentNode`). `getComponent<T>(type: new (...args) => T): T | null` takes the component **class**, not a string ID — `node.getComponent(CarController)`, importing the class by relative path (`./CarController`). There is no string-based lookup (`getComponent('user:CarController')` fails); `user:*` IDs are for `add_component`/scene YAML only. To fetch by hand: `node.components.find(c => c instanceof CarController)`.
@@ -49,12 +49,12 @@ cached texture (the runtime crops a private clone that shares the GPU image), so
 you never clone textures yourself. Author the region once and drive it from
 **both** `onUpdate` (play) and `tickEditorPreview` (edit) so the two modes match. A
 throwing `tickEditorPreview` disables the component and surfaces the error like a
-play-mode hook, so the editor keeps running.
-
-## Engine API map
-
-### A `Script`
-
+play-mode hook, so the editor keeps running.
+
+## Engine API map
+
+### A `Script`
+
 - Lifecycle: `onAttach(node)` → `onStart()` (first frame) → `onUpdate(dt)` (scaled seconds;
   frozen by hitstop) → `onDetach()`. Defaults in the constructor's `this.config = {…}`;
   `static getPropertySchema()` exposes them to the inspector / `set_component_property`.
@@ -62,10 +62,10 @@ play-mode hook, so the editor keeps running.
   editor previews), `this.input` (`InputService`), `this.findNode(q)` (id / name / path →
   node or null), `this.getNode(q)` (throws when missing).
 - Reach another script: `import { Other } from './Other'; this.node.getComponent(Other)` —
-  the class, never the `user:Other` string.
-
-### Nodes
-
+  the class, never the `user:Other` string.
+
+### Nodes
+
 - Transform is three.js and **read-only by reference**: `node.position.set(x, y, 0)`,
   `node.position.x += dx`, `node.rotation.z = radians`, `node.scale.set(s, s, 1)`. Never
   assign `node.position = …`.
@@ -99,10 +99,10 @@ play-mode hook, so the editor keeps running.
   `Hemisphere`, `Directional`, `Point`, `Spot`), `PostProcess` (bloom / vignette /
   chromatic aberration; `affect2D: true` for 2D scenes), `AudioPlayer`.
 - Shader effects on a 2D node: `effects: [{ type: 'core:tint', params: { color, amount } }]`
-  (also `core:adjust`, `core:grayscale`) — the way a near-white placeholder takes a colour.
-
-### `this.scene`
-
+  (also `core:adjust`, `core:grayscale`) — the way a near-white placeholder takes a colour.
+
+### `this.scene`
+
 - Lookup: `findNode(q)`, `findNodeById`, `findNodeByName`, `findNodeByPath`, `getRootNodes()`,
   `getActiveCamera()`, `getActiveCamera2D()`, `getViewportInfo()`, `isPortrait()`.
 - **Pointer in 2D world space:** `scene.getPointer2DWorldPosition()` → `Vector2 | null`
@@ -171,12 +171,15 @@ play-mode hook, so the editor keeps running.
 - Cutscenes: `scene.cutscene.playCinematic(id, {…})`; camera blends via `core:CameraBrain`
   + `VirtualCamera3D`.
 - Multiplayer: `scene.network`, `scene.netNodes`, `core:NetworkedNode`,
-  `core:ReplicatedTransform` (only when the brief says multiplayer).
-
-### `this.input`
-
+  `core:ReplicatedTransform` (only when the brief says multiplayer).
+
+### `this.input`
+
 - Per frame: `input.pointerEvents` → `{ type: 'down' | 'move' | 'up' | 'cancel', pointerId,
-  x, y }[]` (`cancel` is never a completed tap); `input.keyEvents`; `input.wheelDelta`.
+  x, y }[]` (`cancel` is never a completed tap); `input.keyEvents`; `input.wheelDelta` (plain
+  scroll wheel only); `input.wheelZoomDelta` (Ctrl/⌘ + wheel and trackpad pinch — use it for
+  camera zoom, it is excluded from `wheelDelta`); `input.wheelModifiers` (`{ ctrl, meta, shift,
+  alt }`). The canvas already `preventDefault()`s every wheel event, so ctrl-wheel never zooms the page.
 - Polled: `input.isPointerDown` (any finger), `input.pointerPosition` (primary finger,
   canvas space — convert with `scene.getPointer2DWorldPosition()`), `input.getActivePointers()`,
   `input.getPointer(id)`, `input.pointerDownCount`, `input.isPointerOverUI(pointerId)` (gate
@@ -185,19 +188,19 @@ play-mode hook, so the editor keeps running.
 - Keyboard: compare `event.code` (`'KeyW'`, `'ArrowUp'`), case-sensitive.
 - A tap-to-place mechanic is: on a `'down'` event, `scene.getPointer2DWorldPosition(ev.pointerId)`,
   convert to the board's local space (`board.worldToLocal` or subtract the board's world
-  position), place the node, `scene.juice.burst({ x, y })`, `scene.audio.sfx('tap')`.
-
-### Traps
-
+  position), place the node, `scene.juice.burst({ x, y })`, `scene.audio.sfx('tap')`.
+
+### Traps
+
 - Assigning `position` / `rotation` / `scale` throws — mutate them.
 - A component that throws in `onStart` / `onUpdate` is auto-disabled and the game keeps
   running — `read_errors` after `play_start` is the only way to see it.
 - `this.node as any` disables exactly the check that would have caught the above.
 - Hitstop every frame while an overlap lasts freezes the contact forever — edge-trigger it.
-- A hidden `UIControl2D` takes no input; `tick` still runs on hidden nodes.
-
-## Capability catalog — nodes
-
+- A hidden `UIControl2D` takes no input; `tick` still runs on hidden nodes.
+
+## Capability catalog — nodes
+
 Add via the editor **Create** menu / `Create*Command`, or author in `.pix3scene`
 YAML, or (from a script) construct + `parent.adoptChild(child)`. Full property
 tables: node-types-reference.md.
@@ -215,7 +218,7 @@ tables: node-types-reference.md.
   **Skins:** these controls are colour-driven by default and take sprites through texture slots — `Button2D` `textureNormal/Hover/Pressed/Disabled`, `Checkbox2D` `textureBox` / `textureBoxChecked` / `textureMark`, `Slider2D` `textureTrack` / `textureFill` / `textureThumb`, `Bar2D` `textureTrough` / `textureFill`, plus `ScrollContainer2D`'s thumb/track. A set slot replaces that flat colour; an unset one keeps it. `Button2D`, `Slider2D` (track+fill) and `Bar2D` (trough+fill) also take the four `sliceBorder*` nine-slice insets `TiledSprite2D` uses, so one 64x64 skin fits any size instead of smearing — and a fill that shrinks with `value` is re-cut, not squashed. A sliced skin opts out of the 2D quad batcher.
   `Label2D` is multiline: a fixed `width` word-wraps, `labelAlign`/`labelVAlign` align inside the box, and `typewriterSpeed` + `setText()`/`skipTypewriter()`/`'typewriter-complete'` give a per-character reveal.
 - `Camera2D` — pan/zoom/limits/shake for the 2D pass. `CanvasLayer2D` — fixed HUD layer, unaffected by Camera2D.
-- `AnimatedSprite2D` (and `AnimatedSprite3D`) play a flipbook from a **`.pix3anim`** resource — see the recipe below. A non-looping clip emits **`animation-finished`** (clip name as arg) when it stops on the last frame. For self-freeing one-shot VFX set **`freeOnFinish: true`** on the node (destroys itself when the clip ends — no component); use `core:FreeOnSignal` only when the trigger is some _other_ signal.
+- `AnimatedSprite2D` (and `AnimatedSprite3D`) play a flipbook from a **`.pix3anim`** resource — see the recipe below. Switch clips from a script with **`sprite.play('attack', { restart: true })`** (returns `false` for an unknown clip; `restart` replays the current clip from frame 0, which is how a finished one-shot is fired again — writing `currentClip` alone never restarts). A non-looping clip emits **`animation-finished`** (clip name as arg) when it stops on the last frame. For self-freeing one-shot VFX set **`freeOnFinish: true`** on the node (destroys itself when the clip ends — no component); use `core:FreeOnSignal` only when the trigger is some _other_ signal.
 
 **Flipbook animation (`.pix3anim`)** — hand-author it; the file is plain JSON and `SceneLoader` auto-loads the resource + every frame texture (also when the node arrives via `scene.instantiate` of a prefab). Every omitted field is defaulted on load (fps 12, loop true, `playbackMode` normal, anchor 0.5/0.5, `durationMultiplier` 1). Save it next to the frames, point the node at it. **Sequence mode** (one image per frame — the common case, e.g. an impact flash):
 
@@ -238,6 +241,8 @@ tables: node-types-reference.md.
 }
 ```
 
+**Character with variants/states (weapon skins, outfits)** — one `.pix3anim` whose clips are named `<variant>.<state>` (`sword.idle`, `sword.attack`, `bow.idle`, …; a clip without the separator is a variant-less state such as `die`), an `AnimatedSprite2D` as the prefab root (`sizeMode: native` — every frame carries `sourceSize`; the frame `anchor` at the feet, so the node's position is where the character stands) and **`core:CharacterVisual2D`** on that same node (`variant`, `state`, `separator`, optional `spriteNodeId`; empty = the host itself, else its first `AnimatedSprite2D` child). Keep the sprite as the root: selecting the character then selects the drawn quad, and the viewport frames the visible art and marks the pivot at the node position — a `Group2D` wrapper frames a centred box that the frame anchor pushes off the art. Game code says `character.playState('attack', { restart: true })` and `character.setVariant('bow')` (keeps the state, restarts its clip) and never spells a clip name; both return `false` for a pair the resource lacks, no hidden fallback. A finished one-shot holds its last frame and the root emits **`state-finished`** `(state, variant)` — the component adds no movement, physics, AI or automatic transitions. `getVariants()` / `getStates(variant?)` read the vocabulary off the clip names. This is Unity's Sprite Library categories/labels + Sprite Resolver, not an AnimationTree. `compileCharacter` (`src/services/library/character-compiler.ts`) emits exactly this shape from grouped frame files — the Store's `character2d` asset kind — as a managed sprite folder (`sprites/<slug>/<slug>.pix3anim` + `<variant>_<state>_<nnnn>.png`) plus `prefabs/<Name>.pix3scene`; pass `anchor` (y from the top) at the feet row so the node's position is where the character stands — the default is the canvas centre.
+
 **Spritesheet mode** instead: set top-level `texturePath` and give each frame a UV rect `offset:{x,y}` + `repeat:{x,y}` (these default to 0 → sample nothing, so they're required here). Frames may carry `durationMultiplier` and `events:[{signal,args}]` (fired on play-driven frame entry). Node wiring: `type: AnimatedSprite2D`, properties `animationResourcePath`, `currentClip`, `isPlaying`, `freeOnFinish` (one-shot self-destruct), `width`/`height`, `anchor`, `sizeMode`. First spawn of a runtime-instantiated clip warms its texture cache; if the first play must be pixel-perfect, spawn one invisible warm-up at level start. Authoring GUI: the editor's **Sprite Editor** produces the same file — one shell (canvas + clips rail + frame timeline) that edits both a bare image and a `.pix3anim`; selecting a frame binds the canvas to that frame's texture, and crop / rotate / flip / background-removal / generation write straight back into the frame.
 
 **Frame presentation — `sizeMode`, per-frame `anchor`, `sourceSize`.** Two anchors are in play and they mean different things. The **node** `anchor` is a global pivot in the node's `width × height` box (y up, same as `Sprite2D.anchor`). Each **frame's** `anchor` is that frame's own origin inside its — possibly tightly cropped — raster, normalized with **y measured from the top** (image convention, like `boundingBox`). They compose: the quad is placed so the frame anchor lands on the node's position, then shifted by the node pivot. That is what makes cropping pay off — crop a frame tighter, move its anchor to the old visual centre, and the animation is pixel-identical while the PNG (and the atlas) shrinks. `sizeMode` decides how a frame fills the box: `'stretch'` (default, and what every pre-existing scene assumes) scales every frame to exactly `width × height`; `'native'` renders each frame at its own `sourceSize` scaled by one per-clip factor derived from the clip's FIRST frame, so mixed-size frames keep their relative proportions and resizing the node scales the whole animation uniformly (the editor sets `'native'` on newly created nodes). `sourceSize` is an optional per-frame `{width,height}` the editor stamps whenever a frame is added, imported or sliced, so native layout never waits on a texture load; a frame with no known size falls back to stretch, so legacy files keep working. The math lives in one shared module (`core/animated-sprite-layout.ts`) because the editor viewport draws SEPARATE proxy meshes — both apply the same resolver.
@@ -290,10 +295,10 @@ cost is per skeleton per frame, so budget dozens, not hundreds. Full property ta
 **Other**
 
 - `AudioPlayer` — a scene-graph audio source (§4 Audio).
-- `PostProcess` — enables the post-processing pipeline (§4 Post-processing).
-
-## Capability catalog — `core:*` behaviours
-
+- `PostProcess` — enables the post-processing pipeline (§4 Post-processing).
+
+## Capability catalog — `core:*` behaviours
+
 Attach in the inspector or in YAML `components:`. These are the pre-built,
 designer-facing behaviors — prefer them over writing a script for the same
 effect. Registered in
@@ -310,6 +315,7 @@ packages/pix3-runtime/src/behaviors/register-behaviors.ts.
 | `core:RadialProgress`      | Circular progress mask on a Sprite2D                                                                                                        |
 | `core:AnimationPlayer`     | Play keyframe clips on this node + descendants (§4)                                                                                         |
 | `core:PointAttachment`     | Keep this node on a named frame point of a parent `AnimatedSprite2D` (hand socket, muzzle) every tick, optionally copying the point's angle |
+| `core:CharacterVisual2D`   | `variant + state → clip` on an `AnimatedSprite2D` with clips named `<variant>.<state>`; `playState`/`setVariant`, `state-finished`          |
 | `core:PlaySound`           | Play a sound when a node signal fires                                                                                                       |
 | `core:SfxOnSignal`         | Play a **procedural** (asset-free) sound preset when a node signal fires — see §4 "Procedural SFX"                                          |
 | `core:BurstOnSignal`       | Spawn a one-shot 2D particle burst at this node when a signal fires (juice)                                                                 |
@@ -335,13 +341,13 @@ so a keyframe **event track** or a script `emit()` can fire them.
 (3D-only), `core:uv-scroll`, `core:flash`, `core:adjust`
 (brightness/contrast/saturation), `core:grayscale`, `core:tint`. Params are
 keyframe-animatable. See
-packages/pix3-runtime/src/shader-effects/.
-
-## `core:` components — every config key
-
-Read from the runtime's component registry for this CLI's version: the keys a `config:` block
-may carry, their type, the default a fresh component has, and the inspector's range/options.
-
+packages/pix3-runtime/src/shader-effects/.
+
+## `core:` components — every config key
+
+Read from the runtime's component registry for this CLI's version: the keys a `config:` block
+may carry, their type, the default a fresh component has, and the inspector's range/options.
+
 ### `core:AnimationPlayer`
 
 Plays keyframe animation clips on this node and its descendants
@@ -373,6 +379,17 @@ Blends the render camera between virtual cameras by priority (Cinemachine-lite)
 | --- | --- | --- | --- |
 | `blendEnabled` | boolean | `true` | Ease between cameras on activation. Off = hard cut. |
 
+### `core:CharacterVisual2D`
+
+Plays variant + state as a clip of an AnimatedSprite2D whose clips are named <variant>.<state> (sword.idle); swap the variant, keep the state vocabulary
+
+| Key | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | string | `""` | Clip-name prefix (sword, bow). Empty when clips are named by state alone |
+| `state` | string | `""` | State played on start (idle) |
+| `separator` | string | `"."` | Text between variant and state in clip names |
+| `spriteNodeId` | string | `""` | AnimatedSprite2D to drive; empty = this node or its first sprite child |
+
 ### `core:Collider2D`
 
 Physics shape (rect/circle/polygon, rotation-aware, may be concave). With no Physics Body above it this is static world geometry; as a sensor it reports body-entered / body-exited.
@@ -635,4 +652,4 @@ Oscillates a node along a selected axis
 | --- | --- | --- | --- |
 | `amplitude` | number | `1` | ≥ 0; Maximum displacement from the center |
 | `frequency` | number | `1` | ≥ 0; Oscillations per second |
-| `axis` | select | `"y"` | x \| y \| z; The axis to oscillate along |
+| `axis` | select | `"y"` | x \| y \| z; The axis to oscillate along |