castle-web-cli 0.4.84 → 0.4.85

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

@@ -0,0 +1,79 @@
+// Pure control math shared by the touch-first physics control behaviors
+// (Draggable, Slingshot, AnalogStick). No React or DOM here, so it stays simple
+// to reason about and unit-testable outside a browser. The .jsx behaviors are
+// thin wrappers: read input + runtime state, call these, push the result
+// through scene.physics. (Controls are touch/pointer-first; keyboard, when
+// added, should only DUPLICATE an on-screen control, never be the only input.)
+
+export function centerOf(layout) {
+  return { x: layout.x + layout.width / 2, y: layout.y + layout.height / 2 };
+}
+
+export function length(v) {
+  return Math.hypot(v.x, v.y);
+}
+
+// Clamp a vector's magnitude to `max` (keeps direction).
+export function clampLength(v, max) {
+  const len = length(v);
+  if (len <= max || len === 0) return { x: v.x, y: v.y };
+  const s = max / len;
+  return { x: v.x * s, y: v.y * s };
+}
+
+// Springy chase velocity toward a target point (Draggable): a fraction of the
+// gap per step, so the body accelerates toward the pointer and still collides.
+export function chaseVelocity(target, layout, props = {}) {
+  const stiffness = props.stiffness ?? 0.5;
+  const c = centerOf(layout);
+  return { x: (target.x - c.x) * stiffness, y: (target.y - c.y) * stiffness };
+}
+
+// Run `draw(ctx)` in world space, undoing the actor's Layout rotation that the
+// runtime applies about the actor's center. Overlay controls (Slingshot,
+// AnalogStick) use this so their on-screen UI stays anchored where the user
+// pressed instead of rotating/sliding with the actor.
+export function inActorWorldSpace(ctx, layout, draw) {
+  const rot = layout?.rotation ?? 0;
+  ctx.save();
+  if (rot) {
+    const cx = layout.x + layout.width / 2;
+    const cy = layout.y + layout.height / 2;
+    ctx.translate(cx, cy);
+    ctx.rotate((-rot * Math.PI) / 180);
+    ctx.translate(-cx, -cy);
+  }
+  draw(ctx);
+  ctx.restore();
+}
+
+// Slingshot: how far the pointer is pulled from the anchor, clamped to maxDrag.
+// This is the "pull" vector; the launch flings the opposite way.
+export function slingPull(anchor, pointer, maxDrag = 160) {
+  return clampLength({ x: pointer.x - anchor.x, y: pointer.y - anchor.y }, maxDrag);
+}
+
+// Launch velocity when the slingshot is released: opposite the pull, scaled.
+export function slingLaunch(anchor, pointer, props = {}) {
+  const speed = props.speed ?? 0.08;
+  const pull = slingPull(anchor, pointer, props.maxDrag ?? 160);
+  return { x: -pull.x * speed, y: -pull.y * speed };
+}
+
+// AnalogStick: stick displacement from its origin, clamped to maxRadius.
+export function stickVector(pointer, origin, maxRadius = 60) {
+  return clampLength({ x: pointer.x - origin.x, y: pointer.y - origin.y }, maxRadius);
+}
+
+// Velocity a virtual stick commands: proportional to displacement/maxRadius,
+// up to `speed`, restricted to the enabled axes.
+export function analogVelocity(pointer, origin, props = {}) {
+  const speed = props.speed ?? 6;
+  const maxRadius = props.maxRadius ?? 60;
+  const axes = props.axes ?? 'both';
+  const v = stickVector(pointer, origin, maxRadius);
+  const out = { x: (v.x / maxRadius) * speed, y: (v.y / maxRadius) * speed };
+  if (axes === 'horizontal') out.y = 0;
+  if (axes === 'vertical') out.x = 0;
+  return out;
+}

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

@@ -0,0 +1,26 @@
+// Entry point for the self-contained physics module.
+//
+// To add physics to another kit:
+//   1. Copy this `physics/` folder into the kit.
+//   2. Add `matter-js` to the kit's package.json dependencies.
+//   3. In the kit's engine/scene.js: add a systems registry (`this.systems`,
+//      `registerSystem`, and an `afterBehaviors` call in `update`), then call
+//      `installPhysics(runtime)` from `makeScene`.
+//   4. In the kit's editors/behaviorRegistry, also glob `../physics/behaviors/*.jsx`.
+//
+// The behaviors themselves (RigidBody, Collider extensions, controls) live in
+// `physics/behaviors/` and are auto-discovered by the registry.
+
+import { PhysicsSystem } from './PhysicsSystem';
+
+// Register a physics system on a runtime and wire up `runtime.physics`.
+// Returns the system. Cheap to call on every runtime -- the matter engine is
+// created lazily on the first simulation step.
+export function installPhysics(runtime) {
+  const system = new PhysicsSystem();
+  runtime.registerSystem(system);
+  system.attach(runtime);
+  return system;
+}
+
+export { PhysicsSystem };

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

@@ -0,0 +1,126 @@
+// Pure helpers bridging Cauldron actors (Layout + Collider + RigidBody
+// components) to matter-js bodies. No engine state lives here -- the
+// PhysicsSystem owns the world and calls these, feeding in the collider rect it
+// gets from the kit's engine/collider.js (the single source of truth for
+// collider geometry, including sprite-fit `auto` mode).
+//
+// Coordinate systems:
+//  - Cauldron Layout: top-left origin, +y down, `rotation` in degrees CW.
+//  - matter-js Body:  centroid origin, +y down, `angle` in radians.
+// Rotation converts by DEG<->RAD; position via the body's cached center-offset
+// from Layout's top-left (see PhysicsSystem).
+//
+// matter-js unit notes (see Body defaults): `frictionAir` is linear damping,
+// `restitution` is bounciness, `friction` is contact friction. There is no
+// native per-body gravity multiplier and no kinematic body type -- both are
+// emulated here (applyWorldGravity, and kinematic == static-moved-from-Layout).
+
+import Matter from 'matter-js';
+
+export const DEG_TO_RAD = Math.PI / 180;
+export const RAD_TO_DEG = 180 / Math.PI;
+
+// Fixed simulation step. matter-js is tuned for a constant delta in
+// milliseconds and pixel-space coordinates -- our card is already in pixels.
+export const FIXED_STEP_MS = 1000 / 60;
+export const FIXED_STEP_S = FIXED_STEP_MS / 1000;
+export const MAX_STEPS_PER_FRAME = 5;
+
+// 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 };
+
+// An actor participates in physics if it has a Collider (+ Layout). A RigidBody
+// makes it move (dynamic/kinematic); a Collider alone is a static obstacle.
+export function isPhysicsActor(actor) {
+  return Boolean(actor?.components?.Collider && actor?.components?.Layout);
+}
+
+export function rigidBodyType(actor) {
+  const rb = actor?.components?.RigidBody;
+  if (!rb) return 'static';
+  return rb.bodyType ?? 'dynamic';
+}
+
+export function rectCenter(rect) {
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+
+function bodyRadius(actor, rect) {
+  // `radius` of 0 (the default) means "derive from the collider size" -- note
+  // `??` won't do here since 0 is a real number; a 0 radius would be a
+  // degenerate, zero-mass body that NaNs the simulation.
+  const r = actor.components.Collider.radius;
+  return r && r > 0 ? r : Math.min(rect.width, rect.height) / 2;
+}
+
+// Structural signature: when this changes we rebuild the body (shape/size/type)
+// rather than live-patching material props in place.
+export function bodySignature(actor, rect) {
+  const shape = actor.components.Collider.shape ?? 'box';
+  const dims =
+    shape === 'circle'
+      ? `r${Math.round(bodyRadius(actor, rect))}`
+      : `${Math.round(rect.width)}x${Math.round(rect.height)}`;
+  return `${shape}|${dims}|${rigidBodyType(actor)}`;
+}
+
+// Build a fresh matter body at the collider rect's center, oriented by Layout.
+export function createBody(actor, rect) {
+  const center = rectCenter(rect);
+  const options = { angle: (actor.components.Layout.rotation ?? 0) * DEG_TO_RAD };
+  const body =
+    (actor.components.Collider.shape ?? 'box') === 'circle'
+      ? Matter.Bodies.circle(center.x, center.y, bodyRadius(actor, rect), options)
+      : Matter.Bodies.rectangle(center.x, center.y, rect.width, rect.height, options);
+  body.plugin.actorId = actor.id;
+  Matter.Body.setStatic(body, rigidBodyType(actor) !== 'dynamic');
+  patchBody(body, actor);
+  const rb = actor.components.RigidBody;
+  if (rb && rigidBodyType(actor) === 'dynamic' && (rb.velocityX || rb.velocityY)) {
+    Matter.Body.setVelocity(body, { x: rb.velocityX ?? 0, y: rb.velocityY ?? 0 });
+  }
+  return body;
+}
+
+// Live-patch the mutable material/motion props (safe to call every step).
+export function patchBody(body, actor) {
+  const collider = actor.components.Collider;
+  const rb = actor.components.RigidBody;
+  body.restitution = collider.bounciness ?? 0;
+  body.friction = collider.friction ?? 0.1;
+  // `isTrigger` is the source of truth for solid-vs-sensor; legacy decks that
+  // used the retired `kind: 'pickup'` label are still honored as sensors.
+  body.isSensor = Boolean(collider.isTrigger || collider.kind === 'pickup');
+  body.frictionAir = rb?.drag ?? 0.01;
+  body.plugin.gravityScale = rb?.gravityScale ?? 1;
+  body.plugin.angularDrag = rb?.angularDrag ?? 0;
+  if (rb?.freezeRotation) Matter.Body.setInertia(body, Infinity);
+}
+
+// Push a static/kinematic body to a world point + Layout angle.
+export function syncBodyToPoint(body, point, angleDeg) {
+  Matter.Body.setPosition(body, point);
+  Matter.Body.setAngle(body, (angleDeg ?? 0) * DEG_TO_RAD);
+}
+
+// Emulated per-body gravity: replicate matter's own gravity math but multiplied
+// by each body's gravityScale. The system zeroes engine gravity so this is the
+// only source.
+export function applyWorldGravity(bodies, gravity) {
+  for (const body of bodies) {
+    if (body.isStatic || body.isSleeping) continue;
+    const scale = (body.plugin.gravityScale ?? 1) * gravity.scale;
+    body.force.x += body.mass * gravity.x * scale;
+    body.force.y += body.mass * gravity.y * scale;
+  }
+}
+
+// matter damps angular velocity via frictionAir; `angularDrag` adds extra
+// per-step damping on top for authors who want spin to settle faster.
+export function applyAngularDrag(bodies) {
+  for (const body of bodies) {
+    const drag = body.plugin.angularDrag ?? 0;
+    if (drag > 0 && !body.isStatic) body.angularVelocity *= Math.max(0, 1 - drag * FIXED_STEP_S);
+  }
+}