@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/GraphicsContext.d.ts

@@ -68,6 +68,12 @@ export class GraphicsContext {
      * @type {GPUBufferStagingAllocator}
      */
     buffer_allocator_staging: GPUBufferStagingAllocator;
+    /**
+     * Used to read data back from the GPU: `MAP_READ` buffers, held by the CPU across frames, which
+     * is why they cannot come from {@link buffer_allocator_main}.
+     * @type {GPUBufferReadbackAllocator}
+     */
+    buffer_allocator_readback: GPUBufferReadbackAllocator;
     /**
      *
      * @type {GPUTextureAllocator}
@@ -136,6 +142,7 @@ import { BindGroupManager } from "./binding/BindGroupManager.js";
 import { GPUBufferAllocator } from "./buffer/GPUBufferAllocator.js";
 import { GPUBufferAllocatorNative } from "./buffer/GPUBufferAllocatorNative.js";
 import { GPUBufferStagingAllocator } from "./buffer/GPUBufferStagingAllocator.js";
+import { GPUBufferReadbackAllocator } from "./buffer/GPUBufferReadbackAllocator.js";
 import { GPUTextureAllocator } from "./texture/GPUTextureAllocator.js";
 import { GPUBufferContext } from "./buffer/GPUBufferContext.js";
 //# sourceMappingURL=GraphicsContext.d.ts.map

package/src/shade/renderer/GraphicsContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AAiCA;IAoJI,yBA8BC;IAjLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAkCD;;;;;;;;OAQG;IACH,6DANW,sBAAsB,aACtB,oBAAoB,EAAE,cACtB;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,gCAHW,gBAAgB,GACd,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAcC;IAED,4BAEC;IAED,eAmBC;IAED,gBAcC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;+BA5UY,OAAO,0CAA0C,EAAE,gBAAgB;qCACnE,OAAO,kDAAkD,EAAE,sBAAsB;2BAKjF,OAAO,mCAAmC,EAAE,YAAY;mCAjBlC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAXzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAchD,6BAA6B;sCACtB,4CAA4C;iCAbjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAErC,uCAAuC;oCAO7C,kCAAkC;iCARtB,8BAA8B"}
+{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AAkCA;IA2JI,yBA+BC;IAzLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;;OAIG;IACH,2BAFU,0BAA0B,CAEV;IAE1B;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAmCD;;;;;;;;OAQG;IACH,6DANW,sBAAsB,aACtB,oBAAoB,EAAE,cACtB;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,gCAHW,gBAAgB,GACd,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAeC;IAED,4BAEC;IAED,eAmBC;IAED,gBAeC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;+BAtVY,OAAO,0CAA0C,EAAE,gBAAgB;qCACnE,OAAO,kDAAkD,EAAE,sBAAsB;2BAKjF,OAAO,mCAAmC,EAAE,YAAY;mCAjBlC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAZzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAehD,6BAA6B;sCACtB,4CAA4C;iCAdjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAGrC,uCAAuC;2CADtC,wCAAwC;oCAQ/C,kCAAkC;iCATtB,8BAA8B"}

package/src/shade/renderer/GraphicsContext.js

@@ -9,6 +9,7 @@ import { BindGroupManager } from "./binding/BindGroupManager.js";
 import { GPUBufferAllocator } from "./buffer/GPUBufferAllocator.js";
 import { GPUBufferAllocatorNative } from "./buffer/GPUBufferAllocatorNative.js";
 import { create_buffer, GPUBufferContext } from "./buffer/GPUBufferContext.js";
+import { GPUBufferReadbackAllocator } from "./buffer/GPUBufferReadbackAllocator.js";
 import { GPUBufferStagingAllocator } from "./buffer/GPUBufferStagingAllocator.js";
 import { GPUGeometryManager } from "./geometry/GPUGeometryManager.js";
 import { GPUCollectionLimits } from "./rasterize/expand/GPUCollectionLimits.js";
@@ -141,6 +142,13 @@ export class GraphicsContext {
      */
     buffer_allocator_staging;
 
+    /**
+     * Used to read data back from the GPU: `MAP_READ` buffers, held by the CPU across frames, which
+     * is why they cannot come from {@link buffer_allocator_main}.
+     * @type {GPUBufferReadbackAllocator}
+     */
+    buffer_allocator_readback;
+
     /**
      *
      * @type {GPUTextureAllocator}
@@ -189,6 +197,7 @@ export class GraphicsContext {
         this.buffer_allocator_main = new GPUBufferAllocator(device);
         this.buffer_allocator_native = new GPUBufferAllocatorNative(device);
         this.buffer_allocator_staging = new GPUBufferStagingAllocator(device);
+        this.buffer_allocator_readback = new GPUBufferReadbackAllocator(device);
 
         this.allocator_textures = new GPUTextureAllocator(device);
 
@@ -306,6 +315,7 @@ export class GraphicsContext {
 
         r += this.buffer_allocator_main.gpu_memory_usage;
         r += this.buffer_allocator_staging.gpu_memory_usage;
+        r += this.buffer_allocator_readback.gpu_memory_usage;
 
         r += this.allocator_textures.gpu_memory_usage;
         r += this.textures.gpu_memory_usage;
@@ -350,6 +360,7 @@ export class GraphicsContext {
         this.buffer_allocator_main.destroy();
         this.buffer_allocator_native.destroy();
         this.buffer_allocator_staging.destroy();
+        this.buffer_allocator_readback.destroy();
 
         this.#collection_limits.destroy();
     }

package/src/shade/renderer/Renderer.d.ts

@@ -44,8 +44,9 @@ export class Renderer {
      */
     avboit: AVBOITSettings;
     /**
-     * GPU particles. When on, every {@link ParticleEmitter} node in the scene is simulated on the
-     * GPU each frame and its particles are drawn through the AVBOIT transparency pipeline as a
+     * GPU particles. When on, every {@link ParticleEmitter} registered with the scene's particle
+     * system is simulated on the GPU each frame and its particles are drawn through the AVBOIT
+     * transparency pipeline as a
      * side channel of the transparent meshes — order-independently, against them and against the
      * opaque scene. Under {@link ShadeTransparencyMode.MBOIT} the particles are simulated but not
      * drawn: that path is legacy and gets no new sources.

package/src/shade/renderer/Renderer.d.ts.map

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

package/src/shade/renderer/Renderer.js

@@ -198,8 +198,9 @@ export class Renderer {
     avboit = new AVBOITSettings();
 
     /**
-     * GPU particles. When on, every {@link ParticleEmitter} node in the scene is simulated on the
-     * GPU each frame and its particles are drawn through the AVBOIT transparency pipeline as a
+     * GPU particles. When on, every {@link ParticleEmitter} registered with the scene's particle
+     * system is simulated on the GPU each frame and its particles are drawn through the AVBOIT
+     * transparency pipeline as a
      * side channel of the transparent meshes — order-independently, against them and against the
      * opaque scene. Under {@link ShadeTransparencyMode.MBOIT} the particles are simulated but not
      * drawn: that path is legacy and gets no new sources.

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -326,54 +326,44 @@ export class GPUAnimationManager {
         }>;
     }): number;
     /**
-     * High-level skin registration: consumes a {@link Skin} (CPU data
-     * with Node3D joint references and a flat inverse-bind matrix
-     * array), allocates a GPU skin record, and binds every entry in
-     * `skin.meshes` through the skinning context.
-     *
-     * **Eventual consistency.** The `skin_id` is allocated and
-     * returned synchronously — callers can immediately pass it to
-     * state mutators or {@link unregister_skin}. If any joint's
-     * Node3D hasn't been added to a scene yet (no `id_mapping` row),
-     * the joint-block chain that drives the deformation is queued
-     * and built on the next {@link update} that sees all joints
-     * resolved. The skin's table row uses a placeholder
-     * `joint_block_head` until then — observationally indistinguishable
-     * from "skin with no joints driving it" (no deformation runs).
-     *
-     * Mesh→skin bindings register immediately via
-     * {@link GPUMeshSkinningContext#bind}; the skinning context
-     * already tolerates pre-scene-build registration. Each mesh also
-     * gets its {@link SkinnedMesh#skin} reference and a fresh set of
-     * bounds off it, synchronously — that part does not wait for
-     * `id_mapping`, because it reads the joints' `transform_global`
-     * rather than any GPU row.
-     *
-     * @param {Skin} skin
+     * High-level skin registration: consumes a {@link Skin} whose joints and meshes are
+     * **entities**, allocates a GPU skin record, and binds every mesh entity through the
+     * skinning context.
+     *
+     * **Eventual consistency.** The `skin_id` is allocated and returned synchronously — callers
+     * can immediately pass it to state mutators or {@link unregister_skin}. If any joint has not
+     * taken its row yet (see `GPUSceneRows.acquire`), the joint-block chain that drives the
+     * deformation is queued and built on the next {@link update} that sees every joint there.
+     * The skin's table row uses a placeholder `joint_block_head` until then — observationally
+     * indistinguishable from "skin with no joints driving it" (no deformation runs).
+     *
+     * The frame a skin's meshes are deformed in is the prefab's business, fixed once at compile
+     * (`prefab_normalize_skin_frames`); nothing about it is decided here.
+     *
+     * @param {Skin} skin joints and meshes as entities
      * @returns {number} skin id (index into the `animation_skins` table)
      */
     register_skin(skin: Skin): number;
     /**
-     * High-level clip registration: consumes a {@link ShadeAnimationClip}
-     * (CPU data with Node3D targets and per-component curves), uploads
-     * curves and tracks, and creates the GPU clip record.
-     *
-     * **Eventual consistency.** The `clip_id` is allocated and
-     * returned synchronously — callers can immediately call
-     * {@link start} / {@link stop} / {@link set_time} /
-     * {@link set_playback_rate} / {@link set_flags} / {@link clear_flags}
-     * / {@link set_playback_weight} / {@link unregister_clip}. If
-     * any channel target's Node3D hasn't been added to a scene yet
-     * (no `id_mapping` row), the bindings chain that drives the
-     * apply pass is queued and built on the next {@link update}
-     * that sees all targets resolved. The clip's table row uses a
-     * placeholder `bound_track_group_head` until then — apply
-     * produces no contributions, so the clip is observationally
-     * inert (still subject to time advancement via the tick shader
-     * if `Playing` is set).
-     *
-     * Curves and tracks are interned synchronously since they're
-     * pure data — no `id_mapping` dependency.
+     * High-level clip registration: consumes a {@link ShadeAnimationClip} whose channels target
+     * **entities**, uploads curves and tracks, and creates the GPU clip record.
+     *
+     * **Eventual consistency.** The `clip_id` is allocated and returned synchronously — callers
+     * can immediately call {@link start} / {@link stop} / {@link set_time} / {@link set_playback_rate}
+     * / {@link set_flags} / {@link clear_flags} / {@link set_playback_weight} /
+     * {@link unregister_clip}. If any target has not taken its row yet, the bindings chain that
+     * drives the apply pass is queued and built on the next {@link update} that sees every target
+     * there. The clip's table row uses a placeholder `bound_track_group_head` until then — apply
+     * produces no contributions, so the clip is observationally inert (still subject to time
+     * advancement via the tick shader if `Playing` is set).
+     *
+     * **Binding is what hands a target to the GPU.** When the chain is built, every entity it
+     * drives has its `GPUStateAuthority` TransformAttachment bit granted, so the CPU stops
+     * writing its local TRS; the last clip to leave revokes it. The entity has to have declared
+     * the component — a prefab does, on every node a clip reaches — because a grant that could
+     * silently do nothing would be a claim nobody could see.
+     *
+     * Curves and tracks are interned synchronously since they're pure data.
      *
      * @param {ShadeAnimationClip} clip
      * @returns {number} clip id
@@ -420,9 +410,9 @@ export class GPUAnimationManager {
      * `database.buffer`.
      *
      * Also drains the pending-registration queues: skins and clips
-     * whose dependencies (joint Node3D rows, channel-target rows)
+     * whose dependencies (joint rows, channel-target rows)
      * weren't ready at register time get one shot per `update` to
-     * complete. Once `id_mapping` has the missing rows, the
+     * complete. Once every entity has taken its row, the
      * deferred chain build runs and the registration becomes
      * observationally complete — the next-frame `database.update`
      * picks up the patched head pointer.
@@ -488,8 +478,10 @@ export class GPUAnimationManager {
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      * @param {number} dt_seconds wall-clock seconds since last call
+     * @returns {boolean} whether the GPU moved any row this frame — a clip applied, or a skin
+     * deformed — which is what tells the bounds and the TLAS derived from rows that they are stale
      */
-    tick(cmd_ctx: ShadeGPUCommandContext, dt_seconds: number): void;
+    tick(cmd_ctx: ShadeGPUCommandContext, dt_seconds: number): boolean;
     destroy(): void;
     #private;
 }

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

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