@origingame/engine 0.3.0 → 0.5.0

package/knowledge/wiki/render.md

@@ -14,7 +14,7 @@ module render {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 2237</sub>
+<sub>`api.ogt` line 2244</sub>
 
 ## Contents
 
@@ -39,7 +39,10 @@ module render {
 | [`og.SpotLight`](#record-SpotLight) | component | A cone of light along the entity's local -Z, as three.js SpotLight. |
 | [`ToneMapping`](#type-ToneMapping) | enum | The curve from the lit HDR image to the display, as three.js toneMapping. RenderSettings.toneMapped false clamps instead, whichever is chosen. |
 | [`ToneMapping()`](#column-ToneMapping) | column kind | A ToneMapping field: the variant's index. |
-| [`og.RenderSettings`](#record-RenderSettings) | resource | The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure. |
+| [`GraphicsQuality`](#type-GraphicsQuality) | enum | A graphics preset: a row of RenderSettings' quality fields that og.render.applyQuality writes (its doc has the table). The settings screen (og.ui.settingsScreen) offers the three. |
+| [`QualityPreset`](#type-QualityPreset) | enum | The preset RenderSettings' quality fields were last written with (RenderSettings.quality). |
+| [`QualityPreset()`](#column-QualityPreset) | column kind | A QualityPreset field: the variant's index. |
+| [`og.RenderSettings`](#record-RenderSettings) | resource | The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping, and what the frame may cost: the quality fields (rectShadows to msaaSamples) that og.render.applyQuality sets from a graphics preset. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure. |
 | [`Lut`](#type-Lut) | handle | A colour lookup table for PostEffects.lut, from og.load.lut (a `.cube` file). |
 | [`EnvironmentMap`](#type-EnvironmentMap) | handle | 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). |
 | [`ParticleEmitter`](#type-ParticleEmitter) | handle | A particle emitter asset for ParticleSystem.emitter, from og.load.emitter (an `.ogt` of `type particles`). |
@@ -54,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). |
@@ -81,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. |
@@ -105,10 +111,12 @@ 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. |
 | [`og.render.applyLook`](#fn-applyLook) | function | Apply a look, in GameDesc.start (or name it in GameDesc.look) or at any tick for a level's mood, a flashback or a photo mode: every resource the look names is replaced whole (the fields it sets take its values, the rest their defaults; PostEffects.flash and PostEffects.shakeTrauma, which game code animates, keep theirs), and the UI is configured with its style, keeping the rest of the last UiDesc. Resources it does not name are left as they are. Inside a system, the system must declare those resources among its writes. A look that switches the stylisation (a Stylise pass on or off, the pixel grid, retro 3D, the material style) starts TAA's history over, as a camera cut does, so its first frame holds no ghost of the old look. |
+| [`og.render.applyQuality`](#fn-applyQuality) | function | Apply a graphics preset: write its row of RenderSettings' quality fields (the rest of RenderSettings keeps its values) and record it in RenderSettings.quality. The renderer reads those fields and nothing else, so what the probe and dump_world show of RenderSettings is what the next frame draws. The settings screen calls it when the player picks a preset (SettingsDesc.world); a game applies a saved preset itself at start. Inside a system, the system must declare RenderSettings among its writes. The rows: |
 | [`og.render.look`](#fn-look) | function | The look last applied (by og.render.applyLook or GameDesc.look), as og.load.lookInfo describes it; null before any. |
 | [`og.render.capabilities`](#fn-capabilities) | function | The renderer's tier and limits on this device. |
 | [`og.render.text`](#fn-text) | function | Draw text this frame. Systems and commands may call it; the list is cleared at every tick, so submit it every tick the text should show. Multi-page fonts are drawn page by page with one layout. |
@@ -131,6 +139,30 @@ module render {
 | [`og.render.ringGeometry`](#fn-ringGeometry) | function | Make a ring geometry for og.Mesh (one-sided: give it a double-sided material to see it from behind). |
 | [`og.render.circleGeometry`](#fn-circleGeometry) | function | Make a circle geometry for og.Mesh (one-sided, as ringGeometry). |
 | [`og.render.tubeGeometry`](#fn-tubeGeometry) | function | Make a tube along a curve through points for og.Mesh: pipes, cables, rails, a path shown as a ribbon of geometry. Physics can use it as a triangle-mesh Collider.mesh. |
+| [`ShapePoints`](#type-ShapePoints) | struct | A shape as points, what og.Shape.extractPoints returns and what shapeGeometry, extrudeGeometry and sweepGeometry read: the outline, then each hole. A repeated closing point is dropped, as three.js drops it. |
+| [`ShapeGeometryDesc`](#type-ShapeGeometryDesc) | desc struct | A flat shape with holes in the xy plane facing +Z, as three.js ShapeGeometry(shapes, curveSegments): triangulated by earcut (three.js's own port), the outline made clockwise and the holes counter-clockwise first, so its vertices and triangles are three.js's for the same shape. uvs are world x and y (v flipped to run down the image). |
+| [`ExtrudeGeometryDesc`](#type-ExtrudeGeometryDesc) | desc struct | Shapes pushed along +Z, or along a path, as three.js ExtrudeGeometry(shapes, options) with its option names and defaults: a closed solid, its lids from earcut and its walls ring by ring, rounded by a bevel of bevelSegments rings at each face. Unindexed as three.js's (every triangle its own vertices, flat normals), three.js's vertex order and counts; uvs from three.js's WorldUVGenerator (v flipped to run down the image). |
+| [`LatheGeometryDesc`](#type-LatheGeometryDesc) | desc struct | A profile turned round +Y, as three.js LatheGeometry(points, segments, phiStart, phiLength): vases, bottles, columns, wheels. three.js's vertices, indices and smooth normals; u round the axis, v along the profile (flipped to run down the image). A whole turn's seam meets exactly. |
+| [`PolyhedronGeometryDesc`](#type-PolyhedronGeometryDesc) | desc struct | A polyhedron from vertices and faces, every face subdivided `detail` times and every vertex pushed onto the sphere of `radius`, as three.js PolyhedronGeometry(vertices, indices, radius, detail): unindexed, flat normals at detail 0 and the sphere's above, three.js's spherical uvs. |
+| [`SolidGeometryDesc`](#type-SolidGeometryDesc) | desc struct | A regular solid, as three.js IcosahedronGeometry, DodecahedronGeometry, OctahedronGeometry and TetrahedronGeometry(radius, detail): PolyhedronGeometryDesc with the solid's own vertices and faces. An icosahedron at detail 2 or more is a sphere with even triangles. |
+| [`SweepKey`](#type-SweepKey) | struct | A value at a fraction of a sweep's path: linear between keys, held before the first and past the last. |
+| [`SweepGeometryDesc`](#type-SweepGeometryDesc) | desc struct | A section swept along a path, scaled and twisted over it: horns, tusks, handles, blades, tapered pipes, twisted columns (img2threejs's tapered sweep; three.js has no class for it). The section's x lies along the path's normal and y along its binormal (three.js's Frenet frames), rings evenly spaced along the path's length; u runs along the path, v round the section (flipped to run down the image), the sides smooth. An open path's ends are capped. |
+| [`MirrorAxis`](#type-MirrorAxis) | enum | The world axis a part is mirrored along, after its placement. |
+| [`GeometryPart`](#type-GeometryPart) | desc struct | A geometry placed as an Object3D is (scale, then rotate, then move), then mirrored: one part of og.render.mergeGeometries or an operand of og.render.csgGeometry. |
+| [`CsgOp`](#type-CsgOp) | enum | A boolean operation on two solids. |
+| [`CsgGeometryDesc`](#type-CsgGeometryDesc) | desc struct | Two closed geometries combined by a boolean operation, each placed first: a box with a hole bored through it, a dice, a window cut in a wall. The result is closed when both are (every edge shared by two triangles, wound opposite), every piece keeps its source's normals, uvs and colours (b's turned inside out where it is subtracted). Where a plane side or an edge crossing is decided, the decision is exact (Shewchuk's predicates), so every host makes the same cuts; faces that coincide keep one copy or none, as the operation says. |
+| [`MergeGeometriesDesc`](#type-MergeGeometriesDesc) | desc struct | Geometries placed and merged into one, as three.js BufferGeometryUtils.mergeGeometries after applying each part's matrix: a prop of parts drawn in one draw, a mirrored half, an array (the same part at several placements). Normals follow each placement; a mirrored part turns its triangles so they still face out. Vertex colours are kept when any part has them. |
+| [`og.render.shapeGeometry`](#fn-shapeGeometry) | function | Make a flat shape for og.Mesh (one-sided, as circleGeometry): an og.Shape with holes, or a points array. Physics can use it as a triangle-mesh Collider.mesh. |
+| [`og.render.extrudeGeometry`](#fn-extrudeGeometry) | function | Make an extruded solid for og.Mesh: a three.js extrusion is a paste (`og.render.extrudeGeometry(world, { shapes: shape, depth: 0.2, bevelEnabled: true })`). Gears, signs, keys, logos, cookie cutters; along a path, a rail or a moulding. |
+| [`og.render.latheGeometry`](#fn-latheGeometry) | function | Make a solid of revolution for og.Mesh: a profile turned round +Y. |
+| [`og.render.polyhedronGeometry`](#fn-polyhedronGeometry) | function | Make a polyhedron from vertices and faces for og.Mesh, subdivided onto a sphere. |
+| [`og.render.icosahedronGeometry`](#fn-icosahedronGeometry) | function | Make an icosahedron (twenty faces) for og.Mesh; with detail, a geodesic sphere. |
+| [`og.render.dodecahedronGeometry`](#fn-dodecahedronGeometry) | function | Make a dodecahedron (twelve pentagons, thirty-six triangles) for og.Mesh. |
+| [`og.render.octahedronGeometry`](#fn-octahedronGeometry) | function | Make an octahedron (eight faces) for og.Mesh. |
+| [`og.render.tetrahedronGeometry`](#fn-tetrahedronGeometry) | function | Make a tetrahedron (four faces) for og.Mesh. |
+| [`og.render.sweepGeometry`](#fn-sweepGeometry) | function | Make a section swept along a path for og.Mesh, tapered and twisted by keys. |
+| [`og.render.csgGeometry`](#fn-csgGeometry) | function | Make the union, difference or intersection of two placed geometries for og.Mesh. Chain calls for more operands (a cube minus six spheres is six calls); each result is a geometry like any other. |
+| [`og.render.mergeGeometries`](#fn-mergeGeometries) | function | Make one geometry of several placed ones for og.Mesh: one draw instead of many, mirrored halves, arrays. |
 | [`LineMode`](#type-LineMode) | enum | How a line set's points join, as three.js's three line objects. |
 | [`LineMode()`](#column-LineMode) | column kind | A LineMode field: the variant's index. |
 | [`LinesDesc`](#type-LinesDesc) | desc struct | Lines through points, drawn this frame only (immediate mode, as og.render.sprite): submit them every tick they should show. three.js Line, LineSegments and LineLoop with a LineBasicMaterial or LineDashedMaterial, but any width on every tier (each segment is a quad in screen space with a feathered edge, so WebGL2's one-pixel lines do not apply). |
@@ -155,7 +187,7 @@ module render {
 | [`Post()`](#column-Post) | column kind | A Post handle field (0 is none). |
 | [`og.render.setPostParam`](#fn-setPostParam) | function | Set a parameter of a custom post pass, by the name its asset declares: a number for float, two to four for vec2, vec3, vec4 and color. Every frame it runs in reads it. |
 | [`PostError`](#type-PostError) | struct | A custom post pass the device failed to compile. |
-| [`og.render.postErrors`](#fn-postErrors) | function | The custom post passes PostEffects.custom1 to custom8 name that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal. |
+| [`og.render.postErrors`](#fn-postErrors) | function | The custom post passes PostEffects.custom names that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal. |
 | [`VolumetricFog`](#type-VolumetricFog) | enum | How the device draws Fog.volumetric (RenderCapabilities.volumetricFog). |
 | [`og.RectLight`](#record-RectLight) | component | A rectangle of light, as three.js RectAreaLight: width by height metres centred on the entity in its local xy plane, facing along its local -Z (aim it with transform.lookAt, as a spot), emitting color * intensity from its front, or from both faces with twoSided. Shaded with linearly transformed cosines (Heitz et al. 2016, three.js's tables), so its highlight on a glossy floor is the rectangle's shape and its light on a matte wall falls off as a real panel's does. With castShadow it casts a soft shadow in the frame; og bake lightmaps traces its exact soft shadows into the bounce light either way. |
 | [`og.LightVolume`](#record-LightVolume) | component | A box of baked light probes (an irradiance volume): og bake lightmaps traces the light arriving from the scene (bounced off its static models, from the sky, from emissive surfaces) at a grid of points spacing metres apart inside it, as first-order spherical harmonics. Every mesh, model, skinned character and particle-lit surface drawn inside it that has no lightmap of its own takes its ambient light from the probes instead of the sky's, blended at the box's edge over one spacing: a ball rolling past a red wall turns red on that side. |
@@ -192,7 +224,7 @@ fn ribbon {
 }
 ```
 
-<sub>`api.ogt` line 3532</sub>
+<sub>`api.ogt` line 3606</sub>
 
 <a id="fn-sprite"></a>
 
@@ -222,7 +254,7 @@ fn sprite {
 }
 ```
 
-<sub>`api.ogt` line 3660</sub>
+<sub>`api.ogt` line 3735</sub>
 
 <a id="fn-floatingText"></a>
 
@@ -252,7 +284,7 @@ fn floatingText {
 }
 ```
 
-<sub>`api.ogt` line 3840</sub>
+<sub>`api.ogt` line 3916</sub>
 
 <a id="fn-measureText"></a>
 
@@ -282,7 +314,7 @@ fn measureText {
 }
 ```
 
-<sub>`api.ogt` line 3847</sub>
+<sub>`api.ogt` line 3923</sub>
 
 <a id="fn-boxGeometry"></a>
 
@@ -312,7 +344,7 @@ fn boxGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3916</sub>
+<sub>`api.ogt` line 3992</sub>
 
 <a id="fn-planeGeometry"></a>
 
@@ -342,7 +374,7 @@ fn planeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3923</sub>
+<sub>`api.ogt` line 3999</sub>
 
 <a id="fn-sphereGeometry"></a>
 
@@ -372,7 +404,7 @@ fn sphereGeometry {
 }
 ```
 
-<sub>`api.ogt` line 3930</sub>
+<sub>`api.ogt` line 4006</sub>
 
 <a id="fn-standardMaterial"></a>
 
@@ -402,7 +434,7 @@ fn standardMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4010</sub>
+<sub>`api.ogt` line 4088</sub>
 
 <a id="fn-updateMaterial"></a>
 
@@ -434,7 +466,7 @@ fn updateMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4017</sub>
+<sub>`api.ogt` line 4095</sub>
 
 <a id="fn-shaderMaterial"></a>
 
@@ -466,7 +498,7 @@ fn shaderMaterial {
 }
 ```
 
-<sub>`api.ogt` line 4027</sub>
+<sub>`api.ogt` line 4112</sub>
 
 <a id="fn-setMaterialShader"></a>
 
@@ -498,7 +530,7 @@ fn setMaterialShader {
 }
 ```
 
-<sub>`api.ogt` line 4035</sub>
+<sub>`api.ogt` line 4120</sub>
 
 <a id="fn-setShaderParam"></a>
 
@@ -532,7 +564,7 @@ fn setShaderParam {
 }
 ```
 
-<sub>`api.ogt` line 4043</sub>
+<sub>`api.ogt` line 4128</sub>
 
 <a id="fn-applyLook"></a>
 
@@ -562,7 +594,61 @@ fn applyLook {
 }
 ```
 
-<sub>`api.ogt` line 4052</sub>
+<sub>`api.ogt` line 4137</sub>
+
+<a id="fn-applyQuality"></a>
+
+### `og.render.applyQuality`
+
+Apply a graphics preset: write its row of RenderSettings' quality fields (the rest of RenderSettings keeps its values) and record it in RenderSettings.quality. The renderer reads those fields and nothing else, so what the probe and dump_world show of RenderSettings is what the next frame draws. The settings screen calls it when the player picks a preset (SettingsDesc.world); a game applies a saved preset itself at start. Inside a system, the system must declare RenderSettings among its writes. The rows:
+
+| Field | low | medium | high |
+|---|---|---|---|
+| rectShadows | false | true | true |
+| shadowedLights | 2 | 8 | 8 |
+| shadowMapScale | 0.5 | 1 | 2 |
+| volumetricFog | false | true | true |
+| softParticles | false | true | true |
+| screenSpaceReflections | false | true | true |
+| ambientOcclusion | false | true | true |
+| msaaSamples | 1 | 4 | 4 |
+
+Medium is every field's default, the frame drawn before any preset.
+
+```ts
+og.render.applyQuality(world: World, preset: GraphicsQuality): Result<void>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose RenderSettings change. |
+| `preset` | `GraphicsQuality` | no | The preset. |
+
+**Returns** `Result<void>`: Refused for a world that is not alive, or inside a system that did not declare RenderSettings among its writes.
+
+Binding symbol `og_render_apply_quality` · publish builds: kept
+
+```ogt
+fn applyQuality {
+  doc "Apply a graphics preset: write its row of RenderSettings' quality fields (the rest of RenderSettings keeps its values) and record it in RenderSettings.quality. The renderer reads those fields and nothing else, so what the probe and dump_world show of RenderSettings is what the next frame draws. The settings screen calls it when the player picks a preset (SettingsDesc.world); a game applies a saved preset itself at start. Inside a system, the system must declare RenderSettings among its writes. The rows:"
+  doc "| Field | low | medium | high |"
+  doc "|---|---|---|---|"
+  doc "| rectShadows | false | true | true |"
+  doc "| shadowedLights | 2 | 8 | 8 |"
+  doc "| shadowMapScale | 0.5 | 1 | 2 |"
+  doc "| volumetricFog | false | true | true |"
+  doc "| softParticles | false | true | true |"
+  doc "| screenSpaceReflections | false | true | true |"
+  doc "| ambientOcclusion | false | true | true |"
+  doc "| msaaSamples | 1 | 4 | 4 |"
+  doc "Medium is every field's default, the frame drawn before any preset."
+  param world World "The world whose RenderSettings change."
+  param preset GraphicsQuality "The preset."
+  returns Result.Void "Refused for a world that is not alive, or inside a system that did not declare RenderSettings among its writes."
+}
+```
+
+<sub>`api.ogt` line 4144</sub>
 
 <a id="fn-look"></a>
 
@@ -590,7 +676,7 @@ fn look {
 }
 ```
 
-<sub>`api.ogt` line 4059</sub>
+<sub>`api.ogt` line 4162</sub>
 
 <a id="fn-capabilities"></a>
 
@@ -618,7 +704,7 @@ fn capabilities {
 }
 ```
 
-<sub>`api.ogt` line 4065</sub>
+<sub>`api.ogt` line 4168</sub>
 
 <a id="fn-text"></a>
 
@@ -648,7 +734,7 @@ fn text {
 }
 ```
 
-<sub>`api.ogt` line 4071</sub>
+<sub>`api.ogt` line 4174</sub>
 
 <a id="fn-bufferGeometry"></a>
 
@@ -678,7 +764,7 @@ fn bufferGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4109</sub>
+<sub>`api.ogt` line 4212</sub>
 
 <a id="fn-updateGeometry"></a>
 
@@ -710,7 +796,7 @@ fn updateGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4116</sub>
+<sub>`api.ogt` line 4219</sub>
 
 <a id="fn-geometryInfo"></a>
 
@@ -740,7 +826,7 @@ fn geometryInfo {
 }
 ```
 
-<sub>`api.ogt` line 4124</sub>
+<sub>`api.ogt` line 4227</sub>
 
 <a id="fn-cylinderGeometry"></a>
 
@@ -770,7 +856,7 @@ fn cylinderGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4319</sub>
+<sub>`api.ogt` line 4422</sub>
 
 <a id="fn-coneGeometry"></a>
 
@@ -800,7 +886,7 @@ fn coneGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4326</sub>
+<sub>`api.ogt` line 4429</sub>
 
 <a id="fn-capsuleGeometry"></a>
 
@@ -830,7 +916,7 @@ fn capsuleGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4333</sub>
+<sub>`api.ogt` line 4436</sub>
 
 <a id="fn-torusGeometry"></a>
 
@@ -860,7 +946,7 @@ fn torusGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4340</sub>
+<sub>`api.ogt` line 4443</sub>
 
 <a id="fn-ringGeometry"></a>
 
@@ -890,7 +976,7 @@ fn ringGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4347</sub>
+<sub>`api.ogt` line 4450</sub>
 
 <a id="fn-circleGeometry"></a>
 
@@ -920,7 +1006,7 @@ fn circleGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4354</sub>
+<sub>`api.ogt` line 4457</sub>
 
 <a id="fn-tubeGeometry"></a>
 
@@ -950,7 +1036,337 @@ fn tubeGeometry {
 }
 ```
 
-<sub>`api.ogt` line 4361</sub>
+<sub>`api.ogt` line 4464</sub>
+
+<a id="fn-shapeGeometry"></a>
+
+### `og.render.shapeGeometry`
+
+Make a flat shape for og.Mesh (one-sided, as circleGeometry): an og.Shape with holes, or a points array. Physics can use it as a triangle-mesh Collider.mesh.
+
+```ts
+og.render.shapeGeometry(world: World, desc?: ShapeGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `ShapeGeometryDesc` | yes | The shapes and their tessellation. |
+
+**Returns** `Result<Geometry>`: Refused for a shape whose points are not finite or that triangulates to nothing.
+
+Binding symbol `og_render_shape_geometry` · publish builds: kept
+
+```ogt
+fn shapeGeometry {
+  doc "Make a flat shape for og.Mesh (one-sided, as circleGeometry): an og.Shape with holes, or a points array. Physics can use it as a triangle-mesh Collider.mesh."
+  param world World "The world whose renderer owns the geometry."
+  param desc ShapeGeometryDesc "The shapes and their tessellation."
+  returns Result.Geometry "Refused for a shape whose points are not finite or that triangulates to nothing."
+}
+```
+
+<sub>`api.ogt` line 4701</sub>
+
+<a id="fn-extrudeGeometry"></a>
+
+### `og.render.extrudeGeometry`
+
+Make an extruded solid for og.Mesh: a three.js extrusion is a paste (`og.render.extrudeGeometry(world, { shapes: shape, depth: 0.2, bevelEnabled: true })`). Gears, signs, keys, logos, cookie cutters; along a path, a rail or a moulding.
+
+```ts
+og.render.extrudeGeometry(world: World, desc?: ExtrudeGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `ExtrudeGeometryDesc` | yes | The shapes, depth, bevel and path. |
+
+**Returns** `Result<Geometry>`: Refused for a shape whose points are not finite or that triangulates to nothing, or an extrudePath that is not alive.
+
+Binding symbol `og_render_extrude_geometry` · publish builds: kept
+
+```ogt
+fn extrudeGeometry {
+  doc "Make an extruded solid for og.Mesh: a three.js extrusion is a paste (`og.render.extrudeGeometry(world, { shapes: shape, depth: 0.2, bevelEnabled: true })`). Gears, signs, keys, logos, cookie cutters; along a path, a rail or a moulding."
+  param world World "The world whose renderer owns the geometry."
+  param desc ExtrudeGeometryDesc "The shapes, depth, bevel and path."
+  returns Result.Geometry "Refused for a shape whose points are not finite or that triangulates to nothing, or an extrudePath that is not alive."
+}
+```
+
+<sub>`api.ogt` line 4708</sub>
+
+<a id="fn-latheGeometry"></a>
+
+### `og.render.latheGeometry`
+
+Make a solid of revolution for og.Mesh: a profile turned round +Y.
+
+```ts
+og.render.latheGeometry(world: World, desc?: LatheGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `LatheGeometryDesc` | yes | The profile and the turn. |
+
+**Returns** `Result<Geometry>`: Refused for fewer than two points or one that is not finite.
+
+Binding symbol `og_render_lathe_geometry` · publish builds: kept
+
+```ogt
+fn latheGeometry {
+  doc "Make a solid of revolution for og.Mesh: a profile turned round +Y."
+  param world World "The world whose renderer owns the geometry."
+  param desc LatheGeometryDesc "The profile and the turn."
+  returns Result.Geometry "Refused for fewer than two points or one that is not finite."
+}
+```
+
+<sub>`api.ogt` line 4715</sub>
+
+<a id="fn-polyhedronGeometry"></a>
+
+### `og.render.polyhedronGeometry`
+
+Make a polyhedron from vertices and faces for og.Mesh, subdivided onto a sphere.
+
+```ts
+og.render.polyhedronGeometry(world: World, desc?: PolyhedronGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `PolyhedronGeometryDesc` | yes | The vertices, faces, radius and detail. |
+
+**Returns** `Result<Geometry>`: Refused for no faces, an index past the vertices, or a count that is not a multiple of three.
+
+Binding symbol `og_render_polyhedron_geometry` · publish builds: kept
+
+```ogt
+fn polyhedronGeometry {
+  doc "Make a polyhedron from vertices and faces for og.Mesh, subdivided onto a sphere."
+  param world World "The world whose renderer owns the geometry."
+  param desc PolyhedronGeometryDesc "The vertices, faces, radius and detail."
+  returns Result.Geometry "Refused for no faces, an index past the vertices, or a count that is not a multiple of three."
+}
+```
+
+<sub>`api.ogt` line 4722</sub>
+
+<a id="fn-icosahedronGeometry"></a>
+
+### `og.render.icosahedronGeometry`
+
+Make an icosahedron (twenty faces) for og.Mesh; with detail, a geodesic sphere.
+
+```ts
+og.render.icosahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `SolidGeometryDesc` | yes | Its radius and detail. |
+
+**Returns** `Result<Geometry>`.
+
+Binding symbol `og_render_icosahedron_geometry` · publish builds: kept
+
+```ogt
+fn icosahedronGeometry {
+  doc "Make an icosahedron (twenty faces) for og.Mesh; with detail, a geodesic sphere."
+  param world World "The world whose renderer owns the geometry."
+  param desc SolidGeometryDesc "Its radius and detail."
+  returns Result.Geometry
+}
+```
+
+<sub>`api.ogt` line 4729</sub>
+
+<a id="fn-dodecahedronGeometry"></a>
+
+### `og.render.dodecahedronGeometry`
+
+Make a dodecahedron (twelve pentagons, thirty-six triangles) for og.Mesh.
+
+```ts
+og.render.dodecahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `SolidGeometryDesc` | yes | Its radius and detail. |
+
+**Returns** `Result<Geometry>`.
+
+Binding symbol `og_render_dodecahedron_geometry` · publish builds: kept
+
+```ogt
+fn dodecahedronGeometry {
+  doc "Make a dodecahedron (twelve pentagons, thirty-six triangles) for og.Mesh."
+  param world World "The world whose renderer owns the geometry."
+  param desc SolidGeometryDesc "Its radius and detail."
+  returns Result.Geometry
+}
+```
+
+<sub>`api.ogt` line 4736</sub>
+
+<a id="fn-octahedronGeometry"></a>
+
+### `og.render.octahedronGeometry`
+
+Make an octahedron (eight faces) for og.Mesh.
+
+```ts
+og.render.octahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `SolidGeometryDesc` | yes | Its radius and detail. |
+
+**Returns** `Result<Geometry>`.
+
+Binding symbol `og_render_octahedron_geometry` · publish builds: kept
+
+```ogt
+fn octahedronGeometry {
+  doc "Make an octahedron (eight faces) for og.Mesh."
+  param world World "The world whose renderer owns the geometry."
+  param desc SolidGeometryDesc "Its radius and detail."
+  returns Result.Geometry
+}
+```
+
+<sub>`api.ogt` line 4743</sub>
+
+<a id="fn-tetrahedronGeometry"></a>
+
+### `og.render.tetrahedronGeometry`
+
+Make a tetrahedron (four faces) for og.Mesh.
+
+```ts
+og.render.tetrahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `SolidGeometryDesc` | yes | Its radius and detail. |
+
+**Returns** `Result<Geometry>`.
+
+Binding symbol `og_render_tetrahedron_geometry` · publish builds: kept
+
+```ogt
+fn tetrahedronGeometry {
+  doc "Make a tetrahedron (four faces) for og.Mesh."
+  param world World "The world whose renderer owns the geometry."
+  param desc SolidGeometryDesc "Its radius and detail."
+  returns Result.Geometry
+}
+```
+
+<sub>`api.ogt` line 4750</sub>
+
+<a id="fn-sweepGeometry"></a>
+
+### `og.render.sweepGeometry`
+
+Make a section swept along a path for og.Mesh, tapered and twisted by keys.
+
+```ts
+og.render.sweepGeometry(world: World, desc?: SweepGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `SweepGeometryDesc` | yes | The section, path, keys and caps. |
+
+**Returns** `Result<Geometry>`: Refused for a path that is not alive, a section of fewer than three points or of no area, or a value that is not finite.
+
+Binding symbol `og_render_sweep_geometry` · publish builds: kept
+
+```ogt
+fn sweepGeometry {
+  doc "Make a section swept along a path for og.Mesh, tapered and twisted by keys."
+  param world World "The world whose renderer owns the geometry."
+  param desc SweepGeometryDesc "The section, path, keys and caps."
+  returns Result.Geometry "Refused for a path that is not alive, a section of fewer than three points or of no area, or a value that is not finite."
+}
+```
+
+<sub>`api.ogt` line 4757</sub>
+
+<a id="fn-csgGeometry"></a>
+
+### `og.render.csgGeometry`
+
+Make the union, difference or intersection of two placed geometries for og.Mesh. Chain calls for more operands (a cube minus six spheres is six calls); each result is a geometry like any other.
+
+```ts
+og.render.csgGeometry(world: World, desc?: CsgGeometryDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `CsgGeometryDesc` | yes | The operation and its operands. |
+
+**Returns** `Result<Geometry>`: Refused for a dead geometry, a placement with a zero scale, or a position that is not finite.
+
+Binding symbol `og_render_csg_geometry` · publish builds: kept
+
+```ogt
+fn csgGeometry {
+  doc "Make the union, difference or intersection of two placed geometries for og.Mesh. Chain calls for more operands (a cube minus six spheres is six calls); each result is a geometry like any other."
+  param world World "The world whose renderer owns the geometry."
+  param desc CsgGeometryDesc "The operation and its operands."
+  returns Result.Geometry "Refused for a dead geometry, a placement with a zero scale, or a position that is not finite."
+}
+```
+
+<sub>`api.ogt` line 4764</sub>
+
+<a id="fn-mergeGeometries"></a>
+
+### `og.render.mergeGeometries`
+
+Make one geometry of several placed ones for og.Mesh: one draw instead of many, mirrored halves, arrays.
+
+```ts
+og.render.mergeGeometries(world: World, desc?: MergeGeometriesDesc): Result<Geometry>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose renderer owns the geometry. |
+| `desc` | `MergeGeometriesDesc` | yes | The parts and their placements. |
+
+**Returns** `Result<Geometry>`: Refused for no parts, a dead geometry, or a placement with a zero scale.
+
+Binding symbol `og_render_merge_geometries` · publish builds: kept
+
+```ogt
+fn mergeGeometries {
+  doc "Make one geometry of several placed ones for og.Mesh: one draw instead of many, mirrored halves, arrays."
+  param world World "The world whose renderer owns the geometry."
+  param desc MergeGeometriesDesc "The parts and their placements."
+  returns Result.Geometry "Refused for no parts, a dead geometry, or a placement with a zero scale."
+}
+```
+
+<sub>`api.ogt` line 4771</sub>
 
 <a id="fn-lines"></a>
 
@@ -980,7 +1396,7 @@ fn lines {
 }
 ```
 
-<sub>`api.ogt` line 4419</sub>
+<sub>`api.ogt` line 4829</sub>
 
 <a id="fn-points"></a>
 
@@ -1010,7 +1426,7 @@ fn points {
 }
 ```
 
-<sub>`api.ogt` line 4454</sub>
+<sub>`api.ogt` line 4864</sub>
 
 <a id="fn-raycast"></a>
 
@@ -1042,7 +1458,7 @@ fn raycast {
 }
 ```
 
-<sub>`api.ogt` line 4558</sub>
+<sub>`api.ogt` line 4968</sub>
 
 <a id="fn-renderTarget"></a>
 
@@ -1072,7 +1488,7 @@ fn renderTarget {
 }
 ```
 
-<sub>`api.ogt` line 4614</sub>
+<sub>`api.ogt` line 5024</sub>
 
 <a id="fn-setPostParam"></a>
 
@@ -1106,13 +1522,13 @@ fn setPostParam {
 }
 ```
 
-<sub>`api.ogt` line 4726</sub>
+<sub>`api.ogt` line 5136</sub>
 
 <a id="fn-postErrors"></a>
 
 ### `og.render.postErrors`
 
-The custom post passes PostEffects.custom1 to custom8 name that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal.
+The custom post passes PostEffects.custom names that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal.
 
 ```ts
 og.render.postErrors(world: World): readonly PostError[]
@@ -1128,13 +1544,13 @@ Binding symbol `og_render_post_errors` · publish builds: kept
 
 ```ogt
 fn postErrors {
-  doc "The custom post passes PostEffects.custom1 to custom8 name that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal."
+  doc "The custom post passes PostEffects.custom names that failed to compile on this device, each skipped (the frame draws as without it). The cook validates every pass for each back end, so this is a device's own refusal."
   param world World "The world asked."
   returns List.PostError
 }
 ```
 
-<sub>`api.ogt` line 4741</sub>
+<sub>`api.ogt` line 5151</sub>
 
 <a id="fn-bakedLighting"></a>
 
@@ -1162,7 +1578,7 @@ fn bakedLighting {
 }
 ```
 
-<sub>`api.ogt` line 4809</sub>
+<sub>`api.ogt` line 5219</sub>
 
 ## Components, resources and events
 
@@ -1220,7 +1636,7 @@ component Mesh {
 }
 ```
 
-<sub>`api.ogt` line 2505</sub>
+<sub>`api.ogt` line 2512</sub>
 
 <a id="record-DirectionalLight"></a>
 
@@ -1275,7 +1691,7 @@ component DirectionalLight {
 }
 ```
 
-<sub>`api.ogt` line 2535</sub>
+<sub>`api.ogt` line 2542</sub>
 
 <a id="record-PointLight"></a>
 
@@ -1318,7 +1734,7 @@ component PointLight {
 }
 ```
 
-<sub>`api.ogt` line 2567</sub>
+<sub>`api.ogt` line 2574</sub>
 
 <a id="record-SpotLight"></a>
 
@@ -1372,13 +1788,13 @@ component SpotLight {
 }
 ```
 
-<sub>`api.ogt` line 2588</sub>
+<sub>`api.ogt` line 2595</sub>
 
 <a id="record-RenderSettings"></a>
 
 ### `og.RenderSettings` (resource)
 
-The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure.
+The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping, and what the frame may cost: the quality fields (rectShadows to msaaSamples) that og.render.applyQuality sets from a graphics preset. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure.
 
 Token `og.RenderSettings`, registered under the schema name `og.RenderSettings`; its value type is `RenderSettings`.
 
@@ -1397,12 +1813,21 @@ Token `og.RenderSettings`, registered under the schema name `og.RenderSettings`;
 | `toneMapping` | `ToneMapping` | `"aces"` | — | — | — | Which curve tone maps the frame while toneMapped is true: aces (the default), agx or none. |
 | `exposure` | `number` | `1` | 0 … 16 | — | tunable | A multiplier on every camera's Camera.exposure, as three.js renderer.toneMappingExposure is one for the whole frame: a look's brightness without touching the cameras; 1 leaves them as they are. |
 | `decalAtlas` | `Texture` | `0` | — | — | — | The texture Decal components take their uvMin to uvMax region from; 0 draws decals as solid colour. |
-| `lodBias` | `number` | `1` | 0 … 16 | — | tunable | A multiplier on every model's projected size when its level of detail is picked (og.Model.lodBias multiplies it again): 1 is the engine's choice, 2 keeps full meshes twice as far, 0.5 simplifies sooner; 0 draws every model at its full mesh. |
+| `lodBias` | `number` | `1` | 0 … 16 | — | tunable | A multiplier on every model's projected level-of-detail error when its level is picked (og.Model.lodBias multiplies it again): a level is drawn while its error, measured by the cook against the full mesh, covers less than a pixel on the screen. 1 is the engine's choice, 2 keeps full meshes twice as far, 0.5 simplifies sooner; 0 draws every model at its full mesh. |
 | `bakedLighting` | `boolean` | `true` | — | — | — | Draw the baked lighting of the scenes that have it (og bake lightmaps): static models with their lightmaps, everything else inside a LightVolume with its probes. False draws every scene as if unbaked, its ambient light from the sky or the environment map: to compare, or to see the realtime lights alone. |
+| `quality` | `QualityPreset` | `"none"` | — | — | — | The graphics preset og.render.applyQuality last wrote into the quality fields below (rectShadows to msaaSamples), or none. A record for the settings screen and the probe: the renderer reads the fields, never this, so a field the game sets after the preset is drawn as set. |
+| `rectShadows` | `boolean` | `true` | — | — | — | Rect lights whose castShadow is on cast their soft shadows; false draws every rect light unshadowed, each keeping its castShadow for when this is on again. The low preset turns it off: a rect light's shadow is the costliest light in the frame. |
+| `shadowedLights` | `number` | `8` | 0 … 8 | — | — | At most this many point, spot and rect lights cast shadows in a frame, the brightest at the camera kept (RenderCapabilities.shadowedLights caps it); 0 casts none. The directional light's cascades are not counted. |
+| `shadowMapScale` | `number` | `1` | 0.125 … 4 | — | — | The shadow maps at this fraction of their full side: the directional light's cascades (2048 texels by default) and the local lights' layers (512), each kept within 64 texels and the device's limit (4096 for the cascades). Changing it makes the maps again at the next frame; RenderCapabilities.shadowMapSize is the cascades' side drawn. |
+| `volumetricFog` | `boolean` | `true` | — | — | — | An og.VolumetricFog is drawn lit, with its light shafts; false draws the same medium as plain distance and height fog. |
+| `softParticles` | `boolean` | `true` | — | — | — | Particles with a softDistance fade against the scene behind them; false draws them hard-edged and asks no depth prepass for them. |
+| `screenSpaceReflections` | `boolean` | `true` | — | — | — | PostEffects.ssr draws (on the full tier); false leaves smooth surfaces the reflection probes' and the environment's reflection. PostEffects keeps its settings either way. |
+| `ambientOcclusion` | `boolean` | `true` | — | — | — | PostEffects.ao darkens creases; false draws none. PostEffects keeps its settings either way. |
+| `msaaSamples` | `number` | `4` | 1 … 4 | — | — | Samples per pixel where the antialiasing multisamples (msaa, the WebGL2 tier's choice; RenderCapabilities.antialias): 4, or 1, which draws FXAA instead. TAA, FXAA and no antialiasing take one sample whatever it says. Changing it makes the multisampled targets and pipelines again at the next frame. |
 
 ```ogt
 resource RenderSettings {
-  doc "The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure."
+  doc "The frame's look after lighting: environment light, sky, bloom, exposure metering and tone mapping, and what the frame may cost: the quality fields (rectShadows to msaaSamples) that og.render.applyQuality sets from a graphics preset. Read after each tick; it never feeds back into the simulation. Camera.exposure is the manual exposure."
   field environmentIntensity f32 "The strength of the image-based ambient light from the sky; og.Environment.intensity takes its place while an environment map is set." {
     default 0.55
     min 0
@@ -1448,7 +1873,7 @@ resource RenderSettings {
     tunable true
   }
   field decalAtlas Texture "The texture Decal components take their uvMin to uvMax region from; 0 draws decals as solid colour."
-  field lodBias f32 "A multiplier on every model's projected size when its level of detail is picked (og.Model.lodBias multiplies it again): 1 is the engine's choice, 2 keeps full meshes twice as far, 0.5 simplifies sooner; 0 draws every model at its full mesh." {
+  field lodBias f32 "A multiplier on every model's projected level-of-detail error when its level is picked (og.Model.lodBias multiplies it again): a level is drawn while its error, measured by the cook against the full mesh, covers less than a pixel on the screen. 1 is the engine's choice, 2 keeps full meshes twice as far, 0.5 simplifies sooner; 0 draws every model at its full mesh." {
     default 1
     min 0
     max 16
@@ -1457,10 +1882,41 @@ resource RenderSettings {
   field bakedLighting bool "Draw the baked lighting of the scenes that have it (og bake lightmaps): static models with their lightmaps, everything else inside a LightVolume with its probes. False draws every scene as if unbaked, its ambient light from the sky or the environment map: to compare, or to see the realtime lights alone." {
     default true
   }
+  field quality QualityPreset "The graphics preset og.render.applyQuality last wrote into the quality fields below (rectShadows to msaaSamples), or none. A record for the settings screen and the probe: the renderer reads the fields, never this, so a field the game sets after the preset is drawn as set."
+  field rectShadows bool "Rect lights whose castShadow is on cast their soft shadows; false draws every rect light unshadowed, each keeping its castShadow for when this is on again. The low preset turns it off: a rect light's shadow is the costliest light in the frame." {
+    default true
+  }
+  field shadowedLights u32 "At most this many point, spot and rect lights cast shadows in a frame, the brightest at the camera kept (RenderCapabilities.shadowedLights caps it); 0 casts none. The directional light's cascades are not counted." {
+    default 8
+    min 0
+    max 8
+  }
+  field shadowMapScale f32 "The shadow maps at this fraction of their full side: the directional light's cascades (2048 texels by default) and the local lights' layers (512), each kept within 64 texels and the device's limit (4096 for the cascades). Changing it makes the maps again at the next frame; RenderCapabilities.shadowMapSize is the cascades' side drawn." {
+    default 1
+    min 0.125
+    max 4
+  }
+  field volumetricFog bool "An og.VolumetricFog is drawn lit, with its light shafts; false draws the same medium as plain distance and height fog." {
+    default true
+  }
+  field softParticles bool "Particles with a softDistance fade against the scene behind them; false draws them hard-edged and asks no depth prepass for them." {
+    default true
+  }
+  field screenSpaceReflections bool "PostEffects.ssr draws (on the full tier); false leaves smooth surfaces the reflection probes' and the environment's reflection. PostEffects keeps its settings either way." {
+    default true
+  }
+  field ambientOcclusion bool "PostEffects.ao darkens creases; false draws none. PostEffects keeps its settings either way." {
+    default true
+  }
+  field msaaSamples u32 "Samples per pixel where the antialiasing multisamples (msaa, the WebGL2 tier's choice; RenderCapabilities.antialias): 4, or 1, which draws FXAA instead. TAA, FXAA and no antialiasing take one sample whatever it says. Changing it makes the multisampled targets and pipelines again at the next frame." {
+    default 4
+    min 1
+    max 4
+  }
 }
 ```
 
-<sub>`api.ogt` line 2634</sub>
+<sub>`api.ogt` line 2663</sub>
 
 <a id="record-Environment"></a>
 
@@ -1500,7 +1956,7 @@ resource Environment {
 }
 ```
 
-<sub>`api.ogt` line 2719</sub>
+<sub>`api.ogt` line 2779</sub>
 
 <a id="record-PostEffects"></a>
 
@@ -1565,14 +2021,7 @@ Token `og.PostEffects`, registered under the schema name `og.PostEffects`; its v
 | `ssrSteps` | `number` | `32` | 4 … 128 | — | — | Steps along each ray (a binary refinement follows the hit). |
 | `ssrFade` | `number` | `0.15` | 0 … 1 | `ratio` | — | The fraction of the screen's edge, and of the march's end, over which a reflection fades into the probes'. |
 | `ssrIntensity` | `number` | `1` | 0 … 1 | — | tunable | How much of the reflection is laid over the frame; 1 is physically weighted by the surface's Fresnel. |
-| `custom1` | `Post` | `0` | — | — | — | The first custom post pass (og.load.post, a `type post` asset; 0 is none). PostEffects.custom1 to custom8 are an ordered list, as many as og-render runs (RenderCapabilities.maxCustomPosts): each runs over the one before it (the lit image for the first), after depth of field and motion blur and before exposure, bloom and the tone curve, and reads the lit image, depth and normals too (it turns the prepass on). Its parameters are set with og.render.setPostParam. A pass the device fails to compile is reported (og.render.postErrors) and skipped. |
-| `custom2` | `Post` | `0` | — | — | — | The second custom post pass, over the first's output (0 skips the slot). |
-| `custom3` | `Post` | `0` | — | — | — | The third custom post pass. |
-| `custom4` | `Post` | `0` | — | — | — | The fourth custom post pass. |
-| `custom5` | `Post` | `0` | — | — | — | The fifth custom post pass. |
-| `custom6` | `Post` | `0` | — | — | — | The sixth custom post pass. |
-| `custom7` | `Post` | `0` | — | — | — | The seventh custom post pass. |
-| `custom8` | `Post` | `0` | — | — | — | The eighth and last custom post pass, over every one before it. |
+| `custom` | `readonly Post[]` | `[]` | — | — | a list of at most 8 `Post` (`List.Post.8`): reads a frozen copy, writes a whole array | The custom post passes, in order (og.load.post, `type post` assets): at most RenderCapabilities.maxCustomPosts (8, og-render's MAX_CUSTOM_POSTS). Each runs over the one before it (the lit image for the first), after depth of field and motion blur and before exposure, bloom and the tone curve, and reads the lit image, depth and normals too (any pass turns the prepass on). Write the whole list: `post.custom = [grade, crt]`, `post.custom = []`; a look gives it on one line (`custom "post/tint.ogt" "post/crt.ogt"`). A 0 in it is skipped. Its parameters are set with og.render.setPostParam. A pass the device fails to compile is reported (og.render.postErrors) and skipped. |
 
 ```ogt
 resource PostEffects {
@@ -1778,18 +2227,11 @@ resource PostEffects {
     max 1
     tunable true
   }
-  field custom1 Post "The first custom post pass (og.load.post, a `type post` asset; 0 is none). PostEffects.custom1 to custom8 are an ordered list, as many as og-render runs (RenderCapabilities.maxCustomPosts): each runs over the one before it (the lit image for the first), after depth of field and motion blur and before exposure, bloom and the tone curve, and reads the lit image, depth and normals too (it turns the prepass on). Its parameters are set with og.render.setPostParam. A pass the device fails to compile is reported (og.render.postErrors) and skipped."
-  field custom2 Post "The second custom post pass, over the first's output (0 skips the slot)."
-  field custom3 Post "The third custom post pass."
-  field custom4 Post "The fourth custom post pass."
-  field custom5 Post "The fifth custom post pass."
-  field custom6 Post "The sixth custom post pass."
-  field custom7 Post "The seventh custom post pass."
-  field custom8 Post "The eighth and last custom post pass, over every one before it."
+  field custom List.Post.8 "The custom post passes, in order (og.load.post, `type post` assets): at most RenderCapabilities.maxCustomPosts (8, og-render's MAX_CUSTOM_POSTS). Each runs over the one before it (the lit image for the first), after depth of field and motion blur and before exposure, bloom and the tone curve, and reads the lit image, depth and normals too (any pass turns the prepass on). Write the whole list: `post.custom = [grade, crt]`, `post.custom = []`; a look gives it on one line (`custom \"post/tint.ogt\" \"post/crt.ogt\"`). A 0 in it is skipped. Its parameters are set with og.render.setPostParam. A pass the device fails to compile is reported (og.render.postErrors) and skipped."
 }
 ```
 
-<sub>`api.ogt` line 2799</sub>
+<sub>`api.ogt` line 2873</sub>
 
 <a id="record-Stylise"></a>
 
@@ -2044,7 +2486,7 @@ resource Stylise {
 }
 ```
 
-<sub>`api.ogt` line 3055</sub>
+<sub>`api.ogt` line 3129</sub>
 
 <a id="record-MaterialStyle"></a>
 
@@ -2109,7 +2551,7 @@ resource MaterialStyle {
 }
 ```
 
-<sub>`api.ogt` line 3248</sub>
+<sub>`api.ogt` line 3322</sub>
 
 <a id="record-Lighting2D"></a>
 
@@ -2148,7 +2590,7 @@ resource Lighting2D {
 }
 ```
 
-<sub>`api.ogt` line 3298</sub>
+<sub>`api.ogt` line 3372</sub>
 
 <a id="record-Light2D"></a>
 
@@ -2199,7 +2641,7 @@ component Light2D {
 }
 ```
 
-<sub>`api.ogt` line 3317</sub>
+<sub>`api.ogt` line 3391</sub>
 
 <a id="record-Occluder2D"></a>
 
@@ -2230,7 +2672,7 @@ component Occluder2D {
 }
 ```
 
-<sub>`api.ogt` line 3347</sub>
+<sub>`api.ogt` line 3421</sub>
 
 <a id="record-Decal"></a>
 
@@ -2285,7 +2727,7 @@ component Decal {
 }
 ```
 
-<sub>`api.ogt` line 3361</sub>
+<sub>`api.ogt` line 3435</sub>
 
 <a id="record-ParticleSystem"></a>
 
@@ -2322,7 +2764,7 @@ component ParticleSystem {
 }
 ```
 
-<sub>`api.ogt` line 3395</sub>
+<sub>`api.ogt` line 3469</sub>
 
 <a id="record-Trail"></a>
 
@@ -2398,7 +2840,7 @@ component Trail {
 }
 ```
 
-<sub>`api.ogt` line 3411</sub>
+<sub>`api.ogt` line 3485</sub>
 
 <a id="record-Beam"></a>
 
@@ -2464,13 +2906,13 @@ component Beam {
 }
 ```
 
-<sub>`api.ogt` line 3459</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.
 
@@ -2490,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). |
@@ -2511,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."
@@ -2546,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)." {
@@ -2599,7 +3043,7 @@ component Sprite {
 }
 ```
 
-<sub>`api.ogt` line 3667</sub>
+<sub>`api.ogt` line 3742</sub>
 
 <a id="record-Afterimage"></a>
 
@@ -2647,7 +3091,7 @@ component Afterimage {
 }
 ```
 
-<sub>`api.ogt` line 3755</sub>
+<sub>`api.ogt` line 3831</sub>
 
 <a id="record-ReflectionProbe"></a>
 
@@ -2700,7 +3144,7 @@ component ReflectionProbe {
 }
 ```
 
-<sub>`api.ogt` line 3978</sub>
+<sub>`api.ogt` line 4056</sub>
 
 <a id="record-Lines"></a>
 
@@ -2763,7 +3207,7 @@ component Lines {
 }
 ```
 
-<sub>`api.ogt` line 4461</sub>
+<sub>`api.ogt` line 4871</sub>
 
 <a id="record-Points"></a>
 
@@ -2817,7 +3261,7 @@ component Points {
 }
 ```
 
-<sub>`api.ogt` line 4498</sub>
+<sub>`api.ogt` line 4908</sub>
 
 <a id="record-CameraView"></a>
 
@@ -2924,7 +3368,7 @@ component CameraView {
 }
 ```
 
-<sub>`api.ogt` line 4621</sub>
+<sub>`api.ogt` line 5031</sub>
 
 <a id="record-Mirror"></a>
 
@@ -2969,7 +3413,7 @@ component Mirror {
 }
 ```
 
-<sub>`api.ogt` line 4693</sub>
+<sub>`api.ogt` line 5103</sub>
 
 <a id="record-RectLight"></a>
 
@@ -3019,7 +3463,7 @@ component RectLight {
 }
 ```
 
-<sub>`api.ogt` line 4755</sub>
+<sub>`api.ogt` line 5165</sub>
 
 <a id="record-LightVolume"></a>
 
@@ -3053,7 +3497,7 @@ component LightVolume {
 }
 ```
 
-<sub>`api.ogt` line 4782</sub>
+<sub>`api.ogt` line 5192</sub>
 
 ## Types
 
@@ -3069,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 2241</sub>
+<sub>`api.ogt` line 2248</sub>
 
 <a id="type-Material"></a>
 
@@ -3083,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 2242</sub>
+<sub>`api.ogt` line 2249</sub>
 
 <a id="type-Texture"></a>
 
@@ -3097,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 2243</sub>
+<sub>`api.ogt` line 2250</sub>
 
 <a id="type-Side"></a>
 
@@ -3122,7 +3566,7 @@ enum Side {
 }
 ```
 
-<sub>`api.ogt` line 2259</sub>
+<sub>`api.ogt` line 2266</sub>
 
 <a id="type-RenderTier"></a>
 
@@ -3153,7 +3597,7 @@ enum RenderTier {
 }
 ```
 
-<sub>`api.ogt` line 2266</sub>
+<sub>`api.ogt` line 2273</sub>
 
 <a id="type-Antialias"></a>
 
@@ -3182,7 +3626,7 @@ enum Antialias {
 }
 ```
 
-<sub>`api.ogt` line 2276</sub>
+<sub>`api.ogt` line 2283</sub>
 
 <a id="type-PointShadows"></a>
 
@@ -3207,7 +3651,7 @@ enum PointShadows {
 }
 ```
 
-<sub>`api.ogt` line 2285</sub>
+<sub>`api.ogt` line 2292</sub>
 
 <a id="type-TaaHistory"></a>
 
@@ -3230,7 +3674,7 @@ enum TaaHistory {
 }
 ```
 
-<sub>`api.ogt` line 2292</sub>
+<sub>`api.ogt` line 2299</sub>
 
 <a id="type-DebugView"></a>
 
@@ -3259,7 +3703,7 @@ enum DebugView {
 }
 ```
 
-<sub>`api.ogt` line 2298</sub>
+<sub>`api.ogt` line 2305</sub>
 
 <a id="type-RenderOptions"></a>
 
@@ -3299,7 +3743,7 @@ struct RenderOptions {
 }
 ```
 
-<sub>`api.ogt` line 2307</sub>
+<sub>`api.ogt` line 2314</sub>
 
 <a id="type-StandardMaterialDesc"></a>
 
@@ -3569,7 +4013,7 @@ struct StandardMaterialDesc {
 }
 ```
 
-<sub>`api.ogt` line 2326</sub>
+<sub>`api.ogt` line 2333</sub>
 
 <a id="type-ToneMapping"></a>
 
@@ -3594,7 +4038,59 @@ enum ToneMapping {
 }
 ```
 
-<sub>`api.ogt` line 2620</sub>
+<sub>`api.ogt` line 2627</sub>
+
+<a id="type-GraphicsQuality"></a>
+
+### `GraphicsQuality` (enum)
+
+A graphics preset: a row of RenderSettings' quality fields that og.render.applyQuality writes (its doc has the table). The settings screen (og.ui.settingsScreen) offers the three.
+
+A string: one of the variants below. The zero value is `"medium"`.
+
+| Variant | Doc |
+|---|---|
+| `"medium"` | The full frame: every quality field at its default. |
+| `"low"` | The cheapest frame: no rect-light shadows, two shadowed lights, half-size shadow maps, plain fog, hard particles, no screen-space reflections or ambient occlusion, FXAA for MSAA. |
+| `"high"` | The full frame with the shadow maps at twice their side. |
+
+```ogt
+enum GraphicsQuality {
+  doc "A graphics preset: a row of RenderSettings' quality fields that og.render.applyQuality writes (its doc has the table). The settings screen (og.ui.settingsScreen) offers the three."
+  variant medium "The full frame: every quality field at its default."
+  variant low "The cheapest frame: no rect-light shadows, two shadowed lights, half-size shadow maps, plain fog, hard particles, no screen-space reflections or ambient occlusion, FXAA for MSAA."
+  variant high "The full frame with the shadow maps at twice their side."
+}
+```
+
+<sub>`api.ogt` line 2641</sub>
+
+<a id="type-QualityPreset"></a>
+
+### `QualityPreset` (enum)
+
+The preset RenderSettings' quality fields were last written with (RenderSettings.quality).
+
+A string: one of the variants below. The zero value is `"none"`.
+
+| Variant | Doc |
+|---|---|
+| `"none"` | No preset applied: the fields are their defaults or the game's own. |
+| `"low"` | og.render.applyQuality(world, "low"). |
+| `"medium"` | og.render.applyQuality(world, "medium"). |
+| `"high"` | og.render.applyQuality(world, "high"). |
+
+```ogt
+enum QualityPreset {
+  doc "The preset RenderSettings' quality fields were last written with (RenderSettings.quality)."
+  variant none "No preset applied: the fields are their defaults or the game's own."
+  variant low "og.render.applyQuality(world, \"low\")."
+  variant medium "og.render.applyQuality(world, \"medium\")."
+  variant high "og.render.applyQuality(world, \"high\")."
+}
+```
+
+<sub>`api.ogt` line 2648</sub>
 
 <a id="type-Lut"></a>
 
@@ -3608,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 2694</sub>
+<sub>`api.ogt` line 2754</sub>
 
 <a id="type-EnvironmentMap"></a>
 
@@ -3622,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 2695</sub>
+<sub>`api.ogt` line 2755</sub>
 
 <a id="type-ParticleEmitter"></a>
 
@@ -3636,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 2696</sub>
+<sub>`api.ogt` line 2756</sub>
 
 <a id="type-AoMethod"></a>
 
@@ -3661,7 +4157,7 @@ enum AoMethod {
 }
 ```
 
-<sub>`api.ogt` line 2746</sub>
+<sub>`api.ogt` line 2806</sub>
 
 <a id="type-DofQuality"></a>
 
@@ -3684,7 +4180,7 @@ enum DofQuality {
 }
 ```
 
-<sub>`api.ogt` line 2760</sub>
+<sub>`api.ogt` line 2820</sub>
 
 <a id="type-SpriteBlend"></a>
 
@@ -3707,7 +4203,32 @@ enum SpriteBlend {
 }
 ```
 
-<sub>`api.ogt` line 2773</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>
 
@@ -3730,7 +4251,7 @@ enum StripBlend {
 }
 ```
 
-<sub>`api.ogt` line 2786</sub>
+<sub>`api.ogt` line 2860</sub>
 
 <a id="type-Palette"></a>
 
@@ -3744,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 3014</sub>
+<sub>`api.ogt` line 3081</sub>
 
 <a id="type-Look"></a>
 
@@ -3758,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 3015</sub>
+<sub>`api.ogt` line 3082</sub>
 
 <a id="type-DitherPattern"></a>
 
@@ -3789,7 +4310,7 @@ enum DitherPattern {
 }
 ```
 
-<sub>`api.ogt` line 3024</sub>
+<sub>`api.ogt` line 3098</sub>
 
 <a id="type-StyliseSpace"></a>
 
@@ -3814,7 +4335,7 @@ enum StyliseSpace {
 }
 ```
 
-<sub>`api.ogt` line 3041</sub>
+<sub>`api.ogt` line 3115</sub>
 
 <a id="type-LookInfo"></a>
 
@@ -3845,7 +4366,7 @@ struct LookInfo {
 }
 ```
 
-<sub>`api.ogt` line 3287</sub>
+<sub>`api.ogt` line 3361</sub>
 
 <a id="type-RibbonPoint"></a>
 
@@ -3885,7 +4406,7 @@ struct RibbonPoint {
 }
 ```
 
-<sub>`api.ogt` line 3499</sub>
+<sub>`api.ogt` line 3573</sub>
 
 <a id="type-RibbonDesc"></a>
 
@@ -3916,7 +4437,7 @@ struct RibbonDesc {
 }
 ```
 
-<sub>`api.ogt` line 3520</sub>
+<sub>`api.ogt` line 3594</sub>
 
 <a id="type-TextDesc"></a>
 
@@ -3978,7 +4499,7 @@ struct TextDesc {
 }
 ```
 
-<sub>`api.ogt` line 3539</sub>
+<sub>`api.ogt` line 3613</sub>
 
 <a id="type-TextMeasureDesc"></a>
 
@@ -4007,7 +4528,7 @@ struct TextMeasureDesc {
 }
 ```
 
-<sub>`api.ogt` line 3573</sub>
+<sub>`api.ogt` line 3647</sub>
 
 <a id="type-TextMetrics"></a>
 
@@ -4030,13 +4551,13 @@ struct TextMetrics {
 }
 ```
 
-<sub>`api.ogt` line 3584</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.
 
@@ -4062,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). |
@@ -4072,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`."
@@ -4128,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)."
@@ -4141,7 +4664,7 @@ struct SpriteDesc {
 }
 ```
 
-<sub>`api.ogt` line 3591</sub>
+<sub>`api.ogt` line 3665</sub>
 
 <a id="type-FloatingTextDesc"></a>
 
@@ -4229,7 +4752,7 @@ struct FloatingTextDesc {
 }
 ```
 
-<sub>`api.ogt` line 3782</sub>
+<sub>`api.ogt` line 3858</sub>
 
 <a id="type-BoxGeometryDesc"></a>
 
@@ -4271,7 +4794,7 @@ struct BoxGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3854</sub>
+<sub>`api.ogt` line 3930</sub>
 
 <a id="type-PlaneGeometryDesc"></a>
 
@@ -4307,7 +4830,7 @@ struct PlaneGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3877</sub>
+<sub>`api.ogt` line 3953</sub>
 
 <a id="type-SphereGeometryDesc"></a>
 
@@ -4347,7 +4870,7 @@ struct SphereGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 3895</sub>
+<sub>`api.ogt` line 3971</sub>
 
 <a id="type-RenderCapabilities"></a>
 
@@ -4370,11 +4893,13 @@ What the renderer can do on this device. Backend limits are reported here, never
 | `reflectionProbes` | `number` | `0` | — | — | — | How many og.ReflectionProbe components one frame samples (MAX_REFLECTION_PROBES on every tier). |
 | `renderTargetDepth` | `boolean` | `false` | — | — | — | Whether a render target made with `depth` gets its view's depth drawn: true on every tier with a renderer (WebGPU, Vulkan, Metal and WebGL2 alike), false without one. The depth comes from the view's own depth prepass of its opaque meshes into a linear-depth colour target, never from its depth buffer, which WebGL2 cannot read in a shader. |
 | `maxRenderTargetSize` | `number` | `0` | — | — | — | The largest side of a render target (the device's largest 2D texture). |
-| `maxCustomPosts` | `number` | `0` | — | — | — | The most custom post passes a frame runs: 8 on every tier, PostEffects.custom1 to custom8 (numbered fields, as a reflected record has no list field). |
+| `maxCustomPosts` | `number` | `0` | — | — | — | The most custom post passes a frame runs: 8 on every tier, PostEffects.custom's capacity. |
 | `volumetricFog` | `VolumetricFog` | `"froxel"` | — | — | — | How Fog.volumetric is drawn on this device: a froxel grid (the full tier) or a raymarch along each pixel's view ray (WebGL2), each lit by the sun through its shadows and by the point, spot and rect lights around each sample (up to volumetricLights of them) through their shadows and cookies. |
 | `volumetricLights` | `number` | `0` | — | — | — | The most point, spot and rect lights that light one sample of Fog.volumetric: those of its screen cluster, MAX_CLUSTER_LIGHTS (64) in the froxel grid, 8 in WebGL2's raymarch, the brightest at the camera first. |
 | `maxLightCookies` | `number` | `0` | — | — | — | The most light cookie layers one frame draws (24 on every tier): a SpotLight.cookie takes one, a PointLight.cookie six (its cube's faces), and a texture several lights of one kind share takes its layers once. Cookies past it, in the order of their lights' entities, are not drawn: those lights shine without them, and the log names them in a warning. |
-| `gpuTimestamps` | `boolean` | `false` | — | — | — | Whether the device times each render pass on the GPU (timestamp queries: Vulkan, Metal and D3D12 adapters that have them, WebGPU with `timestamp-query`; never WebGL2): ProbeTimings.gpuPasses and the trace's gpu thread are filled only where it is true. |
+| `gpuTimestamps` | `boolean` | `false` | — | — | — | Whether the device times each render pass on the GPU (timestamp queries: Vulkan, Metal and D3D12 adapters that have them, WebGPU with `timestamp-query`; never WebGL2, and never in a publish build, which leaves the queries out): ProbeTimings.gpuPasses and the trace's gpu thread are filled only where it is true. |
+| `spriteAnisotropy` | `number` | `0` | — | — | — | The anisotropic filtering of sprites and og.ui's images (text is not filtered anisotropically: its distance field would lose its edge): 16 where the device filters anisotropically (WebGPU, Vulkan, Metal, WebGL2 with EXT_texture_filter_anisotropic), 1 where it has none and on a software rasterizer (the vulkan-cpu tier: lavapipe's anisotropic filter softens even an image drawn 1:1), 0 without a renderer. Above 1, an image squeezed along one axis keeps the other axis's detail: a style's nine-slice middle squeezed into a short button keeps its outline as crisp as the corners. At 1 the squeezed piece reads a smaller mip level and blurs; og.ui bounds a middle's squeeze at twice its art, so the outline there is one mip level softer than the corners. |
+| `world3d` | `boolean` | `false` | — | — | — | Whether the renderer draws the 3D world subsystems: terrain, planar water (og.Water), the 3D fluids, scattered copies and volumetric fog. False in the 2D profile's publish and lanes modules, which leave them out (a scene's are not drawn, og.terrain's calls and a SHAPE_HEIGHTFIELD collider answer a refusal naming this field, and `og build --publish` refuses a 2D project whose scenes hold og.Terrain, og.TerrainScatter, og.Water, og.WaterSurface or og.Fluid3D, by scene file and line); true in the 3D modules, the dev module and the native host. |
 
 ```ogt
 struct RenderCapabilities {
@@ -4392,15 +4917,17 @@ struct RenderCapabilities {
   field reflectionProbes u32 "How many og.ReflectionProbe components one frame samples (MAX_REFLECTION_PROBES on every tier)."
   field renderTargetDepth bool "Whether a render target made with `depth` gets its view's depth drawn: true on every tier with a renderer (WebGPU, Vulkan, Metal and WebGL2 alike), false without one. The depth comes from the view's own depth prepass of its opaque meshes into a linear-depth colour target, never from its depth buffer, which WebGL2 cannot read in a shader."
   field maxRenderTargetSize u32 "The largest side of a render target (the device's largest 2D texture)."
-  field maxCustomPosts u32 "The most custom post passes a frame runs: 8 on every tier, PostEffects.custom1 to custom8 (numbered fields, as a reflected record has no list field)."
+  field maxCustomPosts u32 "The most custom post passes a frame runs: 8 on every tier, PostEffects.custom's capacity."
   field volumetricFog VolumetricFog "How Fog.volumetric is drawn on this device: a froxel grid (the full tier) or a raymarch along each pixel's view ray (WebGL2), each lit by the sun through its shadows and by the point, spot and rect lights around each sample (up to volumetricLights of them) through their shadows and cookies."
   field volumetricLights u32 "The most point, spot and rect lights that light one sample of Fog.volumetric: those of its screen cluster, MAX_CLUSTER_LIGHTS (64) in the froxel grid, 8 in WebGL2's raymarch, the brightest at the camera first."
   field maxLightCookies u32 "The most light cookie layers one frame draws (24 on every tier): a SpotLight.cookie takes one, a PointLight.cookie six (its cube's faces), and a texture several lights of one kind share takes its layers once. Cookies past it, in the order of their lights' entities, are not drawn: those lights shine without them, and the log names them in a warning."
-  field gpuTimestamps bool "Whether the device times each render pass on the GPU (timestamp queries: Vulkan, Metal and D3D12 adapters that have them, WebGPU with `timestamp-query`; never WebGL2): ProbeTimings.gpuPasses and the trace's gpu thread are filled only where it is true."
+  field gpuTimestamps bool "Whether the device times each render pass on the GPU (timestamp queries: Vulkan, Metal and D3D12 adapters that have them, WebGPU with `timestamp-query`; never WebGL2, and never in a publish build, which leaves the queries out): ProbeTimings.gpuPasses and the trace's gpu thread are filled only where it is true."
+  field spriteAnisotropy u32 "The anisotropic filtering of sprites and og.ui's images (text is not filtered anisotropically: its distance field would lose its edge): 16 where the device filters anisotropically (WebGPU, Vulkan, Metal, WebGL2 with EXT_texture_filter_anisotropic), 1 where it has none and on a software rasterizer (the vulkan-cpu tier: lavapipe's anisotropic filter softens even an image drawn 1:1), 0 without a renderer. Above 1, an image squeezed along one axis keeps the other axis's detail: a style's nine-slice middle squeezed into a short button keeps its outline as crisp as the corners. At 1 the squeezed piece reads a smaller mip level and blurs; og.ui bounds a middle's squeeze at twice its art, so the outline there is one mip level softer than the corners."
+  field world3d bool "Whether the renderer draws the 3D world subsystems: terrain, planar water (og.Water), the 3D fluids, scattered copies and volumetric fog. False in the 2D profile's publish and lanes modules, which leave them out (a scene's are not drawn, og.terrain's calls and a SHAPE_HEIGHTFIELD collider answer a refusal naming this field, and `og build --publish` refuses a 2D project whose scenes hold og.Terrain, og.TerrainScatter, og.Water, og.WaterSurface or og.Fluid3D, by scene file and line); true in the 3D modules, the dev module and the native host."
 }
 ```
 
-<sub>`api.ogt` line 3941</sub>
+<sub>`api.ogt` line 4017</sub>
 
 <a id="type-ReflectionProbeMode"></a>
 
@@ -4423,7 +4950,7 @@ enum ReflectionProbeMode {
 }
 ```
 
-<sub>`api.ogt` line 3965</sub>
+<sub>`api.ogt` line 4043</sub>
 
 <a id="type-Shader"></a>
 
@@ -4437,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 4025</sub>
+<sub>`api.ogt` line 4103</sub>
 
 <a id="type-BufferGeometryDesc"></a>
 
@@ -4478,7 +5005,7 @@ struct BufferGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4080</sub>
+<sub>`api.ogt` line 4183</sub>
 
 <a id="type-GeometryInfo"></a>
 
@@ -4509,7 +5036,7 @@ struct GeometryInfo {
 }
 ```
 
-<sub>`api.ogt` line 4096</sub>
+<sub>`api.ogt` line 4199</sub>
 
 <a id="type-CylinderGeometryDesc"></a>
 
@@ -4568,7 +5095,7 @@ struct CylinderGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4131</sub>
+<sub>`api.ogt` line 4234</sub>
 
 <a id="type-ConeGeometryDesc"></a>
 
@@ -4612,7 +5139,7 @@ struct ConeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4167</sub>
+<sub>`api.ogt` line 4270</sub>
 
 <a id="type-CapsuleGeometryDesc"></a>
 
@@ -4659,7 +5186,7 @@ struct CapsuleGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4191</sub>
+<sub>`api.ogt` line 4294</sub>
 
 <a id="type-TorusGeometryDesc"></a>
 
@@ -4706,7 +5233,7 @@ struct TorusGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4218</sub>
+<sub>`api.ogt` line 4321</sub>
 
 <a id="type-RingGeometryDesc"></a>
 
@@ -4757,7 +5284,7 @@ struct RingGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4245</sub>
+<sub>`api.ogt` line 4348</sub>
 
 <a id="type-CircleGeometryDesc"></a>
 
@@ -4797,7 +5324,7 @@ struct CircleGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4275</sub>
+<sub>`api.ogt` line 4378</sub>
 
 <a id="type-TubeGeometryDesc"></a>
 
@@ -4841,7 +5368,499 @@ struct TubeGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4296</sub>
+<sub>`api.ogt` line 4399</sub>
+
+<a id="type-ShapePoints"></a>
+
+### `ShapePoints` (struct)
+
+A shape as points, what og.Shape.extractPoints returns and what shapeGeometry, extrudeGeometry and sweepGeometry read: the outline, then each hole. A repeated closing point is dropped, as three.js drops it.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `shape` | `readonly Vector2[]` | `[]` | — | — | — | The outline's points, in order. |
+| `holes` | `readonly (readonly Vector2[])[]` | `[]` | — | — | — | Each hole's points, in order. |
+
+```ogt
+struct ShapePoints {
+  doc "A shape as points, what og.Shape.extractPoints returns and what shapeGeometry, extrudeGeometry and sweepGeometry read: the outline, then each hole. A repeated closing point is dropped, as three.js drops it."
+  field shape List.Vector2 "The outline's points, in order."
+  field holes List.List.Vector2 "Each hole's points, in order."
+}
+```
+
+<sub>`api.ogt` line 4473</sub>
+
+<a id="type-ShapeGeometryDesc"></a>
+
+### `ShapeGeometryDesc` (desc struct)
+
+A flat shape with holes in the xy plane facing +Z, as three.js ShapeGeometry(shapes, curveSegments): triangulated by earcut (three.js's own port), the outline made clockwise and the holes counter-clockwise first, so its vertices and triangles are three.js's for the same shape. uvs are world x and y (v flipped to run down the image).
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `shapes` | `Path2 \| readonly Path2[] \| readonly Vector2[] \| null` | `null` | — | — | — | One og.Shape (an og.Path2 is a shape without holes), a list of them, or the outline's points. Without it, three.js's default triangle (0, 0.5), (-0.5, -0.5), (0.5, -0.5). |
+| `curveSegments` | `number` | `12` | ≥ 1 | — | — | Points per curve when an og.Shape's curves are flattened (three.js extractPoints(curveSegments); an ellipse takes twice as many, a spline as many per point). |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too (BufferGeometryDesc.physics). |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later (BufferGeometryDesc.dynamic). |
+
+```ogt
+struct ShapeGeometryDesc {
+  doc "A flat shape with holes in the xy plane facing +Z, as three.js ShapeGeometry(shapes, curveSegments): triangulated by earcut (three.js's own port), the outline made clockwise and the holes counter-clockwise first, so its vertices and triangles are three.js's for the same shape. uvs are world x and y (v flipped to run down the image)."
+  desc true
+  field shapes Option.OneOf.Path2.OneOf.List.Path2.List.Vector2 "One og.Shape (an og.Path2 is a shape without holes), a list of them, or the outline's points. Without it, three.js's default triangle (0, 0.5), (-0.5, -0.5), (0.5, -0.5)."
+  field curveSegments u32 "Points per curve when an og.Shape's curves are flattened (three.js extractPoints(curveSegments); an ellipse takes twice as many, a spline as many per point)." {
+    default 12
+    min 1
+  }
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too (BufferGeometryDesc.physics)." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later (BufferGeometryDesc.dynamic)."
+}
+```
+
+<sub>`api.ogt` line 4479</sub>
+
+<a id="type-ExtrudeGeometryDesc"></a>
+
+### `ExtrudeGeometryDesc` (desc struct)
+
+Shapes pushed along +Z, or along a path, as three.js ExtrudeGeometry(shapes, options) with its option names and defaults: a closed solid, its lids from earcut and its walls ring by ring, rounded by a bevel of bevelSegments rings at each face. Unindexed as three.js's (every triangle its own vertices, flat normals), three.js's vertex order and counts; uvs from three.js's WorldUVGenerator (v flipped to run down the image).
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `shapes` | `Path2 \| readonly Path2[] \| readonly Vector2[] \| null` | `null` | — | — | — | One og.Shape, a list of them, or the outline's points. Without it, three.js's default square of side 1. |
+| `depth` | `number` | `1` | ≥ 0 | `m` | — | How far the shape is pushed along +Z (without extrudePath). |
+| `steps` | `number` | `1` | ≥ 1 | — | — | Rings along the depth or the path. |
+| `bevelEnabled` | `boolean` | `true` | — | — | — | Round the edges of both faces. |
+| `bevelThickness` | `number` | `0.2` | ≥ 0 | `m` | — | How far the bevel reaches beyond each face, along z. |
+| `bevelSize` | `number \| null` | `null` | — | `m` | — | How far the bevel reaches out from the outline. Null or unset, bevelThickness - 0.1, as three.js derives it (0.1 at the default thickness, 0 at a thickness of 0.1). |
+| `bevelOffset` | `number` | `0` | — | `m` | — | How far the bevel starts out from the outline. |
+| `bevelSegments` | `number` | `3` | ≥ 1 | — | — | Rings in each bevel. |
+| `curveSegments` | `number` | `12` | ≥ 1 | — | — | Points per curve when an og.Shape's curves are flattened. |
+| `extrudePath` | `Path` | `0` | — | — | — | A path (og.path.create or og.path.find) to extrude along instead of +Z: the shape's x along the path's normal and y along its binormal (three.js's Frenet frames), steps rings evenly spaced along it. A path turns the bevel off, as three.js. 0 extrudes along +Z. |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct ExtrudeGeometryDesc {
+  doc "Shapes pushed along +Z, or along a path, as three.js ExtrudeGeometry(shapes, options) with its option names and defaults: a closed solid, its lids from earcut and its walls ring by ring, rounded by a bevel of bevelSegments rings at each face. Unindexed as three.js's (every triangle its own vertices, flat normals), three.js's vertex order and counts; uvs from three.js's WorldUVGenerator (v flipped to run down the image)."
+  desc true
+  field shapes Option.OneOf.Path2.OneOf.List.Path2.List.Vector2 "One og.Shape, a list of them, or the outline's points. Without it, three.js's default square of side 1."
+  field depth f32 "How far the shape is pushed along +Z (without extrudePath)." {
+    default 1
+    min 0
+    unit m
+  }
+  field steps u32 "Rings along the depth or the path." {
+    default 1
+    min 1
+  }
+  field bevelEnabled bool "Round the edges of both faces." {
+    default true
+  }
+  field bevelThickness f32 "How far the bevel reaches beyond each face, along z." {
+    default 0.2
+    min 0
+    unit m
+  }
+  field bevelSize Option.f32 "How far the bevel reaches out from the outline. Null or unset, bevelThickness - 0.1, as three.js derives it (0.1 at the default thickness, 0 at a thickness of 0.1)." {
+    unit m
+  }
+  field bevelOffset f32 "How far the bevel starts out from the outline." {
+    unit m
+  }
+  field bevelSegments u32 "Rings in each bevel." {
+    default 3
+    min 1
+  }
+  field curveSegments u32 "Points per curve when an og.Shape's curves are flattened." {
+    default 12
+    min 1
+  }
+  field extrudePath Path "A path (og.path.create or og.path.find) to extrude along instead of +Z: the shape's x along the path's normal and y along its binormal (three.js's Frenet frames), steps rings evenly spaced along it. A path turns the bevel off, as three.js. 0 extrudes along +Z."
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4496</sub>
+
+<a id="type-LatheGeometryDesc"></a>
+
+### `LatheGeometryDesc` (desc struct)
+
+A profile turned round +Y, as three.js LatheGeometry(points, segments, phiStart, phiLength): vases, bottles, columns, wheels. three.js's vertices, indices and smooth normals; u round the axis, v along the profile (flipped to run down the image). A whole turn's seam meets exactly.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `points` | `readonly Vector2[]` | `[]` | — | `m` | — | The profile, x the distance from the axis and y the height, in order (at least two). Without it, three.js's default (0, -0.5), (0.5, 0), (0, 0.5). |
+| `segments` | `number` | `12` | ≥ 1 | — | — | Segments round the axis. |
+| `phiStart` | `number` | `0` | — | `rad` | — | Where the turn starts, from +Z towards +X. |
+| `phiLength` | `number` | `6.283185307179586` | — | `rad` | — | How far it turns; 2 pi is whole (clamped to it). |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct LatheGeometryDesc {
+  doc "A profile turned round +Y, as three.js LatheGeometry(points, segments, phiStart, phiLength): vases, bottles, columns, wheels. three.js's vertices, indices and smooth normals; u round the axis, v along the profile (flipped to run down the image). A whole turn's seam meets exactly."
+  desc true
+  field points List.Vector2 "The profile, x the distance from the axis and y the height, in order (at least two). Without it, three.js's default (0, -0.5), (0.5, 0), (0, 0.5)." {
+    unit m
+  }
+  field segments u32 "Segments round the axis." {
+    default 12
+    min 1
+  }
+  field phiStart f32 "Where the turn starts, from +Z towards +X." {
+    unit rad
+  }
+  field phiLength f32 "How far it turns; 2 pi is whole (clamped to it)." {
+    default 6.283185307179586
+    unit rad
+  }
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4541</sub>
+
+<a id="type-PolyhedronGeometryDesc"></a>
+
+### `PolyhedronGeometryDesc` (desc struct)
+
+A polyhedron from vertices and faces, every face subdivided `detail` times and every vertex pushed onto the sphere of `radius`, as three.js PolyhedronGeometry(vertices, indices, radius, detail): unindexed, flat normals at detail 0 and the sphere's above, three.js's spherical uvs.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `vertices` | `readonly number[]` | `[]` | — | — | — | The corners, x y z each (three.js's flat array). |
+| `indices` | `readonly number[]` | `[]` | — | — | — | The faces, three corner indices each, counter-clockwise seen from outside. |
+| `radius` | `number` | `1` | ≥ 0 | `m` | — | The sphere the vertices are pushed onto. |
+| `detail` | `number` | `0` | ≤ 64 | — | — | Subdivisions of each face: (detail + 1)² triangles a face. |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct PolyhedronGeometryDesc {
+  doc "A polyhedron from vertices and faces, every face subdivided `detail` times and every vertex pushed onto the sphere of `radius`, as three.js PolyhedronGeometry(vertices, indices, radius, detail): unindexed, flat normals at detail 0 and the sphere's above, three.js's spherical uvs."
+  desc true
+  field vertices List.f32 "The corners, x y z each (three.js's flat array)."
+  field indices List.u32 "The faces, three corner indices each, counter-clockwise seen from outside."
+  field radius f32 "The sphere the vertices are pushed onto." {
+    default 1
+    min 0
+    unit m
+  }
+  field detail u32 "Subdivisions of each face: (detail + 1)² triangles a face." {
+    max 64
+  }
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4567</sub>
+
+<a id="type-SolidGeometryDesc"></a>
+
+### `SolidGeometryDesc` (desc struct)
+
+A regular solid, as three.js IcosahedronGeometry, DodecahedronGeometry, OctahedronGeometry and TetrahedronGeometry(radius, detail): PolyhedronGeometryDesc with the solid's own vertices and faces. An icosahedron at detail 2 or more is a sphere with even triangles.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `radius` | `number` | `1` | ≥ 0 | `m` | — | The radius. |
+| `detail` | `number` | `0` | ≤ 64 | — | — | Subdivisions of each face. |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct SolidGeometryDesc {
+  doc "A regular solid, as three.js IcosahedronGeometry, DodecahedronGeometry, OctahedronGeometry and TetrahedronGeometry(radius, detail): PolyhedronGeometryDesc with the solid's own vertices and faces. An icosahedron at detail 2 or more is a sphere with even triangles."
+  desc true
+  field radius f32 "The radius." {
+    default 1
+    min 0
+    unit m
+  }
+  field detail u32 "Subdivisions of each face." {
+    max 64
+  }
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4589</sub>
+
+<a id="type-SweepKey"></a>
+
+### `SweepKey` (struct)
+
+A value at a fraction of a sweep's path: linear between keys, held before the first and past the last.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `t` | `number` | `0` | — | `ratio` | — | The fraction of the path's length, 0 to 1. |
+| `value` | `number` | `0` | — | — | — | The value there. |
+
+```ogt
+struct SweepKey {
+  doc "A value at a fraction of a sweep's path: linear between keys, held before the first and past the last."
+  field t f32 "The fraction of the path's length, 0 to 1." {
+    unit ratio
+  }
+  field value f32 "The value there."
+}
+```
+
+<sub>`api.ogt` line 4609</sub>
+
+<a id="type-SweepGeometryDesc"></a>
+
+### `SweepGeometryDesc` (desc struct)
+
+A section swept along a path, scaled and twisted over it: horns, tusks, handles, blades, tapered pipes, twisted columns (img2threejs's tapered sweep; three.js has no class for it). The section's x lies along the path's normal and y along its binormal (three.js's Frenet frames), rings evenly spaced along the path's length; u runs along the path, v round the section (flipped to run down the image), the sides smooth. An open path's ends are capped.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `section` | `Path2 \| readonly Vector2[] \| null` | `null` | — | — | — | The section's outline: an og.Shape or og.Path2 (flattened by curveSegments; holes are not swept) or its points, at least three, either winding. |
+| `path` | `Path` | `0` | — | — | — | The path (og.path.create or og.path.find). |
+| `steps` | `number` | `64` | ≥ 1 | — | — | Rings along the path, less one. |
+| `scale` | `readonly SweepKey[]` | `[]` | — | — | — | The section's scale over the path (none: 1 throughout). A horn: [{ t: 0, value: 1 }, { t: 1, value: 0.05 }]. |
+| `twist` | `readonly SweepKey[]` | `[]` | — | — | — | The section's turn round the path over its length, in radians (none: 0). |
+| `caps` | `boolean` | `true` | — | — | — | Close the ends of an open path. |
+| `curveSegments` | `number` | `12` | ≥ 1 | — | — | Points per curve when an og.Shape section is flattened. |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct SweepGeometryDesc {
+  doc "A section swept along a path, scaled and twisted over it: horns, tusks, handles, blades, tapered pipes, twisted columns (img2threejs's tapered sweep; three.js has no class for it). The section's x lies along the path's normal and y along its binormal (three.js's Frenet frames), rings evenly spaced along the path's length; u runs along the path, v round the section (flipped to run down the image), the sides smooth. An open path's ends are capped."
+  desc true
+  field section Option.OneOf.Path2.List.Vector2 "The section's outline: an og.Shape or og.Path2 (flattened by curveSegments; holes are not swept) or its points, at least three, either winding."
+  field path Path "The path (og.path.create or og.path.find)."
+  field steps u32 "Rings along the path, less one." {
+    default 64
+    min 1
+  }
+  field scale List.SweepKey "The section's scale over the path (none: 1 throughout). A horn: [{ t: 0, value: 1 }, { t: 1, value: 0.05 }]."
+  field twist List.SweepKey "The section's turn round the path over its length, in radians (none: 0)."
+  field caps bool "Close the ends of an open path." {
+    default true
+  }
+  field curveSegments u32 "Points per curve when an og.Shape section is flattened." {
+    default 12
+    min 1
+  }
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4617</sub>
+
+<a id="type-MirrorAxis"></a>
+
+### `MirrorAxis` (enum)
+
+The world axis a part is mirrored along, after its placement.
+
+A string: one of the variants below. The zero value is `"none"`.
+
+| Variant | Doc |
+|---|---|
+| `"none"` | Not mirrored. |
+| `"x"` | x negated: the mirror image across the yz plane. |
+| `"y"` | y negated: across the xz plane. |
+| `"z"` | z negated: across the xy plane. |
+
+```ogt
+enum MirrorAxis {
+  doc "The world axis a part is mirrored along, after its placement."
+  variant none "Not mirrored."
+  variant x "x negated: the mirror image across the yz plane."
+  variant y "y negated: across the xz plane."
+  variant z "z negated: across the xy plane."
+}
+```
+
+<sub>`api.ogt` line 4644</sub>
+
+<a id="type-GeometryPart"></a>
+
+### `GeometryPart` (desc struct)
+
+A geometry placed as an Object3D is (scale, then rotate, then move), then mirrored: one part of og.render.mergeGeometries or an operand of og.render.csgGeometry.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `geometry` | `Geometry` | `0` | — | — | — | Any geometry: made, a primitive or a loaded glTF's. |
+| `position` | `Vector3` | `{ x: 0, y: 0, z: 0 }` | — | `m` | — | Where it goes. |
+| `quaternion` | `Quaternion` | `{ x: 0, y: 0, z: 0, w: 1 }` | — | — | — | How it turns. |
+| `scale` | `Vector3` | `{ x: 1, y: 1, z: 1 }` | — | — | — | Its scale (a negative component mirrors it as `mirror` does). |
+| `mirror` | `MirrorAxis` | `"none"` | — | — | — | Mirror it along a world axis after placing it: a symmetric prop is one half twice, the second mirrored. |
+
+```ogt
+struct GeometryPart {
+  doc "A geometry placed as an Object3D is (scale, then rotate, then move), then mirrored: one part of og.render.mergeGeometries or an operand of og.render.csgGeometry."
+  desc true
+  field geometry Geometry "Any geometry: made, a primitive or a loaded glTF's."
+  field position Vector3 "Where it goes." {
+    unit m
+  }
+  field quaternion Quaternion "How it turns."
+  field scale Vector3 "Its scale (a negative component mirrors it as `mirror` does)." {
+    default 1 1 1
+  }
+  field mirror MirrorAxis "Mirror it along a world axis after placing it: a symmetric prop is one half twice, the second mirrored."
+}
+```
+
+<sub>`api.ogt` line 4652</sub>
+
+<a id="type-CsgOp"></a>
+
+### `CsgOp` (enum)
+
+A boolean operation on two solids.
+
+A string: one of the variants below. The zero value is `"union"`.
+
+| Variant | Doc |
+|---|---|
+| `"union"` | Everything in either: a + b. |
+| `"subtract"` | What of a is not in b: a - b (holes, notches, a dice's pips). |
+| `"intersect"` | What is in both. |
+
+```ogt
+enum CsgOp {
+  doc "A boolean operation on two solids."
+  variant union "Everything in either: a + b."
+  variant subtract "What of a is not in b: a - b (holes, notches, a dice's pips)."
+  variant intersect "What is in both."
+}
+```
+
+<sub>`api.ogt` line 4666</sub>
+
+<a id="type-CsgGeometryDesc"></a>
+
+### `CsgGeometryDesc` (desc struct)
+
+Two closed geometries combined by a boolean operation, each placed first: a box with a hole bored through it, a dice, a window cut in a wall. The result is closed when both are (every edge shared by two triangles, wound opposite), every piece keeps its source's normals, uvs and colours (b's turned inside out where it is subtracted). Where a plane side or an edge crossing is decided, the decision is exact (Shewchuk's predicates), so every host makes the same cuts; faces that coincide keep one copy or none, as the operation says.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `op` | `CsgOp` | `"union"` | — | — | — | The operation. |
+| `a` | `GeometryPart` | `{}` | — | — | — | The first operand. |
+| `b` | `GeometryPart` | `{}` | — | — | — | The second operand. |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct CsgGeometryDesc {
+  doc "Two closed geometries combined by a boolean operation, each placed first: a box with a hole bored through it, a dice, a window cut in a wall. The result is closed when both are (every edge shared by two triangles, wound opposite), every piece keeps its source's normals, uvs and colours (b's turned inside out where it is subtracted). Where a plane side or an edge crossing is decided, the decision is exact (Shewchuk's predicates), so every host makes the same cuts; faces that coincide keep one copy or none, as the operation says."
+  desc true
+  field op CsgOp "The operation."
+  field a GeometryPart "The first operand."
+  field b GeometryPart "The second operand."
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4673</sub>
+
+<a id="type-MergeGeometriesDesc"></a>
+
+### `MergeGeometriesDesc` (desc struct)
+
+Geometries placed and merged into one, as three.js BufferGeometryUtils.mergeGeometries after applying each part's matrix: a prop of parts drawn in one draw, a mirrored half, an array (the same part at several placements). Normals follow each placement; a mirrored part turns its triangles so they still face out. Vertex colours are kept when any part has them.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `parts` | `readonly GeometryPart[]` | `[]` | — | — | — | The parts, in order (at least one). |
+| `uvRepeat` | `Vector2` | `{ x: 1, y: 1 }` | — | — | — | How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping). |
+| `physics` | `boolean` | `true` | — | — | — | Register it as a physics mesh too. |
+| `dynamic` | `boolean` | `false` | — | — | — | Whether og.render.updateGeometry may rewrite it later. |
+
+```ogt
+struct MergeGeometriesDesc {
+  doc "Geometries placed and merged into one, as three.js BufferGeometryUtils.mergeGeometries after applying each part's matrix: a prop of parts drawn in one draw, a mirrored half, an array (the same part at several placements). Normals follow each placement; a mirrored part turns its triangles so they still face out. Vertex colours are kept when any part has them."
+  desc true
+  field parts List.GeometryPart "The parts, in order (at least one)."
+  field uvRepeat Vector2 "How many times a texture repeats across it, along u and v: its UVs scaled by uvRepeat (three.js texture.repeat, here on the geometry; material textures sample with repeat wrapping)." {
+    default 1 1
+  }
+  field physics bool "Register it as a physics mesh too." {
+    default true
+  }
+  field dynamic bool "Whether og.render.updateGeometry may rewrite it later."
+}
+```
+
+<sub>`api.ogt` line 4688</sub>
 
 <a id="type-LineMode"></a>
 
@@ -4866,7 +5885,7 @@ enum LineMode {
 }
 ```
 
-<sub>`api.ogt` line 4368</sub>
+<sub>`api.ogt` line 4778</sub>
 
 <a id="type-LinesDesc"></a>
 
@@ -4932,7 +5951,7 @@ struct LinesDesc {
 }
 ```
 
-<sub>`api.ogt` line 4382</sub>
+<sub>`api.ogt` line 4792</sub>
 
 <a id="type-PointsDesc"></a>
 
@@ -4983,7 +6002,7 @@ struct PointsDesc {
 }
 ```
 
-<sub>`api.ogt` line 4426</sub>
+<sub>`api.ogt` line 4836</sub>
 
 <a id="type-RaycastGeometryDesc"></a>
 
@@ -5016,7 +6035,7 @@ struct RaycastGeometryDesc {
 }
 ```
 
-<sub>`api.ogt` line 4529</sub>
+<sub>`api.ogt` line 4939</sub>
 
 <a id="type-GeometryHit"></a>
 
@@ -5051,7 +6070,7 @@ struct GeometryHit {
 }
 ```
 
-<sub>`api.ogt` line 4543</sub>
+<sub>`api.ogt` line 4953</sub>
 
 <a id="type-RenderTargetFormat"></a>
 
@@ -5074,7 +6093,7 @@ enum RenderTargetFormat {
 }
 ```
 
-<sub>`api.ogt` line 4568</sub>
+<sub>`api.ogt` line 4978</sub>
 
 <a id="type-RenderTarget"></a>
 
@@ -5088,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 4581</sub>
+<sub>`api.ogt` line 4991</sub>
 
 <a id="type-RenderTargetDesc"></a>
 
@@ -5122,7 +6141,7 @@ struct RenderTargetDesc {
 }
 ```
 
-<sub>`api.ogt` line 4590</sub>
+<sub>`api.ogt` line 5000</sub>
 
 <a id="type-RenderTargetInfo"></a>
 
@@ -5149,7 +6168,7 @@ struct RenderTargetInfo {
 }
 ```
 
-<sub>`api.ogt` line 4605</sub>
+<sub>`api.ogt` line 5015</sub>
 
 <a id="type-Post"></a>
 
@@ -5163,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 4717</sub>
+<sub>`api.ogt` line 5127</sub>
 
 <a id="type-PostError"></a>
 
@@ -5184,7 +6203,7 @@ struct PostError {
 }
 ```
 
-<sub>`api.ogt` line 4735</sub>
+<sub>`api.ogt` line 5145</sub>
 
 <a id="type-VolumetricFog"></a>
 
@@ -5207,7 +6226,7 @@ enum VolumetricFog {
 }
 ```
 
-<sub>`api.ogt` line 4749</sub>
+<sub>`api.ogt` line 5159</sub>
 
 <a id="type-BakedScene"></a>
 
@@ -5240,7 +6259,7 @@ struct BakedScene {
 }
 ```
 
-<sub>`api.ogt` line 4797</sub>
+<sub>`api.ogt` line 5207</sub>
 
 ## Column kinds
 
@@ -5251,6 +6270,7 @@ Each is a factory, `Geometry(value?, options?)`, that makes one field of a compo
 | <a id="column-Geometry"></a>`Geometry` | `Geometry` | `Uint32Array` | 2 | A Geometry handle field. |
 | <a id="column-Material"></a>`Material` | `Material` | `Uint32Array` | 2 | A Material handle field. |
 | <a id="column-ToneMapping"></a>`ToneMapping` | `ToneMapping` | `Uint32Array` | 1 | A ToneMapping field: the variant's index. |
+| <a id="column-QualityPreset"></a>`QualityPreset` | `QualityPreset` | `Uint32Array` | 1 | A QualityPreset field: the variant's index. |
 | <a id="column-Texture"></a>`Texture` | `Texture` | `Uint32Array` | 2 | A Texture handle field (0 is none). |
 | <a id="column-Lut"></a>`Lut` | `Lut` | `Uint32Array` | 2 | A Lut handle field (0 is none). |
 | <a id="column-EnvironmentMap"></a>`EnvironmentMap` | `EnvironmentMap` | `Uint32Array` | 2 | An EnvironmentMap handle field (0 is none). |
@@ -5258,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). |
@@ -5277,7 +6300,7 @@ column Geometry {
 }
 ```
 
-<sub>`api.ogt` line 2245</sub>
+<sub>`api.ogt` line 2252</sub>
 
 ```ogt
 column Material {
@@ -5288,7 +6311,7 @@ column Material {
 }
 ```
 
-<sub>`api.ogt` line 2252</sub>
+<sub>`api.ogt` line 2259</sub>
 
 ```ogt
 column ToneMapping {
@@ -5299,7 +6322,18 @@ column ToneMapping {
 }
 ```
 
-<sub>`api.ogt` line 2627</sub>
+<sub>`api.ogt` line 2634</sub>
+
+```ogt
+column QualityPreset {
+  doc "A QualityPreset field: the variant's index."
+  array Uint32Array
+  stride 1
+  value QualityPreset
+}
+```
+
+<sub>`api.ogt` line 2656</sub>
 
 ```ogt
 column Texture {
@@ -5310,7 +6344,7 @@ column Texture {
 }
 ```
 
-<sub>`api.ogt` line 2698</sub>
+<sub>`api.ogt` line 2758</sub>
 
 ```ogt
 column Lut {
@@ -5321,7 +6355,7 @@ column Lut {
 }
 ```
 
-<sub>`api.ogt` line 2705</sub>
+<sub>`api.ogt` line 2765</sub>
 
 ```ogt
 column EnvironmentMap {
@@ -5332,7 +6366,7 @@ column EnvironmentMap {
 }
 ```
 
-<sub>`api.ogt` line 2712</sub>
+<sub>`api.ogt` line 2772</sub>
 
 ```ogt
 column ParticleEmitter {
@@ -5343,7 +6377,7 @@ column ParticleEmitter {
 }
 ```
 
-<sub>`api.ogt` line 2739</sub>
+<sub>`api.ogt` line 2799</sub>
 
 ```ogt
 column AoMethod {
@@ -5354,7 +6388,7 @@ column AoMethod {
 }
 ```
 
-<sub>`api.ogt` line 2753</sub>
+<sub>`api.ogt` line 2813</sub>
 
 ```ogt
 column DofQuality {
@@ -5365,7 +6399,7 @@ column DofQuality {
 }
 ```
 
-<sub>`api.ogt` line 2766</sub>
+<sub>`api.ogt` line 2826</sub>
 
 ```ogt
 column SpriteBlend {
@@ -5376,7 +6410,18 @@ column SpriteBlend {
 }
 ```
 
-<sub>`api.ogt` line 2779</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 {
@@ -5387,7 +6432,7 @@ column StripBlend {
 }
 ```
 
-<sub>`api.ogt` line 2792</sub>
+<sub>`api.ogt` line 2866</sub>
 
 ```ogt
 column Palette {
@@ -5398,7 +6443,18 @@ column Palette {
 }
 ```
 
-<sub>`api.ogt` line 3017</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 {
@@ -5409,7 +6465,7 @@ column DitherPattern {
 }
 ```
 
-<sub>`api.ogt` line 3034</sub>
+<sub>`api.ogt` line 3108</sub>
 
 ```ogt
 column StyliseSpace {
@@ -5420,7 +6476,7 @@ column StyliseSpace {
 }
 ```
 
-<sub>`api.ogt` line 3048</sub>
+<sub>`api.ogt` line 3122</sub>
 
 ```ogt
 column ReflectionProbeMode {
@@ -5431,7 +6487,18 @@ column ReflectionProbeMode {
 }
 ```
 
-<sub>`api.ogt` line 3971</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 {
@@ -5442,7 +6509,7 @@ column LineMode {
 }
 ```
 
-<sub>`api.ogt` line 4375</sub>
+<sub>`api.ogt` line 4785</sub>
 
 ```ogt
 column RenderTargetFormat {
@@ -5453,7 +6520,7 @@ column RenderTargetFormat {
 }
 ```
 
-<sub>`api.ogt` line 4574</sub>
+<sub>`api.ogt` line 4984</sub>
 
 ```ogt
 column RenderTarget {
@@ -5464,7 +6531,7 @@ column RenderTarget {
 }
 ```
 
-<sub>`api.ogt` line 4583</sub>
+<sub>`api.ogt` line 4993</sub>
 
 ```ogt
 column Post {
@@ -5475,7 +6542,7 @@ column Post {
 }
 ```
 
-<sub>`api.ogt` line 4719</sub>
+<sub>`api.ogt` line 5129</sub>
 
 ## Constants
 
@@ -5491,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 3393</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 3937</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 3938</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 3939</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 3963</sub>
+<sub>`api.ogt` line 4041</sub>