castle-web-cli 0.4.94 → 0.4.95

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

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.94",
+  "version": "0.4.95",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"