castle-web-cli 0.4.94 → 0.4.95

package/kits/physics-2d/engine/blueprint.js

@@ -6,6 +6,7 @@
 // panel propagates to every scene that places it. Shared by the runtime
 // (`scene.js`, so play mode and `PlayOnly` resolve blueprints too) and the
 // editors (which also mint/fork/migrate/cascade-delete blueprint files).
+import { resolveDeckFile } from 'castle-web-sdk';
 import { formatJson } from './files';
 import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
 import { cardSize, dedupeActorId } from './scene';
@@ -13,8 +14,19 @@ import { cardSize, dedupeActorId } from './scene';
 export const BLUEPRINTS_DIR = 'blueprints';
 export const DRAWINGS_DIR = 'drawings';
 
+// A blueprint of this deck (`blueprints/x.scene`) OR of one it imports
+// (`imports/<alias>/blueprints/x.scene`) -- an imported deck's blueprints are
+// placeable like any other, which is most of the point of importing one.
+const BLUEPRINT_PATH_RE = new RegExp(`^(imports/[^/]+/)?${BLUEPRINTS_DIR}/`);
+
 export function isBlueprintPath(path) {
-  return typeof path === 'string' && path.startsWith(`${BLUEPRINTS_DIR}/`) && path.endsWith('.scene');
+  return typeof path === 'string' && path.endsWith('.scene') && BLUEPRINT_PATH_RE.test(path);
+}
+
+// Blueprints an import owns: placeable, but not editable or deletable from here
+// (they belong to the deck they came from).
+export function isImportedPath(path) {
+  return typeof path === 'string' && path.startsWith('imports/');
 }
 
 // Per-property inherit metadata for a behavior prop. Behaviors opt a prop out
@@ -49,12 +61,33 @@ function parseBlueprintText(text) {
   return { name, components: actor.components };
 }
 
+// A reference names a file the way its own deck sees it -- `drawings/rock.pxart`
+// for one of its own, `@imports/<alias>/...` for one of a deck it imports (the
+// SDK's resolveDeckFile is the single definition of that rule). Templates are
+// resolved against the file they were written in, so a kit's blueprint keeps
+// meaning the kit's drawing after the kit is imported by somebody else.
+function resolveTemplateRefs(template, files, fromPath) {
+  if (!template) return template;
+  for (const props of Object.values(template.components ?? {})) {
+    for (const [key, value] of Object.entries(props ?? {})) {
+      if (typeof value !== 'string' || !value) continue;
+      const resolved = resolveDeckFile(value, fromPath);
+      if (resolved !== value && files?.[resolved] !== undefined) props[key] = resolved;
+    }
+  }
+  return template;
+}
+
 // Resolve a blueprint's template from the LIVE files map -- the load-bearing
 // call for live propagation. Returns null when the file is missing, deleted,
 // or malformed (a dangling `blueprint` ref degrades to "no template" rather
 // than throwing).
 export function getBlueprintTemplate(files, blueprintPath) {
-  return parseBlueprintText(files?.[blueprintPath]);
+  // The ref may name this deck's blueprint or an import's; the template's own
+  // refs then resolve against whichever deck the blueprint turned out to be in.
+  const key = resolveDeckFile(blueprintPath);
+  const template = parseBlueprintText(files?.[key]);
+  return resolveTemplateRefs(template, files, key);
 }
 
 // Every blueprint currently in the deck, for the library/hotbar. Skips
@@ -63,7 +96,10 @@ export function listBlueprints(files) {
   const out = [];
   for (const path of Object.keys(files ?? {})) {
     if (!isBlueprintPath(path)) continue;
-    const template = parseBlueprintText(files[path]);
+    // Same origin resolution getBlueprintTemplate does: an imported blueprint's
+    // `drawings/x.pxart` means the import's drawing, and the library previews
+    // these templates -- unresolved, the slot renders with no art.
+    const template = resolveTemplateRefs(parseBlueprintText(files[path]), files, path);
     if (!template) continue;
     out.push({ path, name: template.name, components: template.components });
   }

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

@@ -5,7 +5,7 @@
 // A Collider is a LIST of shapes (`Collider.shapes`), each stored as a FRACTION
 // of the actor's Layout box -- so a collider keeps its relative size and position
 // when the box is resized (blueprint default OR per-instance override). Shapes:
-//   box:      { type:'box',      x, y, w, h }        center + size, fractions of box
+//   box:      { type:'box',      x, y, w, h, angle? } center + size (frac); angle deg
 //   circle:   { type:'circle',   x, y, r }           center frac; r = frac of min(box side)
 //   triangle: { type:'triangle', points:[{x,y}×3] }  fractions of box
 //   polygon:  { type:'polygon',  points:[{x,y}×N] }
@@ -140,7 +140,10 @@ function resolveShape(shape, layout) {
   const h = (shape.h ?? 1) * bh;
   const cx = wx(shape.x ?? 0.5);
   const cy = wy(shape.y ?? 0.5);
-  return { type: 'box', cx, cy, width: w, height: h, x: cx - w / 2, y: cy - h / 2 };
+  // `angle` (deg) rotates the box about its own center, within the unrotated box
+  // frame; Layout.rotation composes on top (matter body + draw ctx). `x`/`y` are
+  // the UNROTATED top-left -- shapeAabb widens them when angled.
+  return { type: 'box', cx, cy, width: w, height: h, x: cx - w / 2, y: cy - h / 2, angle: shape.angle ?? 0 };
 }
 
 // World-space shapes for an actor's collider (list), or null if no Layout/Collider.
@@ -172,7 +175,14 @@ function shapeAabb(s) {
     }
     return [x0, y0, x1, y1];
   }
-  return [s.x, s.y, s.x + s.width, s.y + s.height];
+  const ang = ((s.angle ?? 0) * Math.PI) / 180;
+  if (!ang) return [s.x, s.y, s.x + s.width, s.y + s.height];
+  // AABB of a box rotated about its center: project the half-extents onto the axes.
+  const c = Math.abs(Math.cos(ang));
+  const sn = Math.abs(Math.sin(ang));
+  const ex = (s.width / 2) * c + (s.height / 2) * sn;
+  const ey = (s.width / 2) * sn + (s.height / 2) * c;
+  return [s.cx - ex, s.cy - ey, s.cx + ex, s.cy + ey];
 }
 
 // AABB of the whole collider (union of all shapes), world units -- for

package/kits/physics-2d/engine/files.js

@@ -1,12 +1,33 @@
 // Seed the file map by scanning the deck dir. Vite module-cache is invalidated
 // on restart, so a newly-created file just shows up on the next reload.
-const rawModules = import.meta.glob(
-  ['../scenes/*.scene', '../blueprints/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
-  { query: '?raw', import: 'default', eager: true }
-);
+// Anchored at the DECK ROOT (`/scenes/...`) rather than relative to this module,
+// because the kit itself may be an import: living at `imports/<alias>/`, a
+// `../scenes/*.scene` would find the KIT's scenes instead of the deck's. Anchored
+// at the root, one pattern works whether the kit is the deck or a dependency.
+//
+// The first glob adds every import's content, keyed by its full path
+// (`imports/<alias>/drawings/rock.pxart`) -- which is exactly how a scene or
+// blueprint refers to a dependency's file, so no lookup elsewhere changes.
+// (Patterns and options must be literals: import.meta.glob is a compile-time
+// transform, so these can't be hoisted into shared constants.)
+const rawModules = {
+  ...import.meta.glob(
+    [
+      '/imports/*/scenes/*.scene',
+      '/imports/*/blueprints/*.scene',
+      '/imports/*/drawings/*.pxart',
+      '/imports/*/behaviors/*.jsx',
+    ],
+    { query: '?raw', import: 'default', eager: true }
+  ),
+  ...import.meta.glob(
+    ['/scenes/*.scene', '/blueprints/*.scene', '/drawings/*.pxart', '/behaviors/*.jsx'],
+    { query: '?raw', import: 'default', eager: true }
+  ),
+};
 export const initialFiles = Object.fromEntries(
   Object.entries(rawModules)
-    .map(([globPath, text]) => [globPath.replace(/^\.\.\//, ''), text])
+    .map(([globPath, text]) => [globPath.replace(/^\//, ''), text])
     .sort(([a], [b]) => a.localeCompare(b))
 );
 export function getFileKind(path) {

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

@@ -1,3 +1,4 @@
+import { resolveDeckFile } from 'castle-web-sdk';
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
 import { getColliderRect, intersects, spriteIsEmpty } from './collider';
@@ -18,7 +19,9 @@ export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
 // 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
 // `.scene` extension and a leading `scenes/` are both optional.
 function resolveSceneFileKey(name) {
-  const key = String(name).replace(/^\.?\//, '');
+  // `@imports/<alias>/scenes/x.scene` names an import's scene; anything else is
+  // this deck's, with the `scenes/` folder and `.scene` suffix both optional.
+  const key = resolveDeckFile(String(name));
   const candidates = [key];
   if (!key.endsWith('.scene')) candidates.push(`${key}.scene`);
   for (const candidate of [...candidates]) {
@@ -59,6 +62,11 @@ export class SceneRuntime {
   }
 
   load(sceneData) {
+    // Reset registered systems (e.g. physics) so a reload/restart/scene
+    // transition starts from the authored layout -- otherwise a system holding
+    // simulation state (body positions, joints) would carry it across the load.
+    // No-op on the constructor's first load, before any system is registered.
+    for (const system of this.systems) system.reset?.(this);
     this.data = structuredClone(sceneData);
     this.actors = new Map();
     for (const actor of this.data.actors ?? []) {

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

@@ -6,7 +6,11 @@
 // 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 });
+// Root-anchored, deck + imports (see engine/files.js).
+const modules = {
+  ...import.meta.glob('/imports/*/systems/*.js', { eager: true }),
+  ...import.meta.glob('/systems/*.js', { eager: true }),
+};
 export const systemInstallers = Object.values(modules)
   .map((mod) => mod.installSystem)
   .filter((fn) => typeof fn === 'function');

package/kits/physics-2d/package-lock.json

@@ -1,10 +1,10 @@
 {
-  "name": "basic-2d-js",
+  "name": "physics-2d",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "basic-2d-js",
+      "name": "physics-2d",
       "dependencies": {
         "@codemirror/commands": "^6.10.3",
         "@codemirror/lang-javascript": "^6.2.5",
@@ -15,6 +15,7 @@
         "@lezer/highlight": "^1.2.3",
         "castle-web-sdk": "file:../../sdk",
         "codemirror": "^6.0.2",
+        "matter-js": "^0.20.0",
         "react": "^19.2.4",
         "react-dom": "^19.2.4"
       },
@@ -27,7 +28,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.1",
+      "version": "0.4.11",
       "devDependencies": {
         "eslint": "^9.0.0",
         "jscpd": "^4.0.5",
@@ -1899,6 +1900,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/matter-js": {
+      "version": "0.20.0",
+      "resolved": "https://registry.npmjs.org/matter-js/-/matter-js-0.20.0.tgz",
+      "integrity": "sha512-iC9fYR7zVT3HppNnsFsp9XOoQdQN2tUyfaKg4CHLH8bN+j6GT4Gw7IH2rP0tflAebrHFw730RR3DkVSZRX8hwA==",
+      "license": "MIT"
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",

package/kits/physics-2d/physics/PhysicsSystem.js

@@ -9,6 +9,7 @@
 
 import Matter from 'matter-js';
 import { getColliderRect } from '../engine/collider';
+import { buildJointConstraints, jointSignature, patchJoint } from './joints';
 import {
   DEFAULT_GRAVITY,
   FIXED_STEP_MS,
@@ -18,6 +19,7 @@ import {
   applyAngularDrag,
   applyWorldGravity,
   bodySignature,
+  clampSpeeds,
   createBody,
   isPhysicsActor,
   patchBody,
@@ -29,6 +31,7 @@ export class PhysicsSystem {
   constructor() {
     this.engine = null;
     this.bodies = new Map(); // actorId -> { body, sig, offset: {dx, dy} }
+    this.joints = new Map(); // `${ownerId}#${listIndex}` -> { constraints, bodyA, bodyB, sig }
     this.intents = new Map(); // actorId -> { velocity?, impulse?, force? }
     this.gravity = { ...DEFAULT_GRAVITY };
     this.acc = 0;
@@ -44,6 +47,24 @@ export class PhysicsSystem {
     runtime.physics = this.makeApi();
   }
 
+  // Tear down all simulation state so the next step rebuilds from scratch. The
+  // runtime calls this from `scene.load()` -- a reload/restart/scene-transition
+  // must reset physics to the authored layout, otherwise bodies keep their last
+  // simulated positions and joints keep stale rest lengths (a reloaded scene
+  // would come back mid-fall / tangled instead of fresh). Dropping the engine
+  // lets `ensureEngine` build a clean one on the next step.
+  reset() {
+    this.engine = null;
+    this.bodies.clear();
+    this.joints.clear();
+    this.intents.clear();
+    this.active.clear();
+    this.ndActive.clear();
+    this.enterPairs.length = 0;
+    this.exitPairs.length = 0;
+    this.acc = 0;
+  }
+
   ensureEngine() {
     if (this.engine) return;
     this.engine = Matter.Engine.create();
@@ -63,9 +84,11 @@ export class PhysicsSystem {
   }
 
   afterBehaviors(scene, dt) {
+    this.lastScene = scene; // for the author-facing getJoints() API
     this.ensureEngine();
     this.readGravity(scene);
     this.reconcile(scene);
+    this.reconcileJoints(scene);
     this.applyIntents();
     this.syncStaticBodies(scene);
     this.step(dt);
@@ -103,6 +126,57 @@ export class PhysicsSystem {
     for (const id of [...this.bodies.keys()]) if (!seen.has(id)) this.removeBody(id);
   }
 
+  // Create/rebuild/remove joint constraints to match actors carrying a Joints
+  // list. Runs after body reconcile so both endpoints' bodies exist. Each list
+  // entry is tracked under `ownerId#index`; a joint whose owner or target has no
+  // body (yet), or whose target is missing/self, is skipped -- it binds
+  // automatically once both bodies appear.
+  reconcileJoints(scene) {
+    const seen = new Set();
+    for (const actor of scene.getActors()) {
+      const list = actor.components.Joints?.list;
+      if (!Array.isArray(list) || list.length === 0) continue;
+      const bodyA = this.bodies.get(actor.id)?.body;
+      if (!bodyA) continue;
+      list.forEach((joint, i) => {
+        if (!joint?.target || joint.target === actor.id) return;
+        const bodyB = this.bodies.get(joint.target)?.body;
+        if (!bodyB) return;
+        const key = `${actor.id}#${i}`;
+        seen.add(key);
+        const sig = jointSignature(joint);
+        const entry = this.joints.get(key);
+        // Rebuild on structural change or when either endpoint's body was rebuilt
+        // (a collider edit swaps the body object, orphaning the old constraint).
+        if (!entry || entry.sig !== sig || entry.bodyA !== bodyA || entry.bodyB !== bodyB) {
+          this.removeJoint(key);
+          this.addJoint(key, bodyA, bodyB, joint, sig);
+        } else patchJoint(entry.constraints, bodyA, bodyB, joint);
+        // A weld is a pivot link PLUS frozen rotation on both bodies, so they
+        // can't turn relative to each other -- a rigid, stable fuse. Re-applied
+        // each frame because patchBody's setDensity resets inertia to finite.
+        if ((joint.type ?? 'spring') === 'weld') {
+          Matter.Body.setInertia(bodyA, Infinity);
+          Matter.Body.setInertia(bodyB, Infinity);
+        }
+      });
+    }
+    for (const key of [...this.joints.keys()]) if (!seen.has(key)) this.removeJoint(key);
+  }
+
+  addJoint(id, bodyA, bodyB, joint, sig) {
+    const constraints = buildJointConstraints(bodyA, bodyB, joint);
+    for (const c of constraints) Matter.Composite.add(this.engine.world, c);
+    this.joints.set(id, { constraints, bodyA, bodyB, sig });
+  }
+
+  removeJoint(id) {
+    const entry = this.joints.get(id);
+    if (!entry) return;
+    for (const c of entry.constraints) Matter.Composite.remove(this.engine.world, c);
+    this.joints.delete(id);
+  }
+
   addBody(actor, rect) {
     const body = createBody(actor, rect);
     const center = rectCenter(rect);
@@ -163,6 +237,7 @@ export class PhysicsSystem {
       applyWorldGravity(dynamic, this.gravity);
       applyAngularDrag(dynamic);
       Matter.Engine.update(this.engine, FIXED_STEP_MS);
+      clampSpeeds(dynamic); // backstop: a joint blow-up can't fling a body off screen
       this.acc -= FIXED_STEP_S;
       steps += 1;
     }
@@ -275,8 +350,45 @@ export class PhysicsSystem {
         return this.active.has(pairKey(aId, bId));
       },
       bodyFor: (actor) => this.bodyOf(actor),
+      // Resolved joint geometry for custom rendering: each link's world-space
+      // endpoints (Layout centers, so art lines up with the sprites), type,
+      // length and angle. Draw your own art between `a` and `b` from a behavior's
+      // draw(); set the joint's `render: 'hidden'` so the built-in doesn't
+      // double-draw.
+      getJoints: () => this.collectJoints(),
     };
   }
+
+  collectJoints() {
+    const scene = this.lastScene;
+    if (!scene) return [];
+    const out = [];
+    for (const actor of scene.getActors()) {
+      const list = actor.components.Joints?.list;
+      if (!Array.isArray(list)) continue;
+      const a = centerOfLayout(actor.components.Layout);
+      for (const joint of list) {
+        const target = joint?.target && scene.getActor(joint.target);
+        if (!target || !a) continue;
+        const b = centerOfLayout(target.components.Layout);
+        if (!b) continue;
+        out.push({
+          ownerId: actor.id,
+          targetId: joint.target,
+          type: joint.type ?? 'spring',
+          a,
+          b,
+          length: Math.hypot(b.x - a.x, b.y - a.y),
+          angle: Math.atan2(b.y - a.y, b.x - a.x),
+        });
+      }
+    }
+    return out;
+  }
+}
+
+function centerOfLayout(L) {
+  return L ? { x: L.x + (L.width ?? 0) / 2, y: L.y + (L.height ?? 0) / 2 } : null;
 }
 
 function pairKey(a, b) {