castle-web-cli 0.4.114 → 0.4.116

package/kits/physics-2d/CLAUDE.md

@@ -9,7 +9,7 @@ See `## Physics` below.
 
 ## Welcome message
 
-Welcome to an early test of Castle's new engine, with real 2D physics! You're starting with Castle's art and scene editors. Open `cauldron.pxart` or `main.scene` to try them out, or I can start building something for you — a physics toy, a launcher game, a drag-and-fling puzzle, whatever you like.
+Welcome to an early test of Castle's new engine, with real 2D physics! You're starting with Castle's art and scene editors. Open `cauldron.sprite` or `main.scene` to try them out, or I can start building something for you — a physics toy, a launcher game, a drag-and-fling puzzle, whatever you like.
 
 Do you already know what you want to make, or do you want to figure it out together?
 
@@ -21,11 +21,13 @@ Do you already know what you want to make, or do you want to figure it out toget
 - Game logic lives in `behaviors/*.jsx` classes. A behavior's `static behaviorName` must match the component key used in scene JSON.
 - Editable screens live in `scenes/*.scene` files (plain JSON). Use a separate scene file per distinct screen, and switch with `scene.loadFromFile('name.scene')`.
 - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
-- Real game objects and scenery should usually be editable sprites: generate `.pxart` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.pxart`. Dynamic UI/effects stay procedural.
+- Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
+- A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, `Sound` and `Video` play audio and video files, and `Tone` synthesizes a note with no file at all. Point their `file` at the deck path (`assets/logo.png`).
+- **Supported media formats are exactly**: `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` images, `.mp3` `.wav` `.m4a` audio, `.mp4` (H.264) video. Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
 - This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
 - After any code, scene, or drawing edit, run `npm run restart`.
 - Space is reserved by the editor for play/stop; do not bind Space to gameplay.
-- Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`) to build a game. Their public API is documented below.
+- Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below.
 - Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
 
 ## Files and imports
@@ -33,11 +35,11 @@ Do you already know what you want to make, or do you want to figure it out toget
 One rule wherever a file is named -- JS imports, `"blueprint"` refs, `Sprite.file`,
 a joint's `sprite`, anything a behavior invents:
 
-- `drawings/ship.pxart` -- a file of the deck the reference is WRITTEN IN. In this
+- `drawings/ship.sprite` -- a file of the deck the reference is WRITTEN IN. In this
   deck's own files that means this deck; in a file belonging to an import, that
-  import. So a kit's blueprint saying `drawings/cauldron.pxart` keeps meaning the
+  import. So a kit's blueprint saying `drawings/cauldron.sprite` keeps meaning the
   kit's drawing once the kit is imported by someone else.
-- `@imports/<alias>/drawings/ship.pxart` -- a file of the deck imported under
+- `@imports/<alias>/drawings/ship.sprite` -- a file of the deck imported under
   `<alias>`. This is the only way to name another deck's file, so cross-deck
   references are visible as such, and it means the same thing from any file at
   any depth.
@@ -57,7 +59,7 @@ The deck is already serving when you start (`castle-web init` set that up; see `
 
 1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), `npm run restart`, then add the next piece. Do NOT write the whole game in one shot.
 2. **After every edit:** `npm run restart` (no hot reload). The served page refreshes and the user sees the change.
-3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual pixel-art sprites and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Make art as `.pxart` via the `draw` command (see **Creating pixel art** below). Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into sprites.
+3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual pixel-art sprites and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Make art as `.sprite` via the `draw` command (see **Creating pixel art** below). Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into sprites.
 4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.loadFromFile('gameover.scene')` (reads the file and transitions) on play / win / level change. NEVER `import` a `.scene` file as a module — scene files are data, not modules; use `scene.readFromFile` / `scene.loadFromFile`.
 
 Card size is **500 wide × 700 tall** (origin top-left, +y is down).
@@ -124,7 +126,7 @@ A **blueprint** is a `.scene` file under `blueprints/` whose single actor (`acto
     {
       "components": {
         "Layout": { "width": 50, "height": 25 },
-        "Sprite": { "file": "drawings/brick.pxart" },
+        "Sprite": { "file": "drawings/brick.sprite" },
         "Collider": { "kind": "solid" },
         "Brick": {}
       }
@@ -143,8 +145,8 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
 ## Built-in behaviors
 
 - **Layout** — `{ x, y, width, height, z?, rotation? }`. Every actor needs one. `z` orders draw (low first). `rotation` is degrees about the center.
-- **Sprite** — `{ file: "drawings/foo.pxart", tint?: "#rrggbbaa", playing?: true, tag?: "", mode?: 'cover'|'fit'|'stretch'|'tile', tileSize?: 50 }`. Renders a `.pxart` pixel-art sprite into the Layout box: scaled up preserving the art's aspect ratio to fill the whole box, cropping whatever overflows a mismatched box (`mode: 'cover'`, the default -- CSS object-fit: cover), scaled preserving the art's aspect ratio and centered so the whole sprite stays visible, letterboxing a mismatched box instead of cropping (`mode: 'fit'` -- CSS object-fit: contain), scaled to fill the box exactly and distorting the art when the aspect ratios don't match (`mode: 'stretch'`), or repeated (`mode: 'tile'`). `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. Animated sprites play automatically; set `playing: false` to hold the first frame, or `tag` to play a named animation tag. Tile mode repeats the art at a fixed cell size (`tileSize` card units tall, width scaled by the art's aspect) instead of stretching it across the Layout box.
-  - **Missing sprites fall back to a placeholder.** If `file` names a sprite that doesn't exist yet, it renders the fallback `drawings/cauldron.pxart` — so you can give an actor its REAL intended sprite name (`drawings/paddle.pxart`) right away and it shows the placeholder until that file is created. Reference real names from the start; don't wait for the art.
+- **Sprite** — `{ file: "drawings/foo.sprite", tint?: "#rrggbbaa", playing?: true, tag?: "", mode?: 'cover'|'fit'|'stretch'|'tile', tileSize?: 50 }`. Renders the deck's 2D art into the Layout box. `file` is either a `.sprite` pixel-art sprite or an uploaded **image file** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`) — every prop below works the same on both, except that an image is a single still (no frames or tags) and is drawn smoothed rather than nearest-neighbour, which is what you want for a photo and not for pixel art. Draw modes: scaled up preserving the art's aspect ratio to fill the whole box, cropping whatever overflows a mismatched box (`mode: 'cover'`, the default -- CSS object-fit: cover), scaled preserving the art's aspect ratio and centered so the whole sprite stays visible, letterboxing a mismatched box instead of cropping (`mode: 'fit'` -- CSS object-fit: contain), scaled to fill the box exactly and distorting the art when the aspect ratios don't match (`mode: 'stretch'`), or repeated (`mode: 'tile'`). `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. Animated sprites play automatically; set `playing: false` to hold the first frame, or `tag` to play a named animation tag. Tile mode repeats the art at a fixed cell size (`tileSize` card units tall, width scaled by the art's aspect) instead of stretching it across the Layout box.
+  - **Missing sprites fall back to a placeholder.** If `file` names a sprite that doesn't exist yet, it renders the fallback `drawings/cauldron.sprite` — so you can give an actor its REAL intended sprite name (`drawings/paddle.sprite`) right away and it shows the placeholder until that file is created. Reference real names from the start; don't wait for the art.
   - **Fill the box, don't distort.** The default `mode: 'cover'` fills the Layout box with the art undistorted, cropping whatever overflows when the box aspect doesn't match the art's — so treat the Layout box like an image frame in a design tool: size it to frame what matters and keep the sprite's important content toward the center, since the edges may be cropped. Keeping an actor's Layout aspect ratio close to its sprite's native aspect ratio minimizes how much gets cropped. When the whole sprite must stay visible (nothing is safe to crop), use `mode: 'fit'`, which preserves the art and letterboxes the mismatched box instead. Avoid `mode: 'stretch'` for pixel art — filling a long/tall box by distorting wrecks the pixels (a brick sprite stretched into a wall ruins the bricks). For long surfaces (walls, floors, platforms), use `mode: 'tile'` on one actor to repeat the art at a fixed cell size instead of stretching or cropping a single sprite.
 - **Collider** — `{ kind: 'solid'|'pickup', mode?: 'auto'|'manual', width, height, offsetX?, offsetY?, debug? }`. Just a rect; `offsetX`/`offsetY` nudge the collider from its default position (so `0,0` is the default). `mode: 'auto'` (the default) fits the rect to the actor's Sprite's opaque pixels, mapped through the Sprite's draw mode (`fit`'s letterboxed dest rect, `stretch`'s full Layout box, `cover`'s filled box clipped to the Layout box; `tile` mode and a missing/unresolved Sprite use the whole Layout box instead). `width`/`height` only apply in `mode: 'manual'` (a rect of that size, centered in the Layout box); they're ignored in `auto`. The framework does NOT auto-resolve collisions for you. Use it as data:
 
@@ -158,6 +160,24 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
   ```
 
 - **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation).
+- **Sound** — `{ file: "assets/hit.mp3", volume?: 1, playbackRate?: 1, pan?: 0, loop?: false, polyphonic?: false, playOnStart?: true }`. Plays an audio file (`.mp3`/`.wav`/`.m4a`) from an actor. `playbackRate` retunes it (2 = an octave up and twice as fast, 0.5 = an octave down); `pan` places it left (−1) to right (+1); `polyphonic` overlaps copies instead of cutting the last one off, which is what a sound effect fired twice in a row should do (leave it off for music). With `playOnStart` it starts with the scene; otherwise trigger it from code through the handle it puts on the actor:
+
+  ```jsx
+  scene.getActor('sfx').runtime.sound.play();   // restarts from the beginning
+  await actor.runtime.sound.play();             // ...and wait for it to finish
+  actor.runtime.sound.stop();                   // also: pause(), resume(), .playing
+  scene.sound.stopAll();                        // everything the scene is playing, off
+  ```
+
+  Sound only plays during play, never in the editor, and everything stops on Stop / a scene change. Browsers refuse audio until the player has touched the page; a sound that starts before that is queued and begins on the first tap or key, so don't work around it.
+- **Tone** — `{ note?: 60, waveform?: 'square'|'sawtooth'|'sine'|'triangle'|'noise', attack?: 0, release?: 0.3, volume?: 0.5, pan?: 0, playOnStart?: false }`. Plays a synthesized note — no audio file, nothing downloaded, nothing stored. Reach for this before an audio file for blips, thuds and pickups. `note` is MIDI (60 = middle C, +12 an octave, +1 a semitone), and the note lasts `attack + release` seconds.
+
+  ```jsx
+  actor.runtime.tone.play();                 // the note as configured
+  actor.runtime.tone.play({ note: 72 });     // ...or override per play, e.g. a rising scale
+  await actor.runtime.tone.play({ note: 48, waveform: 'noise' });
+  ```
+- **Video** — `{ file: "assets/clip.mp4", mode?: 'cover'|'fit'|'stretch', playing?: true, loop?: true, muted?: true, volume?: 1 }`. Plays an `.mp4` (H.264) video inside the Layout box, drawn into the scene like a sprite: it moves with Layout, draws in `z` order, and can carry a Collider. `mode` frames it exactly as Sprite's does. In the editor it holds its first frame so you can place it. Leave `muted: true` unless the player has already interacted — an unmuted autoplaying video is blocked by browsers, a muted one isn't.
 
 ## Physics
 
@@ -308,7 +328,7 @@ anchors.
   prototyping; you see your joints working.
 - `hidden` — nothing drawn in play (the joint is pure mechanics). It still shows
   as a faint line in the *editor* so you don't lose track of it.
-- `sprite` — draw art along the joint. Set `sprite` to a `.pxart`
+- `sprite` — draw art along the joint. Set `sprite` to a `.sprite`
   (defaults to a built-in rope), `thickness` (px), and `fit`: `tile` (repeat a
   segment — rope, chain) or `stretch` (one image end-to-end — stick, beam). The
   art rotates to the joint's angle and scales to its live length, so a rope
@@ -349,31 +369,30 @@ draw(actor, scene, ctx) {
 - **A global max-speed clamp (`MAX_SPEED` in matterBridge)** backstops any joint
   blow-up so a body can't be flung off screen — normal motion never reaches it.
 
-## Adding physics to another kit
+## Where physics lives in the kit
 
-The physics module (`physics/`) is self-contained and portable. To add it to a
-different kit:
+Physics is a normal part of this kit, not a bolt-on module. It uses the same
+directories as everything else, because the rest of the system only looks in
+those places:
 
-1. Copy the `physics/` folder into the kit.
-2. Add `matter-js` to the kit's `package.json` dependencies.
-3. In the kit's `engine/scene.js`: add a systems registry to `SceneRuntime`
-   (`this.systems = []`, a `registerSystem(system)` method, at the end of
-   `update(dt)` a `for (const s of this.systems) s.afterBehaviors?.(this, dt);`,
-   and at the START of `load(sceneData)` a
-   `for (const s of this.systems) s.reset?.(this);` so a reload/restart/scene
-   transition resets the simulation to the authored layout instead of carrying
-   over body positions + joints), then call `installPhysics(runtime)` from
-   `makeScene` (and route `clone()` through `makeScene` so clones get it too).
-4. In the kit's `editors/behaviorRegistry`, also glob
-   `../physics/behaviors/*.jsx` so the physics behaviors auto-register.
+- `behaviors/` — `RigidBody`, `Joints`, `Draggable`, `Slingshot`, `AnalogStick`
+  sit alongside `Layout`/`Sprite`/`Collider`/`Camera`. This is the ONE directory
+  behaviors live in: the deck file map (`engine/files.js`), the editor's visible
+  paths (`castle.json`), the lint config, and the duplicate gate all key off it,
+  so a behavior kept anywhere else is invisible to all of them.
+- `engine/physics/` — the simulation itself (`PhysicsSystem.js`, `matterBridge.js`,
+  `joints.js`, `jointArt.js`, `controls.js`). Internal, like the rest of `engine/`.
+- `systems/physics.js` — the installer, auto-discovered by
+  `engine/systemRegistry.js` and invoked by `makeScene`, so the shared engine
+  never references physics directly.
 
-The module reuses the kit's `engine/collider.js` `getColliderRect(actor,
-sprites)` for shape geometry, so a kit needs that (both `basic-2d` and this kit
-have it).
+That last seam is the generic one: any kit can add a per-frame system by dropping
+a file in `systems/` that exports `installSystem(runtime)`, with no engine edits.
+Physics is just this kit's use of it.
 
-## Creating pixel art (`.pxart`)
+## Creating pixel art (`.sprite`)
 
-Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a terse svg-rect** — a tiny `<svg viewBox="0 0 16 16">` with **one `<rect>` per pixel** — and pipe it to `npm run draw`. It quantizes every fill to the agent palette and writes a single-frame `drawings/<name>.pxart`.
+Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a terse svg-rect** — a tiny `<svg viewBox="0 0 16 16">` with **one `<rect>` per pixel** — and pipe it to `npm run draw`. It quantizes every fill to the agent palette and writes a single-frame `drawings/<name>.sprite`.
 
 - **Resolution is 16×16.** Use `viewBox="0 0 16 16"` and **one 1×1 `<rect>` per filled pixel** (`width="1" height="1"` at integer `x`/`y`). Leave background pixels out (omitted = transparent). Keep every rect 1×1 — the decoder infers cell size from the smallest rect, so mixing in larger blocks shrinks the whole grid.
 - **Palette is the agent 16-color subset** (a fixed subset of the editor's full Endesga-64 painting palette) — every `fill` must be one of:
@@ -387,10 +406,22 @@ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a
   printf '<svg viewBox="0 0 16 16"><rect x="7" y="4" width="1" height="1" fill="#ffa214"/><rect x="8" y="4" width="1" height="1" fill="#ffa214"/><rect x="7" y="5" width="1" height="1" fill="#0098dc"/><rect x="8" y="5" width="1" height="1" fill="#0098dc"/></svg>' | npm run draw -- ship
   ```
 
-  writes `drawings/ship.pxart`. You can also pass `--from file.svg` instead of stdin. An undecodable svg (no usable rects) errors with a nonzero exit and writes nothing.
-- **After writing, `npm run restart`.** Newly created files aren't in the kit's static glob until a restart; until then the missing-sprite fallback renders the placeholder (so an actor pointing at a not-yet-drawn `.pxart` is still playable).
+  writes `drawings/ship.sprite`. You can also pass `--from file.svg` instead of stdin. An undecodable svg (no usable rects) errors with a nonzero exit and writes nothing.
+- **After writing, `npm run restart`.** Newly created files aren't in the kit's static glob until a restart; until then the missing-sprite fallback renders the placeholder (so an actor pointing at a not-yet-drawn `.sprite` is still playable).
+
+Point a `Sprite` component's `file` at the generated `drawings/<name>.sprite` to put the art on an actor.
+
+Older decks may still use the `.pxart` extension for the same format; the editor opens and saves both, but **create new art as `.sprite`**.
+
+## Path layers (vector source in `.sprite`)
+
+Layers come in two kinds. A **pixel** layer is the grid of palette keys described above. A **path** layer also carries vector source: an ordered list of shapes, each a fill plus an optional stroke over subpaths of cubic segments. Shapes composite in painter's order, so a later shape overwrites an earlier one's pixels, and a shape's own multi-subpath fill resolves even-odd (which is how holes are punched).
+
+Only **closed** subpaths bound a fill; an open one only strokes. That is how a shape draws its internal divisions — one outline around the silhouette plus an open subpath per division — rather than as two abutting shapes, which would carry two fill keys to keep in step and a seam where each strokes its own side of the shared border. A division that lies exactly on the outline is redundant, and the editor drops it on the next edit, so draw one only where it departs from the outline.
+
+The editor always bakes a path layer's shapes down into the cell's `grid`, so **pixels stay the truth** for the runtime and for anything that doesn't know about paths. Path layers are fully editable in the app — pen, select, bend, punch, flip/rotate, z-order, recolor — and pixel layers behave exactly as they did. Converting a layer's kind is lossy in both directions: Pixel → Path throws away the pixels, Path → Pixel throws away the vector source and keeps the baked grid.
 
-Point a `Sprite` component's `file` at the generated `drawings/<name>.pxart` to put the art on an actor.
+To generate path art, emit an svg of **shapes** rather than per-pixel rects and pipe it to `node scripts/import-svg.mjs <name>`; `scripts/svg-emission-guide.md` covers what the importer accepts. `docs/pxart-format.md` is normative for the on-disk form, the half-cell lattice path points are authored onto (guidance for placement, not a storage rule — coordinates are plain floats), the bake, and the sprite's finish fields.
 
 ## SceneRuntime API (what `scene` exposes to behaviors)
 

package/kits/physics-2d/{physics/behaviors → behaviors}/AnalogStick.jsx

@@ -1,7 +1,7 @@
 import React from 'react';
-import { Panel, SelectField } from '../../engine/ui';
-import { AutoFields, overrideProps } from '../../engine/autoInspector';
-import { analogVelocity, inActorWorldSpace, pressOnDraggable, stickVector } from '../controls';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { analogVelocity, inActorWorldSpace, pressOnDraggable, stickVector } from '../engine/physics/controls';
 
 // AnalogStick: an on-screen virtual joystick that drives the actor it's on --
 // the look and feel of castle-client's Analog Stick. Press anywhere to place

package/kits/physics-2d/behaviors/Collider.jsx

@@ -88,7 +88,7 @@ export class Collider {
     // zone for pickup/goal logic) but doesn't block -- collisions are data.
     isTrigger: false,
     debug: false,
-    // Physics material, read by physics/matterBridge.js. `bounciness` =
+    // Physics material, read by engine/physics/matterBridge.js. `bounciness` =
     // restitution (0 dead .. ~1 very bouncy); `friction` = surface friction;
     // `density` sets mass (= density x total shape area); matter's default 0.001.
     bounciness: 0,

package/kits/physics-2d/{physics/behaviors → behaviors}/Draggable.jsx

@@ -1,7 +1,7 @@
 import React from 'react';
-import { Panel } from '../../engine/ui';
-import { AutoFields } from '../../engine/autoInspector';
-import { centerOf, chaseVelocity, inActorWorldSpace } from '../controls';
+import { Panel } from '../engine/ui';
+import { AutoFields } from '../engine/autoInspector';
+import { centerOf, chaseVelocity, inActorWorldSpace } from '../engine/physics/controls';
 
 // Draggable: grab the actor with the pointer and fling it around. Chases the
 // pointer with a springy velocity (via the physics system) so it still collides

package/kits/physics-2d/{physics/behaviors → behaviors}/Joints.jsx

@@ -1,8 +1,8 @@
 import React, { useState } from 'react';
-import { Panel, SelectField, NumberField, CheckboxField, Button } from '../../engine/ui';
-import { centerOf, inActorWorldSpace } from '../controls';
-import { JOINT_TYPES } from '../joints';
-import { drawJointArt } from '../jointArt';
+import { Panel, SelectField, NumberField, CheckboxField, Button } from '../engine/ui';
+import { centerOf, inActorWorldSpace } from '../engine/physics/controls';
+import { JOINT_TYPES } from '../engine/physics/joints';
+import { drawJointArt } from '../engine/physics/jointArt';
 
 const RENDER_MODES = ['line', 'hidden', 'sprite'];
 // Bound anchor offsets (px, local frame). A large offset lengthens the pivot's
@@ -72,7 +72,7 @@ export class Joints {
 
   static Inspector({ component, setComponent, override, beginPick, pickActive, files }) {
     const list = Array.isArray(component.list) ? component.list : [];
-    const spriteFiles = Object.keys(files ?? {}).filter((f) => f.endsWith('.pxart'));
+    const spriteFiles = Object.keys(files ?? {}).filter((f) => f.endsWith('.sprite') || f.endsWith('.pxart'));
     // Which entry's target-pick is live. Combined with the editor's global
     // `pickActive` so a cancel (Esc/empty click) clears every entry's state.
     const [pickingIndex, setPickingIndex] = useState(null);

package/kits/physics-2d/{physics/behaviors → behaviors}/RigidBody.jsx

@@ -1,6 +1,6 @@
 import React from 'react';
-import { Panel, SelectField } from '../../engine/ui';
-import { AutoFields, overrideProps } from '../../engine/autoInspector';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
 
 // RigidBody makes an actor a physics object. Pair it with a Collider (which
 // gives the shape + material). The simulation reads these props each frame; the

package/kits/physics-2d/{physics/behaviors → behaviors}/Slingshot.jsx

@@ -1,7 +1,7 @@
 import React from 'react';
-import { Panel } from '../../engine/ui';
-import { AutoFields } from '../../engine/autoInspector';
-import { inActorWorldSpace, pressOnDraggable, slingLaunch, slingPull } from '../controls';
+import { Panel } from '../engine/ui';
+import { AutoFields } from '../engine/autoInspector';
+import { inActorWorldSpace, pressOnDraggable, slingLaunch, slingPull } from '../engine/physics/controls';
 
 // Slingshot: pull back and release to fling the actor the opposite way
 // (angry-birds style) -- the physics feel of castle-client's Sling. While

package/kits/physics-2d/behaviors/Sound.jsx

@@ -0,0 +1,152 @@
+import { resolveDeckFile } from 'castle-web-sdk';
+import React from 'react';
+import { mediaElement, playMedia, playOneShot, setMediaPan, stopMedia } from '../engine/media';
+import { mediaFilesOfKind } from '../engine/files';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+
+// Plays a sound file (.mp3 / .wav / .m4a) from an actor.
+//
+// Two ways to use it. Set `playOnStart` and it plays when the scene starts --
+// music, ambience, a jingle on a game-over screen. Or leave it off and trigger
+// it from a behavior, through the handle this puts on the actor:
+//
+//   scene.getActor('sfx').runtime.sound.play();   // from the top
+//   await actor.runtime.sound.play();             // ...and wait for it to end
+//   actor.runtime.sound.stop();
+//
+// `play()` on a `polyphonic` sound overlaps copies instead of cutting the last
+// one off, which is what a sound effect fired twice in a row should do. Without
+// it, a second play restarts the one element, which is what music wants.
+//
+// Sound only plays during play, never in the editor: `update` is what wires the
+// element up, and the editor doesn't run it. Pressing Stop silences everything,
+// as does `scene.sound.stopAll()` (see systems/media.js).
+//
+// Browsers refuse to play audio until the player has touched the page. A sound
+// that starts before that isn't lost -- it's queued and starts on the first tap
+// or key (engine/media.js), which for a game is usually the first input anyway.
+export class Sound {
+  static behaviorName = 'Sound';
+
+  static defaultProps = {
+    file: '',
+    volume: 1,
+    playbackRate: 1,
+    pan: 0,
+    loop: false,
+    polyphonic: false,
+    playOnStart: true,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const file = resolveDeckFile(this.props.file);
+    const element = mediaElement(actor.id, 'audio', file);
+    if (!element) {
+      actor.runtime.sound = null;
+      return;
+    }
+    // Props are live: turning the volume down, the pitch up, or the loop on in
+    // the inspector takes effect on the sound already playing.
+    const settings = readSettings(this.props);
+    element.volume = settings.volume;
+    element.playbackRate = settings.playbackRate;
+    element.loop = settings.loop;
+    if (settings.pan !== 0) setMediaPan(element, settings.pan);
+
+    const handle = actor.runtime.sound;
+    if (!handle || handle.file !== file) {
+      actor.runtime.sound = makeHandle(file, element, () => readSettings(this.props));
+      if (this.props.playOnStart) void actor.runtime.sound.play();
+    } else {
+      handle.settings = settings;
+    }
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Sound" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          options={mediaFilesOfKind('audio')}
+          {...overrideProps(override, 'file')}
+        />
+        <AutoFields
+          defaultProps={Sound.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['volume', 'playbackRate', 'pan', 'loop', 'polyphonic', 'playOnStart']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+function clamp(value, min, max, fallback) {
+  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+function readSettings(props) {
+  return {
+    volume: clamp(props.volume, 0, 1, 1),
+    // The same ceiling the classic editor used: past 10x a sound is a click.
+    playbackRate: clamp(props.playbackRate, 0.01, 10, 1),
+    pan: clamp(props.pan, -1, 1, 0),
+    loop: Boolean(props.loop),
+    polyphonic: Boolean(props.polyphonic),
+  };
+}
+
+// What a behavior gets at `actor.runtime.sound`. Plain methods over the element,
+// so game code never has to know an <audio> is involved.
+//
+// `play()` returns a promise that resolves when the sound ends, so a behavior
+// can `await` one before doing the next thing. A looping sound resolves right
+// away rather than never -- awaiting something that by definition doesn't end
+// would hang the caller forever, and that is never what was meant.
+function makeHandle(file, element, currentSettings) {
+  const handle = {
+    file,
+    element,
+    settings: currentSettings(),
+    play() {
+      const s = handle.settings;
+      if (s.polyphonic) {
+        return playOneShot(file, { volume: s.volume, playbackRate: s.playbackRate, pan: s.pan });
+      }
+      try {
+        element.currentTime = 0;
+      } catch {
+        // Not seekable yet (still loading) -- it plays from the start anyway.
+      }
+      playMedia(element);
+      if (s.loop) return Promise.resolve();
+      return new Promise((resolve) => {
+        const done = () => resolve();
+        element.addEventListener('ended', done, { once: true });
+        element.addEventListener('error', done, { once: true });
+      });
+    },
+    resume() {
+      playMedia(element);
+    },
+    pause() {
+      element.pause();
+    },
+    stop() {
+      stopMedia(element);
+    },
+    get playing() {
+      return !element.paused;
+    },
+  };
+  return handle;
+}