@origingame/engine 0.4.0 → 0.5.0

package/knowledge/wiki/render.md

@@ -14,7 +14,7 @@ module render {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 2243</sub>
+<sub>`api.ogt` line 2244</sub>
 
 ## Contents
 
@@ -57,12 +57,15 @@ module render {
 | [`DofQuality()`](#column-DofQuality) | column kind | A DofQuality field: the variant's index. |
 | [`SpriteBlend`](#type-SpriteBlend) | enum | How a sprite is blended over what is below it. |
 | [`SpriteBlend()`](#column-SpriteBlend) | column kind | A SpriteBlend field: the variant's index. |
+| [`SpriteFacing`](#type-SpriteFacing) | enum | How a world sprite turns towards the camera that draws it: a billboard (three.js Sprite). Decided as a mode of og.Sprite and SpriteDesc rather than a component of its own: a billboard is the same quad, texture, region, flash, glow, blend, layer, drop shadow and texture array layer as any sprite, drawn by the same sprite batch and shader, which only stands its corners differently. The turn is computed on the GPU from each camera's own axes (the main camera, every og.CameraView and og.Mirror, every face of a reflection probe), so it never feeds back into the simulation and a snapshot holds only the mode. The sprite turns about its anchor (a nine-slice turns as one panel), `rotation` still turns it within its own plane, and its drop shadow is cast by the quad stood upright facing the sun, so it shows the whole shape from every camera. Within its layer a faced sprite without sortY draws back to front from the camera's eye (by view depth; a probe's six faces by distance from the probe), after the layer's drop shadows and before its unfaced sprites; and it is culled by its bounds (a sphere round the anchor through the farthest corner) against the camera's view. Sprites draw over the 3D scene after its transparent meshes and particles, depth tested and not depth writing, so a billboard behind a transparent mesh still draws over it. |
+| [`SpriteFacing()`](#column-SpriteFacing) | column kind | A SpriteFacing field: the variant's index. |
 | [`StripBlend`](#type-StripBlend) | enum | How a trail, ribbon or beam is blended. |
 | [`StripBlend()`](#column-StripBlend) | column kind | A StripBlend field: the variant's index. |
 | [`og.PostEffects`](#record-PostEffects) | resource | The post stack beyond RenderSettings' bloom, exposure and tone mapping, and camera shake. Every effect is off by default (its switch false or its amount 0) and then costs nothing: no pass is recorded. Read after each tick; it never feeds back into the simulation. |
 | [`Palette`](#type-Palette) | handle | A colour palette for Stylise.palette, from og.load.palette (a `.hex` or GIMP `.gpl` file of up to 256 colours). |
 | [`Look`](#type-Look) | handle | A look from og.load.look (an `.ogt` of `type look`): the frame's whole art direction as data, applied with og.render.applyLook. |
 | [`Palette()`](#column-Palette) | column kind | A Palette handle field (0 is none). |
+| [`Look()`](#column-Look) | column kind | A Look handle field (0 is none): a look og.load.look answered, kept for og.render.applyLook. |
 | [`DitherPattern`](#type-DitherPattern) | enum | The threshold pattern Stylise.dither spreads the steps of posterize and palette with. |
 | [`DitherPattern()`](#column-DitherPattern) | column kind | A DitherPattern field: the variant's index. |
 | [`StyliseSpace`](#type-StyliseSpace) | enum | Where Stylise lays a pattern (the paint canvas, the hatching, the halftone). |
@@ -84,9 +87,9 @@ module render {
 | [`TextDesc`](#type-TextDesc) | desc struct | A line or block of MSDF text in the world's xy plane facing +z, drawn this frame only (immediate mode: submit it every tick it should show). |
 | [`TextMeasureDesc`](#type-TextMeasureDesc) | desc struct | Text to measure with og.render.measureText, laid out as og.render.text lays it out. |
 | [`TextMetrics`](#type-TextMetrics) | struct | The extent of a laid-out text, in world units. |
-| [`SpriteDesc`](#type-SpriteDesc) | desc struct | A textured or solid quad in the world's xy plane facing +z, drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene. |
+| [`SpriteDesc`](#type-SpriteDesc) | desc struct | A textured or solid quad in the world's xy plane facing +z (or turned to the camera, `facing`), drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene. |
 | [`og.render.sprite`](#fn-sprite) | function | Draw a sprite this frame. Systems and commands may call it; the list is cleared at every tick, so submit it every tick the sprite should show. |
-| [`og.Sprite`](#record-Sprite) | component | A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame. |
+| [`og.Sprite`](#record-Sprite) | component | A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z, in the xy plane or turned to the camera by `facing`; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame. |
 | [`og.Afterimage`](#record-Afterimage) | component | Ghosts of the entity's og.Sprite: every `interval` ticks its pose (position, rotation, scale, frame, flips) is kept, and the last `count` are drawn behind it, fading from `opacity` to 0, tinted by color. A dash, a speed-up, a teleport. The history is world state (the og.sprite state block). |
 | [`FloatingTextDesc`](#type-FloatingTextDesc) | desc struct | A damage number or pickup text that pops at a point, rises, spreads and fades by itself (no per-tick submission). Deterministic: its drift comes from the tick and its order, and it is world state (the og.sprite state block). |
 | [`og.render.floatingText`](#fn-floatingText) | function | Spawn a floating text (damage numbers, +coins, `blocked`). It lives `lifetime` seconds of scaled time on its own; systems and commands may call it. |
@@ -108,6 +111,7 @@ module render {
 | [`og.render.standardMaterial`](#fn-standardMaterial) | function | Create a standard material. |
 | [`og.render.updateMaterial`](#fn-updateMaterial) | function | Change some parameters of a standard material. |
 | [`Shader`](#type-Shader) | handle | A material shader from og.load.shader (an `.ogt` of `type shader`): WGSL hooks of the lit shader, or with `mode full` its own vertex and fragment entries, and the parameters they read. |
+| [`Shader()`](#column-Shader) | column kind | A Shader handle field (0 is none): a material shader og.load.shader answered, kept for og.render.shaderMaterial. |
 | [`og.render.shaderMaterial`](#fn-shaderMaterial) | function | Create a standard material that draws with a material shader's hooks (vertex_offset, surface_color, surface_normal, surface_emissive; the og-game skill's Material shaders section has their WGSL contract), its parameters at their defaults. The hooks apply to skinned meshes too, and shadows and the depth prepass (ambient occlusion, outlines, depth of field) see the mesh where vertex_offset moved it and cut where surface_color's alpha falls below alphaTest. |
 | [`og.render.setMaterialShader`](#fn-setMaterialShader) | function | Give an existing material a material shader, or take it away with null: a loaded model's material (GltfInfo.materials) draws its skinned or static meshes through the hooks, with the shader's parameters at their defaults. Every mesh drawn with that material changes. |
 | [`og.render.setShaderParam`](#fn-setShaderParam) | function | Set a parameter of a shader material, by the name its shader declares: a number for float, two to four for vec2, vec3, vec4 and color. |
@@ -220,7 +224,7 @@ fn ribbon {
 }
 ```
 
-<sub>`api.ogt` line 3584</sub>
+<sub>`api.ogt` line 3606</sub>
 
 <a id="fn-sprite"></a>
 
@@ -250,7 +254,7 @@ fn sprite {
 }
 ```
 
-<sub>`api.ogt` line 3712</sub>
+<sub>`api.ogt` line 3735</sub>
 
 <a id="fn-floatingText"></a>
 
@@ -280,7 +284,7 @@ fn floatingText {
 }
 ```
 
-<sub>`api.ogt` line 3892</sub>
+<sub>`api.ogt` line 3916</sub>
 
 <a id="fn-measureText"></a>
 
@@ -310,7 +314,7 @@ fn measureText {
 }
 ```
 
-<sub>`api.ogt` line 3899</sub>
+<sub>`api.ogt` line 3923</sub>
 
 <a id="fn-boxGeometry"></a>
 
@@ -340,7 +344,7 @@ fn boxGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3968</sub>
+<sub>`api.ogt` line 3992</sub>
 
 <a id="fn-planeGeometry"></a>
 
@@ -370,7 +374,7 @@ fn planeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3975</sub>
+<sub>`api.ogt` line 3999</sub>
 
 <a id="fn-sphereGeometry"></a>
 
@@ -400,7 +404,7 @@ fn sphereGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3982</sub>
+<sub>`api.ogt` line 4006</sub>
 
 <a id="fn-standardMaterial"></a>
 
@@ -430,7 +434,7 @@ fn standardMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4064</sub>
+<sub>`api.ogt` line 4088</sub>
 
 <a id="fn-updateMaterial"></a>
 
@@ -462,7 +466,7 @@ fn updateMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4071</sub>
+<sub>`api.ogt` line 4095</sub>
 
 <a id="fn-shaderMaterial"></a>
 
@@ -494,7 +498,7 @@ fn shaderMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4081</sub>
+<sub>`api.ogt` line 4112</sub>
 
 <a id="fn-setMaterialShader"></a>
 
@@ -526,7 +530,7 @@ fn setMaterialShader {
 }
 ```
 
-<sub>`api.ogt` line 4089</sub>
+<sub>`api.ogt` line 4120</sub>
 
 <a id="fn-setShaderParam"></a>
 
@@ -560,7 +564,7 @@ fn setShaderParam {
 }
 ```
 
-<sub>`api.ogt` line 4097</sub>
+<sub>`api.ogt` line 4128</sub>
 
 <a id="fn-applyLook"></a>
 
@@ -590,7 +594,7 @@ fn applyLook {
 }
 ```
 
-<sub>`api.ogt` line 4106</sub>
+<sub>`api.ogt` line 4137</sub>
 
 <a id="fn-applyQuality"></a>
 
@@ -644,7 +648,7 @@ fn applyQuality {
 }
 ```
 
-<sub>`api.ogt` line 4113</sub>
+<sub>`api.ogt` line 4144</sub>
 
 <a id="fn-look"></a>
 
@@ -672,7 +676,7 @@ fn look {
 }
 ```
 
-<sub>`api.ogt` line 4131</sub>
+<sub>`api.ogt` line 4162</sub>
 
 <a id="fn-capabilities"></a>
 
@@ -700,7 +704,7 @@ fn capabilities {
 }
 ```
 
-<sub>`api.ogt` line 4137</sub>
+<sub>`api.ogt` line 4168</sub>
 
 <a id="fn-text"></a>
 
@@ -730,7 +734,7 @@ fn text {
 }
 ```
 
-<sub>`api.ogt` line 4143</sub>
+<sub>`api.ogt` line 4174</sub>
 
 <a id="fn-bufferGeometry"></a>
 
@@ -760,7 +764,7 @@ fn bufferGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4181</sub>
+<sub>`api.ogt` line 4212</sub>
 
 <a id="fn-updateGeometry"></a>
 
@@ -792,7 +796,7 @@ fn updateGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4188</sub>
+<sub>`api.ogt` line 4219</sub>
 
 <a id="fn-geometryInfo"></a>
 
@@ -822,7 +826,7 @@ fn geometryInfo {
 }
 ```
 
-<sub>`api.ogt` line 4196</sub>
+<sub>`api.ogt` line 4227</sub>
 
 <a id="fn-cylinderGeometry"></a>
 
@@ -852,7 +856,7 @@ fn cylinderGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4391</sub>
+<sub>`api.ogt` line 4422</sub>
 
 <a id="fn-coneGeometry"></a>
 
@@ -882,7 +886,7 @@ fn coneGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4398</sub>
+<sub>`api.ogt` line 4429</sub>
 
 <a id="fn-capsuleGeometry"></a>
 
@@ -912,7 +916,7 @@ fn capsuleGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4405</sub>
+<sub>`api.ogt` line 4436</sub>
 
 <a id="fn-torusGeometry"></a>
 
@@ -942,7 +946,7 @@ fn torusGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4412</sub>
+<sub>`api.ogt` line 4443</sub>
 
 <a id="fn-ringGeometry"></a>
 
@@ -972,7 +976,7 @@ fn ringGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4419</sub>
+<sub>`api.ogt` line 4450</sub>
 
 <a id="fn-circleGeometry"></a>
 
@@ -1002,7 +1006,7 @@ fn circleGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4426</sub>
+<sub>`api.ogt` line 4457</sub>
 
 <a id="fn-tubeGeometry"></a>
 
@@ -1032,7 +1036,7 @@ fn tubeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4433</sub>
+<sub>`api.ogt` line 4464</sub>
 
 <a id="fn-shapeGeometry"></a>
 
@@ -1062,7 +1066,7 @@ fn shapeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4670</sub>
+<sub>`api.ogt` line 4701</sub>
 
 <a id="fn-extrudeGeometry"></a>
 
@@ -1092,7 +1096,7 @@ fn extrudeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4677</sub>
+<sub>`api.ogt` line 4708</sub>
 
 <a id="fn-latheGeometry"></a>
 
@@ -1122,7 +1126,7 @@ fn latheGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4684</sub>
+<sub>`api.ogt` line 4715</sub>
 
 <a id="fn-polyhedronGeometry"></a>
 
@@ -1152,7 +1156,7 @@ fn polyhedronGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4691</sub>
+<sub>`api.ogt` line 4722</sub>
 
 <a id="fn-icosahedronGeometry"></a>
 
@@ -1182,7 +1186,7 @@ fn icosahedronGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4698</sub>
+<sub>`api.ogt` line 4729</sub>
 
 <a id="fn-dodecahedronGeometry"></a>
 
@@ -1212,7 +1216,7 @@ fn dodecahedronGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4705</sub>
+<sub>`api.ogt` line 4736</sub>
 
 <a id="fn-octahedronGeometry"></a>
 
@@ -1242,7 +1246,7 @@ fn octahedronGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4712</sub>
+<sub>`api.ogt` line 4743</sub>
 
 <a id="fn-tetrahedronGeometry"></a>
 
@@ -1272,7 +1276,7 @@ fn tetrahedronGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4719</sub>
+<sub>`api.ogt` line 4750</sub>
 
 <a id="fn-sweepGeometry"></a>
 
@@ -1302,7 +1306,7 @@ fn sweepGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4726</sub>
+<sub>`api.ogt` line 4757</sub>
 
 <a id="fn-csgGeometry"></a>
 
@@ -1332,7 +1336,7 @@ fn csgGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4733</sub>
+<sub>`api.ogt` line 4764</sub>
 
 <a id="fn-mergeGeometries"></a>
 
@@ -1362,7 +1366,7 @@ fn mergeGeometries {
 }
 ```
 
-<sub>`api.ogt` line 4740</sub>
+<sub>`api.ogt` line 4771</sub>
 
 <a id="fn-lines"></a>
 
@@ -1392,7 +1396,7 @@ fn lines {
 }
 ```
 
-<sub>`api.ogt` line 4798</sub>
+<sub>`api.ogt` line 4829</sub>
 
 <a id="fn-points"></a>
 
@@ -1422,7 +1426,7 @@ fn points {
 }
 ```
 
-<sub>`api.ogt` line 4833</sub>
+<sub>`api.ogt` line 4864</sub>
 
 <a id="fn-raycast"></a>
 
@@ -1454,7 +1458,7 @@ fn raycast {
 }
 ```
 
-<sub>`api.ogt` line 4937</sub>
+<sub>`api.ogt` line 4968</sub>
 
 <a id="fn-renderTarget"></a>
 
@@ -1484,7 +1488,7 @@ fn renderTarget {
 }
 ```
 
-<sub>`api.ogt` line 4993</sub>
+<sub>`api.ogt` line 5024</sub>
 
 <a id="fn-setPostParam"></a>
 
@@ -1518,7 +1522,7 @@ fn setPostParam {
 }
 ```
 
-<sub>`api.ogt` line 5105</sub>
+<sub>`api.ogt` line 5136</sub>
 
 <a id="fn-postErrors"></a>
 
@@ -1546,7 +1550,7 @@ fn postErrors {
 }
 ```
 
-<sub>`api.ogt` line 5120</sub>
+<sub>`api.ogt` line 5151</sub>
 
 <a id="fn-bakedLighting"></a>
 
@@ -1574,7 +1578,7 @@ fn bakedLighting {
 }
 ```
 
-<sub>`api.ogt` line 5188</sub>
+<sub>`api.ogt` line 5219</sub>
 
 ## Components, resources and events
 
@@ -1632,7 +1636,7 @@ component Mesh {
 }
 ```
 
-<sub>`api.ogt` line 2511</sub>
+<sub>`api.ogt` line 2512</sub>
 
 <a id="record-DirectionalLight"></a>
 
@@ -1687,7 +1691,7 @@ component DirectionalLight {
 }
 ```
 
-<sub>`api.ogt` line 2541</sub>
+<sub>`api.ogt` line 2542</sub>
 
 <a id="record-PointLight"></a>
 
@@ -1730,7 +1734,7 @@ component PointLight {
 }
 ```
 
-<sub>`api.ogt` line 2573</sub>
+<sub>`api.ogt` line 2574</sub>
 
 <a id="record-SpotLight"></a>
 
@@ -1784,7 +1788,7 @@ component SpotLight {
 }
 ```
 
-<sub>`api.ogt` line 2594</sub>
+<sub>`api.ogt` line 2595</sub>
 
 <a id="record-RenderSettings"></a>
 
@@ -1912,7 +1916,7 @@ resource RenderSettings {
 }
 ```
 
-<sub>`api.ogt` line 2662</sub>
+<sub>`api.ogt` line 2663</sub>
 
 <a id="record-Environment"></a>
 
@@ -1952,7 +1956,7 @@ resource Environment {
 }
 ```
 
-<sub>`api.ogt` line 2778</sub>
+<sub>`api.ogt` line 2779</sub>
 
 <a id="record-PostEffects"></a>
 
@@ -2227,7 +2231,7 @@ resource PostEffects {
 }
 ```
 
-<sub>`api.ogt` line 2858</sub>
+<sub>`api.ogt` line 2873</sub>
 
 <a id="record-Stylise"></a>
 
@@ -2482,7 +2486,7 @@ resource Stylise {
 }
 ```
 
-<sub>`api.ogt` line 3107</sub>
+<sub>`api.ogt` line 3129</sub>
 
 <a id="record-MaterialStyle"></a>
 
@@ -2547,7 +2551,7 @@ resource MaterialStyle {
 }
 ```
 
-<sub>`api.ogt` line 3300</sub>
+<sub>`api.ogt` line 3322</sub>
 
 <a id="record-Lighting2D"></a>
 
@@ -2586,7 +2590,7 @@ resource Lighting2D {
 }
 ```
 
-<sub>`api.ogt` line 3350</sub>
+<sub>`api.ogt` line 3372</sub>
 
 <a id="record-Light2D"></a>
 
@@ -2637,7 +2641,7 @@ component Light2D {
 }
 ```
 
-<sub>`api.ogt` line 3369</sub>
+<sub>`api.ogt` line 3391</sub>
 
 <a id="record-Occluder2D"></a>
 
@@ -2668,7 +2672,7 @@ component Occluder2D {
 }
 ```
 
-<sub>`api.ogt` line 3399</sub>
+<sub>`api.ogt` line 3421</sub>
 
 <a id="record-Decal"></a>
 
@@ -2723,7 +2727,7 @@ component Decal {
 }
 ```
 
-<sub>`api.ogt` line 3413</sub>
+<sub>`api.ogt` line 3435</sub>
 
 <a id="record-ParticleSystem"></a>
 
@@ -2760,7 +2764,7 @@ component ParticleSystem {
 }
 ```
 
-<sub>`api.ogt` line 3447</sub>
+<sub>`api.ogt` line 3469</sub>
 
 <a id="record-Trail"></a>
 
@@ -2836,7 +2840,7 @@ component Trail {
 }
 ```
 
-<sub>`api.ogt` line 3463</sub>
+<sub>`api.ogt` line 3485</sub>
 
 <a id="record-Beam"></a>
 
@@ -2902,13 +2906,13 @@ component Beam {
 }
 ```
 
-<sub>`api.ogt` line 3511</sub>
+<sub>`api.ogt` line 3533</sub>
 
 <a id="record-Sprite"></a>
 
 ### `og.Sprite` (component)
 
-A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame.
+A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z, in the xy plane or turned to the camera by `facing`; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame.
 
 Sorted with the immediate sprites and text by layer, then (sortY) by y, then texture: one draw per run of one texture. Tile layers draw before the sprites of their layer.
 
@@ -2928,6 +2932,7 @@ Token `og.Sprite`, registered under the schema name `og.Sprite`; its value type
 | `uvMax` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | The texture region's bottom-right corner, v down. |
 | `layer` | `number` | `0` | — | — | — | Draw order among sprites, tiles and text; higher draws on top. |
 | `sortY` | `boolean` | `false` | — | — | — | Within its layer, lower y draws in front: top-down characters, props and trees overlap by their feet. |
+| `facing` | `SpriteFacing` | `"none"` | — | — | — | A billboard (SpriteDesc.facing): none keeps the quad in the world's xy plane; camera turns it into each camera's view plane; cameraY stands it upright turned about y towards the camera, for trees and characters in a 3D set. Its afterimages face as it does; its blob shadow stays flat. |
 | `flipX` | `boolean` | `false` | — | — | — | Mirror left to right (a character facing left). |
 | `flipY` | `boolean` | `false` | — | — | — | Mirror top to bottom. |
 | `flash` | `number` | `0` | 0 … 1 | — | tunable | A hit flash: the colour mixed towards flashColor by this much (og.tween.flash fades it out). |
@@ -2949,7 +2954,7 @@ Token `og.Sprite`, registered under the schema name `og.Sprite`; its value type
 
 ```ogt
 component Sprite {
-  doc "A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame."
+  doc "A sprite drawn every frame at the entity's MatrixWorld (its xy and z, its rotation about z, in the xy plane or turned to the camera by `facing`; its scale multiplies width and height, so squash and stretch is a tween of og.Transform.scale). With an og.Flipbook on the entity, the texture (or an `array true` sheet's texture array layer), region and anchor come from the flipbook's current frame."
   doc "Sorted with the immediate sprites and text by layer, then (sortY) by y, then texture: one draw per run of one texture. Tile layers draw before the sprites of their layer."
   field texture Texture "The texture (og.load.texture); 0 draws a solid quad of the colour."
   field array TextureArray "Draw from a layer of this texture array (og.load.textureArray) instead of `texture`; 0 uses `texture`. Every sprite of one array is one draw whichever layer each shows. While the array's streaming group is not resident the sprite draws nothing."
@@ -2984,6 +2989,7 @@ component Sprite {
   }
   field layer i32 "Draw order among sprites, tiles and text; higher draws on top."
   field sortY bool "Within its layer, lower y draws in front: top-down characters, props and trees overlap by their feet."
+  field facing SpriteFacing "A billboard (SpriteDesc.facing): none keeps the quad in the world's xy plane; camera turns it into each camera's view plane; cameraY stands it upright turned about y towards the camera, for trees and characters in a 3D set. Its afterimages face as it does; its blob shadow stays flat."
   field flipX bool "Mirror left to right (a character facing left)."
   field flipY bool "Mirror top to bottom."
   field flash f32 "A hit flash: the colour mixed towards flashColor by this much (og.tween.flash fades it out)." {
@@ -3037,7 +3043,7 @@ component Sprite {
 }
 ```
 
-<sub>`api.ogt` line 3719</sub>
+<sub>`api.ogt` line 3742</sub>
 
 <a id="record-Afterimage"></a>
 
@@ -3085,7 +3091,7 @@ component Afterimage {
 }
 ```
 
-<sub>`api.ogt` line 3807</sub>
+<sub>`api.ogt` line 3831</sub>
 
 <a id="record-ReflectionProbe"></a>
 
@@ -3138,7 +3144,7 @@ component ReflectionProbe {
 }
 ```
 
-<sub>`api.ogt` line 4032</sub>
+<sub>`api.ogt` line 4056</sub>
 
 <a id="record-Lines"></a>
 
@@ -3201,7 +3207,7 @@ component Lines {
 }
 ```
 
-<sub>`api.ogt` line 4840</sub>
+<sub>`api.ogt` line 4871</sub>
 
 <a id="record-Points"></a>
 
@@ -3255,7 +3261,7 @@ component Points {
 }
 ```
 
-<sub>`api.ogt` line 4877</sub>
+<sub>`api.ogt` line 4908</sub>
 
 <a id="record-CameraView"></a>
 
@@ -3362,7 +3368,7 @@ component CameraView {
 }
 ```
 
-<sub>`api.ogt` line 5000</sub>
+<sub>`api.ogt` line 5031</sub>
 
 <a id="record-Mirror"></a>
 
@@ -3407,7 +3413,7 @@ component Mirror {
 }
 ```
 
-<sub>`api.ogt` line 5072</sub>
+<sub>`api.ogt` line 5103</sub>
 
 <a id="record-RectLight"></a>
 
@@ -3457,7 +3463,7 @@ component RectLight {
 }
 ```
 
-<sub>`api.ogt` line 5134</sub>
+<sub>`api.ogt` line 5165</sub>
 
 <a id="record-LightVolume"></a>
 
@@ -3491,7 +3497,7 @@ component LightVolume {
 }
 ```
 
-<sub>`api.ogt` line 5161</sub>
+<sub>`api.ogt` line 5192</sub>
 
 ## Types
 
@@ -3507,7 +3513,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Geometry "Vertex and index data, as three.js BufferGeometry. Comes from a loaded glTF."
 ```
 
-<sub>`api.ogt` line 2247</sub>
+<sub>`api.ogt` line 2248</sub>
 
 <a id="type-Material"></a>
 
@@ -3521,7 +3527,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Material "A material instance."
 ```
 
-<sub>`api.ogt` line 2248</sub>
+<sub>`api.ogt` line 2249</sub>
 
 <a id="type-Texture"></a>
 
@@ -3535,7 +3541,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Texture "A cooked texture."
 ```
 
-<sub>`api.ogt` line 2249</sub>
+<sub>`api.ogt` line 2250</sub>
 
 <a id="type-Side"></a>
 
@@ -3560,7 +3566,7 @@ enum Side {
 }
 ```
 
-<sub>`api.ogt` line 2265</sub>
+<sub>`api.ogt` line 2266</sub>
 
 <a id="type-RenderTier"></a>
 
@@ -3591,7 +3597,7 @@ enum RenderTier {
 }
 ```
 
-<sub>`api.ogt` line 2272</sub>
+<sub>`api.ogt` line 2273</sub>
 
 <a id="type-Antialias"></a>
 
@@ -3620,7 +3626,7 @@ enum Antialias {
 }
 ```
 
-<sub>`api.ogt` line 2282</sub>
+<sub>`api.ogt` line 2283</sub>
 
 <a id="type-PointShadows"></a>
 
@@ -3645,7 +3651,7 @@ enum PointShadows {
 }
 ```
 
-<sub>`api.ogt` line 2291</sub>
+<sub>`api.ogt` line 2292</sub>
 
 <a id="type-TaaHistory"></a>
 
@@ -3668,7 +3674,7 @@ enum TaaHistory {
 }
 ```
 
-<sub>`api.ogt` line 2298</sub>
+<sub>`api.ogt` line 2299</sub>
 
 <a id="type-DebugView"></a>
 
@@ -3697,7 +3703,7 @@ enum DebugView {
 }
 ```
 
-<sub>`api.ogt` line 2304</sub>
+<sub>`api.ogt` line 2305</sub>
 
 <a id="type-RenderOptions"></a>
 
@@ -3737,7 +3743,7 @@ struct RenderOptions {
 }
 ```
 
-<sub>`api.ogt` line 2313</sub>
+<sub>`api.ogt` line 2314</sub>
 
 <a id="type-StandardMaterialDesc"></a>
 
@@ -4007,7 +4013,7 @@ struct StandardMaterialDesc {
 }
 ```
 
-<sub>`api.ogt` line 2332</sub>
+<sub>`api.ogt` line 2333</sub>
 
 <a id="type-ToneMapping"></a>
 
@@ -4032,7 +4038,7 @@ enum ToneMapping {
 }
 ```
 
-<sub>`api.ogt` line 2626</sub>
+<sub>`api.ogt` line 2627</sub>
 
 <a id="type-GraphicsQuality"></a>
 
@@ -4057,7 +4063,7 @@ enum GraphicsQuality {
 }
 ```
 
-<sub>`api.ogt` line 2640</sub>
+<sub>`api.ogt` line 2641</sub>
 
 <a id="type-QualityPreset"></a>
 
@@ -4084,7 +4090,7 @@ enum QualityPreset {
 }
 ```
 
-<sub>`api.ogt` line 2647</sub>
+<sub>`api.ogt` line 2648</sub>
 
 <a id="type-Lut"></a>
 
@@ -4098,7 +4104,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Lut "A colour lookup table for PostEffects.lut, from og.load.lut (a `.cube` file)."
 ```
 
-<sub>`api.ogt` line 2753</sub>
+<sub>`api.ogt` line 2754</sub>
 
 <a id="type-EnvironmentMap"></a>
 
@@ -4112,7 +4118,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle EnvironmentMap "A prefiltered HDR environment map for Environment.map, from og.load.environment (an `.ogt` of `type environment` naming an equirectangular `.hdr` or `.exr`, a KTX2 cube map, or six face images)."
 ```
 
-<sub>`api.ogt` line 2754</sub>
+<sub>`api.ogt` line 2755</sub>
 
 <a id="type-ParticleEmitter"></a>
 
@@ -4126,7 +4132,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle ParticleEmitter "A particle emitter asset for ParticleSystem.emitter, from og.load.emitter (an `.ogt` of `type particles`)."
 ```
 
-<sub>`api.ogt` line 2755</sub>
+<sub>`api.ogt` line 2756</sub>
 
 <a id="type-AoMethod"></a>
 
@@ -4151,7 +4157,7 @@ enum AoMethod {
 }
 ```
 
-<sub>`api.ogt` line 2805</sub>
+<sub>`api.ogt` line 2806</sub>
 
 <a id="type-DofQuality"></a>
 
@@ -4174,7 +4180,7 @@ enum DofQuality {
 }
 ```
 
-<sub>`api.ogt` line 2819</sub>
+<sub>`api.ogt` line 2820</sub>
 
 <a id="type-SpriteBlend"></a>
 
@@ -4197,7 +4203,32 @@ enum SpriteBlend {
 }
 ```
 
-<sub>`api.ogt` line 2832</sub>
+<sub>`api.ogt` line 2833</sub>
+
+<a id="type-SpriteFacing"></a>
+
+### `SpriteFacing` (enum)
+
+How a world sprite turns towards the camera that draws it: a billboard (three.js Sprite). Decided as a mode of og.Sprite and SpriteDesc rather than a component of its own: a billboard is the same quad, texture, region, flash, glow, blend, layer, drop shadow and texture array layer as any sprite, drawn by the same sprite batch and shader, which only stands its corners differently. The turn is computed on the GPU from each camera's own axes (the main camera, every og.CameraView and og.Mirror, every face of a reflection probe), so it never feeds back into the simulation and a snapshot holds only the mode. The sprite turns about its anchor (a nine-slice turns as one panel), `rotation` still turns it within its own plane, and its drop shadow is cast by the quad stood upright facing the sun, so it shows the whole shape from every camera. Within its layer a faced sprite without sortY draws back to front from the camera's eye (by view depth; a probe's six faces by distance from the probe), after the layer's drop shadows and before its unfaced sprites; and it is culled by its bounds (a sphere round the anchor through the farthest corner) against the camera's view. Sprites draw over the 3D scene after its transparent meshes and particles, depth tested and not depth writing, so a billboard behind a transparent mesh still draws over it.
+
+A string: one of the variants below. The zero value is `"none"`.
+
+| Variant | Doc |
+|---|---|
+| `"none"` | In the world's xy plane facing +z, as every sprite before billboards. |
+| `"camera"` | In the camera's view plane: its x along the camera's right, its y along its up, as particle billboards (smoke, glints, impostors seen from any side). |
+| `"cameraY"` | Upright, turned about the world's y axis towards the camera: its y stays +y, its x the camera's right laid level. Trees, characters and props that must stand while the camera looks down on them. |
+
+```ogt
+enum SpriteFacing {
+  doc "How a world sprite turns towards the camera that draws it: a billboard (three.js Sprite). Decided as a mode of og.Sprite and SpriteDesc rather than a component of its own: a billboard is the same quad, texture, region, flash, glow, blend, layer, drop shadow and texture array layer as any sprite, drawn by the same sprite batch and shader, which only stands its corners differently. The turn is computed on the GPU from each camera's own axes (the main camera, every og.CameraView and og.Mirror, every face of a reflection probe), so it never feeds back into the simulation and a snapshot holds only the mode. The sprite turns about its anchor (a nine-slice turns as one panel), `rotation` still turns it within its own plane, and its drop shadow is cast by the quad stood upright facing the sun, so it shows the whole shape from every camera. Within its layer a faced sprite without sortY draws back to front from the camera's eye (by view depth; a probe's six faces by distance from the probe), after the layer's drop shadows and before its unfaced sprites; and it is culled by its bounds (a sphere round the anchor through the farthest corner) against the camera's view. Sprites draw over the 3D scene after its transparent meshes and particles, depth tested and not depth writing, so a billboard behind a transparent mesh still draws over it."
+  variant none "In the world's xy plane facing +z, as every sprite before billboards."
+  variant camera "In the camera's view plane: its x along the camera's right, its y along its up, as particle billboards (smoke, glints, impostors seen from any side)."
+  variant cameraY "Upright, turned about the world's y axis towards the camera: its y stays +y, its x the camera's right laid level. Trees, characters and props that must stand while the camera looks down on them."
+}
+```
+
+<sub>`api.ogt` line 2846</sub>
 
 <a id="type-StripBlend"></a>
 
@@ -4220,7 +4251,7 @@ enum StripBlend {
 }
 ```
 
-<sub>`api.ogt` line 2845</sub>
+<sub>`api.ogt` line 2860</sub>
 
 <a id="type-Palette"></a>
 
@@ -4234,7 +4265,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Palette "A colour palette for Stylise.palette, from og.load.palette (a `.hex` or GIMP `.gpl` file of up to 256 colours)."
 ```
 
-<sub>`api.ogt` line 3066</sub>
+<sub>`api.ogt` line 3081</sub>
 
 <a id="type-Look"></a>
 
@@ -4248,7 +4279,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Look "A look from og.load.look (an `.ogt` of `type look`): the frame's whole art direction as data, applied with og.render.applyLook."
 ```
 
-<sub>`api.ogt` line 3067</sub>
+<sub>`api.ogt` line 3082</sub>
 
 <a id="type-DitherPattern"></a>
 
@@ -4279,7 +4310,7 @@ enum DitherPattern {
 }
 ```
 
-<sub>`api.ogt` line 3076</sub>
+<sub>`api.ogt` line 3098</sub>
 
 <a id="type-StyliseSpace"></a>
 
@@ -4304,7 +4335,7 @@ enum StyliseSpace {
 }
 ```
 
-<sub>`api.ogt` line 3093</sub>
+<sub>`api.ogt` line 3115</sub>
 
 <a id="type-LookInfo"></a>
 
@@ -4335,7 +4366,7 @@ struct LookInfo {
 }
 ```
 
-<sub>`api.ogt` line 3339</sub>
+<sub>`api.ogt` line 3361</sub>
 
 <a id="type-RibbonPoint"></a>
 
@@ -4375,7 +4406,7 @@ struct RibbonPoint {
 }
 ```
 
-<sub>`api.ogt` line 3551</sub>
+<sub>`api.ogt` line 3573</sub>
 
 <a id="type-RibbonDesc"></a>
 
@@ -4406,7 +4437,7 @@ struct RibbonDesc {
 }
 ```
 
-<sub>`api.ogt` line 3572</sub>
+<sub>`api.ogt` line 3594</sub>
 
 <a id="type-TextDesc"></a>
 
@@ -4468,7 +4499,7 @@ struct TextDesc {
 }
 ```
 
-<sub>`api.ogt` line 3591</sub>
+<sub>`api.ogt` line 3613</sub>
 
 <a id="type-TextMeasureDesc"></a>
 
@@ -4497,7 +4528,7 @@ struct TextMeasureDesc {
 }
 ```
 
-<sub>`api.ogt` line 3625</sub>
+<sub>`api.ogt` line 3647</sub>
 
 <a id="type-TextMetrics"></a>
 
@@ -4520,13 +4551,13 @@ struct TextMetrics {
 }
 ```
 
-<sub>`api.ogt` line 3636</sub>
+<sub>`api.ogt` line 3658</sub>
 
 <a id="type-SpriteDesc"></a>
 
 ### `SpriteDesc` (desc struct)
 
-A textured or solid quad in the world's xy plane facing +z, drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene.
+A textured or solid quad in the world's xy plane facing +z (or turned to the camera, `facing`), drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene.
 
 A desc: every field may be omitted and takes its default; `{}` is valid.
 
@@ -4552,6 +4583,7 @@ A desc: every field may be omitted and takes its default; `{}` is valid.
 | `dropShadow` | `number` | `0` | 0 … 1 | — | — | A drop shadow this dark (0 none, 0.5 typical): the sprite's shape in black, flattened along the sun (the first og.DirectionalLight) onto the ground under it (dropShadowHeight, or the og.Terrain there), drawn before every sprite of its layer: pixel sprites standing in a 3D set cast shadows that agree with it. Where the ground already lies in the sun's cascaded shadow the drop shadow fades, so a shadow inside a shadow is no darker. None with the sun below the horizon; at most five times the sprite's height long under a low one. World sprites with a perspective camera over the xz ground; a 2D camera sees the ground edge on. |
 | `dropShadowHeight` | `number` | `0` | — | `m` | — | The height of the level ground the drop shadow lies on (a floor, a deck, a step). Where an og.Terrain under the sprite's anchor is higher, the shadow lies on the terrain instead, on the plane fitted to its slope under the shadow, or bent over a hollow or a ridge narrower than the shadow (the terrain's heights under a 4 x 2 grid of the shadow's cells). 0 with no terrain is the ground plane y = 0. |
 | `toneMapped` | `boolean` | `true` | — | — | — | As three.js Material.toneMapped: true draws the sprite into the lit scene, carried by exposure (auto exposure included), bloom and the tone curve like any surface. false keeps its colours as given: still placed in the world, depth tested and sorted with the other sprites, but shown unexposed and uncurved (clamped to 0 to 1), outside bloom and fog; the grade, vignette, grain and screen flash still apply. For world UI that must read the same at noon and at dusk: speech bubbles, name tags, markers. Alpha blending only: an additive sprite adds light and is always tone mapped. |
+| `facing` | `SpriteFacing` | `"none"` | — | — | — | A billboard: none keeps the quad in the world's xy plane; camera turns it into the view plane of each camera that draws it; cameraY stands it upright turned about y towards the camera (trees, characters). World sprites only (a screen sprite ignores it); see SpriteFacing for sorting, culling and its drop shadow. |
 | `flipX` | `boolean` | `false` | — | — | — | Mirror the region left to right. |
 | `flipY` | `boolean` | `false` | — | — | — | Mirror the region top to bottom. |
 | `sortY` | `boolean` | `false` | — | — | — | Within its layer, draw by y: lower on the screen draws in front (top-down games). |
@@ -4562,7 +4594,7 @@ A desc: every field may be omitted and takes its default; `{}` is valid.
 
 ```ogt
 struct SpriteDesc {
-  doc "A textured or solid quad in the world's xy plane facing +z, drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene."
+  doc "A textured or solid quad in the world's xy plane facing +z (or turned to the camera, `facing`), drawn this frame only (immediate mode, as og.render.text): submit it every tick it should show. Sprites and text are sorted by layer and drawn over the 3D scene."
   desc true
   field texture Option.Texture "The texture from og.load.texture; null draws a solid quad of the colour."
   field array Option.TextureArray "Draw from a layer of this texture array (og.load.textureArray) instead of `texture`: every sprite of one array is one draw whichever layer each shows, so a flipbook's frames packed as layers batch across frames. World and screen sprites alike, with flash, glow, blend and 2D lighting as a textured sprite. null uses `texture`."
@@ -4618,6 +4650,7 @@ struct SpriteDesc {
   field toneMapped bool "As three.js Material.toneMapped: true draws the sprite into the lit scene, carried by exposure (auto exposure included), bloom and the tone curve like any surface. false keeps its colours as given: still placed in the world, depth tested and sorted with the other sprites, but shown unexposed and uncurved (clamped to 0 to 1), outside bloom and fog; the grade, vignette, grain and screen flash still apply. For world UI that must read the same at noon and at dusk: speech bubbles, name tags, markers. Alpha blending only: an additive sprite adds light and is always tone mapped." {
     default true
   }
+  field facing SpriteFacing "A billboard: none keeps the quad in the world's xy plane; camera turns it into the view plane of each camera that draws it; cameraY stands it upright turned about y towards the camera (trees, characters). World sprites only (a screen sprite ignores it); see SpriteFacing for sorting, culling and its drop shadow."
   field flipX bool "Mirror the region left to right."
   field flipY bool "Mirror the region top to bottom."
   field sortY bool "Within its layer, draw by y: lower on the screen draws in front (top-down games)."
@@ -4631,7 +4664,7 @@ struct SpriteDesc {
 }
 ```
 
-<sub>`api.ogt` line 3643</sub>
+<sub>`api.ogt` line 3665</sub>
 
 <a id="type-FloatingTextDesc"></a>
 
@@ -4719,7 +4752,7 @@ struct FloatingTextDesc {
 }
 ```
 
-<sub>`api.ogt` line 3834</sub>
+<sub>`api.ogt` line 3858</sub>
 
 <a id="type-BoxGeometryDesc"></a>
 
@@ -4761,7 +4794,7 @@ struct BoxGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3906</sub>
+<sub>`api.ogt` line 3930</sub>
 
 <a id="type-PlaneGeometryDesc"></a>
 
@@ -4797,7 +4830,7 @@ struct PlaneGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3929</sub>
+<sub>`api.ogt` line 3953</sub>
 
 <a id="type-SphereGeometryDesc"></a>
 
@@ -4837,7 +4870,7 @@ struct SphereGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3947</sub>
+<sub>`api.ogt` line 3971</sub>
 
 <a id="type-RenderCapabilities"></a>
 
@@ -4894,7 +4927,7 @@ struct RenderCapabilities {
 }
 ```
 
-<sub>`api.ogt` line 3993</sub>
+<sub>`api.ogt` line 4017</sub>
 
 <a id="type-ReflectionProbeMode"></a>
 
@@ -4917,7 +4950,7 @@ enum ReflectionProbeMode {
 }
 ```
 
-<sub>`api.ogt` line 4019</sub>
+<sub>`api.ogt` line 4043</sub>
 
 <a id="type-Shader"></a>
 
@@ -4931,7 +4964,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Shader "A material shader from og.load.shader (an `.ogt` of `type shader`): WGSL hooks of the lit shader, or with `mode full` its own vertex and fragment entries, and the parameters they read."
 ```
 
-<sub>`api.ogt` line 4079</sub>
+<sub>`api.ogt` line 4103</sub>
 
 <a id="type-BufferGeometryDesc"></a>
 
@@ -4972,7 +5005,7 @@ struct BufferGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4152</sub>
+<sub>`api.ogt` line 4183</sub>
 
 <a id="type-GeometryInfo"></a>
 
@@ -5003,7 +5036,7 @@ struct GeometryInfo {
 }
 ```
 
-<sub>`api.ogt` line 4168</sub>
+<sub>`api.ogt` line 4199</sub>
 
 <a id="type-CylinderGeometryDesc"></a>
 
@@ -5062,7 +5095,7 @@ struct CylinderGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4203</sub>
+<sub>`api.ogt` line 4234</sub>
 
 <a id="type-ConeGeometryDesc"></a>
 
@@ -5106,7 +5139,7 @@ struct ConeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4239</sub>
+<sub>`api.ogt` line 4270</sub>
 
 <a id="type-CapsuleGeometryDesc"></a>
 
@@ -5153,7 +5186,7 @@ struct CapsuleGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4263</sub>
+<sub>`api.ogt` line 4294</sub>
 
 <a id="type-TorusGeometryDesc"></a>
 
@@ -5200,7 +5233,7 @@ struct TorusGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4290</sub>
+<sub>`api.ogt` line 4321</sub>
 
 <a id="type-RingGeometryDesc"></a>
 
@@ -5251,7 +5284,7 @@ struct RingGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4317</sub>
+<sub>`api.ogt` line 4348</sub>
 
 <a id="type-CircleGeometryDesc"></a>
 
@@ -5291,7 +5324,7 @@ struct CircleGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4347</sub>
+<sub>`api.ogt` line 4378</sub>
 
 <a id="type-TubeGeometryDesc"></a>
 
@@ -5335,7 +5368,7 @@ struct TubeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4368</sub>
+<sub>`api.ogt` line 4399</sub>
 
 <a id="type-ShapePoints"></a>
 
@@ -5356,7 +5389,7 @@ struct ShapePoints {
 }
 ```
 
-<sub>`api.ogt` line 4442</sub>
+<sub>`api.ogt` line 4473</sub>
 
 <a id="type-ShapeGeometryDesc"></a>
 
@@ -5393,7 +5426,7 @@ struct ShapeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4448</sub>
+<sub>`api.ogt` line 4479</sub>
 
 <a id="type-ExtrudeGeometryDesc"></a>
 
@@ -5466,7 +5499,7 @@ struct ExtrudeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4465</sub>
+<sub>`api.ogt` line 4496</sub>
 
 <a id="type-LatheGeometryDesc"></a>
 
@@ -5514,7 +5547,7 @@ struct LatheGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4510</sub>
+<sub>`api.ogt` line 4541</sub>
 
 <a id="type-PolyhedronGeometryDesc"></a>
 
@@ -5558,7 +5591,7 @@ struct PolyhedronGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4536</sub>
+<sub>`api.ogt` line 4567</sub>
 
 <a id="type-SolidGeometryDesc"></a>
 
@@ -5598,7 +5631,7 @@ struct SolidGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4558</sub>
+<sub>`api.ogt` line 4589</sub>
 
 <a id="type-SweepKey"></a>
 
@@ -5621,7 +5654,7 @@ struct SweepKey {
 }
 ```
 
-<sub>`api.ogt` line 4578</sub>
+<sub>`api.ogt` line 4609</sub>
 
 <a id="type-SweepGeometryDesc"></a>
 
@@ -5673,7 +5706,7 @@ struct SweepGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4586</sub>
+<sub>`api.ogt` line 4617</sub>
 
 <a id="type-MirrorAxis"></a>
 
@@ -5700,7 +5733,7 @@ enum MirrorAxis {
 }
 ```
 
-<sub>`api.ogt` line 4613</sub>
+<sub>`api.ogt` line 4644</sub>
 
 <a id="type-GeometryPart"></a>
 
@@ -5734,7 +5767,7 @@ struct GeometryPart {
 }
 ```
 
-<sub>`api.ogt` line 4621</sub>
+<sub>`api.ogt` line 4652</sub>
 
 <a id="type-CsgOp"></a>
 
@@ -5759,7 +5792,7 @@ enum CsgOp {
 }
 ```
 
-<sub>`api.ogt` line 4635</sub>
+<sub>`api.ogt` line 4666</sub>
 
 <a id="type-CsgGeometryDesc"></a>
 
@@ -5795,7 +5828,7 @@ struct CsgGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4642</sub>
+<sub>`api.ogt` line 4673</sub>
 
 <a id="type-MergeGeometriesDesc"></a>
 
@@ -5827,7 +5860,7 @@ struct MergeGeometriesDesc {
 }
 ```
 
-<sub>`api.ogt` line 4657</sub>
+<sub>`api.ogt` line 4688</sub>
 
 <a id="type-LineMode"></a>
 
@@ -5852,7 +5885,7 @@ enum LineMode {
 }
 ```
 
-<sub>`api.ogt` line 4747</sub>
+<sub>`api.ogt` line 4778</sub>
 
 <a id="type-LinesDesc"></a>
 
@@ -5918,7 +5951,7 @@ struct LinesDesc {
 }
 ```
 
-<sub>`api.ogt` line 4761</sub>
+<sub>`api.ogt` line 4792</sub>
 
 <a id="type-PointsDesc"></a>
 
@@ -5969,7 +6002,7 @@ struct PointsDesc {
 }
 ```
 
-<sub>`api.ogt` line 4805</sub>
+<sub>`api.ogt` line 4836</sub>
 
 <a id="type-RaycastGeometryDesc"></a>
 
@@ -6002,7 +6035,7 @@ struct RaycastGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4908</sub>
+<sub>`api.ogt` line 4939</sub>
 
 <a id="type-GeometryHit"></a>
 
@@ -6037,7 +6070,7 @@ struct GeometryHit {
 }
 ```
 
-<sub>`api.ogt` line 4922</sub>
+<sub>`api.ogt` line 4953</sub>
 
 <a id="type-RenderTargetFormat"></a>
 
@@ -6060,7 +6093,7 @@ enum RenderTargetFormat {
 }
 ```
 
-<sub>`api.ogt` line 4947</sub>
+<sub>`api.ogt` line 4978</sub>
 
 <a id="type-RenderTarget"></a>
 
@@ -6074,7 +6107,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle RenderTarget "A texture a camera draws into (og.render.renderTarget), as three.js WebGLRenderTarget."
 ```
 
-<sub>`api.ogt` line 4960</sub>
+<sub>`api.ogt` line 4991</sub>
 
 <a id="type-RenderTargetDesc"></a>
 
@@ -6108,7 +6141,7 @@ struct RenderTargetDesc {
 }
 ```
 
-<sub>`api.ogt` line 4969</sub>
+<sub>`api.ogt` line 5000</sub>
 
 <a id="type-RenderTargetInfo"></a>
 
@@ -6135,7 +6168,7 @@ struct RenderTargetInfo {
 }
 ```
 
-<sub>`api.ogt` line 4984</sub>
+<sub>`api.ogt` line 5015</sub>
 
 <a id="type-Post"></a>
 
@@ -6149,7 +6182,7 @@ A generational handle: a number the engine hands out. A dead handle is an error
 handle Post "A custom post pass from og.load.post (an `.ogt` of `type post`): a WGSL `post` function over the lit image and the parameters it reads."
 ```
 
-<sub>`api.ogt` line 5096</sub>
+<sub>`api.ogt` line 5127</sub>
 
 <a id="type-PostError"></a>
 
@@ -6170,7 +6203,7 @@ struct PostError {
 }
 ```
 
-<sub>`api.ogt` line 5114</sub>
+<sub>`api.ogt` line 5145</sub>
 
 <a id="type-VolumetricFog"></a>
 
@@ -6193,7 +6226,7 @@ enum VolumetricFog {
 }
 ```
 
-<sub>`api.ogt` line 5128</sub>
+<sub>`api.ogt` line 5159</sub>
 
 <a id="type-BakedScene"></a>
 
@@ -6226,7 +6259,7 @@ struct BakedScene {
 }
 ```
 
-<sub>`api.ogt` line 5176</sub>
+<sub>`api.ogt` line 5207</sub>
 
 ## Column kinds
 
@@ -6245,11 +6278,14 @@ Each is a factory, `Geometry(value?, options?)`, that makes one field of a compo
 | <a id="column-AoMethod"></a>`AoMethod` | `AoMethod` | `Uint32Array` | 1 | An AoMethod field: the variant's index. |
 | <a id="column-DofQuality"></a>`DofQuality` | `DofQuality` | `Uint32Array` | 1 | A DofQuality field: the variant's index. |
 | <a id="column-SpriteBlend"></a>`SpriteBlend` | `SpriteBlend` | `Uint32Array` | 1 | A SpriteBlend field: the variant's index. |
+| <a id="column-SpriteFacing"></a>`SpriteFacing` | `SpriteFacing` | `Uint32Array` | 1 | A SpriteFacing field: the variant's index. |
 | <a id="column-StripBlend"></a>`StripBlend` | `StripBlend` | `Uint32Array` | 1 | A StripBlend field: the variant's index. |
 | <a id="column-Palette"></a>`Palette` | `Palette` | `Uint32Array` | 2 | A Palette handle field (0 is none). |
+| <a id="column-Look"></a>`Look` | `Look` | `Uint32Array` | 2 | A Look handle field (0 is none): a look og.load.look answered, kept for og.render.applyLook. |
 | <a id="column-DitherPattern"></a>`DitherPattern` | `DitherPattern` | `Uint32Array` | 1 | A DitherPattern field: the variant's index. |
 | <a id="column-StyliseSpace"></a>`StyliseSpace` | `StyliseSpace` | `Uint32Array` | 1 | A StyliseSpace field: the variant's index. |
 | <a id="column-ReflectionProbeMode"></a>`ReflectionProbeMode` | `ReflectionProbeMode` | `Uint32Array` | 1 | A ReflectionProbeMode field: the variant's index. |
+| <a id="column-Shader"></a>`Shader` | `Shader` | `Uint32Array` | 2 | A Shader handle field (0 is none): a material shader og.load.shader answered, kept for og.render.shaderMaterial. |
 | <a id="column-LineMode"></a>`LineMode` | `LineMode` | `Uint32Array` | 1 | A LineMode field: the variant's index. |
 | <a id="column-RenderTargetFormat"></a>`RenderTargetFormat` | `RenderTargetFormat` | `Uint32Array` | 1 | A RenderTargetFormat field: the variant's index. |
 | <a id="column-RenderTarget"></a>`RenderTarget` | `RenderTarget` | `Uint32Array` | 2 | A RenderTarget handle field (0 is none). |
@@ -6264,7 +6300,7 @@ column Geometry {
 }
 ```
 
-<sub>`api.ogt` line 2251</sub>
+<sub>`api.ogt` line 2252</sub>
 
 ```ogt
 column Material {
@@ -6275,7 +6311,7 @@ column Material {
 }
 ```
 
-<sub>`api.ogt` line 2258</sub>
+<sub>`api.ogt` line 2259</sub>
 
 ```ogt
 column ToneMapping {
@@ -6286,7 +6322,7 @@ column ToneMapping {
 }
 ```
 
-<sub>`api.ogt` line 2633</sub>
+<sub>`api.ogt` line 2634</sub>
 
 ```ogt
 column QualityPreset {
@@ -6297,7 +6333,7 @@ column QualityPreset {
 }
 ```
 
-<sub>`api.ogt` line 2655</sub>
+<sub>`api.ogt` line 2656</sub>
 
 ```ogt
 column Texture {
@@ -6308,7 +6344,7 @@ column Texture {
 }
 ```
 
-<sub>`api.ogt` line 2757</sub>
+<sub>`api.ogt` line 2758</sub>
 
 ```ogt
 column Lut {
@@ -6319,7 +6355,7 @@ column Lut {
 }
 ```
 
-<sub>`api.ogt` line 2764</sub>
+<sub>`api.ogt` line 2765</sub>
 
 ```ogt
 column EnvironmentMap {
@@ -6330,7 +6366,7 @@ column EnvironmentMap {
 }
 ```
 
-<sub>`api.ogt` line 2771</sub>
+<sub>`api.ogt` line 2772</sub>
 
 ```ogt
 column ParticleEmitter {
@@ -6341,7 +6377,7 @@ column ParticleEmitter {
 }
 ```
 
-<sub>`api.ogt` line 2798</sub>
+<sub>`api.ogt` line 2799</sub>
 
 ```ogt
 column AoMethod {
@@ -6352,7 +6388,7 @@ column AoMethod {
 }
 ```
 
-<sub>`api.ogt` line 2812</sub>
+<sub>`api.ogt` line 2813</sub>
 
 ```ogt
 column DofQuality {
@@ -6363,7 +6399,7 @@ column DofQuality {
 }
 ```
 
-<sub>`api.ogt` line 2825</sub>
+<sub>`api.ogt` line 2826</sub>
 
 ```ogt
 column SpriteBlend {
@@ -6374,7 +6410,18 @@ column SpriteBlend {
 }
 ```
 
-<sub>`api.ogt` line 2838</sub>
+<sub>`api.ogt` line 2839</sub>
+
+```ogt
+column SpriteFacing {
+  doc "A SpriteFacing field: the variant's index."
+  array Uint32Array
+  stride 1
+  value SpriteFacing
+}
+```
+
+<sub>`api.ogt` line 2853</sub>
 
 ```ogt
 column StripBlend {
@@ -6385,7 +6432,7 @@ column StripBlend {
 }
 ```
 
-<sub>`api.ogt` line 2851</sub>
+<sub>`api.ogt` line 2866</sub>
 
 ```ogt
 column Palette {
@@ -6396,7 +6443,18 @@ column Palette {
 }
 ```
 
-<sub>`api.ogt` line 3069</sub>
+<sub>`api.ogt` line 3084</sub>
+
+```ogt
+column Look {
+  doc "A Look handle field (0 is none): a look og.load.look answered, kept for og.render.applyLook."
+  array Uint32Array
+  stride 2
+  value Look
+}
+```
+
+<sub>`api.ogt` line 3091</sub>
 
 ```ogt
 column DitherPattern {
@@ -6407,7 +6465,7 @@ column DitherPattern {
 }
 ```
 
-<sub>`api.ogt` line 3086</sub>
+<sub>`api.ogt` line 3108</sub>
 
 ```ogt
 column StyliseSpace {
@@ -6418,7 +6476,7 @@ column StyliseSpace {
 }
 ```
 
-<sub>`api.ogt` line 3100</sub>
+<sub>`api.ogt` line 3122</sub>
 
 ```ogt
 column ReflectionProbeMode {
@@ -6429,7 +6487,18 @@ column ReflectionProbeMode {
 }
 ```
 
-<sub>`api.ogt` line 4025</sub>
+<sub>`api.ogt` line 4049</sub>
+
+```ogt
+column Shader {
+  doc "A Shader handle field (0 is none): a material shader og.load.shader answered, kept for og.render.shaderMaterial."
+  array Uint32Array
+  stride 2
+  value Shader
+}
+```
+
+<sub>`api.ogt` line 4105</sub>
 
 ```ogt
 column LineMode {
@@ -6440,7 +6509,7 @@ column LineMode {
 }
 ```
 
-<sub>`api.ogt` line 4754</sub>
+<sub>`api.ogt` line 4785</sub>
 
 ```ogt
 column RenderTargetFormat {
@@ -6451,7 +6520,7 @@ column RenderTargetFormat {
 }
 ```
 
-<sub>`api.ogt` line 4953</sub>
+<sub>`api.ogt` line 4984</sub>
 
 ```ogt
 column RenderTarget {
@@ -6462,7 +6531,7 @@ column RenderTarget {
 }
 ```
 
-<sub>`api.ogt` line 4962</sub>
+<sub>`api.ogt` line 4993</sub>
 
 ```ogt
 column Post {
@@ -6473,7 +6542,7 @@ column Post {
 }
 ```
 
-<sub>`api.ogt` line 5098</sub>
+<sub>`api.ogt` line 5129</sub>
 
 ## Constants
 
@@ -6489,28 +6558,28 @@ column Post {
 const PARTICLES_ARMED u32 4294967295 "ParticleSystem.startTick's default: never written. A looping emitter emits as if started at tick 0; a one-shot (`looping false`) emits nothing until its startTick is written, so a burst spawned in `start` waits for its first use. Write it back to re-arm a one-shot without firing it."
 ```
 
-<sub>`api.ogt` line 3445</sub>
+<sub>`api.ogt` line 3467</sub>
 
 ```ogt
 const MAX_LIGHTS u32 256 "The most point and spot lights one frame draws, among those in view; past it the ones brightest at the camera are kept."
 ```
 
-<sub>`api.ogt` line 3989</sub>
+<sub>`api.ogt` line 4013</sub>
 
 ```ogt
 const MAX_CLUSTER_LIGHTS u32 64 "The most point and spot lights that shade one screen cluster (a 1/16 by 1/9 tile of the view and one of 24 depth slices); past it the ones brightest at the camera are kept there."
 ```
 
-<sub>`api.ogt` line 3990</sub>
+<sub>`api.ogt` line 4014</sub>
 
 ```ogt
 const UI_LAYER i32 1000 "The UI's layer among screen sprites and screen text (SpriteDesc and TextDesc with screen): those at or below it draw under every og.ui element, those above it over every one, modals, toasts and the screen transition included (a HUD element made of sprites sitting on a UI panel: draw it only while its screen shows), in their layers' order either way."
 ```
 
-<sub>`api.ogt` line 3991</sub>
+<sub>`api.ogt` line 4015</sub>
 
 ```ogt
 const MAX_REFLECTION_PROBES u32 8 "The most og.ReflectionProbe components one frame samples, nearest the camera first; the rest are skipped."
 ```
 
-<sub>`api.ogt` line 4017</sub>
+<sub>`api.ogt` line 4041</sub>