lecodes-cli 0.18.2 → 0.19.0

package/runtime/sdk/compile/shaderSchema.ts

@@ -0,0 +1,202 @@
+// .mat source → the shader's PARAMETER SCHEMA: what the scene editor's material card renders and
+// what `lecodes shaders` prints. Filament's material block carries name + type only, so the rest
+// (widget kind, range, default, tooltip) comes from ANNOTATIONS in the comment that follows each
+// parameter entry — the same trailing comments shader authors already write:
+//
+//   parameters : [
+//       { type : float3,    name : tint },     // @color what the coating does to the world behind it
+//       { type : float,     name : opacity },  // @range(0, 1) @default(0.22) how much the glass darkens
+//       { type : sampler2d, name : mask },     // the reticle mask, white on alpha
+//   ]
+//
+// Tags: `@color` (float3/float4 = a colour picker; `@vec` forces the plain vector — without either,
+// a float3/float4 whose NAME reads like a colour is one), `@range(min, max)` (slider), `@step(s)`,
+// `@default(v)` (a number, `#hex`, `[x, y, z]`, `true`/`false`). Whatever text is left is the
+// tooltip. A full-line comment directly above the entry counts too. Unknown tags are ignored; a
+// malformed one lands in `errors` and the parameter still lists.
+//
+// Built on liteMaterial's block extraction + relaxed-JSON parser (the ONLY .mat syntax knowledge
+// in the repo — do not fork it). Dependency-free, browser-safe, never throws.
+
+import { extractMatBlocks, parseJsonish, type JsonishValue } from "./liteMaterial"
+
+export type ShaderParamEditor =
+  | "number" | "int" | "switch" | "vec2" | "vec3" | "vec4" | "color" | "texture" | "matrix" | "array"
+
+export type ShaderParamValue = number | boolean | string | number[] | null
+
+export type ShaderParam = {
+  name: string
+  /** filament type name, verbatim (float, float3, sampler2d, …) */
+  type: string
+  /** array parameters ("float[9]") */
+  size?: number
+  editor: ShaderParamEditor
+  /** The value a new material starts with (from `@default`, else the type's zero — white for a colour). */
+  default: ShaderParamValue
+  min?: number
+  max?: number
+  step?: number
+  tooltip?: string
+}
+
+export type ShaderSchema = {
+  name: string
+  shadingModel: string
+  blending: string
+  params: ShaderParam[]
+  errors: string[]
+}
+
+const SAMPLER_TYPES = new Set([ "sampler2d", "samplerExternal", "sampler2dArray", "samplerCubemap", "sampler3d" ])
+const COLOR_NAME = /colou?r|tint|albedo|emissive|glare|glow/i
+
+const zeroFor = (type: string, editor: ShaderParamEditor): ShaderParamValue => {
+  switch (editor) {
+    case "number": return 0
+    case "int": return 0
+    case "switch": return false
+    case "vec2": return [ 0, 0 ]
+    case "vec3": return [ 0, 0, 0 ]
+    case "vec4": return [ 0, 0, 0, 0 ]
+    case "color": return type === "float4" ? "#ffffffff" : "#ffffff"
+    case "texture": return null
+    default: return null
+  }
+}
+
+/** Parse one `@default(...)` payload. */
+const parseDefault = (raw: string, editor: ShaderParamEditor): ShaderParamValue | undefined => {
+  const s = raw.trim()
+  if (s === "true") return true
+  if (s === "false") return false
+  if (/^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(s)) return s.toLowerCase()
+  if (/^-?\d+(\.\d+)?$/.test(s)) return editor === "switch" ? Number(s) !== 0 : Number(s)
+  const arr = /^\[(.*)\]$/.exec(s)
+  if (arr) {
+    const nums = arr[1]!.split(",").map((p) => Number(p.trim()))
+    if (nums.length > 0 && nums.every((n) => Number.isFinite(n))) return nums
+  }
+  return undefined
+}
+
+type Annotation = { color?: boolean, vec?: boolean, range?: [number, number], step?: number, default?: string, tooltip: string, errors: string[] }
+
+/** Split a comment into tags + the remaining tooltip text. */
+const parseAnnotation = (comment: string): Annotation => {
+  const out: Annotation = { tooltip: "", errors: [] }
+  let rest = comment
+  rest = rest.replace(/@(color|vec)\b/g, (_m, tag: string) => { out[tag as "color" | "vec"] = true; return " " })
+  rest = rest.replace(/@(range|step|default)\s*\(([^)]*)\)/g, (_m, tag: string, body: string) => {
+    if (tag === "range") {
+      const parts = body.split(",").map((p) => Number(p.trim()))
+      if (parts.length === 2 && parts.every((n) => Number.isFinite(n))) out.range = [ parts[0]!, parts[1]! ]
+      else out.errors.push(`@range expects two numbers, got "${body.trim()}"`)
+    } else if (tag === "step") {
+      const n = Number(body.trim())
+      if (Number.isFinite(n) && n > 0) out.step = n
+      else out.errors.push(`@step expects a positive number, got "${body.trim()}"`)
+    } else {
+      out.default = body
+    }
+    return " "
+  })
+  rest = rest.replace(/@\w+(\([^)]*\))?/g, " ")   // unknown tags: dropped
+  out.tooltip = rest.replace(/\s+/g, " ").trim()
+  return out
+}
+
+/** The comment attached to each parameter entry, by parameter name: the trailing `//` on the
+ *  entry's line, else the full-line comment(s) directly above it. Scans the raw block text
+ *  (the relaxed-JSON parser drops comments). */
+const collectComments = (materialBlock: string): Map<string, string> => {
+  const out = new Map<string, string>()
+  const start = materialBlock.search(/\bparameters\s*[:=]/)
+  if (start < 0) return out
+  const lines = materialBlock.slice(start).split("\n")
+  let above: string[] = []
+  for (const line of lines) {
+    const trimmed = line.trim()
+    const name = /\bname\s*[:=]\s*"?([A-Za-z_]\w*)"?/.exec(line)?.[1]
+    if (name) {
+      const trailing = /\}[^/\n]*\/\/(.*)$/.exec(line)?.[1] ?? /\/\/(.*)$/.exec(line.slice(line.indexOf("}") + 1))?.[1]
+      const text = trailing !== undefined ? trailing : above.join(" ")
+      if (text.trim() !== "") out.set(name, text.trim())
+      above = []
+    } else if (trimmed.startsWith("//")) {
+      above.push(trimmed.slice(2).trim())
+    } else if (trimmed !== "" && trimmed !== "[" && trimmed !== "],") {
+      above = []
+    }
+  }
+  return out
+}
+
+/** Parse a `.mat` source into its parameter schema. Never throws: an unreadable file yields an
+ *  empty schema whose `errors` say why. */
+export const parseShaderSchema = (text: string): ShaderSchema => {
+  const schema: ShaderSchema = { name: "", shadingModel: "lit", blending: "opaque", params: [], errors: [] }
+  let block: string | undefined
+  let def: Record<string, JsonishValue>
+  try {
+    block = extractMatBlocks(text).material
+    if (block === undefined) { schema.errors.push("no material block"); return schema }
+    def = parseJsonish("{" + block + "}")
+  } catch (e) {
+    schema.errors.push(e instanceof Error ? e.message : String(e))
+    return schema
+  }
+  schema.name = typeof def.name === "string" ? def.name : ""
+  schema.shadingModel = typeof def.shadingModel === "string" ? def.shadingModel : "lit"
+  schema.blending = typeof def.blending === "string" ? def.blending : "opaque"
+
+  const comments = collectComments(block)
+  const rawParams = def.parameters === undefined ? [] : Array.isArray(def.parameters) ? def.parameters : [ def.parameters ]
+  for (const raw of rawParams) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) { schema.errors.push("malformed parameter entry"); continue }
+    const entry = raw as Record<string, JsonishValue>
+    const name = String(entry.name ?? "")
+    const typeRaw = String(entry.type ?? "")
+    const typeMatch = /^(\w+)(?:\[(\d+)\])?$/.exec(typeRaw)
+    if (!name || !typeMatch) { schema.errors.push(`malformed parameter "${name || typeRaw}"`); continue }
+    const type = typeMatch[1]!
+    const size = typeMatch[2] ? Number(typeMatch[2]) : undefined
+    const ann = parseAnnotation(comments.get(name) ?? "")
+    for (const e of ann.errors) schema.errors.push(`${name}: ${e}`)
+
+    let editor: ShaderParamEditor
+    if (size !== undefined) editor = "array"
+    else if (SAMPLER_TYPES.has(type)) editor = "texture"
+    else if (type === "float") editor = "number"
+    else if (type === "int" || type === "uint") editor = "int"
+    else if (type === "bool") editor = "switch"
+    else if (type === "float2") editor = "vec2"
+    else if (type === "float3" || type === "float4") {
+      const isColor = ann.color === true || (ann.vec !== true && COLOR_NAME.test(name))
+      editor = isColor ? "color" : type === "float3" ? "vec3" : "vec4"
+    } else if (/^(int|uint|bool)[234]$/.test(type)) editor = `vec${type.slice(-1)}` as ShaderParamEditor
+    else if (/^float[234]x[234]$/.test(type)) editor = "matrix"
+    else editor = "array"
+
+    const param: ShaderParam = { name, type, editor, default: zeroFor(type, editor) }
+    if (size !== undefined) param.size = size
+    if (ann.range) { param.min = ann.range[0]; param.max = ann.range[1] }
+    if (ann.step !== undefined) param.step = ann.step
+    if (ann.default !== undefined) {
+      const v = parseDefault(ann.default, editor)
+      if (v === undefined) schema.errors.push(`${name}: unreadable @default(${ann.default.trim()})`)
+      else param.default = v
+    }
+    if (ann.tooltip) param.tooltip = ann.tooltip
+    schema.params.push(param)
+  }
+  return schema
+}
+
+/** The parameter values a NEW material starts with for this shader (the schema defaults, textures
+ *  left out — an unset sampler stays the engine's white). */
+export const shaderDefaults = (schema: ShaderSchema): Record<string, ShaderParamValue> => {
+  const out: Record<string, ShaderParamValue> = {}
+  for (const p of schema.params) if (p.editor !== "texture" && p.default !== null) out[p.name] = p.default
+  return out
+}

package/runtime/sdk/compile/shaderTargets.ts

@@ -0,0 +1,81 @@
+// The one shader-compile target matrix, shared by the backend's server-side compile
+// (backend/src/utils/compileShader.ts) and the CLI's local compile (lecodes-cli
+// src/compile/shaders.ts). Both must produce the SAME artifact family for a .mat source —
+// the compiled bundle derives per-backend URLs by substituting `_creator.subBackend ??
+// _creator.backend` into the opengl src (compileProject.ts), so the set of names is ABI.
+
+export const externalSamplerReg = /type\s*:\s*samplerExternal/g
+
+// matc invocation per target. `profile` is matc's -p (mobile = shader model MOBILE / ESSL3,
+// desktop = shader model DESKTOP / GLSL 4.1); `api` is -a. WebGL and the Windows desktop host
+// both run OpenGL without external (OES) sampler support, so they get samplerExternal rewritten
+// to sampler2d. The desktop variant exists because the desktop Filament engine rejects the mobile
+// _opengl shader ("not built for desktop"); _creator.backend returns "desktop" there.
+//
+// These names are opaque identities for a (profile, api, rewrite) triple, not API names — hence
+// "opengl" (mobile profile) and "desktop" (desktop profile) both being OpenGL. Their only job is to
+// be stable and unique: the runtime substitutes one into `<hash>_<name>.filamat`.
+export const PLATFORM_BUILD = {
+  opengl:  { profile: "mobile",  api: "opengl", replaceExternal: false },
+  metal:   { profile: "mobile",  api: "metal",  replaceExternal: false },
+  webgl:   { profile: "mobile",  api: "opengl", replaceExternal: true },
+  desktop: { profile: "desktop", api: "opengl", replaceExternal: true },
+} as const
+export type MatcPlatform = keyof typeof PLATFORM_BUILD
+
+// Targets the CLI compiles LOCALLY and the platform does not. Deliberately a separate table, not
+// another PLATFORM_BUILD entry: `MatcPlatform` feeds the backend's `Platform` type, which is checked
+// against the `shaderPlatform` pg enum — widening it would break the backend's inserts at compile
+// time for a value the server never produces. Keep local-only targets here until the platform grows
+// the matching enum value (docs/desktop-vulkan-release-plan.md §4 "Known limitation").
+//
+// 'desktop-vulkan' = the Windows Vulkan desktop host: same DESKTOP shader model as 'desktop' but
+// SPIR-V, and the two are not interchangeable — Filament rejects a foreign one outright ("not built
+// for any of the OpenGL backend's supported shader languages"). `_creator.backend` returns
+// "desktop-vulkan" on that host.
+export const LOCAL_PLATFORM_BUILD = {
+  "desktop-vulkan": { profile: "desktop", api: "vulkan", replaceExternal: true },
+} as const
+export type LocalMatcPlatform = keyof typeof LOCAL_PLATFORM_BUILD
+
+/** Every matc target, local-only ones included — the lookup table for matcArgs. */
+export const ALL_PLATFORM_BUILD = { ...PLATFORM_BUILD, ...LOCAL_PLATFORM_BUILD }
+export type AnyMatcPlatform = MatcPlatform | LocalMatcPlatform
+
+/** The local-only targets, as a list (order matters where it feeds an artifact family). */
+export const LOCAL_ONLY_PLATFORMS: LocalMatcPlatform[] = ["desktop-vulkan"]
+
+// 'webgl-lite' is not a matc target: viewer-lite gets a JSON artifact (parsed .mat — see
+// liteMaterial.ts) that it wraps in its own GLSL template at runtime.
+export type ShaderPlatform = MatcPlatform | "webgl-lite"
+
+/** Every platform the LOCAL compile can produce (matc targets + the lite JSON). */
+export type AnyShaderPlatform = AnyMatcPlatform | "webgl-lite"
+
+/** Bump when the matc invocation for an EXISTING target name changes (a different -p/-a/rewrite for
+ *  a name that already exists). The CLI folds this into its artifact cache key, so such a change
+ *  invalidates caches that would otherwise look complete — adding or removing a target name is
+ *  already caught by the artifact-family check, but changing the argv behind a name is not.
+ *  1 = 'desktop-vulkan' added (2026-08-24). */
+export const TARGET_MATRIX_GENERATION = 1
+
+/** The matc platforms a .mat source needs compiled. WebGL is matc-compiled only when the shader
+ *  has an external sampler: its samplerExternal → sampler2d rewrite makes the output differ from
+ *  the mobile opengl build. Without one the WebGL artifact is byte-identical to the mobile shader,
+ *  so callers copy it from the opengl output instead of running matc again. Either way a _webgl
+ *  artifact must always exist — the web runtime always requests one (via _creator.subBackend).
+ *
+ *  This is the SERVER's contract — it deliberately does not include LOCAL_ONLY_PLATFORMS. The CLI
+ *  appends those itself (lecodes-cli src/compile/shaders.ts). */
+export const matcPlatformsFor = (text: string): MatcPlatform[] => {
+  externalSamplerReg.lastIndex = 0
+  return externalSamplerReg.test(text)
+    ? ["opengl", "metal", "webgl", "desktop"]
+    : ["opengl", "metal", "desktop"]
+}
+
+/** The matc argv (without the executable) for one target. */
+export const matcArgs = (platform: AnyMatcPlatform, outPath: string, inPath: string): string[] => {
+  const build = ALL_PLATFORM_BUILD[platform]
+  return ["-p", build.profile, "--no-essl1", "-a", build.api, "-o", outPath, inPath]
+}

package/runtime/sdk/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}

package/runtime/sdk/core/Aspect.ts

@@ -79,6 +79,7 @@ interface Updatable {
   updateWhilePaused: boolean
   update?(dt: number): void
   updateBefore?(dt: number): void
+  updateFixed?(dt: number): void
   onAttach?(): void
   onDetach?(): void
   onReconfigure?(): void
@@ -90,9 +91,18 @@ type Ctor = Function & { after?: Function[], before?: Function[], aspect?: strin
 // A render-synced frame source: given the two phase runners, wire them to the engine and return true;
 // return false if unavailable (→ setLoop fallback). Installed by the engine layers (Scene / Scene2D).
 type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
+// The FIXED-phase source: wire `fixed` to the engine's per-substep hook and return true; false when the
+// host has no hook (older builds, 2D-only engines) -> the dispatcher steps its own 1/60 accumulator.
+type FixedInstaller = (fixed: PhaseFn) => boolean
 let frameInstaller: FrameInstaller | undefined
-/** @internal Install a render-synced frame source for aspect update(dt). Called from an engine layer. */
-export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
+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 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 }
 
 let attachSeq = 0
 const warned = new Set<string>()
@@ -107,11 +117,11 @@ class PhaseList {
   private dirty = false
   private holes = false
 
-  add(a: Updatable, phase: "update" | "updateBefore"): void {
+  add(a: Updatable, phase: "update" | "updateBefore" | "updateFixed"): void {
     a._phaseSeq = ++attachSeq
     this.items.push(a)
     this.dirty = true
-    a._phases |= phase === "update" ? 2 : 1
+    a._phases |= phase === "update" ? 2 : phase === "updateFixed" ? 4 : 1
   }
   remove(a: Updatable): boolean {
     const i = this.items.indexOf(a)
@@ -120,7 +130,7 @@ class PhaseList {
     else this.items.splice(i, 1)
     return true
   }
-  run(method: "update" | "updateBefore", dt: number): void {
+  run(method: "update" | "updateBefore" | "updateFixed", dt: number): void {
     if (this.dirty) this.sort()
     const items = this.items
     const n = items.length   // appended during the pass → next frame (attach-order snapshot semantics)
@@ -194,35 +204,72 @@ const rankConstraints = (items: (Updatable | null)[]): Map<Function, number> =>
 
 const earlyUpdaters = new PhaseList()
 const lateUpdaters = new PhaseList()
+const fixedUpdaters = new PhaseList()
 let dispatchInstalled = false
+let fixedInstalled = false
+let fixedFallbackOn = false
+let fixedFallbackAcc = 0
+
+// The FIXED phase: dt = Time.fixedDt (1/60) every call, once per physics substep, on every host. The
+// 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-gl's physics/world.cpp.
+const fixedStep: PhaseFn = (dt) => { _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
+  let steps = 0
+  while (fixedFallbackAcc >= step && steps < 4) { fixedStep(step); fixedFallbackAcc -= step; steps++ }
+  if (steps === 4) fixedFallbackAcc = 0
+}
 
 const ensureDispatch = (): void => {
   if (dispatchInstalled) return
   dispatchInstalled = true
   // 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) => { Time._beginFrame(dt); earlyUpdaters.run("updateBefore", Time.dt) }
-  const late: PhaseFn = (dt) => lateUpdaters.run("update", Time._phaseDt(dt))
+  const early: PhaseFn = (dt) => {
+    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) }
   // 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) })
   }
 }
+// Registered lazily - an app with no `updateFixed` never makes the engine call into JS per substep.
+const ensureFixedDispatch = (): void => {
+  if (fixedInstalled) return
+  fixedInstalled = true
+  ensureDispatch()
+  if (!(fixedInstaller && fixedInstaller(fixedStep))) fixedFallbackOn = true
+}
+
+/** @internal Force the frame dispatch on (the Net system pumps from the phase hooks even in an app
+ *  with no aspects) — and the fixed phase with it, since Net.tick is a fixed-step count. */
+export const _ensureNetDispatch = (): void => { ensureDispatch(); ensureFixedDispatch() }
 
 const registerUpdater = (inst: Aspect<any, any, any>): void => {
   const a = internals(inst)
   const hasBefore = typeof a.updateBefore === "function"
   const hasUpdate = typeof a.update === "function"
-  if (!hasBefore && !hasUpdate) return
+  const hasFixed = typeof a.updateFixed === "function"
+  if (!hasBefore && !hasUpdate && !hasFixed) return
   if (hasBefore) earlyUpdaters.add(a, "updateBefore")
   if (hasUpdate) lateUpdaters.add(a, "update")
+  if (hasFixed) fixedUpdaters.add(a, "updateFixed")
   ensureDispatch()
+  if (hasFixed) ensureFixedDispatch()
 }
 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)
   a._phases = 0
 }
 
@@ -456,6 +503,15 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
    * state. A class rarely needs both phases — that is two aspects on one node.
    */
   protected updateBefore?(dt: number): void
+  /**
+   * FIXED phase - once per physics substep, BEFORE that substep's Jolt step, with `dt = Time.fixedDt`
+   * (1/60) exactly, on every machine: under `Time.scale` the NUMBER of steps per frame changes, never
+   * the dt (0-4 calls per frame). The home of simulation that must match another machine's - a
+   * multiplayer player sim, dt-dependent motion that may not drift with the frame rate. `controller.move()`
+   * / velocity writes here feed the same step; between steps the world is consistent, so `Physics.raycast`
+   * is fine. Anything that looks at the screen (cameras, HUD, FX) stays in `updateBefore` / `update`.
+   */
+  protected updateFixed?(dt: number): void
 
   /** Tick order within a phase and rank — ascending; default 0, ties keep attach order. A declared
    *  `static after` / `static before` constraint always beats this number. Read once, at attach —
@@ -496,7 +552,7 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
 
 /**
  * An aspect of a SCENE: game logic with no single node to live on — input mapping, the FX pools, the
- * HUD, the game mode. Same lifecycle (`onAttach`/`onDetach`), same two phases (`updateBefore` /
+ * HUD, the game mode. Same lifecycle (`onAttach`/`onDetach`), same phases (`updateFixed` / `updateBefore` /
  * `update`), same ordering (`updateOrder`, `static after`) and events as a node aspect; `this.scene` is the
  * scene it was attached to. `S` = the scene kind (`Scene` by default, `Scene2D` for 2D games).
  *