lecodes-cli 0.1.6 → 0.1.7

package/runtime/sdk/g2/Texture2D.ts

@@ -0,0 +1,37 @@
+// A GPU texture decoded natively by creator-2d (stb_image). Load from a URL (or an already-fetched
+// response); the raw file bytes are handed to the engine, which decodes + uploads them.
+
+// Internal SDK code imports injected globals explicitly (the bare-global inject is only for USER
+// code; here `fetch` would otherwise resolve to the node/bun ambient one).
+import { fetch, type FetchResponse } from "../runtime/fetch"
+
+export class Texture2D {
+  /** Native texture handle. */
+  readonly id: number
+  readonly width: number
+  readonly height: number
+
+  constructor(id: number, width: number, height: number) {
+    this.id = id
+    this.width = width
+    this.height = height
+  }
+
+  static load(source: string | FetchResponse): Promise<Texture2D> {
+    if (typeof source === "string") {
+      return fetch(source, { useOnce: true }).then((resp) => {
+        if (resp.status >= 400) {
+          return Promise.reject(new Error(`Failed to fetch texture from ${source}. HTTP ${resp.status}`))
+        }
+        return Texture2D.load(resp)
+      })
+    }
+    return new Promise<Texture2D>((resolve, reject) => {
+      _creator2d.createTexture((source as any).id ?? (source as any)._id, (id, w, h) => resolve(new Texture2D(id, w, h)), reject)
+    })
+  }
+
+  destroy(): void {
+    _creator2d.destroyTexture(this.id)
+  }
+}

package/runtime/sdk/g2/Tilemap.ts

@@ -0,0 +1,41 @@
+// A tilemap node. The grid is uploaded once and rendered natively with per-frame view culling; the
+// node's position is the bottom-left of the map. Edit cells with setTile.
+
+import { Node2D } from "./Node2D"
+import type { Texture2D } from "./Texture2D"
+
+export type TilemapOptions = {
+  texture: Texture2D
+  /** Map grid size (in tiles). */
+  cols: number
+  rows: number
+  /** On-screen cell size in world units — a single number (square) or [w, h]. */
+  tile: number | [number, number]
+  /** Atlas grid: how the texture is sliced into tiles, [atlasCols, atlasRows]. */
+  atlas: [number, number]
+  /** Row-major tile indices into the atlas (-1 = empty), length cols*rows. Row 0 is the top row. */
+  data: number[] | Int32Array
+}
+
+export class Tilemap extends Node2D {
+  readonly cols: number
+  readonly rows: number
+
+  constructor(options: TilemapOptions) {
+    const data = options.data instanceof Int32Array ? options.data : Int32Array.from(options.data)
+    const tileW = typeof options.tile === "number" ? options.tile : options.tile[0]
+    const tileH = typeof options.tile === "number" ? options.tile : options.tile[1]
+    const [ atlasCols, atlasRows ] = options.atlas
+    const id = _creator2d.createTilemap(
+      options.texture.id, options.cols, options.rows, tileW, tileH, atlasCols, atlasRows, data,
+    )
+    super(id) // wrap the native tilemap entity
+    this.cols = options.cols
+    this.rows = options.rows
+  }
+
+  setTile(x: number, y: number, index: number): this {
+    _creator2d.setTile(this.id, x, y, index)
+    return this
+  }
+}

package/runtime/sdk/g2/loop.ts

@@ -0,0 +1,22 @@
+// Internal per-frame plumbing for the 2D engine. NOT user-facing — user game logic uses the host
+// `setLoop` global. `onUpdate` taps the engine's render-synced pre-frame hook (_creator2d.onUpdate),
+// used by camera.follow so the camera moves in lockstep with the native render (no 1-frame lag).
+//
+// Both registrations are lazy (first use) so a 2D project that never follows a camera or animates a
+// sprite pulls none of this in.
+
+import { node2dRegistry } from "./Node2D"
+
+export const onUpdate = (callback: (dt: number) => void): void => _creator2d.onUpdate(callback)
+export const offUpdate = (callback: (dt: number) => void): void => _creator2d.offUpdate(callback)
+
+// Route native animation events (queued in C++, drained once per frame) to the owning node, which
+// translates the native clip id to a clip name and emits 'loopReached' / 'completed'.
+let animEventsRegistered = false
+export const ensureAnimEvents = (): void => {
+  if (animEventsRegistered) return
+  animEventsRegistered = true
+  _creator2d.setOnAnimEvent(({ entityId, clipId, type }) => {
+    node2dRegistry.get(entityId)?._dispatchAnimEvent(clipId, type)
+  })
+}

package/runtime/sdk/gl/Body.ts

@@ -0,0 +1,101 @@
+// Physics handle for a Node, backed by a JoltPhysics body in creator-gl. Created by node.physics();
+// reached as node.body. Ported from worker/src/components/RigidBody.ts.
+//
+// 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 { 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 type PhysicsOptions = {
+  /** Default "dynamic". */
+  motion?: MotionType
+  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+  mass?: number
+  /** Default { type: "auto" } — a box from the mesh AABB × world scale. */
+  shape?: BodyShape
+}
+
+export class Body {
+  private _bodyId = 0
+  private readonly _motion: MotionType
+
+  constructor(node: Node, options: PhysicsOptions = {}) {
+    this._motion = options.motion ?? "dynamic"
+    const mass = options.mass ?? 1
+
+    // 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(node, options.shape ?? { type: "auto" })
+    if (shape.type === "sphere") {
+      this._bodyId = _creator.physicsCreateSphere(node.id, shape.radius, motion, mass)
+    } else if (shape.type === "cylinder") {
+      this._bodyId = _creator.physicsCreateCylinder(node.id, shape.halfHeight, shape.radius, motion, mass)
+    } else {
+      this._bodyId = _creator.physicsCreateBox(node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, mass)
+    }
+  }
+
+  /** Native Jolt body id. 0 until assigned, or if the build has no physics support. */
+  get id(): number { return this._bodyId }
+  get motion(): MotionType { return this._motion }
+
+  /** 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
+  }
+
+  /** Remove the body from the simulation. */
+  remove(): 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/Camera.ts

@@ -0,0 +1,40 @@
+// The scene camera — a Node (so position / lookAt / transform all work) plus projection reads and
+// screen↔world ray helpers. Created and attached by Scene. Ported from worker/src/components/Camera.ts.
+
+import { Vec3 } from "../math/vec"
+import { Node } from "./Node"
+import { Ray } from "./Ray"
+
+export class Camera extends Node {
+  private _sceneId = -1
+  /** Live projection matrix (updated by the host when the viewport/fov changes). */
+  readonly projectionMatrix = new Float32Array(16)
+
+  /** @internal — Scene wires the camera to its native scene id + projection callback. */
+  _attach(sceneId: number): void {
+    this._sceneId = sceneId
+    _creator.attachCameraToAR(sceneId, this.id, (mat) => {
+      for (let i = 0; i < 16; i++) this.projectionMatrix[i] = mat[i]
+    })
+  }
+
+  get fov(): number { return _creator.getCameraFov(this._sceneId, 0) }
+  get horizontalFov(): number { return _creator.getCameraFov(this._sceneId, 1) }
+  get displaySize(): [number, number] {
+    const s = _creator.getDisplaySize()
+    return [ s[0], s[1] ]
+  }
+
+  /** World-space ray direction through a screen pixel. */
+  getViewDirection(screenX: number, screenY: number): Vec3 {
+    if (this._sceneId < 0) throw new Error("Camera is not attached to a scene")
+    const v = new Float32Array(3)
+    _creator.getCameraViewDirection(this._sceneId, screenX, screenY, v)
+    return new Vec3(v[0], v[1], v[2])
+  }
+
+  /** A pick ray from the camera through a screen pixel. */
+  getRay(screenX: number, screenY: number): Ray {
+    return new Ray(this.worldPosition, this.getViewDirection(screenX, screenY))
+  }
+}

package/runtime/sdk/gl/Geometry.ts

@@ -0,0 +1,218 @@
+// 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
+  /** @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
+  }
+
+  static box(): Geometry { return createCube() }
+  static sphere(options?: SphereOptions): Geometry { return createSphere(options) }
+  static cylinder(options?: CylinderOptions): Geometry { return createCylinder(options) }
+  static plane(options?: PlaneOptions): Geometry { return createPlane(options) }
+}
+
+// --- cube ---
+const createCube = (): Geometry => {
+  const vertices = new Float32Array(6 * 4 * 3)
+  const normals = new Float32Array(6 * 4 * 3)
+  const uv = new Float32Array(6 * 4 * 3)
+  const indices = new Uint16Array(6 * 6)
+  let cnt = 0, indicesCnt = 0
+  const sides = [ -0.5, 0.5 ]
+  for (let i = 0; i < 6; i++) {
+    const s = cnt
+    const side = i % 2 === 0 ? -0.5 : 0.5
+    for (const a of sides) {
+      for (const b of sides) {
+        uv.set([ a + 0.5, b + 0.5 ], cnt * 2)
+        if (i === 0 || i === 1) { vertices.set([ side, b, -a ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
+        if (i === 2 || i === 3) { vertices.set([ a, side, -b ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
+        if (i === 4 || i === 5) { vertices.set([ a, b, side ], 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
+  }
+  return new Geometry(vertices, normals, indices, uv)
+}
+
+// --- 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)
+  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)
+        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
+    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3); 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)
+      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++
+    }
+  }
+  return new Geometry(vertices, normals, indices, uv)
+}
+
+// --- 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/Light.ts

@@ -0,0 +1,37 @@
+// Lights. Currently a directional sun (the engine's primary light). Add it to a scene like any node.
+
+import { Color, type ColorInput } from "../core/color"
+import type { Vec3Like } from "../math/vec"
+import { Node } from "./Node"
+
+export type SunOptions = {
+  /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
+  direction?: Vec3Like
+  /** Luminous intensity. */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Shadow quality (default 1):
+   *   0 - no shadows
+   *   1 - standard (1024 shadow map, hard PCF edges)
+   *   2 - high (2048 + stable, soft contact-hardening edges)
+   *   3 - best (4096 + stable, PCSS soft shadows)
+   * Higher values cost more GPU/memory.
+   */
+  shadowsQuality?: 0 | 1 | 2 | 3
+}
+
+export class Light extends Node {
+  /** A directional sun light. */
+  static sun(options: SunOptions = {}): Light {
+    const light = new Light()
+    const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
+    _creator.createSunLight(
+      light.id, dx, dy, dz,
+      options.intensity ?? 100000,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.shadowsQuality ?? 1,
+    )
+    return light
+  }
+}

package/runtime/sdk/gl/Material.ts

@@ -0,0 +1,124 @@
+// A material instance over creator-gl. Uniforms are set through a Proxy that lowers each JS value to
+// the right native uniform call. The common materials are static factories (Material.lit/unlit/
+// video/shadow); Material.load brings in a custom compiled shader. Ported from worker/src/Material.ts,
+// with the Lit/Unlit/... subclasses collapsed into factories and color accepting any ColorInput.
+
+import { Color, type ColorInput } from "../core/color"
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Texture } from "./Texture"
+
+type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null
+
+const applyUniform = (id: number, key: string, value: UniformValue): void => {
+  if (typeof value === "string") {
+    if (value.length > 7) _creator.setUniformRgba(id, key, parseInt(value.slice(1), 16))
+    else _creator.setUniformRgb(id, key, parseInt(value.slice(1), 16))
+  } else if (typeof value === "number") {
+    _creator.setUniformFloat(id, key, value)
+  } else if (typeof value === "boolean") {
+    _creator.setUniformBoolean(id, key, value)
+  } else if (value instanceof Texture) {
+    _creator.setUniformTexture(id, key, value._id, value.wrapS, value.wrapT)
+  } else if (value instanceof Float32Array) {
+    _creator.setUniformArray(id, key, value)
+  } else if (Array.isArray(value)) {
+    _creator.setUniformArray(id, key, Float32Array.of(...value))
+  } else {
+    _creator.setUniformNull(id, key)
+  }
+}
+
+export type MaterialColorOptions = { color?: ColorInput, map?: Texture | null }
+
+export class Material {
+  /** @internal native material-instance handle. */
+  _id: number
+  readonly shader: FetchResponse | "unknown"
+  readonly uniforms: Record<string, UniformValue>
+
+  private _colorKey: string | null = null
+  private _useMapFlag = true
+
+  constructor(shader: FetchResponse | number) {
+    if (typeof shader === "number") {
+      this.shader = "unknown"
+      this._id = shader
+    } else {
+      this.shader = shader
+      this._id = _creator.createMaterial((shader as any)._id)
+    }
+    const store: Record<string, UniformValue> = {}
+    const id = () => this._id
+    this.uniforms = new Proxy(store, {
+      get: (t, k: string) => t[k],
+      set: (t, k: string, v: UniformValue) => { t[k] = v; applyUniform(id(), k, v); return true },
+    })
+  }
+
+  /** Set a uniform (chainable). */
+  set(key: string, value: UniformValue): this {
+    this.uniforms[key] = value
+    return this
+  }
+
+  set color(c: ColorInput) {
+    if (this._colorKey) this.uniforms[this._colorKey] = Color.toHexString(c)
+  }
+
+  set map(value: Texture | null) {
+    if (value === null) {
+      if (this._useMapFlag) this.uniforms.useBaseColorMap = false
+    } else {
+      this.uniforms.baseColorMap = value
+      if (this._useMapFlag) this.uniforms.useBaseColorMap = true
+    }
+  }
+
+  // --- factories ---
+
+  /** PBR lit material. */
+  static lit(options: MaterialColorOptions = {}): Material {
+    // The fetchLocal literal must be inline so the compiler's preload header captures the shader name.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("lit.filamat") } as any)
+    m._colorKey = "baseColor"
+    if (options.color !== undefined) m.color = options.color
+    if (options.map) m.map = options.map
+    return m
+  }
+
+  /** Unlit (flat) material. */
+  static unlit(options: MaterialColorOptions = {}): Material {
+    const m = new Material({ _id: _creatorUtils.fetchLocal("unlit.filamat") } as any)
+    m._colorKey = "baseColor"
+    if (options.color !== undefined) m.color = options.color
+    if (options.map) m.map = options.map
+    return m
+  }
+
+  /** Material that samples a VideoPlayer's texture. */
+  static video(map?: Texture): Material {
+    const m = new Material({ _id: _creatorUtils.fetchLocal("video.filamat") } as any)
+    m._useMapFlag = false
+    if (map) m.uniforms.baseColorMap = map
+    return m
+  }
+
+  /** Shadow-catcher material (transparent except where shadows fall). */
+  static shadow(color: ColorInput = "#000000aa"): Material {
+    const m = new Material({ _id: _creatorUtils.fetchLocal("shadow.filamat") } as any)
+    m._colorKey = "color"
+    m.color = color
+    return m
+  }
+
+  /** Load a custom compiled shader (.mat URL) as a material. */
+  static load(url: string): Promise<Material> {
+    return fetch(url, { useOnce: true }).then((resp) => {
+      if (resp.status >= 400) return Promise.reject(new Error(`Failed to fetch shader from ${url}. HTTP ${resp.status}`))
+      return new Material(resp)
+    })
+  }
+
+  /** @internal */
+  static idOf(material: Material): number { return material._id }
+}