lecodes-sdk 0.20.0 → 0.20.2

package/src/compile/compileProject.ts

@@ -69,21 +69,22 @@ export type CompileOptions = {
   serverUrl?: string
 }
 
-export const compileProject = async (opts: CompileOptions): Promise<string> => {
-  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
-  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
-  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
-  if (!entry) {
-    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
-  }
+/** The bundle + its map SEPARATELY (the platform deploy writes the map as a sibling `.js.map`; the
+ *  preview inlines it) plus the entrypoint the compile used. `code` carries the metadata header
+ *  unless `header: false`; `map` is already shifted past that header. */
+export type CompileResult = { code: string, map: string | null, entry: string }
 
+/** Turn compile entries into the bundler's module map — the per-kind rules of the deployable
+ *  bundle (resource → URL export, shader → per-backend URL template, .svg → SvgSource, .json →
+ *  data, code verbatim). Exported for callers that build a `libraries` map from entries. */
+export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
-        const name = e.path.split(/[\\/]/).pop() ?? e.path
+        const name = e.path.split(/[\/]/).pop() ?? e.path
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
@@ -98,7 +99,7 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
         // desktop host reports "desktop" on Windows and "opengl" on Linux, iOS "metal".
         // Only entries the CLI actually compiled+staged carry `shadersLocal`; server artifacts
         // (URLs) and un-staged ones keep the URL forms below.
-        const name = shaders[0].src.split(/[\\/]/).pop() ?? ""
+        const name = shaders[0].src.split(/[\/]/).pop() ?? ""
         const [prefix, suffix = ".filamat"] = name.split("_opengl")
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
       } else if (shaders.length > 0) {
@@ -117,16 +118,30 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
       files[e.path] = e.text ?? ""
     }
   }
+  return files
+}
 
+export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
+  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
+  }
+
+  const files = entriesToFiles(entries, opts)
   const { code, map } = await bundleProjectWithMap(
     entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
   )
-  if (opts.header === false) {
-    return map ? `${code}\n${inlineSourceMapComment(map)}` : code
-  }
+  if (opts.header === false) return { code, map, entry }
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader })
-  if (!map) return header + code
-  // Shift the map down past the header (prepended before the code); the inline comment lands last.
+  // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
-  return `${header}${code}\n${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry }
+}
+
+/** The bundle as ONE string, the map inlined at its end (the shipped/preview form). */
+export const compileProject = async (opts: CompileOptions): Promise<string> => {
+  const { code, map } = await compileProjectWithMap(opts)
+  return map ? `${code}\n${inlineSourceMapComment(map)}` : code
 }

package/src/compile/index.ts

@@ -63,9 +63,12 @@ export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
 export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {
   compileProject,
+  compileProjectWithMap,
+  entriesToFiles,
   type CompileEntry,
   type CompileOptions,
   type CompileFileType,
+  type CompileResult,
 } from "./compileProject"
 export {
   loadSceneHarness,

package/src/core/Aspect.ts

@@ -96,14 +96,27 @@ type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
 type FixedInstaller = (fixed: PhaseFn) => boolean
 let frameInstaller: FrameInstaller | undefined
 let fixedInstaller: FixedInstaller | undefined
-/** @internal Install a render-synced frame source for aspect update(dt) (+ the fixed-step source). Called from an engine layer. */
-export const _installAspectFrames = (fn: FrameInstaller, fixed?: FixedInstaller): void => { frameInstaller = fn; fixedInstaller = fixed }
+/** @internal Install a render-synced frame source for aspect update(dt) (+ the fixed-step source). Called from an engine layer.
+ *  The FIRST engine layer wins: a 3D game that later builds a Scene2D for a UIImage minimap keeps its dispatch on the
+ *  3D engine (the one it presents); the 2D engine's phases stay unwired there, so nothing ticks twice. */
+export const _installAspectFrames = (fn: FrameInstaller, fixed?: FixedInstaller): void => {
+  if (frameInstaller) return
+  frameInstaller = fn; fixedInstaller = fixed
+}
 
 /** @internal Engine-level phase hooks (the Net system, sdk/src/net): FIRST in the early and fixed
  *  phases, LAST in the late one, ahead of / behind every game aspect regardless of ordering
  *  constraints. Single slot each; raw dt. */
 export const _phaseHooks: { early: PhaseFn | null; fixed: PhaseFn | null; late: PhaseFn | null } = { early: null, fixed: null, late: null }
 
+/** @internal Advances at the start of EVERY phase pass — early, each fixed step, late — on the
+ *  render-synced path and the setLoop fallback alike. The key for "read the engine once per phase"
+ *  caches (gl/Vehicle's state block): between two passes the engine rewrites state natively (the
+ *  physics steps, the transform sync), so a value cached under an older stamp is stale. Once per
+ *  FRAME is not enough — the early and late phases of one frame straddle the physics step, and a
+ *  value first read in `updateBefore` must not be what `update` sees. */
+export const _phaseStamp = { value: 0 }
+
 let attachSeq = 0
 const warned = new Set<string>()
 const warnOnce = (msg: string): void => { if (!warned.has(msg)) { warned.add(msg); console.warn(msg) } }
@@ -214,7 +227,11 @@ let fixedFallbackAcc = 0
 // engine drives it from inside its substep loop when it has the hook; otherwise (older wasm / Apple /
 // Android builds, the setLoop path) the SDK steps its own accumulator right after the early phase -
 // same step, same 4-substep cap, same drop-the-backlog rule as creator-physics' cphysFrameBegin.
-const fixedStep: PhaseFn = (dt) => { _phaseHooks.fixed?.(dt); fixedUpdaters.run("updateFixed", dt) }
+const fixedStep: PhaseFn = (dt) => {
+  _phaseStamp.value++   // a substep moved the bodies natively since the last pass
+  _phaseHooks.fixed?.(dt)
+  fixedUpdaters.run("updateFixed", dt)
+}
 const fixedFallback = (): void => {
   const step = Time.fixedDt
   fixedFallbackAcc += Time.dt   // scaled: paused -> no steps, slow-motion -> fewer steps, never a shorter dt
@@ -229,12 +246,17 @@ const ensureDispatch = (): void => {
   // Both phases scale their OWN raw dt (the engine hands the same value to both; a host or test that
   // drives them apart still gets each phase's dt right). The frame counter / clocks advance once, early.
   const early: PhaseFn = (dt) => {
+    _phaseStamp.value++
     Time._beginFrame(dt)
     _phaseHooks.early?.(dt)
     earlyUpdaters.run("updateBefore", Time.dt)
     if (fixedFallbackOn) fixedFallback()
   }
-  const late: PhaseFn = (dt) => { lateUpdaters.run("update", Time._phaseDt(dt)); _phaseHooks.late?.(dt) }
+  const late: PhaseFn = (dt) => {
+    _phaseStamp.value++   // the physics step + transform sync ran since the early pass
+    lateUpdaters.run("update", Time._phaseDt(dt))
+    _phaseHooks.late?.(dt)
+  }
   // render-synced source if an engine layer installed one; else one host loop (early then late).
   if (!(frameInstaller && frameInstaller(early, late))) {
     setLoop((dt) => { early(dt); late(dt) })
@@ -266,10 +288,13 @@ const registerUpdater = (inst: Aspect<any, any, any>): void => {
 }
 const unregisterUpdater = (inst: Aspect<any, any, any>): void => {
   const a = internals(inst)
-  if (a._phases === 0) return
-  earlyUpdaters.remove(a)
-  lateUpdaters.remove(a)
-  fixedUpdaters.remove(a)
+  const phases = a._phases
+  if (phases === 0) return
+  // `_phases` records which lists the aspect is in (1 early / 2 late / 4 fixed) — only those are
+  // scanned, so detaching a late-only aspect never walks the early or fixed lists.
+  if (phases & 1) earlyUpdaters.remove(a)
+  if (phases & 2) lateUpdaters.remove(a)
+  if (phases & 4) fixedUpdaters.remove(a)
   a._phases = 0
 }
 

package/src/g2/Scene2D.ts

@@ -167,6 +167,13 @@ export class Scene2D implements Presentable {
     return this
   }
 
+  /** @internal UIImage source marker (UIImage.toSrc): `UIImage(scene)` shows this scene live — the
+   *  host draws it into the image node's box every frame with the scene's own camera (a minimap, a
+   *  portrait, any 2D view inside the UI). Needs no open(); the scene keeps its aspects and animations. */
+  _imageSrc(): { scene2d: number } {
+    return { scene2d: this.id }
+  }
+
   /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
   _viewDesc(): object {
     return this._vd ??= { type: "scene2d", sceneId: this.id, _p: this }

package/src/gl/AudioSource.ts

@@ -0,0 +1,113 @@
+// A 3D sound emitter, as an aspect on a Node (docs/audio-plan.md §2). The engine follows the node's
+// world pose every frame (position, facing for the cone, velocity for doppler); voices played
+// through it are spatialized against the scene's listener (scene.audio.listener, the camera by
+// default). Parented, animated and physics-driven nodes just work.
+//
+//   const gun = new Node().aspect(AudioSource, { minDistance: 1, maxDistance: 40 })
+//   gun.audio.play(shot, { pitch: 0.95 + Math.random() * 0.1 })
+//   const hum = car.audio.play(engineLoop, { loop: true }); hum.pitch = 0.8 + rpm * 0.6
+//   speaker.aspect(AudioSource, { cone: { inner: 60, outer: 120, outerGain: 0.3 } })   // facing −Z
+//   enemy.aspect(AudioSource, { occlusion: true })   // a wall between it and the listener muffles it
+//
+// Without host audio the aspect is inert: `play` returns an inert Voice, nothing throws.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { audio, sourceParams, type PlaySoundOptions, type Rolloff } from "../audio/audio"
+import type { Sound } from "../audio/Sound"
+import { audioSupported } from "../audio/support"
+import type { Voice } from "../audio/Voice"
+import type { Node } from "./Node"
+
+export type AudioCone = {
+  /** Degrees of full volume around the node's −Z. */
+  inner: number
+  /** Degrees where the volume has fallen to `outerGain`. */
+  outer: number
+  /** Volume behind the source, 0 … 1. */
+  outerGain?: number
+}
+
+export class AudioSource extends Aspect<"audio", Node> {
+  static readonly aspect = "audio"
+
+  static fields: FieldMeta<AudioSource> = {
+    minDistance: { min: 0.05, max: 100, step: 0.05 },
+    maxDistance: { min: 0.5, max: 1000, step: 0.5 },
+    doppler: { min: 0, max: 1, step: 0.05 },
+    spread: { min: 0, max: 1, step: 0.05 },
+  }
+
+  private _minDistance = 1
+  private _maxDistance = 50
+  private _rolloff: Rolloff = "inverse"
+  private _cone: AudioCone | null = null
+  private _doppler = 0
+  private _spread = 0
+  private _occlusion = false
+  private _bus = "sfx"
+  /** @internal engine source id (0 = not attached / no audio). */
+  _id = 0
+
+  /** Metres of full volume around the node. Default 1. */
+  get minDistance(): number { return this._minDistance }
+  set minDistance(v: number) { this._minDistance = v; this._push() }
+  /** Metres beyond which the source no longer gets quieter. Default 50. */
+  get maxDistance(): number { return this._maxDistance }
+  set maxDistance(v: number) { this._maxDistance = v; this._push() }
+  /** `inverse` (default), `linear`, `exponential`, `none`. */
+  get rolloff(): Rolloff { return this._rolloff }
+  set rolloff(v: Rolloff) { this._rolloff = v; this._push() }
+  /** Directional source along the node's −Z; null = omnidirectional (default). */
+  get cone(): AudioCone | null { return this._cone }
+  set cone(v: AudioCone | null) { this._cone = v; this._push() }
+  /** Doppler amount 0 … 1 (0 = off, the default) — needs the node to actually move. */
+  get doppler(): number { return this._doppler }
+  set doppler(v: number) { this._doppler = v; this._push() }
+  /** 0 = pin-point panning (default) … 1 = the same on every speaker (a big, close source). */
+  get spread(): number { return this._spread }
+  set spread(v: number) { this._spread = v; this._push() }
+  /** The engine raycasts listener → source (against solid bodies) and muffles the voices when
+   *  something is in the way. Default false. */
+  get occlusion(): boolean { return this._occlusion }
+  set occlusion(v: boolean) { this._occlusion = v; this._push() }
+  /** Default bus for voices on this source. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  /** Live voices on this source. */
+  get voices(): number { return this._id && audioSupported ? _creatorAudio.sourceVoices(this._id) : 0 }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createSource()
+    if (!this._id) return
+    _creatorAudio.attachSource(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroySource(this._id)
+    this._id = 0
+  }
+
+  /** Play a clip from this node. */
+  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
+    return audio._play(sound, this._id, options)
+  }
+
+  /** Stop every voice on this source (fade in seconds). */
+  stopAll(fade = 0): void {
+    if (this._id && audioSupported) _creatorAudio.stopSource(this._id, fade)
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    const cone = this._cone
+    _creatorAudio.setSourceParams(this._id, sourceParams({
+      minDistance: this._minDistance, maxDistance: this._maxDistance, rolloff: this._rolloff,
+      coneInner: cone ? cone.inner : 360, coneOuter: cone ? cone.outer : 360, coneOuterGain: cone ? cone.outerGain ?? 0.25 : 1,
+      doppler: this._doppler, spread: this._spread, occlusion: this._occlusion, bus: audio._busId(this._bus),
+    }))
+  }
+}

package/src/gl/AudioZone.ts

@@ -0,0 +1,75 @@
+// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
+// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
+// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
+// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
+//
+//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
+//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
+//
+// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
+// units (the node's scale applies). Without host audio the aspect is inert.
+
+import { Aspect } from "../core/Aspect"
+import { reverbBlock, type ReverbParams, type ReverbPreset } from "../audio/Bus"
+import { audio } from "../audio/audio"
+import { audioSupported } from "../audio/support"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+import { Shape } from "./Shape"
+
+export class AudioZone extends Aspect<"audioZone", Node> {
+  static readonly aspect = "audioZone"
+
+  private _box: Vec3Like | null = null
+  private _sphere: number | null = null
+  private _reverb: ReverbPreset | ReverbParams = "room"
+  private _blend = 1
+  private _bus = "sfx"
+  /** @internal engine zone id. */
+  _id = 0
+  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+  get id(): number { return this._id }
+
+  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+  get box(): Vec3Like | null { return this._box }
+  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
+  /** Radius; falls back to the node's Shape sphere. */
+  get sphere(): number | null { return this._sphere }
+  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
+  /** A preset name or explicit params (see Bus.reverb). */
+  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
+  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
+  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+  get blend(): number { return this._blend }
+  set blend(v: number) { this._blend = v; this._push() }
+  /** The bus the zone's reverb rides on. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createZone()
+    if (!this._id) return
+    _creatorAudio.attachZone(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
+    this._id = 0
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    let box = this._box, sphere = this._sphere
+    if (!box && sphere === null) {
+      const shape = this.node.get(Shape)
+      if (shape?.sphere !== undefined) sphere = shape.sphere
+      else if (shape?.box) box = shape.box
+    }
+    const dims = sphere !== null
+      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
+      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
+    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
+  }
+}

package/src/gl/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}