lecodes-sdk 0.19.0

package/src/gl/controls.ts

@@ -0,0 +1,95 @@
+// AR object-placement controls — the classic "drop a model in the room and manipulate it" gesture
+// recipe: ONE finger drags the target across the ground plane (camera-relative), TWO fingers pinch to
+// scale and twist to rotate (yaw). Lives on ARScene (see Scene.ts) because it orchestrates the scene's
+// camera + touch input against a target node; it's built entirely on the public API (no native calls
+// the user couldn't make), so it's a convenience, not a primitive.
+
+import { Vec2, Vec3 } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+import type { Scene } from "./Scene"
+import type { TouchStartEvent } from "../runtime/touch"
+
+export type ControlsOptions = {
+  /** Smallest uniform scale the pinch gesture allows (default 0.08). */
+  minScale?: number
+  /** Largest uniform scale the pinch gesture allows (default 2). */
+  maxScale?: number
+  /** One-finger drag moves the target across the ground plane (default true). */
+  pan?: boolean
+  /** Two-finger pinch scales the target (default true). */
+  pinch?: boolean
+  /** Two-finger twist rotates the target around its Y axis (default true). */
+  twist?: boolean
+}
+
+/** Returned by `addControls` — call `remove()` to detach the gesture listeners. */
+export type ControlsHandle = { remove(): void }
+
+type ActiveTouch = { pointerId: number, x: number, y: number }
+
+const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+
+export const attachControls = (scene: Scene, target: Node, options: ControlsOptions = {}): ControlsHandle => {
+  const minScale = options.minScale ?? 0.08
+  const maxScale = options.maxScale ?? 2
+  const pan = options.pan ?? true
+  const pinch = options.pinch ?? true
+  const twist = options.twist ?? true
+
+  const active: ActiveTouch[] = []
+
+  const onTouchStart = (e: TouchStartEvent<Node | null>): void => {
+    const touch: ActiveTouch = { pointerId: e.pointerId, x: e.clientX, y: e.clientY }
+    active.push(touch)
+    e.track({
+      onMove(m) {
+        if (active.length === 2) {
+          // --- two-finger: pinch-scale + twist-rotate about the gesture axis ---
+          const other = active.find((t) => t !== touch)
+          if (other) {
+            const axis = new Vec2(other.x - touch.x, other.y - touch.y)
+            const span = axis.length()
+            if (span > 1e-3) {
+              const dir = axis.scale(1 / span)
+              const delta = new Vec2(m.deltaX, m.deltaY)
+              if (pinch) {
+                const along = -dir.dot(delta) // movement along the pinch axis
+                target.scale = clamp(target.scale.x * (span + along) / span, minScale * 0.4, maxScale * 1.5)
+              }
+              if (twist) {
+                const tangent = dir.perp().dot(delta) // movement across the axis
+                target.quaternion = target.quaternion.mul(Quat.fromAxisAngle(Vec3.up, Math.atan2(tangent, span)))
+              }
+            }
+          }
+        } else if (active.length === 1 && pan) {
+          // --- one-finger: drag across the ground plane, relative to where the camera looks ---
+          let dir = scene.camera.forward
+          const parent = target.parent
+          if (parent) dir = dir.rotate(parent.quaternion.invert()) // into the parent's local frame
+          dir = dir.withY(0)
+          const k = Math.hypot(dir.x, dir.z)
+          const screen = Math.max(...scene.camera.displaySize)
+          if (k > 1e-4 && screen > 0) {
+            const dist = target.worldPosition.distanceTo(scene.camera.worldPosition)
+            const right = new Vec3(-dir.z, 0, dir.x).scale(m.deltaX / k / screen * dist)
+            const fwd = dir.scale(-m.deltaY / k / screen * dist)
+            const move = right.add(fwd)
+            const p = target.position
+            target.position = new Vec3(p.x + move.x, p.y, p.z + move.z) // keep height fixed
+          }
+        }
+        touch.x = m.clientX
+        touch.y = m.clientY
+      },
+      onEnd() {
+        const i = active.indexOf(touch)
+        if (i >= 0) active.splice(i, 1)
+      },
+    })
+  }
+
+  scene.addEventListener("touchstart", onTouchStart)
+  return { remove() { scene.removeEventListener("touchstart", onTouchStart); active.length = 0 } }
+}

package/src/gl/physicsEvents.ts

@@ -0,0 +1,20 @@
+// Routes native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
+// is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
+// 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
+
+import { nodeRegistry } from "./Node"
+
+let registered = false
+export const ensurePhysicsEvents = (): void => {
+  if (registered) return
+  if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
+  registered = true
+  _creator.setOnPhysicsEvent((a, b, type) => {
+    const na = nodeRegistry.get(a)
+    const nb = nodeRegistry.get(b)
+    if (!na || !nb) return
+    const channel = type === 1 ? "exit" : "enter"
+    na._emitCollision(channel, nb)
+    nb._emitCollision(channel, na)
+  })
+}

package/src/gl/scenarios.ts

@@ -0,0 +1,291 @@
+// No-code scenario aspects: ready-made behaviors a scene builder attaches in the editor without
+// writing any code — move to a target, travel a waypoint path, spin, face something, start a GLB
+// animation. They are ordinary aspects (work from hand-written code too); in the scene editor the
+// movement ones double as `static editor` generators that draw their paths as editor gizmos
+// (`Gizmos.*` in rebuild() — overlay lines, never scene content; play mode never calls rebuild(),
+// so they cost nothing at runtime).
+//
+// Conventions shared by the family:
+//   • targets/waypoints are scene nodes — place an Empty, then pick it in the inspector (`ref()`);
+//   • times are seconds, angles degrees; all motion runs in `update(dt)` (play mode only);
+//   • orientation is quaternion-composed — never euler-incremented (see math/quat.ts).
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import type { InspectorUI } from "../core/InspectorUI"
+import { Vec3 } from "../math/vec"
+import { Quat } from "../math/quat"
+import { Node } from "./Node"
+import { Model } from "./Model"
+import type { Playback } from "./animation/Playback"
+import { Gizmos } from "../scene/gizmos"
+
+const MOVE_LINE = "#5b8ef0"
+const LOOK_LINE = "#d9a13f"
+const DEG2RAD = Math.PI / 180
+
+type LoopMode = "once" | "loop" | "pingpong"
+
+/** Normalized phase for elapsed time `t` over one trip of `duration`: once clamps at 1, loop
+ *  wraps, pingpong triangles 0→1→0. */
+const phase = (t: number, duration: number, mode: LoopMode): number => {
+  if (duration <= 0) return 1
+  const u = t / duration
+  if (mode === "once") return Math.min(u, 1)
+  if (mode === "loop") return u - Math.floor(u)
+  const v = u % 2
+  return v <= 1 ? v : 2 - v
+}
+
+const ease = (k: number, easing: "smooth" | "linear"): number =>
+  easing === "smooth" ? k * k * (3 - 2 * k) : k
+
+/** A world point in `node`'s PARENT space — what `node.position` is expressed in. */
+const toParentLocal = (node: Node, world: Vec3): Vec3 => {
+  const parent = node.parent
+  return parent ? parent.worldMatrix.invert().transformPoint(world) : world
+}
+
+/** A path node's waypoints: its children in scene-FILE order (`_sceneChildOrder`, stamped by
+ *  defineScene — the engine's live child order is insertion-based and may differ), editor helper
+ *  nodes (`__`-prefixed) excluded. Runtime-added children append in engine order. */
+const pathWaypoints = (path: Node): Node[] => {
+  const children = path.children.filter((c) => !(c.name ?? "").startsWith("__"))
+  const order = (path as { _sceneChildOrder?: string[] })._sceneChildOrder
+  if (!order) return children
+  const byName = new Map(children.map((c) => [ c.name, c ]))
+  const sorted: Node[] = []
+  for (const n of order) { const c = byName.get(n); if (c) sorted.push(c) }
+  const seen = new Set(sorted)
+  for (const c of children) if (!seen.has(c)) sorted.push(c)
+  return sorted
+}
+
+// ---- the aspects ---------------------------------------------------------------------------------
+
+/** Travel from the node's starting position to a target node in `duration` seconds. */
+export class MoveTo extends Aspect<"moveTo"> {
+  /** Where to travel — place an Empty node and pick it. */
+  target: Node | null = null
+
+  /** Seconds for the full trip. */
+  duration = 2
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  /** once = stop at the target · loop = restart from the start point · pingpong = back and forth. */
+  mode: LoopMode = "once"
+
+  /** Motion curve. */
+  easing: "smooth" | "linear" = "smooth"
+
+  static readonly aspect = "moveTo"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<MoveTo> = {
+    target: { editor: "node" },
+    duration: { min: 0.05, max: 120, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "once", "loop", "pingpong" ] },
+    easing: { options: [ "smooth", "linear" ] },
+  }
+
+  private _t = 0
+  private _start: Vec3 | null = null
+
+  update(dt: number): void {
+    if (!this.target) return
+    this._start ??= this.node.position
+    this._t += dt
+    const k = ease(phase(Math.max(0, this._t - this.delay), this.duration, this.mode), this.easing)
+    const end = toParentLocal(this.node, this.target.worldPosition)
+    this.node.position = new Vec3(this._start).add(end.sub(this._start).scale(k))
+  }
+
+  /** Editor-only path line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    if (!this.target) return
+    // the target is an empty — its own anchored marker shows the endpoint
+    Gizmos.line(this.node.worldPosition, this.target.worldPosition, { color: MOVE_LINE })
+  }
+}
+
+/** Travel through the children of a path node (add an Empty per waypoint) in `duration` seconds.
+ *  `loop` runs the circuit closed (last → first); `pingpong` goes back and forth along the open
+ *  path; `once` stops at the last waypoint. */
+export class FollowPath extends Aspect<"followPath"> {
+  /** A node whose CHILDREN are the waypoints, in file order. */
+  path: Node | null = null
+
+  /** Seconds for one full pass of the path. */
+  duration = 6
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  mode: LoopMode = "loop"
+
+  /** Turn to face the direction of travel. */
+  orient = true
+
+  /** Which local axis leads when orienting. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  static readonly aspect = "followPath"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<FollowPath> = {
+    path: { editor: "node" },
+    duration: { min: 0.05, max: 300, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "loop", "once", "pingpong" ] },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+  }
+
+  private _t = 0
+
+  private _points(): Vec3[] {
+    if (!this.path) return []
+    const points = pathWaypoints(this.path).map((c) => c.worldPosition)
+    if (this.mode === "loop" && points.length > 1) points.push(points[0]!.clone())
+    return points
+  }
+
+  update(dt: number): void {
+    const points = this._points()
+    if (points.length < 2) return
+    this._t += dt
+    const k = phase(Math.max(0, this._t - this.delay), this.duration, this.mode === "loop" ? "loop" : this.mode)
+
+    const lengths: number[] = []
+    let total = 0
+    for (let i = 0; i < points.length - 1; i++) {
+      const l = points[i + 1]!.sub(points[i]!).length()
+      lengths.push(l)
+      total += l
+    }
+    if (total <= 0) return
+
+    let dist = k * total
+    let i = 0
+    while (i < lengths.length - 1 && dist > lengths[i]!) { dist -= lengths[i]!; i++ }
+    const a = points[i]!
+    const b = points[i + 1]!
+    const seg = b.sub(a)
+    const u = lengths[i]! > 0 ? Math.min(dist / lengths[i]!, 1) : 0
+    const world = a.add(seg.scale(u))
+    this.node.position = toParentLocal(this.node, world)
+    if (this.orient && seg.lengthSq() > 1e-12) this.node.lookAt(world.add(seg), this.forward)
+  }
+
+  /** Editor-only waypoint polyline (edit mode; play mode never calls this). */
+  rebuild(): void {
+    const points = this._points()   // loop mode already appends the first point again
+    Gizmos.polyline(points, { color: MOVE_LINE })   // waypoints are empties: they carry their own markers
+  }
+}
+
+/** Continuous rotation about one of the node's local axes, degrees per second. */
+export class Spin extends Aspect<"spin"> {
+  /** Degrees per second. */
+  speed = 45
+
+  /** Local axis to spin around. */
+  axis: "x" | "y" | "z" = "y"
+
+  static readonly aspect = "spin"
+  static fields: FieldMeta<Spin> = {
+    speed: { min: -720, max: 720, step: 5 },
+    axis: { options: [ "x", "y", "z" ] },
+  }
+
+  update(dt: number): void {
+    const axis: [number, number, number] = this.axis === "x" ? [ 1, 0, 0 ] : this.axis === "y" ? [ 0, 1, 0 ] : [ 0, 0, 1 ]
+    // compose in quaternion space about the LOCAL axis (q ⊗ dq) — never euler-increment
+    this.node.quaternion = this.node.quaternion.mul(Quat.fromAxisAngle(axis, this.speed * dt * DEG2RAD))
+  }
+}
+
+/** Keep the node facing a target node (a turret tracking, a signpost, a camera aimed at a hero).
+ *  Accessor `node.facing` — NOT `lookAt`, which would shadow the `Node.lookAt()` method. */
+export class LookAt extends Aspect<"facing"> {
+  /** The node to face. */
+  target: Node | null = null
+
+  /** Which local axis points at the target. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  /** 0 = snap instantly; otherwise seconds of turn lag (bigger = slower, smoother). */
+  smoothing = 0
+
+  static readonly aspect = "facing"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<LookAt> = {
+    target: { editor: "node" },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+    smoothing: { min: 0, max: 5, step: 0.05 },
+  }
+
+  update(dt: number): void {
+    if (!this.target) return
+    const point = this.target.worldPosition
+    if (this.smoothing <= 0) { this.node.lookAt(point, this.forward); return }
+    const q0 = this.node.quaternion
+    this.node.lookAt(point, this.forward)
+    const q1 = this.node.quaternion
+    this.node.quaternion = q0.slerp(q1, 1 - Math.exp(-dt / this.smoothing))
+  }
+
+  /** Editor-only sight line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    if (!this.target) return
+    Gizmos.line(this.node.worldPosition, this.target.worldPosition, { color: LOOK_LINE })
+  }
+}
+
+/** Start a GLB animation clip when the scene runs. Attach to a `model:` node; the inspector card
+ *  lists the model's clips live and can preview them while editing. */
+export class PlayAnimation extends Aspect<"playAnimation", Model> {
+  /** Clip name; empty = the model's first clip. */
+  clip = ""
+
+  loop = true
+
+  /** Playback rate (1 = authored speed). */
+  speed = 1
+
+  static readonly aspect = "playAnimation"
+  static fields: FieldMeta<PlayAnimation> = {
+    speed: { min: 0.05, max: 5, step: 0.05 },
+  }
+
+  private _preview?: Playback
+
+  onAttach(): void {
+    const anim = (this.node as Model | undefined)?.anim
+    if (!anim) return
+    if (this.loop) anim.playLoop(this.clip === "" ? 0 : this.clip, { speed: this.speed })
+    else anim.play(this.clip === "" ? 0 : this.clip, { speed: this.speed })
+  }
+
+  static inspector(ui: InspectorUI, a: PlayAnimation): void {
+    const anim = (a.node as Model | undefined)?.anim
+    const clips = anim ? anim.clips : []
+    if (clips.length === 0) {
+      ui.warn("No animation clips — attach this to a GLB model node")
+      return
+    }
+    ui.select("clip", clips.map((c) => c.name))
+    ui.auto("loop", "speed")
+    if (anim) {
+      const clip = a.clip === "" ? clips[0]?.name : a.clip
+      const playing = a._preview?.playing === true
+      if (ui.button(playing ? "Restart preview" : "Preview")) {
+        if (a.loop) { anim.playLoop(clip, { speed: a.speed }); a._preview = undefined }
+        else a._preview = anim.play(clip, { speed: a.speed, restart: true })
+      }
+      if (playing && ui.button("Stop")) { anim.stop(); a._preview = undefined }
+      const duration = clips.find((c) => c.name === clip)?.duration
+      ui.info(playing ? "previewing…" : duration !== undefined ? `${duration.toFixed(2)}s` : "")
+    }
+  }
+}

package/src/gl/state.ts

@@ -0,0 +1,6 @@
+// Tiny shared module to break the Node ↔ Scene ↔ touch dependency cycle. The active 3D scene is set
+// here by Scene.open()/close() and read by the touch dispatch system.
+
+import type { Scene } from "./Scene"
+
+export const glState: { activeScene: Scene | null, frame: number } = { activeScene: null, frame: 0 }

package/src/gl/terrainMesh.ts

@@ -0,0 +1,219 @@
+// The terrain grid as geometry, in TypeScript — used two ways (docs/terrain-plan.md §1.3, §3.5):
+//   • `heightAt` / `normalAt` — the SDK's own queries, identical on every host (bilinear on the SAME
+//     triangle split the engines draw and collide);
+//   • `buildTerrainChunk` — chunk meshes for hosts WITHOUT `_creator.terrainCreate` (web-lite, headless,
+//     a wasm/AAR/Apple build predating the feature): the same grid → chunk → triangles rule
+//     creator-gl/src/terrain.cpp applies (the i00–i11 diagonal, CCW seen from +Y, a triangle only when
+//     its three samples are valid), as plain Geometry for setMesh. Normals use central differences over
+//     the FULL grid (seamless chunks); the tangent frame is then the host's arbitrary one, so normal maps
+//     read wrong on those hosts — the accepted fallback cost.
+// Keep the hole / split rule in step with terrain.cpp buildChunk and Jolt's HeightFieldShape.
+
+import { Geometry } from "./Geometry"
+
+export type TerrainGrid = {
+  sizeX: number
+  sizeZ: number
+  cellSize: number
+  /** sizeX × sizeZ heights, row-major (z rows). */
+  heights: Float32Array
+  /** One byte per sample, 1 = hole; null = no holes. */
+  holes: Uint8Array | null
+}
+
+const clampI = (v: number, hi: number): number => (v < 0 ? 0 : v > hi ? hi : v)
+
+/** The sample at integer (x, z), clamped to the grid. */
+export const sampleAt = (g: TerrainGrid, x: number, z: number): number =>
+  g.heights[clampI(z, g.sizeZ - 1) * g.sizeX + clampI(x, g.sizeX - 1)]
+
+export const isHole = (g: TerrainGrid, x: number, z: number): boolean =>
+  g.holes !== null && g.holes[z * g.sizeX + x] !== 0
+
+/** Surface normal at a sample from central differences (one-sided at the borders). Writes `out` (xyz). */
+export const normalAt = (g: TerrainGrid, x: number, z: number, out: Float32Array | number[] = [ 0, 0, 0 ]): typeof out => {
+  const x0 = x > 0 ? x - 1 : x, x1 = x + 1 < g.sizeX ? x + 1 : x
+  const z0 = z > 0 ? z - 1 : z, z1 = z + 1 < g.sizeZ ? z + 1 : z
+  const dx = (sampleAt(g, x1, z) - sampleAt(g, x0, z)) / ((x1 - x0) * g.cellSize)
+  const dz = (sampleAt(g, x, z1) - sampleAt(g, x, z0)) / ((z1 - z0) * g.cellSize)
+  const len = Math.hypot(dx, 1, dz)
+  out[0] = -dx / len; out[1] = 1 / len; out[2] = -dz / len
+  return out
+}
+
+/**
+ * Height at a LOCAL (x, z) in metres, interpolated on the drawn triangles (the i00–i11 diagonal), so a
+ * character's feet and a raycast agree with what is rendered to the millimetre. NaN inside a hole
+ * triangle or outside the grid.
+ */
+export const heightAt = (g: TerrainGrid, x: number, z: number): number => {
+  const fx = x / g.cellSize, fz = z / g.cellSize
+  if (!(fx >= 0 && fz >= 0 && fx <= g.sizeX - 1 && fz <= g.sizeZ - 1)) return NaN
+  let ix = Math.floor(fx), iz = Math.floor(fz)
+  if (ix >= g.sizeX - 1) ix = g.sizeX - 2
+  if (iz >= g.sizeZ - 1) iz = g.sizeZ - 2
+  const u = fx - ix, v = fz - iz
+  const i00 = iz * g.sizeX + ix
+  const h00 = g.heights[i00], h10 = g.heights[i00 + 1], h01 = g.heights[i00 + g.sizeX], h11 = g.heights[i00 + g.sizeX + 1]
+  if (g.holes !== null) {
+    const holes = g.holes
+    if (holes[i00] || holes[i00 + g.sizeX + 1]) return NaN
+    // lower-left triangle (i00, i01, i11) when v >= u, else upper-right (i00, i11, i10)
+    if (v >= u ? holes[i00 + g.sizeX] !== 0 : holes[i00 + 1] !== 0) return NaN
+  }
+  // plane of the triangle the point falls in
+  return v >= u
+    ? h00 + (h11 - h01) * u + (h01 - h00) * v
+    : h00 + (h10 - h00) * u + (h11 - h10) * v
+}
+
+/** The geometric normal at a LOCAL (x, z): the drawn triangle's normal (not the smoothed vertex one). */
+export const faceNormalAt = (g: TerrainGrid, x: number, z: number, out: Float32Array | number[] = [ 0, 0, 0 ]): typeof out => {
+  const fx = x / g.cellSize, fz = z / g.cellSize
+  let ix = Math.floor(fx), iz = Math.floor(fz)
+  ix = clampI(ix, g.sizeX - 2); iz = clampI(iz, g.sizeZ - 2)
+  const u = fx - ix, v = fz - iz
+  const i00 = iz * g.sizeX + ix
+  const h00 = g.heights[i00], h10 = g.heights[i00 + 1], h01 = g.heights[i00 + g.sizeX], h11 = g.heights[i00 + g.sizeX + 1]
+  const c = g.cellSize
+  // gradients of the two planes (see heightAt)
+  const dx = (v >= u ? h11 - h01 : h10 - h00) / c
+  const dz = (v >= u ? h01 - h00 : h11 - h10) / c
+  const len = Math.hypot(dx, 1, dz)
+  out[0] = -dx / len; out[1] = 1 / len; out[2] = -dz / len
+  return out
+}
+
+/** Chunks along X and Z for a grid: a chunk covers `chunk` cells (chunk + 1 samples). */
+export const chunkCounts = (g: TerrainGrid, chunk: number): [number, number] =>
+  [ Math.floor((g.sizeX - 2) / chunk) + 1, Math.floor((g.sizeZ - 2) / chunk) + 1 ]
+
+/**
+ * One chunk as a Geometry (positions, smooth normals, UV0 = local XZ metres, UV1 = the terrain's unit
+ * square, u16 indices), or null when every cell of it is a hole.
+ */
+export const buildTerrainChunk = (g: TerrainGrid, cx: number, cz: number, chunk: number): Geometry | null => {
+  const x0 = cx * chunk, z0 = cz * chunk
+  const x1 = Math.min(x0 + chunk, g.sizeX - 1), z1 = Math.min(z0 + chunk, g.sizeZ - 1)
+  const nx = x1 - x0 + 1, nz = z1 - z0 + 1
+  const idx: number[] = []
+  for (let z = z0; z < z1; z++) {
+    for (let x = x0; x < x1; x++) {
+      const i00 = (z - z0) * nx + (x - x0), i10 = i00 + 1, i01 = i00 + nx, i11 = i01 + 1
+      const v00 = !isHole(g, x, z), v10 = !isHole(g, x + 1, z), v01 = !isHole(g, x, z + 1), v11 = !isHole(g, x + 1, z + 1)
+      if (!(v00 && v11)) continue
+      if (v01) idx.push(i00, i01, i11)
+      if (v10) idx.push(i00, i11, i10)
+    }
+  }
+  if (idx.length === 0) return null
+  const count = nx * nz
+  const vertices = new Float32Array(count * 3)
+  const normals = new Float32Array(count * 3)
+  const uv = new Float32Array(count * 2)
+  const uv1 = new Float32Array(count * 2)
+  const n = [ 0, 0, 0 ]
+  const invX = 1 / (g.sizeX - 1), invZ = 1 / (g.sizeZ - 1)
+  for (let z = z0; z <= z1; z++) {
+    for (let x = x0; x <= x1; x++) {
+      const i = (z - z0) * nx + (x - x0)
+      vertices[i * 3] = x * g.cellSize
+      vertices[i * 3 + 1] = g.heights[z * g.sizeX + x]
+      vertices[i * 3 + 2] = z * g.cellSize
+      normalAt(g, x, z, n)
+      normals[i * 3] = n[0]; normals[i * 3 + 1] = n[1]; normals[i * 3 + 2] = n[2]
+      uv[i * 2] = x * g.cellSize; uv[i * 2 + 1] = z * g.cellSize
+      uv1[i * 2] = x * invX; uv1[i * 2 + 1] = z * invZ
+    }
+  }
+  const geom = new Geometry(vertices, normals, Uint16Array.from(idx), uv)
+  geom.uv1 = uv1
+  return geom
+}
+
+// ---- ray queries ---------------------------------------------------------------------------------
+
+export type GridHit = { x: number, y: number, z: number, distance: number, nx: number, ny: number, nz: number }
+
+/** Möller–Trumbore against one triangle; the distance along the ray, or -1. */
+const rayTriangle = (
+  ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,
+  ax: number, ay: number, az: number, bx: number, by: number, bz: number, qx: number, qy: number, qz: number,
+): number => {
+  const e1x = bx - ax, e1y = by - ay, e1z = bz - az
+  const e2x = qx - ax, e2y = qy - ay, e2z = qz - az
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x
+  const det = e1x * px + e1y * py + e1z * pz
+  if (Math.abs(det) < 1e-12) return -1
+  const inv = 1 / det
+  const tx = ox - ax, ty = oy - ay, tz = oz - az
+  const u = (tx * px + ty * py + tz * pz) * inv
+  if (u < -1e-6 || u > 1 + 1e-6) return -1
+  const qxx = ty * e1z - tz * e1y, qyy = tz * e1x - tx * e1z, qzz = tx * e1y - ty * e1x
+  const v = (dx * qxx + dy * qyy + dz * qzz) * inv
+  if (v < -1e-6 || u + v > 1 + 1e-6) return -1
+  const t = (e2x * qxx + e2y * qyy + e2z * qzz) * inv
+  return t >= 0 ? t : -1
+}
+
+/**
+ * Nearest hit of a LOCAL ray (origin + direction, metres) on the drawn triangles — the same
+ * i00–i11 split and hole rule as `heightAt`, so a pick lands on what is rendered. Walks the cells
+ * the ray crosses (2D DDA on XZ), testing each cell's two triangles; holes let the ray through.
+ * Null when it misses (or never enters the grid within `maxDistance`).
+ */
+export const gridRaycast = (g: TerrainGrid, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance = 1e5): GridHit | null => {
+  const c = g.cellSize, W = (g.sizeX - 1) * c, D = (g.sizeZ - 1) * c
+  let t0 = 0, t1 = maxDistance
+  const clip = (o: number, d: number, hi: number): boolean => {
+    if (Math.abs(d) < 1e-12) return o >= 0 && o <= hi
+    let a = -o / d, b = (hi - o) / d
+    if (a > b) { const s = a; a = b; b = s }
+    if (a > t0) t0 = a
+    if (b < t1) t1 = b
+    return t0 <= t1
+  }
+  if (!clip(ox, dx, W) || !clip(oz, dz, D)) return null
+  const sx = ox + dx * t0, sz = oz + dz * t0
+  let ix = Math.min(g.sizeX - 2, Math.max(0, Math.floor(sx / c)))
+  let iz = Math.min(g.sizeZ - 2, Math.max(0, Math.floor(sz / c)))
+  const stepX = dx > 1e-12 ? 1 : dx < -1e-12 ? -1 : 0
+  const stepZ = dz > 1e-12 ? 1 : dz < -1e-12 ? -1 : 0
+  const tDeltaX = stepX ? Math.abs(c / dx) : Infinity, tDeltaZ = stepZ ? Math.abs(c / dz) : Infinity
+  let tMaxX = stepX > 0 ? t0 + ((ix + 1) * c - sx) / dx : stepX < 0 ? t0 + (ix * c - sx) / dx : Infinity
+  let tMaxZ = stepZ > 0 ? t0 + ((iz + 1) * c - sz) / dz : stepZ < 0 ? t0 + (iz * c - sz) / dz : Infinity
+  const holes = g.holes
+  let t = t0
+  for (let guard = 0; guard < g.sizeX + g.sizeZ + 2 && t <= t1 + 1e-9; guard++) {
+    const i00 = iz * g.sizeX + ix, i10 = i00 + 1, i01 = i00 + g.sizeX, i11 = i01 + 1
+    const x0 = ix * c, x1 = x0 + c, z0 = iz * c, z1 = z0 + c
+    const h00 = g.heights[i00], h10 = g.heights[i10], h01 = g.heights[i01], h11 = g.heights[i11]
+    const ok00 = !holes || holes[i00] === 0, ok11 = !holes || holes[i11] === 0
+    let best = -1, tri = 0
+    if (ok00 && ok11) {
+      // lower-left (i00, i01, i11) and upper-right (i00, i11, i10) — both CCW seen from +Y
+      if (!holes || holes[i01] === 0) {
+        const d = rayTriangle(ox, oy, oz, dx, dy, dz, x0, h00, z0, x0, h01, z1, x1, h11, z1)
+        if (d >= 0 && (best < 0 || d < best)) { best = d; tri = 0 }
+      }
+      if (!holes || holes[i10] === 0) {
+        const d = rayTriangle(ox, oy, oz, dx, dy, dz, x0, h00, z0, x1, h11, z1, x1, h10, z0)
+        if (d >= 0 && (best < 0 || d < best)) { best = d; tri = 1 }
+      }
+    }
+    if (best >= 0 && best <= t1 + 1e-6) {
+      // the hit triangle's normal
+      let ax: number, ay: number, az: number, bx: number, by: number, bz: number
+      if (tri === 0) { ax = 0; ay = h01 - h00; az = c; bx = c; by = h11 - h00; bz = c }
+      else { ax = c; ay = h11 - h00; az = c; bx = c; by = h10 - h00; bz = 0 }
+      let nx = ay * bz - az * by, ny = az * bx - ax * bz, nz = ax * by - ay * bx
+      const l = Math.hypot(nx, ny, nz) || 1
+      nx /= l; ny /= l; nz /= l
+      return { x: ox + dx * best, y: oy + dy * best, z: oz + dz * best, distance: best, nx, ny, nz }
+    }
+    if (tMaxX < tMaxZ) { t = tMaxX; ix += stepX; tMaxX += tDeltaX }
+    else { t = tMaxZ; iz += stepZ; tMaxZ += tDeltaZ }
+    if (ix < 0 || iz < 0 || ix > g.sizeX - 2 || iz > g.sizeZ - 2) break
+  }
+  return null
+}