lecodes-cli 0.17.0 → 0.17.2

package/runtime/sdk/gl/Particles.ts

@@ -12,6 +12,7 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Geometry } from "./Geometry"
 import { Material, _sheetColsRows, type ParticlesMaterialOptions } from "./Material"
 import { Node } from "./Node"
 
@@ -34,6 +35,11 @@ const TAG_SPACE = 12
 const TAG_INHERIT_VELOCITY = 13
 const TAG_RATE_DISTANCE = 14
 const TAG_RENDER_MODE = 15
+const TAG_MESH_GEOMETRY = 16
+const TAG_ANGULAR_VELOCITY = 17
+const TAG_GROUND = 18
+const TAG_VELOCITY_LIFE = 19
+const TAG_ORDER = 20
 
 /** @internal — exported for the tag-sync test only. */
 export const _particleTags = {
@@ -41,7 +47,9 @@ export const _particleTags = {
   VELOCITY_RND: TAG_VELOCITY_RND, ACCELERATION: TAG_ACCELERATION, DRAG: TAG_DRAG,
   NOISE: TAG_NOISE, SEED: TAG_SEED, PARAM_CURVE: TAG_PARAM_CURVE, COLOR_CURVE: TAG_COLOR_CURVE,
   SPACE: TAG_SPACE, INHERIT_VELOCITY: TAG_INHERIT_VELOCITY, RATE_DISTANCE: TAG_RATE_DISTANCE,
-  RENDER_MODE: TAG_RENDER_MODE,
+  RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
+  ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
+  ORDER: TAG_ORDER,
 }
 
 // --- curve builders -----------------------------------------------------------------------------
@@ -206,13 +214,51 @@ type VelocityValue = {
   randomizeAngle?: { min: Vec3Like, max: Vec3Like }
 } & ({ from: Vec3Like } | { to: Vec3Like } | { dir: Vec3Like } | {})
 
+/** Where particles are born, in emitter space. Sphere / hemisphere / cone have an axis of +Y (the
+ *  hemisphere is the +Y half, the cone opens along +Y from its base disc at `center`) — aim the
+ *  node with `lookAt(target, 'y')`. `thickness` 0 emits from the surface only, 1 (default) from the
+ *  whole volume. A sphere or cone also sets the LAUNCH DIRECTION (outward / from the cone's apex)
+ *  when `startVelocity` gives a speed but no direction, like Unity's shapes. */
 type Shape =
   | { type: "point", v: Vec3Like }
   | { type: "box", min: Vec3Like, max: Vec3Like }
   | { type: "circle", center: Vec3Like, radius: number }
+  | { type: "sphere", center?: Vec3Like, radius: number, thickness?: number }
+  | { type: "hemisphere", center?: Vec3Like, radius: number, thickness?: number }
+  | { type: "cone", center?: Vec3Like, radius: number, /** half-angle, radians */ angle?: number, /** emit this far up the axis too */ length?: number, thickness?: number }
+/** Extra velocity over each particle's life — evaluated from the curves every frame and ADDED as a
+ *  displacement (not accumulated like `acceleration`): `radial` pushes outward along the particle's
+ *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
+ *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
+export type VelocityOverLife = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue, z?: ParticleValue }
 type Noise = { strength?: number, frequency?: number, speed?: number }
 
+/** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
+ *  world y with `space: 'world'`, emitter-local y otherwise. */
+export type ParticleGround = {
+  /** Plane height (default 0). */
+  height?: number
+  /** Contact radius — particles stop `radius` above the plane (a mesh's half-extent; default 0). */
+  radius?: number
+  /** Fraction of the vertical speed kept on impact, 0..1 (default 0.3). */
+  bounce?: number
+  /** Tangential damping while in contact, per second — like `drag` (default 8). */
+  friction?: number
+}
+
 export type ParticlesOptions = ParticlesMaterialOptions & {
+  /** Draw every particle as this mesh — lit, tumbling 3D debris (shell casings, rubble, leaves,
+   *  shrapnel) in one draw call. The system switches to the mesh render mode; the default
+   *  material becomes `Material.lit()` (pass `material` for color/roughness/metallic — the
+   *  sprite look options are ignored). `size` scales the mesh (default 1); `rotation`/`opacity`/
+   *  `frame` don't apply. See `angularVelocity` and `ground`. */
+  mesh?: Geometry
+  /** (mesh) Spin, radians per second about the particle's own axes — a vector, or a per-component
+   *  `{ min, max }` range randomized at spawn. Particles are born in the emitter's orientation. */
+  angularVelocity?: Vec3Like | { min: Vec3Like, max: Vec3Like }
+  /** A ground plane the particles bounce on and come to rest on (any render mode); `null`
+   *  disables it. */
+  ground?: ParticleGround | null
   /** Custom draw material. Unset = the default point-sprite material, configured by the
    *  `ParticlesMaterialOptions` sugar (map/sheet/emissive/blend/soft) — which is ignored
    *  when an explicit material is passed. */
@@ -232,7 +278,14 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
    *  Meant for `space: 'world'`. */
   rateOverDistance?: number
+  /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
+   *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
+   *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
+   *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
+  order?: number
   shape?: Shape
+  /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
+  velocityOverLife?: VelocityOverLife
   startVelocity?: Vec3Like | VelocityValue
   /** Downward acceleration, world units/s² — positive pulls particles DOWN (sugar for
    *  `acceleration: [0, -g, 0]`). */
@@ -293,10 +346,54 @@ const pushColor = (out: number[], value: ParticleColor): void => {
   for (let i = 0; i < d.length; i++) out.push(d[i])
 }
 
+const pushMesh = (out: number[], g: Geometry): void => {
+  const nv = g.vertices.length / 3
+  const ni = g.indices.length
+  out.push(TAG_MESH_GEOMETRY, 2 + nv * 8 + ni, nv, ni)
+  for (let i = 0; i < nv * 3; i++) out.push(g.vertices[i])
+  for (let i = 0; i < nv * 3; i++) out.push(g.normals[i])
+  for (let i = 0; i < nv * 2; i++) out.push(g.uv[i])
+  for (let i = 0; i < ni; i++) out.push(g.indices[i])
+}
+
+const pushAngularVelocity = (out: number[], v: Vec3Like | { min: Vec3Like, max: Vec3Like }): void => {
+  const r = v as { min: Vec3Like, max: Vec3Like }
+  if (typeof r === "object" && r !== null && !Array.isArray(r) && "min" in r && !(v instanceof Float32Array) && !(v instanceof Vec3)) {
+    out.push(TAG_ANGULAR_VELOCITY, 6, cx(r.min), cy(r.min), cz(r.min), cx(r.max), cy(r.max), cz(r.max))
+  } else {
+    const a = v as Vec3Like
+    out.push(TAG_ANGULAR_VELOCITY, 6, cx(a), cy(a), cz(a), cx(a), cy(a), cz(a))
+  }
+}
+
+const pushGround = (out: number[], g: ParticleGround | null): void => {
+  if (g === null) out.push(TAG_GROUND, 5, 0, 0, 0, 0, 0)
+  else out.push(TAG_GROUND, 5, 1, g.height ?? 0, g.radius ?? 0, g.bounce ?? 0.3, g.friction ?? 8)
+}
+
 const pushShape = (out: number[], shape: Shape): void => {
   if (shape.type === "point") out.push(TAG_SHAPE, 4, 0, cx(shape.v), cy(shape.v), cz(shape.v))
   else if (shape.type === "box") out.push(TAG_SHAPE, 7, 1, cx(shape.min), cy(shape.min), cz(shape.min), cx(shape.max), cy(shape.max), cz(shape.max))
-  else out.push(TAG_SHAPE, 5, 2, cx(shape.center), cy(shape.center), cz(shape.center), shape.radius)
+  else if (shape.type === "circle") out.push(TAG_SHAPE, 5, 2, cx(shape.center), cy(shape.center), cz(shape.center), shape.radius)
+  else {
+    const c = shape.center ?? [ 0, 0, 0 ]
+    const thickness = shape.thickness ?? 1
+    if (shape.type === "cone") out.push(TAG_SHAPE, 8, 5, cx(c), cy(c), cz(c), shape.radius, shape.angle ?? 0, shape.length ?? 0, thickness)
+    else out.push(TAG_SHAPE, 6, shape.type === "sphere" ? 3 : 4, cx(c), cy(c), cz(c), shape.radius, thickness)
+  }
+}
+
+const pushVelocityLife = (out: number[], v: VelocityOverLife): void => {
+  const axes: Array<[number, ParticleValue | undefined]> = [ [ 0, v.radial ], [ 1, v.x ], [ 2, v.y ], [ 3, v.z ] ]
+  for (const [ axis, value ] of axes) {
+    if (value === undefined) continue
+    if (typeof value === "number") out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value, value, 0)
+    else if (hasData(value)) {
+      const d = value._data
+      out.push(TAG_VELOCITY_LIFE, d.length + 1, axis)
+      for (let i = 0; i < d.length; i++) out.push(d[i])
+    } else out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value.min, value.max, 0)
+  }
 }
 
 const pushVelocity = (out: number[], val: Vec3Like | VelocityValue): void => {
@@ -338,7 +435,7 @@ export class Particles extends Node {
 
   constructor(options: ParticlesOptions = {}) {
     super()
-    this._material = options.material ?? Material.particles(options)
+    this._material = options.material ?? (options.mesh ? Material.lit() : Material.particles(options))
     _creator.createParticleSystem(this.id, Material.idOf(this._material), options.maxParticles ?? 0)
 
     const id = this.id
@@ -355,14 +452,21 @@ export class Particles extends Node {
     })
 
     const out: number[] = []
-    if (options.render !== undefined && options.render !== "point") {
+    if (options.mesh) {
+      out.push(TAG_RENDER_MODE, 1, 3)
+      pushMesh(out, options.mesh)
+    } else if (options.render !== undefined && options.render !== "point") {
       out.push(TAG_RENDER_MODE, 1, options.render === "ribbon" ? 2 : 1)
     }
+    if (options.angularVelocity !== undefined) pushAngularVelocity(out, options.angularVelocity)
+    if (options.ground !== undefined) pushGround(out, options.ground)
     if (options.space !== undefined) out.push(TAG_SPACE, 1, options.space === "world" ? 1 : 0)
     if (options.inheritVelocity !== undefined) out.push(TAG_INHERIT_VELOCITY, 1, options.inheritVelocity)
     if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
+    if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
     if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
     if (options.shape !== undefined) pushShape(out, options.shape)
+    if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
     if (options.startVelocity !== undefined) pushVelocity(out, options.startVelocity)
     if (options.acceleration !== undefined) {
       const a = options.acceleration
@@ -381,7 +485,7 @@ export class Particles extends Node {
     if (options.opacity !== undefined) pushParam(out, 2, options.opacity)
     if (options.frame !== undefined) {
       pushParam(out, 3, options.frame)
-    } else if (options.material === undefined) {
+    } else if (options.material === undefined && !options.mesh) {
       const [ cols, rows ] = _sheetColsRows(options.sheet)
       const frames = cols * rows
       if (frames > 1) {
@@ -412,6 +516,13 @@ export class Particles extends Node {
   set space(val: "local" | "world") { this._send([ TAG_SPACE, 1, val === "world" ? 1 : 0 ]) }
   set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
   set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
+  set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+
+  set velocityOverLife(v: VelocityOverLife) {
+    const out: number[] = []
+    pushVelocityLife(out, v)
+    this._send(out)
+  }
 
   set shape(shape: Shape) {
     const out: number[] = []
@@ -419,6 +530,25 @@ export class Particles extends Node {
     this._send(out)
   }
 
+  /** (mesh mode) Replace the particle mesh; live particles keep flying as the new shape. */
+  set mesh(g: Geometry) {
+    const out: number[] = [ TAG_RENDER_MODE, 1, 3 ]
+    pushMesh(out, g)
+    this._send(out)
+  }
+
+  set angularVelocity(v: Vec3Like | { min: Vec3Like, max: Vec3Like }) {
+    const out: number[] = []
+    pushAngularVelocity(out, v)
+    this._send(out)
+  }
+
+  set ground(g: ParticleGround | null) {
+    const out: number[] = []
+    pushGround(out, g)
+    this._send(out)
+  }
+
   set startVelocity(val: Vec3Like | VelocityValue) {
     const out: number[] = []
     pushVelocity(out, val)

package/runtime/sdk/gl/Physics.ts

@@ -1,119 +1,126 @@
-// Rigid body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl. Requires a Shape
-// aspect on the same node (its geometry becomes the body's collision shape).
-//
-//   Physics.configure({ gravity: [0, -9.81, 0] })          // once, before creating bodies
-//   ground.aspect(Shape, { box: [20, 0.5, 20] }).aspect(Physics, { motion: 'static' })
-//   crate.aspect(Shape, {}).aspect(Physics, { mass: 2 })   // auto box from the mesh
-//   crate.physics.applyImpulse([0, 6, 0])
-//   crate.addEventListener('enter', other => …)            // contact / trigger overlap began
-//
-// 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.
-
-import { Aspect } from "../core/Aspect"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { nodeRegistry, type Node } from "./Node"
-import { Shape } from "./Shape"
-
-export type MotionType = "static" | "dynamic" | "kinematic"
-const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
-
-export interface PhysicsConfig {
-  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
-  gravity?: Vec3Like
-  /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
-  maxBodies?: number
-}
-
-/** Closest raycast hit. */
-export interface RayHit {
-  node: Node | null
-  point: Vec3
-  normal: Vec3
-  fraction: number
-}
-
-export class Physics extends Aspect<"physics", Node> {
-  static readonly aspect = "physics"
-
-  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
-   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
-   *  smoothness — bodies then advance in discrete steps. */
-  private static _interpolation = true
-  static get interpolation(): boolean { return Physics._interpolation }
-  static set interpolation(on: boolean) { Physics._interpolation = on; _creator.setInterpolation(on) }
-
-  /** Default "dynamic". */
-  motion: MotionType = "dynamic"
-  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
-  mass = 1
-
-  private _bodyId = 0
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
-    }
-    const shapeId = shape._claim() // drop the pick-only body; reuse its shape
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
-    shape._ownBody(this._bodyId)
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    this.node.get(Shape)?._recreatePickBody() // keep the node pickable if the Shape stays
-  }
-
-  /** 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
-  }
-
-  // --- world (static) -------------------------------------------------------------------------
-  /** Configure gravity / limits. Call once before creating bodies. */
-  static configure(config: PhysicsConfig = {}): void {
-    const g = config.gravity ?? [0, -9.81, 0]
-    _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
-  }
-
-  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
-  static get supported(): boolean {
-    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
-  }
-
-  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
-  static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
-    const out = new Float32Array(7)
-    const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
-    if (!id) return null
-    return {
-      node: nodeRegistry.get(id) ?? null,
-      point: new Vec3(out[0], out[1], out[2]),
-      normal: new Vec3(out[3], out[4], out[5]),
-      fraction: out[6],
-    }
-  }
-}
+// Rigid body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl. Requires a Shape
+// aspect on the same node (its geometry becomes the body's collision shape).
+//
+//   Physics.configure({ gravity: [0, -9.81, 0] })          // once, before creating bodies
+//   ground.aspect(Shape, { box: [20, 0.5, 20] }).aspect(Physics, { motion: 'static' })
+//   crate.aspect(Shape, {}).aspect(Physics, { mass: 2 })   // auto box from the mesh
+//   crate.physics.applyImpulse([0, 6, 0])
+//   crate.addEventListener('enter', other => …)            // contact / trigger overlap began
+//
+// 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.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import { nodeRegistry, type Node } from "./Node"
+import { Shape } from "./Shape"
+
+export type MotionType = "static" | "dynamic" | "kinematic"
+const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
+
+export interface PhysicsConfig {
+  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
+  gravity?: Vec3Like
+  /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
+  maxBodies?: number
+}
+
+/** Closest raycast hit. */
+export interface RayHit {
+  node: Node | null
+  point: Vec3
+  normal: Vec3
+  fraction: number
+}
+
+export class Physics extends Aspect<"physics", Node> {
+  static readonly aspect = "physics"
+
+  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
+   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
+   *  smoothness — bodies then advance in discrete steps. */
+  private static _interpolation = true
+  static get interpolation(): boolean { return Physics._interpolation }
+  static set interpolation(on: boolean) { Physics._interpolation = on; _creator.setInterpolation(on) }
+
+  /** Default "dynamic". */
+  motion: MotionType = "dynamic"
+  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+  mass = 1
+
+  private _bodyId = 0
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
+    }
+    if (this.motion === "dynamic" && shape._isTriangleMesh) {
+      throw new Error("Physics: a dynamic body cannot use Shape { mesh: true } (triangle meshes are static/kinematic only) — use { mesh: 'convex' } or a primitive shape")
+    }
+    const shapeId = shape._claim() // drop the pick-only body; reuse its shape
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    shape._ownBody(this._bodyId)
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()  // keep the node pickable if the Shape stays
+    }
+  }
+
+  /** 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
+  }
+
+  // --- world (static) -------------------------------------------------------------------------
+  /** Configure gravity / limits. Call once before creating bodies. */
+  static configure(config: PhysicsConfig = {}): void {
+    const g = config.gravity ?? [0, -9.81, 0]
+    _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
+  }
+
+  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
+  static get supported(): boolean {
+    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
+  }
+
+  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+  static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
+    const out = new Float32Array(7)
+    const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
+    if (!id) return null
+    return {
+      node: nodeRegistry.get(id) ?? null,
+      point: new Vec3(out[0], out[1], out[2]),
+      normal: new Vec3(out[3], out[4], out[5]),
+      fraction: out[6],
+    }
+  }
+}