castle-web-cli 0.4.84 → 0.4.86

package/kits/basic-2d/engine/collider.js

@@ -113,13 +113,16 @@ function manualRect(layout, collider) {
 
 const fullLayoutRect = (layout) => ({ x: layout.x, y: layout.y, width: layout.width, height: layout.height });
 
-// The un-offset rect for whichever mode is active: `manualRect` for
-// `mode: 'manual'`, otherwise the auto sprite-bbox rect (or its Layout-box
-// fallback).
+// The un-offset rect. Colliders are sized by their explicit `width`/`height`
+// (the "auto vs manual" mode is gone -- use the inspector's "Auto-fit to sprite"
+// action to snap those to the sprite). Legacy decks that still carry
+// `mode: 'auto'` keep their dynamic sprite fit for back-compat.
 function modeRect(layout, collider, spriteProps, sprites) {
-  if ((collider.mode ?? 'auto') === 'manual') return manualRect(layout, collider);
-  const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
-  return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+  if (collider.mode === 'auto') {
+    const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
+    return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+  }
+  return manualRect(layout, collider);
 }
 
 // The Collider rect for an actor, from its Layout + Collider (+ Sprite, for
@@ -141,6 +144,57 @@ export function getColliderRect(actor, sprites) {
   };
 }
 
+// Full collider geometry: the AABB rect (`x/y/width/height`, offset-applied)
+// PLUS the shape and, for circles, the center + radius. This is the SINGLE
+// SOURCE OF TRUTH for collider shape -- the physics body (matterBridge), the
+// play-mode debug draw (Collider.draw), and the editor selection overlay all
+// derive their geometry from here, so the visual preview always matches the
+// simulated collider. `radius` of 0 means "derive from the rect" (min side / 2),
+// so a circle shows a real size even before you set an explicit radius.
+export function getColliderShape(actor, sprites) {
+  const rect = getColliderRect(actor, sprites);
+  if (!rect) return null;
+  const collider = actor.components.Collider;
+  const shape = collider.shape === 'circle' ? 'circle' : 'box';
+  const radius = collider.radius > 0 ? collider.radius : Math.min(rect.width, rect.height) / 2;
+  return {
+    shape,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    cx: rect.x + rect.width / 2,
+    cy: rect.y + rect.height / 2,
+    radius,
+  };
+}
+
+// The explicit `width`/`height`/`offsetX`/`offsetY` a collider would need to
+// exactly match its sprite's opaque-pixel fit -- what "auto" used to compute
+// dynamically. Returns null when there's nothing to fit to (no Sprite, tile
+// mode, or fully transparent art). Powers the inspector's "Auto-fit to sprite".
+export function computeAutoFit(actor, sprites) {
+  const rawLayout = actor?.components?.Layout;
+  const spriteProps = actor?.components?.Sprite;
+  if (!rawLayout || !spriteProps) return null;
+  // Blueprint templates omit x/y (position is instance-local). x/y cancel out of
+  // the offset delta below, so default them to 0 -- otherwise an undefined x/y
+  // (auto-fitting a template, e.g. on add) turns the offsets into NaN.
+  const layout = { ...rawLayout, x: rawLayout.x ?? 0, y: rawLayout.y ?? 0 };
+  const rect = autoRect(layout, spriteProps, sprites?.[spriteProps.file]);
+  if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+  // manualRect centers a width x height box in the Layout box; the offset is the
+  // delta from that centered position to the sprite-fit rect.
+  const centeredX = layout.x + (layout.width - rect.width) / 2;
+  const centeredY = layout.y + (layout.height - rect.height) / 2;
+  return {
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+    offsetX: Math.round(rect.x - centeredX),
+    offsetY: Math.round(rect.y - centeredY),
+  };
+}
+
 export function intersects(a, b) {
   return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }

package/kits/basic-2d/engine/scene.js

@@ -1,6 +1,7 @@
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
 import { getColliderRect, intersects, spriteIsEmpty } from './collider';
+import { systemInstallers } from './systemRegistry';
 
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
@@ -42,9 +43,21 @@ export class SceneRuntime {
     this.actors = new Map();
     this.camera = undefined;
     this.status = undefined;
+    // Registered systems run once per frame after all behavior `update`s (see
+    // `update`). A system is a plain object with an optional
+    // `afterBehaviors(scene, dt)` hook; kits register systems from `systems/*.js`
+    // (see makeScene), so the engine core stays decoupled from any specific one.
+    this.systems = [];
     this.load(sceneData);
   }
 
+  // Register a per-frame system (e.g. a physics simulation). Systems step in
+  // registration order, after behaviors, every `update`. Returns the system.
+  registerSystem(system) {
+    this.systems.push(system);
+    return system;
+  }
+
   load(sceneData) {
     this.data = structuredClone(sceneData);
     this.actors = new Map();
@@ -88,7 +101,9 @@ export class SceneRuntime {
   }
 
   clone() {
-    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
+    // Route through makeScene so the clone gets the same registered systems as a
+    // freshly-made runtime.
+    return makeScene(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
   }
 
   serialize() {
@@ -190,6 +205,12 @@ export class SceneRuntime {
     for (const actor of this.getActors()) {
       this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
     }
+    // Behaviors have expressed their intent (velocities, forces) for this frame;
+    // now let registered systems advance (e.g. physics integrates, writes results
+    // back to Layout, and dispatches collision callbacks).
+    for (const system of this.systems) {
+      system.afterBehaviors?.(this, dt);
+    }
   }
 
   forEachBehavior(actor, callback) {
@@ -299,7 +320,12 @@ export class SceneRuntime {
 }
 
 export function makeScene(sceneData, behaviors, sprites, files) {
-  return new SceneRuntime(sceneData, behaviors, sprites, files);
+  const runtime = new SceneRuntime(sceneData, behaviors, sprites, files);
+  // Install any runtime systems the kit provides (systems/*.js) -- no-op in a kit
+  // with none. A system's engine is created lazily on first use, so draw-only
+  // editor previews (which never call update) stay free.
+  for (const install of systemInstallers) install(runtime);
+  return runtime;
 }
 
 export function setActorComponent(sceneData, actorId, behaviorName, nextProps) {

package/kits/basic-2d/engine/systemRegistry.js

@@ -0,0 +1,12 @@
+// Discover per-frame runtime systems from `systems/*.js`. Each such module
+// exports `installSystem(runtime)`, which is called once for every created
+// SceneRuntime (see engine/scene.js `makeScene`) to register itself via
+// `runtime.registerSystem(...)`. A system is a plain object with an optional
+// `afterBehaviors(scene, dt)` hook, run once per frame after all behavior
+// updates. Empty in a kit with no `systems/` dir (e.g. basic-2d); a kit adds a
+// system by dropping a file here -- no edits to the engine required. Symmetric
+// with editors/behaviorRegistry.js.
+const modules = import.meta.glob('../systems/*.js', { eager: true });
+export const systemInstallers = Object.values(modules)
+  .map((mod) => mod.installSystem)
+  .filter((fn) => typeof fn === 'function');

package/kits/basic-2d/engine/ui.jsx

@@ -13,6 +13,7 @@ import {
   faCode,
   faCodeBranch,
   faEraser,
+  faExternalLinkAlt,
   faEyeDropper,
   faFile,
   faFilm,
@@ -179,6 +180,7 @@ const icons = {
   // FA5 has no faCodeFork (that's the FA6 name); faCodeBranch is the fork glyph.
   'code-fork': faCodeBranch,
   eraser: faEraser,
+  external: faExternalLinkAlt,
   eyedropper: faEyeDropper,
   fill: faFillDrip,
   'flip-h': faArrowsAltH,

package/kits/basic-2d/main.jsx

@@ -15,9 +15,10 @@ if (!root) throw new Error('Missing root element');
 //   ?file=<path>[&editor=<id>] -> a single rich editor for that file
 const params = new URLSearchParams(window.location.search);
 function pick() {
-  if (!isEdit()) return <PlayOnly />;
+  const initialScene = params.get('scene') ?? undefined;
+  if (!isEdit()) return <PlayOnly initialScene={initialScene} />;
   const file = params.get('file');
   if (file) return <SingleEditor path={file} editor={params.get('editor') ?? undefined} />;
-  return <PlayOnly />;
+  return <PlayOnly initialScene={initialScene} />;
 }
 createRoot(root).render(<ErrorBoundary>{pick()}</ErrorBoundary>);

package/kits/physics-2d/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "bracketSameLine": true,
+  "trailingComma": "es5",
+  "arrowParens": "always"
+}

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

@@ -0,0 +1,329 @@
+# physics-2d kit
+
+This is the `basic-2d` actor/behavior/scene framework plus a built-in 2D
+**physics** system (matter-js). Everything in `basic-2d` works the same; physics
+adds `RigidBody`, physics fields on `Collider`, a world-gravity scene setting,
+collision callbacks, and ready-made touch-first controls (`Draggable`,
+`Slingshot`, `AnalogStick`). 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.
+
+Do you already know what you want to make, or do you want to figure it out together?
+
+## Quick reference
+
+<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
+
+- Actor / behavior / scene framework on a fixed 500x700 canvas ("card").
+- 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.
+- 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.
+- Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
+
+## Scope
+
+Write the smallest game that satisfies what the user asked for. No sound, particles, menus, multi-level progression, or visual polish unless they specifically asked for it. A typical behavior is 30–80 lines — if yours is hitting 200, you're over-engineering: cut feel-good extras, fewer fields on props, fewer edge cases, fewer comments. Ship the core loop first; the user can ask for more.
+
+## Workflow
+
+The deck is already serving when you start (`castle-web init` set that up; see `.castle/serve.json` for the URL). The user is watching that page right now. Your job is to make it interesting incrementally:
+
+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.
+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).
+
+## Behavior shape
+
+A behavior is a class. Minimal contract:
+
+```jsx
+// behaviors/MyThing.jsx
+export class MyThing {
+  static behaviorName = 'MyThing'; // must match the key used in .scene
+  static defaultProps = { speed: 200 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Called every frame in play mode. dt is seconds.
+  update(actor, scene, dt) {
+    const layout = actor.components.Layout;
+    layout.x += this.props.speed * dt; // mutate component in place
+  }
+
+  // Optional. Custom drawing (you usually don't need this; use a Sprite
+  // component instead). ctx is in card units already.
+  draw(actor, scene, ctx) {}
+
+  // Optional. Return React nodes for game-time HUD. Coordinates are card
+  // units. Read state your `update` set; do not start your own loops.
+  ui(actor, scene) {
+    return null;
+  }
+}
+```
+
+A fresh `Behavior` instance is constructed per actor per frame from the actor's component props — DO NOT store per-actor state on `this`. Persist transient state on `actor.runtime` (a free-form object the framework will not serialize) or on the component props themselves.
+
+## Scene file (`scenes/main.scene`, plain JSON)
+
+A scene is a background plus a list of actors. Every actor is an **instance of a blueprint** (see `## Blueprints`): a `blueprint` path plus sparse `components` overrides — usually just its `Layout` position:
+
+```json
+{
+  "background": "#1b2030",
+  "actors": [
+    { "id": "paddle", "blueprint": "blueprints/paddle.scene", "components": { "Layout": { "x": 200, "y": 650 } } },
+    { "id": "brick-1", "blueprint": "blueprints/brick.scene", "components": { "Layout": { "x": 50, "y": 75 } } },
+    { "id": "brick-2", "blueprint": "blueprints/brick.scene", "components": { "Layout": { "x": 100, "y": 75 } } }
+  ]
+}
+```
+
+Rules: every actor needs a unique `id` (any string). An instance's `components` holds ONLY props that differ from its blueprint (merged per-property on top of the template); anything unspecified falls back to the blueprint, then to the behavior's `defaultProps`. Position (`Layout.x`/`y`/`rotation`) always lives on the instance. Omit optional fields (`z`, `rotation`, actor `name`, `tint: '#ffffffff'`, scene `name`) to keep scenes compact, especially when generating many actors.
+
+## Blueprints
+
+A **blueprint** is a `.scene` file under `blueprints/` whose single actor (`actors[0]`, no `id`) is the template:
+
+```json
+{
+  "name": "Brick",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 50, "height": 25 },
+        "Sprite": { "file": "drawings/brick.pxart" },
+        "Collider": { "kind": "solid" },
+        "Brick": {}
+      }
+    }
+  ]
+}
+```
+
+Template `components` keys are behavior names (the `static behaviorName`); add a behavior to a kind of actor by adding its key here, remove it by deleting the key. The template almost always has a `Layout` with `width`/`height` (instances supply `x`/`y`).
+
+- **Author one blueprint per kind of thing** — `blueprints/<meaningful>.scene` with a real `"name"` — and place instances that reference it. Do this even for a one-off actor: it costs one small file and keeps the deck's blueprint library intentional.
+- Editing a blueprint file changes every instance that doesn't override that prop, across every scene — so one `blueprints/player.scene` referenced from every level stays in sync everywhere. Editing an instance's own `Layout.x`/`y`/`rotation` never touches the blueprint (position/rotation are always instance-local — see `Layout.jsx`'s `propertyMeta`).
+- **Never write inline actors** (full `components`, no `blueprint` field). They aren't a lighter-weight alternative: the editor auto-migrates every such actor into its OWN new blueprint file the first time a human opens the scene — mechanically, one blueprint per actor, no dedup. That migration is a compatibility net for pre-blueprint decks, not an authoring workflow; leaning on it turns 10 inline enemies into 10 junk blueprints.
+- Never invent your own `blueprint` path pointing at a file you didn't also create — a dangling reference resolves to "no template" (the instance's own sparse `components` render alone, missing whatever it expected to inherit).
+
+## 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.
+  - **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:
+
+  ```jsx
+  for (const other of scene.getActors()) {
+    if (other.id === actor.id) continue;
+    if (scene.overlaps(actor, other)) {
+      /* react */
+    }
+  }
+  ```
+
+- **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).
+
+## Physics
+
+This kit simulates 2D physics with matter-js. You get gravity, collisions,
+bouncing, friction, and forces without hand-writing an integrator. The rule of
+thumb: **give an actor a `Collider` to make it collide; add a `RigidBody` to
+make it move.**
+
+### Making things physical
+
+- **`Collider`** — required for any physics participant. Beyond the base fields
+  (`mode`, `width`/`height`, `offsetX`/`offsetY`, `debug`) it has:
+  - `shape: 'box' | 'circle'` — the physics shape (default `box`). A circle uses
+    `radius`, or half the smaller collider dimension if `radius` is 0.
+  - `isTrigger` — a **sensor**: detects overlaps (fires collision callbacks) but
+    does **not** block. Use for pickups, goals, zones.
+  - `bounciness` — restitution, 0 (dead) to ~1 (very bouncy), can exceed 1.
+  - `friction` — surface friction (default 0.1).
+  - A `Collider` **without** a `RigidBody` is a static obstacle (walls, floors).
+- **`RigidBody`** — makes an actor move under physics:
+  - `bodyType: 'dynamic' | 'static' | 'kinematic'`. `dynamic` = simulated
+    (gravity, collisions, forces). `static` = never moves (same as a lone
+    Collider). `kinematic` = unpushable, but you move it by writing its Layout.
+  - `gravityScale` — multiplies world gravity for this body (`0` = floats).
+  - `drag` — linear damping (air resistance). `angularDrag` — spin damping.
+  - `freezeRotation` — keep it from rotating (stays upright).
+  - `velocityX` / `velocityY` — initial velocity, applied once when play starts.
+
+### World gravity
+
+Set it per-scene in the `.scene` file: `"physics": { "gravity": 1 }` (matter
+units; `1` is a gentle fall, `0` is zero-g, higher falls faster). `gravityX`
+tilts it sideways. Omit for the default (`1`, downward).
+
+### Driving physics from behaviors — `scene.physics`
+
+In a behavior's `update`, steer bodies through `scene.physics` (never write
+`Layout` directly for a dynamic body — the sim owns its transform):
+
+- `scene.physics.setVelocity(actor, { x, y })` — set velocity (px per fixed
+  step; multiply by ~60 for px/s).
+- `scene.physics.applyImpulse(actor, { x, y })` — add to velocity this frame.
+- `scene.physics.applyForce(actor, { x, y })` — add a matter-space force.
+- `scene.physics.getVelocity(actor)` — current velocity `{ x, y }`.
+- `scene.physics.isColliding(a, b)` — are these two actors touching right now?
+
+### Collision callbacks
+
+A behavior can implement these; the physics system calls them on both actors of
+a contact — every pair, including static-vs-static and moving kinematic bodies
+(and sensor overlaps). For a quick one-off "are these two touching right now?"
+without callbacks, use `scene.physics.isColliding(a, b)`. (`scene.overlaps(a, b)`
+also exists but is a cheaper *bounding-box* test — not shape-accurate; prefer
+the physics calls for physics actors.)
+
+```jsx
+export class Coin {
+  static behaviorName = 'Coin';
+  onCollisionEnter(actor, scene, other) {
+    if (other.components.Player) scene.despawnActor(actor.id); // collected
+  }
+  onCollisionExit(actor, scene, other) {}
+}
+```
+
+### Built-in controls (add these behaviors, no code needed)
+
+These read input and drive the actor through the physics system, so the actor
+still collides with the world. Each needs a `RigidBody` (dynamic) + `Collider`.
+Controls are **touch/pointer-first** (Castle games are played on mobile first;
+touch degrades to mouse). Keyboard, if added, should only *duplicate* an
+on-screen control -- never be the only way to play.
+
+- **`Draggable`** — grab the actor with the pointer and fling it (springy,
+  collides). `stiffness`.
+- **`Slingshot`** — press the actor, pull back, release to launch it the
+  opposite way (angry-birds), with an aim arrow. `speed`, `maxDrag`.
+- **`AnalogStick`** — on-screen virtual joystick (press anywhere) that drives
+  the actor. `speed`, `maxRadius`, `axes`. Best for top-down.
+
+### Recipe: a launch-and-bounce game
+
+- Ball blueprint: `Layout` (square), `Sprite`, `Collider {shape:'circle',
+  bounciness:0.6}`, `RigidBody {bodyType:'dynamic'}`, `Slingshot {}`.
+- Walls/floor blueprint: `Layout`, `Collider {bounciness:0.4}` (no RigidBody →
+  static).
+- Goal blueprint: `Collider {isTrigger:true}` + a `Goal` behavior with
+  `onCollisionEnter` that scores when `other` is the ball.
+- Scene: set `"physics": { "gravity": 1 }`, place one ball, walls, a goal.
+
+### Gotchas
+
+- **Fast bodies + thin walls tunnel.** A small body moving faster than a static
+  wall is thick (per simulation step, ~a body-speed of `speed*maxDrag` for a
+  Slingshot) can pass straight through it — matter-js has no continuous
+  collision. Keep boundary walls thick (50px+) and/or cap launch power. The
+  demo scene uses 50px walls with a ~20px/step launch cap.
+- **Don't move a dynamic body by writing `Layout`.** The simulation owns a
+  dynamic body's transform and overwrites `Layout` every frame — use
+  `scene.physics.setVelocity/applyImpulse/applyForce`. Writing `Layout`
+  directly is only for `static`/`kinematic` bodies.
+- **Editor vs play.** Physics only steps during play; in the editor actors sit
+  where you place them. `RigidBody.velocityX/Y` apply once when play starts.
+
+## Adding physics to another kit
+
+The physics module (`physics/`) is self-contained and portable. To add it to a
+different kit:
+
+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, and, at the end of
+   `update(dt)`, `for (const s of this.systems) s.afterBehaviors?.(this, dt);`),
+   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.
+
+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).
+
+## Creating pixel art (`.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>.pxart`.
+
+- **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:
+
+  `#e69c69` `#bf6f4a` `#8a4836` `#391f21` `#891e2b` `#ea323c` `#ffa214` `#ffeb57` `#5ac54f` `#1e6f50` `#134c4c` `#657392` `#c7cfdd` `#ffffff` `#0cf1ff` `#0098dc`
+
+  (Off-palette fills are snapped to the nearest of these, so stay on-palette to keep what you intend. People editing in the app can paint with the full Endesga-64 palette; only this generation path is constrained to the 16.)
+- **Run it** (sprite name as the arg; stdin is the svg):
+
+  ```bash
+  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).
+
+Point a `Sprite` component's `file` at the generated `drawings/<name>.pxart` to put the art on an actor.
+
+## SceneRuntime API (what `scene` exposes to behaviors)
+
+- `scene.time` — seconds since start.
+- `scene.keys` — `Set` of currently-held KeyboardEvent codes (e.g. `'ArrowLeft'`, `'KeyA'`, `'Space'`). Read in `update`.
+- `scene.pointer` — `{ x, y, down }` in world (card) coordinates, camera-adjusted.
+- `scene.getActor(id)` / `scene.getActors()` (sorted by Layout.z) / `scene.getComponent(actor, name)`.
+- `scene.actorWith('GameController')` / `scene.actorsWith('Brick')` — find one / all actors carrying a given behavior. Prefer these to `getActors().find(a => a.components.X)`.
+- `scene.colliderRect(actorOrId)` — rect from Layout + Collider, or null.
+- `scene.overlaps(a, b)` — true when two actors/ids with Collider overlap.
+- `scene.data` — the live scene data. Mutate `actor.components.X = {...}` to change props.
+- `scene.spawnActor({ components: { Layout: {...}, MyBehavior: {...} } })` — add a new actor at runtime with fully-specified components (no blueprint). Returns the actor (with auto-minted `id` and `runtime = {}`). Use this; don't push to `scene.data.actors` by hand.
+- `scene.spawnFromBlueprint('blueprints/enemy.scene', { components: { Layout: { x, y } } })` — spawn an instance of a blueprint, same merge semantics as a placed instance. Prefer this over `spawnActor` when you're spawning copies of something that has (or should have) a blueprint, e.g. `scene.spawnFromBlueprint(actor.blueprint, { components: { Layout: { x: actor.components.Layout.x, y: actor.components.Layout.y } } })` to spawn another of the same kind as an existing actor.
+- `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
+- `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
+- `scene.load(sceneData)` — replace the running scene with the given scene data object.
+- `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
+- `scene.loadFromFile(name)` — read a scene file and transition the running scene to it. The way to switch screens/levels and to restart, e.g. `scene.loadFromFile('main.scene')`.
+- `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
+
+## Input shortcuts
+
+```jsx
+if (scene.keys.has('ArrowLeft')) layout.x -= speed * dt;
+if (scene.keys.has('ArrowRight')) layout.x += speed * dt;
+if (scene.keys.has('KeyX')) /* launch ball */ ;
+```
+
+**Space is reserved** — the editor binds it to the play/stop toggle, so don't bind Space to a gameplay action (jump / shoot / launch / ...). Use arrows, WASD, letter keys, or on-screen buttons instead.
+
+For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`.
+
+## Common breakout-shaped recipe (sketch)
+
+- `Paddle` behavior: read keys, clamp x to `[0, 500 - layout.width]`.
+- `Ball` behavior: store `vx, vy` on `actor.runtime`; integrate; bounce off wall edges (`x<0`, `x+w>500`, `y<0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `y > 700` lose a life.
+- `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `actor.runtime` or the brick's own props.
+- `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `ui()`.
+
+## Don't
+
+- Don't `console.log` in tight loops — flood the serve log.
+- Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
+- Don't try to import from `editors/`; behaviors run in the play runtime too.
+- Don't add types or `.ts`/`.tsx` files. This kit is JavaScript.
+- Don't add a build step or change `vite.config.js` for a game — it's configured for you.

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

@@ -0,0 +1,43 @@
+import { cardSize } from '../engine/scene';
+
+// Follow camera: keeps the target actor centered in the viewport, clamped to
+// the room bounds so the empty area past the room edges never scrolls in.
+export class Camera {
+  static behaviorName = 'Camera';
+
+  static defaultProps = {
+    target: '',
+    followX: true,
+    followY: true,
+    roomWidth: 900,
+    roomHeight: 1100,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(_actor, scene) {
+    const target = this.props.target ? scene.getActor(this.props.target) : undefined;
+    const targetLayout = target?.components.Layout;
+    if (!targetLayout) return;
+
+    const centerX = targetLayout.x + targetLayout.width / 2;
+    const centerY = targetLayout.y + targetLayout.height / 2;
+    const desiredX = centerX - cardSize.width / 2;
+    const desiredY = centerY - cardSize.height / 2;
+
+    scene.camera = {
+      x: this.props.followX
+        ? clamp(desiredX, 0, this.props.roomWidth - cardSize.width)
+        : 0,
+      y: this.props.followY
+        ? clamp(desiredY, 0, this.props.roomHeight - cardSize.height)
+        : 0,
+    };
+  }
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(Math.max(min, max), value));
+}