castle-web-cli 0.4.119 → 0.4.121

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

@@ -5,6 +5,21 @@
 // through scene.physics. (Controls are touch/pointer-first; keyboard, when
 // added, should only DUPLICATE an on-screen control, never be the only input.)
 
+// Authored Draggable `stiffness` (0..1, 0 = floppy .. 1 = rigid) -> the matter
+// constraint values that hold the object. Geometric, like joints.js's rope map
+// and for the same reason: matter's useful range here is ~0.001 (slack) to ~0.4
+// (tight), and everything above that is indistinguishably rigid -- so a linear
+// prop spends nearly all of its travel in "stiff" and never reaches the loose
+// end at all.
+//
+// Damping rides along rather than being its own knob: a slack band should be
+// free to oscillate and a tight one shouldn't, so one control moves the whole
+// feel together.
+export function dragHold(stiffness) {
+  const s = Math.min(1, Math.max(0, stiffness ?? 0.3));
+  return { stiffness: 0.001 * Math.pow(400, s), damping: 0.02 + 0.25 * s };
+}
+
 export function centerOf(layout) {
   return { x: layout.x + layout.width / 2, y: layout.y + layout.height / 2 };
 }
@@ -21,26 +36,35 @@ export function clampLength(v, max) {
   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 };
-}
-
 // --- Touch ownership -------------------------------------------------------
-// Hierarchy: a press that lands ON a Draggable object is CONSUMED by that drag,
-// so Slingshot/AnalogStick ignore it. A press anywhere else is shared -- both
-// Slingshot and AnalogStick act (no fair way to rank them). So the only gate the
-// non-drag controls need is this: did the current press land on a draggable?
-// Stateless -- a pure per-press query (the controls only ask on their press
-// edge), so there's no owner to latch and nothing to reset.
-export function pressOnDraggable(scene) {
-  const p = scene.pointer;
-  if (!p.down) return false;
-  const hit = scene.actorAt(p.x, p.y);
-  return !!hit && !!hit.components.Draggable;
+// Each control claims the pointer it started on (scene.claimPointer), so a
+// finger drives exactly one thing and the others leave it alone. Two priorities
+// are all this needs:
+//
+//   TARGETED  the press landed on THIS actor's collider, so the intent is
+//             unambiguous -- a Draggable being grabbed, a Slingshot pressed on
+//             its own body.
+//   GREEDY    the control takes any press anywhere (a Slingshot with
+//             grabAnywhere, an AnalogStick), so it must yield to a targeted one.
+//
+// Ranking them explicitly is what makes the outcome independent of actor order.
+// Previously this was a `pressOnDraggable` query that hardcoded one behavior's
+// name into shared code and had no answer at all once two fingers were down.
+export const TARGETED_CLAIM = 10;
+export const GREEDY_CLAIM = 0;
+
+// Take the first fresh press this frame that `actorId` is allowed to have, and
+// claim it. `priorityFor(pointer)` returns the claim priority to bid, or null to
+// pass on that pointer -- which is the only part that differs between controls.
+// Returns the claimed pointer, or null if there was nothing to take.
+export function acquirePress(scene, actorId, priorityFor) {
+  for (const p of scene.pointers.values()) {
+    if (!p.justPressed) continue;
+    const priority = priorityFor(p);
+    if (priority == null) continue;
+    if (scene.claimPointer(p.id, actorId, priority)) return p;
+  }
+  return null;
 }
 
 // Run `draw(ctx)` in world space, undoing the actor's Layout rotation that the

package/kits/physics-2d/engine/propertyRanges.js

@@ -0,0 +1,27 @@
+// Named inspector ranges for behaviors' `static propertyMeta`.
+//
+// A numeric prop with no meta renders as an unbounded scrubber stepping by whole
+// numbers, which is wrong for anything living in 0..1. The recurring shapes get a
+// name here so "a normalized level" is defined once instead of restated in every
+// behavior -- and so a range change lands everywhere at once.
+//
+// A `max` is a hard authoring ceiling, not just a slider bound: typed entry is
+// clamped to it too (see NumberField's `commit`). So only give something a max
+// when exceeding it is meaningless or actively breaks the simulation.
+
+// A normalized 0..1 level: volume, and anything else expressed as a fraction.
+export const UNIT = { min: 0, max: 1, step: 0.05 };
+
+// Stereo position, -1 (left) .. +1 (right). Hard-bounded by definition.
+export const PAN = { min: -1, max: 1, step: 0.05 };
+
+// Open-ended and non-negative -- a floor, but no ceiling, for quantities matter
+// or the browser treats as unbounded (restitution, friction, seconds).
+export const POSITIVE = { min: 0, step: 0.05 };
+
+// Matter's air/angular friction. Above 1 it flips the velocity sign and the body
+// destabilizes, so 1 is a real ceiling. Finer step: the useful values are small.
+export const DAMPING = { min: 0, max: 1, step: 0.01 };
+
+// A distance in card units (px).
+export const PIXELS = { min: 0, step: 5 };

package/kits/physics-2d/engine/scene.js

@@ -41,6 +41,12 @@ export class SceneRuntime {
     this.files = files ?? {};
     this.time = 0;
     this.keys = new Set();
+    // Every active pointer (finger / mouse / stylus), keyed by the browser's
+    // pointerId. A control that starts a gesture latches the id it started on
+    // and follows THAT pointer, so a second finger landing can't steal or drop
+    // an in-progress drag. `pointer` stays the primary (first-down) pointer for
+    // single-touch behaviors and for decks reading the documented API.
+    this.pointers = new Map();
     this.pointer = { x: 0, y: 0, down: false };
     this.data = { actors: [] };
     this.actors = new Map();
@@ -210,11 +216,85 @@ export class SceneRuntime {
   // input path -- the standalone ScenePlayer and the editor's play mode --
   // agree on it; behaviors read `scene.pointer` in world coordinates. Pass
   // `down` to also update the press state.
-  setPointerFromScreen(canvas, clientX, clientY, down) {
+  // `pointerId` identifies which finger/device this event came from; the
+  // browser reuses it for every event of one contact, press through release.
+  setPointerFromScreen(canvas, clientX, clientY, down, pointerId = 0) {
     const point = screenToCard(canvas, clientX, clientY);
-    this.pointer.x = point.x + (this.camera?.x ?? 0);
-    this.pointer.y = point.y + (this.camera?.y ?? 0);
-    if (down !== undefined) this.pointer.down = down;
+    const x = point.x + (this.camera?.x ?? 0);
+    const y = point.y + (this.camera?.y ?? 0);
+    let p = this.pointers.get(pointerId);
+    if (!p) {
+      // Only a press creates a pointer. A move with no press is a mouse hover,
+      // and a stray event after release must not resurrect a finished contact.
+      if (down !== true) return this.syncPrimaryPointer(x, y);
+      p = { id: pointerId, x, y, down: false, justPressed: false, claimedBy: null, claimPriority: 0 };
+      this.pointers.set(pointerId, p);
+    }
+    p.x = x;
+    p.y = y;
+    // The press edge is per-pointer, so a finger landing while another is
+    // already held still registers as a new press (a shared `down` flag would
+    // show no rising edge and the second press would be invisible).
+    if (down === true && !p.down) p.justPressed = true;
+    if (down !== undefined) p.down = down;
+    this.syncPrimaryPointer(x, y);
+  }
+
+  // Claim a pointer for one gesture, so two controls can't both act on the same
+  // finger. Returns whether `ownerId` holds it afterwards.
+  //
+  // `priority` resolves the case that actor order otherwise decides arbitrarily:
+  // a TARGETED control (a Draggable whose collider was actually pressed) must
+  // beat a GREEDY one (a Slingshot set to grab anywhere, an AnalogStick that
+  // takes any press), no matter which actor updates first. A higher priority
+  // takes the pointer from a lower one; equal or lower leaves it alone.
+  //
+  // Losing a claim is how the greedy control learns to stand down, and it costs
+  // nothing visible: on the press frame its own displacement from its origin is
+  // still zero, so it has commanded no velocity yet.
+  claimPointer(pointerId, ownerId, priority = 0) {
+    const p = this.pointers.get(pointerId);
+    if (!p) return false;
+    if (p.claimedBy == null || p.claimedBy === ownerId || priority > p.claimPriority) {
+      p.claimedBy = ownerId;
+      p.claimPriority = priority;
+    }
+    return p.claimedBy === ownerId;
+  }
+
+  // True while `ownerId` still holds this pointer. A control that latched a
+  // pointer checks this each frame so it releases when outranked. Claims need no
+  // cleanup: they live on the pointer entry, which disappears when it lifts.
+  ownsPointer(pointerId, ownerId) {
+    return this.pointers.get(pointerId)?.claimedBy === ownerId;
+  }
+
+  // Released pointers are reaped at the end of the frame rather than on the
+  // event, so a tap that begins and ends between two frames is still seen once
+  // -- and so a control latched to a pointer observes `down: false` before the
+  // entry disappears.
+  reapPointers() {
+    for (const [id, p] of this.pointers) {
+      p.justPressed = false;
+      if (!p.down) this.pointers.delete(id);
+    }
+    this.syncPrimaryPointer();
+  }
+
+  // `pointer` mirrors the primary -- the oldest pointer still held (Map keeps
+  // insertion order) -- so single-touch behaviors and decks reading the
+  // documented `scene.pointer` API behave exactly as before.
+  syncPrimaryPointer(fallbackX, fallbackY) {
+    for (const p of this.pointers.values()) {
+      if (!p.down) continue;
+      this.pointer.x = p.x;
+      this.pointer.y = p.y;
+      this.pointer.down = true;
+      return;
+    }
+    if (fallbackX !== undefined) this.pointer.x = fallbackX;
+    if (fallbackY !== undefined) this.pointer.y = fallbackY;
+    this.pointer.down = false;
   }
 
   update(dt) {
@@ -228,6 +308,8 @@ export class SceneRuntime {
     for (const system of this.systems) {
       system.afterBehaviors?.(this, dt);
     }
+    // Every behavior and system has now seen this frame's presses and releases.
+    this.reapPointers();
   }
 
   forEachBehavior(actor, callback) {

package/kits/physics-2d/engine/ui.jsx

@@ -458,6 +458,19 @@ function NumberInlineInput({ value, min, max, step, onCommit, onDone }) {
   );
 }
 
+// Snap to a multiple of `step`. `Math.round(v / step) * step` alone reintroduces
+// binary error the moment `step` isn't representable in base 2 -- 0.05 x 14 is
+// 0.7000000000000001, which then gets stored and rendered in full -- so re-round
+// to the decimal places the step itself implies.
+function snapToStep(v, step) {
+  const snapped = Math.round(v / step) * step;
+  const text = String(step);
+  const decimals = text.includes('e-')
+    ? Number(text.split('e-')[1])
+    : (text.split('.')[1] ?? '').length;
+  return Number(snapped.toFixed(Math.min(decimals, 100)));
+}
+
 export function NumberField({ label, value, onChange, min, max, step = 1, overridden, defaultValue, onReset }) {
   const current = Number.isFinite(value) ? (value ?? 0) : 0;
   // A field with BOTH a min and max is a true slider (fill + thumb), the pointer's X
@@ -481,7 +494,7 @@ export function NumberField({ label, value, onChange, min, max, step = 1, overri
     return v;
   }
   function scrubTo(v) {
-    if (step) v = Math.round(v / step) * step;
+    if (step) v = snapToStep(v, step);
     v = clampVal(v);
     if (v !== current) onChange(v);
   }

package/kits/physics-2d/engine/ui.module.css

@@ -1797,6 +1797,7 @@
   z-index: 200;
   width: min(280px, calc(100vw - 16px));
   max-height: min(420px, calc(100vh - 16px));
+  box-sizing: border-box;
   overflow: auto;
   padding: 12px 14px 14px;
   border: 1px solid var(--castle-inspector-border);

package/kits/physics-2d/package-lock.json

@@ -28,7 +28,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.12",
+      "version": "0.4.13",
       "devDependencies": {
         "eslint": "^9.0.0",
         "jscpd": "^4.0.5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.119",
+  "version": "0.4.121",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"
@@ -37,6 +37,7 @@
     "@xterm/xterm": "^6.0.0",
     "codemirror": "^6.0.2",
     "dockview": "^4.13.1",
+    "html2canvas": "^1.4.1",
     "marked": "^18.0.5",
     "nanoid": "^5.1.7",
     "open": "^10.0.0",