@origingame/engine 0.2.0 → 0.3.0

package/knowledge/wiki/load.md

@@ -18,7 +18,7 @@ module load {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 3379</sub>
+<sub>`api.ogt` line 4818</sub>
 
 ## Contents
 
@@ -27,7 +27,7 @@ module load {
 | [`Asset`](#type-Asset) | handle | A loaded bundle, scene or glTF asset. |
 | [`Font`](#type-Font) | handle | A cooked MSDF font: its glyph table and one or more atlas pages. |
 | [`Sound`](#type-Sound) | handle | A cooked sound: QOA-encoded PCM the audio module plays. |
-| [`Skin`](#type-Skin) | handle | A cooked UI skin: its atlas, fonts, icons and sounds loaded with it, for og.ui.configure. |
+| [`Style`](#type-Style) | handle | A cooked UI style: its values, atlas, fonts, icons and sounds loaded with it, for og.ui.configure. |
 | [`TextureArray`](#type-TextureArray) | handle | A cooked texture array: same-sized layers uploaded as one 2D-array texture (og.load.textureArray). |
 | [`TextureArray()`](#column-TextureArray) | column kind | A TextureArray handle field (0 is none). |
 | [`Asset()`](#column-Asset) | column kind | An Asset handle field. |
@@ -51,11 +51,12 @@ module load {
 | [`og.load.lut`](#fn-lut) | function | A colour lookup table for PostEffects.lut, from a cooked `.cube` file (Adobe/Resolve 3D LUT; other sizes are resampled to 32). Loaded once per path. One in a streaming group's pack loads once its group is resident (refused before, naming the group); while the group is unloaded PostEffects.lut grades nothing with it, and it comes back under the same handle. |
 | [`og.load.environment`](#fn-environment) | function | A prefiltered environment map for Environment.map, from a cooked `.ogt` of `type environment`: `source` an equirectangular Radiance `.hdr` or OpenEXR `.exr` (the centre column faces +X, as three.js maps it) or a KTX2 cube map (six square faces +X -X +Y -Y +Z -Z with rows from the top; RGBA16F, RGB9E5, BC6H and the other HDR formats, decoded at cook time), or `faces` with six `.hdr`/`.exr` images in that order; `size` level 0's face size (a power of two, 16 to 2048, default 128), `intensity`, `rotation` (degrees about +Y) and `samples`. The cook prefilters it into a cube of five GGX levels (roughness 0 to 1) in RGB9E5 and the diffuse irradiance as nine harmonics, so loading only uploads it; `prefiltered true` takes a KTX2 cube's own mip chain as those levels instead (one already GGX-prefiltered by cmgen, IBLBaker or the glTF IBL sampler: level k of L at roughness k / (L - 1)), at the file's own size, without filtering it again. On the web it is fetched with the bundle like any blob; one in a streaming group's pack loads when its group is resident, and the sky lights the scene until then. Loaded once per path. |
 | [`og.load.emitter`](#fn-emitter) | function | A particle emitter asset for ParticleSystem.emitter, from a cooked `.ogt` of `type particles` (the og-game skill's Effects section gives every line with its default and an example; og-cook's fx module parses it): shape, rate and bursts, lifetime, speed, size and colour over life, gravity, drag, noise, a texture and sprite sheet, blending, collision, billboard or 2D sprite rendering. A sprite-mode emitter may draw from a texture array instead (`array "<id>" [<layers>] [off \| life <cycles> \| fps <n> \| random]`: each particle shows a layer by its age, at a rate, or one at random for its life; one draw per array whatever the layers; `round true` fades each particle to the soft dot's round edge). The textures and the array it names are loaded with it; while the array's streaming group is not resident its systems draw nothing. Loaded once per path. |
-| [`og.load.shader`](#fn-shader) | function | A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). Loaded once per path. |
+| [`og.load.shader`](#fn-shader) | function | A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). `mode hooks` (the default) defines hooks of the lit shader; `mode full lit` or `mode full unlit` defines `fn vertex(v: VertexInput, model: mat4x4<f32>, p: Params) -> VertexOutput` and `fn fragment(f: FragmentInput, p: Params) -> SurfaceOutput` over the binding contract (camera(), the model with its skin, Params, tex0 to tex7 for the material's eight texture slots; the og-game skill's Full custom shaders section), lit by the frame's lights or drawn as returned, the prepass and every shadow pass drawn through the same entries. Loaded once per path. |
+| [`og.load.post`](#fn-post) | function | A custom post pass for PostEffects.custom1 to custom8, from a cooked `.ogt` of `type post`: `code` or `source` (a `.wgsl` beside it) defining `fn post(f: PostInput, p: Params) -> vec4<f32>` and `param <name> float\|vec2\|vec3\|vec4\|color <default...>` lines (at most eight). The function reads previous(uv), scene_color(uv), depth(uv), normal(uv) and f.uv, f.pixel, f.size, f.time, and returns linear HDR colour (the og-game skill's Custom post passes section has the contract). The cook compiles it for every back end. Loaded once per path. |
 | [`og.load.texture`](#fn-texture) | function | Load a cooked texture for og.render.sprite and og.ui.image, as three.js TextureLoader.load. |
 | [`og.load.textureArray`](#fn-textureArray) | function | Load a cooked texture array (an `.ogt` of `type texture-array`: `kind color\|normal\|linear\|pixel` and one `layer "<file>"` per layer, 1 to 256 images of one size, each path beside the file or under assets/) and upload it as one 2D-array texture, its layers in file order, each in the encoding the device takes for its kind. Each layer is also a texture of its own, `<path>#layer<n>`, for og.load.texture. Loading the same path again answers the same array. |
-| [`og.load.skin`](#fn-skin) | function | Load a cooked UI skin (an `.ogt` of `type skin`: the atlas and its nine-slice frames, ornaments, palette, radii, type ramp, fonts, icons, motion and sounds; the grammar is og-ui's `skin` module) for UiDesc.skin. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path. |
-| [`og.load.look`](#fn-look) | function | Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `skin` (a UI skin's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut "luts/warm.cube"`, `palette "palettes/dusk.hex"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and skin it names are loaded with it. Loaded once per path. |
+| [`og.load.style`](#fn-style) | function | Load a cooked UI style (an `.ogt` of `type style`: every palette role, the radii, type ramp, durations, and its art: the atlas and its nine-slice frames, ornaments, fonts, icons, motion and sounds; the grammar is og-ui's `parse_style`) for UiDesc.style. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path. A built-in style a look names is in the bundle as `@styles/<name>/style.ogt`. |
+| [`og.load.look`](#fn-look) | function | Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `ui` (a UI style: a built-in style's slug, such as `cartoon`, or the game's own style file's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut "luts/warm.cube"`, `palette "palettes/dusk.hex"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and UI style it names are loaded with it. Loaded once per path. |
 | [`og.load.lookInfo`](#fn-lookInfo) | function | What a loaded look holds and sets. |
 | [`og.load.palette`](#fn-palette) | function | A colour palette for Stylise.palette, from a cooked `.hex` (one RRGGBB per line, as palette sites publish them) or GIMP `.gpl` file: up to 256 sRGB colours, in file order. Loaded once per path. One in a streaming group's pack loads once its group is resident; while the group is unloaded Stylise.palette quantises to no palette, and the palette comes back under the same handle. |
 | [`og.load.soundInfo`](#fn-soundInfo) | function | A loaded sound's format and length. |
@@ -66,6 +67,10 @@ module load {
 | [`og.load.rig`](#fn-rig) | function | Load a cooked humanoid map (an `.ogt` of `type rig`: a naming scheme and bones named outright) for og.anim.retarget and og.anim.humanoid. Loading the same path again answers the same handle. |
 | [`og.load.flipbook`](#fn-flipbook) | function | Load a cooked flipbook sheet (an `.ogt` of `type flipbook`, with its Aseprite or TexturePacker atlas resolved by the cook) and its texture, and register it with og.flipbook. A sheet with `array true` is cooked into a texture array instead (its frames, one size, cut out of the texture as layers): its sprites draw frame n as layer n, every sprite of the sheet one draw whichever frame each shows, and FlipbookInfo.array names the array. A sheet in a streaming group (its array and layers with it) loads once its group is resident (refused naming the group before), and its sprites draw nothing while the group is away. Loading the same path again answers the same handles. |
 | [`og.load.tilemap`](#fn-tilemap) | function | Load a cooked map (a tilemap `.ogt`, a Tiled `.tmj` or an LDtk `.ldtk`), its tilesets and their textures. Loading the same path again answers the same handles. |
+| [`og.load.video`](#fn-video) | function | Load cooked footage (an `.ogt` of `type video`: `source` an .mp4, .webm or .mov beside it or under assets/, `fps`, `maxSeconds`, `size W H`, `kind color\|pixel`, `audio`), which og cook turns with ffmpeg into a texture array of its frames and its sound track. Uploads the frames as one 2D-array texture and makes the video's Texture (VideoInfo.texture), which shows the frame its og.VideoPlayer is at: a material map, an og.Sprite or a UI image draws it like any texture. Load it in GameDesc.start (every process of an og render --jobs run loads it the same way, so its handles agree). Loading the same path again answers the same handles. |
+| [`og.load.videoInfo`](#fn-videoInfo) | function | A loaded video's size, frames, rate, length, texture and sound. |
+| [`og.load.timeline`](#fn-timeline) | function | Load a timeline: an `.ogt` of `type timeline` (the og.timeline module's file: duration, paths and tracks of keys), cooked with its caption files imported. Loaded once per path; play it with an og.Timeline whose asset is the handle, or `timeline:play:<name>` on the command channel. |
+| [`og.load.rig2d`](#fn-rig2d) | function | Load a cooked 2D rig (an `.ogt` of `type rig2d`, written by hand or imported by the cook from DragonBones JSON) and its texture, and register it with og.skeleton2d. Loading the same path again answers the same handles. |
 | [`og.AssetReady`](#record-AssetReady) | event | A load completed. |
 | [`og.AssetFailed`](#record-AssetFailed) | event | A load failed. |
 
@@ -99,7 +104,7 @@ fn bundle {
 }
 ```
 
-<sub>`api.ogt` line 3508</sub>
+<sub>`api.ogt` line 4957</sub>
 
 <a id="fn-bundleInfo"></a>
 
@@ -129,7 +134,7 @@ fn bundleInfo {
 }
 ```
 
-<sub>`api.ogt` line 3515</sub>
+<sub>`api.ogt` line 4964</sub>
 
 <a id="fn-defaultBundle"></a>
 
@@ -157,7 +162,7 @@ fn defaultBundle {
 }
 ```
 
-<sub>`api.ogt` line 3522</sub>
+<sub>`api.ogt` line 4971</sub>
 
 <a id="fn-gltf"></a>
 
@@ -192,7 +197,7 @@ fn gltf {
 }
 ```
 
-<sub>`api.ogt` line 3528</sub>
+<sub>`api.ogt` line 4977</sub>
 
 <a id="fn-scene"></a>
 
@@ -222,7 +227,7 @@ fn scene {
 }
 ```
 
-<sub>`api.ogt` line 3537</sub>
+<sub>`api.ogt` line 4986</sub>
 
 <a id="fn-font"></a>
 
@@ -252,7 +257,7 @@ fn font {
 }
 ```
 
-<sub>`api.ogt` line 3544</sub>
+<sub>`api.ogt` line 4993</sub>
 
 <a id="fn-fontInfo"></a>
 
@@ -282,7 +287,7 @@ fn fontInfo {
 }
 ```
 
-<sub>`api.ogt` line 3551</sub>
+<sub>`api.ogt` line 5000</sub>
 
 <a id="fn-sound"></a>
 
@@ -315,7 +320,7 @@ fn sound {
 }
 ```
 
-<sub>`api.ogt` line 3558</sub>
+<sub>`api.ogt` line 5007</sub>
 
 <a id="fn-lut"></a>
 
@@ -345,7 +350,7 @@ fn lut {
 }
 ```
 
-<sub>`api.ogt` line 3566</sub>
+<sub>`api.ogt` line 5015</sub>
 
 <a id="fn-environment"></a>
 
@@ -375,7 +380,7 @@ fn environment {
 }
 ```
 
-<sub>`api.ogt` line 3573</sub>
+<sub>`api.ogt` line 5022</sub>
 
 <a id="fn-emitter"></a>
 
@@ -405,13 +410,13 @@ fn emitter {
 }
 ```
 
-<sub>`api.ogt` line 3580</sub>
+<sub>`api.ogt` line 5029</sub>
 
 <a id="fn-shader"></a>
 
 ### `og.load.shader`
 
-A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). Loaded once per path.
+A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). `mode hooks` (the default) defines hooks of the lit shader; `mode full lit` or `mode full unlit` defines `fn vertex(v: VertexInput, model: mat4x4<f32>, p: Params) -> VertexOutput` and `fn fragment(f: FragmentInput, p: Params) -> SurfaceOutput` over the binding contract (camera(), the model with its skin, Params, tex0 to tex7 for the material's eight texture slots; the og-game skill's Full custom shaders section), lit by the frame's lights or drawn as returned, the prepass and every shadow pass drawn through the same entries. Loaded once per path.
 
 ```ts
 og.load.shader(world: World, path: string): Result<Shader>
@@ -428,14 +433,44 @@ Binding symbol `og_load_shader` · publish builds: kept
 
 ```ogt
 fn shader {
-  doc "A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). Loaded once per path."
+  doc "A material shader for og.render.shaderMaterial, from a cooked `.ogt` of `type shader` (its WGSL compiled by the cook for every back end). `mode hooks` (the default) defines hooks of the lit shader; `mode full lit` or `mode full unlit` defines `fn vertex(v: VertexInput, model: mat4x4<f32>, p: Params) -> VertexOutput` and `fn fragment(f: FragmentInput, p: Params) -> SurfaceOutput` over the binding contract (camera(), the model with its skin, Params, tex0 to tex7 for the material's eight texture slots; the og-game skill's Full custom shaders section), lit by the frame's lights or drawn as returned, the prepass and every shadow pass drawn through the same entries. Loaded once per path."
   param world World "The world whose renderer owns it."
   param path String "The asset id, such as `shaders/dissolve.ogt`."
   returns Result.Shader "Refused for a path not in the bundle or not a shader."
 }
 ```
 
-<sub>`api.ogt` line 3587</sub>
+<sub>`api.ogt` line 5036</sub>
+
+<a id="fn-post"></a>
+
+### `og.load.post`
+
+A custom post pass for PostEffects.custom1 to custom8, from a cooked `.ogt` of `type post`: `code` or `source` (a `.wgsl` beside it) defining `fn post(f: PostInput, p: Params) -> vec4<f32>` and `param <name> float|vec2|vec3|vec4|color <default...>` lines (at most eight). The function reads previous(uv), scene_color(uv), depth(uv), normal(uv) and f.uv, f.pixel, f.size, f.time, and returns linear HDR colour (the og-game skill's Custom post passes section has the contract). The cook compiles it for every back end. Loaded once per path.
+
+```ts
+og.load.post(world: World, path: string): Result<Post>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns it. |
+| `path` | `string` | no | The asset id, such as `post/crt.ogt`. |
+
+**Returns** `Result<Post>`: Refused for a path not in the bundle or not a post pass.
+
+Binding symbol `og_load_post` · publish builds: kept
+
+```ogt
+fn post {
+  doc "A custom post pass for PostEffects.custom1 to custom8, from a cooked `.ogt` of `type post`: `code` or `source` (a `.wgsl` beside it) defining `fn post(f: PostInput, p: Params) -> vec4<f32>` and `param <name> float|vec2|vec3|vec4|color <default...>` lines (at most eight). The function reads previous(uv), scene_color(uv), depth(uv), normal(uv) and f.uv, f.pixel, f.size, f.time, and returns linear HDR colour (the og-game skill's Custom post passes section has the contract). The cook compiles it for every back end. Loaded once per path."
+  param world World "The world whose renderer owns it."
+  param path String "The asset id, such as `post/crt.ogt`."
+  returns Result.Post "Refused for a path not in the bundle or not a post pass."
+}
+```
+
+<sub>`api.ogt` line 5043</sub>
 
 <a id="fn-texture"></a>
 
@@ -468,7 +503,7 @@ fn texture {
 }
 ```
 
-<sub>`api.ogt` line 3594</sub>
+<sub>`api.ogt` line 5050</sub>
 
 <a id="fn-textureArray"></a>
 
@@ -501,43 +536,43 @@ fn textureArray {
 }
 ```
 
-<sub>`api.ogt` line 3602</sub>
+<sub>`api.ogt` line 5058</sub>
 
-<a id="fn-skin"></a>
+<a id="fn-style"></a>
 
-### `og.load.skin`
+### `og.load.style`
 
-Load a cooked UI skin (an `.ogt` of `type skin`: the atlas and its nine-slice frames, ornaments, palette, radii, type ramp, fonts, icons, motion and sounds; the grammar is og-ui's `skin` module) for UiDesc.skin. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path.
+Load a cooked UI style (an `.ogt` of `type style`: every palette role, the radii, type ramp, durations, and its art: the atlas and its nine-slice frames, ornaments, fonts, icons, motion and sounds; the grammar is og-ui's `parse_style`) for UiDesc.style. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path. A built-in style a look names is in the bundle as `@styles/<name>/style.ogt`.
 
 ```ts
-og.load.skin(world: World, path: string): Result<Skin>
+og.load.style(world: World, path: string): Result<Style>
 ```
 
 | Parameter | Type | Optional | Doc |
 |---|---|---|---|
 | `world` | `World` | no | The world whose UI uses it. |
-| `path` | `string` | no | The asset id, such as `skins/pixel/skin.ogt`. |
+| `path` | `string` | no | The asset id, such as `styles/pixel/style.ogt` or `@styles/pixel/style.ogt`. |
 
-**Returns** `Result<Skin>`: Refused for a path not in the bundle, a skin that does not parse (the reason names the line) or an asset it names that cannot load.
+**Returns** `Result<Style>`: Refused for a path not in the bundle, a style that does not parse (the reason names the line) or an asset it names that cannot load.
 
-Binding symbol `og_load_skin` · publish builds: kept
+Binding symbol `og_load_style` · publish builds: kept
 
 ```ogt
-fn skin {
-  doc "Load a cooked UI skin (an `.ogt` of `type skin`: the atlas and its nine-slice frames, ornaments, palette, radii, type ramp, fonts, icons, motion and sounds; the grammar is og-ui's `skin` module) for UiDesc.skin. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path."
+fn style {
+  doc "Load a cooked UI style (an `.ogt` of `type style`: every palette role, the radii, type ramp, durations, and its art: the atlas and its nine-slice frames, ornaments, fonts, icons, motion and sounds; the grammar is og-ui's `parse_style`) for UiDesc.style. Its atlas, fonts, icons and sounds are loaded with it. Loaded once per path. A built-in style a look names is in the bundle as `@styles/<name>/style.ogt`."
   param world World "The world whose UI uses it."
-  param path String "The asset id, such as `skins/pixel/skin.ogt`."
-  returns Result.Skin "Refused for a path not in the bundle, a skin that does not parse (the reason names the line) or an asset it names that cannot load."
+  param path String "The asset id, such as `styles/pixel/style.ogt` or `@styles/pixel/style.ogt`."
+  returns Result.Style "Refused for a path not in the bundle, a style that does not parse (the reason names the line) or an asset it names that cannot load."
 }
 ```
 
-<sub>`api.ogt` line 3610</sub>
+<sub>`api.ogt` line 5066</sub>
 
 <a id="fn-look"></a>
 
 ### `og.load.look`
 
-Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `skin` (a UI skin's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut "luts/warm.cube"`, `palette "palettes/dusk.hex"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and skin it names are loaded with it. Loaded once per path.
+Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `ui` (a UI style: a built-in style's slug, such as `cartoon`, or the game's own style file's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut "luts/warm.cube"`, `palette "palettes/dusk.hex"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and UI style it names are loaded with it. Loaded once per path.
 
 ```ts
 og.load.look(world: World, path: string): Result<Look>
@@ -554,14 +589,14 @@ Binding symbol `og_load_look` · publish builds: kept
 
 ```ogt
 fn look {
-  doc "Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `skin` (a UI skin's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut \"luts/warm.cube\"`, `palette \"palettes/dusk.hex\"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and skin it names are loaded with it. Loaded once per path."
+  doc "Load a look: an `.ogt` of `type look` binding a frame's art direction as data. Its top-level `name`, `extends` (a built-in preset's slug, such as `anime-cel-3d`, or another look's asset id: the game's own `assets/looks/<slug>.ogt` wins over the built-in preset of that slug), `ui` (a UI style: a built-in style's slug, such as `cartoon`, or the game's own style file's asset id) and `antialias`, then one block per resource it sets (RenderSettings, PostEffects, Stylise, MaterialStyle, Fog, Sky, Environment) with that resource's fields by name, an asset id where a field is a handle (`lut \"luts/warm.cube\"`, `palette \"palettes/dusk.hex\"`). The cook validates every field against the resources' reflected schema and flattens `extends`, so the blob is the whole look. The textures, LUTs, palettes, environment map and UI style it names are loaded with it. Loaded once per path."
   param world World "The world whose renderer owns it."
   param path String "The asset id, such as `looks/main.ogt`."
   returns Result.Look "Refused for a path not in the bundle (the reason says to run og cook) or an asset it names that cannot load."
 }
 ```
 
-<sub>`api.ogt` line 3617</sub>
+<sub>`api.ogt` line 5073</sub>
 
 <a id="fn-lookInfo"></a>
 
@@ -591,7 +626,7 @@ fn lookInfo {
 }
 ```
 
-<sub>`api.ogt` line 3624</sub>
+<sub>`api.ogt` line 5080</sub>
 
 <a id="fn-palette"></a>
 
@@ -621,7 +656,7 @@ fn palette {
 }
 ```
 
-<sub>`api.ogt` line 3631</sub>
+<sub>`api.ogt` line 5087</sub>
 
 <a id="fn-soundInfo"></a>
 
@@ -651,7 +686,7 @@ fn soundInfo {
 }
 ```
 
-<sub>`api.ogt` line 3638</sub>
+<sub>`api.ogt` line 5094</sub>
 
 <a id="fn-status"></a>
 
@@ -681,7 +716,7 @@ fn status {
 }
 ```
 
-<sub>`api.ogt` line 3645</sub>
+<sub>`api.ogt` line 5101</sub>
 
 <a id="fn-error"></a>
 
@@ -711,7 +746,7 @@ fn error {
 }
 ```
 
-<sub>`api.ogt` line 3652</sub>
+<sub>`api.ogt` line 5108</sub>
 
 <a id="fn-gltfInfo"></a>
 
@@ -741,7 +776,7 @@ fn gltfInfo {
 }
 ```
 
-<sub>`api.ogt` line 3659</sub>
+<sub>`api.ogt` line 5115</sub>
 
 <a id="fn-animation"></a>
 
@@ -774,7 +809,7 @@ fn animation {
 }
 ```
 
-<sub>`api.ogt` line 3666</sub>
+<sub>`api.ogt` line 5122</sub>
 
 <a id="fn-rig"></a>
 
@@ -804,7 +839,7 @@ fn rig {
 }
 ```
 
-<sub>`api.ogt` line 3674</sub>
+<sub>`api.ogt` line 5130</sub>
 
 <a id="fn-flipbook"></a>
 
@@ -834,7 +869,7 @@ fn flipbook {
 }
 ```
 
-<sub>`api.ogt` line 3681</sub>
+<sub>`api.ogt` line 5137</sub>
 
 <a id="fn-tilemap"></a>
 
@@ -864,7 +899,127 @@ fn tilemap {
 }
 ```
 
-<sub>`api.ogt` line 3688</sub>
+<sub>`api.ogt` line 5144</sub>
+
+<a id="fn-video"></a>
+
+### `og.load.video`
+
+Load cooked footage (an `.ogt` of `type video`: `source` an .mp4, .webm or .mov beside it or under assets/, `fps`, `maxSeconds`, `size W H`, `kind color|pixel`, `audio`), which og cook turns with ffmpeg into a texture array of its frames and its sound track. Uploads the frames as one 2D-array texture and makes the video's Texture (VideoInfo.texture), which shows the frame its og.VideoPlayer is at: a material map, an og.Sprite or a UI image draws it like any texture. Load it in GameDesc.start (every process of an og render --jobs run loads it the same way, so its handles agree). Loading the same path again answers the same handles.
+
+```ts
+og.load.video(world: World, path: string): Result<VideoInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer and audio own it. |
+| `path` | `string` | no | The video's asset id: the `.ogt`, such as `clips/intro.ogt`. |
+
+**Returns** `Result<VideoInfo>`: Refused for a path not in the bundle (run og cook: a video needs ffmpeg there, og doctor) or not a video.
+
+Binding symbol `og_load_video` · publish builds: kept
+
+```ogt
+fn video {
+  doc "Load cooked footage (an `.ogt` of `type video`: `source` an .mp4, .webm or .mov beside it or under assets/, `fps`, `maxSeconds`, `size W H`, `kind color|pixel`, `audio`), which og cook turns with ffmpeg into a texture array of its frames and its sound track. Uploads the frames as one 2D-array texture and makes the video's Texture (VideoInfo.texture), which shows the frame its og.VideoPlayer is at: a material map, an og.Sprite or a UI image draws it like any texture. Load it in GameDesc.start (every process of an og render --jobs run loads it the same way, so its handles agree). Loading the same path again answers the same handles."
+  param world World "The world whose renderer and audio own it."
+  param path String "The video's asset id: the `.ogt`, such as `clips/intro.ogt`."
+  returns Result.VideoInfo "Refused for a path not in the bundle (run og cook: a video needs ffmpeg there, og doctor) or not a video."
+}
+```
+
+<sub>`api.ogt` line 5151</sub>
+
+<a id="fn-videoInfo"></a>
+
+### `og.load.videoInfo`
+
+A loaded video's size, frames, rate, length, texture and sound.
+
+```ts
+og.load.videoInfo(world: World, video: Video): Result<VideoInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world that loaded it. |
+| `video` | `Video` | no | The video. |
+
+**Returns** `Result<VideoInfo>`: Refused for a handle og.load.video did not answer.
+
+Binding symbol `og_load_video_info` · publish builds: kept
+
+```ogt
+fn videoInfo {
+  doc "A loaded video's size, frames, rate, length, texture and sound."
+  param world World "The world that loaded it."
+  param video Video "The video."
+  returns Result.VideoInfo "Refused for a handle og.load.video did not answer."
+}
+```
+
+<sub>`api.ogt` line 5158</sub>
+
+<a id="fn-timeline"></a>
+
+### `og.load.timeline`
+
+Load a timeline: an `.ogt` of `type timeline` (the og.timeline module's file: duration, paths and tracks of keys), cooked with its caption files imported. Loaded once per path; play it with an og.Timeline whose asset is the handle, or `timeline:play:<name>` on the command channel.
+
+```ts
+og.load.timeline(world: World, path: string): Result<TimelineAsset>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `path` | `string` | no | The timeline's asset id, such as `timelines/intro.ogt`. |
+
+**Returns** `Result<TimelineAsset>`: Refused for a path not in the bundle (run og cook) or a file that is not a timeline.
+
+Binding symbol `og_load_timeline` · publish builds: kept
+
+```ogt
+fn timeline {
+  doc "Load a timeline: an `.ogt` of `type timeline` (the og.timeline module's file: duration, paths and tracks of keys), cooked with its caption files imported. Loaded once per path; play it with an og.Timeline whose asset is the handle, or `timeline:play:<name>` on the command channel."
+  param world World "The world."
+  param path String "The timeline's asset id, such as `timelines/intro.ogt`."
+  returns Result.TimelineAsset "Refused for a path not in the bundle (run og cook) or a file that is not a timeline."
+}
+```
+
+<sub>`api.ogt` line 5165</sub>
+
+<a id="fn-rig2d"></a>
+
+### `og.load.rig2d`
+
+Load a cooked 2D rig (an `.ogt` of `type rig2d`, written by hand or imported by the cook from DragonBones JSON) and its texture, and register it with og.skeleton2d. Loading the same path again answers the same handles.
+
+```ts
+og.load.rig2d(world: World, path: string): Result<Rig2DInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose animation and renderer own it. |
+| `path` | `string` | no | The rig's asset id, such as `rigs/hero.ogt`. |
+
+**Returns** `Result<Rig2DInfo>`: Refused for a path not in the bundle (run og cook) or a texture it cannot load.
+
+Binding symbol `og_load_rig2d` · publish builds: kept
+
+```ogt
+fn rig2d {
+  doc "Load a cooked 2D rig (an `.ogt` of `type rig2d`, written by hand or imported by the cook from DragonBones JSON) and its texture, and register it with og.skeleton2d. Loading the same path again answers the same handles."
+  param world World "The world whose animation and renderer own it."
+  param path String "The rig's asset id, such as `rigs/hero.ogt`."
+  returns Result.Rig2DInfo "Refused for a path not in the bundle (run og cook) or a texture it cannot load."
+}
+```
+
+<sub>`api.ogt` line 5172</sub>
 
 ## Components, resources and events
 
@@ -887,6 +1042,9 @@ Token `og.Model`, registered under the schema name `og.Model`; its value type is
 | `castShadow` | `boolean` | `true` | — | — | — | Every mesh of the model casts shadows, as Mesh.castShadow: drawn into the sun's cascades and the shadowed lights' maps. On by default, unlike Mesh's (a loaded model casts, as it always has); false takes this instance out of every shadow pass. world.instantiate of a glTF and a scene's `model` line set it from the load's GltfDesc.castShadow, unless the scene gives the entity a `Model` table (whose castShadow is on unless it says false). |
 | `receiveShadow` | `boolean` | `true` | — | — | — | Every mesh of the model receives shadows, as Mesh.receiveShadow; false lights this instance as if unshadowed by every light. On by default. Set as castShadow is, from GltfDesc.receiveShadow or the scene's `Model` table. |
 | `visible` | `boolean` | `true` | — | — | — | Whether it is drawn, as Mesh.visible: false skips every draw of this instance (its meshes, its shadows) while it keeps its transform, its animation and its physics, so a ghost car or a pickup waiting to respawn is hidden without moving it away. |
+| `lodBias` | `number` | `1` | 0 … 16 | — | tunable | This instance's level of detail bias, multiplied with RenderSettings.lodBias: the cook simplifies every mesh into levels (a model's import settings, `model { lods 1 0.5 0.25 }` by default, the triangle fraction of each level; a glTF with MSFT_lod keeps its own levels), and the renderer draws the level its projected size calls for, with hysteresis so it does not flicker at the boundary. Above 1 keeps detail farther (a hero), below 1 drops it sooner (a crowd); 0 always draws the full mesh. dump_entity shows the level drawn. |
+| `layers` | `number` | `1` | — | — | — | Three.js layers of every mesh of the model, as Mesh.layers. |
+| `static` | `boolean` | `false` | — | — | — | Part of its scene's baked lighting: og bake lightmaps gives a static model lightmap UVs (xatlas, over its world-space triangles) and traces the light arriving at its surfaces from the scene into the scene's lightmap (`<scene>.lightmap.ogt` and `.ktx2` beside the scene). Once baked, the model draws with it (its ambient light from the lightmap instead of the sky; its lights' direct light, shadows and highlights still drawn every frame) for as long as the bake matches the scene. A scene entity says `static true` beside its `model` line; an unbaked static model draws as any model, and og doctor --project names the scene. |
 
 ```ogt
 component Model {
@@ -913,10 +1071,20 @@ component Model {
   field visible bool "Whether it is drawn, as Mesh.visible: false skips every draw of this instance (its meshes, its shadows) while it keeps its transform, its animation and its physics, so a ghost car or a pickup waiting to respawn is hidden without moving it away." {
     default true
   }
+  field lodBias f32 "This instance's level of detail bias, multiplied with RenderSettings.lodBias: the cook simplifies every mesh into levels (a model's import settings, `model { lods 1 0.5 0.25 }` by default, the triangle fraction of each level; a glTF with MSFT_lod keeps its own levels), and the renderer draws the level its projected size calls for, with hysteresis so it does not flicker at the boundary. Above 1 keeps detail farther (a hero), below 1 drops it sooner (a crowd); 0 always draws the full mesh. dump_entity shows the level drawn." {
+    default 1
+    min 0
+    max 16
+    tunable true
+  }
+  field layers u32 "Three.js layers of every mesh of the model, as Mesh.layers." {
+    default 1
+  }
+  field static bool "Part of its scene's baked lighting: og bake lightmaps gives a static model lightmap UVs (xatlas, over its world-space triangles) and traces the light arriving at its surfaces from the scene into the scene's lightmap (`<scene>.lightmap.ogt` and `.ktx2` beside the scene). Once baked, the model draws with it (its ambient light from the lightmap instead of the sky; its lights' direct light, shadows and highlights still drawn every frame) for as long as the bake matches the scene. A scene entity says `static true` beside its `model` line; an unbaked static model draws as any model, and og doctor --project names the scene."
 }
 ```
 
-<sub>`api.ogt` line 3482</sub>
+<sub>`api.ogt` line 4921</sub>
 
 <a id="record-AssetReady"></a>
 
@@ -939,7 +1107,7 @@ event AssetReady {
 }
 ```
 
-<sub>`api.ogt` line 3695</sub>
+<sub>`api.ogt` line 5179</sub>
 
 <a id="record-AssetFailed"></a>
 
@@ -964,7 +1132,7 @@ event AssetFailed {
 }
 ```
 
-<sub>`api.ogt` line 3701</sub>
+<sub>`api.ogt` line 5185</sub>
 
 ## Types
 
@@ -980,7 +1148,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Asset "A loaded bundle, scene or glTF asset."
 ```
 
-<sub>`api.ogt` line 3385</sub>
+<sub>`api.ogt` line 4824</sub>
 
 <a id="type-Font"></a>
 
@@ -994,7 +1162,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Font "A cooked MSDF font: its glyph table and one or more atlas pages."
 ```
 
-<sub>`api.ogt` line 3386</sub>
+<sub>`api.ogt` line 4825</sub>
 
 <a id="type-Sound"></a>
 
@@ -1008,21 +1176,21 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Sound "A cooked sound: QOA-encoded PCM the audio module plays."
 ```
 
-<sub>`api.ogt` line 3387</sub>
+<sub>`api.ogt` line 4826</sub>
 
-<a id="type-Skin"></a>
+<a id="type-Style"></a>
 
-### `Skin` (handle)
+### `Style` (handle)
 
-A cooked UI skin: its atlas, fonts, icons and sounds loaded with it, for og.ui.configure.
+A cooked UI style: its values, atlas, fonts, icons and sounds loaded with it, for og.ui.configure.
 
 A generational handle: a number the engine hands out. A dead handle is an error value, never a crash.
 
 ```ogt
-handle Skin "A cooked UI skin: its atlas, fonts, icons and sounds loaded with it, for og.ui.configure."
+handle Style "A cooked UI style: its values, atlas, fonts, icons and sounds loaded with it, for og.ui.configure."
 ```
 
-<sub>`api.ogt` line 3388</sub>
+<sub>`api.ogt` line 4827</sub>
 
 <a id="type-TextureArray"></a>
 
@@ -1036,7 +1204,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle TextureArray "A cooked texture array: same-sized layers uploaded as one 2D-array texture (og.load.textureArray)."
 ```
 
-<sub>`api.ogt` line 3389</sub>
+<sub>`api.ogt` line 4828</sub>
 
 <a id="type-LoadStatus"></a>
 
@@ -1061,7 +1229,7 @@ enum LoadStatus {
 }
 ```
 
-<sub>`api.ogt` line 3412</sub>
+<sub>`api.ogt` line 4851</sub>
 
 <a id="type-GltfDesc"></a>
 
@@ -1091,7 +1259,7 @@ struct GltfDesc {
 }
 ```
 
-<sub>`api.ogt` line 3419</sub>
+<sub>`api.ogt` line 4858</sub>
 
 <a id="type-GltfInfo"></a>
 
@@ -1116,7 +1284,7 @@ struct GltfInfo {
 }
 ```
 
-<sub>`api.ogt` line 3431</sub>
+<sub>`api.ogt` line 4870</sub>
 
 <a id="type-BundleInfo"></a>
 
@@ -1139,7 +1307,7 @@ struct BundleInfo {
 }
 ```
 
-<sub>`api.ogt` line 3439</sub>
+<sub>`api.ogt` line 4878</sub>
 
 <a id="type-FontInfo"></a>
 
@@ -1172,7 +1340,7 @@ struct FontInfo {
 }
 ```
 
-<sub>`api.ogt` line 3446</sub>
+<sub>`api.ogt` line 4885</sub>
 
 <a id="type-SoundInfo"></a>
 
@@ -1203,7 +1371,7 @@ struct SoundInfo {
 }
 ```
 
-<sub>`api.ogt` line 3458</sub>
+<sub>`api.ogt` line 4897</sub>
 
 <a id="type-TextureArrayInfo"></a>
 
@@ -1234,7 +1402,7 @@ struct TextureArrayInfo {
 }
 ```
 
-<sub>`api.ogt` line 3471</sub>
+<sub>`api.ogt` line 4910</sub>
 
 ## Column kinds
 
@@ -1255,7 +1423,7 @@ column TextureArray {
 }
 ```
 
-<sub>`api.ogt` line 3391</sub>
+<sub>`api.ogt` line 4830</sub>
 
 ```ogt
 column Asset {
@@ -1266,7 +1434,7 @@ column Asset {
 }
 ```
 
-<sub>`api.ogt` line 3398</sub>
+<sub>`api.ogt` line 4837</sub>
 
 ```ogt
 column Sound {
@@ -1277,4 +1445,4 @@ column Sound {
 }
 ```
 
-<sub>`api.ogt` line 3405</sub>
+<sub>`api.ogt` line 4844</sub>