@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/renderer/light/environment/execute_filter_environment_map.d.ts

@@ -1,7 +1,17 @@
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+/**
+ * Offer the pipeline {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_filter_environment_map_pipelines(enquiry: PipelineEnquiry): void;
 /**
  *
  * @param {GPUTextureContext} map
  * @param {ShadeGPUCommandContext} encoder
  */
 export function execute_filter_environment_map(map: GPUTextureContext, encoder: ShadeGPUCommandContext): void;
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 //# sourceMappingURL=execute_filter_environment_map.d.ts.map

package/src/shade/renderer/light/environment/execute_filter_environment_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/execute_filter_environment_map.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,8GAmDC"}
+{"version":3,"file":"execute_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/execute_filter_environment_map.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;;;;GAIG;AACH,kEAFW,eAAe,QAIzB;AAED;;;;GAIG;AACH,8GAmDC;8BApEY,OAAO,6CAA6C,EAAE,eAAe"}

package/src/shade/renderer/light/environment/execute_filter_environment_map.js

@@ -3,6 +3,19 @@ import { TextureViewDescriptor } from "../../../descriptor/texture/TextureViewDe
 import { SPHERE_PROBE_MIPMAP_LEVELS } from "./DEFINES.js";
 import { shader_convolve_reflection_map } from "./shader_convolve_reflection_map.js";
 
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+
+/**
+ * Offer the pipeline {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_filter_environment_map_pipelines(enquiry) {
+    enquiry.compute.push(shader_convolve_reflection_map.pipeline);
+}
+
 /**
  *
  * @param {GPUTextureContext} map

package/src/shade/renderer/lightmap/GPULightMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightMap.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/lightmap/GPULightMap.js"],"names":[],"mappings":"AAmBA;IAgCI;;;OAGG;IACH,+BA6CC;IA/ED;;;OAGG;IACH,WAFU,iBAAiB,GAAC,IAAI,CAEf;IACjB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IACpB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IAEpB;;;OAGG;IACH,aAFU,iBAAiB,GAAC,IAAI,CAEb;IAEnB;;;OAGG;IACH,yBAEC;IA2ED;;;;OAIG;IACH,wEAmCC;IA6BD;;OAEG;IACH,oBA2DC;IAED,iBA4EC;IAED;;;;OAIG;IACH,kEAQC;;CAEJ;kCAzViC,iCAAiC"}
+{"version":3,"file":"GPULightMap.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/lightmap/GPULightMap.js"],"names":[],"mappings":"AAoBA;IAgCI;;;OAGG;IACH,+BA6CC;IA/ED;;;OAGG;IACH,WAFU,iBAAiB,GAAC,IAAI,CAEf;IACjB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IACpB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IAEpB;;;OAGG;IACH,aAFU,iBAAiB,GAAC,IAAI,CAEb;IAEnB;;;OAGG;IACH,yBAEC;IA2ED;;;;OAIG;IACH,wEAmCC;IA6BD;;OAEG;IACH,oBA6DC;IAED,iBA4EC;IAED;;;;OAIG;IACH,kEAQC;;CAEJ;kCA5ViC,iCAAiC"}

package/src/shade/renderer/lightmap/GPULightMap.js

@@ -11,6 +11,7 @@ import { graph_draw_lightmap_viz_buffer } from "./bake/raster/graph_draw_lightma
 import { shader_lightmap_denoise_sh } from "./bake/shader_lightmap_denoise_sh.js";
 import { shader_lightmap_dilate } from "./bake/shader_lightmap_dilate.js";
 import { shader_lightmap_viz_to_sh } from "./bake/shader_lightmap_viz_to_sh.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 import { DEFAULT_LIGHTMAP_RESOLUTION } from "./DEFAULT_LIGHTMAP_RESOLUTION.js";
 
 const MAX_LIGHT_MAP_SIZE = DEFAULT_LIGHTMAP_RESOLUTION;
@@ -233,6 +234,8 @@ export class GPULightMap {
 
                 light_data: scene_ctx.lights.buffer_data,
                 tEnvironment: scene_ctx.lights.environment.obtainView(),
+                tParticipatingMediaNoise: scene_ctx.volumetrics.noise_atlas.texture.obtainView(),
+                sParticipatingMediaNoise: graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
 
                 tlas: scene_ctx.tlas.buffer,
                 blas_lookup: scene_ctx.geometries.blas.buffer_metadata,

package/src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_lightmap_viz_to_irradiance_flat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.js"],"names":[],"mappings":"AAsOA,iEASE;4BArM0B,6BAA6B"}
+{"version":3,"file":"shader_lightmap_viz_to_irradiance_flat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.js"],"names":[],"mappings":"AA0OA,iEASE;4BAzM0B,6BAA6B"}

package/src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.js

@@ -44,6 +44,7 @@ import { ImageShader } from "../../shader/ImageShader.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
 import { sr_create_group_RTX } from "../../geometry/sr_create_group_RTX.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 import { chunk_lightmap_geometry_uv_to_atlas } from "../chunk_lightmap_geometry_uv_to_atlas.js";
 
 const resources = new ShaderResourceSetDescriptor();
@@ -58,6 +59,9 @@ resources.createGroup()
 resources.createGroup()
     .addStorageBuffer("light_data", WebGPUArray.u32)
     .addTexture("tEnvironment", "unfilterable-float", "2d")
+    // the fog volumes' noise, read through participating_media_volume_density_at
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR)
 
 resources.createGroup()
     .addTexture("viz_mesh", "uint")

package/src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_sh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_lightmap_viz_to_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_sh.js"],"names":[],"mappings":"AAmOA,oDAOE;4BAlM0B,6BAA6B"}
+{"version":3,"file":"shader_lightmap_viz_to_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_sh.js"],"names":[],"mappings":"AAuOA,oDAOE;4BAtM0B,6BAA6B"}

package/src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_sh.js

@@ -45,6 +45,7 @@ import { sr_create_group_RTX } from "../../geometry/sr_create_group_RTX.js";
 import { chunk_lightmap_geometry_uv_to_atlas } from "../chunk_lightmap_geometry_uv_to_atlas.js";
 import { LIGHTMAP_SH_COLOR_TARGETS_DESCRIPTOR } from "./LIGHTMAP_SH_COLOR_TARGETS_DESCRIPTOR.js";
 import { LIGHTMAP_SH_FRAGMENT_OUTPUT } from "./LIGHTMAP_SH_FRAGMENT_OUTPUT.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 
 const resources = new ShaderResourceSetDescriptor();
 sr_create_group_RTX(resources);
@@ -58,6 +59,9 @@ resources.createGroup()
 resources.createGroup()
     .addStorageBuffer("light_data", WebGPUArray.u32)
     .addTexture("tEnvironment", "unfilterable-float", "2d")
+    // the fog volumes' noise, read through participating_media_volume_density_at
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR)
 
 resources.createGroup()
     .addTexture("viz_buffer", "uint") // [mesh, triangle]

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#265@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#271@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/material/GPUMaterialManager.d.ts

@@ -71,16 +71,27 @@ export class GPUMaterialManager {
      */
     destroy(): void;
     /**
-     * Build a template's G-buffer pipeline now, rather than on the frame its first material is
-     * drawn. Pipeline creation is synchronous, so a template that first appears mid-game compiles
-     * on that frame; this lets its owner pay for it at a moment of its choosing — a level load.
+     * Offer the pipelines materials are drawn and recorded with — see {@link PipelineEnquiry}: the
+     * G-buffer pipeline of the standard template, which a renderer draws a plain material with
+     * before any material has arrived, and of every template a material has brought since, and the
+     * upload of the metadata table.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry: PipelineEnquiry): void;
+    /**
+     * Start compiling a template's G-buffer pipeline now, rather than on the frame its first
+     * material is drawn — a template that first appears mid-game would otherwise compile on that
+     * frame, synchronously. Its owner pays for it at a moment of its choosing, a level load, off the
+     * thread that presents frames, and the renderer holds frames back until it is in.
      *
      * The alpha-tested pipelines of a template that can cut out are built on the first alpha-tested
      * pass that meets one of its materials, as they always have been.
      *
      * @param {ShadeMaterialTemplate} template
+     * @returns {Promise<void>} settles once the pipeline is compiled; never rejects
      */
-    prewarm(template: ShadeMaterialTemplate): void;
+    prewarm(template: ShadeMaterialTemplate): Promise<void>;
     /**
      * A scene's drawn materials grouped by template — the alpha-tested passes filter from this.
      * Derived once per drawn set; the same array as `drawn` when it is already grouped.
@@ -104,6 +115,7 @@ export class GPUMaterialManager {
     update(ctx: ShadeGPUCommandContext): void;
     #private;
 }
+export type PipelineEnquiry = import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 export type GPUViewContext = import("../view/GPUViewContext.js").GPUViewContext;
 export type FrameGraph = import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 export type ShadeGPUCommandContext = import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;

package/src/shade/renderer/material/GPUMaterialManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AAyNA;IAiFI;;;;;;;;OAQG;IACH,yCANW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,aACrB,iBAAiB,EAmD3B;IApID;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IAsBrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IAoLD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAiMnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;;;;;;;;;;OAYG;IACH,kBAHW,aAAa,GACX,OAAO,CAyBnB;IAED;;;;OAIG;IACH,gBAaC;IAED;;;;;;;;;OASG;IACH,kBAFW,qBAAqB,QAM/B;IAsBD;;;;;;OAMG;IACH,0BAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAED;;;;;;OAMG;IACH,wBAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAuED;;;OAGG;IACH,YAFW,sBAAsB,QAiChC;;CAEJ;6BA91BY,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;gCACzD,OAAO,yBAAyB,EAAE,iBAAiB;6BACnD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;oCAC1C,OAAO,qCAAqC,EAAE,qBAAqB;mCApBzE,yBAAyB;mCAjBG,8CAA8C"}
+{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AA2NA;IAoFI;;;;;;;;OAQG;IACH,yCANW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,aACrB,iBAAiB,EAiD3B;IArID;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IAyBrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IAsLD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAiMnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;;;;;;;;;;OAYG;IACH,kBAHW,aAAa,GACX,OAAO,CAyBnB;IAED;;;;OAIG;IACH,gBAaC;IAED;;;;;;;OAOG;IACH,0BAFW,eAAe,QAazB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,qBAAqB,GACnB,QAAQ,IAAI,CAAC,CAMzB;IAsBD;;;;;;OAMG;IACH,0BAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAED;;;;;;OAMG;IACH,wBAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAuED;;;OAGG;IACH,YAFW,sBAAsB,QAiChC;;CAEJ;8BA33BY,OAAO,0CAA0C,EAAE,eAAe;6BAClE,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;gCACzD,OAAO,yBAAyB,EAAE,iBAAiB;6BACnD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;oCAC1C,OAAO,qCAAqC,EAAE,qBAAqB;mCAtBzE,yBAAyB;mCAjBG,8CAA8C"}

package/src/shade/renderer/material/GPUMaterialManager.js

@@ -28,10 +28,12 @@ import {
 import { MATERIAL_METADATA_STRUCT } from "./MATERIAL_METADATA_STRUCT.js";
 import { PIXEL_TEXTURE_ORM } from "./PIXEL_TEXTURE_ORM.js";
 import { GPUMaterialServices, MaterialGPUDefaults } from "./template/GPUMaterialServices.js";
+import { STANDARD_MATERIAL_TEMPLATE } from "./standard/STANDARD_MATERIAL_TEMPLATE.js";
 import { material_template_of } from "./template/material_template_of.js";
 import { TransparencyMode } from "./TransparencyMode.js";
 
 /**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../view/GPUViewContext.js").GPUViewContext} GPUViewContext
  */
 
@@ -239,9 +241,12 @@ export class GPUMaterialManager {
     #bindings;
 
     /**
-     * @type {GPURenderPipeline}
+     * Made on first use rather than at construction, so that it compiles with everything else the
+     * renderer offers (see {@link enquirePipelines}) instead of alone, synchronously, before that.
+     *
+     * @type {GPURenderPipeline|null}
      */
-    #material_buffer_pipeline;
+    #material_buffer_pipeline = null;
 
     /**
      * @type {GPUSingleTypeTable}
@@ -315,8 +320,6 @@ export class GPUMaterialManager {
             type: MATERIAL_METADATA_STRUCT
         });
 
-        this.#material_buffer_pipeline = render_pipelines.obtain(material_buffer_pipeline_descriptor);
-
         // initialize defaults
         const defaults = new MaterialGPUDefaults();
 
@@ -418,6 +421,10 @@ export class GPUMaterialManager {
             }
         });
 
+        if (this.#material_buffer_pipeline === null) {
+            this.#material_buffer_pipeline = this.#render_pipelines.obtain(material_buffer_pipeline_descriptor);
+        }
+
         pass.setPipeline(this.#material_buffer_pipeline);
 
         const bindings = this.#bindings;
@@ -731,19 +738,42 @@ export class GPUMaterialManager {
     }
 
     /**
-     * Build a template's G-buffer pipeline now, rather than on the frame its first material is
-     * drawn. Pipeline creation is synchronous, so a template that first appears mid-game compiles
-     * on that frame; this lets its owner pay for it at a moment of its choosing — a level load.
+     * Offer the pipelines materials are drawn and recorded with — see {@link PipelineEnquiry}: the
+     * G-buffer pipeline of the standard template, which a renderer draws a plain material with
+     * before any material has arrived, and of every template a material has brought since, and the
+     * upload of the metadata table.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry) {
+        const services = this.#services;
+
+        enquiry.render.push(material_buffer_pipeline_descriptor);
+        enquiry.render.push(STANDARD_MATERIAL_TEMPLATE.gbuffer_pipeline_descriptor(services));
+
+        for (const material_ctx of this.contexts.values()) {
+            enquiry.render.push(material_ctx.template.gbuffer_pipeline_descriptor(services));
+        }
+
+        GPUSingleTypeTable.enquirePipelines(enquiry);
+    }
+
+    /**
+     * Start compiling a template's G-buffer pipeline now, rather than on the frame its first
+     * material is drawn — a template that first appears mid-game would otherwise compile on that
+     * frame, synchronously. Its owner pays for it at a moment of its choosing, a level load, off the
+     * thread that presents frames, and the renderer holds frames back until it is in.
      *
      * The alpha-tested pipelines of a template that can cut out are built on the first alpha-tested
      * pass that meets one of its materials, as they always have been.
      *
      * @param {ShadeMaterialTemplate} template
+     * @returns {Promise<void>} settles once the pipeline is compiled; never rejects
      */
     prewarm(template) {
         assert.equal(template.isShadeMaterialTemplate, true, 'template.isShadeMaterialTemplate !== true');
 
-        this.#render_pipelines.obtain(template.gbuffer_pipeline_descriptor(this.#services));
+        return this.#render_pipelines.prepare(template.gbuffer_pipeline_descriptor(this.#services));
     }
 
     /**

package/src/shade/renderer/particles/DESIGN.md

@@ -9,7 +9,8 @@ rows, and the decision to spawn is the GPU's.
 ## Goals (from the brief)
 
 - Single simulation execution shader (data-driven VM, not one-pipeline-per-effect).
-- Projection modes: camera-facing billboard (+ velocity-stretched, axis-locked, world-oriented).
+- Projection modes: camera-facing billboard (+ velocity-stretched, axis-locked, world-oriented),
+  each a frame a particle's own orientation (a quaternion) turns the quad inside. See "Orientation".
 - Order-independent transparency: the particles are a side channel of the AVBOIT pipeline, so they
   composite against the transparent meshes with no depth ordering of any kind.
 - Node-based composition → shader VM (compile graph → bytecode).
@@ -265,7 +266,7 @@ remembers the version its row was staged from. An author who edits an emitter sa
 One `emitters` table (CPU-managed, low churn). Row = `PARTICLE_EMITTER_STRUCT`: program
 offsets+lengths, constant-pool offset, seed, spawn rate, **node** (transforms row), **generation**,
 flags (lighting/soft/cull/blend/projection), render binding (attr offsets for
-position/size/color/rotation/frame/velocity), atlas region + flipbook grid, and the program id
+position/size/color/orientation/frame/velocity), atlas region + flipbook grid, and the program id
 the coherence pass buckets on. The atlas region is resolved, not authored: the emitter names an
 image and the system packs it, the way `ShaderManager` packs the old engine's sprites, so a repack
 moves every patch without any emitter changing. The seed is resolved too — an emitter left at 0 gets
@@ -351,7 +352,7 @@ finished appending to the alive list:
 - **accumulate** — one thread per live particle: read where its quad is and merge it into its
   emitter's accumulator. The centre is the record's `render_position`; the dilation is
   `particle_billboard_radius`, the largest offset `particle_billboard_offset` can produce for that
-  size, velocity and projection, over every corner, every roll and any camera. The box has to hold
+  size, velocity and projection, over every corner, every orientation and any camera. The box has to hold
   the *quads*, not the centres, and it has to be camera-independent, because it is read on a later
   frame. The merge is `atomic_min_f32_storage` / `atomic_max_f32_storage`, the same CAS-spin the
   skinned-mesh bounds refresh uses; both load first and return without a CAS once the box holds the
@@ -516,11 +517,51 @@ draw's.
 
 ### Rendering
 
-A 6-vertex quad is expanded per instance (billboard/velocity-stretch/axis-lock/world modes) by
-`chunk_particle_billboard_vertex`. Fragment: sample atlas (region + flipbook frame), optional
+A 6-vertex quad is expanded per instance by `chunk_particle_billboard_vertex`, on the basis the
+particle's projection mode and orientation compose (below). Fragment: sample atlas (region + flipbook frame), optional
 soft-depth fade, optional lighting (below). Soft-depth fading scales both RGB and alpha for
 premultiplied inputs; straight-alpha and additive inputs have alpha scaled before premultiplication.
 
+### Orientation
+
+**The record says how a particle is turned; the projection mode says how a view sees it.**
+
+    offset = F(mode, camera, velocity) · Q · (corner.x · size, corner.y · size · stretch, 0)
+
+- **`Q` is the `orientation` render channel**, a 4-word attribute holding a quaternion (x, y, z, w)
+  — the only rotation a particle has. It is normalised at the draw, because a program integrating a
+  spin drifts off unit length and an unnormalised quaternion scales what it turns by its squared
+  length. The zero quaternion, which is what an attribute nobody wrote holds, reads as no turn with
+  no branch, and so does an unbound channel.
+- **`F` is the mode's frame**, a proper rotation whose x and y are the sprite's right and up and whose
+  z is the side the mode shows: BILLBOARD the camera's axes; STRETCHED the screen velocity as its up
+  and the camera's axes at rest; VERTICAL world +Y as up and a horizontal face toward the eye;
+  HORIZONTAL world +X and -Z, facing +Y; FACING_WORLD the world's axes. Every one of them shows the
+  sprite the way round BILLBOARD does from its front, rather than its mirror image — three did not,
+  until the frames were written down as frames.
+- **`stretch`** is STRETCHED's `1 + |v_screen|` and 1 otherwise. It belongs to the sprite and
+  elongates it along its own +Y, before the turn.
+
+So FACING_WORLD with an orientation is a quad turned any way in the world, BILLBOARD with one is a
+quad turned relative to the eye — a turn about +Z is a roll on the screen, which is how the bonfire's
+flame, smoke and soot spin — and the other modes take a turn inside their frames with no rule of
+their own. The frame is the renderer's and the rotation the record's because the frame is the one
+part a view decides: the VM has no camera, one record is drawn by every view, and no quaternion
+written into it could face all of them.
+
+`particle_basis` composes the two once per vertex and feeds both the offset and the normal, so they
+cannot disagree about which way a mode faces. **Bounds do not change**: the basis is a rotation, so no
+corner reaches past `sqrt(2) · size · stretch`, which is what `particle_billboard_radius` already
+states; the bounds pass never reads the channel. **The VM does not change** either: a program writes
+a vec4 attribute like any other, and the node library has what it takes to build one —
+`quatFromAxisAngle`, `quatLookRotation`, `quatRotate`, `quatMultiply`, `quatIntegrate` (exact for a
+constant angular velocity at any step, which the warm-up's stretched ticks need), `sampleRotation`
+(uniform) and `emitterRotation` (the node's own rotation; `EMITTER_DIRECTION` is its -Z).
+
+There was a scalar `rotation` channel, a roll; it is gone rather than kept beside this, and
+`ParticleEffect` serializes at version 2 — a version-1 save loads with its orientation unbound, since
+its bytecode writes an angle. `ORIENTATION_PLAN_2026_10_15.md` has the alternatives and why each lost.
+
 Additive vs. alpha is never a pipeline switch: the shader emits premultiplied RGB with alpha 0
 (additive) or alpha a (normal), so one setup covers both and the choice stays per particle and
 GPU-driven. Under AVBOIT that choice picks which accumulators the fragment writes.
@@ -830,8 +871,9 @@ a vertex need not be on screen, and one quad can span the frustum.
   light evaluated at `-normal`, passed on in proportion to `1 - alpha`. The dense core of a puff
   holds light from behind back and its thin edges let it through — smoke backlit by the moon has an
   edge instead of being black. It costs nothing measurable: the draw is bound by its texture reads.
-- **The normal** is the quad's own plane per projection mode, turned to the side the eye is on and
-  bent out toward the corners (`particle_billboard_normal`), so a sprite shades as a puff.
+- **The normal** is the quad's own plane — the face of the basis its mode and orientation lay it
+  on — turned to the side the eye is on and bent out toward the corners
+  (`particle_billboard_normal`), so a sprite shades as a puff, and a turned one as it turns.
 - **The directional light skips the atmosphere's transmittance** the fog applies: meshes are lit by
   `sun.color` as it stands, and a lit particle has to agree with the surface beside it.