castle-web-cli 0.4.93 → 0.4.95

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) {

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

@@ -0,0 +1,291 @@
+import React, { useState } from 'react';
+import { Panel, SelectField, NumberField, CheckboxField, Button } from '../../engine/ui';
+import { centerOf, inActorWorldSpace } from '../controls';
+import { JOINT_TYPES } from '../joints';
+import { drawJointArt } from '../jointArt';
+
+const RENDER_MODES = ['line', 'hidden', 'sprite'];
+// Bound anchor offsets (px, local frame). A large offset lengthens the pivot's
+// lever arm, which is what destabilizes a weld -- so the UI caps it well
+// inside the safe range rather than letting a broken value be typed.
+const ANCHOR_MAX = 120;
+
+// Joints: connect this actor to one or more `target` actors with physics links.
+// The component holds a LIST so an actor can carry several links at once (a
+// a body both sprung and roped, a truss node). Each entry picks a TYPE -- spring
+// (elastic), rod (rigid stick, ends rotate; also the hinge -- to a static anchor),
+// weld (fused, no relative rotation), rope (slack, taut at max length). The
+// simulation builds the matter constraints
+// (see physics/joints.js); this behavior owns the authoring UI + editor overlay.
+//
+// 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. `target`
+// is instance-local -- pick it per instance, since a blueprint-level target would
+// point every instance at the same actor.
+export class Joints {
+  static behaviorName = 'Joints';
+
+  static defaultProps = { list: [] };
+
+  // A freshly-added Joints behavior starts with one blank link to fill in.
+  static initialProps() {
+    return { list: [defaultJoint()] };
+  }
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Draw every link. In the EDITOR (options.editPlaceholders) it's an authoring
+  // overlay -- always shown so connections are visible, sprite-art previewed
+  // WYSIWYG, and even `hidden` joints drawn as a faint line so you don't lose
+  // them. In PLAY each joint's `render` decides: `hidden` (nothing), `line` (the
+  // schematic) or `sprite` (art along the joint). Drawn in world space so the
+  // link doesn't spin with the actor's rotation (see inActorWorldSpace).
+  draw(actor, scene, ctx, options) {
+    const list = Array.isArray(this.props.list) ? this.props.list : [];
+    if (!list.length) return;
+    const editing = Boolean(options.editPlaceholders);
+    const emphasized =
+      options.colliderOverlayIds?.includes(actor.id) ||
+      (Boolean(options.dimBlueprintPath) && actor.blueprint === options.dimBlueprintPath);
+    const a = centerOf(actor.components.Layout);
+    inActorWorldSpace(ctx, actor.components.Layout, (g) => {
+      for (const joint of list) {
+        const target = joint?.target && scene.getActor(joint.target);
+        if (!target || target.id === actor.id) continue;
+        const b = centerOf(target.components.Layout);
+        // hidden shows as a faint line in the editor, nothing in play.
+        let render = joint.render ?? 'line';
+        if (editing && render === 'hidden') render = 'line';
+        if (render === 'hidden') continue;
+        if (render === 'sprite' && drawJointArt(g, scene, joint, a, b)) continue;
+        g.globalAlpha = editing ? (emphasized ? 1 : 0.45) : 0.7;
+        g.strokeStyle = '#c9a9ff';
+        g.fillStyle = '#c9a9ff';
+        g.lineWidth = 2;
+        drawLink(g, a, b, joint.type ?? 'spring');
+        g.globalAlpha = 1;
+      }
+    });
+  }
+
+  static Inspector({ component, setComponent, override, beginPick, pickActive, files }) {
+    const list = Array.isArray(component.list) ? component.list : [];
+    const spriteFiles = Object.keys(files ?? {}).filter((f) => f.endsWith('.pxart'));
+    // Which entry's target-pick is live. Combined with the editor's global
+    // `pickActive` so a cancel (Esc/empty click) clears every entry's state.
+    const [pickingIndex, setPickingIndex] = useState(null);
+    const update = (next) => setComponent({ list: next });
+    const patchAt = (i, patch) => update(list.map((j, k) => (k === i ? { ...j, ...patch } : j)));
+    const onPickToggle = (i) => {
+      if (pickActive && pickingIndex === i) return beginPick?.(null);
+      setPickingIndex(i);
+      return beginPick?.((id) => patchAt(i, { target: id }));
+    };
+    return (
+      <Panel title="Joints" overridden={override?.anyOverridden()}>
+        {list.map((joint, i) => (
+          <JointEntry
+            key={i}
+            index={i}
+            joint={joint}
+            spriteFiles={spriteFiles}
+            active={pickActive && pickingIndex === i}
+            onPickToggle={() => onPickToggle(i)}
+            onPatch={(patch) => patchAt(i, patch)}
+            onRemove={() => update(list.filter((_, k) => k !== i))}
+          />
+        ))}
+        <Button onClick={() => update([...list, defaultJoint()])}>+ Add joint</Button>
+      </Panel>
+    );
+  }
+}
+
+function defaultJoint() {
+  return { type: 'spring', target: '', length: -1, springiness: 0.4, damping: 0.1, render: 'line' };
+}
+
+// One editable link in the list: type, target picker, type-specific fields, and
+// how it renders in play (line / hidden / sprite art along the joint).
+function JointEntry({ index, joint, spriteFiles, active, onPickToggle, onPatch, onRemove }) {
+  const [showAnchors, setShowAnchors] = useState(false);
+  const type = joint.type ?? 'spring';
+  const isPivot = type === 'weld';
+  const soft = type === 'spring' || type === 'rope';
+  const target = joint.target || '';
+  const render = joint.render ?? 'line';
+  const lengthAuto = (joint.length ?? -1) < 0;
+  const lengthLabel = type === 'rope' ? 'Max length (px)' : 'Length (px)';
+  return (
+    <div style={entryBox}>
+      <div style={entryHead}>
+        <strong style={entryTitle}>Joint {index + 1}</strong>
+        <button type="button" style={removeLink} onClick={onRemove}>
+          Remove
+        </button>
+      </div>
+      <SelectField label="Type" value={type} onChange={(t) => onPatch({ type: t })} options={JOINT_TYPES} />
+      <div style={targetRow}>
+        <span style={targetText}>
+          Target: <strong>{target || '(none)'}</strong>
+        </span>
+        <div style={{ display: 'flex', gap: 6 }}>
+          <Button active={active} onClick={onPickToggle}>
+            {active ? 'Click an actor…' : target ? 'Re-pick' : 'Pick target'}
+          </Button>
+          {target ? <Button onClick={() => onPatch({ target: '' })}>Clear</Button> : null}
+        </div>
+      </div>
+      {!isPivot ? (
+        <>
+          {/* Auto = -1 sentinel, but the UI expresses it as a checkbox so you
+              can't type a broken negative length. */}
+          <CheckboxField label="Auto length" checked={lengthAuto} onChange={(on) => onPatch({ length: on ? -1 : 100 })} />
+          {!lengthAuto ? (
+            <NumberField label={lengthLabel} value={joint.length} min={0} onChange={(v) => onPatch({ length: v })} />
+          ) : null}
+        </>
+      ) : null}
+      {soft ? (
+        <NumberField
+          label={type === 'rope' ? 'Springiness (0=dead → 1=bungee)' : 'Springiness'}
+          value={joint.springiness ?? 0.4}
+          min={0}
+          max={1}
+          step={0.05}
+          onChange={(v) => onPatch({ springiness: v })}
+        />
+      ) : null}
+      {type === 'spring' ? (
+        <NumberField
+          label="Damping"
+          value={joint.damping ?? 0.1}
+          min={0}
+          max={1}
+          step={0.05}
+          onChange={(v) => onPatch({ damping: v })}
+        />
+      ) : null}
+      <button type="button" style={anchorToggle} onClick={() => setShowAnchors((s) => !s)}>
+        {showAnchors ? '▾' : '▸'} Anchor offsets
+      </button>
+      {showAnchors ? <AnchorFields joint={joint} isPivot={isPivot} onPatch={onPatch} /> : null}
+      <SelectField label="Show in play" value={render} onChange={(v) => onPatch({ render: v })} options={RENDER_MODES} />
+      {render === 'sprite' ? (
+        <>
+          <SelectField
+            label="Art"
+            value={joint.sprite || ''}
+            onChange={(v) => onPatch({ sprite: v })}
+            options={['', ...spriteFiles]}
+          />
+          <NumberField label="Thickness" value={joint.thickness ?? 12} min={1} onChange={(v) => onPatch({ thickness: v })} />
+          <SelectField
+            label="Fit"
+            value={joint.fit ?? 'tile'}
+            onChange={(v) => onPatch({ fit: v })}
+            options={['tile', 'stretch']}
+          />
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+// Attach-point offsets (advanced, tucked behind a toggle). For weld the owner
+// offset moves the shared pivot; for spring/rod/rope the owner + target offsets
+// move each end's attach point. All bounded to ±ANCHOR_MAX.
+function AnchorFields({ joint, isPivot, onPatch }) {
+  const field = (label, key) => (
+    <NumberField
+      label={label}
+      value={joint[key] ?? 0}
+      min={-ANCHOR_MAX}
+      max={ANCHOR_MAX}
+      onChange={(v) => onPatch({ [key]: v })}
+    />
+  );
+  return isPivot ? (
+    <>
+      {field('Pivot offset X', 'anchorX')}
+      {field('Pivot offset Y', 'anchorY')}
+    </>
+  ) : (
+    <>
+      {field('Anchor X', 'anchorX')}
+      {field('Anchor Y', 'anchorY')}
+      {field('Target anchor X', 'targetAnchorX')}
+      {field('Target anchor Y', 'targetAnchorY')}
+    </>
+  );
+}
+
+const entryBox = { borderTop: '1px solid var(--castle-inspector-divider)', paddingTop: 8, marginBottom: 6 };
+const anchorToggle = {
+  background: 'none',
+  border: 'none',
+  padding: '2px 0',
+  margin: '2px 0 8px',
+  color: '#4aa3ff',
+  fontSize: 12,
+  cursor: 'pointer',
+};
+const entryHead = { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 6 };
+const entryTitle = { color: '#c9a9ff', fontSize: 13 };
+const removeLink = { background: 'none', border: 'none', padding: 0, color: '#ff7a7a', fontSize: 12, cursor: 'pointer' };
+const targetRow = { display: 'flex', flexDirection: 'column', gap: 6, margin: '4px 0 10px' };
+const targetText = { fontSize: 13, color: 'var(--castle-inspector-text)' };
+
+// Draw the link between two world points, styled by joint type: spring coils,
+// rope dashes, weld doubles the line, rod is a plain line.
+function drawLink(ctx, a, b, type) {
+  if (type === 'spring') return drawCoil(ctx, a, b);
+  if (type === 'rope') {
+    ctx.setLineDash([6, 5]);
+    line(ctx, a, b);
+    ctx.setLineDash([]);
+    return;
+  }
+  if (type === 'weld') return drawDouble(ctx, a, b);
+  line(ctx, a, b); // rod (and any fallthrough)
+}
+
+function line(ctx, a, b) {
+  ctx.beginPath();
+  ctx.moveTo(a.x, a.y);
+  ctx.lineTo(b.x, b.y);
+  ctx.stroke();
+}
+
+// Two parallel lines offset along the perpendicular -- the "fused" read.
+function drawDouble(ctx, a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const nx = (-dy / len) * 3;
+  const ny = (dx / len) * 3;
+  line(ctx, { x: a.x + nx, y: a.y + ny }, { x: b.x + nx, y: b.y + ny });
+  line(ctx, { x: a.x - nx, y: a.y - ny }, { x: b.x - nx, y: b.y - ny });
+}
+
+// A zig-zag coil between the endpoints, straight stubs at each end.
+function drawCoil(ctx, a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const px = -dy / len;
+  const py = dx / len;
+  const coils = Math.max(3, Math.min(10, Math.round(len / 22)));
+  const amp = 6;
+  ctx.beginPath();
+  ctx.moveTo(a.x, a.y);
+  for (let i = 1; i < coils; i++) {
+    const t = i / coils;
+    const side = i % 2 === 0 ? 1 : -1;
+    ctx.lineTo(a.x + dx * t + px * amp * side, a.y + dy * t + py * amp * side);
+  }
+  ctx.lineTo(b.x, b.y);
+  ctx.stroke();
+}

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

@@ -0,0 +1,57 @@
+// Draws a joint's `sprite` art along the segment between its two endpoints,
+// rotated to the joint's angle and scaled to its current length -- so a rope
+// visibly stretches as a spring extends. Two fits:
+//   tile    repeat a segment along the length (rope, chain)
+//   stretch one image end-to-end (stick, beam, plank)
+// Used by Joints.draw() for `render: 'sprite'`. Reuses the kit's pxart renderer;
+// a small WeakMap caches the native-resolution frame canvas per sprite object.
+
+/* global document */
+import { resolveDeckFile } from 'castle-web-sdk';
+import { renderSpriteFrame } from '../engine/pxart';
+
+export const DEFAULT_JOINT_SPRITE = 'drawings/joint-rope.pxart';
+
+const canvasCache = new WeakMap();
+function frameCanvas(sprite) {
+  let canvas = canvasCache.get(sprite);
+  if (!canvas) {
+    canvas = document.createElement('canvas');
+    renderSpriteFrame(sprite, 0, canvas);
+    canvasCache.set(sprite, canvas);
+  }
+  return canvas;
+}
+
+// Draw the art from world point `a` to `b`. Returns false if the sprite can't be
+// resolved (so the caller can fall back to the schematic line).
+export function drawJointArt(ctx, scene, joint, a, b) {
+  // `drawings/x.pxart` is this deck's; `@imports/<alias>/drawings/x.pxart` is an
+  // import's -- same rule the Sprite behavior follows.
+  const path = resolveDeckFile(joint.sprite || DEFAULT_JOINT_SPRITE);
+  const sprite = scene.sprites?.[path] ?? scene.sprites?.[DEFAULT_JOINT_SPRITE];
+  if (!sprite) return false;
+  const canvas = frameCanvas(sprite);
+  if (!canvas.width || !canvas.height) return false;
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const len = Math.hypot(dx, dy);
+  if (len < 1) return true;
+  const thickness = joint.thickness > 0 ? joint.thickness : 12;
+  ctx.save();
+  ctx.translate(a.x, a.y);
+  ctx.rotate(Math.atan2(dy, dx));
+  ctx.imageSmoothingEnabled = sprite.cornerRadius > 0;
+  const top = -thickness / 2;
+  if ((joint.fit ?? 'tile') === 'stretch') {
+    ctx.drawImage(canvas, 0, top, len, thickness);
+  } else {
+    const tileW = Math.max(2, thickness * (canvas.width / canvas.height));
+    ctx.beginPath();
+    ctx.rect(0, top, len, thickness);
+    ctx.clip();
+    for (let x = 0; x < len; x += tileW) ctx.drawImage(canvas, x, top, tileW, thickness);
+  }
+  ctx.restore();
+  return true;
+}