@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#267@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#286@#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/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.d.ts

@@ -1,3 +1,24 @@
+/**
+ * The standard material's uniform.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MATERIAL_INFO_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_DIFFUSE_TEXTURE_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_DIFFUSE_SAMPLER_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_NORMAL_TEXTURE_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_NORMAL_SAMPLER_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_ORM_TEXTURE_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_ORM_SAMPLER_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_EMISSIVE_TEXTURE_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_EMISSIVE_SAMPLER_RESOURCE: ShaderResourceDescriptor;
 /**
  * Group 0 of the standard material template: its uniform and its four textures.
  *
@@ -9,5 +30,6 @@
  * @type {ShaderResourceGroupDescriptor}
  */
 export const SHADING_MATERIAL_RESOURCE_GROUP: ShaderResourceGroupDescriptor;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 //# sourceMappingURL=SHADING_MATERIAL_RESOURCE_GROUP.d.ts.map

package/src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SHADING_MATERIAL_RESOURCE_GROUP.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,8CAFU,6BAA6B,CAE4C;8CAbrC,wDAAwD"}
+{"version":3,"file":"SHADING_MATERIAL_RESOURCE_GROUP.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qCAFU,wBAAwB,CAEgF;AAElH,uCAAuC;AACvC,gDADW,wBAAwB,CAC2E;AAC9G,uCAAuC;AACvC,gDADW,wBAAwB,CAC0E;AAC7G,uCAAuC;AACvC,+CADW,wBAAwB,CACyE;AAC5G,uCAAuC;AACvC,+CADW,wBAAwB,CACwE;AAC3G,uCAAuC;AACvC,4CADW,wBAAwB,CACmE;AACtG,uCAAuC;AACvC,4CADW,wBAAwB,CACkE;AACrG,uCAAuC;AACvC,iDADW,wBAAwB,CAC6E;AAChH,uCAAuC;AACvC,iDADW,wBAAwB,CAC4E;AAE/G;;;;;;;;;GASG;AACH,8CAFU,6BAA6B,CAE4C;yCArC1C,mDAAmD;8CAC9C,wDAAwD"}

package/src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js

@@ -1,7 +1,31 @@
 import { GPUShaderStage } from "../../../descriptor/GPUShaderStage.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 import { MATERIAL_METADATA_STRUCT } from "../MATERIAL_METADATA_STRUCT.js";
 
+/**
+ * The standard material's uniform.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MATERIAL_INFO_RESOURCE = ShaderResourceDescriptor.uniform("material_info", MATERIAL_METADATA_STRUCT);
+
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_DIFFUSE_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("texture_diffuse", "float");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_DIFFUSE_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("texture_diffuse_sampler");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_NORMAL_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("texture_normal", "float");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_NORMAL_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("texture_normal_sampler");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_ORM_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("texture_orm", "float");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_ORM_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("texture_orm_sampler");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_EMISSIVE_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("texture_emissive", "float");
+/** @type {ShaderResourceDescriptor} */
+export const MATERIAL_EMISSIVE_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("texture_emissive_sampler");
+
 /**
  * Group 0 of the standard material template: its uniform and its four textures.
  *
@@ -16,14 +40,14 @@ export const SHADING_MATERIAL_RESOURCE_GROUP = new ShaderResourceGroupDescriptor
 
 SHADING_MATERIAL_RESOURCE_GROUP.label = "Material";
 
-SHADING_MATERIAL_RESOURCE_GROUP.addUniform("material_info", MATERIAL_METADATA_STRUCT)
-    .addTexture("texture_diffuse", "float")
-    .addSampler("texture_diffuse_sampler")
-    .addTexture("texture_normal", "float")
-    .addSampler("texture_normal_sampler")
-    .addTexture("texture_orm", "float")
-    .addSampler("texture_orm_sampler")
-    .addTexture("texture_emissive", "float")
-    .addSampler("texture_emissive_sampler")
+SHADING_MATERIAL_RESOURCE_GROUP.add(MATERIAL_INFO_RESOURCE)
+    .add(MATERIAL_DIFFUSE_TEXTURE_RESOURCE)
+    .add(MATERIAL_DIFFUSE_SAMPLER_RESOURCE)
+    .add(MATERIAL_NORMAL_TEXTURE_RESOURCE)
+    .add(MATERIAL_NORMAL_SAMPLER_RESOURCE)
+    .add(MATERIAL_ORM_TEXTURE_RESOURCE)
+    .add(MATERIAL_ORM_SAMPLER_RESOURCE)
+    .add(MATERIAL_EMISSIVE_TEXTURE_RESOURCE)
+    .add(MATERIAL_EMISSIVE_SAMPLER_RESOURCE)
 
 SHADING_MATERIAL_RESOURCE_GROUP.addVisibility(GPUShaderStage.FRAGMENT);

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).
@@ -155,6 +156,12 @@ wide-register variants bind nine, which is the one place the system spends past
 still inside the ten the engine demands of an adapter. `particle_shaders_wgsl_validity.spec` pins
 the count for every pass.
 
+Every pass that runs the VM — emit, simulate, their wide variants and the warm-up's advance — also
+binds the scene's published wind field (`../wind/`, `GPUSceneWind.bind`, per frame): one uniform, one
+3-D texture and a sampler, and no storage buffer, so it costs none of the eight. It is bound with or
+without a producer; with none it reads still air. `graph_particles_wind.spec` holds every one of
+those passes to it.
+
 ### The VM (`ParticleVM`)
 
 Register machine, emulator-safe (bounded instruction loop + big `switch`, no subgroup ops, no
@@ -181,6 +188,12 @@ recursion, no data-dependent jumps — conditionals are predicated via CMP/SELEC
 - Builtins (`LOAD_BUILTIN`): DT, EMITTER_AGE, EMITTER_POSITION, EMITTER_DIRECTION, EMITTER_UP,
   PARTICLE_INDEX, SPAWN_FRACTION, TIME … assembled per-invocation by the host shader. The emitter's
   position and axes are its node's `global` out of the scene database.
+- `SAMPLE_WIND dst, position` (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §13): the scene's wind at a
+  world position, m/s — three lanes in, three out (a fourth, if asked for, is zero). The one opcode
+  that reads a resource the host binds: the interpreter calls `particle_vm_sample_wind`, which every
+  particle host defines over the published wind field (`vm/chunk_particle_vm_wind_field.js`), and the
+  JS reference calls its `sample_wind` host function — still air when a host passes none. To the
+  optimizer it is a pure read: removable, shareable within a run, narrowable to three, never folded.
 
 #### Two interpreters
 
@@ -229,8 +242,9 @@ A core `NodeGraph` holds particle nodes (ports + parameters) for INIT and UPDATE
 
 Standard node library: constants, attribute get/set, arithmetic/vector/math, random (uniform/sphere/
 disk/cone), authored curves and RGB/RGBA gradients, noise (curl), integrate, gravity, emit-shapes,
-compare/select, kill-if. Curves and gradients expand into graph nodes that emit ordinary VM
-arithmetic; no animation-table binding or sampling opcode is needed.
+compare/select, kill-if, and `wind` (a world position in, the scene's wind there out: `SAMPLE_WIND`).
+Curves and gradients expand into graph nodes that emit ordinary VM arithmetic; no animation-table
+binding or sampling opcode is needed.
 
 ### Emitters run at entities' rows
 
@@ -265,7 +279,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 +365,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 +530,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.
@@ -689,6 +743,7 @@ src/shade/renderer/particles/
   vm/chunk_particle_vm.js            WGSL interpreter CodeChunk (parity target)
   vm/chunk_particle_vm_registers_fast.js  register file in var<private> — the interpreter that runs
   vm/chunk_particle_vm_registers_wide.js  register file in storage — the fallback
+  vm/chunk_particle_vm_wind_field.js  the VM's wind read, off the scene's published wind field
   shaders/chunk_particle_simulate_step.js one particle's simulate, shared by both simulate shaders
   shaders/chunk_particle_emit_step.js     one newborn's emit, shared by both emit shaders
   graph/ParticleNodeDescription.js   node type base (ports + lowering)
@@ -830,8 +885,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.
 

package/src/shade/renderer/particles/GPUParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/particles/GPUParticleSystem.js

@@ -498,6 +498,9 @@ export class GPUParticleSystem {
             graph,
             camera,
             scene_database,
+            // The scene's wind, which every VM pass binds for `SAMPLE_WIND`. The scene context always
+            // has one; nothing here knows or asks what produces it.
+            wind: this.scene_context.wind,
             gpu: buffers,
             emitters,
             capacity: this.capacity,