@pix3/cli 1.6.0

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

@@ -0,0 +1,235 @@
+---
+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.
+---
+
+<!-- Pix3 agent kit 1.6.0 -->
+# `.pix3scene` format
+
+Scenes, prefabs and overlays are the same file type: YAML with a `.pix3scene` extension.
+"Prefab" only means "a scene file that other scenes instance". There is no `.pix3prefab`.
+The engine's own statement of the format (principles, skinned UI controls, Spine nodes) is in
+`reference.md` beside this file; where the two differ, this page describes what the loader and
+`pix3 validate` actually do.
+
+## 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`).
+
+## File
+
+```yaml
+version: 1.0.0                 # the only format version; copy it
+metadata:                      # optional, free-form
+  author: Pix3 Recipe
+  description: Tapper gameplay — falling objects
+root:                          # list of root nodes; at least one
+  - id: game-root
+    type: Group2D
+    ...
+```
+
+`#` lines are comments and may appear anywhere. Top-level keys are exactly `version`,
+`description`, `metadata`, `root`.
+
+## Node
+
+```yaml
+- id: spawner-targets          # REQUIRED. Unique across the scene incl. instanced prefabs.
+  type: Group2D                # REQUIRED for a plain node. Exact class name (see pix3-nodes).
+  name: Spawner Targets        # display name; free to change
+  groups: [spawners]           # optional runtime groups
+  properties:                  # node properties — names from pix3-nodes
+    width: 900
+    height: 60
+    transform:
+      position: [0, 690]
+      scale: [1, 1]
+      rotation: 0
+  components:                  # optional; script components
+    - id: target-spawner
+      type: user:Spawner
+      enabled: true
+      config:
+        prefab: res://scenes/prefabs/target.pix3scene
+        intervalSec: 0.85
+  children: []                 # optional; child nodes, same shape, recursive
+```
+
+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
+  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.
+- **`properties`**: unknown keys are kept silently and do nothing; a value of the wrong type
+  (a string where a number belongs) is silently replaced by the default. Check names and
+  types against `pix3-nodes`.
+- **`children`**: tree order is 2D paint order — a later sibling, or a deeper node, draws on
+  top. `zIndex` overrides it.
+
+### 2D transform
+
+```yaml
+transform:
+  position: [x, y]      # design pixels; the node's CENTRE, relative to its parent
+  scale: [1, 1]
+  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
+`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
+radians (`node.rotation.z`). `{ x: 0, y: 690 }` is also accepted for a vector, and so is a flat
+`position:` beside `transform` (read-compat), but write the `transform:` block the editor saves.
+
+3D nodes (`Node3D`, meshes, cameras, lights) use
+`transform: { position: [x, y, z], rotationEuler: [dx, dy, dz], scale: [1, 1, 1] }`,
+rotation in degrees.
+
+### Anchor layout (2D)
+
+```yaml
+layout:
+  enabled: true
+  horizontalAlign: left      # left | center | right | stretch
+  verticalAlign: top         # top | center | bottom | stretch
+```
+
+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.
+
+**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.
+
+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 }`.
+
+The flat names `layoutEnabled`, `horizontalAlign`, `flowEnabled`, `flowGap` … are the
+inspector's names for the same values: on a plain node they belong in these blocks (flat they
+are ignored — `pix3 validate` says so); on an **instance** node they are the only form (below).
+
+### Values
+
+- **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`
+  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/`).
+- **Texture slot**: `texture: { type: 'texture', url: 'res://sprites/x.png' }` (same shape for
+  `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"`).
+
+### Shader effects (`Sprite2D`, `AnimatedSprite2D`, `Button2D` only)
+
+```yaml
+effects:
+  - type: core:tint
+    params: { color: "#7ee787", amount: 1 }
+```
+
+`core:tint` multiplies a near-white placeholder PNG to the colour — this is how recipe
+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`.
+
+## Component
+
+```yaml
+- id: combo                    # readable id; keep it unique in the scene
+  type: user:Combo             # user:<ExportedClassName> (scripts/*.ts) or core:<Name>
+  enabled: true
+  config:                      # keys = names in the component's getPropertySchema()
+    windowSec: 1.2
+```
+
+- `config` is **merged over** the defaults the script's constructor sets, so write only the
+  keys you want to differ.
+- A `user:X` whose class does not exist (or has no `static getPropertySchema()`) is kept as
+  "pending" with a console warning and never runs.
+- Built-ins (`core:*`) and every config key they take, with defaults, are listed in
+  `.claude/skills/pix3-scripts/reference.md` ("`core:` components").
+
+## Prefab instance
+
+```yaml
+- id: result-overlay
+  name: Result Overlay
+  instance: res://scenes/ui/result.pix3scene
+  properties:
+    visible: false
+    transform: { position: [0, 0] }
+```
+
+- `instance:` **replaces** `type:`. The instanced file must contain **exactly one** root node.
+- 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.
+- 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:
+
+  ```yaml
+  overrides:
+    byLocalId:
+      retry-button:            # an id below the prefab root; nested: parent-id/child-id
+        properties: { label: "AGAIN" }   # schema names, as on the instance itself
+  ```
+
+- Nodes inside an instance keep their authored ids when those are unique, so scripts can find
+  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
+  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 })`.
+
+## Full-screen UI lives in `scenes/ui/`
+
+A result card, pause menu or modal is its own file in `scenes/ui/`, instanced into the host
+scene with `properties: { visible: false }`. Two different flags, both needed:
+
+- `visible: false` on the **instance** — hides it in the **editor**, so `main.pix3scene`
+  opens on the game, not on a GAME OVER card. Never remove it.
+- `initiallyVisible: false|true` on the **overlay file's root node** — what **play mode**
+  applies at start. A script reveals the overlay by setting `node.visible = true`.
+
+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.
+- Instance overrides of **components** inside a prefab are not supported from the host scene.

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

@@ -0,0 +1,176 @@
+<!-- Pix3 agent kit 1.6.0 — generated from docs/pix3-specification.md ("Scene File Format"). Do not edit: pix3 kit --update regenerates it. -->
+# `.pix3scene` — the engine specification
+
+Excerpts of the engine's specification, as shipped with this CLI. `SKILL.md` beside this file
+is the practical version and wins where they differ — in particular node ids may be readable
+kebab-case, and there are no scene-format migrations today (`version: 1.0.0` is the only one).
+The "Flat Asset Layout" principle is what `pix3 new` creates; an existing project keeps its own
+layout (`res://` is always relative to the project root). Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine repository, not of this project.
+
+## Key principles
+
+- Declarative: The file describes the composition and structure of the scene, not the process of its creation.
+- Asset Referencing: Assets (models, textures) are not embedded in the file but are referenced via relative paths with a res:// prefix (path from the project root).
+- Flat Asset Layout: a game project keeps one folder per asset type **at its root** — `scenes/`, `sprites/` (images/textures), `models/`, `audio/`, `fonts/`, `spine/` (skeleton + atlas + pages together), `scripts/`, `locales/` — with free subdivision inside (`sprites/ui/…`). There is no `assets/` wrapper folder; the project templates ship this layout and `defaultAssetFolder()` (`src/core/asset-categories.ts`) is the canonical mapping used when the editor creates an asset from a bare file name.
+- SVG textures: an `.svg` works as a `Sprite2D` / `Button2D` texture only when its root `<svg>` carries `xmlns="http://www.w3.org/2000/svg"` and px `width`/`height` (a viewBox alone has no intrinsic size), it is self-contained, and the Blob it is decoded from is typed `image/svg+xml` — every read path therefore types image/audio blobs by extension when the stored type is generic (`CloudProjectCacheService.readBlob`, `PlayableHtmlBuildService.resolveMimeType`). `pix3 validate` checks referenced SVGs (`E_SVG_INVALID`, `E_SVG_NO_SIZE`, `W_SVG_VIEWBOX_ONLY`, `W_SVG_EXTERNAL_REF`).
+- Composition: Complex scenes are assembled from simpler ones by instantiating other scene files.
+- Unambiguous Structure: An explicit children key is used to denote the list of child nodes, which separates the hierarchy from the properties of the node itself.
+- Unique Identification: Every node must have an id field. The value is a short, cryptographically secure unique identifier (similar to Nano ID) to provide a balance between file readability and the absolute reliability of references.
+- Versioned Schema: Each file includes a `version` field; migrations are maintained in the SceneManager and run automatically on load.
+- Conflict Resolution: Instance overrides always win over parent definitions. Duplicate IDs trigger validation errors during import.
+- Forgiving Vocabulary: a `type:` the loader does not know does **not** fail the load — the node is built as a bare `NodeBase` placeholder that does nothing, so a scene written by a newer version (or with a typo) stays openable and editable. Because such a node is otherwise indistinguishable from a working one, it is reported on three surfaces: the renderability lint (`inert-nodes` in `scene_tree` / `game_observe` / play start), the loader diagnostic (`describeUnknownNodeType`, which suggests the nearest known name), and the Scene Tree row, which carries a warn badge and states the reason in its tooltip. `isInertNode` (`packages/pix3-runtime/src/core/renderability-lint.ts`) is the one predicate behind all three.
+
+## Skinned 2D UI controls
+
+`Button2D`, `Checkbox2D`, `Slider2D` and `Bar2D` are colour-driven by default and
+skinned by pointing their texture slots at `res://` sprites. A slot that is set
+replaces the corresponding flat colour (the material tint goes white); a slot that
+is unset keeps the colour, so an existing scene is unchanged and **every one of
+these keys is omitted from a saved scene at its default**.
+
+Slots per node: `Button2D` — `textureNormal` / `textureHover` / `texturePressed` /
+`textureDisabled` (a missing state falls back to normal); `Checkbox2D` —
+`textureBox`, `textureBoxChecked` (optional; falls back to `textureBox`),
+`textureMark` (drawn over the box only while checked); `Slider2D` —
+`textureTrack`, `textureFill`, `textureThumb`; `Bar2D` — `textureTrough`,
+`textureFill`.
+
+The four `sliceBorderLeft/Right/Top/Bottom` scalars are the same nine-slice insets
+`TiledSprite2D` uses — source-texture pixels, Godot's `patch_margin_*` — so one
+64x64 skin fits a control of any size instead of being smeared. They apply to
+`Button2D`'s state skins, `Slider2D`'s track and fill, and `Bar2D`'s trough and
+fill; the slider thumb is drawn at its authored size and is never sliced. A fill
+that shrinks with `value` is **re-cut** at the new width, so its end caps keep
+their pixel size. All-zero (the default) is the plain stretch. A sliced skin opts
+out of the 2D quad batcher, because the batcher extracts four *unit* corners, and
+is excluded from the pre-launch texture atlas for the same reason.
+
+Sprites for every one of these slots — and the matching insets — can be generated
+and applied without leaving the editor; the files and their manifest are specified
+in **§6.23 UI Kit Assets**.
+
+```yaml
+- id: 'q7Bd-1mZ_kTn0-Vx4pA'
+  type: 'Button2D'
+  name: 'PlayButton'
+  properties:
+    transform:
+      position: { x: 0, y: -80 }
+    width: 240
+    height: 72
+    label: 'Play'
+    buttonAction: 'Submit'
+    textureNormal: { type: 'texture', url: 'res://sprites/ui/btn_normal.png' }
+    textureHover: { type: 'texture', url: 'res://sprites/ui/btn_hover.png' }
+    texturePressed: { type: 'texture', url: 'res://sprites/ui/btn_pressed.png' }
+    # 64x64 skin with 16 px corners -> fits 240x72 without smearing
+    sliceBorderLeft: 16
+    sliceBorderRight: 16
+    sliceBorderTop: 16
+    sliceBorderBottom: 16
+
+- id: 'w3Kf-8sQ_2rLm-Yc6tB'
+  type: 'Bar2D'
+  name: 'HealthBar'
+  properties:
+    width: 200
+    height: 24
+    value: 100
+    maxValue: 100
+    textureTrough: { type: 'texture', url: 'res://sprites/ui/bar_trough.png' }
+    textureFill: { type: 'texture', url: 'res://sprites/ui/bar_fill.png' }
+    sliceBorderLeft: 12
+    sliceBorderRight: 12
+
+- id: 'e5Nh-4tW_9pJk-Zd1uC'
+  type: 'Checkbox2D'
+  name: 'MusicToggle'
+  properties:
+    size: 32
+    checked: true
+    label: 'Music'
+    textureBox: { type: 'texture', url: 'res://sprites/ui/check_off.png' }
+    textureBoxChecked: { type: 'texture', url: 'res://sprites/ui/check_on.png' }
+    textureMark: { type: 'texture', url: 'res://sprites/ui/check_tick.png' }
+```
+
+## Spine skeleton nodes
+
+A `SpineSkeleton2D` references its Spine export by two `res://` paths — the
+skeleton (`.json` or `.skel`) and the atlas (`.atlas`). The atlas' page images are
+NOT listed: they are named inside the atlas text and resolved relative to it (the
+export asset collector parses `.atlas` files for the same reason). `texture` is an
+optional single-page override.
+
+```yaml
+- id: 'ZP2h-9kQ_1sVb0Ac-7mnE'
+  type: 'SpineSkeleton2D'
+  name: 'Hero'
+  properties:
+    transform:
+      position: { x: 0, y: -120 }
+      scale: { x: 1, y: 1 }
+    skeletonPath: 'res://spine/hero.json'
+    atlasPath: 'res://spine/hero.atlas'
+    animation: 'idle'
+    loop: true
+    isPlaying: true
+    skin: ''
+    timeScale: 1
+    defaultMix: 0.15
+    color: '#ffffff'
+    # Omitted unless enabled: twoColorTint, freeOnFinish, previewInEditor
+```
+
+Rendering requires the optional `@esotericsoftware/spine-threejs` (`~4.3`) module,
+registered by the host through `setSpineModuleLoader`. A scene with a Spine node
+still loads without it — the node keeps its authored properties and warns.
+
+## Groups
+
+Groups provide runtime categorization for nodes (for example, `enemies`, `ui`, `interactables`).
+
+#### 6.19.1 Node API
+
+- `addToGroup(group)`
+- `removeFromGroup(group)`
+- `isInGroup(group)`
+
+#### 6.19.2 Scene API
+
+`SceneManager` provides group-based queries and invocation:
+
+- `getNodesInGroup(group)` - returns matching nodes in the active scene.
+- `callGroup(group, method, ...args)` - calls matching component methods across grouped nodes.
+
+`callGroup` performs runtime method checks and warns if no callable method is found.
+
+#### 6.19.3 Serialization
+
+Groups are serialized in `.pix3scene` nodes via `groups: []`.
+
+```yaml
+root:
+  - id: player_001
+    type: Node3D
+    name: Player
+    groups: [actors, player]
+```
+
+## Prefabs — instance creation
+
+Creating a prefab instance uses the `instance:` YAML key:
+
+```yaml
+root:
+  - id: scene_root
+    type: Node3D
+    children:
+      - id: player_instance_1
+        instance: res://prefabs/player.pix3scene
+        name: Player1
+        properties:
+          position: { x: 0, y: 0, z: 0 }
+```
+
+The `properties` block allows overriding base prefab values. Overrides are tracked separately from the base values.