castle-web-cli 0.4.168 → 0.4.170

package/kits/multiplayer-2d/castle.json

@@ -19,11 +19,11 @@
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-01T01:02:46.041Z"
+      "version": "2026-09-10T00:57:31.408Z"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-05T01:31:11.287Z"
+      "version": "2026-09-10T00:56:59.388Z"
     }
   },
   "autoUpdateWhenImported": true,
@@ -35,5 +35,5 @@
   },
   "deckId": "oiFu96LkwZ09",
   "cardId": "nkJgrvrCby3H",
-  "publishedVersion": "2026-09-05T01:32:45.261Z"
+  "publishedVersion": "2026-09-10T00:58:09.384Z"
 }

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

@@ -15,7 +15,6 @@
         "@dnd-kit/modifiers": "^9.0.0",
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
-        "@fortawesome/free-solid-svg-icons": "^5.15.4",
         "@lezer/highlight": "^1.2.3",
         "castle-web-fonts": "^1.0.0",
         "codemirror": "^6.0.2",
@@ -151,7 +150,6 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -202,29 +200,6 @@
         "react": ">=16.8.0"
       }
     },
-    "node_modules/@fortawesome/fontawesome-common-types": {
-      "version": "0.2.36",
-      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-0.2.36.tgz",
-      "integrity": "sha512-a/7BiSgobHAgBWeN7N0w+lAhInrGxksn13uK7231n2m8EDPE3BMCl9NZLTGrj9ZXfCmC6LM0QLqXidIizVQ6yg==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "node_modules/@fortawesome/free-solid-svg-icons": {
-      "version": "5.15.4",
-      "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-5.15.4.tgz",
-      "integrity": "sha512-JLmQfz6tdtwxoihXLg6lT78BorrFyCf59SAwBM6qV/0zXyVeDygJVb3fk+j5Qat+Yvcxp1buLTY5iDh1ZSAQ8w==",
-      "hasInstallScript": true,
-      "license": "(CC-BY-4.0 AND MIT)",
-      "dependencies": {
-        "@fortawesome/fontawesome-common-types": "^0.2.36"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/@lezer/common": {
       "version": "1.5.2",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",
@@ -308,7 +283,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
       "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -318,7 +292,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
       "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },

package/kits/multiplayer-2d/package.json

@@ -16,7 +16,6 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@fortawesome/free-solid-svg-icons": "^5.15.4",
     "@lezer/highlight": "^1.2.3",
     "castle-web-fonts": "^1.0.0",
     "codemirror": "^6.0.2",

package/kits/multiplayer-3d/castle.json

@@ -18,22 +18,22 @@
     },
     "castle.physics-3d": {
       "deckId": "JH0SclbPVP0y",
-      "version": "2026-09-01T01:02:48.784Z"
+      "version": "2026-09-10T00:57:52.158Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-01T01:02:46.041Z",
+      "version": "2026-09-10T00:57:31.408Z",
       "via": "castle.physics-3d"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-05T01:31:11.287Z"
+      "version": "2026-09-10T00:56:59.388Z"
     }
   },
   "autoUpdateWhenImported": true,
   "deckId": "ZwA_P_-VO-Qh",
   "cardId": "bvRmCzyUpt_a",
-  "publishedVersion": "2026-09-05T01:32:53.625Z",
+  "publishedVersion": "2026-09-10T00:58:16.876Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

package/kits/multiplayer-3d/package-lock.json

@@ -16,7 +16,6 @@
         "@dnd-kit/modifiers": "^9.0.0",
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
-        "@fortawesome/free-solid-svg-icons": "^5.15.4",
         "@lezer/highlight": "^1.2.3",
         "castle-web-fonts": "^1.0.0",
         "codemirror": "^6.0.2",
@@ -159,7 +158,6 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -210,29 +208,6 @@
         "react": ">=16.8.0"
       }
     },
-    "node_modules/@fortawesome/fontawesome-common-types": {
-      "version": "0.2.36",
-      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-0.2.36.tgz",
-      "integrity": "sha512-a/7BiSgobHAgBWeN7N0w+lAhInrGxksn13uK7231n2m8EDPE3BMCl9NZLTGrj9ZXfCmC6LM0QLqXidIizVQ6yg==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "node_modules/@fortawesome/free-solid-svg-icons": {
-      "version": "5.15.4",
-      "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-5.15.4.tgz",
-      "integrity": "sha512-JLmQfz6tdtwxoihXLg6lT78BorrFyCf59SAwBM6qV/0zXyVeDygJVb3fk+j5Qat+Yvcxp1buLTY5iDh1ZSAQ8w==",
-      "hasInstallScript": true,
-      "license": "(CC-BY-4.0 AND MIT)",
-      "dependencies": {
-        "@fortawesome/fontawesome-common-types": "^0.2.36"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/@lezer/common": {
       "version": "1.5.2",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",
@@ -316,7 +291,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
       "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -326,7 +300,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
       "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },

package/kits/multiplayer-3d/package.json

@@ -17,7 +17,6 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@fortawesome/free-solid-svg-icons": "^5.15.4",
     "@lezer/highlight": "^1.2.3",
     "castle-web-fonts": "^1.0.0",
     "codemirror": "^6.0.2",

package/kits/physics-2d/CLAUDE.md

@@ -22,9 +22,10 @@ Do you already know what you want to make, or do you want to figure it out toget
 - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
 - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
 - A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
-- The deck's body/UI font is picked in the Style editor (`theme.style`): HUD text inherits it, canvas text reads `scene.font`. A second display face is imported in the behavior that uses it. See `## Deck font` below.
+- The deck's body/UI font is picked in the Style editor (`theme.style`): canvas text reads `scene.font`. A second display face is imported in the behavior that uses it. See `## Deck font` below.
 - This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
 - Space is reserved by the editor for play/stop; do not bind Space to gameplay.
+- Two render hooks: `draw(ctx)` is world space and scrolls with `Camera`; `drawUi(ctx)` is screen space (card units, camera-free). On-screen controls, gauges and HUD go in `drawUi`, never `draw`. The React `ui()` hook is deprecated — prefer `drawUi`.
 - Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below. Forking is the exception: when you're deliberately copying a kit file into the deck to change it — an editor (see `## Editors`) or a behavior you're shadowing — read the original. `engine/` stays off-limits either way.
 - An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. Scenes, sprites and styles have editors; per-actor settings belong on behavior props in the inspector — not in a new editor.
 - Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
@@ -266,11 +267,16 @@ export class MyThing {
   }
 
   // Optional. Custom drawing (you usually don't need this; use a Sprite
-  // component instead). ctx is in card units already.
+  // component instead). ctx is world space: card units, translated by the
+  // camera when a `Camera` exists, then rotated by the actor's Layout.
   draw(actor, scene, ctx) {}
 
-  // Optional. Return React nodes for game-time HUD. Coordinates are card
-  // units. Read state your `update` set; do not start your own loops.
+  // Optional. Canvas HUD in screen-fixed card units; never moves with the
+  // camera. Prefer this for every on-screen control, gauge, and HUD label.
+  drawUi(actor, scene, ctx) {}
+
+  // Deprecated. Prefer `drawUi`. Still runs (React overlay, screen-fixed card
+  // units) but new HUD should not use it.
   ui(actor, scene) {
     return null;
   }
@@ -290,12 +296,6 @@ export class MyThing {
 
 A fresh `Behavior` instance is constructed per actor per frame from the actor's component props — DO NOT store per-actor state on `this`. Persist transient state on `actor.runtime` (a free-form object the framework will not serialize) or on the component props themselves.
 
-Interactive HUD from `ui` works by default for real controls (`button`, `a`,
-`input`, `select`, `textarea`, `[role="button"]`). A tap handler on anything
-else — a plain `div` — is click-through, so the HUD doesn't eat taps meant for
-the game: set `pointerEvents: 'auto'` on that element, never on a wrapper
-covering the card (every behavior's `ui` shares one layer).
-
 ## Scene file (`scenes/main.scene`, plain JSON)
 
 A scene is a background plus a list of actors. Every actor is an **instance of a blueprint** (see `## Blueprints`): a `blueprint` path plus sparse `components` overrides — usually just its `Layout` position:
@@ -400,7 +400,7 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
   }
   ```
 
-- **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation).
+- **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation). It translates everything drawn in `draw()`; `drawUi()` is unaffected. `scene.camera` is `{ x, y }` while a Camera actor runs, else `undefined`.
 - **SoundPlayer** — `{ file: "assets/music/theme.mp3", stream?: false, volume?: 1, playbackRate?: 1, pan?: 0, loop?: false, playOnStart?: true }`. Plays one audio file from an actor. `stream: false` (the default) fires it from memory — instant and overlapping, for effects; `stream: true` streams it from an `<audio>` element — for music and long ambience, whose decoded audio would be far too big to hold. `loop` applies to `stream: true` only. `playbackRate` retunes it (2 = an octave up and twice as fast, 0.5 = an octave down); `pan` places it left (−1) to right (+1). With `playOnStart` it starts with the scene; otherwise trigger it through the handle it puts on the actor:
 
   ```jsx
@@ -442,7 +442,7 @@ Name a sound by its filename without the extension, or by its full deck path. Tw
 
 A physics-2d deck picks its **deck font** in the Style editor — open
 `theme.style` and choose one of the nine Castle faces, or None. That is the
-deck's body and UI face: HUD text inherits it, and `scene.font` returns it.
+deck's body and UI face: `scene.font` returns it for `draw` / `drawUi`.
 
 Picking writes two files, and both belong in the deck:
 
@@ -451,25 +451,19 @@ Picking writes two files, and both belong in the deck:
 - `fonts.generated.js` — one static re-export, and the only thing that carries
   that face's bytes into the published deck. Generated; don't edit it.
 
-Use it in the two places this kit renders text:
-
-- **HUD text** (a behavior's `ui` hook) inherits it already — plain React, no
-  extra work. `--castle-deck-font` is on the UI layer if you want to name it in
-  CSS.
-- **In-world text** (a behavior's `draw` hook) reads `scene.font`, which is
-  always a usable CSS family — the deck's face, or a sans stack when it has
-  none:
+Use it from canvas text in `draw` / `drawUi` — both read `scene.font`, which is
+always a usable CSS family (the deck's face, or a sans stack when it has none):
 
-  ```jsx
-  draw(actor, scene, ctx) {
-    ctx.font = `24px ${scene.font}`;
-    ctx.fillText(`${this.props.score}`, 20, 40);
-  }
-  ```
+```jsx
+drawUi(actor, scene, ctx) {
+  ctx.font = `24px ${scene.font}`;
+  ctx.fillText(`${this.props.score}`, 20, 40);
+}
+```
 
-  Don't hardcode the deck font's family name there: a `draw` hook naming
-  `'Piazzolla'` outright keeps drawing in it after someone picks a different
-  font, and draws in nothing at all once they pick None.
+Don't hardcode the deck font's family name there: a hook naming `'Piazzolla'`
+outright keeps drawing in it after someone picks a different font, and draws in
+nothing at all once they pick None.
 
 ### A second face
 
@@ -498,8 +492,8 @@ behavior imported for itself — before the first frame, so `ctx.font` is safe t
 set from the very first `draw`. Each face costs its own 12–90 KB in the bundle,
 so two or three in total is the shape to aim for.
 
-There is no Text behavior — text is drawn by the deck's own code, through the
-two hooks above.
+There is no Text behavior — text is drawn by the deck's own code via `draw`
+(world) or `drawUi` (screen HUD).
 
 ## Physics
 
@@ -544,13 +538,21 @@ tilts it sideways. Omit for the default (`1`, downward).
 
 ### Driving physics from behaviors — `scene.physics`
 
-In a behavior's `update`, steer bodies through `scene.physics` (never write
-`Layout` directly for a dynamic body — the sim owns its transform):
+In a behavior's `update`, steer bodies through `scene.physics`. Writing
+`Layout.x`/`y`/`rotation` on a dynamic body **teleports** it there before the
+next step (velocity kept, no collision along the way). To move it *under*
+physics use `setVelocity`/`applyImpulse`/`applyForce`:
 
 - `scene.physics.setVelocity(actor, { x, y })` — set velocity (px per fixed
   step; multiply by ~60 for px/s).
 - `scene.physics.applyImpulse(actor, { x, y })` — add to velocity this frame.
 - `scene.physics.applyForce(actor, { x, y })` — add a matter-space force.
+- `scene.physics.setRotation(actor, deg)` — same as writing `Layout.rotation`.
+- `scene.physics.setPosition(actor, { x, y })` — same as writing Layout; x/y
+  are the Layout top-left.
+- `scene.physics.setAngularVelocity(actor, degPerStep)` /
+  `getAngularVelocity(actor)` — set to 0 to stop a spin;
+  `setVelocity(actor, {x:0,y:0})` stops linear motion.
 - `scene.physics.getVelocity(actor)` — current velocity `{ x, y }`.
 - `scene.physics.isColliding(a, b)` — are these two actors touching right now?
 - `scene.physics.actorAtPoint(x, y)` — topmost actor whose **collider** contains
@@ -578,6 +580,26 @@ export class Coin {
 }
 ```
 
+### Stick hooks
+
+An `AnalogStick` on the same actor fires sibling hooks when the gesture begins
+and ends — begin on the first nonzero deflection (not on a still press), end on
+release or when the stick is disabled mid-hold. Signature `(actor, scene)`; the
+stick itself receives them and ignores them.
+
+```jsx
+export class StickSlowDownToggle {
+  static behaviorName = 'StickSlowDownToggle';
+  onAnalogStickBegin(actor, scene) {
+    // e.g. mute a sibling Slow Down while the stick is active
+    actor.runtime.stickHeld = true;
+  }
+  onAnalogStickEnd(actor, scene) {
+    actor.runtime.stickHeld = false;
+  }
+}
+```
+
 ### Built-in controls (add these behaviors, no code needed)
 
 These read input and drive the actor through the physics system, so the actor
@@ -616,7 +638,13 @@ see the SceneRuntime API below.
 - **`Slingshot`** — press the actor, pull back, release to launch it the
   opposite way (angry-birds), with an aim arrow. `speed`, `maxDrag`.
 - **`AnalogStick`** — on-screen virtual joystick (press anywhere) that drives
-  the actor. `speed`, `maxRadius`, `axes`. Best for top-down.
+  the actor with force-mode feel: ramp in, hard top speed, idle-only brake.
+  Screen-fixed (`drawUi`) so it works with a `Camera`. `speed` (top speed,
+  px/step), `rampTime` (seconds rest→speed at full deflection; `0` = instant),
+  `slowDown` (idle deceleration in speed units per second; `0` = coast),
+  `turnBoost` (extra accel when reversing), `maxRadius`, `axes`. Never clamps
+  or brakes an undriven axis (so horizontal + gravity still falls). Best for
+  top-down; see **Stick hooks** above for begin/end.
 
 ### Recipe: a launch-and-bounce game
 
@@ -712,10 +740,13 @@ draw(actor, scene, ctx) {
   Slingshot) can pass straight through it — matter-js has no continuous
   collision. Keep boundary walls thick (50px+) and/or cap launch power. The
   demo scene uses 50px walls with a ~20px/step launch cap.
-- **Don't move a dynamic body by writing `Layout`.** The simulation owns a
-  dynamic body's transform and overwrites `Layout` every frame — use
-  `scene.physics.setVelocity/applyImpulse/applyForce`. Writing `Layout`
-  directly is only for `static`/`kinematic` bodies.
+- **Writing `Layout` teleports.** A Layout write on a body snaps it there
+  before the next step with no collision response on the way — a per-frame
+  `layout.x += speed*dt` on a dynamic body ghosts through walls and jitters
+  (use `setVelocity` for that). Momentum is kept, so to drive rotation every
+  frame pair it with `freezeRotation` or expect a small spin drift between
+  writes. Teleporting one end of a joint makes the constraint snap it back
+  next step.
 - **Editor vs play.** Physics only steps during play; in the editor actors sit
   where you place them. `RigidBody.velocityX/Y` apply once when play starts.
 - **No `Collider` means no physics at all.** A body only exists for an actor with
@@ -791,8 +822,9 @@ To generate path art, emit an svg of **shapes** rather than per-pixel rects and
 
 - `scene.time` — seconds since start.
 - `scene.keys` — `Set` of currently-held KeyboardEvent codes (e.g. `'ArrowLeft'`, `'KeyA'`, `'Space'`). Read in `update`.
-- `scene.pointer` — `{ x, y, down }` in world (card) coordinates, camera-adjusted. The **primary** pointer: the one held longest. Use this for anything single-touch.
-- `scene.pointers` — `Map` of every active pointer (finger / mouse / stylus) by id, each `{ id, x, y, down, justPressed, claimedBy }`, same coordinates. For multi-touch: latch the `id` a gesture began on and follow that entry, so another finger landing can't hijack it. `justPressed` is that pointer's press edge for this frame (a shared `down` flag would miss a finger landing while another is already held). Entries disappear on release.
+- `scene.pointer` — `{ x, y, screenX, screenY, down }`. `x`/`y` are world coordinates (card units offset by the camera); `screenX`/`screenY` are card coords before the camera, for screen-fixed controls. The **primary** pointer: the one held longest. Use this for anything single-touch.
+- `scene.pointers` — `Map` of every active pointer (finger / mouse / stylus) by id, each `{ id, x, y, screenX, screenY, down, justPressed, claimedBy }`, same coordinates. For multi-touch: latch the `id` a gesture began on and follow that entry, so another finger landing can't hijack it. `justPressed` is that pointer's press edge for this frame (a shared `down` flag would miss a finger landing while another is already held). Entries disappear on release.
+- `scene.camera` — `{ x, y }` while a Camera actor runs, else `undefined`.
 - `scene.claimPointer(id, ownerId, priority?)` / `scene.ownsPointer(id, ownerId)` — take a finger for one gesture so two controls can't both act on it, and check you still hold it. A higher `priority` takes it from a lower one, which is how a control that was actually pressed (a `Draggable`'s collider) beats one that takes any press (an `AnalogStick`), regardless of actor order. Claims vanish with the pointer, so there's nothing to release. This is what lets a player work a stick with one thumb and drag with the other.
 - `scene.getActor(id)` / `scene.getActors()` (sorted by Layout.z) / `scene.getComponent(actor, name)`.
 - `scene.actorWith('GameController')` / `scene.actorsWith('Brick')` — find one / all actors carrying a given behavior. Prefer these to `getActors().find(a => a.components.X)`.
@@ -803,7 +835,7 @@ To generate path art, emit an svg of **shapes** rather than per-pixel rects and
 - `scene.spawnFromBlueprint('blueprints/enemy.scene', { components: { Layout: { x, y } } })` — spawn an instance of a blueprint, same merge semantics as a placed instance. Prefer this over `spawnActor` when you're spawning copies of something that has (or should have) a blueprint, e.g. `scene.spawnFromBlueprint(actor.blueprint, { components: { Layout: { x: actor.components.Layout.x, y: actor.components.Layout.y } } })` to spawn another of the same kind as an existing actor.
 - `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
 - `scene.sound` — the deck's sound library: `play(name, opts)`, `stopAll()`, `isLoaded`, `whenLoaded`, `has(name)`, `voiceCount`. See `## Sound`.
-- `scene.font` — the deck's font as a CSS family, for `ctx.font` in `draw`. Always usable: the face picked in the Style editor, or a sans stack. See `## Deck font`.
+- `scene.font` — the deck's font as a CSS family, for `ctx.font` in `draw` / `drawUi`. Always usable: the face picked in the Style editor, or a sans stack. See `## Deck font`.
 - `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
 - `scene.load(sceneData)` — replace the running scene with the given scene data object.
 - `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
@@ -820,14 +852,14 @@ if (scene.keys.has('KeyX')) /* launch ball */ ;
 
 **Space is reserved** — the editor binds it to the play/stop toggle, so don't bind Space to a gameplay action (jump / shoot / launch / ...). Use arrows, WASD, letter keys, or on-screen buttons instead.
 
-For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`. Both render in the deck's font — see `## Deck font`.
+For HUD text and shapes use `drawUi` (screen-fixed canvas). Only in-world text or shapes go in `draw`. Both read `scene.font` — see `## Deck font`. The React `ui()` hook is deprecated.
 
 ## Common breakout-shaped recipe (sketch)
 
 - `Paddle` behavior: read keys, clamp x to `[0, 500 - layout.width]`.
 - `Ball` behavior: store `vx, vy` on `actor.runtime`; integrate; bounce off wall edges (`x<0`, `x+w>500`, `y<0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `y > 700` lose a life.
 - `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `actor.runtime` or the brick's own props.
-- `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `ui()`.
+- `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `drawUi()`.
 
 ## Don't
 

package/kits/physics-2d/behaviors/AnalogStick.jsx

@@ -4,19 +4,39 @@ import { AutoFields, overrideProps } from '../engine/autoInspector';
 import {
   GREEDY_CLAIM,
   acquirePress,
-  analogVelocity,
-  inActorWorldSpace,
+  length,
+  screenPoint,
+  stickBrake,
+  stickDrive,
   stickVector,
 } from '../engine/physics/controls';
 
-// AnalogStick: an on-screen virtual joystick that drives the actor it's on --
-// the look and feel of castle-client's Analog Stick. Press anywhere to place
-// the stick; drag to steer. Draws the stick base ring + knob while held. Best
-// for top-down movement; needs a RigidBody (dynamic) + Collider.
+// AnalogStick: on-screen virtual joystick (press anywhere) that drives the
+// actor with OG-style force mode — ramp in, hard top speed, idle-only brake.
+// Screen-fixed: the ring stays under the thumb while a Camera scrolls, and does
+// not rotate with the actor. Needs a RigidBody (dynamic) + Collider. Never
+// touches an undriven axis.
 //
-//   speed     -> velocity at full deflection (px per fixed step).
+//   speed     -> top speed at full deflection (px per fixed step).
+//   rampTime  -> seconds from rest to speed at full deflection (0 = instant).
+//   slowDown  -> deceleration while idle, speed units lost per second (0 = coast).
+//   turnBoost -> extra accel when velocity points away from the stick (OG turnFriction).
 //   maxRadius -> stick throw radius in pixels.
-//   axes      -> restrict to 'horizontal' / 'vertical' / 'both'.
+//   axes      -> 'horizontal' / 'vertical' / 'both'.
+//
+// Sibling hooks (fired on this actor only): onAnalogStickBegin / onAnalogStickEnd
+// (actor, scene) — begin on first nonzero deflection, end on release or disable.
+function fireStickHook(actor, scene, hook) {
+  scene.forEachBehavior(actor, (inst) => inst[hook]?.(actor, scene));
+}
+
+function clearStickRuntime(rt) {
+  rt._stickBegan = false;
+  rt._stickPointerId = null;
+  rt._stickOrigin = null;
+  rt._stickKnob = null;
+}
+
 export class AnalogStick {
   static behaviorName = 'AnalogStick';
   // Drives a body, so it needs one: Collider + dynamic RigidBody.
@@ -24,14 +44,20 @@ export class AnalogStick {
 
   static defaultProps = {
     speed: 6,
+    rampTime: 0.2,
+    slowDown: 20,
+    turnBoost: 3,
     maxRadius: 60,
     axes: 'both',
   };
 
   // `maxRadius` is the stick's travel in px; below ~10 the knob has no usable
-  // throw and the control reads as broken.
+  // throw and the control reads as broken. slowDown humanizes to "Slow Down".
   static propertyMeta = {
     speed: { min: 0, step: 0.5 },
+    rampTime: { min: 0, step: 0.05 },
+    slowDown: { min: 0, step: 1 },
+    turnBoost: { min: 0, step: 0.5 },
     maxRadius: { min: 10, step: 5 },
   };
 
@@ -55,59 +81,63 @@ export class AnalogStick {
     const press = acquirePress(scene, actor.id, () => GREEDY_CLAIM);
     if (!press) return null;
     rt._stickPointerId = press.id;
-    rt._stickOrigin = { x: press.x, y: press.y };
+    rt._stickOrigin = { x: press.screenX, y: press.screenY };
     return press;
   }
 
-  update(actor, scene) {
+  update(actor, scene, dt) {
     const rt = actor.runtime;
     const p = this.trackedPointer(actor, scene);
-    // Only drive velocity while the stick is actually held.
     if (p?.down && rt._stickOrigin) {
-      rt._stickKnob = stickVector(p, rt._stickOrigin, this.props.maxRadius ?? 60);
-      scene.physics.setVelocity(actor, analogVelocity(p, rt._stickOrigin, this.props));
-      rt._stickActive = true;
+      const maxRadius = this.props.maxRadius ?? 60;
+      const sp = screenPoint(p);
+      const knob = stickVector(sp, rt._stickOrigin, maxRadius);
+      rt._stickKnob = knob;
+      const deflection = { x: knob.x / maxRadius, y: knob.y / maxRadius };
+      const vel = scene.physics.getVelocity(actor);
+      scene.physics.applyImpulse(actor, stickDrive(vel, deflection, this.props, dt));
+      // OG fires on first movement, not on a still press.
+      if (!rt._stickBegan && length(deflection) > 0) {
+        rt._stickBegan = true;
+        fireStickHook(actor, scene, 'onAnalogStickBegin');
+      }
       return;
     }
 
-    rt._stickPointerId = null;
-    rt._stickOrigin = null;
-    rt._stickKnob = null;
-    // Stop ONCE on release, and only on the driven axes (so a top-down mover
-    // doesn't drift). Critically, do NOT touch velocity while idle -- doing that
-    // every frame zeroes the velocity gravity builds up, so the actor barely
-    // falls. An idle AnalogStick must leave physics (gravity, momentum) alone.
-    if (rt._stickActive) {
-      rt._stickActive = false;
-      const axes = this.props.axes ?? 'both';
-      const cur = scene.physics.getVelocity(actor);
-      scene.physics.setVelocity(actor, {
-        x: axes === 'vertical' ? cur.x : 0,
-        y: axes === 'horizontal' ? cur.y : 0,
-      });
+    if (rt._stickBegan) {
+      fireStickHook(actor, scene, 'onAnalogStickEnd');
     }
+    clearStickRuntime(rt);
+    // Idle every frame: brake on driven axes only (gravity/momentum elsewhere stay).
+    const vel = scene.physics.getVelocity(actor);
+    scene.physics.applyImpulse(actor, stickBrake(vel, this.props, dt));
+  }
+
+  // Switched off mid-hold: fire end and drop runtime state. `update` stops
+  // running once disabled, so this is the only chance to release the gesture.
+  onDisable(actor, scene) {
+    const rt = actor.runtime;
+    if (rt._stickBegan) fireStickHook(actor, scene, 'onAnalogStickEnd');
+    clearStickRuntime(rt);
   }
 
-  // Base ring anchored where the user pressed + knob at the current (clamped)
-  // deflection. Drawn in world space so it stays put instead of rotating/sliding
-  // with the actor.
-  draw(actor, scene, ctx) {
+  // Drawn in screen space (drawUi) so the ring stays under the thumb while the
+  // camera scrolls, and doesn't rotate with the actor.
+  drawUi(actor, scene, ctx) {
     const rt = actor.runtime;
     if (!rt._stickOrigin) return;
     const o = rt._stickOrigin;
     const k = rt._stickKnob ?? { x: 0, y: 0 };
     const radius = this.props.maxRadius ?? 60;
-    inActorWorldSpace(ctx, actor.components.Layout, (c) => {
-      c.strokeStyle = 'rgba(255, 255, 255, 0.5)';
-      c.lineWidth = 3;
-      c.beginPath();
-      c.arc(o.x, o.y, radius, 0, Math.PI * 2);
-      c.stroke();
-      c.fillStyle = 'rgba(255, 255, 255, 0.85)';
-      c.beginPath();
-      c.arc(o.x + k.x, o.y + k.y, 20, 0, Math.PI * 2);
-      c.fill();
-    });
+    ctx.strokeStyle = 'rgba(255, 255, 255, 0.5)';
+    ctx.lineWidth = 3;
+    ctx.beginPath();
+    ctx.arc(o.x, o.y, radius, 0, Math.PI * 2);
+    ctx.stroke();
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.85)';
+    ctx.beginPath();
+    ctx.arc(o.x + k.x, o.y + k.y, 20, 0, Math.PI * 2);
+    ctx.fill();
   }
 
   static Inspector({ component, setComponent, override }) {

package/kits/physics-2d/behaviors/Slingshot.jsx

@@ -100,8 +100,7 @@ export class Slingshot {
     const dir = { x: -pull.x / len, y: -pull.y / len }; // launch direction (opposite pull)
     const end = { x: a.x - pull.x * 0.8, y: a.y - pull.y * 0.8 };
 
-    // The launch is absolute, so draw the aim in world space too (castle-client
-    // draws the sling as a screen overlay for the same reason).
+    // Aim is drawn in world space because the anchor is on the actor.
     inActorWorldSpace(ctx, actor.components.Layout, (c) => drawSling(c, a, end, dir));
   }