lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/gl/Gearbox.ts

@@ -1,212 +0,0 @@
-// The gearbox of a `Vehicle`, as an aspect on the same node. It is deliberately NOT in the engine:
-// picking a gear is policy, not physics — two RPM thresholds and a latency timer — and every game
-// wants its own. The engine keeps only the physical half (the clutch's stiffness and the coupled
-// engine/wheel solve), and is told one ratio and one clutch scalar per frame.
-//
-//   car.aspect(Gearbox, { ratios: [2.66, 1.78, 1.3, 1.0, 0.74], reverse: -2.9 })
-//
-// A `Vehicle` with no `Gearbox` attaches this one with its defaults, so a car that never mentions
-// gears still drives.
-//
-// Custom behaviour is a subclass overriding ONE method:
-//
-//   class SportBox extends Gearbox {
-//     select(v: Vehicle): number { return v.rpm > 6200 ? this.gear + 1 : this.gear }
-//   }
-//
-// The clutch is two things multiplied. The SHIFT envelope (`shiftTime`/`clutchTime`) stays with the
-// base class on purpose: a forgotten ramp breaks a car silently — no drive at all, or a slammed
-// clutch. The TAKE-UP (`takeUp`) is the left-foot half, and is overridable for a car that launches
-// unusually — a torque converter, a rally launch control.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import type { Node } from "./Node"
-import type { Vehicle } from "./Vehicle"
-
-// How far above idle counts as "revs to spare". A simulated engine cannot fall below its idle — the
-// physics clamps it — so being AT idle is the observable form of "the wheels are dragging me under".
-// This is the tolerance for reading that clamp, not a tuning knob.
-const IDLE_MARGIN = 1.05
-
-// The car this gearbox belongs to. Read through the aspect accessor rather than node.get(Vehicle),
-// so this file needs Vehicle only as a TYPE and the two do not import each other at runtime.
-const carOf = (n: Node): Vehicle | null => (n as unknown as { vehicle?: Vehicle }).vehicle ?? null
-
-export class Gearbox extends Aspect<"gearbox", Node> {
-  static readonly aspect = "gearbox"
-
-  /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
-  ratios: number[] = [ 2.66, 1.78, 1.3, 1.0, 0.74 ]
-  /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
-  reverse = -2.9
-  /** Shift up when the engine passes this fraction of its redline. */
-  shiftUp = 0.67
-  /** Shift down when it falls below this fraction. */
-  shiftDown = 0.33
-  /** How long a shift takes, in seconds — the clutch is out for this long. */
-  shiftTime = 0.2
-  /** How long the clutch takes to re-engage afterwards. */
-  clutchTime = 0.3
-  /** How long to wait after a shift before another is allowed — without it a car sitting on a
-   *  threshold hunts between two gears. */
-  latency = 0.5
-
-  /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
-   *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
-   *  still pulls away gently at the same bite point. */
-  bite = 0.4
-
-  static fields: FieldMeta<Gearbox> = {
-    reverse: { max: -0.1, step: 0.1 },
-    shiftUp: { min: 0.1, max: 1, step: 0.01 },
-    shiftDown: { min: 0, max: 0.9, step: 0.01 },
-    shiftTime: { min: 0, max: 3, step: 0.05 },
-    clutchTime: { min: 0, max: 3, step: 0.05 },
-    latency: { min: 0, max: 3, step: 0.05 },
-    bite: { min: 0, max: 1, step: 0.05 },
-    ratios: { hidden: true },
-  }
-
-  /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
-  gear = 0
-  /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
-  get shifting(): boolean { return this._shiftLeft > 0 }
-
-  private _shiftLeft = 0      // seconds of clutch-out left
-  private _engageLeft = 0     // seconds of clutch re-engagement left
-  private _waitLeft = 0       // anti-hunting
-  private _take = 0           // how far the CAR's own state wants the clutch in, latched per frame
-
-  /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
-  updateBefore(dt: number): void {
-    const v = carOf(this.node)
-    if (!v || !v.id) return
-
-    this._waitLeft = Math.max(0, this._waitLeft - dt)
-
-    if (this._shiftLeft > 0) {
-      // Mid-shift: clutch fully out, and the moment it ends the re-engagement ramp starts.
-      this._shiftLeft = Math.max(0, this._shiftLeft - dt)
-      if (this._shiftLeft === 0) this._engageLeft = this.clutchTime
-    } else {
-      const want = this.select(v)
-      if (want !== this.gear) this.shift(want)
-      else this._engageLeft = Math.max(0, this._engageLeft - dt)
-    }
-
-    // The pedal only moves while no shift is in flight. During one the revs say nothing about
-    // whether the wheels can sustain them: an engine still spinning down from the last gear reads as
-    // "revs to spare" and would drop the clutch straight back in — enough to shove a stopped car
-    // several km/h with no throttle at all. Freezing it is what a driver does anyway; the foot is
-    // already down, and the envelope owns the clutch until the gear is in.
-    if (this._shiftLeft === 0 && this._engageLeft === 0) {
-      this._take = Math.max(0, Math.min(1, this.takeUp(v, dt)))
-    }
-
-    v._setTransmission(this.ratio, this.clutch)
-  }
-
-  /**
-   * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
-   *
-   * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
-   * wheels are about to drag the engine under, and that is when you push the clutch in.** That
-   * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
-   * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
-   * without being told the gear.
-   *
-   * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
-   * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
-   * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
-   *
-   * Three things fall out of it for free:
-   *
-   * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
-   *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
-   *   idle, so the pedal goes down and the brakes have nothing to fight.
-   * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
-   *   is exactly why a fixed road-speed threshold got reverse wrong.
-   * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
-   *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
-   *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
-   *   stall the car under load. Throttle only holds the floor at `bite`.
-   *
-   * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
-   * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
-   * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
-   * bring the creep straight back.
-   */
-  protected takeUp(v: Vehicle, dt: number): number {
-    if (this.gear === 0) return 0
-    const idle = v.engine.idleRpm ?? 1000
-    const step = dt / Math.max(this.clutchTime, dt)
-    const asked = v.throttle !== 0
-    let take = this._take
-    if (v.rpm <= idle * IDLE_MARGIN) take -= step   // being dragged under: pedal goes down
-    else if (asked) take += step                    // revs to spare AND somewhere to go: let it up
-    // Asking for drive also holds the pedal at the bite point however far down the rule wants it;
-    // that is what makes a launch — and a hill start — slip instead of collapsing to nothing.
-    return asked ? Math.max(take, this.bite) : take
-  }
-
-  /**
-   * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
-   * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
-   * and refuse to shift again for `latency` seconds. Override this and nothing else.
-   */
-  select(v: Vehicle): number {
-    const throttle = v.throttle
-    // Neutral, or asked to go the other way: engage once the car has (nearly) stopped.
-    if (this.gear === 0 || throttle * this.gear < 0) {
-      if (Math.abs(v.speed) > 1 && this.gear !== 0) return this.gear
-      return throttle > 0 ? 1 : throttle < 0 ? -1 : this.gear
-    }
-    if (this.gear < 0 || this._waitLeft > 0 || this.shifting) return this.gear
-    const rpm = v.rpm
-    const max = v.engine.maxRpm ?? 6000
-    // Upshifting needs COUPLED revs. With the clutch out the engine is free, so a blip at a
-    // standstill reads as 6000 rpm and the box would climb to top gear without the car moving —
-    // then launch in it. Downshifting stays open either way: it can only take you to a lower gear,
-    // which is where a car with dying revs belongs.
-    if (rpm > max * this.shiftUp && this.clutch >= 1 && this.gear < this.ratios.length) return this.gear + 1
-    if (rpm < max * this.shiftDown && this.gear > 1) return this.gear - 1
-    return this.gear
-  }
-
-  /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
-   *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
-  shift(gear: number): void {
-    const clamped = Math.max(-1, Math.min(this.ratios.length, Math.round(gear)))
-    if (clamped === this.gear) return
-    // The envelope is for swapping one ENGAGED gear for another. If nothing is coupled there is
-    // nothing to disengage, so it is skipped: neutral at either end, and equally a car sitting still
-    // with the pedal already down — picking reverse there should pull away the moment it is asked
-    // to, not sit out a shift it never had to make.
-    const swapping = this.gear !== 0 && clamped !== 0 && this._take > 0
-    this.gear = clamped
-    this._shiftLeft = swapping ? this.shiftTime : 0
-    this._engageLeft = swapping ? this.clutchTime : 0
-    this._waitLeft = this.latency + this._shiftLeft
-  }
-
-  /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
-  get ratio(): number {
-    if (this.gear === 0) return 0
-    if (this.gear < 0) return this.reverse
-    return this.ratios[this.gear - 1] ?? 1
-  }
-
-  /**
-   * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
-   * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
-   * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
-   * dragged to idle is out whatever gear it just picked.
-   */
-  get clutch(): number {
-    if (this._shiftLeft > 0) return 0
-    const envelope =
-      this._engageLeft > 0 && this.clutchTime > 0 ? 1 - this._engageLeft / this.clutchTime : 1
-    return envelope * this._take
-  }
-}

package/runtime/sdk/gl/Geometry.ts

@@ -1,279 +0,0 @@
-// Mesh geometry: vertex / normal / index / uv buffers, plus the primitive builders. `Geometry.box()`
-// etc. return a Geometry you can hand to Mesh.from(); Mesh.box() is sugar over them. Ported from
-// worker/src/primitives/*.
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-
-export type MeshKind = "triangles" | "vertices" | "edges"
-
-// local tuple helpers — geometry building works on raw Float32Array buffers, so it stays out of the
-// Vec3 wrapper (no per-vertex allocation).
-type Tup3 = [number, number, number]
-const cross = (a: Tup3, b: Tup3): Tup3 => [ a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0] ]
-const normalize = (a: Tup3): Tup3 => {
-  const l = Math.hypot(a[0], a[1], a[2])
-  return l === 0 ? [ 0, 0, 0 ] : [ a[0] / l, a[1] / l, a[2] / l ]
-}
-
-export class Geometry {
-  vertices: Float32Array
-  normals: Float32Array
-  indices: Uint16Array
-  uv: Float32Array
-  /** Lightmap UV set (2 floats per vertex, non-overlapping, inside the unit square) — the
-   *  `Lightmap` atlas samples a Mesh through it. The box and cylinder builders fill it (their `uv`
-   *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
-   *  `uv`, which is right for a plane. */
-  uv1?: Float32Array
-  /** @internal native mesh-type enum (0 triangles / 1 edges / 2 vertices). */
-  _meshKind = 0
-
-  constructor(vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array) {
-    this.vertices = vertices
-    this.normals = normals
-    this.indices = indices
-    this.uv = uv
-  }
-
-  translate(x: number, y: number, z: number): this {
-    for (let i = 0; i < this.vertices.length; i += 3) {
-      this.vertices[i] += x; this.vertices[i + 1] += y; this.vertices[i + 2] += z
-    }
-    return this
-  }
-  scale(x: number, y: number, z: number): this {
-    for (let i = 0; i < this.vertices.length; i += 3) {
-      this.vertices[i] *= x; this.vertices[i + 1] *= y; this.vertices[i + 2] *= z
-    }
-    return this
-  }
-  scaleUV(x: number, y: number): this {
-    for (let i = 0; i < this.uv.length; i += 2) { this.uv[i] *= x; this.uv[i + 1] *= y }
-    return this
-  }
-  set kind(kind: MeshKind) {
-    this._meshKind = kind === "edges" ? 1 : kind === "vertices" ? 2 : 0
-  }
-
-  /** A box; `size` (default 1) scales the vertices AND lays the lightmap chart out in proportion to
-   *  the faces' areas (a floor's top face gets the texels, not its 1 m side strips). */
-  static box(size: Vec3Like | number = 1): Geometry { return createCube(size) }
-  static sphere(options?: SphereOptions): Geometry { return createSphere(options) }
-  static cylinder(options?: CylinderOptions): Geometry { return createCylinder(options) }
-  static plane(options?: PlaneOptions): Geometry { return createPlane(options) }
-}
-
-// Gutter between lightmap charts (fraction of the chart square): the bake dilates each rect by a
-// few texels and the shader samples bilinearly, so neighbouring faces must not touch in uv1.
-const LM_GUTTER = 0.03
-
-type Rect = { x: number, y: number, w: number, h: number }
-
-/** Shelf-pack rectangles (metres) into the unit square at the largest uniform scale — every face
- *  gets texels in proportion to its area, so a 64×1×64 floor's top face isn't squeezed into the
- *  same cell as its 1 m side strips. Returns rects in input order. */
-const packCharts = (dims: [number, number][]): Rect[] => {
-  const order = dims.map((_, i) => i).sort((a, b) => dims[b][1] - dims[a][1])
-  const attempt = (scale: number): Rect[] | null => {
-    const out: Rect[] = new Array(dims.length)
-    let x = 0, y = 0, rowH = 0
-    for (const i of order) {
-      const w = dims[i][0] * scale, h = dims[i][1] * scale
-      if (x > 0 && x + w > 1) { y += rowH + LM_GUTTER; x = 0; rowH = 0 }
-      if (w > 1 || y + h > 1) return null
-      out[i] = { x, y, w, h }
-      x += w + LM_GUTTER
-      rowH = Math.max(rowH, h)
-    }
-    return out
-  }
-  let lo = 0, hi = 1 / Math.max(...dims.map((d) => Math.max(d[0], d[1])))
-  let best = attempt(hi)
-  if (!best) {
-    for (let it = 0; it < 40; it++) {
-      const mid = (lo + hi) / 2
-      const r = attempt(mid)
-      if (r) { best = r; lo = mid } else hi = mid
-    }
-  }
-  return best ?? dims.map(() => ({ x: 0, y: 0, w: 1, h: 1 }))
-}
-
-// --- cube ---
-const createCube = (size: Vec3Like | number = 1): Geometry => {
-  const sx = typeof size === "number" ? size : cx(size)
-  const sy = typeof size === "number" ? size : cy(size)
-  const sz = typeof size === "number" ? size : cz(size)
-  const vertices = new Float32Array(6 * 4 * 3)
-  const normals = new Float32Array(6 * 4 * 3)
-  const uv = new Float32Array(6 * 4 * 2)
-  const uv1 = new Float32Array(6 * 4 * 2)
-  const indices = new Uint16Array(6 * 6)
-  let cnt = 0, indicesCnt = 0
-  const sides = [ -0.5, 0.5 ]
-  // face extents along the (a, b) parameters below: ±x faces span (z, y), ±y faces (x, z), ±z faces (x, y)
-  const charts = packCharts([ [ sz, sy ], [ sz, sy ], [ sx, sz ], [ sx, sz ], [ sx, sy ], [ sx, sy ] ])
-  for (let i = 0; i < 6; i++) {
-    const s = cnt
-    const side = i % 2 === 0 ? -0.5 : 0.5
-    const c = charts[i]
-    for (const a of sides) {
-      for (const b of sides) {
-        uv.set([ a + 0.5, b + 0.5 ], cnt * 2)
-        uv1.set([ c.x + (a + 0.5) * c.w, c.y + (b + 0.5) * c.h ], cnt * 2)
-        if (i === 0 || i === 1) { vertices.set([ side * sx, b * sy, -a * sz ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
-        if (i === 2 || i === 3) { vertices.set([ a * sx, side * sy, -b * sz ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
-        if (i === 4 || i === 5) { vertices.set([ a * sx, b * sy, side * sz ], cnt * 3); normals.set([ 0, 0, side * 2 ], cnt * 3) }
-        cnt++
-      }
-    }
-    const s1 = s + 1, s2 = s + 2, s3 = s + 3
-    if (i % 2 === 0) indices.set([ s, s1, s2, s3, s2, s1 ], indicesCnt)
-    else indices.set([ s2, s1, s, s1, s2, s3 ], indicesCnt)
-    indicesCnt += 6
-  }
-  const g = new Geometry(vertices, normals, indices, uv)
-  g.uv1 = uv1
-  return g
-}
-
-// --- sphere ---
-export type SphereOptions = { radius?: number, widthSegments?: number, heightSegments?: number }
-const createSphere = (options: SphereOptions = {}): Geometry => {
-  const { radius = 0.5, widthSegments = 32, heightSegments = 32 } = options
-  const verticesCount = (widthSegments + 1) * (heightSegments - 1) + widthSegments * 2
-  const vertices = new Float32Array(verticesCount * 3)
-  const normals = new Float32Array(verticesCount * 3)
-  const uvs = new Float32Array(verticesCount * 2)
-  const indices = new Uint16Array(widthSegments * (heightSegments - 2) * 6 + widthSegments * 3 * 2)
-  const phiLength = Math.PI * 2, thetaLength = Math.PI
-  let vertexCnt = 0, indicesCnt = 0
-  for (let iy = 1; iy < heightSegments; iy++) {
-    const v = iy / heightSegments
-    for (let ix = 0; ix <= widthSegments; ix++) {
-      const u = ix / widthSegments
-      const point: [number, number, number] = [
-        -Math.cos(u * phiLength) * Math.sin(v * thetaLength),
-        Math.cos(v * thetaLength),
-        Math.sin(u * phiLength) * Math.sin(v * thetaLength),
-      ]
-      vertices.set([ point[0] * radius, point[1] * radius, point[2] * radius ], vertexCnt * 3)
-      normals.set(point, vertexCnt * 3)
-      uvs.set([ u, 1 - v ], vertexCnt * 2)
-      if (iy > 1 && ix > 0) {
-        const s = vertexCnt - 1
-        const s1 = vertexCnt - (widthSegments + 1) - 1
-        indices.set([ s + 1, s1, s, s1, s + 1, s1 + 1 ], indicesCnt)
-        indicesCnt += 6
-      }
-      vertexCnt++
-    }
-  }
-  const sides = [ -radius, radius ]
-  const circleStart2 = vertexCnt - (widthSegments + 1)
-  for (const side of sides) {
-    const circleStart = side > 0 ? 0 : circleStart2
-    for (let ix = 0; ix < widthSegments; ix++) {
-      const u = (ix + 0.5) / widthSegments
-      vertices.set([ 0, side, 0 ], vertexCnt * 3)
-      normals.set([ 0, side < 0 ? -1 : 1, 0 ], vertexCnt * 3)
-      uvs.set([ u, side < 0 ? 0 : 1 ], vertexCnt * 2)
-      const s = circleStart + ix
-      if (side > 0) indices.set([ s, s + 1, vertexCnt ], indicesCnt)
-      else indices.set([ vertexCnt, s + 1, s ], indicesCnt)
-      indicesCnt += 3
-      vertexCnt++
-    }
-  }
-  return new Geometry(vertices, normals, indices, uvs)
-}
-
-// --- cylinder ---
-export type CylinderOptions = { radius?: number, radiusTop?: number, radiusBottom?: number, edges?: number, smooth?: boolean }
-const createCylinder = (options: CylinderOptions = {}): Geometry => {
-  const { edges = 32, smooth = true, radius = 0.5, radiusTop = radius, radiusBottom = radius } = options
-  const verticesCount = edges * 4 + (edges + 1) * 2
-  const vertices = new Float32Array(verticesCount * 3)
-  const normals = new Float32Array(verticesCount * 3)
-  const uv = new Float32Array(verticesCount * 2)
-  // lightmap chart: the side strip across the upper half, the two caps as discs in the lower half
-  const uv1 = new Float32Array(verticesCount * 2)
-  const indices = new Uint16Array(edges * 6 + edges * 6)
-  const sides = [ -0.5, 0.5 ]
-  let cnt = 0, indicesCnt = 0
-  for (let i = 0; i < edges; i++) {
-    const s = cnt
-    const normalX = Math.cos((i + 0.5) / edges * Math.PI * 2)
-    const normalY = Math.sin((i + 0.5) / edges * Math.PI * 2)
-    for (let j = 0; j < 2; j++) {
-      const x = Math.cos((i + j) / edges * Math.PI * 2)
-      const y = Math.sin((i + j) / edges * Math.PI * 2)
-      for (const side of sides) {
-        if (side > 0) vertices.set([ x * radiusTop, side, y * radiusTop ], cnt * 3)
-        else vertices.set([ x * radiusBottom, side, y * radiusBottom ], cnt * 3)
-        if (smooth) normals.set([ x, 0, y ], cnt * 3)
-        else normals.set([ normalX, 0, normalY ], cnt * 3)
-        uv.set([ (i + j) / edges, side + 0.5 ], cnt * 2)
-        uv1.set([ (i + j) / edges, 0.55 + (side + 0.5) * 0.43 ], cnt * 2)
-        cnt++
-      }
-    }
-    const s1 = s + 1, s2 = (s + 2) % (edges * 4), s3 = (s + 3) % (edges * 4)
-    indices.set([ s, s1, s2, s3, s2, s1 ], indicesCnt)
-    indicesCnt += 6
-  }
-  for (const side of sides) {
-    const center = cnt
-    const capU = side > 0 ? 0.75 : 0.25   // lightmap disc centre per cap
-    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3)
-    uv1.set([ capU, 0.25 ], cnt * 2); cnt++
-    for (let i = 0; i < edges; i++) {
-      const x = Math.cos(i / edges * Math.PI * 2), y = Math.sin(i / edges * Math.PI * 2)
-      if (side > 0) vertices.set([ x * radiusTop, side, y * radiusTop ], cnt * 3)
-      else vertices.set([ x * radiusBottom, side, y * radiusBottom ], cnt * 3)
-      normals.set([ 0, side * 2, 0 ], cnt * 3)
-      uv1.set([ capU + x * 0.22, 0.25 + y * 0.22 ], cnt * 2)
-      if (side < 0) indices.set([ center, center + i + 1, center + 1 + ((i + 1) % edges) ], indicesCnt)
-      else indices.set([ center + 1 + ((i + 1) % edges), center + i + 1, center ], indicesCnt)
-      indicesCnt += 3
-      cnt++
-    }
-  }
-  const g = new Geometry(vertices, normals, indices, uv)
-  g.uv1 = uv1
-  return g
-}
-
-// --- plane ---
-export type PlaneOptions = { normal?: Vec3Like }
-const createPlane = (options: PlaneOptions = {}): Geometry => {
-  const normal: Tup3 = options.normal ? [ cx(options.normal), cy(options.normal), cz(options.normal) ] : [ 0, 0, 1 ]
-  const vertices = new Float32Array(4 * 3)
-  const normals = new Float32Array(4 * 3)
-  const uvs = new Float32Array(4 * 2)
-  const sides = [ -0.5, 0.5 ]
-  let cnt = 0
-  let upVector: Tup3, rightVec: Tup3
-  if (normal[1] === 0 && normal[2] === 0) { upVector = [ 0, 1, 0 ]; rightVec = [ 0, 0, -normal[0] ] }
-  else if (normal[0] === 0 && normal[2] === 0) { upVector = [ 0, 0, 1 ]; rightVec = [ -normal[1], 0, 0 ] }
-  else if (normal[0] === 0 && normal[1] === 0) { upVector = [ 0, 1, 0 ]; rightVec = [ normal[2], 0, 0 ] } // тут было верно
-  else {
-    const temp: Tup3 = Math.abs(normal[0]) < 0.5 ? [ 1, 0, 0 ] : [ 0, 0, 1 ]
-    upVector = normalize(cross(temp, normal))
-    rightVec = normalize(cross(upVector, normal))
-  }
-  for (const a of sides) {
-    for (const b of sides) {
-      normals.set(normal, cnt * 3)
-      uvs.set([ a + 0.5, b + 0.5 ], cnt * 2)
-      vertices.set([
-        rightVec[0] * a + upVector[0] * b,
-        rightVec[1] * a + upVector[1] * b,
-        rightVec[2] * a + upVector[2] * b,
-      ], cnt * 3)
-      cnt++
-    }
-  }
-  const indices = new Uint16Array([ 2, 1, 0, 1, 2, 3 ])
-  return new Geometry(vertices, normals, indices, uvs)
-}

package/runtime/sdk/gl/IK.ts

@@ -1,193 +0,0 @@
-// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
-// They run after the animation wrote the pose (base anim or Animator) and before the skin is
-// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
-// walked up through parents — one instance per end effector, any Node hierarchy works.
-//
-//   const foot = hero.bone('LeftFoot')!
-//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
-//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
-//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
-//
-// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
-// slot in later behind the same API.
-
-import { Aspect } from "../core/Aspect"
-import { Vec3, type Vec3Like } from "../math/vec"
-import { Quat } from "../math/quat"
-import type { Node } from "./Node"
-
-type Target = Node | Vec3Like
-
-const targetPos = (t: Target | undefined): Vec3 | null => {
-  if (t === undefined || t === null) return null
-  const n = t as Node
-  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
-  return new Vec3(t as Vec3Like)
-}
-
-/** World rotation of a node (parent chain composed natively). */
-const worldRot = (n: Node): Quat => n.worldMatrix.rotation
-
-/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
-const setWorldRot = (n: Node, q: Quat): void => {
-  const p = n.parent
-  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
-}
-
-const clampAngle = (q: Quat, maxRad: number): Quat => {
-  // angle of a unit quaternion = 2·acos(|w|)
-  const w = Math.min(1, Math.abs(q.w))
-  const ang = 2 * Math.acos(w)
-  if (ang <= maxRad || ang < 1e-6) return q
-  const s = Math.sqrt(1 - w * w)
-  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
-  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
-}
-
-/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
- *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
- *  (knee/elbow) — a Node or world point. */
-class TwoBone extends Aspect<"ik", Node> {
-  static readonly aspect = "ik"
-
-  /** Where the end bone should be (Node or world position). */
-  target?: Target
-  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
-  pole?: Target
-  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
-   *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
-   *  want it set). Blended by `weight · rotationWeight`. */
-  rotation?: Node | Quat
-  /** 0–1 contribution of `rotation` (on top of `weight`). */
-  rotationWeight = 1
-  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
-  weight = 1
-  /** Solve every frame (default). Set false to drive `solve()` yourself. */
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const end = this.node
-    const mid = end.parent
-    const root = mid?.parent
-    if (!mid || !root) return
-
-    const w = Math.min(1, this.weight)
-    const midLocal0 = mid.quaternion
-    const rootLocal0 = root.quaternion
-
-    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
-    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
-    if (l1 < 1e-6 || l2 < 1e-6) return
-    const eps = 1e-4
-    const toT = t.sub(a)
-    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
-
-    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
-    const ba = a.sub(b), bc = c.sub(b)
-    const cur = ba.angle(bc)
-    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
-    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
-    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
-    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
-    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
-    let axis = ba.cross(bc)
-    if (axis.lengthSq() < 1e-10) {
-      // straight limb: bend toward the pole (or any perpendicular)
-      const p = targetPos(this.pole)
-      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
-      axis = ba.cross(ref)
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
-    }
-    axis = axis.normalize()
-    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
-    const midWorld = worldRot(mid)
-    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
-
-    // 2. swing the root so the end lands on the target direction
-    const c2 = end.worldPosition
-    const rootWorld = worldRot(root)
-    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
-
-    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
-    const p = targetPos(this.pole)
-    if (p) {
-      const dir = toT.normalize()
-      const b2 = mid.worldPosition
-      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
-      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
-      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
-        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
-      }
-    }
-
-    // 4. weight: blend from the animated pose to the solved one
-    if (w < 1) {
-      root.quaternion = rootLocal0.slerp(root.quaternion, w)
-      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
-    }
-
-    // 5. end-bone rotation: take the target's world rotation (a hand stays on its grip, a foot
-    // flat on the slope) — the solve above only placed the end's ORIGIN
-    const r = this.rotation
-    if (r !== undefined && r !== null) {
-      const rw = w * Math.min(1, Math.max(0, this.rotationWeight))
-      if (rw > 0) {
-        const want = (r as Node).id !== undefined && typeof (r as Node).worldMatrix === "object" ? worldRot(r as Node) : (r as Quat)
-        const endLocal0 = end.quaternion
-        setWorldRot(end, want)
-        if (rw < 1) end.quaternion = endLocal0.slerp(end.quaternion, rw)
-      }
-    }
-  }
-}
-
-/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
- *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
- *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
- *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
-class LookAt extends Aspect<"lookAt", Node> {
-  static readonly aspect = "lookAt"
-
-  target?: Target
-  /** The bone's local axis that should point at the target. */
-  axis: Vec3Like = [ 0, 0, -1 ]
-  /** Max deflection from the animated direction, in degrees (default 80). */
-  limit = 80
-  /** 0–1 contribution. */
-  weight = 1
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const bone = this.node
-    const w = Math.min(1, this.weight)
-    const local0 = bone.quaternion
-    const from = bone.worldPosition
-    const dir = t.sub(from)
-    if (dir.lengthSq() < 1e-10) return
-    const rot = worldRot(bone)
-    const current = new Vec3(this.axis).rotate(rot)
-    let delta = Quat.fromTo(current, dir)
-    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
-    setWorldRot(bone, delta.mul(rot))
-    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
-  }
-}
-
-/** Inverse kinematics aspects — attach to bones (see file header). */
-export const IK = { TwoBone, LookAt }
-export type IKTwoBone = TwoBone
-export type IKLookAt = LookAt