lecodes-cli 0.1.6 → 0.2.0

package/runtime/sdk/gl/Node.ts

@@ -0,0 +1,234 @@
+// Base 3D scene node — an empty transform. Mesh and Light extend it, so every node operation works
+// on them. Native (creator-gl) owns the authoritative transform; reads decompose a cached local
+// matrix (re-synced lazily, since physics can write the transform from native each frame).
+//
+// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Collider, …).
+// A GLB import is the Model node kind (with the ModelAnimation aspect). Hierarchy lives here.
+
+import { AspectHost } from "../core/Aspect"
+import { Registry } from "../core/registry"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Quat, cw, type QuatLike } from "../math/quat"
+import { Mat4, type Mat4Like } from "../math/mat4"
+import type { Geometry } from "./Geometry"
+import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+
+/** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
+export const nodeRegistry = new Registry<Node>()
+
+export type NodeEvents = {
+  click: (ev: ClickEvent<Node | null>) => void
+  touchstart: (ev: TouchStartEvent<Node | null>) => void
+  /** A looping GLB animation clip wrapped around. */
+  loopReached: (clip: number) => void
+  /** A non-looping GLB animation clip finished. */
+  completed: (clip: number) => void
+  /** AR anchors only (`scene.root` / `scene.createAnchor()`): the anchor began tracking. */
+  track: () => void
+  /** AR anchors only: the anchor lost tracking. */
+  untrack: () => void
+}
+
+export class Node extends AspectHost<NodeEvents> {
+  /** Native entity handle. */
+  readonly id: number
+
+  /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
+   *  'track' / 'untrack' events; `false` for any non-anchor node. */
+  isTracked = false
+
+  private _matrix?: Float32Array
+  private _lastSync = 0
+  private _worldMatrix?: Float32Array
+  private _scaleCache?: [number, number, number]
+
+  /** @internal — the active animation aspect's clip-complete handler (installed by ModelAnimation). */
+  _animComplete?: (clipIndex: number) => boolean
+
+  constructor(internalId?: number) {
+    super()
+    this.id = internalId ?? _creator.createEntity()
+    nodeRegistry.set(this.id, this)
+  }
+
+  /** Geometry, if this node is a Mesh (used by physics auto-shape). Overridden by Mesh. */
+  get geometry(): Geometry | undefined { return undefined }
+
+  // --- name / visibility ---
+  get name(): string { return _creator.getName(this.id) }
+  set name(value: string) { _creator.setName(this.id, value) }
+  get visible(): boolean { return _creator.isVisible(this.id) }
+  set visible(value: boolean) { _creator.setVisible(this.id, value) }
+
+  // --- local transform ---
+  // Native owns the authoritative matrix; we keep a Float32Array cache (re-synced lazily because physics
+  // can rewrite it each frame). The PUBLIC `matrix` getter hands back a fresh Mat4 *copy* (value
+  // semantics — mutating it never touches the node until you assign it back). `_sync()` is the internal
+  // hot path that returns the cache directly for cheap component reads.
+  private _sync(): Float32Array {
+    if (!this._matrix) this._matrix = new Float32Array(16)
+    if (this._lastSync === 0 || Date.now() - this._lastSync > 10) {
+      _creator.getMatrix(this.id, this._matrix)
+      this._scaleCache = undefined
+      this._lastSync = Date.now()
+    }
+    return this._matrix
+  }
+
+  get matrix(): Mat4 { return new Mat4(this._sync()) }
+  set matrix(m: Mat4Like) {
+    if (!this._matrix) this._matrix = new Float32Array(16)
+    this._matrix.set(matArr(m))
+    this._lastSync = Date.now()
+    _creator.setMatrix(this.id, this._matrix)
+  }
+
+  get worldMatrix(): Mat4 {
+    if (this.parent === null) return this.matrix
+    if (!this._worldMatrix) this._worldMatrix = new Float32Array(16)
+    _creator.getWorldMatrix(this.id, this._worldMatrix)
+    return new Mat4(this._worldMatrix)
+  }
+  set worldMatrix(m: Mat4Like) {
+    if (this.parent === null) { this.matrix = m; return }
+    this._lastSync = 0
+    _creator.setWorldMatrix(this.id, Float32Array.from(matArr(m)))
+  }
+
+  get position(): Vec3 { const m = this._sync(); return new Vec3(m[12], m[13], m[14]) }
+  set position(v: Vec3Like) { this._lastSync = 0; _creator.setPosition(this.id, cx(v), cy(v), cz(v)) }
+
+  // Scalar position accessors — the loud, correct way to nudge one axis (`node.x = 3`), so nobody reaches
+  // for `node.position.x = 3` (a no-op: the getter returns a fresh copy).
+  get x(): number { return this._sync()[12] }
+  set x(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, v, m[13], m[14]) }
+  get y(): number { return this._sync()[13] }
+  set y(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], v, m[14]) }
+  get z(): number { return this._sync()[14] }
+  set z(v: number) { const m = this._sync(); this._lastSync = 0; _creator.setPosition(this.id, m[12], m[13], v) }
+
+  get scale(): Vec3 {
+    if (this._lastSync === 0 || !this._scaleCache) {
+      const m = this._sync()
+      this._scaleCache = [ Math.hypot(m[0], m[1], m[2]), Math.hypot(m[4], m[5], m[6]), Math.hypot(m[8], m[9], m[10]) ]
+    }
+    return new Vec3(this._scaleCache)
+  }
+  set scale(v: Vec3Like | number) {
+    this._lastSync = 0
+    if (typeof v === "number") _creator.setScale(this.id, v, v, v)
+    else _creator.setScale(this.id, cx(v), cy(v), cz(v))
+  }
+
+  get quaternion(): Quat { return new Mat4(this._sync()).rotation }
+  set quaternion(v: QuatLike) { this._lastSync = 0; _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v)) }
+
+  get eulerAngles(): Vec3 { return new Mat4(this._sync()).eulerAngles }
+  set eulerAngles(v: Vec3Like) { this._lastSync = 0; _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 0) }
+
+  // --- world-space reads ---
+  get forward(): Vec3 {
+    const v = new Float32Array(3)
+    _creator.getWorldDirection(this.id, 2, v)
+    return new Vec3(-v[0], -v[1], -v[2])
+  }
+  get worldPosition(): Vec3 {
+    const v = new Float32Array(3)
+    _creator.getWorldPosition(this.id, v)
+    return new Vec3(v[0], v[1], v[2])
+  }
+  get worldScale(): Vec3 { return this.worldMatrix.scaling }
+  get worldQuaternion(): Quat { return this.worldMatrix.rotation }
+  get worldEulerAngles(): Vec3 { return this.worldMatrix.eulerAngles }
+
+  // --- hierarchy ---
+  get parent(): Node | null {
+    const id = _creator.getParent(this.id)
+    return id === 0 ? null : (nodeRegistry.get(id) ?? new Node(id))
+  }
+  get children(): Node[] {
+    return _creator.getChildren(this.id).map((id) => nodeRegistry.get(id) ?? new Node(id))
+  }
+  get childCount(): number { return _creator.getChildCount(this.id) }
+  getChild(index: number): Node | null {
+    const id = _creator.getChild(this.id, index)
+    return id === 0 ? null : (nodeRegistry.get(id) ?? new Node(id))
+  }
+  /** Parent the given nodes under this one. */
+  add(...children: Node[]): this {
+    for (const c of children) _creator.setParent(c.id, this.id, false)
+    return this
+  }
+  setParent(parent: Node | null, worldPositionStays = false): this {
+    if (parent === null) _creator.setParentNull(this.id, worldPositionStays)
+    else _creator.setParent(this.id, parent.id, worldPositionStays)
+    if (worldPositionStays) this._lastSync = 0
+    return this
+  }
+  traverse(callback: (node: Node) => void): void {
+    callback(this)
+    _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
+  }
+
+  // --- behaviors are aspects: node.aspect(Physics, …) / node.aspect(Collider, …) ---
+
+  /** Orient the node so the given axis (default "-z", "forward") points at a world point. */
+  lookAt(point: Vec3Like, mode: "z" | "-z" | "x" | "-x" | "y" | "-y" = "-z", ortho: Vec3Like = [ 0, 1, 0 ]): this {
+    const world = this.worldMatrix
+    const pos = world.position
+    let dir = new Vec3(point).sub(pos)
+    const len = dir.length()
+    if (len === 0) return this
+    let axis: string = mode
+    if (mode.startsWith("-")) { dir = dir.scale(-1 / len); axis = mode.slice(1) }
+    else dir = dir.scale(1 / len)
+
+    const o = new Vec3(ortho)
+    let forward: Vec3, right: Vec3, up: Vec3
+    if (axis === "x") {
+      right = dir; up = o.cross(right).normalize(); forward = up.cross(right).normalize()
+    } else if (axis === "y") {
+      up = dir; right = o.cross(up).normalize(); forward = up.cross(right).normalize()
+    } else {
+      forward = dir; right = o.cross(dir).normalize(); up = dir.cross(right)
+    }
+    const s = world.scaling, w = world.m
+    this.worldMatrix = Float32Array.of(
+      right.x * s.x, right.y * s.x, right.z * s.x, 0,
+      up.x * s.y, up.y * s.y, up.z * s.y, 0,
+      forward.x * s.z, forward.y * s.z, forward.z * s.z, 0,
+      w[12], w[13], w[14], w[15],
+    )
+    return this
+  }
+
+  // --- events ---
+  override addEventListener<K extends keyof NodeEvents>(channel: K, callback: NodeEvents[K]): void {
+    if (channel === "click") registerTouchEndEvent()
+    else if (channel === "touchstart") registerTouchStartEvent()
+    super.addEventListener(channel, callback)
+  }
+
+  /** @internal — called by the touch system to deliver a hit. */
+  _dispatchEvent<K extends keyof NodeEvents>(channel: K, ...args: Parameters<NodeEvents[K]>): void {
+    this.dispatch(channel, ...args)
+  }
+
+  /** @internal — host animation-complete callback; forwards to the ModelAnimation aspect (if any).
+   *  Returns whether the clip should keep playing. */
+  _onAnimationComplete(clipIndex: number): boolean {
+    return this._animComplete?.(clipIndex) ?? true
+  }
+
+  /** @internal — emit a GLB animation event (the ModelAnimation aspect can't reach protected dispatch). */
+  _emitAnim(channel: "loopReached" | "completed", clip: number): void { this.dispatch(channel, clip) }
+
+  destroy(): void {
+    nodeRegistry.delete(this.id)
+    _creator.destroyEntity(this.id)
+  }
+}
+
+/** Read the raw column-major elements out of a Mat4 wrapper or a plain length-16 array. */
+const matArr = (m: Mat4Like): ArrayLike<number> => (m as { m?: ArrayLike<number> }).m ?? (m as ArrayLike<number>)

package/runtime/sdk/gl/Noise.ts

@@ -0,0 +1,30 @@
+// Native FastNoise (Perlin/fractal) sampler. Ported from worker/src/utils/PerlinNoise.ts.
+
+export class Noise {
+  private readonly _id: number
+
+  constructor() {
+    this._id = _creator.createNoise()
+  }
+
+  /** Sample 2D noise. */
+  get(x: number, y: number): number { return _creator.getNoise2D(this._id, x, y) }
+  /** Sample 3D noise. */
+  get3d(x: number, y: number, z: number): number { return _creator.getNoise3D(this._id, x, y, z) }
+
+  private _frequency = 0.01
+  get frequency(): number { return this._frequency }
+  set frequency(v: number) { this._frequency = v; _creator.setNoiseFrequency(this._id, v) }
+
+  private _octaves = 1
+  get octaves(): number { return this._octaves }
+  set octaves(v: number) { this._octaves = v; _creator.setNoiseOctaves(this._id, v) }
+
+  private _fractalLacunarity = 2
+  get fractalLacunarity(): number { return this._fractalLacunarity }
+  set fractalLacunarity(v: number) { this._fractalLacunarity = v; _creator.setNoiseFractalLunacrity(this._id, v) }
+
+  private _fractalGain = 0.5
+  get fractalGain(): number { return this._fractalGain }
+  set fractalGain(v: number) { this._fractalGain = v; _creator.setNoiseFractalGain(this._id, v) }
+}

package/runtime/sdk/gl/Particles.ts

@@ -0,0 +1,185 @@
+// GPU particle system, as a Node. Created with a material; properties drive the native emitter.
+// Ported from worker/src/components/Particles.ts — folded into the node, so (unlike the worker
+// component) the system exists at construction and setters apply immediately.
+
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Material } from "./Material"
+import { Node } from "./Node"
+
+type Range<T> = T | { min: T, max: T }
+
+type VelocityValue = {
+  speed?: Range<number>
+  randomizeAngle?: { min: Vec3Like, max: Vec3Like }
+} & ({ from: Vec3Like } | { to: Vec3Like } | { dir: Vec3Like } | {})
+
+export type DynamicValue =
+  | Range<number>
+  | { value?: Range<number>, inc?: Float32Array, inc_b?: Float32Array, mul?: Float32Array, mul_b?: Float32Array }
+
+export type DynamicColor =
+  | Range<string>
+  | { value?: Range<string>, mul: string, mul_b?: string, t: Float32Array }
+
+type Shape = { type: "point", v: Vec3Like } | { type: "box", min: Vec3Like, max: Vec3Like }
+type Noise = { strength?: number, frequency?: number, speed?: number }
+
+export type ParticlesOptions = {
+  material: Material
+  rate?: Range<number>
+  shape?: Shape
+  startVelocity?: Vec3Like | VelocityValue
+  gravity?: number
+  drag?: number
+  lifetime?: Range<number>
+  color?: DynamicColor
+  size?: DynamicValue
+  rotation?: DynamicValue
+  noise?: Noise | null
+}
+
+export class Particles extends Node {
+  private _material: Material
+
+  /** Custom curve params (slots 0..3); size/rotation alias slots 0/1. */
+  readonly custom: DynamicValue[]
+
+  constructor(options: ParticlesOptions) {
+    super()
+    this._material = options.material
+    _creator.createParticleSystem(this.id, Material.idOf(options.material))
+
+    const id = this.id
+    this.custom = new Proxy([] as DynamicValue[], {
+      set(target, prop: string, value: DynamicValue) {
+        const i = parseInt(prop)
+        if (Number.isNaN(i)) { (target as any)[prop] = value; return true }
+        target[i] = value
+        applyParam(id, i, value)
+        return true
+      },
+    })
+
+    if (options.rate !== undefined) this.rate = options.rate
+    if (options.shape !== undefined) this.shape = options.shape
+    if (options.startVelocity !== undefined) this.startVelocity = options.startVelocity
+    if (options.gravity !== undefined) this.gravity = options.gravity
+    if (options.drag !== undefined) this.drag = options.drag
+    if (options.lifetime !== undefined) this.lifetime = options.lifetime
+    if (options.color !== undefined) this.color = options.color
+    if (options.size !== undefined) this.custom[0] = options.size
+    if (options.rotation !== undefined) this.custom[1] = options.rotation
+    if (options.noise) this.noise = options.noise
+  }
+
+  /** Emit `count` particles immediately (a burst). */
+  spawn(count: number): this { _creator.spawnParticles(this.id, count); return this }
+
+  set rate(val: Range<number>) {
+    if (typeof val === "number") _creator.setParticleSystemRateValue(this.id, val)
+  }
+
+  set shape(shape: Shape) {
+    if (shape.type === "point") _creator.setParticleSystemShapePoint(this.id, cx(shape.v), cy(shape.v), cz(shape.v))
+    else _creator.setParticleSystemShapeBox(this.id, cx(shape.min), cy(shape.min), cz(shape.min), cx(shape.max), cy(shape.max), cz(shape.max))
+  }
+
+  set startVelocity(val: Vec3Like | VelocityValue) {
+    if (Array.isArray(val) || val instanceof Float32Array || val instanceof Vec3) {
+      _creator.setParticleSystemVelocityValue(this.id, 1, cx(val), cy(val), cz(val))
+      return
+    }
+    const v = val as VelocityValue
+    if ("from" in v) _creator.setParticleSystemVelocityValue(this.id, 2, cx(v.from), cy(v.from), cz(v.from))
+    else if ("to" in v) _creator.setParticleSystemVelocityValue(this.id, 3, cx(v.to), cy(v.to), cz(v.to))
+    else if ("dir" in v) _creator.setParticleSystemVelocityValue(this.id, 1, cx(v.dir), cy(v.dir), cz(v.dir))
+    else _creator.setParticleSystemVelocityValue(this.id, 0, 0, 0, 0)
+    if ("speed" in v && v.speed !== undefined) {
+      if (typeof v.speed === "number") _creator.setParticleSystemVelocitySpeedValue(this.id, v.speed)
+      else _creator.setParticleSystemVelocitySpeedRange(this.id, v.speed.min, v.speed.max)
+    }
+    if (v.randomizeAngle) {
+      const a = v.randomizeAngle
+      _creator.setParticleSystemVelocityRndAngle(this.id, cx(a.min), cy(a.min), cz(a.min), cx(a.max), cy(a.max), cz(a.max))
+    }
+  }
+
+  set gravity(val: number) { _creator.setParticleSystemGravityValue(this.id, val) }
+  set drag(val: number) { _creator.setParticleSystemDragValue(this.id, val) }
+
+  set lifetime(val: Range<number>) {
+    if (typeof val === "number") _creator.setParticleSystemLifetimeValue(this.id, val)
+    else _creator.setParticleSystemLifetimeRange(this.id, val.min, val.max)
+  }
+
+  set size(val: DynamicValue) { this.custom[0] = val }
+  set rotation(val: DynamicValue) { this.custom[1] = val }
+
+  set color(value: DynamicColor) {
+    if (typeof value === "string") _creator.setParticleSystemColorValue(this.id, value)
+    else if ("min" in value) _creator.setParticleSystemColorRange(this.id, value.min, value.max)
+    else {
+      if (typeof value.value === "string") _creator.setParticleSystemColorValue(this.id, value.value)
+      else if (value.value) _creator.setParticleSystemColorRange(this.id, value.value.min, value.value.max)
+      if (value.mul) _creator.setParticleSystemColorCurveA(this.id, value.mul, value.t)
+      if (value.mul_b) _creator.setParticleSystemColorCurveB(this.id, value.mul_b, value.t)
+    }
+  }
+
+  get material(): Material { return this._material }
+  set material(material: Material) {
+    this._material = material
+    _creator.setMaterial(this.id, Material.idOf(material), 0)
+  }
+
+  set noise(noise: Noise | null) {
+    if (noise) _creator.setParticleSystemNoise(this.id, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1)
+    else _creator.disableParticleSystemNoise(this.id)
+  }
+}
+
+const applyParam = (id: number, i: number, value: DynamicValue): void => {
+  if (typeof value === "number") {
+    _creator.setParticleSystemParamValue(id, i, value)
+  } else if ("min" in value) {
+    _creator.setParticleSystemParamRange(id, i, value.min, value.max)
+  } else {
+    if (typeof value.value === "number") _creator.setParticleSystemParamValue(id, i, value.value)
+    else if (value.value) _creator.setParticleSystemParamRange(id, i, value.value.min, value.value.max)
+    if (value.inc) _creator.setParticleSystemParamCurveA(id, i, value.inc, 1)
+    if (value.inc_b) _creator.setParticleSystemParamCurveB(id, i, value.inc_b)
+    if (value.mul) _creator.setParticleSystemParamCurveA(id, i, value.mul, 0)
+    if (value.mul_b) _creator.setParticleSystemParamCurveB(id, i, value.mul_b)
+  }
+}
+
+// --- curve builders (unchanged from worker) ---
+
+export const dynamicColor = (baseValue: Range<string>, ...args: (number | string | { min: string, max: string })[]): DynamicColor => {
+  const t = new Float32Array(args.length / 2)
+  const mul: string[] = []
+  let mul_b: string[] | undefined
+  for (let i = 0; i < args.length / 2; i++) {
+    if (typeof args[i * 2] !== "number") throw new Error(`dynamicColor: arg ${i * 2} must be a number`)
+    t[i] = args[i * 2] as number
+    const val = args[i * 2 + 1]
+    if (typeof val === "string") { mul[i] = val; if (mul_b) mul_b[i] = val }
+    else if (typeof val === "number") throw new Error(`dynamicColor: arg ${i * 2 + 1} must be a string`)
+    else { mul[i] = val.min; if (!mul_b) mul_b = [ ...mul ]; mul_b[i] = val.max }
+  }
+  return { value: baseValue, mul: mul.join("\0"), mul_b: mul_b?.join("\0"), t }
+}
+
+export const dynamic = (baseValue: Range<number>, type: "multiply" | "inc", ...args: (number | { min: number, max: number })[]): DynamicValue => {
+  const inc = new Float32Array(args.length)
+  let inc_b: Float32Array | undefined
+  for (let i = 0; i < args.length; i += 2) {
+    if (typeof args[i] !== "number") throw new Error(`dynamic: arg ${i} must be a number`)
+    inc[i] = args[i] as number
+    if (inc_b) inc_b[i] = args[i] as number
+    const val = args[i + 1]
+    if (typeof val === "number") { inc[i + 1] = val; if (inc_b) inc_b[i + 1] = val }
+    else { inc[i + 1] = val.min; if (!inc_b) inc_b = new Float32Array(inc); inc_b[i + 1] = val.max }
+  }
+  return type === "inc" ? { value: baseValue, inc, inc_b } : { value: baseValue, mul: inc, mul_b: inc_b }
+}

package/runtime/sdk/gl/Physics.ts

@@ -0,0 +1,95 @@
+// Physics body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl.
+//   node.aspect(Physics, { motion: 'dynamic' });  node.physics.applyImpulse([0, 6, 0])
+//
+// For a `dynamic` body, physics OWNS the transform — do NOT set node.position per frame; drive it
+// via velocity / applyImpulse. Reading node.position is free (native already wrote it). Kinematic
+// bodies are driven with moveTo. (Ported from the former Body class.)
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+
+export type MotionType = "static" | "dynamic" | "kinematic"
+const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
+
+export type BodyShape =
+  | { type: "auto" }
+  | { type: "box", halfExtents: Vec3Like }
+  | { type: "sphere", radius: number }
+  | { type: "cylinder", halfHeight: number, radius: number }
+
+export class Physics extends Aspect<"physics", Node> {
+  static readonly aspect = "physics"
+
+  /** Default "dynamic". */
+  motion: MotionType = "dynamic"
+  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+  mass = 1
+  /** Default { type: "auto" } — a box from the mesh AABB × world scale. */
+  shape: BodyShape = { type: "auto" }
+
+  private _bodyId = 0
+
+  onAttach(): void {
+    // No physics in this build (CREATOR_GL_PHYSICS=OFF) → bodyId stays 0; all methods no-op.
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const motion = MOTION[this.motion]
+    const shape = resolveShape(this.node, this.shape)
+    if (shape.type === "sphere") {
+      this._bodyId = _creator.physicsCreateSphere(this.node.id, shape.radius, motion, this.mass)
+    } else if (shape.type === "cylinder") {
+      this._bodyId = _creator.physicsCreateCylinder(this.node.id, shape.halfHeight, shape.radius, motion, this.mass)
+    } else {
+      this._bodyId = _creator.physicsCreateBox(this.node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, this.mass)
+    }
+  }
+
+  /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
+  get id(): number { return this._bodyId }
+
+  /** Linear velocity in world units/second (fresh Vec3 on read). */
+  get velocity(): Vec3 {
+    const out = new Float32Array(3)
+    if (this._bodyId) _creator.physicsGetLinearVelocity(this._bodyId, out)
+    return new Vec3(out[0], out[1], out[2])
+  }
+  set velocity(v: Vec3Like) {
+    if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v))
+  }
+
+  /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
+  applyImpulse(v: Vec3Like): this {
+    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
+    return this
+  }
+
+  /** Teleport / drive a kinematic (or dynamic) body to a world position. */
+  moveTo(p: Vec3Like): this {
+    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p))
+    return this
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+  }
+}
+
+// Resolve "auto" to a box from the mesh AABB × world scale (so the physical box matches the rendered
+// size). Falls back to a unit box if there is no geometry.
+const resolveShape = (node: Node, shape: BodyShape): Exclude<BodyShape, { type: "auto" }> => {
+  if (shape.type !== "auto") return shape
+  const scale = node.worldScale
+  let hx = 0.5, hy = 0.5, hz = 0.5
+  const geom = node.geometry
+  if (geom) {
+    const v = geom.vertices
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity
+    for (let i = 0; i + 2 < v.length; i += 3) {
+      if (v[i] < minX) minX = v[i]; if (v[i] > maxX) maxX = v[i]
+      if (v[i + 1] < minY) minY = v[i + 1]; if (v[i + 1] > maxY) maxY = v[i + 1]
+      if (v[i + 2] < minZ) minZ = v[i + 2]; if (v[i + 2] > maxZ) maxZ = v[i + 2]
+    }
+    hx = (maxX - minX) * 0.5; hy = (maxY - minY) * 0.5; hz = (maxZ - minZ) * 0.5
+  }
+  return { type: "box", halfExtents: [ hx * scale.x, hy * scale.y, hz * scale.z ] }
+}

package/runtime/sdk/gl/Plane.ts

@@ -0,0 +1,53 @@
+// A geometric plane (point + normal) with ray intersection. Ported from worker/src/utils/Plane.ts
+// onto the SDK's fluent Vec3 (the mat4 transform() method is omitted — add if needed).
+
+import { Vec3, type Vec3Like } from "../math/vec"
+import type { Ray } from "./Ray"
+
+export class Plane {
+  /** Unit normal. */
+  readonly normal: Vec3
+  /** Scalar offset: dot(normal, point). */
+  readonly d: number
+
+  constructor(normal: Vec3Like, point: Vec3Like) {
+    this.normal = new Vec3(normal).normalize()
+    this.d = this.normal.dot(point)
+  }
+
+  static fromPoints(a: Vec3Like, b: Vec3Like, c: Vec3Like): Plane {
+    const A = new Vec3(a)
+    return new Plane(new Vec3(b).sub(A).cross(new Vec3(c).sub(A)), a)
+  }
+
+  static fromCoefficients(a: number, b: number, c: number, d: number): Plane {
+    const len = Math.hypot(a, b, c)
+    const l2 = len * len
+    return new Plane([ a, b, c ], [ (a * d) / l2, (b * d) / l2, (c * d) / l2 ])
+  }
+
+  /** Ray-plane parameter t (≥0), or null on a miss (parallel / behind origin). */
+  intersectRay(ray: Ray): number | null {
+    const denom = this.normal.dot(ray.dir)
+    if (Math.abs(denom) < 1e-8) return null
+    const t = (this.d - this.normal.dot(ray.origin)) / denom
+    return t < 0 ? null : t
+  }
+
+  /** Like intersectRay but allows hits behind the origin (line-plane). */
+  intersectLine(ray: Ray): number | null {
+    const denom = this.normal.dot(ray.dir)
+    if (Math.abs(denom) < 1e-8) return null
+    return (this.d - this.normal.dot(ray.origin)) / denom
+  }
+
+  /** Signed distance from a point (positive on the normal's side). */
+  signedDistance(point: Vec3Like): number {
+    return this.normal.dot(point) - this.d
+  }
+
+  /** Project a point onto the plane. */
+  projectPoint(point: Vec3Like): Vec3 {
+    return new Vec3(point).scaleAndAdd(this.normal, -this.signedDistance(point))
+  }
+}

package/runtime/sdk/gl/Ray.ts

@@ -0,0 +1,16 @@
+// A ray defined by an origin and a (not necessarily normalized) direction.
+
+import { Vec3, type Vec3Like } from "../math/vec"
+
+export class Ray {
+  readonly origin: Vec3
+  readonly dir: Vec3
+
+  constructor(origin: Vec3Like, dir: Vec3Like) {
+    this.origin = new Vec3(origin)
+    this.dir = new Vec3(dir)
+  }
+
+  /** The world-space point origin + t·dir. */
+  getPoint(t: number): Vec3 { return this.origin.scaleAndAdd(this.dir, t) }
+}