@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/character-attachments.md

@@ -0,0 +1,166 @@
+# Character attachments — put a prop in a player's hand (held items & sockets)
+
+Read this when a world needs a character to HOLD or WEAR something: a mug, a torch, a sword, a phone, a hat.
+The humanoid-character system ships named skeleton sockets and a world-facing attach API — you never compute
+bone transforms, and attachments replicate to other players automatically.
+
+**Prerequisite — the world's INSTALLED humanoid-character must be ≥ 0.2.14** (where attachments were added).
+On a world you did not scaffold this session, run `check_for_updates({ projectDir })` FIRST: an older install
+shows as in-range-stale, and the fix is just `install_world_packages` + rebuild — any existing `^0.2` pin
+already allows 0.2.14, no helix.json edit needed. For attachments to REPLICATE (not just render locally) the
+same check also flags a stale project SDK — update and rebuild too.
+
+## The API
+
+```js
+// mp is the CharacterMultiplayer facade (standalone Character has the same three methods).
+// The prop GLB lives in the world's own public/props/ — new URL(...) makes it absolute at runtime.
+const mug = await mp.attach(new URL('props/mug.glb', location.href).href, 'hand_r.grip', { preset: 'mug' });
+mp.detach(mug);
+mp.listSockets();   // the valid socket names on this character
+```
+
+- **The URL must be ABSOLUTE http(s), and `new URL('props/…', location.href).href` is how a local file in
+  `public/` becomes one** — the ref replicates verbatim and the room drops a bare `/props/…` path with the
+  whole set. There is no CDN step: bundle the prop with the world.
+- **URL attaches replicate by default**: other players see the prop, late joiners see it too, and it cleans up
+  on detach/leave. Pass `{ replicate: false }` to keep one local. A raw `THREE.Object3D` source is always
+  local-only (it has no asset URL to send).
+- **Cap: 8 replicated attachments per player.** Over the cap the send is skipped with a console warning.
+- Attach from input/interaction handlers (they run only on the acting player), never from replicated-state
+  observers — the same rule as gestures and movement.
+- Props on `head`/`camera` sockets auto-hide in first person so they never clip the camera; `hideInFp` overrides.
+
+## Sockets — where a prop can go
+
+`hand_r.grip` / `hand_l.grip` (held items), `head`, `head.top` (hats), `camera` (eye plane), `chest`, `back`,
+`hips_l` / `hips_r` (holsters). Call `listSockets()` rather than assuming — the set comes from the installed
+system version. Socket frames carry the natural orientation for a +z-authored item: `back` slings it tip-UP
+along the spine, the hips holster it tip-DOWN, and `chest`/`head`/`head.top`/`camera` point it forward as worn.
+
+**The grip sockets are semantic held-item frames: +z is where the item points, +y is the item's up.** You
+reason in "the mug's spout points +z", never in bone axes.
+
+## Prop conventions — meters, grip at origin, per-category frame
+
+Author or pick prop GLBs with the **grip point at the origin** (where the fist closes — never the prop's
+base) and **units in meters**. Two hard rules:
+
+- **A prop spanning more than 2 m on any axis is rejected at load** — that is almost always a cm/mm export
+  slip. Fix the export; do not scale around it with offsets.
+- Per-item alignment goes in `position` / `rotationEulerDeg` (socket-local, meters/degrees) or a `preset` —
+  never baked into world code as magic bone math.
+
+**The prop's own axes are PER CATEGORY — "+z out along the tip" is only the pointed-item rule.** Each
+preset's calibrated offsets assume the frame below; author a different frame and the preset lands wrong
+(the classic failure: a mug modeled with its cup axis along +z attaches lying on its side, spilling).
+
+| preset | author the GLB as | reference size |
+|---|---|---|
+| `sword`, `torch` (long-shaft family: staff, axe, pickaxe, wand) | shaft along **+z**, blade/flame END at +z; the fist point at the origin, shaft running a little −z behind it | torch 0.53 m long |
+| `mug` (cylinder family: glass, bottle, can) | body CENTERED on the origin, **opening UP (+y)**, handle on **−x** — NOT +z | ⌀ 0.084 × 0.10 m |
+| `flashlight` | body wrapping the origin, **beam out +z**, head at +z | 0.17 m long |
+| `phone` | slab centered on the origin, thin axis **y**, TOP edge toward **+z**, screen facing **+y** | 0.072 × 0.15 × 0.008 m |
+| `pistol`, `rifle` | muzzle **+z**, grip at the origin, iron sights up **+y** | calibrated against the platform arsenal |
+
+Pick the preset by how the item is HELD, not by shape — `torch` carries the tip up like a flame,
+`flashlight` points it forward like a beam. Explicit offsets override the preset per field. For WEAPONS
+there is a third layer between the two: a weapon profile's `hold` block (per-gun grip seating, resolved by
+the attachment URL at attach time) beats the preset and loses to explicit call-site offsets — so a gun with
+a baked seating lands right with a bare `{ preset }` attach; see `read_doc({ name: "shooter-worlds" })`. Presets work
+in EITHER hand: attach with a preset to `hand_l.grip` and the offsets auto-mirror (position x → −x,
+rotation `[a,b,c]` → `[a,−b,−c]`); explicit offsets are never mirrored. `inspect_gesture` /
+`capture_gesture` apply the SAME mirror and tag the offsets line "(preset auto-mirrored for this
+socket)", and the posed placement line reports both `dir=` (+z) and `up=` (+y) so a wrong authoring
+frame shows numerically — a held mug should read `up` ≈ world +y.
+
+### No asset? Build the GLB from three.js primitives — do NOT attach an in-scene Object3D
+
+`attach()` takes a URL **by design**: the attachment replicates the asset reference, so every client must
+fetch the same file — an Object3D you composed in the scene cannot ride the wire. When no hosted asset
+exists, compose the prop with three.js primitives **in the canonical frame** and export a GLB once, as a
+node script in the world repo (`scripts/make-props.mjs`, rerun after tweaks):
+
+```js
+import { writeFileSync, mkdirSync } from 'node:fs';
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
+
+// GLTFExporter's binary path uses the browser FileReader; node has Blob but not FileReader.
+// This shim is all an untextured prop needs.
+globalThis.FileReader = class {
+  readAsArrayBuffer(blob) {
+    blob.arrayBuffer().then((buf) => { this.result = buf; this.onloadend(); });
+  }
+};
+
+const prop = new THREE.Group();
+const ceramic = new THREE.MeshStandardMaterial({ color: 0xe8e3da, roughness: 0.85, side: THREE.DoubleSide });
+// Body CENTERED on the origin — the origin is where the fist closes, not the prop's base.
+// Real-world meters: a mug is ~0.08 m wide, a phone ~0.15 m tall — not 1.0.
+prop.add(new THREE.Mesh(new THREE.CylinderGeometry(0.042, 0.042, 0.1, 24), ceramic));
+const handle = new THREE.Mesh(new THREE.TorusGeometry(0.028, 0.007, 10, 16, Math.PI), ceramic);
+handle.position.set(-0.042, 0, 0);
+handle.rotation.z = Math.PI / 2;
+prop.add(handle);
+
+const glb = await new GLTFExporter().parseAsync(prop, { binary: true });
+mkdirSync('public/props', { recursive: true });
+writeFileSync('public/props/mug.glb', Buffer.from(glb));
+```
+
+Frame rules while composing: the grip point at the origin (a long prop's shaft runs from slightly −z
+through the origin out along **+z**), +y is the item's up, real-world meters. `DoubleSide` on thin or
+open shells (a culled backface reads as a hole). Serve from `public/` and attach with an **absolute**
+URL — `new URL('props/mug.glb', location.href).href` — a bare path is dropped with the whole set.
+
+**Then verify with numbers, not eyes** — `inspect_gesture` with `attach` measures the exported file in
+the grip frame. First RAW (no preset) to prove the convention:
+
+```
+attachment: mug.glb → hand_r.grip
+  prop bbox (m): x -0.077…0.042 · y -0.05…0.05 · z -0.042…0.042 — meters OK (0.12 m max span)
+  extends 0.04m out along +z, … grip origin is inside the prop volume
+```
+
+`meters OK` and `grip origin is inside the prop volume` are the two verdicts that must hold ("origin is
+OUTSIDE" = you modeled the prop beside its grip point; a span near 2 m = a cm/mm export slip). Then
+re-run with the `preset` you intend to ship and check the posed placement line reads sensibly.
+
+## Grip finger poses — the hand closes by itself (≥ 0.2.15)
+
+A preset also carries a calibrated FINGER pose, so the hand actually wraps the item instead of resting flat
+under it: `mug` curls into the cylinder hold, `sword`/`torch` close the shaft fist, `flashlight` wraps the
+barrel; `phone` deliberately keeps the neutral hand. Nothing to call — it plays on attach to a grip socket,
+stops on detach, mirrors automatically in the left hand, and replicates through the preset name that already
+rides the wire (older clients simply render the flat hand). Behavior worth knowing:
+
+- **While the prop is held, the grip OWNS that hand's fingers (≥ 0.2.17):** gestures keep playing, but
+  their finger keys on the holding side are skipped — a sip cannot unwrap the hand around the mug. The
+  fingers return to gesture/animation control on detach. (On ≤ 0.2.16 the priority was reversed: a
+  finger-keying gesture temporarily unwrapped the grip.) Author finger keys freely; they apply whenever
+  that hand is not holding something.
+- On rigs without finger bones (some imported avatars) the pose no-ops cleanly.
+- Explicit-offset attaches without a `preset` get no finger pose — pass the preset when you want the wrap.
+
+## Getting a prop RIGHT — measure before pixels
+
+The gesture tools grew attachment params; the loop is the same measure-first loop as gestures:
+
+1. `inspect_gesture` with `attach` (+ `attachSocket`/`attachPreset`/`attachOffset`/`attachRotation`): reports
+   the prop bbox **in the grip frame** ("0.06m behind the grip point", "grip origin OUTSIDE the prop volume —
+   is the grip modeled at the origin?"), a **unit verdict**, and where the prop lands at each `t` of a clip
+   ("prop@hand_r.grip: between shoulder and head, points up"). Iterate offsets HERE — it is milliseconds.
+2. `capture_gesture` with the same attach params: renders the prop in the hand across the clip (or one moment
+   with `at`) — the closing look. Trust it for how the held prop READS; go back to `inspect_gesture` for any
+   distance question.
+
+A held pose + prop converges in 2–3 rounds this way: fix the unit verdict first, then the grip-frame bbox
+(behind/above/out numbers), then look once.
+
+## Multiplayer notes
+
+Attachments are synced state (not events): the full desired set replaces on each change, replicas diff by id
+and evict removed props, late joiners converge on the pre-existing set. Offsets are resolved on the sender and
+travel resolved, so version skew between players cannot misplace a prop. The room enforces: ≤ 8 entries, https
+asset URLs ≤ 512 chars, offsets ≤ 2 m — an invalid set is dropped whole (nothing partially applies).