castle-web-cli 0.4.94 → 0.4.96

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

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

@@ -0,0 +1,136 @@
+// Joints connect two physics actors with matter-js constraints. matter has one
+// primitive -- Matter.Constraint (a point-to-point distance link with stiffness
+// / damping / length) -- so every joint TYPE here is composed from one or two of
+// them:
+//
+//   spring  soft elastic tether            1 constraint, low stiffness, at rest length
+//   rod     rigid fixed-distance link      1 constraint, high stiffness, free rotation
+//   weld    fused, no relative rotation     1 zero-length pivot + frozen rotation
+//   rope    slack, taut only at max length  1 constraint, stiffness toggled per step
+//
+// The joint lives on the OWNER actor (bodyA) and points at a `target` actor
+// (bodyB). Anchors are px offsets in each body's local (unrotated) frame; default
+// (0,0) attaches at the body center. Geometry is resolved against the live matter
+// bodies, so a joint tracks whatever the collider/rigidbody reconcile produced.
+
+import Matter from 'matter-js';
+
+// No `pin` (free-rotating coincident-pivot hinge): a length-0 revolute between two
+// dynamic bodies is matter's most unstable case and no tuning made it robust. Use
+// `rod` (to a static anchor) for a hinge / pendulum instead.
+export const JOINT_TYPES = ['spring', 'rod', 'weld', 'rope'];
+
+const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+
+// A body-local point (unrotated frame) -> world, and the inverse. matter rotates
+// a constraint's local point by the body angle when solving, so we store points
+// in that same local frame.
+function toWorld(body, local) {
+  return Matter.Vector.add(body.position, Matter.Vector.rotate(local, body.angle));
+}
+function toLocal(body, world) {
+  return Matter.Vector.rotate(sub(world, body.position), -body.angle);
+}
+
+// springiness (0..1) -> matter stiffness. Kept low so springs read as springs;
+// rigid types use a fixed high stiffness instead.
+function springStiffness(springiness) {
+  const s = Math.min(1, Math.max(0, springiness ?? 0.4));
+  return 0.002 + s * 0.05;
+}
+
+// Rope stiffness WHEN TAUT, from `springiness`: 0 = a dead rope (stiff 0.9, holds
+// firm at max length), 1 = a bungee (very soft ~0.002, stretches well past and
+// springs back). Geometric interpolation -- a light body barely stretches a stiff
+// constraint, so the useful range is tiny stiffnesses and a linear map would waste
+// most of the slider in the "firm" zone.
+function ropeStiffness(springiness) {
+  const s = Math.min(1, Math.max(0, springiness ?? 0));
+  return 0.9 * Math.pow(0.0025, s);
+}
+
+function ownerAnchorLocal(joint) {
+  return { x: joint.anchorX ?? 0, y: joint.anchorY ?? 0 };
+}
+function targetAnchorLocal(joint) {
+  return { x: joint.targetAnchorX ?? 0, y: joint.targetAnchorY ?? 0 };
+}
+
+// Structural signature: a change here rebuilds the constraint set; everything
+// else (length, springiness, damping) is live-patched in place.
+export function jointSignature(joint) {
+  const a = ownerAnchorLocal(joint);
+  const b = targetAnchorLocal(joint);
+  return `${joint.type ?? 'spring'}|${joint.target ?? ''}|${a.x},${a.y}|${b.x},${b.y}`;
+}
+
+// Distance between the two resolved anchor world points right now.
+function anchorGap(bodyA, bodyB, joint) {
+  const wa = toWorld(bodyA, ownerAnchorLocal(joint));
+  const wb = toWorld(bodyB, targetAnchorLocal(joint));
+  return Matter.Vector.magnitude(sub(wa, wb));
+}
+
+// The rest/target length for distance-style joints: authored `length`, or the
+// current gap when length is auto (-1).
+function restLength(bodyA, bodyB, joint) {
+  const len = joint.length ?? -1;
+  return len >= 0 ? len : anchorGap(bodyA, bodyB, joint);
+}
+
+// Build the matter constraint(s) for a joint. `weld` is a single zero-length
+// pivot link; PhysicsSystem additionally freezes both bodies' rotation so they
+// can't turn relative to each other (a rigid fuse). A single stable pivot avoids
+// the numerical blow-up that two fighting stiff length-0 links cause under
+// collision, especially with a diagonal offset.
+export function buildJointConstraints(bodyA, bodyB, joint) {
+  const type = joint.type ?? 'spring';
+  if (type === 'weld') return [pivotConstraint(bodyA, bodyB, joint)];
+  const pointA = ownerAnchorLocal(joint);
+  const pointB = targetAnchorLocal(joint);
+  const length = restLength(bodyA, bodyB, joint);
+  const stiffness =
+    type === 'spring' ? springStiffness(joint.springiness) : type === 'rope' ? ropeStiffness(joint.springiness) : 0.9;
+  // Rope carries no damping so a bungee actually bounces; spring/rod use theirs.
+  const damping = type === 'rope' ? 0 : joint.damping ?? 0.1;
+  return [Matter.Constraint.create({ bodyA, bodyB, pointA, pointB, length, stiffness, damping })];
+}
+
+// Zero-length link at the midpoint of the two centers, shifted by the owner
+// anchor -- the position half of a weld (rotation is frozen separately). 0.7 is
+// firm but below matter's length-0 instability threshold; the velocity clamp in
+// PhysicsSystem backstops any residual runaway.
+function pivotConstraint(bodyA, bodyB, joint) {
+  const a = ownerAnchorLocal(joint);
+  const pivotWorld = {
+    x: (bodyA.position.x + bodyB.position.x) / 2 + a.x,
+    y: (bodyA.position.y + bodyB.position.y) / 2 + a.y,
+  };
+  return Matter.Constraint.create({
+    bodyA,
+    bodyB,
+    pointA: toLocal(bodyA, pivotWorld),
+    pointB: toLocal(bodyB, pivotWorld),
+    length: 0,
+    stiffness: 0.7,
+    damping: 0.1,
+  });
+}
+
+// Live-patch the mutable feel of an existing constraint set (no rebuild). Rope is
+// one-sided: it pulls only when stretched past its length (stiffness from
+// `springiness` -- dead rope to bungee), and goes fully slack (zero stiffness)
+// when closer -- matter has no native max-only constraint.
+export function patchJoint(constraints, bodyA, bodyB, joint) {
+  const type = joint.type ?? 'spring';
+  if (type === 'weld') return;
+  const c = constraints[0];
+  if (!c) return;
+  if ((joint.length ?? -1) >= 0) c.length = joint.length;
+  if (type === 'spring') {
+    c.stiffness = springStiffness(joint.springiness);
+    c.damping = joint.damping ?? 0.1;
+  } else if (type === 'rope') {
+    c.stiffness = anchorGap(bodyA, bodyB, joint) > c.length ? ropeStiffness(joint.springiness) : 0;
+  }
+}