Skip to content

A free, open-source framework for cinematic, interactive 3D websites with AI-generated assets (Nano Banana 2 + Meshy 7.1 on fal). 20 example sites.

10.8 KB
Raw Blame
// The walker. Scroll sets a target distance along the traverse; the astronaut follows it with a soft speed cap.
// The gait phase is advanced by *distance* (not time), so planted boots never slide at any scroll speed:
// walk → lunar lope (the run clip, slowed, with extra 1/6 g flight) → "time-lapse" when you scroll hard.
// Idle is synthesised (the Meshy idle preset is broken): suit rest pose, arms eased down, breathing.
import { THREE, damp, clamp, smooth, lerp } from '../../src/core/engine.js';

const V = () => new THREE.Vector3();

function analyse(model, mixer, clip, bones) {
  const act = mixer.clipAction(clip);
  mixer.stopAllAction();
  act.reset().play().setEffectiveWeight(1);
  const N = 96, rows = [];
  const a = V(), b = V();
  for (let i = 0; i <= N; i++) {
    act.time = (clip.duration * i) / N; mixer.update(0); model.updateMatrixWorld(true);
    bones.lf.getWorldPosition(a); bones.rf.getWorldPosition(b);
    rows.push({ t: act.time, ly: a.y, lz: a.z, ry: b.y, rz: b.z });
  }
  act.stop();
  const minL = Math.min(...rows.map(r => r.ly)), minR = Math.min(...rows.map(r => r.ry));
  // stance velocity: foot low and moving backwards relative to the hips
  let vs = 0, vn = 0;
  for (let i = 1; i < rows.length; i++) {
    const p = rows[i - 1], q = rows[i], dt = q.t - p.t;
    if (p.ly < minL + 0.012 && q.ly < minL + 0.012) { vs += -(q.lz - p.lz) / dt; vn++; }
    if (p.ry < minR + 0.012 && q.ry < minR + 0.012) { vs += -(q.rz - p.rz) / dt; vn++; }
  }
  const speed = vs / Math.max(1, vn);
  // left heel strike phase
  let contact = 0;
  for (let i = 1; i < rows.length; i++) if (rows[i].ly < minL + 0.014 && rows[i - 1].ly >= minL + 0.014) { contact = i / N; break; }
  // flight: both feet clearly off the ground
  const air = rows.map(r => (r.ly > minL + 0.03 && r.ry > minR + 0.03 ? 1 : 0));
  const lift = new Float32Array(N + 1);
  for (let i = 0; i <= N; i++) {
    if (!air[i]) continue;
    let s = i, e = i;
    while (s > 0 && air[s - 1]) s--;
    while (e < N && air[e + 1]) e++;
    lift[i] = Math.sin(Math.PI * (i - s + 0.5) / (e - s + 1));
  }
  return { speed, stride: speed * clip.duration, contact, lift, footY: (minL + minR) / 2 };
}

function idleClip(model, bones) {
  // Rest pose tracks for every animated bone, with the arms lowered and a slow breathing cycle.
  model.updateMatrixWorld(true);
  const rest = new Map();
  model.traverse(o => { if (o.isBone) rest.set(o, { q: o.quaternion.clone(), p: o.position.clone() }); });
  const worldQ = o => o.getWorldQuaternion(new THREE.Quaternion());
  const lowerArm = (arm, fore, down, fwd) => {
    const d = fore.getWorldPosition(V()).sub(arm.getWorldPosition(V())).normalize();
    const axis = V().crossVectors(d, V().set(0, -1, 0)).normalize();
    const qW = new THREE.Quaternion().setFromAxisAngle(axis, down);
    const newW = qW.multiply(worldQ(arm));
    const parentW = worldQ(arm.parent);
    arm.quaternion.copy(parentW.invert().multiply(newW));
    arm.updateMatrixWorld(true);
    // bend the elbow forward a touch
    const d2 = fore.children[0]?.getWorldPosition(V()).sub(fore.getWorldPosition(V())).normalize() ?? V(0, -1, 0);
    const ax2 = V().crossVectors(d2, V().set(0, 0, 1)).normalize();
    const q2 = new THREE.Quaternion().setFromAxisAngle(ax2, fwd).multiply(worldQ(fore));
    fore.quaternion.copy(worldQ(fore.parent).invert().multiply(q2));
    fore.updateMatrixWorld(true);
  };
  lowerArm(bones.la, bones.lfa, 0.36, 0.3);
  lowerArm(bones.ra, bones.rfa, 0.36, 0.3);
  const pose = new Map();
  model.traverse(o => { if (o.isBone) pose.set(o, { q: o.quaternion.clone(), p: o.position.clone() }); });
  // restore rest so the mixer's bindings see the true bind pose
  for (const [o, r] of rest) { o.quaternion.copy(r.q); o.position.copy(r.p); }
  const T = 4.8, times = [0, 1.2, 2.4, 3.6, 4.8];
  const tracks = [];
  const breathe = [0, 1, 0, -1, 0];
  for (const [o, s] of pose) {
    const vals = [];
    for (let k = 0; k < times.length; k++) {
      const q = s.q.clone();
      const b = breathe[k];
      if (o === bones.spine) q.multiply(new THREE.Quaternion().setFromEuler(new THREE.Euler(b * 0.018, 0, 0)));
      if (o === bones.head) q.multiply(new THREE.Quaternion().setFromEuler(new THREE.Euler(0.03 + b * 0.01, Math.sin(k / 4 * Math.PI * 2) * 0.05, 0)));
      if (o === bones.la || o === bones.ra) q.multiply(new THREE.Quaternion().setFromEuler(new THREE.Euler(b * 0.02, 0, 0)));
      vals.push(q.x, q.y, q.z, q.w);
    }
    tracks.push(new THREE.QuaternionKeyframeTrack(`${o.name}.quaternion`, times, vals));
    if (o === bones.hips) {
      const pv = [];
      for (let k = 0; k < times.length; k++) pv.push(s.p.x, s.p.y + breathe[k] * 0.35 - 0.6, s.p.z);
      tracks.push(new THREE.VectorKeyframeTrack(`${o.name}.position`, times, pv));
    }
  }
  return new THREE.AnimationClip('idle-synth', T, tracks);
}

export class Astronaut {
  constructor(gltf, H, { onStep, onLift } = {}) {
    this.H = H; this.onStep = onStep; this.onLift = onLift;
    this.root = new THREE.Group();
    this.model = gltf.scene;
    this.root.add(this.model);
    const get = n => this.model.getObjectByName(n);
    this.bones = { hips: get('Hips'), lf: get('LeftFoot'), rf: get('RightFoot'), lt: get('LeftToeBase'), rt: get('RightToeBase'),
      spine: get('Spine01'), head: get('Head'), la: get('LeftArm'), ra: get('RightArm'), lfa: get('LeftForeArm'), rfa: get('RightForeArm') };
    this.model.traverse(o => { if (o.isSkinnedMesh) { o.frustumCulled = false; this.mesh = o; } });
    this.mixer = new THREE.AnimationMixer(this.model);
    const clip = n => gltf.animations.find(a => a.name === n);
    this.walkClip = clip('walk'); this.runClip = clip('run');
    this.walkInfo = analyse(this.model, this.mixer, this.walkClip, this.bones);
    this.runInfo = analyse(this.model, this.mixer, this.runClip, this.bones);
    this.idle = idleClip(this.model, this.bones);
    this.mixer.stopAllAction();
    this.aWalk = this.mixer.clipAction(this.walkClip).play();
    this.aRun = this.mixer.clipAction(this.runClip).play();
    this.aIdle = this.mixer.clipAction(this.idle).play();
    this.aWalk.timeScale = 0; this.aRun.timeScale = 0;
    this.runOffset = this.runInfo.contact - this.walkInfo.contact;
    // state
    this.curve = H.curve; this.len = this.curve.getLength();
    this.d = 0; this.v = 0; this.phase = 0.12; this.moveW = 0; this.runW = 0; this.yaw = 0;
    this.stillT = 10; this.steps = 0; this.lift = 0;
    this.feet = [
      { ankle: this.bones.lf, toe: this.bones.lt, down: false, side: 'L' },
      { ankle: this.bones.rf, toe: this.bones.rt, down: false, side: 'R' },
    ];
    this.pos = V(); this.fwd = V(1, 0, 0); this.side = V(0, 0, 1);
    this._a = V(); this._b = V(); this._t = V();
    this.pose(0, 0);
    console.info(`[artemis] walk ${this.walkInfo.speed.toFixed(2)} m/s stride ${this.walkInfo.stride.toFixed(2)} m · run ${this.runInfo.speed.toFixed(2)} m/s stride ${this.runInfo.stride.toFixed(2)} m · offset ${this.runOffset.toFixed(3)}`);
  }

  get stride() { return lerp(this.walkInfo.stride, this.runInfo.stride, this.runW); }

  // Place root on the path at distance d and evaluate the blended pose at the current phase.
  pose(dt, idleDt) {
    const u = clamp(this.d / this.len, 0, 1);
    const p = this.curve.getPointAt(u), tg = this.curve.getTangentAt(u);
    const yaw = Math.atan2(tg.x, tg.z);
    this.yaw = this.yawInit ? yaw : yaw; this.yawInit = true;
    const ph = ((this.phase % 1) + 1) % 1;
    const rph = (((this.phase + this.runOffset) % 1) + 1) % 1;
    const li = this.runInfo.lift, n = li.length - 1, fi = rph * n, i0 = Math.floor(fi);
    const lift = (li[i0] + (li[Math.min(n, i0 + 1)] - li[i0]) * (fi - i0)) * this.runW * this.moveW;
    this.lift = lift;
    this.root.position.set(p.x, this.H.heightAt(p.x, p.z) + lift * 0.3 - 0.004, p.z);
    this.root.rotation.y = this.yaw + (this.yawOffset || 0);
    this.fwd.set(Math.sin(this.yaw), 0, Math.cos(this.yaw));
    this.side.set(this.fwd.z, 0, -this.fwd.x).negate();
    this.pos.copy(this.root.position);
    const w = this.moveW;
    this.aWalk.setEffectiveWeight(w * (1 - this.runW));
    this.aRun.setEffectiveWeight(w * this.runW);
    this.aIdle.setEffectiveWeight(1 - w);
    this.aWalk.time = ph * this.walkClip.duration;
    this.aRun.time = rph * this.runClip.duration;
    this.mixer.update(idleDt);
    this.root.updateMatrixWorld(true);
  }

  detect(emit, time) {
    const moving = this.moveW > 0.55 && this.v > 0.04;
    for (const f of this.feet) {
      const a = f.ankle.getWorldPosition(this._a), t = f.toe.getWorldPosition(this._b);
      const h = a.y - this.root.position.y;
      const low = this.walkInfo.footY + 0.016, high = this.walkInfo.footY + 0.05;
      if (!f.down && h < low && (moving || !emit)) {
        f.down = true;
        if (moving && emit) {
          const dir = this._t.copy(t).sub(a); dir.y = 0; dir.normalize();
          const cx = a.x + dir.x * 0.07, cz = a.z + dir.z * 0.07;
          this.steps++;
          this.onStep?.({ x: cx, z: cz, yaw: Math.atan2(dir.x, dir.z), foot: f.side, speed: this.v, lope: this.runW, time, toe: t.clone() });
        }
      } else if (f.down && h > high) {
        f.down = false;
        if (moving && emit) this.onLift?.({ toe: t.clone(), fwd: this.fwd.clone(), speed: this.v, lope: this.runW, time });
      }
    }
  }

  // Jump straight to distance d, stamping every print along the way (reload mid-page, nav links).
  simulateTo(d, stamp) {
    const saveOn = this.onLift; this.onLift = null;
    this.moveW = 1; this.runW = 0; this.v = 1;
    while (this.d < d - 0.05) {
      const s = Math.min(0.08, d - this.d);
      this.d += s; this.phase += s / this.stride;
      this.pose(0, 0);
      this.detect(stamp, 0);
    }
    this.onLift = saveOn;
    this.v = 0; this.moveW = 0;
  }

  update(dt, target, time) {
    target = clamp(target, 0, this.len - 0.4);
    const gap = target - this.d;
    const vmax = 2.5 + Math.max(0, Math.abs(gap) - 5) * 1.4;
    const vDes = clamp(gap * 2.1, -vmax, vmax);
    this.v = damp(this.v, vDes, 3.2, dt);
    if (Math.abs(gap) < 0.004 && Math.abs(this.v) < 0.02) this.v = 0;
    const sp = Math.abs(this.v);
    this.stillT = sp > 0.05 ? 0 : this.stillT + dt;
    this.moveW = damp(this.moveW, this.stillT < 0.18 ? 1 : 0, this.stillT < 0.18 ? 5 : 3, dt);
    this.runW = damp(this.runW, smooth(1.6, 2.8, sp), 2.5, dt);
    // never walk past the ends of the traverse (the damped velocity would otherwise overshoot)
    const dMax = this.len - 0.4;
    if (this.d + this.v * dt > dMax) this.v = Math.max(0, (dMax - this.d) / dt);
    if (this.d + this.v * dt < 0) this.v = Math.min(0, -this.d / dt);
    const ds = this.v * dt;
    const n = Math.min(24, Math.max(1, Math.ceil(Math.abs(ds) / 0.09)));
    for (let k = 1; k <= n; k++) {
      this.d += ds / n;
      this.phase += ds / n / this.stride;
      this.pose(k === n ? dt : 0, k === n ? dt : 0);
      this.detect(true, time - dt * (1 - k / n));
    }
  }
}