castle-web-cli 0.4.94 → 0.4.95

package/dist/init.js

@@ -36,7 +36,7 @@ const DEFAULT_KIT = "basic-2d";
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = "0.4.10";
+const PUBLISHED_SDK_VERSION = "0.4.11";
 // Never copied into a fresh deck: build/dependency junk. castle.json IS copied
 // (the kit ships a config-only one with the editor layout / file filters), but
 // `scaffoldFromKit` strips any identity fields off it first -- a fresh deck has

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

@@ -3,8 +3,9 @@
 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.
+collision callbacks, `Joints` that link actors (spring/rod/pin/weld/rope, several
+per actor), and ready-made touch-first controls (`Draggable`, `Slingshot`, `AnalogStick`).
+See `## Physics` below.
 
 ## Welcome message
 
@@ -27,6 +28,25 @@ Do you already know what you want to make, or do you want to figure it out toget
 - 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`.
 
+## Files and imports
+
+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
+  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
+  kit's drawing once the kit is imported by someone else.
+- `@imports/<alias>/drawings/ship.pxart` -- 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.
+
+Imports are read-only: their files belong to the deck they came from. Use them,
+don't edit them. `castle-web add-import <deckId>` adds one, `update-import`
+re-fetches it. `resolveDeckFile` from `castle-web-sdk` is the rule itself, if a
+behavior needs to resolve a path it was handed.
+
 ## 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.
@@ -152,6 +172,10 @@ make it move.**
   (`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.
+  - A collider can hold **multiple shapes** (a compound body) — edit them in the
+    inspector's shape list. A **box shape takes an `angle`** (degrees), so one
+    actor can have an angled collider (e.g. a skateboard: a flat deck box plus an
+    upturned nose and tail box) instead of gluing separate actors together.
   - `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.
@@ -228,6 +252,83 @@ on-screen control -- never be the only way to play.
   `onCollisionEnter` that scores when `other` is the ball.
 - Scene: set `"physics": { "gravity": 1 }`, place one ball, walls, a goal.
 
+### Joints (link actors together)
+
+Add a **`Joints`** behavior to connect an actor to one or more `target` actors
+with physics links. The component holds a **list**, so one actor can carry
+several links at once (a ragdoll pelvis pinned to both thighs, a ball slung
+between two anchors, a body both sprung and roped). Both actors of a link need a
+`Collider` (to have a body); the owner is usually a dynamic `RigidBody` and each
+target either dynamic or a static anchor (a lone `Collider`). Each list entry:
+
+- `type` — the link's feel:
+  - `spring` — soft elastic tether (`springiness` 0..1 + `damping`).
+  - `rod` — rigid fixed-distance stick; the ends still rotate freely. This is also
+    your **hinge**: a `rod` to a static anchor is a pendulum / swinging door.
+  - `weld` — fused rigid: a pivot link plus frozen rotation, so the two bodies
+    can't move or turn relative to each other. Place them slightly apart.
+  - `rope` — slack, taut only at `length` (max); the bob free-falls then catches.
+  - (`pin`, a free-rotating coincident-pivot hinge, was removed — a length-0
+    revolute between two dynamic bodies is matter's most unstable case. Use `rod`.)
+- `target` — the other actor's id. **Author it per instance** (pick it on the
+  canvas — see below), not on a blueprint, unless every instance really should
+  link to the same actor (e.g. many things roped to one anchor).
+- `length` — rest length (spring/rod) or max length (rope) in px. In the
+  inspector, turn **Auto length** on to lock it to the actors' distance when play
+  starts (stored as `-1`). Not used by `pin`/`weld`.
+- `springiness` (0..1) — for `spring`, how bouncy the tether is; for `rope`, how
+  it behaves *when taut*: `0` = a dead rope (holds firm at max length), `1` = a
+  bungee (stretches well past and springs back).
+- `damping` (0..1, spring only) — how fast the spring's oscillation settles.
+- `anchorX/anchorY` (+ `targetAnchorX/targetAnchorY` for spring/rod/rope) —
+  attach-point offsets in px, under the inspector's **Anchor offsets** toggle. For
+  `pin`/`weld` the owner offset moves the shared pivot.
+
+**Author a joint:** add the `Joints` behavior to the owner, then in the inspector
+click **Pick target** and click the other actor on the canvas (Esc / empty click
+cancels). **+ Add joint** appends another link; each has its own Remove. Links
+draw as colored overlays (coil = spring, dashed = rope, double line = weld, ring =
+pin, plain line = rod) so you can see what's connected. In the scene file it's a
+list: `"Joints": { "list": [ { "type": "rod", "target": "anchor" }, … ] }`.
+
+`target` is instance-local (a blueprint-level target points every instance at the
+same actor — only what you want for a shared anchor). You rarely need multiple
+entries: a chain A–B–C just puts one link on B→A and one on C→B. Reach for a
+multi-entry list when an actor genuinely connects to two+ others at once.
+
+Recipe — pendulum: a static `anchor` actor (Collider, no RigidBody) at top, a
+dynamic ball below with `Joints { list: [{ type: 'rod', target: 'anchor' }] }`.
+The ball swings at a fixed radius. Swap `rod`→`rope` for a slack tether,
+`rod`→`spring` for a bouncy one; add a second entry to sling it between two
+anchors.
+
+**How a joint looks in play** — each entry has a `render`:
+
+- `line` (default) — the schematic overlay (coil/dashed/etc.). Good for
+  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`
+  (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
+  visibly stretches. The editor previews it WYSIWYG.
+
+**Custom joint visuals (draw your own):** for anything beyond the built-in art,
+set the joint's `render: 'hidden'` and draw it yourself from a behavior's
+`draw()` using `scene.physics.getJoints()`. It returns one entry per link with
+world-space endpoints so your art lines up with the sprites:
+
+```jsx
+draw(actor, scene, ctx) {
+  for (const j of scene.physics.getJoints()) {
+    // j = { ownerId, targetId, type, a:{x,y}, b:{x,y}, length, angle }
+    ctx.strokeStyle = '#0cf1ff';
+    ctx.beginPath(); ctx.moveTo(j.a.x, j.a.y); ctx.lineTo(j.b.x, j.b.y); ctx.stroke();
+  }
+}
+```
+
 ### Gotchas
 
 - **Fast bodies + thin walls tunnel.** A small body moving faster than a static
@@ -241,6 +342,12 @@ on-screen control -- never be the only way to play.
   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.
+- **A joint binds only when both actors have a body.** If a `Joints` entry's
+  owner or `target` has no `Collider` (or the target id is wrong/missing), that
+  link is silently skipped until both bodies exist. `weld`/`pin` want the two
+  actors placed a little apart, not overlapping.
+- **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
 
@@ -250,10 +357,13 @@ 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).
+   (`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.
 

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

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
 import { NumberField, Panel, SelectField } from '../engine/ui';
 import { AutoFields } from '../engine/autoInspector';
 import { computeAutoFit, getColliderRect, getColliderShapes, intersects } from '../engine/collider';
@@ -61,6 +61,13 @@ function drawShape(ctx, s) {
     for (let k = 1; k < s.points.length; k++) ctx.lineTo(s.points[k].x, s.points[k].y);
     ctx.closePath();
     ctx.stroke();
+  } else if (s.angle) {
+    // Rotate the outline about the box center to match the (angled) matter part.
+    ctx.save();
+    ctx.translate(s.cx, s.cy);
+    ctx.rotate((s.angle * Math.PI) / 180);
+    ctx.strokeRect(-s.width / 2 + 1, -s.height / 2 + 1, s.width - 2, s.height - 2);
+    ctx.restore();
   } else {
     ctx.strokeRect(s.x + 1, s.y + 1, s.width - 2, s.height - 2);
   }
@@ -113,14 +120,21 @@ export class Collider {
     const shapes = getColliderShapes(actor);
     if (!shapes) return;
     const isSensor = Boolean(this.props.isTrigger) || this.props.kind === 'pickup';
+    // When editing this blueprint (hotbar), highlight the shape the inspector has
+    // selected so you can tell which chip is which on its lit instances -- the
+    // selected-instance path does this via the SelectionOverlay instead.
+    const highlight = blueprintSelected ? options.colliderShapeSel ?? -1 : -1;
     ctx.save();
-    ctx.strokeStyle = isSensor ? '#ffe17a' : '#8db7ff';
-    ctx.lineWidth = 2;
-    for (const s of shapes) drawShape(ctx, s);
+    shapes.forEach((s, k) => {
+      const on = k === highlight;
+      ctx.strokeStyle = on ? '#ffd24a' : isSensor ? '#ffe17a' : '#8db7ff';
+      ctx.lineWidth = on ? 3.5 : 2;
+      drawShape(ctx, s);
+    });
     ctx.restore();
   }
 
-  static Inspector({ actor, component, sprites, setComponent, override }) {
+  static Inspector({ actor, component, sprites, setComponent, override, onSelectShape }) {
     const [sel, setSel] = useState(0);
     const [addOpen, setAddOpen] = useState(false);
     const layout = actor?.components?.Layout ?? {};
@@ -129,6 +143,9 @@ export class Collider {
 
     const shapes = currentShapes(component);
     const i = Math.min(sel, shapes.length - 1);
+    // Report the selected shape index up so the on-canvas overlay can highlight
+    // it (fires on mount with 0, and on every chip click / add / remove).
+    useEffect(() => onSelectShape?.(i), [i, onSelectShape]);
     const shape = shapes[i];
     const isCircle = shape.type === 'circle';
     const isPoly = shape.type === 'triangle' || shape.type === 'polygon';
@@ -160,6 +177,22 @@ export class Collider {
     const offXPx = Math.round(((shape.x ?? 0.5) - 0.5) * bw);
     const offYPx = Math.round(((shape.y ?? 0.5) - 0.5) * bh);
 
+    // Per-subfield override state vs the blueprint's version of THIS shape. The
+    // shape fields don't go through AutoFields, so without this an instance that
+    // changed e.g. box 3's offset X wouldn't show the tint / Default / Reset.
+    // Null override (editing the blueprint template itself) shows nothing.
+    const bpShapes = override?.baseline?.('shapes');
+    const bShape = Array.isArray(bpShapes) ? bpShapes[i] : null;
+    const shapeOv = (key, dflt, toPx) => {
+      if (!bShape || bShape.type !== shape.type) return {};
+      const bv = bShape[key] ?? dflt;
+      return {
+        overridden: Math.abs((shape[key] ?? dflt) - bv) > 1e-4,
+        defaultValue: toPx(bv),
+        onReset: () => patchSel({ [key]: bv }),
+      };
+    };
+
     const density = component.density > 0 ? component.density : 0.001;
 
     // Auto-fit (box/circle) for the selected shape.
@@ -205,17 +238,50 @@ export class Collider {
           <>
             <SelectField label="Shape" value={shape.type} onChange={setType} options={['box', 'circle']} />
             {isCircle ? (
-              <NumberField label="Radius" value={radiusPx} onChange={(v) => patchSel({ r: v / Math.min(bw, bh) })} />
+              <NumberField
+                label="Radius"
+                value={radiusPx}
+                onChange={(v) => patchSel({ r: v / Math.min(bw, bh) })}
+                {...shapeOv('r', 0.5, (f) => Math.round(f * Math.min(bw, bh)))}
+              />
             ) : (
               <>
-                <NumberField label="Width" value={widthPx} onChange={(v) => patchSel({ w: v / bw })} />
-                <NumberField label="Height" value={heightPx} onChange={(v) => patchSel({ h: v / bh })} />
+                <NumberField
+                  label="Width"
+                  value={widthPx}
+                  onChange={(v) => patchSel({ w: v / bw })}
+                  {...shapeOv('w', 1, (f) => Math.round(f * bw))}
+                />
+                <NumberField
+                  label="Height"
+                  value={heightPx}
+                  onChange={(v) => patchSel({ h: v / bh })}
+                  {...shapeOv('h', 1, (f) => Math.round(f * bh))}
+                />
+                <NumberField
+                  label="Angle"
+                  value={Math.round(shape.angle ?? 0)}
+                  min={-180}
+                  max={180}
+                  onChange={(v) => patchSel({ angle: v })}
+                  {...shapeOv('angle', 0, (f) => Math.round(f))}
+                />
               </>
             )}
           </>
         )}
-        <NumberField label="Offset X" value={offXPx} onChange={(v) => patchSel({ x: 0.5 + v / bw })} />
-        <NumberField label="Offset Y" value={offYPx} onChange={(v) => patchSel({ y: 0.5 + v / bh })} />
+        <NumberField
+          label="Offset X"
+          value={offXPx}
+          onChange={(v) => patchSel({ x: 0.5 + v / bw })}
+          {...shapeOv('x', 0.5, (f) => Math.round((f - 0.5) * bw))}
+        />
+        <NumberField
+          label="Offset Y"
+          value={offYPx}
+          onChange={(v) => patchSel({ y: 0.5 + v / bh })}
+          {...shapeOv('y', 0.5, (f) => Math.round((f - 0.5) * bh))}
+        />
         <div style={actionRow}>
           {autoFit && !fitted ? (
             <button type="button" onClick={() => writeShapes(shapes.map((s, k) => (k === i ? autoFit : s)))} style={linkBtn}>

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

@@ -1,3 +1,4 @@
+import { resolveDeckFile } from 'castle-web-sdk';
 import React from 'react';
 import { frameCount, renderSpriteFrame } from '../engine/pxart';
 import { renderSmoothSpriteFrame } from '../engine/pxartSmooth';
@@ -37,7 +38,11 @@ export class Sprite {
   }
 
   resolveSprite(scene) {
-    return scene.sprites?.[this.props.file] ?? scene.sprites?.[FALLBACK_FILE] ?? null;
+    // `drawings/x.pxart` is this deck's; `@imports/<alias>/drawings/x.pxart` is
+    // an import's. (A value inherited from an imported blueprint arrives already
+    // resolved against that blueprint's deck -- see engine/blueprint.js.)
+    const file = resolveDeckFile(this.props.file);
+    return scene.sprites?.[file] ?? scene.sprites?.[FALLBACK_FILE] ?? null;
   }
 
   update(actor, scene, dt) {

package/kits/physics-2d/drawings/joint-rope.pxart

@@ -0,0 +1,26 @@
+{
+  "format": "compact",
+  "palette": {
+    "a": "#8a4836",
+    "b": "#bf6f4a",
+    "c": "#e69c69"
+  },
+  "grid": [
+    "................",
+    "................",
+    "................",
+    "..cc........cc..",
+    ".b..b......b..b.",
+    "a....a....a....a",
+    "......a..a......",
+    ".......aa.......",
+    ".......aa.......",
+    "......a..a......",
+    "a....a....a....a",
+    ".b..b......b..b.",
+    "..cc........cc..",
+    "................",
+    "................",
+    "................"
+  ]
+}

package/kits/physics-2d/editors/SceneEditor.jsx

@@ -161,6 +161,27 @@ export function SceneEditor({
   const editCameraRef = useRef(reloadStash?.editCamera ?? { x: 0, y: 0, zoom: 1 });
   const selectedActorIdsRef = useRef(selectedActorIds);
   selectedActorIdsRef.current = selectedActorIds;
+  // Transient "click an actor to pick it" mode, triggered by an inspector field
+  // (e.g. Joint's target picker). Holds `{ onPick }`; the next edit-canvas click
+  // resolves it with the clicked actor's id instead of selecting. A ref mirror
+  // lets the pointer gesture read it live without re-creating handlers.
+  const [pickRequest, setPickRequest] = useState(null);
+  const pickRequestRef = useRef(null);
+  pickRequestRef.current = pickRequest;
+  const beginPick = useCallback((onPick) => setPickRequest(onPick ? { onPick } : null), []);
+  useEffect(() => {
+    if (!pickRequest) return undefined;
+    const onKey = (e) => e.key === 'Escape' && setPickRequest(null);
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [pickRequest]);
+  // Which Collider shape the inspector has selected, so the on-canvas overlay can
+  // highlight it. The Collider inspector reports its index up via onSelectShape.
+  // A ref mirror feeds the draw loop (blueprint-lit instances highlight via the
+  // canvas draw); the SelectionOverlay reads the state directly.
+  const [colliderShapeSel, setColliderShapeSel] = useState(0);
+  const colliderShapeSelRef = useRef(colliderShapeSel);
+  colliderShapeSelRef.current = colliderShapeSel;
   const [isPlaying, setIsPlaying] = useState(reloadStash?.isPlaying ?? false);
   // Hotbar blueprint selection (tap a slot -> inspect/edit the blueprint in
   // the sidebar; drag remains the placement gesture). Mutually exclusive with
@@ -239,9 +260,19 @@ export function SceneEditor({
     marqueeRef,
     selectedActorIdsRef,
     selectedBlueprintPathRef,
+    colliderShapeSelRef,
   });
   const panGesture = usePanGesture({ canvasRef, editCameraRef, isPlaying });
   useScenePlayKeys(runtimeRef);
+  // Resolve an in-progress target pick: a click on the owner itself is ignored
+  // (a self-joint is meaningless); a click on empty space cancels.
+  const onPickTarget = (actorId) => {
+    const req = pickRequestRef.current;
+    if (!req) return;
+    if (actorId && actorId === selectedActorIdsRef.current[0]) return;
+    setPickRequest(null);
+    if (actorId) req.onPick(actorId);
+  };
   const gesture = useSelectionGesture({
     canvasRef,
     sceneData,
@@ -254,6 +285,8 @@ export function SceneEditor({
     onSetMultiSelectMode,
     marqueeRef,
     editCameraRef,
+    pickRequestRef,
+    onPickTarget,
     applyScene: (next) => onChange(serialize(next)),
     recordSceneSnapshot: history.recordSnapshot,
   });
@@ -549,6 +582,7 @@ export function SceneEditor({
                   previewSceneData={previewSceneData}
                   sprites={sprites}
                   selectedActorIds={selectedActorIds}
+                  selectedColliderShape={colliderShapeSel}
                   snap={snapSettings}
                   onArrange={isBlueprintFile ? undefined : actions.arrangeSelection}
                   onClone={isBlueprintFile ? undefined : actions.duplicateSelection}
@@ -594,6 +628,7 @@ export function SceneEditor({
                   onSetComponent={blueprintActions.setComponent}
                   onAddBehavior={blueprintActions.addBehavior}
                   onRemoveBehavior={blueprintActions.removeBehavior}
+                  onSelectShape={setColliderShapeSel}
                 />
               ) : showMulti ? (
                 <MultiSelectInspector
@@ -622,6 +657,9 @@ export function SceneEditor({
                       ? undefined
                       : () => onSelectBlueprint(rawSelectedActor.blueprint)
                   }
+                  onBeginPick={beginPick}
+                  pickActive={Boolean(pickRequest)}
+                  onSelectShape={setColliderShapeSel}
                 />
               ) : (
                 <SceneInspector
@@ -800,6 +838,13 @@ function useSelectionGesture(args) {
     const stack = scene.actorsAt(point.x, point.y);
     const stackIds = stack.map((a) => a.id);
     const actor = stack[0] ?? null;
+    // Target-pick mode swallows this click: resolve the pick with the clicked
+    // actor (or cancel on empty space) instead of selecting/dragging.
+    if (current.pickRequestRef?.current) {
+      current.canvasRef.current.releasePointerCapture?.(event.pointerId);
+      current.onPickTarget(actor?.id ?? null);
+      return;
+    }
     const drag = {
       pointerId: event.pointerId,
       startPoint: point,
@@ -1339,6 +1384,7 @@ function useScenePlayLoop({
   marqueeRef,
   selectedActorIdsRef,
   selectedBlueprintPathRef,
+  colliderShapeSelRef,
 }) {
   // Spin up / tear down the play-mode runtime as the user toggles play. `text`
   // is the stable identity for `sceneData` (which is re-parsed every render);
@@ -1398,6 +1444,9 @@ function useScenePlayLoop({
           useCamera: true,
           editPlaceholders: !isPlaying,
           dimBlueprintPath: isPlaying ? null : selectedBlueprintPathRef.current,
+          // Highlight the collider shape the blueprint inspector has selected on
+          // its lit instances.
+          colliderShapeSel: isPlaying ? -1 : colliderShapeSelRef?.current ?? -1,
         });
       }
       raf = requestAnimationFrame(frame);
@@ -1415,6 +1464,7 @@ function useScenePlayLoop({
     marqueeRef,
     selectedActorIdsRef,
     selectedBlueprintPathRef,
+    colliderShapeSelRef,
   ]);
 }
 function useScenePlayKeys(runtimeRef) {
@@ -1523,6 +1573,7 @@ function BlueprintInspector({
   onSetComponent,
   onAddBehavior,
   onRemoveBehavior,
+  onSelectShape,
 }) {
   const templateActor = { id: '__blueprint__', components: template.components };
   const instanceCount = countBlueprintInstances(files, blueprintPath);
@@ -1552,6 +1603,7 @@ function BlueprintInspector({
         onSetComponent={(actorId, behaviorName, nextProps) => onSetComponent(behaviorName, nextProps)}
         onAddBehavior={(actorId, behaviorName) => onAddBehavior(behaviorName)}
         onRemoveBehavior={(actorId, behaviorName) => onRemoveBehavior(behaviorName)}
+        onSelectShape={onSelectShape}
       />
     </>
   );
@@ -1593,6 +1645,9 @@ function ActorInspector({
   onRemoveBehavior,
   onFork,
   onEditBlueprint,
+  onBeginPick,
+  pickActive,
+  onSelectShape,
 }) {
   const isInstance = Boolean(rawActor?.blueprint);
   const presentNames = new Set(
@@ -1687,6 +1742,9 @@ function ActorInspector({
             sprites={sprites}
             setComponent={setComponent}
             override={override}
+            beginPick={onBeginPick}
+            pickActive={pickActive}
+            onSelectShape={onSelectShape}
           />
         ) : (
           <AutoInspector

package/kits/physics-2d/editors/SelectionOverlay.jsx

@@ -68,6 +68,7 @@ export function SelectionOverlay({
   previewSceneData,
   sprites,
   selectedActorIds,
+  selectedColliderShape,
   snap,
   onArrange,
   onClone,
@@ -198,6 +199,9 @@ export function SelectionOverlay({
 
   const geometry = getOverlayGeometry(frame, box, camera);
   const colliderFrames = getSelectedColliderFrames(previewSceneData, selectedActorIds, sprites);
+  // The collider inspector edits one shape of a single-selected actor; highlight
+  // that shape's box so you can see which one you're editing at a glance.
+  const editedColliderActor = selectedActorIds.length === 1 ? selectedActorIds[0] : null;
 
   return (
     <div ref={rootRef} className={styles.selOverlayRoot}>
@@ -211,24 +215,34 @@ export function SelectionOverlay({
         <div
           className={styles.selChromeWorld}
           style={{ transform: `translate(${-geometry.camX}px, ${-geometry.camY}px)` }}>
-          {colliderFrames.map((collider, i) => (
-            <div
-              key={`${collider.actorId}:${i}`}
-              className={cx(
-                styles.selColliderBox,
-                collider.isTrigger && styles.selColliderPickup
-              )}
-              style={{
-                left: collider.x,
-                top: collider.y,
-                width: collider.width,
-                height: collider.height,
-                borderRadius: collider.shape === 'circle' ? '50%' : undefined,
-                transformOrigin: `${collider.originX}px ${collider.originY}px`,
-                transform: `rotate(${collider.rotation}deg)`,
-              }}
-            />
-          ))}
+          {colliderFrames.map((collider, i) => {
+            const highlighted =
+              collider.actorId === editedColliderActor && collider.shapeIndex === selectedColliderShape;
+            return (
+              <div
+                key={`${collider.actorId}:${i}`}
+                className={cx(
+                  styles.selColliderBox,
+                  collider.isTrigger && styles.selColliderPickup
+                )}
+                style={{
+                  left: collider.x,
+                  top: collider.y,
+                  width: collider.width,
+                  height: collider.height,
+                  borderRadius: collider.shape === 'circle' ? '50%' : undefined,
+                  transformOrigin: '0 0',
+                  transform: colliderTransform(collider),
+                  // The shape being edited: a bright border + tint, lifted above
+                  // the others so an overlapping (e.g. skateboard) shape reads clearly.
+                  borderColor: highlighted ? '#ffd24a' : undefined,
+                  borderWidth: highlighted ? 3 : undefined,
+                  background: highlighted ? 'rgba(255, 210, 74, 0.14)' : undefined,
+                  zIndex: highlighted ? 1 : 0,
+                }}
+              />
+            );
+          })}
         </div>
       </div>
 
@@ -456,6 +470,19 @@ function getActionAnchor({ centerX, centerY, halfH, rotateAnchor }) {
   };
 }
 
+// Compose the collider box's on-screen transform (origin = box top-left): rotate
+// by the shape's own `angle` about its center, then by the actor's Layout.rotation
+// about the actor center. Both pivots explicit since they differ.
+function colliderTransform(c) {
+  const ax = c.originX;
+  const ay = c.originY;
+  const layout = `translate(${ax}px, ${ay}px) rotate(${c.rotation}deg) translate(${-ax}px, ${-ay}px)`;
+  if (!c.shapeAngle) return layout;
+  const cx = c.width / 2;
+  const cy = c.height / 2;
+  return `${layout} translate(${cx}px, ${cy}px) rotate(${c.shapeAngle}deg) translate(${-cx}px, ${-cy}px)`;
+}
+
 function getSelectedColliderFrames(sceneData, actorIds, sprites) {
   if (!sceneData || !actorIds || actorIds.length === 0) return [];
   const wanted = new Set(actorIds);
@@ -470,7 +497,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
       // One preview box per collider shape, from the shared geometry so the
       // preview matches the physics body. A circle renders as a radius-sized
       // square with border-radius; a triangle/polygon as its AABB (v1).
-      return shapes.map((s) => {
+      return shapes.map((s, shapeIndex) => {
         let kind = 'box';
         let x;
         let y;
@@ -505,6 +532,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
         }
         return {
           actorId: actor.id,
+          shapeIndex,
           shape: kind,
           isTrigger,
           x,
@@ -512,6 +540,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
           width,
           height,
           rotation: layout.rotation ?? 0,
+          shapeAngle: s.type === 'box' ? s.angle ?? 0 : 0,
           originX: layout.x + layout.width / 2 - x,
           originY: layout.y + layout.height / 2 - y,
         };

package/kits/physics-2d/editors/behaviorRegistry.js

@@ -3,9 +3,15 @@
 // picked up on the next reload/restart. The physics glob is what lets the
 // self-contained physics module ship its behaviors without polluting the core
 // `behaviors/` folder — a kit adopts physics by copying `physics/` in.
+// Root-anchored so the kit finds the DECK's behaviors even when the kit is
+// itself an import (see engine/files.js). Imports are swept first and the deck's
+// own behaviors last: collectBehaviors keys by behaviorName, so a behavior the
+// deck defines wins over one of the same name from a dependency.
 const modules = {
-  ...import.meta.glob('../behaviors/*.jsx', { eager: true }),
-  ...import.meta.glob('../physics/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/imports/*/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/imports/*/physics/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/physics/behaviors/*.jsx', { eager: true }),
 };
 function isBehaviorClass(value) {
   return typeof value === 'function' && typeof value.behaviorName === 'string';