sindicate 0.2.0 → 0.5.0

package/src/systems/casino/blackjack.js

@@ -0,0 +1,187 @@
+// BLACKJACK ENGINE — pure rules + state machine, no three.js and no DOM. MULTI-SEAT: one human seat +
+// any number of AI seats, all versus the house. 6-deck shoe, dealer stands on 17 (incl. soft 17), 3:2
+// on a natural, Hit / Stand / Double (no split/insurance). AI seats hit under 17. The 3D table and the
+// HUD subscribe to the events and read the public state — they never touch the rules.
+//
+// TICKABLE: call update(dt) each frame. The engine paces the AI seats, the dealer's draws and the
+// end-of-round hold itself. Each seat's stake is reserved by the caller before start(); the seat's
+// result reports the signed delta to credit back (see onResult).
+
+export const SUITS = ['spades', 'hearts', 'diamonds', 'clubs'];        // suit index 0..3
+export const RANK_LABEL = ['', 'A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K']; // rank 1..13
+
+export const PHASE = { IDLE: 'idle', DEALING: 'dealing', PLAYER: 'player', DEALER: 'dealer', PAYOUT: 'payout' };
+const AI_DELAY = 0.9;      // seconds an AI seat waits before each hit/stand
+const DEALER_STEP = 0.6;   // seconds between the dealer's own draws
+const PAYOUT_HOLD = 2.6;   // seconds the result sits before the round clears
+
+export function cardValue(rank) { return rank >= 10 ? 10 : rank; }
+export function handValue(cards) {
+  let v = 0, aces = 0;
+  for (const c of cards) { v += cardValue(c.rank); if (c.rank === 1) aces++; }
+  while (aces > 0 && v + 10 <= 21) { v += 10; aces--; }
+  return v;
+}
+export function isSoft(cards) {
+  let v = 0, aces = 0;
+  for (const c of cards) { v += cardValue(c.rank); if (c.rank === 1) aces++; }
+  return aces > 0 && v + 10 <= 21;
+}
+export function isBlackjack(cards) { return cards.length === 2 && handValue(cards) === 21; }
+
+class Shoe {
+  constructor(decks = 6, rng = Math.random) { this.decks = decks; this.rng = rng; this.build(); }
+  build() {
+    this.cards = [];
+    for (let d = 0; d < this.decks; d++)
+      for (let s = 0; s < 4; s++)
+        for (let r = 1; r <= 13; r++) this.cards.push({ rank: r, suit: s });
+    this.shuffle();
+  }
+  shuffle() {
+    for (let i = this.cards.length - 1; i > 0; i--) {
+      const j = (this.rng() * (i + 1)) | 0;
+      const t = this.cards[i]; this.cards[i] = this.cards[j]; this.cards[j] = t;
+    }
+  }
+  get needsReshuffle() { return this.cards.length < 52; }
+  draw() { if (this.cards.length === 0) this.build(); return this.cards.pop(); }
+}
+
+export class Blackjack {
+  constructor(opts = {}) {
+    this.minBet = opts.minBet ?? 5;
+    this.maxBet = opts.maxBet ?? 500;
+    this.shoe = new Shoe(opts.decks ?? 6, opts.rng);
+    this.phase = PHASE.IDLE;
+    this.seats = [];           // [{ id, ai, cards, bet, standing, busted, result }] — turn order = insertion order
+    this.dealer = [];
+    this.holeRevealed = false;
+    this.turn = -1;            // index into seats of the seat whose turn it is (-1 = none)
+    this._t = 0;
+    this._pendingSettle = false;
+    // callbacks the presentation layer wires up (all optional)
+    this.onDeal = null;        // (targetId:'dealer'|seatId, card, faceUp, index)
+    this.onReveal = null;      // (holeCard)
+    this.onPhase = null;       // (phase)
+    this.onTurn = null;        // (seatId | null)  — whose turn it is now
+    this.onResult = null;      // (seatId, { outcome, delta })
+    this.onClear = null;       // () — round fully over, wipe the felt
+  }
+
+  addSeat(id, ai = false) { const s = { id, ai, cards: [], bet: 0, standing: false, busted: false, result: null }; this.seats.push(s); return s; }
+  seat(id) { return this.seats.find((s) => s.id === id); }
+  get current() { return this.turn >= 0 ? this.seats[this.turn] : null; }
+  handValue(id) { const s = this.seat(id); return s ? handValue(s.cards) : 0; }
+  get dealerValue() { return handValue(this.dealer); }
+  get dealerUpValue() { return this.holeRevealed ? handValue(this.dealer) : cardValue(this.dealer[0]?.rank ?? 0); }
+  canDouble(id, chips) { const s = this.seat(id); return this.phase === PHASE.PLAYER && this.current === s && !s.ai && s.cards.length === 2 && chips >= s.bet; }
+
+  _setPhase(p) { this.phase = p; this.onPhase?.(p); }
+  _give(target, faceUp) {
+    const arr = target === 'dealer' ? this.dealer : target.cards;
+    const c = this.shoe.draw();
+    arr.push(c);
+    this.onDeal?.(target === 'dealer' ? 'dealer' : target.id, c, faceUp, arr.length - 1);
+    return c;
+  }
+
+  // clear the table back to IDLE WITHOUT dealing — used when the player sits into an ambient hand or
+  // stands up. Fires onClear so the presentation wipes the felt.
+  reset() {
+    for (const s of this.seats) { s.cards = []; s.bet = 0; s.standing = false; s.busted = false; s.result = null; }
+    this.dealer = []; this.holeRevealed = false; this._t = 0; this.turn = -1; this._pendingSettle = false;
+    this._setPhase(PHASE.IDLE);
+    this.onClear?.();
+  }
+
+  // begin a round. `bets` is a map seatId -> stake (already reserved by the caller)
+  start(bets = {}) {
+    if (this.shoe.needsReshuffle) this.shoe.build();
+    for (const s of this.seats) { s.cards = []; s.bet = bets[s.id] ?? this.minBet; s.standing = false; s.busted = false; s.result = null; }
+    this.dealer = []; this.holeRevealed = false; this._t = 0; this.turn = -1;
+    this._setPhase(PHASE.DEALING);
+    for (const s of this.seats) this._give(s, true);        // round 1: each seat up
+    this._give('dealer', true);                              //          dealer up
+    for (const s of this.seats) this._give(s, true);        // round 2: each seat up
+    this._give('dealer', false);                             //          dealer hole (down)
+    for (const s of this.seats) if (isBlackjack(s.cards)) s.standing = true;   // naturals auto-stand
+    if (isBlackjack(this.dealer)) { this._enterDealer(); return this.phase; }
+    this._advanceTurn(-1);
+    return this.phase;
+  }
+
+  _advanceTurn(from) {
+    for (let i = from + 1; i < this.seats.length; i++) {
+      const s = this.seats[i];
+      if (!s.standing && !s.busted) { this.turn = i; this._t = 0; this._setPhase(PHASE.PLAYER); this.onTurn?.(s.id); return; }
+    }
+    this.turn = -1; this.onTurn?.(null); this._enterDealer();
+  }
+
+  // human input, only honoured for the current non-AI seat
+  hit(id) { const s = this.current; if (s && s.id === id && !s.ai && this.phase === PHASE.PLAYER) this._hit(s); }
+  stand(id) { const s = this.current; if (s && s.id === id && !s.ai && this.phase === PHASE.PLAYER) { s.standing = true; this._advanceTurn(this.turn); } }
+  double(id) {
+    const s = this.current;
+    if (!s || s.id !== id || s.ai || this.phase !== PHASE.PLAYER || s.cards.length !== 2) return;
+    s.bet *= 2; this._give(s, true); s.standing = true;
+    if (handValue(s.cards) > 21) s.busted = true;
+    this._advanceTurn(this.turn);
+  }
+  _hit(s) {
+    this._give(s, true);
+    if (handValue(s.cards) > 21) { s.busted = true; s.standing = true; this._advanceTurn(this.turn); }
+  }
+
+  update(dt) {
+    if (this.phase === PHASE.PLAYER) {
+      const s = this.current;
+      if (s && s.ai) {                                    // AI seat plays itself, paced
+        this._t += dt;
+        if (this._t >= AI_DELAY) {
+          this._t = 0;
+          if (handValue(s.cards) < 17) this._hit(s);
+          else { s.standing = true; this._advanceTurn(this.turn); }
+        }
+      }
+    } else if (this.phase === PHASE.DEALER) {
+      this._t += dt;
+      if (this._t < DEALER_STEP) return;
+      this._t = 0;
+      if (!this._pendingSettle && this.dealerValue < 17) { this._give('dealer', true); return; }
+      this._settle();
+    } else if (this.phase === PHASE.PAYOUT) {
+      this._t += dt;
+      if (this._t >= PAYOUT_HOLD) { this._t = 0; this._setPhase(PHASE.IDLE); this.onClear?.(); }
+    }
+  }
+
+  _enterDealer() {
+    this._setPhase(PHASE.DEALER);
+    this.holeRevealed = true; this.onReveal?.(this.dealer[1]);
+    this._t = 0;
+    // if every seat busted (or a natural is out), the dealer needn't draw
+    const anyAlive = this.seats.some((s) => !s.busted);
+    this._pendingSettle = !anyAlive || isBlackjack(this.dealer) || this.seats.every((s) => isBlackjack(s.cards));
+  }
+
+  // resolve every seat vs the dealer; `delta` is the amount to CREDIT back (stake was reserved on start)
+  _settle() {
+    const dv = this.dealerValue, dbj = isBlackjack(this.dealer);
+    for (const s of this.seats) {
+      const pv = handValue(s.cards), pbj = isBlackjack(s.cards);
+      let outcome, credit;
+      if (s.busted) { outcome = 'bust'; credit = 0; }
+      else if (pbj && !dbj) { outcome = 'blackjack'; credit = Math.floor(s.bet * 2.5); }
+      else if (dbj && !pbj) { outcome = 'lose'; credit = 0; }
+      else if (pbj && dbj) { outcome = 'push'; credit = s.bet; }
+      else if (dv > 21 || pv > dv) { outcome = 'win'; credit = s.bet * 2; }
+      else if (pv < dv) { outcome = 'lose'; credit = 0; }
+      else { outcome = 'push'; credit = s.bet; }
+      s.result = { outcome, delta: credit };
+      this.onResult?.(s.id, s.result);
+    }
+    this._setPhase(PHASE.PAYOUT);
+  }
+}

package/src/systems/casino/cards3d.js

@@ -0,0 +1,55 @@
+// 3D PLAYING CARDS — a clean public-domain vector deck, one PNG per card in public/assets/casino/cards/
+// (<rank><suit>.png, e.g. AS.png, 10H.png, KC.png, plus back.png). A card is a thin quad: top face = the
+// card's own texture, bottom face = the shared back. Sized to the Kiwi card (~0.06 × 0.09 m). All 52 faces
+// + the back preload in initCards() so makeCard() stays synchronous for the dealer.
+import * as THREE from 'three/webgpu';
+import { loadTexture } from '../../core/assets.js';
+
+export const CARD_W = 0.062;
+export const CARD_L = 0.090;                 // deck aspect ≈ 0.69
+const RANK = ['', 'A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K'];   // rank 1..13
+const SUITL = ['S', 'H', 'D', 'C'];           // matches engine SUITS: spades, hearts, diamonds, clubs
+
+const _tex = {};
+let _ready = null;
+
+async function load(name) {
+  if (_tex[name]) return _tex[name];
+  const t = await loadTexture(`/assets/casino/cards/${name}.png`);
+  t.colorSpace = THREE.SRGBColorSpace;
+  t.anisotropy = 8;
+  _tex[name] = t;
+  return t;
+}
+
+export async function initCards() {
+  if (_ready) return _ready;
+  _ready = (async () => {
+    const jobs = [load('back')];
+    for (let s = 0; s < 4; s++) for (let r = 1; r <= 13; r++) jobs.push(load(`${RANK[r]}${SUITL[s]}`));
+    await Promise.all(jobs);
+  })();
+  return _ready;
+}
+
+// A card lying flat: face (rank+suit) on +Y, back on −Y. suit is an index 0..3; rank is 1..13. Flip
+// face-down by rotating the group 180° about its long (Z) axis — then the back reads up.
+export function makeCard(rank, suit) {
+  const g = new THREE.Group();
+  const faceTex = _tex[`${RANK[rank]}${SUITL[suit]}`] || _tex['back'];
+
+  const face = new THREE.Mesh(new THREE.PlaneGeometry(CARD_W, CARD_L),
+    new THREE.MeshBasicNodeMaterial({ map: faceTex, toneMapped: true }));   // opaque white card art
+  face.rotation.x = -Math.PI / 2;             // lie flat, facing +Y
+  face.position.y = 0.0016;
+  g.add(face);
+
+  const back = new THREE.Mesh(new THREE.PlaneGeometry(CARD_W, CARD_L),
+    new THREE.MeshBasicNodeMaterial({ map: _tex['back'], toneMapped: true }));
+  back.rotation.x = Math.PI / 2;              // facing −Y
+  back.position.y = -0.0016;
+  g.add(back);
+
+  g.userData = { rank, suit };
+  return g;
+}

package/src/systems/casino/coins3d.js

@@ -0,0 +1,75 @@
+// GOLD COINS — the live wager on the felt, from Synty's PolygonCasino coin (SM_Prop_Coin_01, converted
+// to public/assets/casino/coin_01.glb). The GLB renders ~0.11 m across at native scale, so a stack is
+// built native-size and the whole group is shrunk to a believable coin and given a plain gold PBR
+// material — no atlas needed. A CoinStack tracks the current bet: raise it and a coin DROPS in from
+// just above with a little weight + bounce; lower it and a coin comes off the top.
+import * as THREE from 'three/webgpu';
+import { loadGLB } from '../../core/assets.js';
+
+const STACK_SCALE = 0.4;    // native 0.11 m coin → ~0.045 m
+const NATIVE_THICK = 0.016; // native coin thickness (m), before STACK_SCALE
+const DROP = 0.09;          // native units a coin falls from (≈ 3.6 mm above rest after scale)
+const GRAV = -3.2;          // native units/s² — falls the drop in ~0.25 s
+const REST = 0.3;           // bounce restitution
+const STOP = 0.12;          // |v| below which a coin is done bouncing
+const TAU = Math.PI * 2;
+
+let _proto = null, _mat = null, _ready = null;
+
+export async function initCoins() {
+  if (_ready) return _ready;
+  _ready = (async () => {
+    _proto = await loadGLB('/assets/casino/coin_01.glb');   // keep the whole node (its baked scale)
+    _mat = new THREE.MeshStandardNodeMaterial({ color: 0xd8a52a, metalness: 0.85, roughness: 0.34 });
+  })();
+  return _ready;
+}
+
+// how many coins to show for a bet — a readable stack, not a literal count (min a few, capped)
+export function coinsForBet(bet) { return Math.max(3, Math.min(16, Math.round(bet / 5) + 2)); }
+
+// A growable/shrinkable stack of gold coins. `group` sits at the bet spot (base on y=0, stacks +Y).
+export class CoinStack {
+  constructor() {
+    this.group = new THREE.Group();
+    this.group.scale.setScalar(STACK_SCALE);
+    this.coins = [];
+  }
+  count() { return this.coins.length; }
+
+  // match the stack to `n` coins — new ones drop in, extras come off the top
+  setCount(n) {
+    n = Math.max(0, n);
+    while (this.coins.length < n) this._add();
+    while (this.coins.length > n) this._remove();
+  }
+  _add() {
+    const i = this.coins.length;
+    const c = _proto.clone(true);
+    c.traverse((o) => { if (o.isMesh) o.material = _mat; });
+    c.rotation.y = Math.random() * TAU;                 // vary edges so it's not a clean cylinder
+    const restY = NATIVE_THICK * (i + 0.5);
+    c.position.y = restY + DROP;                         // start just above its resting height
+    this.group.add(c);
+    this.coins.push({ c, restY, v: 0, delay: Math.random() * 0.03, done: false });
+  }
+  _remove() {
+    const o = this.coins.pop();
+    if (o) this.group.remove(o.c);
+  }
+
+  // per-frame: let any un-settled coins fall + jingle to rest
+  settle(dt) {
+    for (const o of this.coins) {
+      if (o.done) continue;
+      if (o.delay > 0) { o.delay -= dt; continue; }
+      o.v += GRAV * dt;
+      o.c.position.y += o.v * dt;
+      if (o.c.position.y <= o.restY) {                  // hit the coin below (or the felt)
+        o.c.position.y = o.restY;
+        if (Math.abs(o.v) < STOP) { o.v = 0; o.done = true; }
+        else o.v = -o.v * REST;                          // little jingle
+      }
+    }
+  }
+}

package/src/systems/casino/table3d.js

@@ -0,0 +1,130 @@
+// BLACKJACK TABLE — the 3D presentation on top of the pure engine (blackjack.js). MULTI-SEAT: every
+// seat (you + AI) and the dealer has an anchor on the felt where its cards land; the table subscribes
+// to the engine's events so a dealt card becomes a card flying from the deck with the arc + flip.
+// No DOM here — the HUD is separate; this owns the felt (cards, deck, the human's coin wager).
+//
+// Anchors are LOCAL to the root Group placed at the table: { id, x, z, yaw } — yaw is the way that
+// seat faces (cards read toward it), cards spread along the seat's "right".
+import * as THREE from 'three/webgpu';
+import { Blackjack, PHASE, handValue } from './blackjack.js';
+import { makeCard, initCards } from './cards3d.js';
+import { initCoins, CoinStack, coinsForBet } from './coins3d.js';
+
+const DEAL_TRAVEL = 0.32;   // s, card flight
+const DEAL_ARC = 0.14;      // m, hop peak
+const DEAL_GAP = 0.15;      // s, between successive deals in a burst
+const SPREAD = 0.052;       // m, gap between cards in a hand
+const CARD_LIFT = 0.006;    // m above the felt
+
+const _pp = new THREE.Vector3(), _q0 = new THREE.Quaternion(), _q1 = new THREE.Quaternion();
+const ease = (t) => t * t * (3 - 2 * t);
+
+export class BlackjackTable {
+  // opts: { tableY, seats:[{id,x,z,yaw,ai}], dealer:{x,z,yaw}, deckPos:{x,z}, humanId, minBet, maxBet }
+  constructor(opts = {}) {
+    this.root = new THREE.Group();
+    this.tableY = opts.tableY ?? 0;
+    this.humanId = opts.humanId ?? 'you';
+    this.anchors = {};
+    for (const s of opts.seats) this.anchors[s.id] = s;
+    this.anchors['dealer'] = opts.dealer;
+    this.deck = { x: opts.deckPos?.x ?? 0, z: opts.deckPos?.z ?? 0.14 };
+    this.game = new Blackjack({ minBet: opts.minBet ?? 5, maxBet: opts.maxBet ?? 500 });
+    for (const s of opts.seats) this.game.addSeat(s.id, !!s.ai);
+    this.meshes = {};                      // id -> [card meshes]
+    for (const id of Object.keys(this.anchors)) this.meshes[id] = [];
+    this._queue = []; this._gap = 0; this._anims = [];
+    this._wire();
+  }
+
+  async load() {
+    await Promise.all([initCards(), initCoins()]);
+    // the DRAW PILE (shoe)
+    this.deckPile = new THREE.Group();
+    for (let i = 0; i < 16; i++) {
+      const c = makeCard(1, 0);
+      c.rotation.set(Math.PI, (Math.random() - 0.5) * 0.12, 0);
+      c.position.set(this.deck.x, this.tableY + CARD_LIFT + i * 0.0016, this.deck.z);
+      this.deckPile.add(c);
+    }
+    this.root.add(this.deckPile);
+    // the human's coin wager sits just inboard of their card row
+    const h = this.anchors[this.humanId];
+    this.betCoins = new CoinStack();
+    this.betCoins.group.position.set(h.x * 0.72, this.tableY, h.z * 0.72);
+    this.root.add(this.betCoins.group);
+    return this;
+  }
+
+  _wire() {
+    const g = this.game;
+    g.onDeal = (id, card, faceUp) => this._queue.push({ id, card, faceUp });
+    g.onReveal = () => { const m = this.meshes['dealer'][1]; if (m) this._flip(m, true); };
+    g.onClear = () => this._clearFelt();
+  }
+
+  // where card `i` of a hand sits at seat `id` (centred, spread along the seat's right)
+  _slot(id, i, total) {
+    const a = this.anchors[id];
+    const rx = Math.cos(a.yaw), rz = -Math.sin(a.yaw);        // right ⟂ forward=(sin,cos)
+    const off = (i - (total - 1) / 2) * SPREAD;
+    return _pp.set(a.x + rx * off, this.tableY + CARD_LIFT + i * 0.001, a.z + rz * off);
+  }
+  _relayout(id) {
+    const arr = this.meshes[id];
+    for (let i = 0; i < arr.length; i++) {
+      const m = arr[i]; if (m.userData._flying) continue;
+      const s = this._slot(id, i, arr.length); m.position.set(s.x, s.y, s.z);
+    }
+  }
+
+  _startDeal(job) {
+    const { id, card, faceUp } = job;
+    const a = this.anchors[id], arr = this.meshes[id];
+    const mesh = makeCard(card.rank, card.suit);
+    mesh.rotation.set(Math.PI, a.yaw, 0);                     // start face-down, facing the seat
+    mesh.position.set(this.deck.x, this.tableY + 0.02, this.deck.z);
+    this.root.add(mesh); arr.push(mesh); this._relayout(id);
+    const dest = this._slot(id, arr.length - 1, arr.length);
+    mesh.userData._flying = true;
+    _q0.setFromEuler(new THREE.Euler(Math.PI, a.yaw, 0));
+    _q1.setFromEuler(new THREE.Euler(faceUp ? 0 : Math.PI, a.yaw, 0));
+    this._anims.push({
+      mesh, t: 0, dur: DEAL_TRAVEL, arc: DEAL_ARC,
+      p0: new THREE.Vector3(this.deck.x, this.tableY + 0.02, this.deck.z), p1: dest.clone(),
+      q0: _q0.clone(), q1: _q1.clone(),
+      onDone: () => { mesh.userData._flying = false; this._relayout(id); },
+    });
+  }
+  _flip(mesh, faceUp) {
+    _q1.setFromEuler(new THREE.Euler(faceUp ? 0 : Math.PI, mesh.rotation.y, 0));
+    this._anims.push({ mesh, t: 0, dur: 0.22, arc: 0, p0: mesh.position.clone(), p1: mesh.position.clone(), q0: mesh.quaternion.clone(), q1: _q1.clone() });
+  }
+  _clearFelt() {
+    for (const id of Object.keys(this.meshes)) { for (const m of this.meshes[id]) this.root.remove(m); this.meshes[id] = []; }
+    this._queue.length = 0; this._anims.length = 0;   // drop in-flight/pending cards too, or a reset (e.g. sitting into an ambient hand) redeals them onto the just-cleared felt as ghosts
+  }
+
+  setBet(amount) { this.betCoins?.setCount(coinsForBet(amount)); }
+  deal(bets) { this._clearFelt(); this._queue.length = 0; this._anims.length = 0; this.game.start(bets); }
+  hit(id) { this.game.hit(id); }
+  stand(id) { this.game.stand(id); }
+  double(id) { this.game.double(id); }
+  // true while cards are still flying/pacing — the HUD uses it to know the felt is settling
+  get busy() { return this._queue.length > 0 || this._anims.length > 0; }
+
+  update(dt) {
+    this.betCoins?.settle(dt);
+    this._gap -= dt;
+    if (this._queue.length && this._gap <= 0) { this._startDeal(this._queue.shift()); this._gap = DEAL_GAP; }
+    for (let i = this._anims.length - 1; i >= 0; i--) {
+      const a = this._anims[i]; a.t += dt;
+      const k = Math.min(1, a.t / a.dur), e = ease(k);
+      _pp.lerpVectors(a.p0, a.p1, e); _pp.y += Math.sin(k * Math.PI) * a.arc;
+      a.mesh.position.copy(_pp);
+      a.mesh.quaternion.slerpQuaternions(a.q0, a.q1, e);
+      if (k >= 1) { a.onDone?.(); this._anims.splice(i, 1); }
+    }
+    if (!this._queue.length && !this._anims.length) this.game.update(dt);   // engine paces AI/dealer only once the felt has caught up
+  }
+}

package/src/systems/climbing.js

@@ -0,0 +1,136 @@
+// Climbing: the player's ladder controller — ported from fable/src/game/climbing.js and adapted to
+// western. The climb clips (climbMount/Up/Down/Top/Idle) are already retargeted onto the player rig
+// through the normal clip pipeline (clips.js → the default Synty rig), so this just snaps the player to
+// a registered ladder and runs mount → up/down loop (code-driven vertical) → climb-off.
+//
+// Ladders come from world.ladders (town.js buildLadders): [{ base:Vector3(world), quat:Quaternion(world),
+// height }]. main.js's E-contest resolves the nearest one and calls mount(l). Mirrors Riding's
+// "takes over the player's update + camera" shape; player.update early-returns while active.
+import * as THREE from 'three/webgpu';
+
+const CLIMB_SPEED = 1.7;   // m/s along the rungs (match the up/down loop cadence)
+const ANIM_SPEED = 2;      // clip playback ×; the mocap loops are slow, so 2× keeps the hands with the movement
+const BODY_OFF = 0.30;     // player root sits this far back from the ladder line (gripping side)
+const FACE_SIGN = 1;       // +1 for western's ladder props (fable used −1); flips which side the climber grips + faces
+const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+const _axis = new THREE.Vector3(), _face = new THREE.Vector3();
+
+export class Climbing {
+  constructor(player) {
+    this.player = player;
+    this.game = player.game;
+    this.mode = 'off';      // off | mounting | climbing | dismounting
+    this.ladder = null; this.h = 0; this.faceYaw = 0; this.height = 0;
+  }
+
+  get active() { return this.mode !== 'off'; }   // getter — never assign it; forceOff() resets the raw fields
+
+  // up-the-rungs axis (from the prop quat) + the horizontal yaw to face INTO the ladder
+  _solve(l) {
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();      // climb direction
+    _face.set(_axis.x, 0, _axis.z);                              // a leaning ladder tilts away from the wall
+    if (_face.lengthSq() < 1e-3) _face.set(0, 0, 1).applyQuaternion(l.quat).setY(0);   // vertical ladder → prop +Z
+    _face.normalize();
+    this.faceYaw = Math.atan2(FACE_SIGN * _face.x, FACE_SIGN * _face.z);
+  }
+
+  // Cap the climb at the SURFACE you step onto. The ladder MESH runs from its base to its own top, which
+  // sits above the roofline (a real ladder pokes past the eaves). Raycast down over the ladder top, nudged
+  // toward the building, for the highest roof/floor at/below the mesh top, and top the climb out there so
+  // you don't climb off into thin air. Falls back to the mesh height if no surface is found.
+  _resolveHeight(l) {
+    const W = this.game.world;
+    const bvhs = [W.buildingBVH, ...(W.sideBVHs || [])].filter((b) => b && b.raycast);
+    if (!bvhs.length || !W._snapRay) return l.height;
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    const sx = l.base.x + _axis.x * l.height + Math.sin(this.faceYaw) * 0.7;   // over the top, onto the roof
+    const sz = l.base.z + _axis.z * l.height + Math.cos(this.faceYaw) * 0.7;
+    const ray = W._snapRay; ray.origin.set(sx, l.base.y + l.height + 4, sz); ray.direction.set(0, -1, 0);
+    let roof = -Infinity;
+    for (const b of bvhs) {
+      const hs = b.raycast(ray, 2) || [];
+      for (const h of hs) {
+        const n = h.face?.normal;
+        if (n && Math.abs(n.y) > 0.4 && h.point.y > roof && h.point.y <= l.base.y + l.height + 0.3) roof = h.point.y;
+      }
+    }
+    return roof > l.base.y + 1 ? Math.min(l.height, roof - l.base.y + 0.15) : l.height;
+  }
+
+  // ENTRY — main.js's E-contest resolves the nearest ladder and calls this. Enters at the bottom, or the
+  // top if you walked onto it from the roof platform.
+  mount(l) {
+    if (this.active || !l) return;
+    this._solve(l);
+    this.height = this._resolveHeight(l);   // cap the climb at the surface you step ONTO (the mesh pokes above)
+    // Enter at YOUR height on the rungs — project (you − base) onto the climb axis — so grabbing from the
+    // street enters at the bottom, from the roof at the top, and RE-GRABBING MID-AIR (after a hop-off)
+    // continues from where you are instead of snapping to an end.
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    const p = this.player.position;
+    const hAlong = (p.x - l.base.x) * _axis.x + (p.y - l.base.y) * _axis.y + (p.z - l.base.z) * _axis.z;
+    this.ladder = l; this.mode = 'mounting'; this.h = clamp(hAlong, 0, this.height);
+    this._place(); this.player.busy = true;
+    this.player.animator.play('climbMount', { once: true, fade: 0.12, timeScale: ANIM_SPEED, onDone: () => { if (this.mode === 'mounting') this.mode = 'climbing'; } });
+  }
+
+  // place the player at height h along the rungs, set back from the ladder by BODY_OFF, facing it
+  _place() {
+    const l = this.ladder, p = this.player;
+    _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+    p.position.x = l.base.x + _axis.x * this.h - Math.sin(this.faceYaw) * BODY_OFF;
+    p.position.z = l.base.z + _axis.z * this.h - Math.cos(this.faceYaw) * BODY_OFF;
+    p.position.y = l.base.y + _axis.y * this.h;
+    p._visualY = p.position.y;                  // keep the model lift glued to the climb height
+    p.heading = this.faceYaw; p.root.rotation.y = this.faceYaw;
+  }
+
+  update(dt, input, camera) {
+    const p = this.player, l = this.ladder;
+    const ui = this.game.ui;
+    const inMenu = ui?.anyPanelOpen || ui?.dialogueOpen || ui?.cinematic;
+    if (this.mode === 'climbing') {
+      let v = 0;
+      if (!inMenu) { if (input.down('KeyW')) v += 1; if (input.down('KeyS')) v -= 1; }   // held W/S
+      p.animator.play(v > 0 ? 'climbUp' : v < 0 ? 'climbDown' : 'climbIdle', { fade: 0.12, timeScale: ANIM_SPEED });
+      this.h = clamp(this.h + v * CLIMB_SPEED * dt, 0, this.height);
+      this._place();
+      if (this.h >= this.height && v > 0) {                    // reached the top → climb off
+        this.mode = 'dismounting';
+        p.animator.play('climbTop', { once: true, fade: 0.12, timeScale: ANIM_SPEED, onDone: () => this._dismount(true) });
+      } else if (this.h <= 0 && v < 0) this._dismount(false);  // stepped off the bottom
+      else if (!inMenu && input.hit('Space')) this._dismount(false); // hop off anywhere
+    } else {
+      this._place();                                            // mounting | dismounting — hold while the clip plays
+    }
+    // Reuse the player's OWN look + follow camera (not a bespoke one) so the on-foot ↔ climb transition is
+    // seamless — _camera reads position + _visualY, which _place() keeps synced to the climb height.
+    if (!inMenu) p._look?.(input, this.game.rawDt ?? dt);
+    p._camera(dt, input, camera);
+  }
+
+  _dismount(top) {
+    const l = this.ladder, p = this.player;
+    if (top) {                                                 // step forward off the top onto the surface
+      _axis.set(0, 1, 0).applyQuaternion(l.quat).normalize();
+      p.position.x = l.base.x + _axis.x * this.height + Math.sin(this.faceYaw) * 0.7;
+      p.position.z = l.base.z + _axis.z * this.height + Math.cos(this.faceYaw) * 0.7;
+      p.position.y = l.base.y + _axis.y * this.height + 0.1;
+    }
+    this.mode = 'off'; this.ladder = null;
+    // PIN _visualY to the current feet height, NOT undefined: this same frame the climb update still calls
+    // p._camera(), which reads `_visualY + 1.55` — undefined there = NaN = a grey (void) screen. position.y
+    // is valid, and the on-foot smoother continues cleanly from it next frame.
+    p.busy = false; p.vy = 0; p.airborne = false; p._visualY = p.position.y;
+    p.animator.play('idle', { fade: 0.15 });
+  }
+
+  // Hard exit for death / fast-travel / load — a LIVE controller re-glues the player to the ladder every
+  // frame via _place(), silently undoing any teleport. Reset the raw fields (never assign .active).
+  forceOff() {
+    if (!this.active) return;
+    const p = this.player;
+    this.mode = 'off'; this.ladder = null;
+    p.busy = false; p.vy = 0; p.airborne = false; p._visualY = p.position.y;
+  }
+}