lecodes-cli 0.1.5 → 0.1.7

package/runtime/sdk/g2/Camera2D.ts

@@ -0,0 +1,73 @@
+// Orthographic camera for a Scene2D. Position/zoom/rotation live natively; `follow` adds a
+// render-synced per-frame update that tracks a node.
+
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { Node2D } from "./Node2D"
+import { offUpdate, onUpdate } from "./loop"
+
+export type FollowOptions = {
+  /** World-space offset added to the target's position. */
+  offset?: Vec2Like
+  /** 0 = snap (default). >0 = exponential smoothing time constant in seconds (smaller = snappier). */
+  smooth?: number
+}
+
+export class Camera2D {
+  private _x = 0
+  private _y = 0
+  private _zoom = 1
+  private _rotation = 0
+
+  private _followTarget: Node2D | null = null
+  private _followOpts: FollowOptions = {}
+  private _followCb: ((dt: number) => void) | null = null
+
+  private readonly sceneId: number
+  constructor(sceneId: number) { this.sceneId = sceneId }
+
+  get position(): Vec2 { return new Vec2(this._x, this._y) }
+  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.cameraSetPosition(this.sceneId, this._x, this._y) }
+
+  get zoom(): number { return this._zoom }
+  set zoom(z: number) { this._zoom = z; _creator2d.cameraSetZoom(this.sceneId, z) }
+
+  get rotation(): number { return this._rotation }
+  set rotation(deg: number) { this._rotation = deg; _creator2d.cameraSetRotation(this.sceneId, deg) }
+
+  screenToWorld(screenX: number, screenY: number): Vec2 {
+    const o = _creator2d.cameraScreenToWorld(this.sceneId, screenX, screenY)
+    return new Vec2(o[0], o[1])
+  }
+  worldToScreen(worldX: number, worldY: number): Vec2 {
+    const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
+    return new Vec2(o[0], o[1])
+  }
+
+  /** Track a node each frame (snaps by default; pass `smooth` for eased follow). */
+  follow(node: Node2D, options: FollowOptions = {}): this {
+    this._followTarget = node
+    this._followOpts = options
+    if (this._followCb) return this
+    this._followCb = (dt: number) => {
+      const t = this._followTarget
+      if (!t) return
+      const [ ox, oy ] = this._followOpts.offset ?? [ 0, 0 ]
+      const tx = t.x + ox
+      const ty = t.y + oy
+      const s = this._followOpts.smooth ?? 0
+      if (s > 0) {
+        const k = 1 - Math.exp(-dt / s)
+        this.position = [ this._x + (tx - this._x) * k, this._y + (ty - this._y) * k ]
+      } else {
+        this.position = [ tx, ty ]
+      }
+    }
+    onUpdate(this._followCb)
+    return this
+  }
+
+  unfollow(): void {
+    this._followTarget = null
+    if (this._followCb) { offUpdate(this._followCb); this._followCb = null }
+  }
+}

package/runtime/sdk/g2/Node2D.ts

@@ -0,0 +1,104 @@
+// Base 2D scene node — an empty transform. Sprite and Tilemap extend it, so every node operation
+// (position, layer, visibility, events) works on them. Native (creator-2d) owns the authoritative
+// transform; JS is the sole writer (no 2D physics yet) so a local cache makes reads free.
+//
+// Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and trigger /
+// logic objects you attach a .collider() to.
+
+import { Emitter } from "../core/events"
+import { Registry } from "../core/registry"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+
+// re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
+export { Vec2, type Vec2Like }
+
+export type Node2DEvents = {
+  /** A looping animation clip wrapped around (fires each loop). */
+  loopReached: (clip: string) => void
+  /** A non-looping animation clip finished. */
+  completed: (clip: string) => void
+  /** A collider overlap began / ended (deferred — native 2D triggers are not built yet). */
+  enter: (other: Node2D) => void
+  exit: (other: Node2D) => void
+}
+
+/** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
+export const node2dRegistry = new Registry<Node2D>()
+
+export type ColliderOptions = {
+  /** Box half-extents (world units). Defaults to the sprite size when omitted. */
+  size?: Vec2Like
+  /** Center offset. */
+  offset?: Vec2Like
+  /** Report overlaps via 'enter'/'exit' instead of blocking (always true for now). */
+  trigger?: boolean
+}
+
+export class Node2D extends Emitter<Node2DEvents> {
+  /** Native entity handle. */
+  readonly id: number
+
+  protected _x = 0
+  protected _y = 0
+  protected _rotation = 0
+  protected _sx = 1
+  protected _sy = 1
+  protected _layer = 0
+  protected _z = 0
+  protected _visible = true
+
+  constructor(internalId?: number) {
+    super()
+    this.id = internalId ?? _creator2d.createEntity()
+    node2dRegistry.set(this.id, this)
+  }
+
+  // --- transform (Y-up world; at zoom 1, units == pixels) ---
+  get x(): number { return this._x }
+  set x(v: number) { this._x = v; _creator2d.setPosition(this.id, v, this._y) }
+  get y(): number { return this._y }
+  set y(v: number) { this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+
+  get position(): Vec2 { return new Vec2(this._x, this._y) }
+  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.setPosition(this.id, this._x, this._y) }
+
+  /** Rotation in degrees (CCW). */
+  get rotation(): number { return this._rotation }
+  set rotation(deg: number) { this._rotation = deg; _creator2d.setRotation(this.id, deg) }
+
+  get scale(): Vec2 { return new Vec2(this._sx, this._sy) }
+  set scale(v: Vec2Like | number) {
+    const sx = typeof v === "number" ? v : cx(v)
+    const sy = typeof v === "number" ? v : cy(v)
+    this._sx = sx; this._sy = sy
+    _creator2d.setScale(this.id, sx, sy)
+  }
+
+  /** Draw layer (int). Higher layers render on top. */
+  get layer(): number { return this._layer }
+  set layer(v: number) { this._layer = v; _creator2d.setLayer(this.id, v) }
+
+  /** Intra-layer depth for non-Y-sorted layers (higher z = on top). */
+  get z(): number { return this._z }
+  set z(v: number) { this._z = v; _creator2d.setZ(this.id, v) }
+
+  get visible(): boolean { return this._visible }
+  set visible(v: boolean) { this._visible = v; _creator2d.setVisible(this.id, v) }
+
+  /**
+   * Attach a collider for overlap detection. DEFERRED: native 2D physics/triggers are not built yet,
+   * so this records intent and is a no-op until the engine lands — the 'enter'/'exit' events won't
+   * fire. The API is here so game code that uses it compiles and stays stable.
+   */
+  collider(_options: ColliderOptions = {}): this {
+    return this
+  }
+
+  /** @internal — overridden by Sprite to translate native clip ids into named animation events. */
+  _dispatchAnimEvent(_clipId: number, _type: number): void {}
+
+  destroy(): void {
+    node2dRegistry.delete(this.id)
+    _creator2d.destroyEntity(this.id)
+  }
+}

package/runtime/sdk/g2/Scene2D.ts

@@ -0,0 +1,73 @@
+// A 2D scene: a draw set + an orthographic Camera2D. Opening a scene asks the host to bring up the
+// 2D engine and starts its RAF loop; only the active scene renders. Grown from the Phase 0 seed.
+
+import { Color, type ColorInput } from "../core/color"
+import { Camera2D } from "./Camera2D"
+import type { Node2D } from "./Node2D"
+
+export type Scene2DOptions = {
+  /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
+  background?: ColorInput
+}
+
+/** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
+class LayerHandle {
+  private readonly sceneId: number
+  private readonly layer: number
+  constructor(sceneId: number, layer: number) { this.sceneId = sceneId; this.layer = layer }
+  /** In this layer, lower-on-screen sprites overlap higher ones (top-down feet sorting). */
+  ySort(enabled = true): this {
+    _creator2d.setLayerYSort(this.sceneId, this.layer, enabled)
+    return this
+  }
+}
+
+export class Scene2D {
+  /** Native scene handle. */
+  readonly id: number
+  readonly camera: Camera2D
+
+  private static _active: Scene2D | null = null
+  static get active(): Scene2D | null { return Scene2D._active }
+
+  constructor(options: Scene2DOptions = {}) {
+    this.id = _creator2d.createScene()
+    this.camera = new Camera2D(this.id)
+    if (options.background !== undefined) this.background = options.background
+  }
+
+  set background(color: ColorInput) {
+    const [ r, g, b, a ] = Color.toRgba01(color)
+    _creator2d.sceneSetClearColor(this.id, r, g, b, a)
+  }
+
+  /** Address a draw layer to configure it, e.g. scene2d.layer(1).ySort(). */
+  layer(n: number): LayerHandle {
+    return new LayerHandle(this.id, n)
+  }
+
+  add(...nodes: Node2D[]): this {
+    for (const n of nodes) _creator2d.addEntityToScene(this.id, n.id)
+    return this
+  }
+  remove(...nodes: Node2D[]): this {
+    for (const n of nodes) _creator2d.removeEntityFromScene(this.id, n.id)
+    return this
+  }
+
+  /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
+  open(): this {
+    _creator2d.openScene(this.id)
+    Scene2D._active = this
+    return this
+  }
+  close(): this {
+    _creator2d.closeScene()
+    if (Scene2D._active === this) Scene2D._active = null
+    return this
+  }
+  destroy(): void {
+    this.close()
+    _creator2d.destroyScene(this.id)
+  }
+}

package/runtime/sdk/g2/Sprite.ts

@@ -0,0 +1,164 @@
+// A textured 2D node. Cheap setters proxy straight to the native sprite; the data lives in
+// creator-2d. Sprite-sheet animation is built in as chainable methods (no separate component):
+//   new Sprite({ texture }).clips({ size: [32, 48], idle: [0,1,2,3], walk: [4,5,6,7] }).play('idle')
+
+import { Color, type ColorInput } from "../core/color"
+import { Vec2, type Vec2Like } from "../math/vec"
+import { ensureAnimEvents } from "./loop"
+import { Node2D } from "./Node2D"
+import type { Texture2D } from "./Texture2D"
+
+export type SpriteOptions = {
+  texture?: Texture2D
+  /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
+  anchor?: Vec2Like
+  /** World size; defaults to the texture's pixel dimensions (or the clip frame size once set). */
+  size?: Vec2Like
+  /** Normalized UV sub-rect [u0,v0,u1,v1]. */
+  frame?: [number, number, number, number]
+  /** Tint multiplied with the texture. */
+  color?: ColorInput
+  opacity?: number
+  layer?: number
+  position?: Vec2Like
+}
+
+/** Per-clip frame list, or an object for per-clip fps/loop overrides. */
+export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
+
+/** Animation definition: the grid frame size + named clips (+ optional shared fps/loop defaults). */
+export type SpriteClips = {
+  /** Grid cell size in texture pixels. */
+  size: [number, number]
+  /** Default fps for clips that don't override it (default 12). */
+  fps?: number
+  /** Default loop for clips that don't override it (default true). */
+  loop?: boolean
+  [clip: string]: Clip | [number, number] | number | boolean | undefined
+}
+
+export class Sprite extends Node2D {
+  private _texture?: Texture2D
+  private _anchor = new Vec2(0.5, 0.5)
+  private _color: ColorInput = 0xffffff
+  private _opacity = 1
+  private _flipX = false
+  private _flipY = false
+  private _size: Vec2 | null = null
+
+  private _clipIds: Record<string, number> = {}
+  private _clipNames: Record<number, string> = {}
+  private _current: string | null = null
+
+  constructor(options: SpriteOptions = {}) {
+    super()
+    if (options.texture) this.texture = options.texture
+    if (options.size) this.size = options.size
+    if (options.anchor) this.anchor = options.anchor
+    if (options.frame) this.frame = options.frame
+    if (options.color !== undefined) this.color = options.color
+    if (options.opacity !== undefined) this.opacity = options.opacity
+    if (options.layer !== undefined) this.layer = options.layer
+    if (options.position) this.position = options.position
+  }
+
+  get texture(): Texture2D | undefined { return this._texture }
+  set texture(t: Texture2D | undefined) {
+    this._texture = t
+    if (!t) return
+    _creator2d.setSprite(this.id, t.id) // native resets UV + size to the full texture
+    if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
+  }
+
+  /** Current world size: explicit override if set, else the texture's pixel dimensions. */
+  get size(): Vec2 { return this._size ?? (this._texture ? new Vec2(this._texture.width, this._texture.height) : new Vec2(0, 0)) }
+  set size(v: Vec2Like) { this._size = new Vec2(v); _creator2d.setSpriteSize(this.id, this._size.x, this._size.y) }
+
+  get anchor(): Vec2 { return this._anchor.clone() }
+  set anchor(v: Vec2Like) { this._anchor = new Vec2(v); _creator2d.setSpriteAnchor(this.id, this._anchor.x, this._anchor.y) }
+
+  /** Set the UV sub-rect (normalized). */
+  set frame(uv: [number, number, number, number]) { _creator2d.setSpriteFrame(this.id, uv[0], uv[1], uv[2], uv[3]) }
+  /** Set the sub-rect in texture pixels. */
+  setFramePx(px: number, py: number, pw: number, ph: number): this {
+    _creator2d.setSpriteFramePx(this.id, px, py, pw, ph)
+    return this
+  }
+
+  get color(): ColorInput { return this._color }
+  set color(c: ColorInput) { this._color = c; const [ r, g, b ] = Color.toRgb01(c); _creator2d.setSpriteColor(this.id, r, g, b) }
+
+  get opacity(): number { return this._opacity }
+  set opacity(a: number) { this._opacity = a; _creator2d.setSpriteOpacity(this.id, a) }
+
+  get flipX(): boolean { return this._flipX }
+  set flipX(v: boolean) { this._flipX = v; _creator2d.setSpriteFlip(this.id, v, this._flipY) }
+  get flipY(): boolean { return this._flipY }
+  set flipY(v: boolean) { this._flipY = v; _creator2d.setSpriteFlip(this.id, this._flipX, v) }
+
+  // --- animation (chainable) ---
+
+  /**
+   * Define named sprite-sheet clips from a uniform grid. Frame indices are row-major into the grid.
+   * Sets the sprite's display size to one cell. Once defined, clips advance entirely in native code.
+   */
+  clips(def: SpriteClips): this {
+    const tex = this._texture
+    if (!tex) throw new Error("Sprite.clips(): set a texture before defining clips")
+    const [ fw, fh ] = def.size
+    const defFps = typeof def.fps === "number" ? def.fps : 12
+    const defLoop = typeof def.loop === "boolean" ? def.loop : true
+    const cols = Math.max(1, Math.floor(tex.width / fw))
+
+    for (const name of Object.keys(def)) {
+      if (name === "size" || name === "fps" || name === "loop") continue
+      const value = def[name] as Clip
+      const indices = Array.isArray(value) ? value : value.frames
+      const fps = Array.isArray(value) ? defFps : (value.fps ?? defFps)
+      const loop = Array.isArray(value) ? defLoop : (value.loop ?? defLoop)
+
+      const frames = new Float32Array(indices.length * 4)
+      indices.forEach((idx, i) => {
+        const cx = (idx % cols) * fw
+        const cy = Math.floor(idx / cols) * fh
+        frames[i * 4 + 0] = cx / tex.width
+        frames[i * 4 + 1] = cy / tex.height
+        frames[i * 4 + 2] = (cx + fw) / tex.width
+        frames[i * 4 + 3] = (cy + fh) / tex.height
+      })
+      const clipId = _creator2d.defineAnimation(this.id, frames, fps, loop)
+      this._clipIds[name] = clipId
+      this._clipNames[clipId] = name
+    }
+
+    if (!this._size) _creator2d.setSpriteSize(this.id, fw, fh)
+    ensureAnimEvents()
+    return this
+  }
+
+  /** Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly). */
+  play(name: string): this {
+    const id = this._clipIds[name]
+    if (id === undefined) throw new Error(`Sprite.play(): unknown clip "${name}"`)
+    if (this._current === name) return this
+    this._current = name
+    _creator2d.playAnimation(this.id, id)
+    return this
+  }
+
+  stop(): this {
+    this._current = null
+    _creator2d.stopAnimation(this.id)
+    return this
+  }
+
+  set animationSpeed(value: number) { _creator2d.setAnimationSpeed(this.id, value) }
+  get currentClip(): string | null { return this._current }
+  get animationFrame(): number { return _creator2d.getAnimationFrame(this.id) }
+
+  /** @internal — translate a native clip id back to its name and emit the animation event. */
+  override _dispatchAnimEvent(clipId: number, type: number): void {
+    const name = this._clipNames[clipId] ?? ""
+    this.dispatch(type === 1 ? "completed" : "loopReached", name)
+  }
+}

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))
+  }
+}