lecodes-cli 0.1.6 → 0.2.0

package/runtime/sdk/g2/Shape.ts

@@ -0,0 +1,63 @@
+// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape does not by itself
+// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger (sensor), both
+// of which require a Shape and turn its geometry into a Box2D fixture. The shape is also what pointer
+// picking hits, so a node is clickable once it has a Shape + Physics2D/Trigger (a body to query).
+//
+//   wall.aspect(Shape, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
+//   goal.aspect(Shape, { circle: 20 }).aspect(Trigger)
+//   hero.aspect(Shape, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
+//
+// With no geometry set, Shape derives a box from the node's sprite size ("auto").
+
+import { Aspect } from "../core/Aspect"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { Node2D } from "./Node2D"
+
+export class Shape extends Aspect<"shape", Node2D> {
+  static readonly aspect = "shape"
+
+  /** Box half-extents [hw, hh] (world units). */
+  box?: Vec2Like
+  /** Circle radius. */
+  circle?: number
+  /** Capsule between two local points, with a radius. */
+  capsule?: { from: Vec2Like, to: Vec2Like, radius: number }
+  /** Thin segment (an edge — for static ground/walls/slopes) between two local points. */
+  segment?: { from: Vec2Like, to: Vec2Like }
+  /** Convex polygon, up to 8 local points (a convex hull is computed). */
+  polygon?: Vec2Like[]
+  /** Local offset of the shape from the node origin. */
+  offset?: Vec2Like
+
+  /**
+   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger).
+   * `sensor` selects a sensor (trigger) vs solid fixture; density/friction/restitution are the
+   * material (ignored for sensors / segments only use friction+restitution).
+   */
+  _addTo(handle: number, sensor: boolean, density: number, friction: number, restitution: number): void {
+    const ox = this.offset ? cx(this.offset) : 0
+    const oy = this.offset ? cy(this.offset) : 0
+    if (this.circle !== undefined) {
+      _creator2d.physicsAddCircle(handle, this.circle, ox, oy, density, friction, restitution, sensor)
+    } else if (this.capsule) {
+      const { from, to, radius } = this.capsule
+      _creator2d.physicsAddCapsule(handle, cx(from), cy(from), cx(to), cy(to), radius, density, friction, restitution, sensor)
+    } else if (this.segment) {
+      _creator2d.physicsAddSegment(handle, cx(this.segment.from), cy(this.segment.from), cx(this.segment.to), cy(this.segment.to), friction, restitution)
+    } else if (this.polygon) {
+      const pts = new Float32Array(this.polygon.length * 2)
+      this.polygon.forEach((p, i) => { pts[i * 2] = cx(p); pts[i * 2 + 1] = cy(p) })
+      _creator2d.physicsAddPolygon(handle, pts, this.polygon.length, density, friction, restitution, sensor)
+    } else {
+      // box: explicit half-extents, or "auto" from the node's sprite size (fallback 8×8).
+      let hw = 8, hh = 8
+      if (this.box) {
+        hw = cx(this.box); hh = cy(this.box)
+      } else {
+        const size = (this.node as { size?: Vec2 }).size
+        if (size) { hw = size.x * 0.5; hh = size.y * 0.5 }
+      }
+      _creator2d.physicsAddBox(handle, hw, hh, ox, oy, density, friction, restitution, sensor)
+    }
+  }
+}

package/runtime/sdk/g2/Sprite.ts

@@ -0,0 +1,79 @@
+// A textured 2D node. Cheap setters proxy straight to the native sprite; the data lives in
+// creator-2d. Sprite-sheet animation is no longer built in — attach the SpriteAnimation aspect:
+//   new Sprite({ texture }).aspect(SpriteAnimation, { size: [32, 48], idle: [0,1,2,3] }).anim.play('idle')
+
+import { Color, type ColorInput } from "../core/color"
+import { Vec2, type Vec2Like } from "../math/vec"
+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. */
+  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
+}
+
+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
+
+  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) }
+}

package/runtime/sdk/g2/SpriteAnimation.ts

@@ -0,0 +1,90 @@
+// Sprite-sheet animation as an aspect on a Sprite. Configured as DATA (frame size + named clips) in
+// the attach call, then driven by name:
+//   sprite.aspect(SpriteAnimation, { size: [32, 48], fps: 10, clips: { idle: [0,1], walk: [4,5,6,7] } })
+//   sprite.anim.play('walk')
+// Once defined, clips advance entirely in native code; the aspect just translates clip ids back to
+// names for the node's 'loopReached' / 'completed' events.
+
+import { Aspect } from "../core/Aspect"
+import { ensureAnimEvents } from "./loop"
+import type { Sprite } from "./Sprite"
+
+/** Per-clip frame list, or an object for per-clip fps/loop overrides. */
+export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
+
+export class SpriteAnimation extends Aspect<"anim", Sprite> {
+  static readonly aspect = "anim"
+
+  /** Grid cell size in texture pixels (defaults to the full texture). */
+  size?: [number, number]
+  /** Default fps for clips that don't override it. */
+  fps = 12
+  /** Default loop for clips that don't override it. */
+  loop = true
+  /** Named clips; frame indices are row-major into the grid. Set via the attach opts. */
+  clips: Record<string, Clip> = {}
+
+  private _clipIds: Record<string, number> = {}
+  private _clipNames: Record<number, string> = {}
+  private _current: string | null = null
+
+  onAttach(): void {
+    this._define()
+    // route native animation events for this entity to named 'loopReached'/'completed' events.
+    ;(this.node as { _dispatchAnimEvent: (clipId: number, type: number) => void })._dispatchAnimEvent =
+      (clipId, type) => this.node._emitAnim(type === 1 ? "completed" : "loopReached", this._clipNames[clipId] ?? "")
+    ensureAnimEvents()
+  }
+
+  /** (Re)build native clips from `this.clips`. Called on attach; call again after changing clips. */
+  define(): this { this._define(); return this }
+
+  private _define(): void {
+    const node = this.node
+    const tex = node.texture
+    if (!tex) throw new Error("SpriteAnimation: set a texture on the Sprite before adding the aspect")
+    const [ fw, fh ] = this.size ?? [ tex.width, tex.height ]
+    const cols = Math.max(1, Math.floor(tex.width / fw))
+
+    for (const name of Object.keys(this.clips)) {
+      const value = this.clips[name]
+      const indices = Array.isArray(value) ? value : value.frames
+      const fps = Array.isArray(value) ? this.fps : (value.fps ?? this.fps)
+      const loop = Array.isArray(value) ? this.loop : (value.loop ?? this.loop)
+
+      const frames = new Float32Array(indices.length * 4)
+      indices.forEach((idx, i) => {
+        const px = (idx % cols) * fw
+        const py = Math.floor(idx / cols) * fh
+        frames[i * 4 + 0] = px / tex.width
+        frames[i * 4 + 1] = py / tex.height
+        frames[i * 4 + 2] = (px + fw) / tex.width
+        frames[i * 4 + 3] = (py + fh) / tex.height
+      })
+      const clipId = _creator2d.defineAnimation(node.id, frames, fps, loop)
+      this._clipIds[name] = clipId
+      this._clipNames[clipId] = name
+    }
+    if (this.size) _creator2d.setSpriteSize(node.id, fw, fh)
+  }
+
+  /** 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(`SpriteAnimation.play(): unknown clip "${name}"`)
+    if (this._current === name) return this
+    this._current = name
+    _creator2d.playAnimation(this.node.id, id)
+    return this
+  }
+
+  stop(): this {
+    this._current = null
+    _creator2d.stopAnimation(this.node.id)
+    return this
+  }
+
+  set speed(value: number) { _creator2d.setAnimationSpeed(this.node.id, value) }
+  get current(): string | null { return this._current }
+  get frame(): number { return _creator2d.getAnimationFrame(this.node.id) }
+}

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/Trigger.ts

@@ -0,0 +1,47 @@
+// A trigger zone, as an aspect on a Node2D. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement.
+//
+//   const goal = new Node2D({ ... })
+//     .aspect(Shape, { box: [32, 64] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => ...)
+//
+// (A trigger is still pointer-pickable — clicks hit sensor shapes too.)
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, type Vec2Like } from "../math/vec"
+import { ensurePhysicsEvents } from "./loop"
+import { Shape } from "./Shape"
+import type { Node2D } from "./Node2D"
+
+export class Trigger extends Aspect<"trigger", Node2D> {
+  static readonly aspect = "trigger"
+
+  private _h = 0
+  /** Native body handle (0 if no physics support). */
+  get handle(): number { return this._h }
+
+  onAttach(): void {
+    if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    this._h = _creator2d.physicsCreateBody(this.node.id, 0 /* static */)
+    if (!this._h) return
+    shape._addTo(this._h, true /* sensor */, 1, 0, 0)
+    ensurePhysicsEvents()   // routes contact/sensor events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._h) { _creator2d.physicsRemoveBody(this._h); this._h = 0 }
+  }
+
+  /** Reposition the trigger zone to a world point. */
+  moveTo(p: Vec2Like): this {
+    if (this._h) _creator2d.physicsSetTransform(this._h, cx(p), cy(p), 0)
+    return this
+  }
+}

package/runtime/sdk/g2/loop.ts

@@ -0,0 +1,39 @@
+// 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),
+// for anything that must move in lockstep with the native render (no 1-frame lag).
+//
+// The animation-event registration is lazy (first use) so a 2D project that never 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)
+  })
+}
+
+// Route native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
+// is delivered to BOTH nodes with the other as the argument. type: 0 contactBegin, 1 contactEnd,
+// 2 sensorBegin, 3 sensorEnd. Registered lazily on the first physics body.
+let physicsEventsRegistered = false
+export const ensurePhysicsEvents = (): void => {
+  if (physicsEventsRegistered) return
+  physicsEventsRegistered = true
+  _creator2d.setOnPhysicsEvent((a, b, type) => {
+    const na = node2dRegistry.get(a)
+    const nb = node2dRegistry.get(b)
+    if (!na || !nb) return
+    const channel = type === 1 || type === 3 ? "exit" : "enter"
+    na._emitCollision(channel, nb)
+    nb._emitCollision(channel, na)
+  })
+}

package/runtime/sdk/g2/touch.ts

@@ -0,0 +1,83 @@
+// 2D pointer dispatch + track (drag) system. The host (createViewer2d canvas / Creator2DView) delivers
+// raw pointer phases via _creator2d.setOnPointer; this module hit-tests in the active scene and routes
+// to the struck node and the scene's listeners. Mirrors the 3D gl/touch.ts, but the hit-test is done
+// here (screen→world via the camera, then a physics overlap), not by the host.
+//
+// What can be hit: a node with a Physics2D shape (precise) → its 'touchstart'/'click' events; the
+// active Scene2D always gets the event too (target = the hit node or null). A node listener can call
+// ev.track({ onMove, onEnd, onCancel }) to capture the rest of the gesture (drag/pan).
+
+import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
+import { Physics2D } from "./Physics2D"
+import { Scene2D } from "./Scene2D"
+import type { Node2D } from "./Node2D"
+
+type Active = { tracker?: TrackHandler, lastX: number, lastY: number }
+const active = new Map<number, Active>()
+
+let registered = false
+/** Register the host pointer callback once, on the first click/touchstart listener (node or scene). */
+export const ensurePointerEvents = (): void => {
+  if (registered) return
+  registered = true
+  _creator2d.setOnPointer((phase, id, x, y) => {
+    if (phase === 0) onDown(id, x, y)
+    else if (phase === 1) onMove(id, x, y)
+    else if (phase === 2) onUp(id, x, y)
+    else onCancel(id)
+  })
+}
+
+// Hit-test: screen (logical px) → world → topmost physics body at the point.
+const hitTest = (scene: Scene2D, sx: number, sy: number): { node: Node2D | null, wx: number, wy: number } => {
+  const w = scene.camera.screenToWorld(sx, sy)
+  return { node: Physics2D.overlapPoint(w), wx: w.x, wy: w.y }
+}
+
+const onDown = (id: number, sx: number, sy: number): void => {
+  const scene = Scene2D.active
+  if (!scene) return
+  const { node, wx, wy } = hitTest(scene, sx, sy)
+  const ev = new TouchStartEvent<Node2D | null>(sx, sy, id)
+  ev.worldX = wx; ev.worldY = wy
+  ev.target = node
+
+  let tracker: TrackHandler | undefined
+  if (node) { node._dispatchEvent("touchstart", ev); tracker = ev._trackHandler }
+  if (!tracker) {
+    for (const l of scene._touchStartListeners.slice()) {
+      l(ev)
+      if (ev._trackHandler) { tracker = ev._trackHandler; break }
+    }
+  }
+  active.set(id, { tracker, lastX: sx, lastY: sy })
+}
+
+const onMove = (id: number, sx: number, sy: number): void => {
+  const a = active.get(id)
+  if (!a) return
+  a.tracker?.onMove?.({ clientX: sx, clientY: sy, deltaX: sx - a.lastX, deltaY: sy - a.lastY })
+  a.lastX = sx; a.lastY = sy
+}
+
+const onUp = (id: number, sx: number, sy: number): void => {
+  const a = active.get(id)
+  active.delete(id)
+  a?.tracker?.onEnd?.({ clientX: sx, clientY: sy, deltaX: a ? sx - a.lastX : 0, deltaY: a ? sy - a.lastY : 0 })
+
+  // A pointer-up is also a click, dispatched at the up location (independent of any track).
+  const scene = Scene2D.active
+  if (!scene) return
+  const { node, wx, wy } = hitTest(scene, sx, sy)
+  const ev = new ClickEvent<Node2D | null>(sx, sy, id)
+  ev.worldX = wx; ev.worldY = wy
+  ev.target = node
+  if (node) node._dispatchEvent("click", ev)
+  for (const l of scene._clickListeners.slice()) l(ev)
+}
+
+const onCancel = (id: number): void => {
+  const a = active.get(id)
+  active.delete(id)
+  a?.tracker?.onCancel?.()
+}

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/Collider.ts

@@ -0,0 +1,29 @@
+// A 3D collider for click/touch hit-testing, as an aspect. Derives a box from the mesh by default.
+// (3D is the default engine, so this is the unsuffixed Collider; the 2D one is Collider2D.)
+//   node.aspect(Collider, { shape: 'box' })
+//   node.aspect(Collider, { shape: 'box', center: [0,1,0], size: [2,2,2] })
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+
+export class Collider extends Aspect<"collider", Node> {
+  static readonly aspect = "collider"
+  shape: "box" | "sphere" = "box"
+  /** Explicit box: center + full size. */
+  center?: Vec3Like
+  size?: Vec3Like
+  /** Explicit sphere: center + radius. */
+  radius?: number
+
+  onAttach(): void {
+    const id = this.node.id
+    if (this.shape === "box" && this.center && this.size) {
+      _creator.setColliderBox(id, cx(this.center), cy(this.center), cz(this.center), cx(this.size), cy(this.size), cz(this.size))
+    } else if (this.shape === "sphere" && this.center && this.radius !== undefined) {
+      _creator.setColliderSphere(id, cx(this.center), cy(this.center), cz(this.center), this.radius)
+    } else {
+      _creator.setColliderFromMesh(id, id, this.shape === "sphere" ? 1 : 0)
+    }
+  }
+}