npm - castle-web-cli - Versions diffs - 0.4.84 → 0.4.85 - Mend

castle-web-cli 0.4.84 → 0.4.85

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/dist/ide.js +35 -13
package/dist/shell/assets/{index-BOgm5T3W.js → index-BJLaUTJE.js} +21 -21
package/dist/shell/index.html +1 -1
package/kits/physics-2d/.prettierrc +8 -0
package/kits/physics-2d/CLAUDE.md +329 -0
package/kits/physics-2d/behaviors/Camera.jsx +43 -0
package/kits/physics-2d/behaviors/Collider.jsx +199 -0
package/kits/physics-2d/behaviors/Goal.jsx +29 -0
package/kits/physics-2d/behaviors/Layout.jsx +53 -0
package/kits/physics-2d/behaviors/Sprite.jsx +352 -0
package/kits/physics-2d/behaviors/tint.js +47 -0
package/kits/physics-2d/blueprints/ball.scene +14 -0
package/kits/physics-2d/blueprints/block.scene +12 -0
package/kits/physics-2d/blueprints/cauldron.scene +18 -0
package/kits/physics-2d/blueprints/crate.scene +14 -0
package/kits/physics-2d/blueprints/goal.scene +12 -0
package/kits/physics-2d/castle.json +13 -0
package/kits/physics-2d/docs/pxart-format.md +377 -0
package/kits/physics-2d/drawings/block.pxart +25 -0
package/kits/physics-2d/drawings/cauldron.pxart +113 -0
package/kits/physics-2d/editors/BlueprintLibrary.jsx +247 -0
package/kits/physics-2d/editors/ErrorBoundary.jsx +59 -0
package/kits/physics-2d/editors/PlayOnly.jsx +31 -0
package/kits/physics-2d/editors/PxArtEditor.jsx +954 -0
package/kits/physics-2d/editors/SceneEditor.jsx +1681 -0
package/kits/physics-2d/editors/SelectionOverlay.jsx +909 -0
package/kits/physics-2d/editors/SingleEditor.jsx +122 -0
package/kits/physics-2d/editors/behaviorRegistry.js +30 -0
package/kits/physics-2d/editors/editorHistory.js +157 -0
package/kits/physics-2d/editors/inspectorSheet.js +13 -0
package/kits/physics-2d/editors/pixelCanvas.js +11 -0
package/kits/physics-2d/editors/pixelEditorChrome.jsx +74 -0
package/kits/physics-2d/editors/pixelGeometry.js +140 -0
package/kits/physics-2d/editors/pixelInspector.jsx +633 -0
package/kits/physics-2d/editors/pxArtEditorModel.js +732 -0
package/kits/physics-2d/editors/pxArtPlayback.js +92 -0
package/kits/physics-2d/editors/pxArtTimeline.jsx +752 -0
package/kits/physics-2d/editors/pxArtTimeline.module.css +506 -0
package/kits/physics-2d/editors/pxArtTools.js +232 -0
package/kits/physics-2d/editors/useArtboardFit.js +102 -0
package/kits/physics-2d/engine/ScenePlayer.jsx +196 -0
package/kits/physics-2d/engine/SceneUI.jsx +59 -0
package/kits/physics-2d/engine/assets.js +15 -0
package/kits/physics-2d/engine/autoInspector.jsx +70 -0
package/kits/physics-2d/engine/blueprint.js +521 -0
package/kits/physics-2d/engine/collider.js +196 -0
package/kits/physics-2d/engine/files.js +117 -0
package/kits/physics-2d/engine/liveReload.js +88 -0
package/kits/physics-2d/engine/pxart.js +1032 -0
package/kits/physics-2d/engine/pxartSmooth.js +222 -0
package/kits/physics-2d/engine/scene.js +686 -0
package/kits/physics-2d/engine/spriteGeometry.js +32 -0
package/kits/physics-2d/engine/ui.jsx +688 -0
package/kits/physics-2d/engine/ui.module.css +2287 -0
package/kits/physics-2d/eslint.config.js +71 -0
package/kits/physics-2d/index.html +24 -0
package/kits/physics-2d/main.jsx +24 -0
package/kits/physics-2d/package-lock.json +2706 -0
package/kits/physics-2d/package.json +42 -0
package/kits/physics-2d/physics/PhysicsSystem.js +290 -0
package/kits/physics-2d/physics/behaviors/AnalogStick.jsx +101 -0
package/kits/physics-2d/physics/behaviors/Draggable.jsx +79 -0
package/kits/physics-2d/physics/behaviors/RigidBody.jsx +55 -0
package/kits/physics-2d/physics/behaviors/Slingshot.jsx +118 -0
package/kits/physics-2d/physics/controls.js +79 -0
package/kits/physics-2d/physics/index.js +26 -0
package/kits/physics-2d/physics/matterBridge.js +126 -0
package/kits/physics-2d/pnpm-lock.yaml +1761 -0
package/kits/physics-2d/scenes/main.scene +12 -0
package/kits/physics-2d/scenes/sandbox.scene +13 -0
package/kits/physics-2d/scripts/draw.mjs +121 -0
package/kits/physics-2d/vite.config.js +1 -0
package/package.json +1 -1

package/dist/shell/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Castle Editor</title>
-    <script type="module" crossorigin src="/__castle/ide/assets/index-BOgm5T3W.js"></script>
+    <script type="module" crossorigin src="/__castle/ide/assets/index-BJLaUTJE.js"></script>
     <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-DonnH--m.css">
   </head>
   <body>

package/kits/physics-2d/.prettierrc ADDED Viewed

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

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

@@ -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 ADDED Viewed

@@ -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));
+}

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

@@ -0,0 +1,199 @@
+import React, { useState } from 'react';
+import { Icon, NumberField, Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { computeAutoFit, getColliderRect, getColliderShape, intersects } from '../engine/collider';
+// Collapsible "Dimensions" section. The header row's label lines up exactly with
+// the field labels above/below (both start at the panel body's 16px left pad);
+// the open/closed caret floats in the left gutter without shifting the label.
+// `margin-bottom: 12px` matches a field row's `padding-bottom`, so the gap to
+// the next entry is the same whether the section is open or closed.
+const dimHeaderRowStyle = {
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 10,
+  minHeight: 28,
+  margin: '0 0 12px',
+};
+const dimToggleStyle = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  margin: 0,
+  color: 'var(--castle-inspector-text)',
+  fontFamily: 'inherit',
+  fontSize: 14,
+  cursor: 'pointer',
+};
+// The caret sits in the panel's left gutter (label column starts at x=16).
+const dimCaretStyle = {
+  position: 'absolute',
+  left: -14,
+  top: '50%',
+  transform: 'translateY(-50%)',
+  display: 'inline-flex',
+  alignItems: 'center',
+  fontSize: 11,
+  opacity: 0.65,
+};
+const autoFitLinkStyle = {
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  color: '#4aa3ff',
+  fontFamily: 'inherit',
+  fontSize: 13,
+  cursor: 'pointer',
+};
+const dimBodyStyle = { paddingLeft: 14 };
+export class Collider {
+  static behaviorName = 'Collider';
+  static defaultProps = {
+    shape: 'box',
+    // width/height/radius are intentionally NOT defaulted: an unset size means
+    // "match the actor's Layout box" (see engine/collider.js manualRect and the
+    // effective values in the inspector). Defaulting them to a fixed number made
+    // every collider shrink to that number instead of tracking the actor.
+    radius: 0,
+    offsetX: 0,
+    offsetY: 0,
+    // Physics material (used by the physics simulation; ignored by plain
+    // scene.overlaps checks). `isTrigger` = a sensor: detects overlaps but
+    // doesn't block. `bounciness` = restitution (0..1+). `friction` = surface
+    // friction.
+    isTrigger: false,
+    bounciness: 0,
+    friction: 0.1,
+    debug: false,
+  };
+  constructor(props) {
+    this.props = props;
+  }
+  draw(actor, scene, ctx, options) {
+    if (!options.showDebugColliders && !this.props.debug) return;
+    const geom = getColliderShape(actor, scene.sprites);
+    if (!geom) return;
+    // A sensor (isTrigger) reads as a pass-through zone; a solid as a wall.
+    const isSensor = Boolean(this.props.isTrigger) || this.props.kind === 'pickup';
+    ctx.save();
+    ctx.strokeStyle = isSensor ? '#ffe17a' : '#8db7ff';
+    ctx.lineWidth = 2;
+    if (geom.shape === 'circle') {
+      ctx.beginPath();
+      ctx.arc(geom.cx, geom.cy, geom.radius, 0, Math.PI * 2);
+      ctx.stroke();
+    } else {
+      ctx.strokeRect(geom.x + 1, geom.y + 1, geom.width - 2, geom.height - 2);
+    }
+    ctx.restore();
+  }
+  static Inspector({ actor, component, sprites, setComponent, override }) {
+    const [dimOpen, setDimOpen] = useState(true);
+    const layout = actor?.components?.Layout ?? {};
+    const shape = component.shape ?? Collider.defaultProps.shape;
+    // Unset width/height/radius track the actor's Layout box; surface that
+    // effective value so a field never reads blank while the collider is sized.
+    const width = component.width ?? layout.width ?? 50;
+    const height = component.height ?? layout.height ?? 50;
+    const effectiveRadius = component.radius > 0 ? component.radius : Math.min(width, height) / 2;
+    // "Auto-fit to sprite": the explicit dims/offset that match the sprite's
+    // opaque-pixel bounds. Only offered when the collider isn't already fitted.
+    const autoFit = computeAutoFit(actor, sprites);
+    let autoFitPatch = null;
+    if (autoFit) {
+      autoFitPatch =
+        shape === 'circle'
+          ? { radius: Math.round(Math.min(autoFit.width, autoFit.height) / 2), offsetX: autoFit.offsetX, offsetY: autoFit.offsetY }
+          : { width: autoFit.width, height: autoFit.height, offsetX: autoFit.offsetX, offsetY: autoFit.offsetY };
+    }
+    const currentValue = (key) => {
+      if (key === 'radius') return effectiveRadius;
+      if (key === 'width') return width;
+      if (key === 'height') return height;
+      return component[key] ?? 0;
+    };
+    const alreadyFitted =
+      autoFitPatch && Object.entries(autoFitPatch).every(([key, value]) => Math.abs(currentValue(key) - value) < 0.6);
+    return (
+      <Panel title="Collider" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="Shape"
+          value={component.shape}
+          onChange={(value) => setComponent({ shape: value })}
+          options={['box', 'circle']}
+          {...overrideProps(override, 'shape')}
+        />
+        <div style={dimHeaderRowStyle}>
+          <span style={dimCaretStyle}>
+            <Icon name={dimOpen ? 'chevron-down' : 'chevron-right'} />
+          </span>
+          <button type="button" onClick={() => setDimOpen((open) => !open)} style={dimToggleStyle}>
+            Dimensions
+          </button>
+          {autoFitPatch && !alreadyFitted ? (
+            <button type="button" onClick={() => setComponent(autoFitPatch)} style={autoFitLinkStyle}>
+              Auto-fit to sprite
+            </button>
+          ) : null}
+        </div>
+        {dimOpen ? (
+          <div style={dimBodyStyle}>
+            {shape === 'circle' ? (
+              <NumberField
+                label="Radius"
+                value={effectiveRadius}
+                onChange={(value) => setComponent({ radius: value })}
+                {...overrideProps(override, 'radius')}
+              />
+            ) : (
+              <>
+                <NumberField
+                  label="Width"
+                  value={width}
+                  onChange={(value) => setComponent({ width: value })}
+                  {...overrideProps(override, 'width')}
+                />
+                <NumberField
+                  label="Height"
+                  value={height}
+                  onChange={(value) => setComponent({ height: value })}
+                  {...overrideProps(override, 'height')}
+                />
+              </>
+            )}
+            <AutoFields
+              defaultProps={Collider.defaultProps}
+              component={component}
+              setComponent={setComponent}
+              only={['offsetX', 'offsetY']}
+              override={override}
+            />
+          </div>
+        ) : null}
+        <AutoFields
+          defaultProps={Collider.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['shape', 'width', 'height', 'radius', 'offsetX', 'offsetY']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+// Re-exported for callers that need the rect / overlap test outside a running
+// scene (e.g. editors/SelectionOverlay.jsx, which passes the merged preview
+// actors plus the sprites map). See engine/collider.js for the single
+// implementation.
+export { getColliderRect, getColliderShape, intersects };

package/kits/physics-2d/behaviors/Goal.jsx ADDED Viewed

@@ -0,0 +1,29 @@
+// Goal: a sensor zone that counts when a physics body enters it, and flashes
+// green briefly. Demonstrates the physics collision callbacks + a Collider with
+// `isTrigger: true`. Put it on an actor with a Layout and a trigger Collider.
+export class Goal {
+  static behaviorName = 'Goal';
+  static defaultProps = {};
+  constructor(props) {
+    this.props = props;
+  }
+  onCollisionEnter(actor, scene, other) {
+    if (!other.components.RigidBody) return; // only score moving bodies
+    actor.runtime.scored = (actor.runtime.scored ?? 0) + 1;
+    actor.runtime.flashUntil = scene.time + 0.6;
+  }
+  draw(actor, scene, ctx) {
+    const layout = actor.components.Layout;
+    const lit = (actor.runtime.flashUntil ?? 0) > scene.time;
+    ctx.save();
+    ctx.strokeStyle = lit ? '#5ac54f' : 'rgba(255, 235, 87, 0.9)';
+    ctx.lineWidth = 4;
+    ctx.setLineDash([6, 4]);
+    ctx.strokeRect(layout.x + 2, layout.y + 2, layout.width - 4, layout.height - 4);
+    ctx.restore();
+  }
+}