lecodes-sdk 2.4.8 → 2.4.10

package/src/scene/defineScene.ts

@@ -52,11 +52,11 @@ import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
-import { Lightmap, type LightmapTransmit } from "../gl/Lightmap"
+import { Lightmap, type LightmapDef } from "../gl/Lightmap"
 import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
-import { Light, type SunOptions } from "../gl/Light"
+import { Light, type PointOptions, type SpotOptions, type SunOptions } from "../gl/Light"
 import { Material } from "../gl/Material"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
 import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
@@ -71,7 +71,13 @@ export type MeshDef =
   | ({ kind: "capsule" } & CapsuleOptions)
   | ({ kind: "plane" } & PlaneOptions)
 
-export type LightDef = { kind: "sun" } & SunOptions
+/** The `light: {}` source block, by `kind` — `Light.sun` / `Light.point` / `Light.spot` with the node's transform: a
+ *  point light's `bakeArea` panel lies in the node's local XZ plane and emits along its local -Y, so `eulerAngles`
+ *  tilts it; a spot shines along the node's -Z (`direction` aims it, as a sun's does). */
+export type LightDef =
+  | ({ kind: "sun" } & SunOptions)
+  | ({ kind: "point" } & PointOptions)
+  | ({ kind: "spot" } & SpotOptions)
 
 /** A stamp: the terrain conforms to another node of this file (a road) at load — see Terrain.conform. */
 export type TerrainStampDef = {
@@ -192,7 +198,7 @@ export type SceneNodeDef = {
    *  `'cube'` = a static whose every mesh bakes as AMBIENT CUBES instead of atlas texels — an occluder (its shadow and
    *  bounce stay in the bake) lit where it stands, the way the bake treats small and thin props on its own: a pipe run, a
    *  fence, a prop whose lightmap seams show. A prefab marked `'cube'` bakes its statics that way too. By name for a whole
-   *  kit: `env.lightmap.cube`. */
+   *  kit: the `cube` option of `env.lightmap`'s `bake()`. */
   lightmap?: boolean | "cube"
   /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
    *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
@@ -215,55 +221,6 @@ export type SceneCameraDef = CameraProjectionDef & {
   target?: Vec3Like
 }
 
-/** `env.lightmap` — the level's baked lighting (engines/bake): the files `lecodes lightmap bake`
- *  writes. Absent = real-time only. */
-export type SceneLightmapDef = {
-  /** `asset('./assets/lightmap/level.bake')` */
-  data: string
-  /** `asset('./assets/lightmap/level-light.ktx2')` — or, for a bake that took more than one atlas PAGE
-   *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x-light.ktx2'), asset('x-light_1.ktx2')]`. */
-  light: string | string[]
-  /** `asset('./assets/lightmap/level-aux.ktx2')` (pages like `light`) — sun / sky visibility + light direction. */
-  aux: string | string[]
-  /** DEBUG: the page sets a `lecodes lightmap bake --split` wrote (`<stem>-direct[_n].ktx2`, `<stem>-indirect[_n].ktx2`),
-   *  pages like `light` — the `Lightmap.debug("direct" | "indirect")` views bind them in place of `light`. */
-  direct?: string | string[]
-  indirect?: string | string[]
-  /** `asset('./assets/lightmap/level-probes.ktx2')` — the bake's reflection probes (one prefiltered cubemap of the level's
-   *  radiance per probe; every static reflects the nearest). Absent = statics reflect the sky's SH alone. */
-  probes?: string
-  /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
-   *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK (the school's panels
-   *  say 10); this is where the level says what they give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default: what
-   *  the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. `--emissive-nits` overrides. */
-  emissiveNits?: number
-  /** `false` = the emissive surfaces light nothing in the bake - the level is lit by its lamps (`Light.point` with a
-   *  `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only says how
-   *  bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. */
-  emissiveBake?: boolean
-  /** FOR THE BAKE: materials that let light THROUGH them, by glTF material name (`"name*"` = every name with that start) →
-   *  the share of a shadow ray that passes, tinted by the material's base colour x map: `{ mat_awning: 0.3 }` puts the
-   *  awning's warm, patterned light on the sand. The surface stays opaque - baked, drawn as before, a shadow caster.
-   *  `{ through, diffuse }` splits it: `through` goes straight (the picture of the map), `diffuse` is scattered by the
-   *  fibres (the underside glows, a soft fill with no picture) - dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
-  transmit?: Record<string, LightmapTransmit>
-  /** FOR THE BAKE: CUBES BY NAME — regular expressions (ECMAScript, case-sensitive) searched in every baked mesh's key
-   *  (`<node path>@<ordinal>`): `['SM_pipe', 'SM_fence']` bakes every pipe and fence node as ambient cubes instead of atlas
-   *  texels, like a node's `lightmap: 'cube'`. The CLI's `--cube` adds to these. */
-  cube?: string[]
-  /** `asset('./assets/lightmap/level.lgrid')` — THE LIGHT GRID for movers: every node a Physics aspect or a
-   *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
-   *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
-  volume?: string
-  /** `asset('./assets/lightmap/level-uv1.bin')` — THE PACKED LIGHTMAP UV1 the bake's rects map: it packs every mesh's
-   *  lightmap charts into a square of their own instead of the unwrap's (once per mesh, whatever model holds it), and the
-   *  engine swaps this into the models' TEXCOORD_1 before the rects go on. Required when the bake wrote one (the .bake's `uv1`): without it the statics
-   *  read the wrong texels, so the bake is not applied. */
-  uv1?: string
-  /** A DEBUG multiplier on the atlas' lux (default 1). */
-  lightScale?: number
-}
-
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
  *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
 export type SceneNavmeshDef = {
@@ -276,7 +233,9 @@ export type SceneNavmeshDef = {
 }
 
 export type SceneDef = {
-  env?: SceneOptions & { lightmap?: SceneLightmapDef, navmesh?: SceneNavmeshDef, foliage?: FoliageOptions }
+  /** `lightmap` = the level's baked lighting (engines/bake): `bake('./assets/lightmap/level.bake', { …options })`, the
+   *  macro that reads the bake's manifest at compile time (`LightmapDef`). Absent = real-time only. */
+  env?: SceneOptions & { lightmap?: LightmapDef, navmesh?: SceneNavmeshDef, foliage?: FoliageOptions }
   camera?: SceneCameraDef
   nodes?: Record<string, SceneNodeDef>
 }
@@ -503,12 +462,23 @@ export const createSource = (path: string, def: SceneNodeDef, lightmap: boolean)
   if (def.model !== undefined) return loadModel(def.model, lightmap, !!def.foliage)
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
   if (def.terrain !== undefined) return createTerrain(def.terrain, lightmap)
-  if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
+  if (def.light !== undefined) return createLight(path, def.light)
   // make/prefab/camera/group nodes are plain wrappers — make/prefab subtrees mount under them
   // during the build (attachPrefab) or in phase 2 (attachMake); a camera node drives scene.camera
   return new Node()
 }
 
+/** A `light:` block by its kind. The node IS the light: its transform (applyNode) aims a sun / spot and turns a
+ *  point light's `bakeArea` panel (local XZ, emitting along local -Y). */
+const createLight = (path: string, def: LightDef): Light => {
+  switch (def.kind) {
+    case "sun": { const { kind: _k, ...opts } = def; return Light.sun(opts) }
+    case "point": { const { kind: _k, ...opts } = def; return Light.point(opts) }
+    case "spot": { const { kind: _k, ...opts } = def; return Light.spot(opts) }
+  }
+  throw new Error(`Scene node "${path}": light kind "${String((def as { kind?: unknown }).kind)}" is not sun, point or spot`)
+}
+
 /** Edit mode: play the preview pose on a model node (`editor: { clip, time }`) — idempotent, the
  *  harness re-applies it on inspector edits. No clip = back to the rest pose. */
 export const applyEditorPose = (node: Node, pose: { clip?: string, time?: number } | undefined): void => {
@@ -1034,10 +1004,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   }
 
   // the level is complete: apply the bake — or, under `lecodes lightmap bake`, run it
-  if (lm && lightmap) {
-    await Lightmap.load(scene, { data: lightmap.data, light: lightmap.light, aux: lightmap.aux, direct: lightmap.direct, indirect: lightmap.indirect, probes: lightmap.probes, volume: lightmap.volume, uv1: lightmap.uv1 },
-                        { lightScale: lightmap.lightScale, emissiveNits: lightmap.emissiveNits, emissiveBake: lightmap.emissiveBake, transmit: lightmap.transmit, cube: lightmap.cube })
-  }
+  if (lm && lightmap) await Lightmap.load(scene, lightmap)
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)
   if (navmesh && !(EDITOR && isEditMode())) {

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.8"
+export const SDK_VERSION = "2.4.10"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {