@rydr/game-sdk 9.10.0 → 9.11.0

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from "./protocol/index.js";
 export * from "./client/index.js";
 export * from "./host/index.js";
 export * from "./world-runtime.js";
+export * from "./world-lighting.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -11,4 +11,5 @@ export * from "./protocol/index.js";
 export * from "./client/index.js";
 export * from "./host/index.js";
 export * from "./world-runtime.js";
+export * from "./world-lighting.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}

package/dist/protocol/version.d.ts

@@ -9,5 +9,5 @@
 export declare const RYDR_PROTOCOL_VERSION: 42;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging.
  *  (Bumped to 2.0.0 by `npm version major` on release — see CHANGELOG [Unreleased].) */
-export declare const RYDR_SDK_VERSION = "9.10.0";
+export declare const RYDR_SDK_VERSION = "9.11.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/protocol/version.js

@@ -398,5 +398,5 @@
 export const RYDR_PROTOCOL_VERSION = 42;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging.
  *  (Bumped to 2.0.0 by `npm version major` on release — see CHANGELOG [Unreleased].) */
-export const RYDR_SDK_VERSION = "9.10.0";
+export const RYDR_SDK_VERSION = "9.11.0";
 //# sourceMappingURL=version.js.map

package/dist/protocol/worlds.d.ts

@@ -62,6 +62,157 @@ export interface WorldMapDelta {
      * Applied by `applyWorld`; absent on worlds saved before it existed.
      */
     worldTransform?: WorldTransform;
+    /**
+     * Lights placed in the world (lamps, spots, extra suns, area lights). Optional: absent on worlds
+     * saved before lights existed. The SUN is not here: it belongs to a lighting preset
+     * ({@link WorldLightingPreset.sun}), because Day and Night each have their own.
+     *
+     * These are authored in the platform world editor and exist so a bake can light the world with
+     * them. A game renders them LIVE only when it opts in (`createWorldLights`, capped), since dozens of
+     * real-time lights are unplayable in WebGL; in a baked scene their light is already in the lightmap.
+     */
+    lights?: WorldLight[];
+}
+/** The kinds of light a world can hold. `area` is bake-only: glTF and live three.js have no match. */
+export type WorldLightType = "directional" | "point" | "spot" | "area";
+/**
+ * One light placed in a world.
+ *
+ * **Units are three.js's physical units**, so a light looks the same live and baked:
+ * `directional` in lux-like irradiance (a noon sun is ~3), `point`/`spot` in candela (a street lamp is
+ * ~40-150 at a few metres), `area` in Blender watts (it has no live counterpart). The bake script
+ * converts them to Cycles once, in one place.
+ *
+ * **Transforms are absolute, in world (map) space, like `WorldAddedObject`.** To make a lamp move with
+ * its post, group the two in the editor (object groups are editor metadata); the light is still
+ * stored with its own absolute transform.
+ */
+export interface WorldLight {
+    id: string;
+    type: WorldLightType;
+    /** Shown in the editor's outliner. */
+    name?: string;
+    position: [number, number, number];
+    /**
+     * Orientation quaternion `[x, y, z, w]`. The light shines down its local -Y axis (a lamp hanging
+     * from its post points down with the identity rotation). Ignored by `point`.
+     */
+    rotation?: [number, number, number, number];
+    /** `#rrggbb`, sRGB — the same string `THREE.Color.set` takes. */
+    color: string;
+    intensity: number;
+    /** Metres; the light has no effect past it. Absent or 0 = physically unbounded (inverse square). */
+    range?: number;
+    /** Spot only: outer cone half-angle, radians. */
+    angle?: number;
+    /** Spot only: 0 (hard edge) .. 1 (fully soft). */
+    penumbra?: number;
+    /** Area: side of the square emitter (m). Point/spot: radius of the emitter for soft shadows (m). */
+    size?: number;
+    /** Default true. */
+    castShadow?: boolean;
+    /**
+     * The light group a preset scales ({@link WorldLightingPreset.groups}), e.g. `"street-lamps"`: Night
+     * sets it to 1, Day to 0. Absent = always on at full intensity.
+     */
+    group?: string;
+}
+/**
+ * One way of lighting a world — "Day", "Dusk", "Night". A world holds several; a game (or one track of
+ * it) picks one, and a bake is made per preset.
+ *
+ * The fields are exactly a live rig's, so a game can light itself from a preset with no translation:
+ * sun + unshadowed fill opposite it + hemisphere + flat ambient + a gradient sky used as both the
+ * background and the environment probe, then fog and exposure. Colours are sRGB `#rrggbb`.
+ */
+export interface WorldLightingPreset {
+    id: string;
+    name: string;
+    /** The shadow-casting sun (or moon). `intensity: 0` for none. Degrees; azimuth is measured from +X toward +Z. */
+    sun: {
+        azimuthDeg: number;
+        elevationDeg: number;
+        color: string;
+        intensity: number;
+    };
+    /** Unshadowed rim light from the sun's opposite side. */
+    fill?: {
+        color: string;
+        intensity: number;
+    };
+    /**
+     * Gradient sky, straight up → horizon → below it. It is the background AND the environment light
+     * (`scene.environment`, scaled by `intensity`), which is also how the bake lights the world with it.
+     */
+    sky: {
+        zenith: string;
+        horizon: string;
+        ground: string;
+        intensity: number;
+    };
+    hemisphere?: {
+        sky: string;
+        ground: string;
+        intensity: number;
+    };
+    ambient?: {
+        color: string;
+        intensity: number;
+    };
+    fog?: {
+        color: string;
+        near: number;
+        far: number;
+    };
+    /** Tone-mapping exposure (ACES filmic). Default 1. */
+    exposure?: number;
+    /** Multiplier per {@link WorldLight.group}. A group not listed is at 1. */
+    groups?: Record<string, number>;
+}
+/** A world's lighting: its presets, and which one a game gets when it asks for none. */
+export interface WorldLighting {
+    presets: WorldLightingPreset[];
+    defaultPresetId: string;
+}
+/**
+ * A baked scene: a scene's lighting cooked into lightmaps by Blender (see the platform's
+ * `docs/baked-lighting.md`), stored as ONE self-contained glb whose materials carry the
+ * `RYDR_lightmap` extension.
+ *
+ * It is a derived output, never a source: it records the fingerprints of what it was built from, and
+ * the moment either changes (a prop moved, a lamp added, a route re-drawn) it is **stale** and a game
+ * ignores it and renders live. `isBakeFresh` / `pickBake` decide that.
+ *
+ * Where it is stored says what it covers: on the world (`CoreWorld.bakes`) it covers the world alone;
+ * in a game's own document (a racing track) it also covers that game's layer — the road, barriers and
+ * kerbs the game generates — and `layer` identifies it.
+ */
+export interface SceneBake {
+    /** Format of the baked glb. 1 = `RYDR_lightmap` v1. */
+    format: 1;
+    id: string;
+    /** The {@link WorldLightingPreset.id} it was lit with. */
+    presetId: string;
+    glbUrl: string;
+    /** The {@link CoreWorld.id} it was built on. */
+    worldId: string;
+    /** `worldFingerprint(world, presetId)` at export time. */
+    worldFingerprint: string;
+    /** The game layer baked with it, when there is one. `fingerprint` is the game's own `layerFingerprint`. */
+    layer?: {
+        game: string;
+        docId: string;
+        fingerprint: string;
+    };
+    bakedAt: number;
+    stats?: {
+        atlases?: number;
+        atlasSize?: number;
+        bytes?: number;
+        samples?: number;
+        minutes?: number;
+        blender?: string;
+    };
 }
 /** Optional lighting/fog for a world. */
 export interface WorldEnv {
@@ -86,6 +237,13 @@ export interface CoreWorld {
     name: string;
     env?: WorldEnv;
     map: WorldMapDelta;
+    /**
+     * Lighting presets (Day, Night…). Optional: a world without it has at most the legacy `env`, which
+     * `lightingPresets()` reads as an implicit `"default"` preset.
+     */
+    lighting?: WorldLighting;
+    /** World-only bakes, one per preset (see {@link SceneBake}). A game's own layer keeps its bakes itself. */
+    bakes?: SceneBake[];
     createdAt: number;
     updatedAt: number;
 }
@@ -100,4 +258,27 @@ export interface CatalogItem {
 }
 /** The objectName used for the root of a baked single-object catalog glb. */
 export declare const CATALOG_ROOT_OBJECT = "root";
+/**
+ * The shared-content collection a game publishes its **reference layers** to (one doc per layer, in the
+ * game's own `shared` scope, which every client can read).
+ *
+ * A reference layer is a lightweight glb of what a GAME builds on top of a world — racing's road,
+ * barriers and kerbs — so the platform world editor can show it as a read-only ghost. That is what
+ * lets a world author place street lamps along a road that otherwise exists only in the game's code.
+ */
+export declare const WORLD_REFERENCES_COLLECTION = "world-references";
+/** One doc in {@link WORLD_REFERENCES_COLLECTION}. */
+export interface WorldReferenceLayer {
+    /** The {@link CoreWorld.id} it sits on. */
+    coreWorldId: string;
+    /** The publishing game's slug. */
+    game: string;
+    /** The game document it comes from (a racing track id). */
+    docId: string;
+    /** Shown in the editor's layer list, e.g. "Racing · Paris GP". */
+    label: string;
+    /** World-space glb (same frame as the world's own geometry). */
+    glbUrl: string;
+    updatedAt: number;
+}
 //# sourceMappingURL=worlds.d.ts.map

package/dist/protocol/worlds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worlds.d.ts","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,iFAAiF;IACjF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,aAAa,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"worlds.d.ts","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"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"}

package/dist/protocol/worlds.js

@@ -7,4 +7,13 @@
  */
 /** The objectName used for the root of a baked single-object catalog glb. */
 export const CATALOG_ROOT_OBJECT = "root";
+/**
+ * The shared-content collection a game publishes its **reference layers** to (one doc per layer, in the
+ * game's own `shared` scope, which every client can read).
+ *
+ * A reference layer is a lightweight glb of what a GAME builds on top of a world — racing's road,
+ * barriers and kerbs — so the platform world editor can show it as a read-only ghost. That is what
+ * lets a world author place street lamps along a road that otherwise exists only in the game's code.
+ */
+export const WORLD_REFERENCES_COLLECTION = "world-references";
 //# sourceMappingURL=worlds.js.map

package/dist/protocol/worlds.js.map

@@ -1 +1 @@
-{"version":3,"file":"worlds.js","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoGH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC"}
+{"version":3,"file":"worlds.js","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2OH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAAkB,CAAC"}

package/dist/three/README.md

@@ -166,6 +166,31 @@ dispose();
 Handles GLB loading, DRACO decompression, placement transforms, and a shared cache so the same world
 isn't re-downloaded. Prefer this over a per-game `GLTFLoader`. `clearWorldCache(id?)` evicts.
 
+## Baked lighting — `loadBakedScene`, presets, shadow catcher
+
+A platform world can carry lights and lighting presets (Day, Night…), and a scene baked from it in Blender
+(the platform's `docs/baked-lighting.md`). Show the bake while it still matches, live otherwise:
+
+```ts
+import { pickBake, resolvePreset, layerFingerprint } from "@rydr/game-sdk";
+import { loadBakedScene, createShadowCatcher, applyLightingPreset, loadWorld } from "@rydr/game-sdk/three";
+
+const preset = resolvePreset(world, myPresetId);
+const bake = pickBake(myBakes, { world, presetId: preset?.id, layerFingerprint: layerFingerprint(myLayer) });
+if (bake) {
+  const baked = await loadBakedScene(bake);          // unlit albedo × lightmap, cached by URL
+  baked.attach(scene);
+  createShadowCatcher(baked.receivers);               // moving things' live shadows on the baked road
+} else {
+  (await loadWorld(world)).attach(scene);
+}
+if (preset) applyLightingPreset(scene, preset, { renderer, shadows: true }); // lights the moving things
+```
+
+A baked material ignores live lights, so `createWorldLights(world, preset, { max, near })` can light a car
+with the world's lamps at no cost to the world. `RydrLightmapPlugin` is the `RYDR_lightmap` GLTFLoader
+plugin, for a loader of your own.
+
 ## `mergeByMaterial` — cut draw calls
 
 ```ts

package/dist/three/baked-lighting.d.ts

@@ -0,0 +1,144 @@
+/**
+ * baked-lighting — load a BAKED scene ({@link SceneBake}) and render it with its lightmaps.
+ *
+ * A baked scene is one self-contained glb produced by the platform's bake pipeline (Blender, see the
+ * platform repo's `docs/baked-lighting.md`): the world plus whatever a game baked with it, every static
+ * mesh carrying a second UV set (`TEXCOORD_1`) and a material extension, `RYDR_lightmap`, that points at
+ * the lightmap atlas it was baked into.
+ *
+ * ## What a lightmap holds, and how it is shown
+ *
+ * The light each surface RECEIVES (sun, sky, lamps, bounce) — not its colour. So a baked material is
+ * `albedo × lightmap`, which keeps the full detail of the colour textures at a low lightmap resolution,
+ * and it is a `MeshBasicMaterial`: the scene's live lights must not light it a second time. That is
+ * also why a baked world is CHEAPER than a live one — no per-pixel lighting at all.
+ *
+ * The atlas is an 8-bit sRGB PNG: the bake divides the light by a per-atlas `scale` before encoding,
+ * the GPU's sRGB decode undoes the curve for free, and `intensity` (= π × scale, the π cancelling
+ * `MeshBasicMaterial`'s Lambert term) puts the range back. No custom shader, no alpha channel for
+ * a browser to premultiply.
+ *
+ * ## What stays live
+ *
+ * Anything that moves. A car is still lit by the game's own sun + environment, and its shadow is put
+ * on the baked ground by a SHADOW CATCHER ({@link createShadowCatcher}): a `ShadowMaterial` overlay on
+ * the meshes the export marked as receivers (the road, the ground around it). Everything else in the
+ * baked scene casts and receives nothing live — its shadows are in the lightmap.
+ */
+import * as THREE from "three";
+import { GLTFLoader, type GLTFLoaderPlugin, type GLTFParser } from "three/addons/loaders/GLTFLoader.js";
+import { type GlbLoaderOptions } from "./world-loader.js";
+import type { SceneBake } from "../protocol/worlds.js";
+/** The glTF material extension a baked glb carries. */
+export declare const RYDR_LIGHTMAP_EXTENSION = "RYDR_lightmap";
+/** `materials[i].extensions.RYDR_lightmap`. */
+export interface RydrLightmapDef {
+    /** Index into the glb's `textures`. */
+    index: number;
+    /** Which UV set samples it. Always 1 from the pipeline. */
+    texCoord?: number;
+    /** `lightMapIntensity`: π × the atlas's encode scale. */
+    intensity: number;
+}
+/** Node extras the export writes and the bake carries through (see the platform's bake docs). */
+export declare const BAKE_EXTRAS: {
+    /** `"static"` (gets a lightmap) or `"occluder"` (casts in the bake, then dropped). */
+    readonly role: "rydr_role";
+    /** true on meshes a moving object's live shadow must land on (a road). */
+    readonly receiveShadow: "rydr_receive_shadow";
+    /** Texels per metre wanted for this mesh. */
+    readonly density: "rydr_lm_density";
+    /** Atlas preference, e.g. `"near-road"`. */
+    readonly atlasHint: "rydr_atlas_hint";
+    /** Written BY the bake: the atlas a mesh ended up in. */
+    readonly lightmap: "rydr_lightmap";
+    /**
+     * `"world"` (the platform world's geometry) or `"game"` (what the game added: a road, walls). Lets a
+     * game tell the two apart in a baked scene — racing probes the drivable height off the WORLD alone.
+     */
+    readonly layer: "rydr_layer";
+};
+/** Name of the empty node carrying the bake manifest (a JSON string in its extras). */
+export declare const BAKE_MANIFEST_NODE = "RYDR_BAKE_MANIFEST";
+/** The extras key on {@link BAKE_MANIFEST_NODE}. */
+export declare const BAKE_MANIFEST_KEY = "rydr_bake_manifest";
+/**
+ * GLTFLoader plugin for `RYDR_lightmap`: assigns the atlas as the material's `lightMap` on UV channel 1
+ * with the extension's intensity. Register it on any GLTFLoader that may meet a baked glb:
+ * `loader.register((parser) => new RydrLightmapPlugin(parser))`.
+ */
+export declare class RydrLightmapPlugin implements GLTFLoaderPlugin {
+    private readonly parser;
+    readonly name = "RYDR_lightmap";
+    constructor(parser: GLTFParser);
+    extendMaterialParams(materialIndex: number, materialParams: Record<string, unknown>): Promise<unknown>;
+}
+/** Add the {@link RydrLightmapPlugin} to a loader (idempotent per loader instance is the caller's job). */
+export declare function registerBakedLighting(loader: GLTFLoader): GLTFLoader;
+/**
+ * The material a baked mesh renders with: `albedo × lightmap`, unlit by the live rig.
+ *
+ * Returns `src` untouched when it has no lightmap (a mesh the bake skipped stays lit live, rather than
+ * turning black). Emissive surfaces keep their glow — a lit window IS its emission — via a two-line
+ * shader addition, since `MeshBasicMaterial` has no emissive of its own.
+ */
+export declare function toBakedMaterial(src: THREE.Material): THREE.Material;
+export interface LoadBakedSceneOptions extends GlbLoaderOptions {
+    /** Merge the static meshes by material (≈ one draw per material), as `loadWorld({ mergeStatics })`. */
+    mergeStatics?: boolean;
+}
+/** A loaded baked scene. Same lifecycle contract as `LoadedWorld`. */
+export interface LoadedBakedScene {
+    /** The glb's path — the cache key. */
+    readonly id: string;
+    readonly group: THREE.Group;
+    /** Meshes the export marked `rydr_receive_shadow` — hand them to {@link createShadowCatcher}. */
+    readonly receivers: THREE.Mesh[];
+    /** The manifest the export embedded (fingerprints, preset…), or null for a glb without one. */
+    readonly manifest: BakeManifest | null;
+    attach(parent: THREE.Object3D): void;
+    detach(): void;
+    dispose(): void;
+}
+/** What the export embeds in {@link BAKE_MANIFEST_NODE}. Parsed as-is; fields may grow. */
+export interface BakeManifest {
+    format: number;
+    worldId?: string;
+    presetId?: string;
+    worldFingerprint?: string;
+    layer?: {
+        game: string;
+        docId: string;
+        fingerprint: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Load (and cache by glb path) a baked scene, with every lightmapped material swapped for its
+ * {@link toBakedMaterial}. Pass the {@link SceneBake} (or its url). Rejects if the glb fails to load —
+ * the caller falls back to rendering live.
+ */
+export declare function loadBakedScene(bake: SceneBake | string, opts?: LoadBakedSceneOptions): Promise<LoadedBakedScene>;
+/** Drop cached baked scenes (all, or one glb path) and free them. */
+export declare function clearBakedSceneCache(url?: string): void;
+export interface ShadowCatcherOptions {
+    /** How dark a live shadow gets on the baked ground. Default 0.45. */
+    opacity?: number;
+}
+/** A shadow-catcher overlay; `dispose` removes and frees it. */
+export interface ShadowCatcher {
+    readonly meshes: THREE.Mesh[];
+    setOpacity(opacity: number): void;
+    dispose(): void;
+}
+/**
+ * Put a moving object's LIVE shadow on baked ground: one `ShadowMaterial` overlay per receiver, sharing
+ * its geometry and parented to it (so it follows exactly, at zero extra memory), drawn just in front
+ * of it with a polygon offset.
+ *
+ * It only darkens, which is the point — the receiver's own lighting is the lightmap and must not
+ * change. The catcher needs the game's sun to cast shadows as it already does; nothing else about the
+ * live rig changes.
+ */
+export declare function createShadowCatcher(receivers: readonly THREE.Mesh[], opts?: ShadowCatcherOptions): ShadowCatcher;
+//# sourceMappingURL=baked-lighting.d.ts.map

package/dist/three/baked-lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baked-lighting.d.ts","sourceRoot":"","sources":["../../src/three/baked-lighting.ts"],"names":[],"mappings":"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"}