castle-web-cli 0.4.93 → 0.4.95

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

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

@@ -27,6 +27,13 @@ export const FIXED_STEP_MS = 1000 / 60;
 export const FIXED_STEP_S = FIXED_STEP_MS / 1000;
 export const MAX_STEPS_PER_FRAME = 5;
 
+// Hard cap on a body's speed (px per fixed step) -- a safety net so a constraint
+// blow-up (a stiff joint at a bad angle can inject huge velocity in one step)
+// can't fling a body off screen. Well above any intended motion (a slingshot
+// launch is ~20), so normal gameplay never touches it; it only ever engages to
+// bound a runaway.
+export const MAX_SPEED = 60;
+
 // World gravity in matter's own units. `scale` matches matter's internal
 // default; `y` is what a scene tunes (1 ~= a gentle arcade fall).
 export const DEFAULT_GRAVITY = { x: 0, y: 1, scale: 0.001 };
@@ -73,7 +80,10 @@ function shapeToPart(s) {
     if (part) return part;
     return Matter.Bodies.rectangle((x0 + x1) / 2, (y0 + y1) / 2, Math.max(1, x1 - x0), Math.max(1, y1 - y0));
   }
-  return Matter.Bodies.rectangle(s.cx, s.cy, Math.max(1, s.width), Math.max(1, s.height));
+  // `s.angle` (deg) rotates the box part about its center at creation; the
+  // compound body's Layout.rotation composes on top.
+  const opts = s.angle ? { angle: s.angle * DEG_TO_RAD } : undefined;
+  return Matter.Bodies.rectangle(s.cx, s.cy, Math.max(1, s.width), Math.max(1, s.height), opts);
 }
 
 // Structural signature: when this changes we rebuild the body (shape set / sizes
@@ -87,7 +97,7 @@ export function bodySignature(actor) {
       s.type === 'circle'
         ? `c${Math.round(s.radius)}`
         : s.type === 'box'
-          ? `b${Math.round(s.width)}x${Math.round(s.height)}`
+          ? `b${Math.round(s.width)}x${Math.round(s.height)}@${Math.round(s.angle ?? 0)}`
           : `${s.type[0]}${(s.points ?? []).length}`
     )
     .join(',');
@@ -173,3 +183,13 @@ export function applyAngularDrag(bodies) {
     if (drag > 0 && !body.isStatic) body.angularVelocity *= Math.max(0, 1 - drag * FIXED_STEP_S);
   }
 }
+
+// Safety clamp: bound each body's speed to MAX_SPEED so a constraint blow-up
+// can't fling it off screen. Run right after each Engine.update.
+export function clampSpeeds(bodies) {
+  for (const body of bodies) {
+    if (body.isStatic) continue;
+    const s = Math.hypot(body.velocity.x, body.velocity.y);
+    if (s > MAX_SPEED) Matter.Body.setVelocity(body, { x: (body.velocity.x / s) * MAX_SPEED, y: (body.velocity.y / s) * MAX_SPEED });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.93",
+  "version": "0.4.95",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"