@origingame/engine 0.3.0 → 0.4.0

package/types/index.d.ts

@@ -31,12 +31,32 @@ export interface FieldSpec<K extends ColumnKind = ColumnKind> {
   readonly capacity?: number;
 }
 
+/** The column kinds a list holds: one number (`f32`, `f64`, `u32`, `i32`) or a handle. */
+export type ListKind = {
+  [K in ColumnKind]: ColumnKinds[K]["value"] extends number ? K : never;
+}[ColumnKind];
+
+/**
+ * A list field, made by `list(of, capacity)`: at most `list` values of the
+ * element's kind, starting empty. Its value is a frozen array: read it as a
+ * copy, write it whole (`post.custom = [...post.custom, h]`).
+ */
+export interface ListSpec<K extends ListKind = ListKind> {
+  readonly kind: K;
+  readonly default: readonly ColumnKinds[K]["value"][];
+  readonly options: FieldOptions;
+  /** The capacity in elements, 1 to 1024. */
+  readonly list: number;
+}
+
 /** A reflected layout: field names to field specs. */
-export type Fields = { readonly [field: string]: FieldSpec };
+export type Fields = { readonly [field: string]: FieldSpec | ListSpec };
 
-/** The value of a layout: each field as its column's value type. */
+/** The value of a layout: each field as its column's value type, a list as a read-only array of it. */
 export type FieldValues<F extends Fields> = {
-  -readonly [K in keyof F]: ColumnKinds[F[K]["kind"]]["value"];
+  -readonly [K in keyof F]: F[K] extends { readonly list: number }
+    ? readonly ColumnKinds[F[K]["kind"]]["value"][]
+    : ColumnKinds[F[K]["kind"]]["value"];
 };
 
 /** The typed views of a layout: each field as its column's typed array. */
@@ -117,6 +137,8 @@ export interface ColumnKinds {
   Material: { readonly array: Uint32Array; readonly stride: 2; readonly value: Material };
   /** A ToneMapping field: the variant's index. */
   ToneMapping: { readonly array: Uint32Array; readonly stride: 1; readonly value: ToneMapping };
+  /** A QualityPreset field: the variant's index. */
+  QualityPreset: { readonly array: Uint32Array; readonly stride: 1; readonly value: QualityPreset };
   /** A Texture handle field (0 is none). */
   Texture: { readonly array: Uint32Array; readonly stride: 2; readonly value: Texture };
   /** A Lut handle field (0 is none). */
@@ -901,7 +923,7 @@ export declare const color: ColorMath;
 // ── reflect ─────────────────────────────────────────────────────
 // Reflection: components and resources are declared once with their field layout and metadata, and registered by name.
 // The inspector, Tune, the probe, scene text and the wiki read this one schema. Each column factory below makes one field.
-// A field holds one value: there is no array or list column. A few values are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things is an entity each, with its own component, looped over by a query (a ring of skid marks, the laps of a race); a long record (a lap's taped inputs) is text in `str` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.
+// A field holds one value, or a list of at most a fixed number of one number type or handle: `list(u32(), 8)`, `list(Asset(), 4)` (the list factory below). A list is read as a frozen copy (`push` throws) and written whole (`chain.passes = [...chain.passes, h]`); one over its capacity is refused, never truncated. A few vectors are numbered fields (`p0` to `p7`, as og.CameraRail does); a list of things with fields of their own is an entity each, with its own component, looped over by a query (a ring of skid marks, the laps of a race); a long record (a lap's taped inputs) is text in `str` fields of at most 4,096 bytes each, chunked over entities. Keep none of it in module variables: they are not world state, so a snapshot, a replay and a hot reload lose them.
 // A handle (an og.load answer, a texture, a sound, a geometry, a material, an entity) is a 64-bit number: keep it in a field of its own kind (`Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()`, `Entity()`, the factories of the API's handle types), in a component or a resource. A `u32` field refuses one (handles pass 2^32: `4294967298 is not a u32`); an `f64` holds the number but loses its type.
 
 /**
@@ -1055,6 +1077,17 @@ export declare function Color(value?: Color, options?: FieldOptions): FieldSpec<
  */
 export declare function str(capacity: number, value?: string, options?: FieldOptions): FieldSpec<"str">;
 
+/**
+ * A list of at most `capacity` values of one number column (`f32`, `f64`, `u32`, `i32`) or handle column (`Asset`, `Entity`, `Post`, ...), stored inline: a count, then the elements, zeros past the count, so `[]` and `[0]` differ and the list is world state like a number. The capacity is 1 to 1,024 elements; it starts empty and is never tunable.
+ * Reading it answers a frozen array, a copy: `push`, `splice` and index writes throw, so change it by writing a whole array (`v.passes = [...v.passes, h]`, `v.passes = []`). A list over the capacity is refused with the fix named (an error value from world.insert/world.set, a throw from a resource's setter), never truncated. Scene text and looks give it on one line, its elements in order (`passes 3 5`), the key alone for the empty list. Its view is the element's typed array with a stride of (capacity + 1) elements, the count first.
+ *
+ * A list field: stored in the element's typed array, (capacity + 1) of its lanes per entity, the count first.
+ * @param of The element's column factory, called for its kind: `u32()`, `Asset()`, `Post()` (its default and options are not used).
+ * @param capacity The most elements it holds, 1 to 1024.
+ * @param options Label and docs (a list has no range and is not tunable).
+ */
+export declare function list<K extends ListKind>(of: FieldSpec<K>, capacity: number, options?: FieldOptions): ListSpec<K>;
+
 /**
  * Declare a component: plain data stored per entity in engine memory, one column per field.
  * Registration is by name, so a hot reload re-registers the same component and migrates its fields by name.
@@ -4030,7 +4063,33 @@ export type ToneMapping = "aces" | "agx" | "none";
 export declare function ToneMapping(value?: ToneMapping, options?: FieldOptions): FieldSpec<"ToneMapping">;
 
 /**
- * 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.
+ * 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.
+ * - `"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.
+ */
+export type GraphicsQuality = "medium" | "low" | "high";
+
+/**
+ * The preset RenderSettings' quality fields were last written with (RenderSettings.quality).
+ * - `"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").
+ */
+export type QualityPreset = "none" | "low" | "medium" | "high";
+
+/**
+ * A QualityPreset field: the variant's index.
+ *
+ * A `QualityPreset` field: stored in a `Uint32Array` with stride 1.
+ * @param value The field's default; omitted, the column's zero value.
+ * @param options Range, unit, label, docs and the tunable flag.
+ */
+export declare function QualityPreset(value?: QualityPreset, options?: FieldOptions): FieldSpec<"QualityPreset">;
+
+/**
+ * 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.
  *
  * The `RenderSettings` resource (token `og.RenderSettings`).
  */
@@ -4115,7 +4174,7 @@ export interface RenderSettings {
    */
   decalAtlas: Texture;
   /**
-   * 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.
+   * 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
    * @range 0..16
@@ -4128,6 +4187,61 @@ export interface RenderSettings {
    * @default true
    */
   bakedLighting: boolean;
+  /**
+   * 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.
+   */
+  quality: QualityPreset;
+  /**
+   * 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
+   */
+  rectShadows: boolean;
+  /**
+   * 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
+   * @range 0..8
+   */
+  shadowedLights: number;
+  /**
+   * 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
+   * @range 0.125..4
+   */
+  shadowMapScale: number;
+  /**
+   * An og.VolumetricFog is drawn lit, with its light shafts; false draws the same medium as plain distance and height fog.
+   *
+   * @default true
+   */
+  volumetricFog: boolean;
+  /**
+   * Particles with a softDistance fade against the scene behind them; false draws them hard-edged and asks no depth prepass for them.
+   *
+   * @default true
+   */
+  softParticles: boolean;
+  /**
+   * 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
+   */
+  screenSpaceReflections: boolean;
+  /**
+   * PostEffects.ao darkens creases; false draws none. PostEffects keeps its settings either way.
+   *
+   * @default true
+   */
+  ambientOcclusion: boolean;
+  /**
+   * 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
+   * @range 1..4
+   */
+  msaaSamples: number;
 }
 
 /**
@@ -4617,23 +4731,11 @@ export interface PostEffects {
    */
   ssrIntensity: number;
   /**
-   * 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.
+   * 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.
+   *
+   * @capacity 8 elements (List.Post.8): reading answers a frozen copy (push throws); write a whole array, refused over the capacity, never truncated
    */
-  custom1: Post;
-  /** The second custom post pass, over the first's output (0 skips the slot). */
-  custom2: Post;
-  /** The third custom post pass. */
-  custom3: Post;
-  /** The fourth custom post pass. */
-  custom4: Post;
-  /** The fifth custom post pass. */
-  custom5: Post;
-  /** The sixth custom post pass. */
-  custom6: Post;
-  /** The seventh custom post pass. */
-  custom7: Post;
-  /** The eighth and last custom post pass, over every one before it. */
-  custom8: Post;
+  custom: readonly Post[];
 }
 
 /**
@@ -6323,7 +6425,7 @@ export interface RenderCapabilities {
   /** The largest side of a render target (the device's largest 2D texture). */
   readonly maxRenderTargetSize: number;
   /**
-   * 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).
+   * The most custom post passes a frame runs: 8 on every tier, PostEffects.custom's capacity.
    */
   readonly maxCustomPosts: number;
   /**
@@ -6339,9 +6441,17 @@ export interface RenderCapabilities {
    */
   readonly maxLightCookies: number;
   /**
-   * 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.
+   * 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.
    */
   readonly gpuTimestamps: boolean;
+  /**
+   * 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.
+   */
+  readonly spriteAnisotropy: number;
+  /**
+   * 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.
+   */
+  readonly world3d: boolean;
 }
 
 /**
@@ -6436,6 +6546,7 @@ export type Shader = number & { readonly [handleType]: "Shader" };
 
 
 
+
 /**
  * Geometry from attribute arrays, as three.js BufferGeometry with its attributes set: one item per vertex in each array, triangles three indices each (or, with no indices, every three vertices).
  * Missing normals are computed, as three.js computeVertexNormals (each vertex the area-weighted sum of its triangles' normals: shared vertices shade smooth, an unindexed geometry flat); missing tangents are generated when a normal map needs them. An unindexed geometry whose vertex count is not a multiple of three has no triangles: it draws nothing as an og.Mesh and is a vertex set for og.Lines and og.Points.
@@ -6704,152 +6815,667 @@ export interface TorusGeometryDesc {
    * @default 48
    * @range 3..
    */
-  readonly tubularSegments?: number;
+  readonly tubularSegments?: number;
+  /**
+   * How far around the ring goes.
+   *
+   * @default 6.283185307179586
+   * @unit rad (radians)
+   */
+  readonly arc?: number;
+}
+
+/**
+ * A flat ring in the xy plane facing +Z, as three.js RingGeometry(innerRadius, outerRadius, thetaSegments, phiSegments, thetaStart, thetaLength).
+ *
+ * A desc: every field may be omitted and then takes its documented default; `{}` is valid.
+ */
+export interface RingGeometryDesc {
+  /**
+   * The hole's radius.
+   *
+   * @default 0.5
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly innerRadius?: number;
+  /**
+   * The ring's radius.
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly outerRadius?: number;
+  /**
+   * Segments around.
+   *
+   * @default 32
+   * @range 3..
+   */
+  readonly thetaSegments?: number;
+  /**
+   * Rings from the inside out.
+   *
+   * @default 1
+   * @range 1..
+   */
+  readonly phiSegments?: number;
+  /**
+   * Where it starts, from +X towards +Y.
+   *
+   * @default 0
+   * @unit rad (radians)
+   */
+  readonly thetaStart?: number;
+  /**
+   * How far around it goes.
+   *
+   * @default 6.283185307179586
+   * @unit rad (radians)
+   */
+  readonly thetaLength?: number;
+}
+
+/**
+ * A disc (or a sector) in the xy plane facing +Z, as three.js CircleGeometry(radius, segments, thetaStart, thetaLength): a 2D polygon's simplest shape.
+ *
+ * A desc: every field may be omitted and then takes its documented default; `{}` is valid.
+ */
+export interface CircleGeometryDesc {
+  /**
+   * The radius.
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly radius?: number;
+  /**
+   * Segments around.
+   *
+   * @default 32
+   * @range 3..
+   */
+  readonly segments?: number;
+  /**
+   * Where it starts, from +X towards +Y.
+   *
+   * @default 0
+   * @unit rad (radians)
+   */
+  readonly thetaStart?: number;
+  /**
+   * How far around it goes.
+   *
+   * @default 6.283185307179586
+   * @unit rad (radians)
+   */
+  readonly thetaLength?: number;
+}
+
+/**
+ * A tube along a curve, as three.js TubeGeometry(curve, tubularSegments, radius, radialSegments, closed): its rings are evenly spaced along the curve's length (three.js getPointAt), u runs along it, v around. The curve is `path` when set (an og.path, whatever its kind, followed exactly: a scene's or a timeline's path becomes a tube), otherwise new CatmullRomCurve3(points, closed, 'centripetal') through `points`, which may come from anywhere: a rope's points, a spline a tool made.
+ *
+ * A desc: every field may be omitted and then takes its documented default; `{}` is valid.
+ */
+export interface TubeGeometryDesc {
+  /**
+   * The points the curve passes through, in order (at least two), when `path` is 0.
+   *
+   * @default []
+   * @unit m (metres)
+   */
+  readonly points?: readonly Vector3[];
+  /**
+   * A path (og.path.create, or a scene's `path` by og.path.find) the tube follows instead of the points: its own curve, kind and closed flag (`closed` is the path's then). 0 uses the points.
+   *
+   * @default 0
+   */
+  readonly path?: Path;
+  /**
+   * Segments along the tube.
+   *
+   * @default 64
+   * @range 1..
+   */
+  readonly tubularSegments?: number;
+  /**
+   * The tube's radius.
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly radius?: number;
+  /**
+   * Segments around it.
+   *
+   * @default 8
+   * @range 3..
+   */
+  readonly radialSegments?: number;
+  /**
+   * Join the last point back to the first.
+   *
+   * @default false
+   */
+  readonly closed?: boolean;
+}
+
+
+
+
+
+
+
+
+/**
+ * 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.
+ */
+export interface ShapePoints {
+  /** The outline's points, in order. */
+  readonly shape: readonly Vector2[];
+  /** Each hole's points, in order. */
+  readonly holes: readonly (readonly Vector2[])[];
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface ShapeGeometryDesc {
+  /**
+   * 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).
+   *
+   * @default null
+   */
+  readonly shapes?: Path2 | readonly Path2[] | readonly Vector2[] | null;
+  /**
+   * 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
+   * @range 1..
+   */
+  readonly curveSegments?: number;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too (BufferGeometryDesc.physics).
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later (BufferGeometryDesc.dynamic).
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface ExtrudeGeometryDesc {
+  /**
+   * One og.Shape, a list of them, or the outline's points. Without it, three.js's default square of side 1.
+   *
+   * @default null
+   */
+  readonly shapes?: Path2 | readonly Path2[] | readonly Vector2[] | null;
+  /**
+   * How far the shape is pushed along +Z (without extrudePath).
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly depth?: number;
+  /**
+   * Rings along the depth or the path.
+   *
+   * @default 1
+   * @range 1..
+   */
+  readonly steps?: number;
+  /**
+   * Round the edges of both faces.
+   *
+   * @default true
+   */
+  readonly bevelEnabled?: boolean;
+  /**
+   * How far the bevel reaches beyond each face, along z.
+   *
+   * @default 0.2
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly bevelThickness?: number;
+  /**
+   * 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).
+   *
+   * @default null
+   * @unit m (metres)
+   */
+  readonly bevelSize?: number | null;
+  /**
+   * How far the bevel starts out from the outline.
+   *
+   * @default 0
+   * @unit m (metres)
+   */
+  readonly bevelOffset?: number;
+  /**
+   * Rings in each bevel.
+   *
+   * @default 3
+   * @range 1..
+   */
+  readonly bevelSegments?: number;
+  /**
+   * Points per curve when an og.Shape's curves are flattened.
+   *
+   * @default 12
+   * @range 1..
+   */
+  readonly curveSegments?: number;
+  /**
+   * 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.
+   *
+   * @default 0
+   */
+  readonly extrudePath?: Path;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later.
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface LatheGeometryDesc {
+  /**
+   * 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).
+   *
+   * @default []
+   * @unit m (metres)
+   */
+  readonly points?: readonly Vector2[];
+  /**
+   * Segments round the axis.
+   *
+   * @default 12
+   * @range 1..
+   */
+  readonly segments?: number;
+  /**
+   * Where the turn starts, from +Z towards +X.
+   *
+   * @default 0
+   * @unit rad (radians)
+   */
+  readonly phiStart?: number;
+  /**
+   * How far it turns; 2 pi is whole (clamped to it).
+   *
+   * @default 6.283185307179586
+   * @unit rad (radians)
+   */
+  readonly phiLength?: number;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later.
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface PolyhedronGeometryDesc {
+  /**
+   * The corners, x y z each (three.js's flat array).
+   *
+   * @default []
+   */
+  readonly vertices?: readonly number[];
+  /**
+   * The faces, three corner indices each, counter-clockwise seen from outside.
+   *
+   * @default []
+   */
+  readonly indices?: readonly number[];
+  /**
+   * The sphere the vertices are pushed onto.
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly radius?: number;
+  /**
+   * Subdivisions of each face: (detail + 1)² triangles a face.
+   *
+   * @default 0
+   * @range ..64
+   */
+  readonly detail?: number;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later.
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface SolidGeometryDesc {
+  /**
+   * The radius.
+   *
+   * @default 1
+   * @range 0..
+   * @unit m (metres)
+   */
+  readonly radius?: number;
+  /**
+   * Subdivisions of each face.
+   *
+   * @default 0
+   * @range ..64
+   */
+  readonly detail?: number;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later.
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * A value at a fraction of a sweep's path: linear between keys, held before the first and past the last.
+ */
+export interface SweepKey {
+  /**
+   * The fraction of the path's length, 0 to 1.
+   *
+   * @unit ratio (a fraction between 0 and 1)
+   */
+  readonly t: number;
+  /** The value there. */
+  readonly value: number;
+}
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
+ */
+export interface SweepGeometryDesc {
+  /**
+   * 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.
+   *
+   * @default null
+   */
+  readonly section?: Path2 | readonly Vector2[] | null;
+  /**
+   * The path (og.path.create or og.path.find).
+   *
+   * @default 0
+   */
+  readonly path?: Path;
+  /**
+   * Rings along the path, less one.
+   *
+   * @default 64
+   * @range 1..
+   */
+  readonly steps?: number;
+  /**
+   * The section's scale over the path (none: 1 throughout). A horn: [{ t: 0, value: 1 }, { t: 1, value: 0.05 }].
+   *
+   * @default []
+   */
+  readonly scale?: readonly SweepKey[];
+  /**
+   * The section's turn round the path over its length, in radians (none: 0).
+   *
+   * @default []
+   */
+  readonly twist?: readonly SweepKey[];
+  /**
+   * Close the ends of an open path.
+   *
+   * @default true
+   */
+  readonly caps?: boolean;
+  /**
+   * Points per curve when an og.Shape section is flattened.
+   *
+   * @default 12
+   * @range 1..
+   */
+  readonly curveSegments?: number;
+  /**
+   * 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 { x: 1, y: 1 }
+   */
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
   /**
-   * How far around the ring goes.
+   * Whether og.render.updateGeometry may rewrite it later.
    *
-   * @default 6.283185307179586
-   * @unit rad (radians)
+   * @default false
    */
-  readonly arc?: number;
+  readonly dynamic?: boolean;
 }
 
 /**
- * A flat ring in the xy plane facing +Z, as three.js RingGeometry(innerRadius, outerRadius, thetaSegments, phiSegments, thetaStart, thetaLength).
+ * The world axis a part is mirrored along, after its placement.
+ * - `"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.
+ */
+export type MirrorAxis = "none" | "x" | "y" | "z";
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
  */
-export interface RingGeometryDesc {
+export interface GeometryPart {
   /**
-   * The hole's radius.
+   * Any geometry: made, a primitive or a loaded glTF's.
    *
-   * @default 0.5
-   * @range 0..
-   * @unit m (metres)
+   * @default 0
    */
-  readonly innerRadius?: number;
+  readonly geometry?: Geometry;
   /**
-   * The ring's radius.
+   * Where it goes.
    *
-   * @default 1
-   * @range 0..
+   * @default { x: 0, y: 0, z: 0 }
    * @unit m (metres)
    */
-  readonly outerRadius?: number;
-  /**
-   * Segments around.
-   *
-   * @default 32
-   * @range 3..
-   */
-  readonly thetaSegments?: number;
+  readonly position?: Vector3;
   /**
-   * Rings from the inside out.
+   * How it turns.
    *
-   * @default 1
-   * @range 1..
+   * @default { x: 0, y: 0, z: 0, w: 1 }
    */
-  readonly phiSegments?: number;
+  readonly quaternion?: Quaternion;
   /**
-   * Where it starts, from +X towards +Y.
+   * Its scale (a negative component mirrors it as `mirror` does).
    *
-   * @default 0
-   * @unit rad (radians)
+   * @default { x: 1, y: 1, z: 1 }
    */
-  readonly thetaStart?: number;
+  readonly scale?: Vector3;
   /**
-   * How far around it goes.
+   * Mirror it along a world axis after placing it: a symmetric prop is one half twice, the second mirrored.
    *
-   * @default 6.283185307179586
-   * @unit rad (radians)
+   * @default "none"
    */
-  readonly thetaLength?: number;
+  readonly mirror?: MirrorAxis;
 }
 
 /**
- * A disc (or a sector) in the xy plane facing +Z, as three.js CircleGeometry(radius, segments, thetaStart, thetaLength): a 2D polygon's simplest shape.
+ * A boolean operation on two solids.
+ * - `"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.
+ */
+export type CsgOp = "union" | "subtract" | "intersect";
+
+/**
+ * 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 then takes its documented default; `{}` is valid.
  */
-export interface CircleGeometryDesc {
+export interface CsgGeometryDesc {
   /**
-   * The radius.
+   * The operation.
    *
-   * @default 1
-   * @range 0..
-   * @unit m (metres)
+   * @default "union"
    */
-  readonly radius?: number;
+  readonly op?: CsgOp;
   /**
-   * Segments around.
+   * The first operand.
    *
-   * @default 32
-   * @range 3..
+   * @default {}
    */
-  readonly segments?: number;
+  readonly a?: GeometryPart;
   /**
-   * Where it starts, from +X towards +Y.
+   * The second operand.
    *
-   * @default 0
-   * @unit rad (radians)
+   * @default {}
    */
-  readonly thetaStart?: number;
+  readonly b?: GeometryPart;
   /**
-   * How far around it goes.
+   * 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 6.283185307179586
-   * @unit rad (radians)
+   * @default { x: 1, y: 1 }
    */
-  readonly thetaLength?: number;
+  readonly uvRepeat?: Vector2;
+  /**
+   * Register it as a physics mesh too.
+   *
+   * @default true
+   */
+  readonly physics?: boolean;
+  /**
+   * Whether og.render.updateGeometry may rewrite it later.
+   *
+   * @default false
+   */
+  readonly dynamic?: boolean;
 }
 
 /**
- * A tube along a curve, as three.js TubeGeometry(curve, tubularSegments, radius, radialSegments, closed): its rings are evenly spaced along the curve's length (three.js getPointAt), u runs along it, v around. The curve is `path` when set (an og.path, whatever its kind, followed exactly: a scene's or a timeline's path becomes a tube), otherwise new CatmullRomCurve3(points, closed, 'centripetal') through `points`, which may come from anywhere: a rope's points, a spline a tool made.
+ * 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 then takes its documented default; `{}` is valid.
  */
-export interface TubeGeometryDesc {
+export interface MergeGeometriesDesc {
   /**
-   * The points the curve passes through, in order (at least two), when `path` is 0.
+   * The parts, in order (at least one).
    *
    * @default []
-   * @unit m (metres)
-   */
-  readonly points?: readonly Vector3[];
-  /**
-   * A path (og.path.create, or a scene's `path` by og.path.find) the tube follows instead of the points: its own curve, kind and closed flag (`closed` is the path's then). 0 uses the points.
-   *
-   * @default 0
    */
-  readonly path?: Path;
-  /**
-   * Segments along the tube.
-   *
-   * @default 64
-   * @range 1..
-   */
-  readonly tubularSegments?: number;
+  readonly parts?: readonly GeometryPart[];
   /**
-   * The tube's radius.
+   * 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
-   * @range 0..
-   * @unit m (metres)
+   * @default { x: 1, y: 1 }
    */
-  readonly radius?: number;
+  readonly uvRepeat?: Vector2;
   /**
-   * Segments around it.
+   * Register it as a physics mesh too.
    *
-   * @default 8
-   * @range 3..
+   * @default true
    */
-  readonly radialSegments?: number;
+  readonly physics?: boolean;
   /**
-   * Join the last point back to the first.
+   * Whether og.render.updateGeometry may rewrite it later.
    *
    * @default false
    */
-  readonly closed?: boolean;
+  readonly dynamic?: boolean;
 }
 
 
@@ -6859,6 +7485,10 @@ export interface TubeGeometryDesc {
 
 
 
+
+
+
+
 /**
  * How a line set's points join, as three.js's three line objects.
  * - `"strip"`: One polyline through every point, as three.js Line.
@@ -7578,6 +8208,165 @@ export interface BakedScene {
 }
 
 
+// ── shapes ──────────────────────────────────────────────────────
+// Two-dimensional outlines in three.js's words: og.Shape and og.Path2 are three.js's Shape and Path, built by the same calls (moveTo, lineTo, quadraticCurveTo, bezierCurveTo, splineThru, arc, absarc, ellipse, absellipse, closePath) and flattened to points by getPoints, so a three.js outline is a paste. og.render.shapeGeometry, extrudeGeometry and sweepGeometry take them; only their points cross to the engine.
+// They are TypeScript values, not world state: make them in start or a command and let the geometry made from them be what the world keeps. Points come from basic arithmetic (no Math.sin), so they are the same on every host.
+// A prop of these parts belongs in an asset: an `.ogt` of `type model` names each part's geometry by its og.render call (`extrudeGeometry { shape { absarc 0 0 1 0 6.283185307179586 false } depth 0.2 }`), its shapes as og.Shape's calls one a line with `hole { }` blocks, places parts as mergeGeometries does (`position`, `quaternion`, `scale`, `mirror`, or several `at { }` blocks: one mesh drawn instanced), gives each a `material` and hangs it from a named `pivot` (a node). og cook builds it into the model blob a glTF cooks to (levels of detail, raycast BVH, nodes), refuses it past project.ogt's triangle and vertex budgets, and og dev re-cooks it on an edit; og.load.gltf and a scene's `model` line take it as any model. The og-game skill §18 has a whole example.
+
+/** A shape's holes, as three.js Shape.holes: an array; push a path to add a hole. */
+export interface PathList {
+  /** How many holes. */
+  readonly length: number;
+  /**
+   * Add a hole (Array.push).
+   *
+   * @param path The hole's outline, either winding.
+   */
+  push(path: Path2): number;
+}
+
+/**
+ * An outline of curves, as three.js Path: each call adds a curve from the current point (moveTo only moves it). Every method but getPoints returns the path, so calls chain.
+ */
+export interface Path2 {
+  /**
+   * Move the current point without drawing, as three.js Path.moveTo.
+   *
+   * @param x x.
+   * @param y y.
+   */
+  moveTo(x: number, y: number): this;
+  /**
+   * A straight line to (x, y), as three.js Path.lineTo.
+   *
+   * @param x x.
+   * @param y y.
+   */
+  lineTo(x: number, y: number): this;
+  /**
+   * A quadratic Bézier curve through one control point to (x, y), as three.js Path.quadraticCurveTo.
+   *
+   * @param cpX The control point's x.
+   * @param cpY The control point's y.
+   * @param x The end's x.
+   * @param y The end's y.
+   */
+  quadraticCurveTo(cpX: number, cpY: number, x: number, y: number): this;
+  /**
+   * A cubic Bézier curve through two control points to (x, y), as three.js Path.bezierCurveTo.
+   *
+   * @param cp1X The first control point's x.
+   * @param cp1Y The first control point's y.
+   * @param cp2X The second control point's x.
+   * @param cp2Y The second control point's y.
+   * @param x The end's x.
+   * @param y The end's y.
+   */
+  bezierCurveTo(cp1X: number, cp1Y: number, cp2X: number, cp2Y: number, x: number, y: number): this;
+  /**
+   * A Catmull-Rom spline from the current point through the points, as three.js Path.splineThru (a SplineCurve).
+   *
+   * @param points The points it passes through, in order.
+   */
+  splineThru(points: readonly Vector2[]): this;
+  /**
+   * A circular arc centred at (x, y) from the current point, as three.js Path.arc.
+   *
+   * @param x The centre's x, from the current point.
+   * @param y The centre's y, from the current point.
+   * @param radius The radius.
+   * @param startAngle Where it starts, from +x towards +y.
+   * @param endAngle Where it ends.
+   * @param clockwise Go clockwise. Default `false`.
+   */
+  arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, clockwise?: boolean): this;
+  /**
+   * A circular arc centred at (x, y), as three.js Path.absarc: a line joins it to the current point when they differ.
+   *
+   * @param x The centre's x.
+   * @param y The centre's y.
+   * @param radius The radius.
+   * @param startAngle Where it starts, from +x towards +y.
+   * @param endAngle Where it ends.
+   * @param clockwise Go clockwise. Default `false`.
+   */
+  absarc(x: number, y: number, radius: number, startAngle: number, endAngle: number, clockwise?: boolean): this;
+  /**
+   * An elliptic arc centred at (x, y) from the current point, as three.js Path.ellipse.
+   *
+   * @param x The centre's x, from the current point.
+   * @param y The centre's y, from the current point.
+   * @param xRadius The radius along x.
+   * @param yRadius The radius along y.
+   * @param startAngle Where it starts.
+   * @param endAngle Where it ends.
+   * @param clockwise Go clockwise. Default `false`.
+   * @param rotation The ellipse's turn round its centre. Default `0`.
+   */
+  ellipse(x: number, y: number, xRadius: number, yRadius: number, startAngle: number, endAngle: number, clockwise?: boolean, rotation?: number): this;
+  /**
+   * An elliptic arc centred at (x, y), as three.js Path.absellipse.
+   *
+   * @param x The centre's x.
+   * @param y The centre's y.
+   * @param xRadius The radius along x.
+   * @param yRadius The radius along y.
+   * @param startAngle Where it starts.
+   * @param endAngle Where it ends.
+   * @param clockwise Go clockwise. Default `false`.
+   * @param rotation The ellipse's turn round its centre. Default `0`.
+   */
+  absellipse(x: number, y: number, xRadius: number, yRadius: number, startAngle: number, endAngle: number, clockwise?: boolean, rotation?: number): this;
+  /**
+   * Start at the first point and draw lines through the rest, as three.js Path.setFromPoints.
+   *
+   * @param points The points.
+   */
+  setFromPoints(points: readonly Vector2[]): this;
+  /**
+   * A line back to the first point when the outline does not end there, as three.js CurvePath.closePath.
+   */
+  closePath(): this;
+  /**
+   * The outline as points, as three.js CurvePath.getPoints: each curve divided into `divisions` (an ellipse twice as many, a spline as many per point, a line one), repeated points dropped.
+   *
+   * @param divisions Divisions per curve. Default `12`.
+   */
+  getPoints(divisions?: number): readonly Vector2[];
+}
+
+/** An outline with holes, as three.js Shape. */
+export interface Shape extends Path2 {
+  /** The holes: `shape.holes.push(hole)`. */
+  readonly holes: PathList;
+  /**
+   * The outline's and the holes' points, as three.js Shape.extractPoints.
+   *
+   * @param divisions Divisions per curve. Default `12`.
+   */
+  extractPoints(divisions?: number): ShapePoints;
+}
+
+/** og.Path2: `new og.Path2(points?)`. */
+export interface Path2Class {
+  /**
+   * A path, through the points when given (setFromPoints).
+   *
+   * @param points Points to start from.
+   */
+  new(points?: readonly Vector2[] | null): Path2;
+}
+
+/** og.Shape: `new og.Shape(points?)`. */
+export interface ShapeClass {
+  /**
+   * A shape, through the points when given (setFromPoints).
+   *
+   * @param points Points to start from.
+   */
+  new(points?: readonly Vector2[] | null): Shape;
+}
+
 // ── load ────────────────────────────────────────────────────────
 // Asset loading from cooked output: `og cook` turns assets/ into cooked/ (.ogb blobs and the manifest cooked/.cook.ogt), and the runtime reads only cooked/.
 // Paths are asset ids: the path under assets/ (`models/ship.glb`, `scenes/main.ogt`); an `assets/` prefix is accepted. Every blob is checked against the manifest's type, schema version and cook stamp.
@@ -7818,7 +8607,7 @@ export interface Model {
    */
   visible: boolean;
   /**
-   * This instance's level of detail bias, multiplied with RenderSettings.lodBias: the cook simplifies every mesh into levels (a model's import settings, `model { lods 1 0.5 0.25 }` by default, the triangle fraction of each level; a glTF with MSFT_lod keeps its own levels), and the renderer draws the level its projected size calls for, with hysteresis so it does not flicker at the boundary. Above 1 keeps detail farther (a hero), below 1 drops it sooner (a crowd); 0 always draws the full mesh. dump_entity shows the level drawn.
+   * This instance's level of detail bias, multiplied with RenderSettings.lodBias: the cook simplifies every mesh into levels (a model's import settings, `model { lods 1 0.5 0.25 }` by default, the triangle fraction of each level; a glTF with MSFT_lod keeps its own levels) and measures each level's error against the full mesh, and the renderer draws the coarsest level whose error covers less than a pixel at the model's distance, with hysteresis so it does not flicker at the boundary. Above 1 keeps detail farther (a hero), below 1 drops it sooner (a crowd); 0 always draws the full mesh. dump_entity shows the level drawn.
    *
    * @default 1
    * @range 0..16
@@ -11734,6 +12523,12 @@ export interface Skeleton2D {
    * The sprite layer it draws in, sorted with the sprites there (after them when they share the layer).
    */
   layer: number;
+  /**
+   * The skin it wears: an index into Rig2DInfo.skins (0 is the rig's default; `rig.skins.indexOf("armor")` finds one by name). A skin shows its own attachment wherever the setup pose or a clip shows the default's; a slot the skin leaves alone shows the default's. Change it any tick: the pose is drawn from it.
+   *
+   * @range 0..
+   */
+  skin: number;
   /**
    * Written: a clip that does not loop reached its end (or its start, played backwards).
    *
@@ -11743,7 +12538,7 @@ export interface Skeleton2D {
 }
 
 /**
- * A 2D skeleton's clip passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
+ * A 2D skeleton's clip, or the clip a child armature in one of its slots plays, passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
  *
  * The payload of the `Skeleton2DEvent` event (token `og.Skeleton2DEvent`).
  */
@@ -11760,6 +12555,10 @@ export interface Skeleton2DEvent {
    * @unit s (seconds of simulation time)
    */
   readonly time: number;
+  /**
+   * Empty for the skeleton's own clip; for an event of a child armature shown in one of its slots, that armature's name (`clip` and `time` are then the child's clip and its time): a flame's crackle apart from the keeper's footsteps (at most 63 bytes).
+   */
+  readonly armature: string;
 }
 
 /**
@@ -11847,6 +12646,10 @@ export interface Rig2DInfo {
   readonly slots: readonly string[];
   /** The IK constraints' names: an index here is IkTarget2D.constraint. */
   readonly constraints: readonly string[];
+  /**
+   * Its skins' names, `default` (the rig's own attachments) first: an index here is Skeleton2D.skin.
+   */
+  readonly skins: readonly string[];
   /** Its clips, in file order. */
   readonly clips: readonly Rig2DClipInfo[];
 }
@@ -16908,14 +17711,6 @@ export interface ScreenTransitionResult {
 
 
 
-/**
- * A graphics quality preset.
- * - `"medium"`: Medium.
- * - `"low"`: Low: the fewest effects.
- * - `"high"`: High: every effect.
- */
-export type GraphicsQuality = "medium" | "low" | "high";
-
 /**
  * A template's action, by its id (a menu item, `buy:<item>`, `share`).
  *
@@ -17219,6 +18014,12 @@ export interface SettingsDesc {
    * @default null
    */
   readonly onSave?: SettingsChanged | null;
+  /**
+   * The world the graphics preset is drawn in: when the player picks another preset the screen calls og.render.applyQuality(world, preset) before onChange. Null leaves applying it to the game. Inside a system, the system declares RenderSettings among its writes.
+   *
+   * @default null
+   */
+  readonly world?: World | null;
   /**
    * The dialog's title. Every word of the screen is a field with its English default: a localised game passes its string table's (og.i18n.t).
    *
@@ -20012,7 +20813,7 @@ export interface EngineProbe extends RuntimeProbe {
 
 // ── terrain ─────────────────────────────────────────────────────
 // Terrain (phase 2): a height field over a rectangle, cooked by `og cook` from a `type terrain` .ogt (a 16-bit grey PNG or an EXR heightmap, an optional control map, up to four layered materials with slope and altitude rules, their maps separate textures or layers of two texture arrays: `layers` and `layerNormals` with each layer's `albedoLayer` and `normalLayer`, two sampled textures instead of up to eight) into tiles; drawn as a geometry clipmap around the camera (nested levels by distance, no cracks) that casts and receives shadows under the fog; collided with as a height field; baked into navmeshes by a navmesh file's `terrain` entry.
-// Load it with og.terrain.load, then place it: an og.Terrain on an entity draws it placed by the entity's world transform (centred on its position, turned and scaled with it), and an og.Collider of shape SHAPE_HEIGHTFIELD naming the TerrainInfo's geometry makes it solid. og.TerrainScatter grows grass, flowers or stones over a layer near the camera. og.terrain.sample answers the surface's height and normal anywhere (pass it the entity's position, quaternion and scale); og.terrain.edit raises, lowers, flattens, smooths or paints it at runtime, and og.terrain.setLayer retunes a layer. Edits are world state: a snapshot keeps them, the world hash covers them, and a restore brings the ground back as it was (rebuilt from the cook with the restored edits replayed, for the renderer, physics and sample alike).
+// Load it with og.terrain.load, then place it: an og.Terrain on an entity draws it placed by the entity's world transform (centred on its position, turned and scaled with it), and an og.Collider of shape SHAPE_HEIGHTFIELD naming the TerrainInfo's geometry makes it solid. og.TerrainScatter grows grass, flowers or stones over a layer near the camera. og.terrain.sample answers the surface's height and normal anywhere (pass it the entity's position, quaternion and scale); og.terrain.edit raises, lowers, flattens, smooths or paints it at runtime, and og.terrain.setLayer retunes a layer. Terrain is 3D: the 2D profile's publish and lanes modules leave it out (RenderCapabilities.world3d is false), where every call here answers a refusal naming that field. Edits are world state: a snapshot keeps them, the world hash covers them, and a restore brings the ground back as it was (rebuilt from the cook with the restored edits replayed, for the renderer, physics and sample alike).
 // Its tiles stream (phase 3): the cook stores the field as a pyramid of tiles, each compressed on its own, and every frame the renderer keeps on the GPU only the tiles the camera's clipmap wants, within each terrain's tile budget (16 MiB by default), decoded off the frame (a worker thread natively, the browser's DecompressionStream on the Web) a few at a time, the most needed first; until a tile arrives its area draws from the coarser level that holds it, then fades in. Nothing a tick reads depends on which tiles are resident (collision and og.terrain.sample read the whole field), so a run's world hash is the same streamed or not. The probe's `terrain_stream:resident` decodes every wanted tile before each frame instead (`terrain_stream:stream[:<MiB>]` streams again, within that budget), and `dump_stream`'s `terrain` gives the tiles resident, waiting, decoding and cached.
 
 /**
@@ -20183,6 +20984,12 @@ export interface TerrainInfo {
   readonly collision: boolean;
   /** Its terrain file's `castShadows`. */
   readonly castShadows: boolean;
+  /**
+   * A generated terrain's sea level (`generate { sea <m> }`) above its entity: place an og.Water there, the terrain's size; null without a sea.
+   *
+   * @unit m (metres)
+   */
+  readonly seaLevel: number | null;
 }
 
 /**
@@ -21413,9 +22220,9 @@ export declare namespace og {
   /** A cone of light along the entity's local -Z, as three.js SpotLight. */
   const SpotLight: ComponentType<{ readonly color: FieldSpec<"Color">; readonly intensity: FieldSpec<"f32">; readonly distance: FieldSpec<"f32">; readonly angle: FieldSpec<"f32">; readonly penumbra: FieldSpec<"f32">; readonly castShadow: FieldSpec<"bool">; readonly cookie: FieldSpec<"Texture"> }, SpotLight>;
   /**
-   * 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.
    */
-  const RenderSettings: ResourceType<{ readonly environmentIntensity: FieldSpec<"f32">; readonly sky: FieldSpec<"bool">; readonly bloom: FieldSpec<"bool">; readonly bloomThreshold: FieldSpec<"f32">; readonly bloomKnee: FieldSpec<"f32">; readonly bloomIntensity: FieldSpec<"f32">; readonly autoExposure: FieldSpec<"bool">; readonly adaptSpeedUp: FieldSpec<"f32">; readonly adaptSpeedDown: FieldSpec<"f32">; readonly toneMapped: FieldSpec<"bool">; readonly toneMapping: FieldSpec<"ToneMapping">; readonly exposure: FieldSpec<"f32">; readonly decalAtlas: FieldSpec<"Texture">; readonly lodBias: FieldSpec<"f32">; readonly bakedLighting: FieldSpec<"bool"> }, RenderSettings>;
+  const RenderSettings: ResourceType<{ readonly environmentIntensity: FieldSpec<"f32">; readonly sky: FieldSpec<"bool">; readonly bloom: FieldSpec<"bool">; readonly bloomThreshold: FieldSpec<"f32">; readonly bloomKnee: FieldSpec<"f32">; readonly bloomIntensity: FieldSpec<"f32">; readonly autoExposure: FieldSpec<"bool">; readonly adaptSpeedUp: FieldSpec<"f32">; readonly adaptSpeedDown: FieldSpec<"f32">; readonly toneMapped: FieldSpec<"bool">; readonly toneMapping: FieldSpec<"ToneMapping">; readonly exposure: FieldSpec<"f32">; readonly decalAtlas: FieldSpec<"Texture">; readonly lodBias: FieldSpec<"f32">; readonly bakedLighting: FieldSpec<"bool">; readonly quality: FieldSpec<"QualityPreset">; readonly rectShadows: FieldSpec<"bool">; readonly shadowedLights: FieldSpec<"u32">; readonly shadowMapScale: FieldSpec<"f32">; readonly volumetricFog: FieldSpec<"bool">; readonly softParticles: FieldSpec<"bool">; readonly screenSpaceReflections: FieldSpec<"bool">; readonly ambientOcclusion: FieldSpec<"bool">; readonly msaaSamples: FieldSpec<"u32"> }, RenderSettings>;
   /**
    * Image-based light from a cooked HDR environment map instead of the sky, as three.js scene.environment, and the map behind the scene, as scene.background = the environment. Load the map with og.load.environment: the cook has already prefiltered it (GGX levels for reflections from mirror to rough, harmonics for the diffuse light), so setting it costs a few copy passes on any tier, WebGL2 included. Without a map the sky lights the scene as before (og.Sky, a DayNight, or the built-in one). Read after each tick; it never feeds back into the simulation.
    */
@@ -21424,7 +22231,7 @@ export declare namespace og {
    * 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.
    * Screen-space ambient occlusion, outlines, depth of field, motion blur and god rays run a depth-normal prepass, turned on with them. Grading, vignette, aberration, grain and the flash apply to the display colour after tone mapping; the UI and screen-space sprites (the overlay) come after all of it.
    */
-  const PostEffects: ResourceType<{ readonly ao: FieldSpec<"bool">; readonly aoRadius: FieldSpec<"f32">; readonly aoIntensity: FieldSpec<"f32">; readonly aoMethod: FieldSpec<"AoMethod">; readonly outline: FieldSpec<"bool">; readonly outlineColor: FieldSpec<"Color">; readonly outlineWidth: FieldSpec<"f32">; readonly outlineDepthThreshold: FieldSpec<"f32">; readonly outlineNormalThreshold: FieldSpec<"f32">; readonly depthOfField: FieldSpec<"bool">; readonly dofFocusDistance: FieldSpec<"f32">; readonly dofFocusRange: FieldSpec<"f32">; readonly dofMaxBlur: FieldSpec<"f32">; readonly dofFalloff: FieldSpec<"f32">; readonly dofQuality: FieldSpec<"DofQuality">; readonly motionBlur: FieldSpec<"bool">; readonly motionBlurShutter: FieldSpec<"f32">; readonly motionBlurSamples: FieldSpec<"u32">; readonly motionBlurMaxPixels: FieldSpec<"f32">; readonly godRays: FieldSpec<"bool">; readonly godRaysIntensity: FieldSpec<"f32">; readonly godRaysDecay: FieldSpec<"f32">; readonly godRaysDensity: FieldSpec<"f32">; readonly godRaysTint: FieldSpec<"Color">; readonly godRaysSamples: FieldSpec<"u32">; readonly godRaysThreshold: FieldSpec<"f32">; readonly glow: FieldSpec<"bool">; readonly glowIntensity: FieldSpec<"f32">; readonly lut: FieldSpec<"Lut">; readonly lutIntensity: FieldSpec<"f32">; readonly vignette: FieldSpec<"bool">; readonly vignetteIntensity: FieldSpec<"f32">; readonly vignetteRadius: FieldSpec<"f32">; readonly vignetteSmoothness: FieldSpec<"f32">; readonly vignetteColor: FieldSpec<"Color">; readonly chromaticAberration: FieldSpec<"f32">; readonly filmGrain: FieldSpec<"f32">; readonly filmGrainSize: FieldSpec<"f32">; readonly flash: FieldSpec<"f32">; readonly flashColor: FieldSpec<"Color">; readonly shakeTrauma: FieldSpec<"f32">; readonly shakeMaxOffset: FieldSpec<"f32">; readonly shakeMaxRoll: FieldSpec<"f32">; readonly shakeFrequency: FieldSpec<"f32">; readonly shakeSeed: FieldSpec<"u32">; readonly ssr: FieldSpec<"bool">; readonly ssrMaxDistance: FieldSpec<"f32">; readonly ssrThickness: FieldSpec<"f32">; readonly ssrSteps: FieldSpec<"u32">; readonly ssrFade: FieldSpec<"f32">; readonly ssrIntensity: FieldSpec<"f32">; readonly custom1: FieldSpec<"Post">; readonly custom2: FieldSpec<"Post">; readonly custom3: FieldSpec<"Post">; readonly custom4: FieldSpec<"Post">; readonly custom5: FieldSpec<"Post">; readonly custom6: FieldSpec<"Post">; readonly custom7: FieldSpec<"Post">; readonly custom8: FieldSpec<"Post"> }, PostEffects>;
+  const PostEffects: ResourceType<{ readonly ao: FieldSpec<"bool">; readonly aoRadius: FieldSpec<"f32">; readonly aoIntensity: FieldSpec<"f32">; readonly aoMethod: FieldSpec<"AoMethod">; readonly outline: FieldSpec<"bool">; readonly outlineColor: FieldSpec<"Color">; readonly outlineWidth: FieldSpec<"f32">; readonly outlineDepthThreshold: FieldSpec<"f32">; readonly outlineNormalThreshold: FieldSpec<"f32">; readonly depthOfField: FieldSpec<"bool">; readonly dofFocusDistance: FieldSpec<"f32">; readonly dofFocusRange: FieldSpec<"f32">; readonly dofMaxBlur: FieldSpec<"f32">; readonly dofFalloff: FieldSpec<"f32">; readonly dofQuality: FieldSpec<"DofQuality">; readonly motionBlur: FieldSpec<"bool">; readonly motionBlurShutter: FieldSpec<"f32">; readonly motionBlurSamples: FieldSpec<"u32">; readonly motionBlurMaxPixels: FieldSpec<"f32">; readonly godRays: FieldSpec<"bool">; readonly godRaysIntensity: FieldSpec<"f32">; readonly godRaysDecay: FieldSpec<"f32">; readonly godRaysDensity: FieldSpec<"f32">; readonly godRaysTint: FieldSpec<"Color">; readonly godRaysSamples: FieldSpec<"u32">; readonly godRaysThreshold: FieldSpec<"f32">; readonly glow: FieldSpec<"bool">; readonly glowIntensity: FieldSpec<"f32">; readonly lut: FieldSpec<"Lut">; readonly lutIntensity: FieldSpec<"f32">; readonly vignette: FieldSpec<"bool">; readonly vignetteIntensity: FieldSpec<"f32">; readonly vignetteRadius: FieldSpec<"f32">; readonly vignetteSmoothness: FieldSpec<"f32">; readonly vignetteColor: FieldSpec<"Color">; readonly chromaticAberration: FieldSpec<"f32">; readonly filmGrain: FieldSpec<"f32">; readonly filmGrainSize: FieldSpec<"f32">; readonly flash: FieldSpec<"f32">; readonly flashColor: FieldSpec<"Color">; readonly shakeTrauma: FieldSpec<"f32">; readonly shakeMaxOffset: FieldSpec<"f32">; readonly shakeMaxRoll: FieldSpec<"f32">; readonly shakeFrequency: FieldSpec<"f32">; readonly shakeSeed: FieldSpec<"u32">; readonly ssr: FieldSpec<"bool">; readonly ssrMaxDistance: FieldSpec<"f32">; readonly ssrThickness: FieldSpec<"f32">; readonly ssrSteps: FieldSpec<"u32">; readonly ssrFade: FieldSpec<"f32">; readonly ssrIntensity: FieldSpec<"f32">; readonly custom: ListSpec<"Post"> }, PostEffects>;
   /**
    * Stylisation primitives that move the frame away from the photographic: a low-resolution pixel grid scaled up by whole numbers, fewer tones or a fixed palette through an ordered or blue-noise dither, halftone dots, cross-hatching, painterly smoothing over a canvas, ink lines on tonal edges, flat colour bands by depth, and the vertex snapping, affine textures and coarse depth of early 3D hardware. They compose: a look (og.load.look) sets this with PostEffects and RenderSettings, and the game's art direction is in that data, not in the engine. Every primitive is off at its zero value (0, false, none) and then costs nothing: no pass is recorded and no pipeline is built. RenderCapabilities.stylise names the primitives this renderer draws; a field it does not name is carried and read back but not drawn. Read after each tick; it never feeds back into the simulation.
    * Order in the frame: depth bands colour the lit scene with the fog, before tone mapping; after tone mapping and PostEffects' grading come paint, hatching, halftone and ink, then posterize and palette quantise through the dither, all at the logical resolution, and the pixel grid is scaled up last. The UI and screen-space sprites are drawn over the scaled frame at the output's resolution, unstylised.
@@ -21611,6 +22418,25 @@ export declare namespace og {
      * @returns Refused for a look not loaded in this world, one in a streaming group that is not resident (the reason names it), or a resource the system did not declare.
      */
     function applyLook(world: World, look: Look): Result<void>;
+    /**
+     * 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.
+     *
+     * @param world The world whose RenderSettings change.
+     * @param preset The preset.
+     * @returns Refused for a world that is not alive, or inside a system that did not declare RenderSettings among its writes.
+     */
+    function applyQuality(world: World, preset: GraphicsQuality): Result<void>;
     /**
      * The look last applied (by og.render.applyLook or GameDesc.look), as og.load.lookInfo describes it; null before any.
      *
@@ -21706,6 +22532,90 @@ export declare namespace og {
      * @returns Refused for fewer than two points or a point that is not finite (without a path), or a path that is not alive.
      */
     function tubeGeometry(world: World, desc?: TubeGeometryDesc): Result<Geometry>;
+    /**
+     * 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 The world whose renderer owns the geometry.
+     * @param desc The shapes and their tessellation.
+     * @returns Refused for a shape whose points are not finite or that triangulates to nothing.
+     */
+    function shapeGeometry(world: World, desc?: ShapeGeometryDesc): Result<Geometry>;
+    /**
+     * 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 The world whose renderer owns the geometry.
+     * @param desc The shapes, depth, bevel and path.
+     * @returns Refused for a shape whose points are not finite or that triangulates to nothing, or an extrudePath that is not alive.
+     */
+    function extrudeGeometry(world: World, desc?: ExtrudeGeometryDesc): Result<Geometry>;
+    /**
+     * Make a solid of revolution for og.Mesh: a profile turned round +Y.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc The profile and the turn.
+     * @returns Refused for fewer than two points or one that is not finite.
+     */
+    function latheGeometry(world: World, desc?: LatheGeometryDesc): Result<Geometry>;
+    /**
+     * Make a polyhedron from vertices and faces for og.Mesh, subdivided onto a sphere.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc The vertices, faces, radius and detail.
+     * @returns Refused for no faces, an index past the vertices, or a count that is not a multiple of three.
+     */
+    function polyhedronGeometry(world: World, desc?: PolyhedronGeometryDesc): Result<Geometry>;
+    /**
+     * Make an icosahedron (twenty faces) for og.Mesh; with detail, a geodesic sphere.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc Its radius and detail.
+     */
+    function icosahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>;
+    /**
+     * Make a dodecahedron (twelve pentagons, thirty-six triangles) for og.Mesh.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc Its radius and detail.
+     */
+    function dodecahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>;
+    /**
+     * Make an octahedron (eight faces) for og.Mesh.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc Its radius and detail.
+     */
+    function octahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>;
+    /**
+     * Make a tetrahedron (four faces) for og.Mesh.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc Its radius and detail.
+     */
+    function tetrahedronGeometry(world: World, desc?: SolidGeometryDesc): Result<Geometry>;
+    /**
+     * Make a section swept along a path for og.Mesh, tapered and twisted by keys.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc The section, path, keys and caps.
+     * @returns 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.
+     */
+    function sweepGeometry(world: World, desc?: SweepGeometryDesc): Result<Geometry>;
+    /**
+     * 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 The world whose renderer owns the geometry.
+     * @param desc The operation and its operands.
+     * @returns Refused for a dead geometry, a placement with a zero scale, or a position that is not finite.
+     */
+    function csgGeometry(world: World, desc?: CsgGeometryDesc): Result<Geometry>;
+    /**
+     * Make one geometry of several placed ones for og.Mesh: one draw instead of many, mirrored halves, arrays.
+     *
+     * @param world The world whose renderer owns the geometry.
+     * @param desc The parts and their placements.
+     * @returns Refused for no parts, a dead geometry, or a placement with a zero scale.
+     */
+    function mergeGeometries(world: World, desc?: MergeGeometriesDesc): Result<Geometry>;
     /**
      * Draw lines this frame. Systems and commands may call it; the list is cleared at every tick, so submit them every tick they should show (og.Lines keeps a static set).
      *
@@ -21750,7 +22660,7 @@ export declare namespace og {
      */
     function setPostParam(world: World, post: Post, name: string, value: readonly number[]): Result<void>;
     /**
-     * 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.
      *
      * @param world The world asked.
      */
@@ -21762,6 +22672,14 @@ export declare namespace og {
      */
     function bakedLighting(world: World): readonly BakedScene[];
   }
+  /**
+   * three.js's Path (named Path2 beside og.path's 3D paths): `new og.Path2().moveTo(0, 0).lineTo(1, 0)`.
+   */
+  const Path2: Path2Class;
+  /**
+   * three.js's Shape: `const s = new og.Shape(); s.moveTo(0, 0).lineTo(1, 0).lineTo(0, 1); s.holes.push(hole)`.
+   */
+  const Shape: ShapeClass;
   /**
    * Draws a loaded glTF's default scene at the entity's world transform: every mesh node with its glTF material. Scene entities with a `model` line get one; world.instantiate of a glTF asset spawns one.
    * The glTF's materials are shared by every instance of it; `tint` and `flash` are this instance's own, carried with its transform to the lit shaders (one draw for every instance, whatever each shows), so one of a crowd can flash when struck.
@@ -21802,7 +22720,7 @@ export declare namespace og {
     function defaultBundle(world: World): Result<Asset>;
     /**
      * Load a cooked glTF (.gltf or .glb), as three.js GLTFLoader.load: its meshes, materials and textures join the renderer once.
-     * A MagicaVoxel `.vox` cooks to a glTF and loads here too: greedy-meshed, flat-shaded, its palette as vertex colours, z-up turned y-up, each model about its centre (MagicaVoxel's pivot, with a scene graph or without). Its import settings (`models/hut.vox.ogt`, `type import`) size and place it: `model { voxScale 0.1 voxOrigin bottom }` is 0.1 m a voxel (default 1) and the lowest voxel on y = 0 (default `center`, the editor's origin). A `.vox` with frames (MagicaVoxel's animation) cooks to clips that swap the frames' models, played by og.AnimationPlayer as any skinned clip: `voxFps 8` (default 10) and `voxClip walk 0 3` (frames 0 to 3; default one clip `frames` of every frame).
+     * A MagicaVoxel `.vox` cooks to a glTF and loads here too: greedy-meshed, flat-shaded, its palette as vertex colours, z-up turned y-up, each model about its centre (MagicaVoxel's pivot, with a scene graph or without). Its import settings (`models/hut.vox.ogt`, `type import`) size and place it: `model { voxScale 0.1 voxOrigin bottom }` is 0.1 m a voxel (default 1) and the lowest voxel on y = 0 (default `center`, the editor's origin). A `.vox` with frames (MagicaVoxel's animation) cooks to clips that swap the frames' models, played by og.AnimationPlayer as any skinned clip: `voxFps 8` (default 10) and `voxClip walk 0 3` (frames 0 to 3; default one clip `frames` of the file's playback range, else of every frame); a node's `_loop` repeats its keys as the editor plays them.
      *
      * @param world The world that owns the asset.
      * @param path The asset id, such as `models/ship.glb`.
@@ -21873,7 +22791,7 @@ export declare namespace og {
      */
     function shader(world: World, path: string): Result<Shader>;
     /**
-     * A custom post pass for PostEffects.custom1 to custom8, from a cooked `.ogt` of `type post`: `code` or `source` (a `.wgsl` beside it) defining `fn post(f: PostInput, p: Params) -> vec4<f32>` and `param <name> float|vec2|vec3|vec4|color <default...>` lines (at most eight). The function reads previous(uv), scene_color(uv), depth(uv), normal(uv) and f.uv, f.pixel, f.size, f.time, and returns linear HDR colour (the og-game skill's Custom post passes section has the contract). The cook compiles it for every back end. Loaded once per path.
+     * A custom post pass for PostEffects.custom, from a cooked `.ogt` of `type post`: `code` or `source` (a `.wgsl` beside it) defining `fn post(f: PostInput, p: Params) -> vec4<f32>` and `param <name> float|vec2|vec3|vec4|color <default...>` lines (at most eight). The function reads previous(uv), scene_color(uv), depth(uv), normal(uv) and f.uv, f.pixel, f.size, f.time, and returns linear HDR colour (the og-game skill's Custom post passes section has the contract). The cook compiles it for every back end. Loaded once per path.
      *
      * @param world The world whose renderer owns it.
      * @param path The asset id, such as `post/crt.ogt`.
@@ -22341,9 +23259,9 @@ export declare namespace og {
    * Plays a clip of a 2D rig at the entity: the og.skeleton2d system advances it by scaled time (Time.scaledDt) after the game's systems and fires its events as og.Skeleton2DEvent; extraction draws its slots, in their order, as textured triangles of the sprite batch at `layer` (region attachments as quads, mesh attachments weighted to bones and deformed by the clip), lit by og.Lighting2D when the layer is in its range, as a sprite there is. The rig's pixels are `unit` to a world unit and +y is up; the entity's og.Transform places, turns (about z) and scales it.
    * Changing `clip` restarts at 0 (or at `time`, written in the same tick); writing a different time is a seek and fires no events. The pose is a function of these fields, the Transform and the og.IkTarget2D on it; the playback position is world state (the og.skeleton2d state block).
    */
-  const Skeleton2D: ComponentType<{ readonly rig: FieldSpec<"Rig2D">; readonly clip: FieldSpec<"u32">; readonly time: FieldSpec<"f32">; readonly speed: FieldSpec<"f32">; readonly loop: FieldSpec<"bool">; readonly flipX: FieldSpec<"bool">; readonly layer: FieldSpec<"i32">; readonly finished: FieldSpec<"bool"> }, Skeleton2D>;
+  const Skeleton2D: ComponentType<{ readonly rig: FieldSpec<"Rig2D">; readonly clip: FieldSpec<"u32">; readonly time: FieldSpec<"f32">; readonly speed: FieldSpec<"f32">; readonly loop: FieldSpec<"bool">; readonly flipX: FieldSpec<"bool">; readonly layer: FieldSpec<"i32">; readonly skin: FieldSpec<"u32">; readonly finished: FieldSpec<"bool"> }, Skeleton2D>;
   /**
-   * A 2D skeleton's clip passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
+   * A 2D skeleton's clip, or the clip a child armature in one of its slots plays, passed one of its events (`event 0.2 "step"` in the rig) in the last tick: footsteps, the frame a swing lands. Read in the tick after, like every event; a clip started at 0 fires its events at 0, a looping clip fires each once per pass.
    */
   const Skeleton2DEvent: EventType<Skeleton2DEvent>;
   /**
@@ -23800,7 +24718,7 @@ export declare namespace og {
   const TerrainScatter: ComponentType<{ readonly data: FieldSpec<"TerrainData">; readonly geometry: FieldSpec<"Geometry">; readonly material: FieldSpec<"Material">; readonly layer: FieldSpec<"u32">; readonly density: FieldSpec<"f32">; readonly distance: FieldSpec<"f32">; readonly fade: FieldSpec<"f32">; readonly minScale: FieldSpec<"f32">; readonly maxScale: FieldSpec<"f32">; readonly align: FieldSpec<"f32">; readonly seed: FieldSpec<"u32"> }, TerrainScatter>;
   /**
    * Terrain (phase 2): a height field over a rectangle, cooked by `og cook` from a `type terrain` .ogt (a 16-bit grey PNG or an EXR heightmap, an optional control map, up to four layered materials with slope and altitude rules, their maps separate textures or layers of two texture arrays: `layers` and `layerNormals` with each layer's `albedoLayer` and `normalLayer`, two sampled textures instead of up to eight) into tiles; drawn as a geometry clipmap around the camera (nested levels by distance, no cracks) that casts and receives shadows under the fog; collided with as a height field; baked into navmeshes by a navmesh file's `terrain` entry.
-   * Load it with og.terrain.load, then place it: an og.Terrain on an entity draws it placed by the entity's world transform (centred on its position, turned and scaled with it), and an og.Collider of shape SHAPE_HEIGHTFIELD naming the TerrainInfo's geometry makes it solid. og.TerrainScatter grows grass, flowers or stones over a layer near the camera. og.terrain.sample answers the surface's height and normal anywhere (pass it the entity's position, quaternion and scale); og.terrain.edit raises, lowers, flattens, smooths or paints it at runtime, and og.terrain.setLayer retunes a layer. Edits are world state: a snapshot keeps them, the world hash covers them, and a restore brings the ground back as it was (rebuilt from the cook with the restored edits replayed, for the renderer, physics and sample alike).
+   * Load it with og.terrain.load, then place it: an og.Terrain on an entity draws it placed by the entity's world transform (centred on its position, turned and scaled with it), and an og.Collider of shape SHAPE_HEIGHTFIELD naming the TerrainInfo's geometry makes it solid. og.TerrainScatter grows grass, flowers or stones over a layer near the camera. og.terrain.sample answers the surface's height and normal anywhere (pass it the entity's position, quaternion and scale); og.terrain.edit raises, lowers, flattens, smooths or paints it at runtime, and og.terrain.setLayer retunes a layer. Terrain is 3D: the 2D profile's publish and lanes modules leave it out (RenderCapabilities.world3d is false), where every call here answers a refusal naming that field. Edits are world state: a snapshot keeps them, the world hash covers them, and a restore brings the ground back as it was (rebuilt from the cook with the restored edits replayed, for the renderer, physics and sample alike).
    * Its tiles stream (phase 3): the cook stores the field as a pyramid of tiles, each compressed on its own, and every frame the renderer keeps on the GPU only the tiles the camera's clipmap wants, within each terrain's tile budget (16 MiB by default), decoded off the frame (a worker thread natively, the browser's DecompressionStream on the Web) a few at a time, the most needed first; until a tile arrives its area draws from the coarser level that holds it, then fades in. Nothing a tick reads depends on which tiles are resident (collision and og.terrain.sample read the whole field), so a run's world hash is the same streamed or not. The probe's `terrain_stream:resident` decodes every wanted tile before each frame instead (`terrain_stream:stream[:<MiB>]` streams again, within that budget), and `dump_stream`'s `terrain` gives the tiles resident, waiting, decoding and cached.
    */
   namespace terrain {