kasaframe 0.1.3 → 0.1.5

package/themes/marble-run/effects.ts

@@ -0,0 +1,678 @@
+import { clamp, ease, toEase, type EaseName, type SceneCtx } from "@kasaframe/core";
+import { dropBurst } from "@kasaframe/motion";
+import { stage3d, textPlane, THREE, type Stage3D } from "@kasaframe/themes/stage3d";
+
+// 벽에 걸린 구슬 조형 — 벽은 z=0, 장치는 벽에서 +z 로 나와 있고 카메라는 +z 쪽 조금 위·오른쪽에서 본다.
+// 움직이는 것은 구슬(요청)과 장치가 일하는 순간(레일이 놓이고·갈림판이 넘어가고·문이 열리고)뿐, 벽은 서 있다
+
+type V3 = [number, number, number];
+
+const col = (ctx: SceneCtx, k: string) => new THREE.Color(ctx.style.colors[k] ?? k);
+const steelMat = (ctx: SceneCtx) => new THREE.MeshStandardMaterial({ color: col(ctx, "steel"), metalness: 0.9, roughness: 0.22 });
+const brassMat = (ctx: SceneCtx) => new THREE.MeshStandardMaterial({ color: col(ctx, "brass"), metalness: 0.75, roughness: 0.32 });
+const shade = <T extends THREE.Object3D>(m: T): T => {
+  m.castShadow = true;
+  m.receiveShadow = true;
+  return m;
+};
+// 구슬 무리 — 경계 구를 첫 프레임(다 숨은 채 원점)에서 한 번 잡아 두면 원점에서 먼 세트의 구슬이 통째로 잘린다. 자르지 않는다
+function swarm(ctx: SceneCtx, r: number, n: number, colors: readonly string[]): THREE.InstancedMesh {
+  const mesh = shade(new THREE.InstancedMesh(new THREE.SphereGeometry(r, 16, 12), new THREE.MeshStandardMaterial({ roughness: 0.08, metalness: 0.05 }), Math.max(1, n)));
+  mesh.frustumCulled = false;
+  for (let i = 0; i < n; i++) mesh.setColorAt(i, col(ctx, colors[i % colors.length]));
+  return mesh;
+}
+// 장치가 「톡」 놓이는 손 — 살짝 넘쳤다 앉는다
+const pop = (t: number, at: number, dur = 0.3) => (t < at ? 0 : ease.outBack(clamp((t - at) / dur)));
+const G = 9;
+// 구슬 반지름 — 레일 두 가닥(간격 0.26) 위에 얹히면 가운데가 레일 선보다 이만큼 뜬다
+const R = 0.2;
+const LIFT = 0.19;
+const HIDE = new THREE.Matrix4().makeScale(0, 0, 0);
+
+// ── 무대 ─────────────────────────────────────────────────────────────
+
+export interface MarbleKey {
+  t: number;
+  /** 벽 위 보는 곳(x, y) */
+  look: [number, number];
+  /** 벽에서 카메라까지 — 작을수록 다가간다 */
+  dist?: number;
+  /** 앞 키에서 이 키로 오는 이징. 기본 inOutCubic */
+  ease?: EaseName;
+}
+
+export interface MarbleShot {
+  from: number;
+  to: number;
+  /** 키 사이만 움직이고 키에서 선다 — 다가가기·물러나기·구슬 따라가기처럼 까닭이 있을 때만 */
+  keys: MarbleKey[];
+}
+
+function camAt(t: number, keys: MarbleKey[]): { x: number; y: number; d: number } {
+  const ks = [...keys].sort((a, b) => a.t - b.t);
+  const v = (k: MarbleKey) => ({ x: k.look[0], y: k.look[1], d: k.dist ?? 22 });
+  if (t <= ks[0].t) return v(ks[0]);
+  for (let i = 1; i < ks.length; i++) {
+    if (t >= ks[i].t) continue;
+    const [a, b] = [v(ks[i - 1]), v(ks[i])];
+    const u = toEase(ks[i].ease ?? "inOutCubic")((t - ks[i - 1].t) / Math.max(1e-6, ks[i].t - ks[i - 1].t));
+    return { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u, d: a.d + (b.d - a.d) * u };
+  }
+  return v(ks[ks.length - 1]);
+}
+
+/**
+ * 구슬 조형 무대 — 호두나무 벽 한 장, 위쪽 키라이트 하나(레일·구슬 그림자가 벽에 떨어진다), 강철이 비칠 방 빛.
+ * 컷마다 벽의 다른 자리(세트)를 보고, 카메라는 키로만 다가가고 물러난다
+ */
+export function marbleStage(el: HTMLElement, o: { ctx: SceneCtx; shots: MarbleShot[] }): ((t: number) => void) & Stage3D {
+  const { ctx } = o;
+  const shots = [...o.shots].sort((a, b) => a.from - b.from);
+  const shotAt = (t: number) => shots.find((x) => t >= x.from && t < x.to) ?? shots[shots.length - 1];
+  const stage = stage3d(el, {
+    ctx,
+    camera: "perspective",
+    fov: 32,
+    env: true,
+    exposure: 1.05,
+    background: ctx.style.colors.bg,
+    shot(t, cam) {
+      const k = camAt(t, shotAt(t).keys);
+      cam.position.set(k.x + 1.2, k.y + 1.6, k.d);
+      cam.lookAt(k.x, k.y, 0.4);
+    },
+  });
+  // 키라이트를 받으면 벽이 밝아진다 — 찍힌 벽이 바탕색 쯤 되게 어둡게 칠해 두면 구슬이 벽에서 또렷이 떠오른다
+  const wall = new THREE.Mesh(new THREE.PlaneGeometry(600, 80), new THREE.MeshStandardMaterial({ color: col(ctx, "bg").multiplyScalar(0.62), roughness: 0.92, metalness: 0 }));
+  wall.position.set(200, 0, 0);
+  wall.receiveShadow = true;
+  stage.scene.add(wall);
+  stage.scene.add(new THREE.HemisphereLight(0xfff1dc, 0x3a2a1e, 0.55));
+  const key = new THREE.DirectionalLight(0xffe2b8, 2.4);
+  key.castShadow = true;
+  key.shadow.mapSize.set(1024, 1024);
+  Object.assign(key.shadow.camera as THREE.OrthographicCamera, { left: -15, right: 15, top: 10, bottom: -10, near: 1, far: 60 });
+  key.shadow.bias = -0.0006;
+  stage.scene.add(key, key.target);
+  return Object.assign((t: number) => {
+    const [x, y] = shotAt(t).keys[0].look;
+    key.position.set(x - 7, y + 12, 16);
+    key.target.position.set(x, y, 0);
+    key.target.updateMatrixWorld();
+    stage.paint(t);
+  }, stage);
+}
+
+// ── 레일과 구슬 ─────────────────────────────────────────────────────────
+
+interface Track {
+  curve: THREE.CatmullRomCurve3;
+  pts: THREE.Vector3[];
+  s: number[];
+  total: number;
+}
+
+function track(points: readonly V3[], closed = false): Track {
+  const curve = new THREE.CatmullRomCurve3(points.map((p) => new THREE.Vector3(...p)), closed, "centripetal");
+  const n = Math.max(60, Math.ceil(curve.getLength() / 0.05));
+  const pts = curve.getSpacedPoints(n);
+  const s = [0];
+  for (let i = 1; i < pts.length; i++) s.push(s[i - 1] + pts[i].distanceTo(pts[i - 1]));
+  return { curve, pts, s, total: s[s.length - 1] };
+}
+
+function pointAt(tr: Track, len: number, out = new THREE.Vector3()): THREE.Vector3 {
+  const x = clamp(len, 0, tr.total);
+  let lo = 0;
+  let hi = tr.s.length - 1;
+  while (hi - lo > 1) {
+    const m = (lo + hi) >> 1;
+    if (tr.s[m] <= x) lo = m;
+    else hi = m;
+  }
+  const k = (x - tr.s[lo]) / (tr.s[hi] - tr.s[lo] || 1);
+  return out.copy(tr.pts[lo]).lerp(tr.pts[hi], k);
+}
+
+export interface RailOpts {
+  ctx: SceneCtx;
+  /** 레일 가운데 선의 꼭짓점 — 벽에서 z 만큼 나와 있다. 순 수직은 피한다(두 가닥이 겹친다) */
+  points: readonly V3[];
+  at?: number;
+  /** 놓이는 시간 — 처음 점부터 자란다 */
+  dur?: number;
+  /** 두 가닥 사이 */
+  gauge?: number;
+  /** 벽에 물리는 받침대 */
+  brackets?: boolean;
+  /** 고리 — 끝이 처음으로 매끈하게 이어진다(처음 점을 끝에 다시 넣지 않는다) */
+  closed?: boolean;
+}
+
+/** 레일 — 강철 두 가닥이 처음 점부터 끝까지 놓여 가고, 받침대가 벽에 물린다. 구슬은 그 위를 구른다 */
+export function rail(stage: Stage3D, o: RailOpts): (t: number) => void {
+  const { ctx } = o;
+  const tr = track(o.points, o.closed);
+  const gauge = o.gauge ?? 0.26;
+  const m = steelMat(ctx);
+  const segs = Math.max(24, Math.ceil(tr.total * 10));
+  const tubes = [-1, 1].map((side) => {
+    // 두 가닥은 진행 방향과 위(y)에 모두 수직인 쪽으로 벌린다 — 벽을 따라 놓인 레일이면 앞뒤(z)
+    const off = tr.pts.map((p, i) => {
+      const a = tr.pts[Math.max(0, i - 1)];
+      const b = tr.pts[Math.min(tr.pts.length - 1, i + 1)];
+      const tan = b.clone().sub(a).normalize();
+      const side3 = new THREE.Vector3().crossVectors(tan, new THREE.Vector3(0, 1, 0));
+      if (side3.lengthSq() < 1e-6) side3.set(0, 0, 1);
+      return p.clone().addScaledVector(side3.normalize(), (side * gauge) / 2);
+    });
+    const geo = new THREE.TubeGeometry(new THREE.CatmullRomCurve3(off, o.closed), segs, 0.035, 6, o.closed);
+    const mesh = shade(new THREE.Mesh(geo, m));
+    stage.scene.add(mesh);
+    return mesh;
+  });
+  const brackets: { mesh: THREE.Mesh; k: number }[] = [];
+  if (o.brackets !== false) {
+    const bm = brassMat(ctx);
+    for (let d = 0.6; d < tr.total - 0.3; d += 1.5) {
+      const p = pointAt(tr, d);
+      if (p.z < 0.15) continue;
+      const g = new THREE.CylinderGeometry(0.035, 0.035, p.z, 6);
+      g.rotateX(Math.PI / 2);
+      const mesh = shade(new THREE.Mesh(g, bm));
+      mesh.position.set(p.x, p.y - 0.05, p.z / 2);
+      stage.scene.add(mesh);
+      brackets.push({ mesh, k: d / tr.total });
+    }
+  }
+  const at = o.at ?? -1;
+  const dur = o.dur ?? 0.4;
+  return (t) => {
+    const p = t < at ? 0 : ease.inOutCubic(clamp((t - at) / dur));
+    for (const mesh of tubes) {
+      const idx = mesh.geometry.index!.count;
+      mesh.visible = p > 0;
+      mesh.geometry.setDrawRange(0, Math.floor((p * idx) / 6) * 6);
+    }
+    for (const b of brackets) b.mesh.visible = p >= b.k;
+  };
+}
+
+export interface MarblesOpts {
+  ctx: SceneCtx;
+  /** 레일과 같은 꼭짓점 */
+  points: readonly V3[];
+  /** count 개를 every 초마다(또는 times 에) 처음 점에서 굴린다 */
+  at?: number;
+  count?: number;
+  every?: number;
+  times?: readonly number[];
+  /** 구슬 색 — style.colors 키(marble1–9)나 색. 배열이면 차례로 */
+  colors?: string | readonly string[];
+  /** 처음 빠르기 */
+  v0?: number;
+  /** 끝에 닿은 뒤 — hide 사라진다 · stay 끝에 선다 · loop 처음부터 다시 */
+  end?: "hide" | "stay" | "loop";
+  until?: number;
+  /** 구슬 반지름 */
+  radius?: number;
+  /** 레일과 같게 — 고리면 끝에서 처음으로 이어 돈다 */
+  closed?: boolean;
+}
+
+/**
+ * 구슬 = 요청 — 레일을 따라 구른다. 내리막에서 빨라지고 오르막·평지에서 느려진다(에너지 보존, 아주 서지는 않는다).
+ * 돌려준 함수의 arrivals 에 구슬마다 끝에 닿는 시각
+ */
+export function marbles(stage: Stage3D, o: MarblesOpts): ((t: number) => void) & { arrivals: number[]; ride: number } {
+  const { ctx } = o;
+  const tr = track(o.points, o.closed);
+  const y0 = tr.pts[0].y;
+  const v0 = o.v0 ?? 1.4;
+  // 길이마다 지나는 시각 — 에너지 보존 빠르기를 적분
+  const tAt = [0];
+  for (let i = 1; i < tr.pts.length; i++) {
+    const v = (y: number) => Math.max(1.1, Math.sqrt(v0 * v0 + 2 * G * (y0 - y)));
+    const vm = (v(tr.pts[i - 1].y) + v(tr.pts[i].y)) / 2;
+    tAt.push(tAt[i - 1] + (tr.s[i] - tr.s[i - 1]) / vm);
+  }
+  const ride = tAt[tAt.length - 1];
+  const lenAt = (tau: number): number => {
+    let lo = 0;
+    let hi = tAt.length - 1;
+    while (hi - lo > 1) {
+      const m = (lo + hi) >> 1;
+      if (tAt[m] <= tau) lo = m;
+      else hi = m;
+    }
+    const k = (tau - tAt[lo]) / (tAt[hi] - tAt[lo] || 1);
+    return tr.s[lo] + (tr.s[hi] - tr.s[lo]) * k;
+  };
+  const times = o.times ?? Array.from({ length: o.count ?? 1 }, (_, k) => (o.at ?? 0) + k * (o.every ?? 0.5));
+  const cols = typeof o.colors === "string" || !o.colors ? [o.colors ?? "marble1"] : o.colors;
+  const rad = o.radius ?? R;
+  const lift = LIFT + (rad - R);
+  const mesh = swarm(ctx, rad, times.length, cols);
+  stage.scene.add(mesh);
+  const m4 = new THREE.Matrix4();
+  const p = new THREE.Vector3();
+  const until = o.until ?? Infinity;
+  const end = o.end ?? "hide";
+  const paint = (t: number) => {
+    times.forEach((T, k) => {
+      let tau = t - T;
+      if (tau < 0 || t >= until || (end === "hide" && tau > ride)) return mesh.setMatrixAt(k, HIDE);
+      if (end === "loop") tau %= ride;
+      pointAt(tr, lenAt(Math.min(tau, ride)), p);
+      mesh.setMatrixAt(k, m4.makeTranslation(p.x, p.y + lift, p.z));
+    });
+    mesh.instanceMatrix.needsUpdate = true;
+  };
+  return Object.assign(paint, { arrivals: times.map((T) => T + ride), ride });
+}
+
+// ── 장치 ─────────────────────────────────────────────────────────────
+
+/**
+ * 깔때기 = 한 주소 — 여러 레일에서 온 구슬이 테두리로 들어와 소용돌이를 돌며(안쪽일수록 빨리) 가운데 구멍으로 빠진다.
+ * feeds 마다 [들어오는 시각, 색, 들어오는 각(라디안)]. 돌려준 함수의 exits 에 구멍으로 빠지는 시각
+ */
+export function funnel(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; radius?: number; at?: number; feeds: readonly { time: number; color: string; angle?: number }[]; spin?: number }): ((t: number) => void) & { exits: number[] } {
+  const { ctx } = o;
+  const Rr = o.radius ?? 2.4;
+  const hole = 0.3;
+  const H = 1.6;
+  const prof = (r: number) => H * (1 - (hole / r) ** 0.9);
+  const profile = Array.from({ length: 24 }, (_, i) => {
+    const r = hole + ((Rr - hole) * i) / 23;
+    return new THREE.Vector2(r, prof(r));
+  });
+  const group = new THREE.Group();
+  const bowl = shade(new THREE.Mesh(new THREE.LatheGeometry(profile, 40), new THREE.MeshStandardMaterial({ color: 0x17120e, metalness: 0.35, roughness: 0.16, side: THREE.DoubleSide })));
+  const rim = shade(new THREE.Mesh(new THREE.TorusGeometry(Rr, 0.06, 6, 48), brassMat(ctx)));
+  rim.rotation.x = Math.PI / 2;
+  rim.position.y = prof(Rr);
+  group.add(bowl, rim);
+  group.position.set(...o.pos);
+  stage.scene.add(group);
+  const spin = o.spin ?? 1.5;
+  // 한 바퀴 길 — 반지름이 줄수록 각속도 ∝ r^-1.5 (각운동량), 미리 적분해 둔다
+  const N = 90;
+  const path = [{ r: Rr - 0.25, a: 0 }];
+  for (let i = 1; i <= N; i++) {
+    const u = i / N;
+    const r = hole + (Rr - 0.25 - hole) * (1 - u) ** 1.3;
+    path.push({ r, a: path[i - 1].a + (spin / N) * 2.2 * r ** -1.5 });
+  }
+  const fall = 0.28;
+  const mesh = swarm(ctx, R, o.feeds.length, o.feeds.map((f) => f.color));
+  stage.scene.add(mesh);
+  const m4 = new THREE.Matrix4();
+  const at = o.at ?? -1;
+  const paint = (t: number) => {
+    group.scale.setScalar(Math.max(0.001, pop(t, at, 0.36)));
+    o.feeds.forEach((f, k) => {
+      const tau = t - f.time;
+      if (tau < 0 || tau > spin + fall) return mesh.setMatrixAt(k, HIDE);
+      let x: number;
+      let y: number;
+      let z: number;
+      if (tau <= spin) {
+        const i = Math.min(N - 1, Math.floor((tau / spin) * N));
+        const w = (tau / spin) * N - i;
+        const r = path[i].r + (path[i + 1].r - path[i].r) * w;
+        const a = (f.angle ?? 0) - (path[i].a + (path[i + 1].a - path[i].a) * w);
+        x = Math.cos(a) * r;
+        z = Math.sin(a) * r;
+        y = prof(Math.max(hole, r)) + R;
+      } else {
+        const d = tau - spin;
+        x = 0;
+        z = 0;
+        y = R - 0.5 * G * d * d - 1.2 * d;
+      }
+      mesh.setMatrixAt(k, m4.makeTranslation(o.pos[0] + x, o.pos[1] + y, o.pos[2] + z));
+    });
+    mesh.instanceMatrix.needsUpdate = true;
+  };
+  return Object.assign(paint, { exits: o.feeds.map((f) => f.time + spin + fall * 0.6) });
+}
+
+/**
+ * 갈림판 = 라우팅 — 갈림길 위 놋쇠 판이 flips 시각마다 넘어가 다른 레일을 겨눈다(겨눈 쪽으로 구슬이 간다). 폴백은 판이 다른 쪽으로 넘어가는 것.
+ * aims 를 주면 n 번째로 넘어간 뒤 aims[n] 도(갈래가 여럿일 때), 없으면 ±angle 을 오간다
+ */
+export function flipper(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; at?: number; flips: readonly number[]; angle?: number; aims?: readonly number[]; length?: number }): (t: number) => void {
+  const { ctx } = o;
+  const len = o.length ?? 1.2;
+  const group = new THREE.Group();
+  const paddle = new THREE.BoxGeometry(len, 0.08, 0.5);
+  paddle.translate(len / 2, 0, 0);
+  const arm = shade(new THREE.Mesh(paddle, brassMat(ctx)));
+  const pin = shade(new THREE.Mesh(new THREE.CylinderGeometry(0.09, 0.09, 0.62, 12).rotateX(Math.PI / 2), steelMat(ctx)));
+  group.add(arm, pin);
+  group.position.set(...o.pos);
+  stage.scene.add(group);
+  const A = ((o.angle ?? 28) * Math.PI) / 180;
+  const flips = [...o.flips].sort((a, b) => a - b);
+  const at = o.at ?? -1;
+  return (t) => {
+    group.scale.setScalar(Math.max(0.001, pop(t, at)));
+    const n = flips.filter((f) => f <= t).length;
+    const aim = (i: number) => (o.aims ? (o.aims[Math.max(0, i) % o.aims.length] * Math.PI) / 180 : i % 2 ? A : -A);
+    const last = n ? flips[n - 1] : -1e9;
+    const k = ease.outBack(clamp((t - last) / 0.14));
+    arm.rotation.z = n ? aim(n - 1) + (aim(n) - aim(n - 1)) * k : aim(0);
+  };
+}
+
+export interface TubeItem {
+  x: number;
+  count: number;
+  color: string;
+  /** 첫 구슬을 놓는 시각과 간격 */
+  at: number;
+  every?: number;
+}
+
+/**
+ * 투명 관 = 쌓인 수 — 관 위에서 구슬이 하나씩 떨어져 쌓인다. 높이가 곧 수(관끼리 같은 높이라 막대그래프처럼 읽힌다).
+ * 돌려준 함수의 landed(i, t) 는 i 번 관에 t 까지 앉은 구슬 수
+ */
+export function tubes(stage: Stage3D, o: { ctx: SceneCtx; items: readonly TubeItem[]; base: number; z?: number; height?: number }): ((t: number) => void) & { landed(i: number, t: number): number } {
+  const { ctx } = o;
+  const z = o.z ?? 0.6;
+  const r = 0.12;
+  const d = r * 2;
+  const H = o.height ?? Math.max(...o.items.map((it) => it.count)) * d + 0.3;
+  const glass = new THREE.MeshStandardMaterial({ color: 0xffffff, transparent: true, opacity: 0.14, roughness: 0.05, metalness: 0, depthWrite: false, side: THREE.DoubleSide });
+  const bm = brassMat(ctx);
+  for (const it of o.items) {
+    const tube = new THREE.Mesh(new THREE.CylinderGeometry(r * 1.35, r * 1.35, H, 16, 1, true), glass);
+    tube.position.set(it.x, o.base + H / 2, z);
+    const foot = shade(new THREE.Mesh(new THREE.CylinderGeometry(r * 1.7, r * 1.7, 0.1, 16), bm));
+    foot.position.set(it.x, o.base - 0.05, z);
+    stage.scene.add(tube, foot);
+  }
+  // 관 안 급수구에서 쌓일 자리 바로 위로 떨어진다 — 관 꼭대기에서 떨어뜨리면 한 마디 안에 다 못 앉는다
+  const g = G * 2.5;
+  const all: { i: number; x: number; T: number; y1: number; y0: number; fall: number }[] = [];
+  o.items.forEach((it, i) => {
+    for (let k = 0; k < it.count; k++) {
+      const y1 = o.base + r + k * d;
+      const y0 = Math.min(o.base + H, y1 + 3);
+      all.push({ i, x: it.x, T: it.at + k * (it.every ?? 0.03), y1, y0, fall: Math.sqrt((2 * (y0 - y1)) / g) });
+    }
+  });
+  const mesh = swarm(ctx, r, all.length, all.map((m) => o.items[m.i].color));
+  stage.scene.add(mesh);
+  const m4 = new THREE.Matrix4();
+  const paint = (t: number) => {
+    all.forEach((m, k) => {
+      const tau = t - m.T;
+      if (tau < 0) return mesh.setMatrixAt(k, HIDE);
+      const y = tau >= m.fall ? m.y1 : m.y0 - 0.5 * g * tau * tau;
+      mesh.setMatrixAt(k, m4.makeTranslation(m.x, y, z));
+    });
+    mesh.instanceMatrix.needsUpdate = true;
+  };
+  return Object.assign(paint, { landed: (i: number, t: number) => all.filter((m) => m.i === i && t - m.T >= m.fall).length });
+}
+
+// ── 명판 ─────────────────────────────────────────────────────────────
+
+type Text = string | ((t: number) => string);
+
+/** 놋쇠 판 한 장을 캔버스에 — 둥근 판·짙은 테두리·나사 넷, 글은 새긴 듯 짙게(아래 1px 빛) */
+function brassPlate(ctx: SceneCtx, sample: string, font: "sans" | "display" | "mono", px = 140) {
+  const fam = ctx.style.fonts[font];
+  const f = `${font === "mono" ? 500 : 700} ${px}px ${fam}`;
+  const probe = document.createElement("canvas").getContext("2d")!;
+  probe.font = f;
+  const cw = Math.ceil(probe.measureText(sample).width + px * 1.3);
+  const ch = Math.ceil(px * 1.6);
+  const c = document.createElement("canvas");
+  c.width = cw;
+  c.height = ch;
+  const tex = new THREE.CanvasTexture(c);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  const draw = (s: string) => {
+    const g = c.getContext("2d")!;
+    g.clearRect(0, 0, cw, ch);
+    g.fillStyle = ctx.style.colors.brass;
+    g.beginPath();
+    g.roundRect(0, 0, cw, ch, px * 0.16);
+    g.fill();
+    g.lineWidth = px * 0.06;
+    g.strokeStyle = ctx.style.colors.engrave;
+    g.globalAlpha = 0.55;
+    g.beginPath();
+    g.roundRect(px * 0.12, px * 0.12, cw - px * 0.24, ch - px * 0.24, px * 0.1);
+    g.stroke();
+    g.globalAlpha = 1;
+    g.fillStyle = ctx.style.colors.engrave;
+    for (const [x, y] of [[px * 0.3, px * 0.3], [cw - px * 0.3, px * 0.3], [px * 0.3, ch - px * 0.3], [cw - px * 0.3, ch - px * 0.3]]) {
+      g.beginPath();
+      g.arc(x, y, px * 0.06, 0, Math.PI * 2);
+      g.fill();
+    }
+    g.font = f;
+    g.textAlign = "center";
+    g.textBaseline = "middle";
+    g.fillStyle = "rgba(255,240,200,0.55)";
+    g.fillText(s, cw / 2, ch / 2 + px * 0.06 + 2);
+    g.fillStyle = ctx.style.colors.engrave;
+    g.fillText(s, cw / 2, ch / 2 + px * 0.06);
+    tex.needsUpdate = true;
+  };
+  return { tex, draw, aspect: cw / ch };
+}
+
+/**
+ * 명판 — 벽에 놋쇠 판이 톡 붙고 글이 새겨져 있다(조형 옆 명판). text 가 함수면 그 t 의 글로 다시 새긴다.
+ * 화면 글은 모두 명판에
+ */
+export function plaque(stage: Stage3D, o: { ctx: SceneCtx; text: Text; pos: V3; height?: number; at?: number; until?: number; font?: "sans" | "display" | "mono"; anchor?: "center" | "left" | "right" }): (t: number) => void {
+  const { ctx } = o;
+  const h = o.height ?? 0.7;
+  const sample = typeof o.text === "function" ? [0, 1e9].map((x) => (o.text as (t: number) => string)(x)).sort((a, b) => b.length - a.length)[0] : o.text;
+  const plate = brassPlate(ctx, sample, o.font ?? "display");
+  const w = h * plate.aspect;
+  const geo = new THREE.PlaneGeometry(w, h);
+  if (o.anchor === "left") geo.translate(w / 2, 0, 0);
+  if (o.anchor === "right") geo.translate(-w / 2, 0, 0);
+  const mesh = new THREE.Mesh(geo, new THREE.MeshStandardMaterial({ map: plate.tex, metalness: 0.35, roughness: 0.45, transparent: true }));
+  mesh.castShadow = true;
+  mesh.position.set(...o.pos);
+  stage.scene.add(mesh);
+  if (typeof o.text === "string") plate.draw(o.text);
+  const at = o.at ?? -1;
+  const until = o.until ?? Infinity;
+  return (t) => {
+    const k = pop(t, at);
+    mesh.visible = k > 0 && t < until;
+    mesh.scale.setScalar(Math.max(0.001, k));
+    if (typeof o.text === "function") plate.draw(o.text(t));
+  };
+}
+
+/**
+ * 관문 = 비용 — 레일을 앞뒤로 걸친 놋쇠 문(기둥 둘·들보)이 서고, 들보 앞판에 지나는 값이 새겨져 있다. 구슬은 기둥 사이로 지난다.
+ * 값이 바뀌는 순간(changes) 문이 한 번 내려앉았다 선다. price 가 함수면 그 t 의 값
+ */
+export function tollGate(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; price: Text; at?: number; changes?: readonly number[]; height?: number }): (t: number) => void {
+  const { ctx } = o;
+  const h = o.height ?? 1.2;
+  const group = new THREE.Group();
+  const bm = brassMat(ctx);
+  for (const z of [-0.42, 0.42]) {
+    const post = shade(new THREE.Mesh(new THREE.BoxGeometry(0.12, h, 0.12), bm));
+    post.position.set(0, h / 2 - 0.2, z);
+    group.add(post);
+  }
+  const beam = shade(new THREE.Mesh(new THREE.BoxGeometry(0.2, 0.16, 1.0), bm));
+  beam.position.y = h - 0.2;
+  group.add(beam);
+  const sample = typeof o.price === "function" ? [0, 1e9].map((x) => (o.price as (t: number) => string)(x)).sort((a, b) => b.length - a.length)[0] : o.price;
+  const plate = brassPlate(ctx, sample, "mono");
+  const ph = 0.6;
+  const sign = new THREE.Mesh(new THREE.PlaneGeometry(ph * plate.aspect, ph), new THREE.MeshStandardMaterial({ map: plate.tex, metalness: 0.35, roughness: 0.45, transparent: true }));
+  sign.castShadow = true;
+  sign.position.set(0, h + 0.2, 0.52);
+  group.add(sign);
+  group.position.set(...o.pos);
+  stage.scene.add(group);
+  if (typeof o.price === "string") plate.draw(o.price);
+  const at = o.at ?? -1;
+  const changes = o.changes ?? [];
+  return (t) => {
+    group.scale.setScalar(Math.max(0.001, pop(t, at)));
+    if (typeof o.price === "function") plate.draw(o.price(t));
+    const last = changes.filter((c) => c <= t).pop();
+    const k = last === undefined ? 1 : clamp((t - last) / 0.3);
+    group.position.y = o.pos[1] - (last === undefined ? 0 : Math.sin(k * Math.PI) * 0.18);
+  };
+}
+
+/**
+ * 하루 = 시계 고리 — 벽에 둥근 고리 레일과 24 시 놋쇠 못(00 이 위, 시계 방향). windowAt 에 한 시간대(00–10) 고리가 다른 운임 색으로 켜지고,
+ * 구슬(요청)이 고리를 쉬지 않고 돈다
+ */
+export function clockWheel(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; radius?: number; at?: number; window?: [number, number]; windowAt?: number; turn?: number; count?: number; color?: string }): (t: number) => void {
+  const { ctx } = o;
+  const Rr = o.radius ?? 2.8;
+  const group = new THREE.Group();
+  const ring = shade(new THREE.Mesh(new THREE.TorusGeometry(Rr, 0.05, 6, 96), steelMat(ctx)));
+  const ring2 = shade(new THREE.Mesh(new THREE.TorusGeometry(Rr, 0.05, 6, 96), steelMat(ctx)));
+  ring.position.z = 0.13;
+  ring2.position.z = -0.13;
+  group.add(ring, ring2);
+  const bm = brassMat(ctx);
+  // 시각 h 의 자리 — 00 이 위, 시계 방향
+  const ang = (h: number) => Math.PI / 2 - (h / 24) * Math.PI * 2;
+  for (let h = 0; h < 24; h++) {
+    const big = h % 6 === 0;
+    const peg = shade(new THREE.Mesh(new THREE.CylinderGeometry(big ? 0.09 : 0.05, big ? 0.09 : 0.05, 0.5, 8).rotateX(Math.PI / 2), bm));
+    const rr = Rr + (big ? 0.42 : 0.3);
+    peg.position.set(Math.cos(ang(h)) * rr, Math.sin(ang(h)) * rr, -0.1);
+    group.add(peg);
+  }
+  for (const h of [0, 6, 12, 18]) {
+    const label = textPlane({ text: String(h).padStart(2, "0"), family: ctx.style.fonts.mono, weight: 500, color: ctx.style.colors.ink, height: 0.5 });
+    label.position.set(Math.cos(ang(h)) * (Rr + 1.0), Math.sin(ang(h)) * (Rr + 1.0), 0.2);
+    group.add(label);
+  }
+  const [h0, h1] = o.window ?? [0, 10];
+  const arc = new THREE.Mesh(
+    new THREE.TorusGeometry(Rr, 0.11, 8, 64, ((h1 - h0) / 24) * Math.PI * 2),
+    new THREE.MeshStandardMaterial({ color: col(ctx, o.color ?? "success"), emissive: col(ctx, o.color ?? "success"), emissiveIntensity: 0.55, roughness: 0.4 }),
+  );
+  arc.rotation.z = ang(h1);
+  arc.scale.set(1, 1, 3.2);
+  group.add(arc);
+  group.position.set(...o.pos);
+  stage.scene.add(group);
+  const n = o.count ?? 4;
+  const mesh = swarm(ctx, R, n, Array.from({ length: 9 }, (_, k) => `marble${k + 1}`));
+  stage.scene.add(mesh);
+  const m4 = new THREE.Matrix4();
+  const at = o.at ?? -1;
+  const turn = o.turn ?? 4;
+  const wAt = o.windowAt ?? at;
+  return (t) => {
+    group.scale.setScalar(Math.max(0.001, pop(t, at, 0.4)));
+    arc.visible = t >= wAt;
+    arc.scale.setScalar(t >= wAt ? 1 + 0.25 * (1 - ease.outCubic(clamp((t - wAt) / 0.3))) : 1);
+    arc.scale.z = 3.2;
+    for (let k = 0; k < n; k++) {
+      if (t < at + 0.3) {
+        mesh.setMatrixAt(k, HIDE);
+        continue;
+      }
+      const h = ((((t - at) / turn) * 24 + (k * 24) / n) % 24 + 24) % 24;
+      const a = ang(h);
+      mesh.setMatrixAt(k, m4.makeTranslation(o.pos[0] + Math.cos(a) * (Rr - 0.02), o.pos[1] + Math.sin(a) * (Rr - 0.02), o.pos[2] + 0.02));
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+  };
+}
+
+/**
+ * 드롭 = 방출 문 — 넓은 경사판 꼭대기에 모아 둔 구슬 더미를 문이 막고 있다가, 드롭 순간 문이 젖혀지고 구슬이 한꺼번에 쏟아져 내려
+ * 아래 받침에 깔린다. 섬광·흔들림(dropBurst)은 카메라에. fill 을 주면 그 사이 구슬이 위에서 하나씩 떨어져 더미가 차오른다(드롭 앞 모아 올리기)
+ */
+export function releaseGate(stage: Stage3D, o: { ctx: SceneCtx; drop?: number; top: V3; bottom: V3; count: number; colors?: readonly string[]; width?: number; fill?: [number, number] }): (t: number) => void {
+  const { ctx } = o;
+  const D = ctx.beats.drop(o.drop ?? 0);
+  const top = new THREE.Vector3(...o.top);
+  const bottom = new THREE.Vector3(...o.bottom);
+  const dir = bottom.clone().sub(top);
+  const L = dir.length();
+  dir.normalize();
+  const width = o.width ?? 2.2;
+  const board = shade(new THREE.Mesh(new THREE.BoxGeometry(L + 0.6, 0.08, width), new THREE.MeshStandardMaterial({ color: col(ctx, "raised"), roughness: 0.8 })));
+  board.position.copy(top).add(bottom).multiplyScalar(0.5).add(new THREE.Vector3(0, -0.15, 0));
+  board.rotation.z = Math.atan2(dir.y, dir.x);
+  const gate = shade(new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.9, width), brassMat(ctx)));
+  // 문은 위 경첩에 매달려 있다가 내리막 쪽으로 젖혀진다
+  const pivot = new THREE.Group();
+  pivot.position.copy(top).addScaledVector(dir, 0.35).add(new THREE.Vector3(0, 0.9, 0));
+  gate.position.y = -0.45;
+  pivot.add(gate);
+  stage.scene.add(board, pivot);
+  const cols = Math.ceil(Math.sqrt(o.count * 1.6));
+  const rows = Math.ceil(o.count / cols);
+  const lane = (width - 0.3) / rows;
+  // 더미 자리(문 뒤 위쪽으로 쌓임) → 받침 자리(경사 끝에서 펼쳐짐)
+  const items = Array.from({ length: o.count }, (_, i) => {
+    const c = i % cols;
+    const r = Math.floor(i / cols);
+    const z = -width / 2 + 0.15 + (r + 0.5) * lane;
+    const pile = top.clone().addScaledVector(dir, -c * 0.17).add(new THREE.Vector3(0, (c % 3) * 0.12, z));
+    const land = bottom.clone().add(new THREE.Vector3(0.35 + (c / cols) * 2.6, 0, z));
+    return { pile, land, delay: c * 0.012 + r * 0.008 };
+  });
+  const mesh = swarm(ctx, 0.13, o.count, o.colors ?? ["marble1"]);
+  stage.scene.add(mesh);
+  const flash = document.createElement("div");
+  flash.style.cssText = `position:absolute;inset:0;background:${ctx.style.colors.ink};opacity:0;pointer-events:none;`;
+  stage.el.append(flash);
+  // 문이 열리면 1 초 안에 다 쏟아지게 — 실제 경사보다 가파르게 민다(드롭은 한 박의 사건이다)
+  const a = 2.6 * G * Math.max(0.2, -dir.y);
+  const m4 = new THREE.Matrix4();
+  const p = new THREE.Vector3();
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "releaseGate" });
+    flash.style.opacity = (s.flash * 0.6).toFixed(3);
+    stage.camera.position.x += (s.shake.x ?? 0) * 0.02;
+    stage.camera.position.y += (s.shake.y ?? 0) * 0.02;
+    pivot.rotation.z = t < D ? 0 : 1.4 * ease.outBack(clamp((t - D) / 0.22));
+    items.forEach((it, i) => {
+      const tau = t - D - it.delay;
+      if (tau <= 0) {
+        if (!o.fill) return mesh.setMatrixAt(i, m4.makeTranslation(it.pile.x, it.pile.y, it.pile.z));
+        const app = o.fill[0] + (i / o.count) * (o.fill[1] - o.fill[0]);
+        if (t < app) return mesh.setMatrixAt(i, HIDE);
+        const k = ease.inCubic(clamp((t - app) / 0.18));
+        return mesh.setMatrixAt(i, m4.makeTranslation(it.pile.x, it.pile.y + 2.2 * (1 - k), it.pile.z));
+      }
+      const run = 6 * tau + 0.5 * a * tau * tau;
+      const along = run + it.pile.clone().sub(top).dot(dir);
+      if (along < L) {
+        p.copy(top).addScaledVector(dir, along);
+        p.z = it.pile.z;
+        p.y += Math.max(0, it.pile.y - top.y) * (1 - clamp(run / 0.6));
+      } else {
+        const left = L - it.pile.clone().sub(top).dot(dir);
+        const tEnd = (-6 + Math.sqrt(36 + 2 * a * left)) / a;
+        const k = clamp((tau - tEnd) / 0.35);
+        p.copy(bottom).lerp(it.land, ease.outCubic(k));
+        p.y += Math.sin(k * Math.PI) * 0.35 * (1 - k);
+      }
+      mesh.setMatrixAt(i, m4.makeTranslation(p.x, p.y, p.z));
+    });
+    mesh.instanceMatrix.needsUpdate = true;
+  };
+}