lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/scene/defineScene.ts

@@ -39,7 +39,6 @@ import {
   type AspectEntry, type MakeEntry as SharedMakeEntry,
 } from "./grammar"
 import { InspectorUI, type InspectorEvent, type InspectorWidget } from "../core/InspectorUI"
-import type { ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
 import { Scene, type SceneOptions } from "../gl/Scene"
 import { CAMERA_DEFAULTS } from "../gl/Camera"
@@ -47,11 +46,12 @@ import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
+import { Physics } from "../gl/Physics"
+import { Lightmap } from "../gl/Lightmap"
 import { Light, type SunOptions } from "../gl/Light"
-import { Material, type LitMaterialOptions, type MaterialColorOptions } from "../gl/Material"
+import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
 import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
-import { edgesMesh } from "../gl/scenarios"
-import { GizmoBuffer, withGizmoScope, type GizmoBatch } from "./gizmos"
+import { GizmoBuffer, Gizmos, withGizmoScope, type GizmoBatch } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
 
@@ -63,12 +63,9 @@ export type MeshDef =
 
 export type LightDef = { kind: "sun" } & SunOptions
 
-export type MaterialDef =
-  | { lit: LitMaterialOptions }
-  | { unlit: MaterialColorOptions }
-  | { shadow: ColorInput }
-  // An imported/shared Material instance — valid at runtime; the editor shows it read-only.
-  | Material
+// The material grammar (`{ lit }` / `{ unlit }` / `{ shadow }` / `{ shader, params }` / a
+// material asset handle / a code instance) lives in ./material.ts — re-exported for callers.
+export type { MaterialDef }
 
 // The grammar markers (`use`/`ref`/`make`) live in ./grammar.ts, shared with defineScene2d —
 // re-exported here so this module remains the one import site for scene-file machinery.
@@ -85,6 +82,10 @@ export type ModelOverrideDef = {
   eulerAngles?: Vec3Like
   scale?: Vec3Like | number
   visible?: boolean
+  /** Materials by primitive SLOT of this part (`0` for a single-material mesh; the editor lists
+   *  the slots with their glTF material names): a material asset, an inline def, or a custom
+   *  shader. Slots left out keep the glTF material. */
+  materials?: Record<number | string, MaterialDef>
 }
 
 /** Camera projection settings, shared by the `camera:` source block and the top-level `camera:`
@@ -142,6 +143,11 @@ export type SceneNodeDef = {
   editor?: { clip?: string, time?: number }
   castShadows?: boolean
   receiveShadows?: boolean
+  /** Baked lighting (a scene with `env.lightmap`): is this model/mesh node a lightmap STATIC — a
+   *  receiver and an occluder in the bake, real-time shadow casting off once the bake applies?
+   *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
+   *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
+  lightmap?: boolean
   // -- capabilities / hierarchy --
   aspects?: readonly AspectEntry<any>[]
   children?: Record<string, SceneNodeDef>
@@ -153,8 +159,21 @@ export type SceneCameraDef = CameraProjectionDef & {
   target?: Vec3Like
 }
 
+/** `env.lightmap` — the level's baked lighting (see lightmap.md): the two files
+ *  `lecodes lightmap bake` writes, plus how the bake is applied. Absent = real-time only. */
+export type SceneLightmapDef = {
+  /** `asset('./assets/lightmap/lightmap.bake')` */
+  data: string
+  /** `asset('./assets/lightmap/lightmap.ktx2')` */
+  texture: string
+  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
+  sunStrength?: number
+  /** Multiplier on the ambient share in the shadow math (1 = filament's own darkness). Default 1. */
+  ambientScale?: number
+}
+
 export type SceneDef = {
-  env?: SceneOptions
+  env?: SceneOptions & { lightmap?: SceneLightmapDef }
   camera?: SceneCameraDef
   nodes?: Record<string, SceneNodeDef>
 }
@@ -265,6 +284,17 @@ const applyOverridesToRows = (rows: ModelPartRow[], overrides: Record<string, Mo
     if (o.eulerAngles) node.eulerAngles = o.eulerAngles
     if (o.scale !== undefined) node.scale = o.scale
     if (o.visible !== undefined) node.visible = o.visible
+    // slot materials load in like textures do (a shader package fetch) — the part keeps its glTF
+    // material until then
+    if (o.materials) {
+      for (const [ slot, def ] of Object.entries(o.materials)) {
+        const index = Number(slot)
+        if (!Number.isInteger(index) || index < 0) continue
+        void assignMaterialDef(node, index, def).catch((e) => {
+          console.warn(`[scene] material for "${path}" slot ${index}: ${e instanceof Error ? e.message : String(e)}`)
+        })
+      }
+    }
   }
 }
 
@@ -291,27 +321,42 @@ const attachHost = (parent: Node, def: SceneNodeDef, path: string): Node =>
 
 // ---- runtime -------------------------------------------------------------------
 
-const resolveMaterial = (def: MaterialDef): Material => {
-  if (def instanceof Material) return def
-  if ("lit" in def) return Material.lit(def.lit)
-  if ("unlit" in def) return Material.unlit(def.unlit)
-  return Material.shadow(def.shadow)
-}
-
-const createMesh = (def: MeshDef, material?: MaterialDef): Mesh => {
-  const mat = material !== undefined ? resolveMaterial(material) : undefined
+/** A mesh node resolves its material BEFORE it appears (a custom shader fetches its compiled
+ *  package, textures decode) — the same contract a model has with its GLB. Handle users are
+ *  tracked so the editor can re-assign them when the asset's shader changes. */
+const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> => {
+  const mat = material !== undefined ? await resolveMaterialDef(material) : undefined
+  let mesh: Mesh
   switch (def.kind) {
-    case "box": return Mesh.box({ size: def.size, material: mat })
-    case "sphere": { const { kind: _k, ...opts } = def; return Mesh.sphere({ ...opts, material: mat }) }
-    case "cylinder": { const { kind: _k, ...opts } = def; return Mesh.cylinder({ ...opts, material: mat }) }
-    case "plane": { const { kind: _k, ...opts } = def; return Mesh.plane({ ...opts, material: mat }) }
+    case "box": mesh = Mesh.box({ size: def.size, material: mat }); break
+    case "sphere": { const { kind: _k, ...opts } = def; mesh = Mesh.sphere({ ...opts, material: mat }); break }
+    case "cylinder": { const { kind: _k, ...opts } = def; mesh = Mesh.cylinder({ ...opts, material: mat }); break }
+    case "plane": { const { kind: _k, ...opts } = def; mesh = Mesh.plane({ ...opts, material: mat }); break }
   }
+  if (material instanceof MaterialHandle) material._users.add({ node: mesh, slot: 0 })
+  return mesh
 }
 
-const createSource = (path: string, def: SceneNodeDef): Node | Promise<Node> => {
+// ---- baked lighting (env.lightmap) ---------------------------------------------------------------
+// Statics are derived, not declared: a model/mesh node bakes unless a Physics aspect moves it
+// (`dynamic` — Physics' default — or `kinematic`); `lightmap: true | false` on the node overrides.
+// Keys are node paths (prefab internals: `wrapper/inner`), so lightmap.bake stays readable and a
+// rename honestly invalidates the rect. make() subtrees are code — they register themselves with
+// Lightmap.add. Edit mode never bakes or applies (the editor shows real-time shadows).
+
+type LightmapCtx = { prefix: string }
+
+const movesByPhysics = (def: SceneNodeDef): boolean =>
+  (def.aspects ?? []).some((e) =>
+    (e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
+
+const createSource = (path: string, def: SceneNodeDef, lightmap = false): Node | Promise<Node> => {
   const sources = [ def.mesh, def.model, def.light, def.make, def.prefab, def.camera ].filter((s) => s !== undefined).length
   if (sources > 1) throw new Error(`Scene node "${path}" declares more than one source (mesh/model/light/make/prefab/camera)`)
-  if (def.model !== undefined) return Model.load(def.model)
+  if (def.model !== undefined) return Model.load(def.model, { lightmap })
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
   if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
   // make/prefab/camera/group nodes are plain wrappers — make/prefab subtrees mount under them
@@ -369,30 +414,23 @@ const isGroupDef = (def: SceneNodeDef): boolean =>
   def.mesh === undefined && def.model === undefined && def.light === undefined
   && def.make === undefined && def.prefab === undefined && def.camera === undefined
 
-/** Edit mode: give otherwise-invisible nodes (empties, cameras) an `__editor_marker` line-mesh
- *  child so they render and pick in the viewport. The harness reads `_sceneMarker` to give the
- *  node itself a box collider (markers are editor nodes — never raycast/placement targets). */
-const addEditorMarker = (node: Node, def: SceneNodeDef, scene: Scene): void => {
-  let marker: Mesh
+/** Edit mode: otherwise-invisible nodes (empties, `camera:` nodes) get an ANCHORED gizmo marker —
+ *  an axis cross / a frustum in the node's local frame (scene/gizmos.ts) — so they show and pick
+ *  in the viewport. Never scene content: nothing renders in Filament, nothing outlines, and the
+ *  engine follows the node live, so the buffer is filled once and lives on the node
+ *  (`_editorMarker`) — `_editorGizmos()` reads it off the handle's own def nodes, so a removed
+ *  node's marker goes with its record and prefab / instance internals (not selectable) draw none. */
+const addEditorMarker = (node: Node, def: SceneNodeDef): void => {
+  const buffer = new GizmoBuffer()
   if (def.camera !== undefined) {
-    // wireframe frustum looking down local -Z + an "up" fin above the near rect
-    const z = -0.55, w = 0.3, h = 0.21
-    const segs: number[] = []
-    for (const [ cx, cy ] of [ [ -w, -h ], [ w, -h ], [ w, h ], [ -w, h ] ] as const) segs.push(0, 0, 0, cx, cy, z)
-    segs.push(-w, -h, z, w, -h, z, w, -h, z, w, h, z, w, h, z, -w, h, z, -w, h, z, -w, -h, z)
-    segs.push(-0.12, h, z, 0, h + 0.14, z, 0, h + 0.14, z, 0.12, h, z)
-    marker = edgesMesh(segs, "#cfd4dd")
-    ;(node as { _sceneMarker?: string })._sceneMarker = "camera"
+    withGizmoScope(buffer, () => Gizmos.frustum(def.camera?.fov ?? CAMERA_DEFAULTS.fov, { node, color: "#cfd4dd" }))
   } else if (isGroupDef(def)) {
-    const s = 0.3
-    marker = edgesMesh([ -s, 0, 0, s, 0, 0, 0, -s, 0, 0, s, 0, 0, 0, -s, 0, 0, s ], "#8f96a3")
-    ;(node as { _sceneMarker?: string })._sceneMarker = "empty"
+    withGizmoScope(buffer, () => Gizmos.cross([ 0, 0, 0 ], 0.3, { node, color: "#8f96a3" }))
   } else {
     return
   }
-  marker.name = "__editor_marker"
-  node.add(marker)
-  scene.add(marker)
+  ;(node as { _editorMarker?: GizmoBuffer })._editorMarker = buffer
+  gizmoVersion++
 }
 
 /** The ACTIVE `CameraPlace` entry in THIS file's own defs (depth-first; prefab / instance internals
@@ -677,7 +715,7 @@ const prefabPartRows = (defs: Record<string, SceneNodeDef>, local: Record<string
   return out
 }
 
-const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>): Promise<void> => {
+const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>, lm: LightmapCtx | null): Promise<void> => {
   const pdef = (def.prefab as { def?: SceneDef } | undefined)?.def
   if (!pdef || typeof pdef !== "object") {
     console.error(`[scene] "${path}".prefab is not a scene handle (import the .scene file's default export)`)
@@ -691,7 +729,7 @@ const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scen
   }
   const local: Record<string, Node> = {}
   const localRuns: EditorRun[] = []   // discarded: instance internals render, but aren't editor-tracked
-  await buildNodes(pdef.nodes ?? {}, wrapper, scene, local, localRuns, new Set(stack).add(pdef))
+  await buildNodes(pdef.nodes ?? {}, wrapper, scene, local, localRuns, new Set(stack).add(pdef), lm)
   const rows = prefabPartRows(pdef.nodes ?? {}, local, "", 0)
   ;(wrapper as { _prefabParts?: ModelPartRow[] })._prefabParts = rows
   if (def.overrides) applyOverridesToRows(rows, def.overrides)
@@ -703,6 +741,7 @@ const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scen
 const buildNodes = async (
   defs: Record<string, SceneNodeDef>, parent: Node | null, scene: Scene,
   nodes: Record<string, Node>, editorRuns: EditorRun[], stack: Set<SceneDef>,
+  lm: LightmapCtx | null = null,
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
 
@@ -714,15 +753,17 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const node = await createSource(path, nd)
+    const lmStatic = lm !== null && isLightmapStatic(nd)
+    const node = await createSource(path, nd, lmStatic)
     // a `mount` def parents to an internal part of the parent asset — safe here: the parent's
     // model was awaited and attachPrefab completed before its children build
     if (parentNode) attachHost(parentNode, nd, path).add(node)
     // Draw-set membership is separate from parenting (see docs/3d/node.md) — every def node joins.
     scene.add(node)
     applyNode(node, name, nd)   // engine-side name stays the bare sibling segment
-    if (isEditMode()) addEditorMarker(node, nd, scene)
-    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack)
+    if (lmStatic && (node instanceof Model || node instanceof Mesh)) Lightmap._register(node, lm!.prefix + path)
+    if (isEditMode()) addEditorMarker(node, nd)
+    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/` } : null)
     pending.push({ path, node, def: nd })
     nodes[path] = node
     await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path)))
@@ -740,9 +781,13 @@ const buildNodes = async (
 }
 
 const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ scene: Scene, nodes: Record<string, Node> }> => {
-  const scene = new Scene(def.env)
+  const { lightmap, ...env } = def.env ?? {}
+  const scene = new Scene(env)
   const nodes: Record<string, Node> = {}
-  await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]))
+  // baked lighting is a play-mode concern; the level owns the registry (a rebuild starts clean)
+  const lm: LightmapCtx | null = lightmap && !isEditMode() ? { prefix: "" } : null
+  if (lm) Lightmap.clear()
+  await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]), lm)
 
   // a camera NODE wins over the top-level `camera:` block; in play mode it keeps driving the view
   // (CameraRig), in edit mode it only seeds the editor's starting viewpoint. The PROJECTION applies
@@ -771,6 +816,12 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
     applyCameraProjection(scene, def.camera)
   }
 
+  // the level is complete: apply the bake — or, under `lecodes lightmap bake`, run it
+  if (lm && lightmap) {
+    await Lightmap.load(scene, { data: lightmap.data, texture: lightmap.texture },
+      { sunStrength: lightmap.sunStrength, ambientScale: lightmap.ambientScale })
+  }
+
   return { scene, nodes }
 }
 
@@ -896,7 +947,7 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       if (parent) attachHost(parent, d, p).add(node)
       scene.add(node)
       applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)
-      if (isEditMode()) addEditorMarker(node, d, scene)
+      if (isEditMode()) addEditorMarker(node, d)
       attachAspects(node, p, d, nodes, scene, this._editorRuns)
       nodes[p] = node
       await Promise.all(Object.entries(d.children ?? {}).map(([ cn, cd ]) => build(`${p}/${cn}`, cd, node)))
@@ -928,6 +979,10 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     const batches: GizmoBatch[] = []
     for (const run of this._editorRuns) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
     for (const runs of foreignRuns.values()) for (const run of runs) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
+    for (const node of Object.values(this._live?.nodes ?? {})) {
+      const marker = (node as { _editorMarker?: GizmoBuffer })._editorMarker
+      if (marker) for (const b of marker.batches) batches.push(b)
+    }
     return { version: gizmoVersion, batches }
   }
 

package/runtime/sdk/scene/gizmos.ts

@@ -13,20 +13,33 @@
 // Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
 // `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
 // after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
+//
+// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
+// follows the node live — through a gizmo drag, not only after it — with the node's scale
+// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
+// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
+// accent while selected. World-space calls (path lines) are never pickable.
 
 import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Vec3Like } from "../math/vec"
 
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = { readonly id: number }
+
 export type GizmoStyle = {
   /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
   color?: string
   /** 0..1, default 1. */
   alpha?: number
+  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+   *  live, are pickable (a click selects the node) and turn the selection accent when it is
+   *  selected. Omit for world-space lines (not pickable). */
+  node?: GizmoAnchor | null
 }
 
-/** One color batch of world-space LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands
- *  the engine. */
-export type GizmoBatch = { color: string, alpha: number, segments: number[] }
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
+ *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
 
 const DEFAULT_COLOR = "#cfd4dd"
 
@@ -44,10 +57,11 @@ export class GizmoBuffer {
   segments(style: GizmoStyle | undefined): number[] {
     const color = style?.color ?? DEFAULT_COLOR
     const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
-    const key = `${color}@${alpha}`
+    const entityId = style?.node?.id
+    const key = `${color}@${alpha}@${entityId ?? ""}`
     let b = this._byStyle.get(key)
     if (!b) {
-      b = { color, alpha, segments: [] }
+      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
       this._byStyle.set(key, b)
       this.batches.push(b)
     }
@@ -102,15 +116,21 @@ export const Gizmos = {
     for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
   },
 
-  /** A wireframe camera frustum looking down a node's local −Z (the `CameraPlace` marker): the
-   *  four edges from the node origin to a far rect `length` metres ahead sized by `fov` (vertical,
-   *  degrees) × `aspect`, plus an "up" fin above the rect. Points are transformed by `worldMatrix`. */
-  frustum(worldMatrix: Mat4Like, fov: number, aspect = 16 / 9, length = 0.6, style?: GizmoStyle): void {
+  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
     const out = target(style)
     if (!out) return
-    const m = new Mat4(worldMatrix)
+    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
+    const m = style?.matrix ? new Mat4(style.matrix) : null
     const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
-    const P = (x: number, y: number, zz: number): [number, number, number] => { const v = m.transformPoint([ x, y, zz ]); return [ v.x, v.y, v.z ] }
+    const P = (x: number, y: number, zz: number): [number, number, number] => {
+      if (!m) return [ x, y, zz ]
+      const v = m.transformPoint([ x, y, zz ])
+      return [ v.x, v.y, v.z ]
+    }
     const o = P(0, 0, 0)
     const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
     for (const q of c) out.push(...o, ...q)

package/runtime/sdk/scene/material.ts

@@ -0,0 +1,188 @@
+// Materials as data — the `material:` grammar of scene files and the `defineMaterial` document
+// behind `*.material.ts` assets (docs/scene-materials-plan.md).
+//
+//   // materials/holo-glass.material.ts
+//   export default defineMaterial({
+//     shader: asset('../assets/shaders/lens.mat'),
+//     params: { tint: '#1d2b26', opacity: 0.22, mask: asset('../assets/weapons/reticle.png') },
+//   })
+//
+//   // range.scene.ts
+//   import holoGlass from './materials/holo-glass.material'
+//   lens: { mesh: { kind: 'plane' }, material: holoGlass },
+//
+// One grammar serves the inline form (`material: { lit: {…} }` / `{ shader, params }` on a node),
+// the asset form (the handle) and GLB-part overrides. A handle is ONE shared GPU material: every
+// node using the asset renders the same instance, and editing the asset changes all of them
+// (Unity's rule — two looks are two assets).
+//
+// Parameter values need no shader metadata at runtime: a string is a colour when it starts with
+// `#`, otherwise it is a texture URL (`asset('./x.png')` compiles to one) — the same lowering
+// `Material.set` already applies to colours.
+
+import type { ColorInput } from "../core/color"
+import { Material, type LitMaterialOptions, type MaterialColorOptions } from "../gl/Material"
+import { Texture } from "../gl/Texture"
+import type { Node } from "../gl/Node"
+import { EDIT_FLAG } from "./grammar"
+
+/** A shader parameter value as scene files write it: number, boolean, `#colour`, texture URL
+ *  (`asset('./x.png')`), or a numeric vector. */
+export type MaterialParamValue = number | boolean | string | number[]
+
+type WithMapUrl<T> = Omit<T, "map"> & {
+  /** Base-colour texture — a `Texture`, a `Canvas`, or `asset('./x.png')` (a URL string). */
+  map?: LitMaterialOptions["map"] | string
+}
+
+export type LitMaterialDef = WithMapUrl<LitMaterialOptions>
+export type UnlitMaterialDef = WithMapUrl<MaterialColorOptions>
+
+/** A custom Filament shader (`asset('./x.mat')` — compiled by the platform / `lecodes shaders`)
+ *  plus its parameter values. */
+export type ShaderMaterialDef = {
+  shader: string
+  params?: Record<string, MaterialParamValue>
+}
+
+export type MaterialDef =
+  | { lit: LitMaterialDef }
+  | { unlit: UnlitMaterialDef }
+  | { shadow: ColorInput }
+  | ShaderMaterialDef
+  /** A material asset (`import m from './x.material'`) — one shared instance. */
+  | MaterialHandle
+  /** A code-level Material instance — valid at runtime; the editor shows it read-only. */
+  | Material
+
+/** The data forms of MaterialDef (everything but a live instance / handle). */
+export type MaterialData = Exclude<MaterialDef, MaterialHandle | Material>
+
+const isTextureUrl = (v: unknown): v is string => typeof v === "string" && !v.startsWith("#")
+
+/** Push one parameter into a live material. Textures load asynchronously — the returned promise
+ *  settles once the value is applied (immediately for scalars). */
+export const applyMaterialParam = (material: Material, name: string, value: MaterialParamValue | null): Promise<void> => {
+  if (isTextureUrl(value)) {
+    return Texture.load(value).then((tex) => { material.set(name, tex) }, (e) => {
+      console.warn(`[material] "${name}": ${e instanceof Error ? e.message : String(e)}`)
+    })
+  }
+  material.set(name, value as never)
+  return Promise.resolve()
+}
+
+/** Build a live Material from a data def. Resolves once every texture it names has loaded. */
+export const createMaterialFromData = async (def: MaterialData): Promise<Material> => {
+  if ("shader" in def) {
+    const m = await Material.load(def.shader)
+    await Promise.all(Object.entries(def.params ?? {}).map(([ k, v ]) => applyMaterialParam(m, k, v)))
+    return m
+  }
+  if ("shadow" in def) return Material.shadow(def.shadow)
+  const lit = "lit" in def
+  const opts = lit ? def.lit : def.unlit
+  const { map, ...rest } = opts
+  const m = lit ? Material.lit(rest as LitMaterialOptions) : Material.unlit(rest as MaterialColorOptions)
+  if (isTextureUrl(map)) m.map = await Texture.load(map)
+  else if (map !== undefined) m.map = map as LitMaterialOptions["map"] as Texture | null
+  return m
+}
+
+/**
+ * A material asset: the default export of a `*.material.ts` file. `load()` yields ONE shared
+ * `Material` (cached); scene files hand the handle to `material:` and the loader resolves it.
+ * The editor edits the asset live through `setParam` / `reset` — every node the handle was
+ * applied to follows (`_users`).
+ */
+export class MaterialHandle {
+  def: MaterialData
+  private _instance: Material | null = null
+  private _loading: Promise<Material> | null = null
+  /** Every (node, slot) this handle was applied to through a scene — the editor re-assigns them
+   *  when the asset's shader changes. */
+  readonly _users = new Set<{ node: Node, slot: number }>()
+
+  constructor(def: MaterialData) {
+    this.def = def
+  }
+
+  /** The shared material instance (built on first use). */
+  load(): Promise<Material> {
+    if (this._instance) return Promise.resolve(this._instance)
+    this._loading ??= createMaterialFromData(this.def).then((m) => { this._instance = m; return m })
+    return this._loading
+  }
+
+  /** The live instance, if built yet. */
+  get material(): Material | null { return this._instance }
+
+  /** Editor: assign this material to `node`'s `slot`, remembering the user. */
+  async _applyTo(node: Node, slot: number): Promise<Material> {
+    const m = await this.load()
+    node.setMaterial(m, slot)
+    this._users.add({ node, slot })
+    return m
+  }
+
+  /** Editor: one parameter value, applied live to the shared instance (a texture loads in). */
+  setParam(name: string, value: MaterialParamValue | null): void {
+    const def = this.def
+    if ("shader" in def) {
+      def.params ??= {}
+      if (value === null) delete def.params[name]
+      else def.params[name] = value
+    } else if ("lit" in def || "unlit" in def) {
+      const opts = ("lit" in def ? def.lit : def.unlit) as Record<string, unknown>
+      if (value === null) delete opts[name]
+      else opts[name] = value
+    }
+    const m = this._instance
+    if (!m) return
+    if (!("shader" in def) && name === "color") { m.color = value as string; return }
+    if (!("shader" in def) && name === "map") {
+      if (isTextureUrl(value)) void Texture.load(value).then((t) => { m.map = t })
+      else m.map = null
+      return
+    }
+    void applyMaterialParam(m, name, value)
+  }
+
+  /** Editor: replace the whole definition (a shader/kind switch) — rebuilds the instance and
+   *  re-assigns every user. */
+  async reset(def: MaterialData): Promise<Material> {
+    this.def = def
+    this._instance = null
+    this._loading = null
+    const m = await this.load()
+    for (const u of this._users) u.node.setMaterial(m, u.slot)
+    return m
+  }
+}
+
+/** Resolve any `material:` value to a live Material (a handle's shared instance, a data def's
+ *  fresh one, a code instance as is). */
+export const resolveMaterialDef = (def: MaterialDef): Promise<Material> => {
+  if (def instanceof Material) return Promise.resolve(def)
+  if (def instanceof MaterialHandle) return def.load()
+  return createMaterialFromData(def)
+}
+
+/** Resolve and assign a `material:` value to one slot of a node (tracking handle users). */
+export const assignMaterialDef = async (node: Node, slot: number, def: MaterialDef): Promise<Material> => {
+  if (def instanceof MaterialHandle) return def._applyTo(node, slot)
+  const m = await resolveMaterialDef(def)
+  node.setMaterial(m, slot)
+  return m
+}
+
+/**
+ * Define a material as data — the default export of a `*.material.ts` file. Import it into scene
+ * files (`material: handle`) or code (`const m = await handle.load()`).
+ */
+export const defineMaterial = (def: MaterialData): MaterialHandle => {
+  const handle = new MaterialHandle(def)
+  const g = globalThis as unknown as { [EDIT_FLAG]?: boolean, __lecodesMaterialHandles?: MaterialHandle[] }
+  if (g[EDIT_FLAG]) (g.__lecodesMaterialHandles ??= []).push(handle)
+  return handle
+}