@waica/engine 0.19.1 → 0.20.0

package/README.md

@@ -93,6 +93,52 @@ Invalid inputs fail closed without throwing: invalid `area` bodies and non-finit
 
 Area and point intentionally use the collision system's polygonally approximated circle/ellipse outline. Ray queries intersect circle-shaped Solids as analytic ellipses and return their exact outward unit normal. Collision Layers and Masks never filter `area` or `point`; use a query filter when category-like eligibility is needed.
 
+## CPU particle emitters
+
+`ParticleEmitter` is the authorable 2D particle component. It simulates a fixed-capacity CPU batch in fixed-step time and renders the whole effect with one mesh, one geometry, and one material. Its complete authoring surface and defaults are:
+
+| Props | Defaults |
+| --- | --- |
+| continuous | `rate: 0`, `emitting: true` |
+| lifetime and spawn | `lifetime: 1`, `positionSpread: [0, 0]` |
+| motion | `velocity: [0, 0]`, `velocitySpread: [0, 0]`, `gravity: [0, 0]` |
+| coordinates and random stream | `space: 'world'`, `seed: 1` |
+| storage | `capacity: 256`, `overflow: 'recycle-oldest'` |
+| ownership | `destroyMode: 'clear'` |
+| quad | `width: 1`, `height: 1`, `startScale: 1`, `endScale: 1` |
+| tint | `startColor: 0xffffff`, `endColor: 0xffffff`, `startAlpha: 1`, `endAlpha: 0` |
+| material | `texture: ''`, `pixelArt: false`, `blend: 'normal'` |
+| draw band | `layer: 0` |
+
+```ts
+import { ParticleEmitter } from '@waica/engine'
+
+const smoke = entity.add(ParticleEmitter, {
+  rate: 12,
+  lifetime: 0.8,
+  positionSpread: [0.4, 0.1],
+  velocity: [0, 2],
+  velocitySpread: [0.5, 0.5],
+  gravity: [0, -3],
+  startColor: 0xffffff,
+  endColor: 0x777777,
+  startAlpha: 0.8,
+  endAlpha: 0,
+  texture: 'art/smoke.png',
+  blend: 'additive',
+  capacity: 256,
+})
+smoke.emit(20) // deterministic burst; returns the accepted count
+```
+
+A seeded Mulberry32 stream makes equivalent runs deterministic; `emit(count)` uses the same stream as continuous `rate` emission. `overflow: 'recycle-oldest'` (the default) replaces the oldest live particles at capacity, while `'drop-new'` rejects new ones without sampling. Resizing `capacity` clears the batch but does not reset the stream; changing `seed` or remounting does.
+
+`space: 'world'` snapshots the entity's logical origin at spawn, while `'local'` keeps live particles attached to it. Logical simulation is projection-independent: orthographic and isometric scenes only change render projection. In `sort: 'y'` scenes every live particle contributes its own global depth entry alongside Sprites, AnimatedSprites, and draining batches; equal-Y ties preserve spawn order.
+
+Textures use the Game's shared `AssetLoader`; `pixelArt` chooses nearest or linear filtering, and `blend` selects normal or additive blending. All three are reactive authoring props. A failed or empty texture falls back to the flat colored quad. Batching keeps one draw submission but does not promise order-independent or globally exact alpha composition between meshes. `destroyMode: 'clear'` removes the batch with its owner; `'drain'` transfers it to scene scope, stops emission, and simulates it until empty. Scene unload and `game.dispose()` always clear drains.
+
+`active`, `capacity`, and `emitting` are the only fields exposed by Runtime Snapshot. Particle arrays remain private. This first CPU implementation is intended for bounded 2D effects, not collision, per-particle scripting, GPU simulation, trails, rotation, or sub-emitters.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

package/dist/component.d.ts

@@ -8,7 +8,7 @@ export interface ParamSpec {
     max?: number;
     step?: number;
     /** Specialized editor control for values that are otherwise plain JSON. */
-    kind?: 'string-list';
+    kind?: 'string-list' | 'vector2' | 'color' | 'texture';
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */

package/dist/components/particle-emitter.d.ts

@@ -0,0 +1,167 @@
+import { Component } from '../component.js';
+import type { YSortBatchParticipant, YSortEntry } from '../render-sort.js';
+export type ParticleVector = [number, number];
+export type ParticleSpace = 'world' | 'local';
+export type ParticleOverflow = 'recycle-oldest' | 'drop-new';
+export type ParticleDestroyMode = 'clear' | 'drain';
+export type ParticleBlend = 'normal' | 'additive';
+/** A fixed-capacity source of short-lived, batched 2D particles. */
+export declare class ParticleEmitter extends Component implements YSortBatchParticipant {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        rate: {
+            label: string;
+            min: number;
+        };
+        emitting: {
+            label: string;
+        };
+        lifetime: {
+            label: string;
+            min: number;
+        };
+        positionSpread: {
+            label: string;
+            kind: "vector2";
+        };
+        velocity: {
+            label: string;
+            kind: "vector2";
+        };
+        velocitySpread: {
+            label: string;
+            kind: "vector2";
+        };
+        gravity: {
+            label: string;
+            kind: "vector2";
+        };
+        space: {
+            label: string;
+            options: string[];
+        };
+        seed: {
+            label: string;
+            step: number;
+        };
+        capacity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        overflow: {
+            label: string;
+            options: string[];
+        };
+        destroyMode: {
+            label: string;
+            options: string[];
+        };
+        width: {
+            label: string;
+            min: number;
+        };
+        height: {
+            label: string;
+            min: number;
+        };
+        startScale: {
+            label: string;
+            min: number;
+        };
+        endScale: {
+            label: string;
+            min: number;
+        };
+        startColor: {
+            label: string;
+            kind: "color";
+        };
+        endColor: {
+            label: string;
+            kind: "color";
+        };
+        startAlpha: {
+            label: string;
+            min: number;
+            max: number;
+        };
+        endAlpha: {
+            label: string;
+            min: number;
+            max: number;
+        };
+        texture: {
+            label: string;
+            kind: "texture";
+        };
+        pixelArt: {
+            label: string;
+        };
+        blend: {
+            label: string;
+            options: string[];
+        };
+        layer: {
+            label: string;
+            step: number;
+        };
+    };
+    rate: number;
+    emitting: boolean;
+    lifetime: number;
+    positionSpread: ParticleVector;
+    velocity: ParticleVector;
+    velocitySpread: ParticleVector;
+    gravity: ParticleVector;
+    space: ParticleSpace;
+    private _seed;
+    get seed(): number;
+    set seed(value: number);
+    private _capacity;
+    get capacity(): number;
+    set capacity(value: number);
+    overflow: ParticleOverflow;
+    destroyMode: ParticleDestroyMode;
+    width: number;
+    height: number;
+    startScale: number;
+    endScale: number;
+    startColor: number;
+    endColor: number;
+    startAlpha: number;
+    endAlpha: number;
+    private _texture;
+    get texture(): string;
+    set texture(value: string);
+    private _pixelArt;
+    get pixelArt(): boolean;
+    set pixelArt(value: boolean);
+    private _blend;
+    get blend(): ParticleBlend;
+    set blend(value: ParticleBlend);
+    private _layer;
+    get layer(): number;
+    set layer(value: number);
+    private _batch?;
+    private _unsubscribeRenderSync?;
+    private _emissionRemainder;
+    private _destroyed;
+    get active(): number;
+    onReady(): void;
+    onUpdate(dt: number): void;
+    /** Emits a burst immediately and returns how many particles from it remain active. */
+    emit(value: number): number;
+    ySortEntries(): readonly YSortEntry[];
+    setSortZ(z: number): void;
+    setSortZs(values: readonly number[]): void;
+    inspectState(): {
+        active: number;
+        capacity: number;
+        emitting: boolean;
+    };
+    onDestroy(): void;
+    private renderContext;
+    private spawnConfig;
+}

package/dist/components/particle-emitter.js

@@ -0,0 +1,219 @@
+import { Component } from '../component.js';
+import { ParticleBatch, } from '../particle-batch.js';
+import { sceneDrainsOf } from '../scene-drains.js';
+/** A fixed-capacity source of short-lived, batched 2D particles. */
+export class ParticleEmitter extends Component {
+    static componentName = 'ParticleEmitter';
+    static displayName = 'Particle Emitter';
+    static params = {
+        rate: { label: 'Rate', min: 0 },
+        emitting: { label: 'Emitting' },
+        lifetime: { label: 'Lifetime', min: 0 },
+        positionSpread: { label: 'Position spread', kind: 'vector2' },
+        velocity: { label: 'Velocity', kind: 'vector2' },
+        velocitySpread: { label: 'Velocity spread', kind: 'vector2' },
+        gravity: { label: 'Gravity', kind: 'vector2' },
+        space: { label: 'Space', options: ['world', 'local'] },
+        seed: { label: 'Seed', step: 1 },
+        capacity: { label: 'Capacity', min: 1, step: 1 },
+        overflow: { label: 'Overflow', options: ['recycle-oldest', 'drop-new'] },
+        destroyMode: { label: 'On destroy', options: ['clear', 'drain'] },
+        width: { label: 'Width', min: 0 },
+        height: { label: 'Height', min: 0 },
+        startScale: { label: 'Start scale', min: 0 },
+        endScale: { label: 'End scale', min: 0 },
+        startColor: { label: 'Start color', kind: 'color' },
+        endColor: { label: 'End color', kind: 'color' },
+        startAlpha: { label: 'Start alpha', min: 0, max: 1 },
+        endAlpha: { label: 'End alpha', min: 0, max: 1 },
+        texture: { label: 'Texture', kind: 'texture' },
+        pixelArt: { label: 'Pixel art' },
+        blend: { label: 'Blend', options: ['normal', 'additive'] },
+        layer: { label: 'Layer', step: 1 },
+    };
+    rate = 0;
+    emitting = true;
+    lifetime = 1;
+    positionSpread = [0, 0];
+    velocity = [0, 0];
+    velocitySpread = [0, 0];
+    gravity = [0, 0];
+    space = 'world';
+    _seed = 1;
+    get seed() {
+        return this._seed;
+    }
+    set seed(value) {
+        const next = Number.isFinite(value) ? Math.trunc(value) >>> 0 : 1;
+        if (next === this._seed)
+            return;
+        this._seed = next;
+        this._batch?.setSeed(next);
+    }
+    _capacity = 256;
+    get capacity() {
+        return this._capacity;
+    }
+    set capacity(value) {
+        const next = Number.isFinite(value) ? Math.max(1, Math.floor(value)) : 256;
+        if (next === this._capacity)
+            return;
+        this._capacity = next;
+        this._batch?.resize(next);
+    }
+    overflow = 'recycle-oldest';
+    destroyMode = 'clear';
+    width = 1;
+    height = 1;
+    startScale = 1;
+    endScale = 1;
+    startColor = 0xffffff;
+    endColor = 0xffffff;
+    startAlpha = 1;
+    endAlpha = 0;
+    _texture = '';
+    get texture() {
+        return this._texture;
+    }
+    set texture(value) {
+        const next = typeof value === 'string' ? value : '';
+        if (next === this._texture)
+            return;
+        this._texture = next;
+        this._batch?.setTexture(next, this.pixelArt);
+    }
+    _pixelArt = false;
+    get pixelArt() {
+        return this._pixelArt;
+    }
+    set pixelArt(value) {
+        const next = value === true;
+        if (next === this._pixelArt)
+            return;
+        this._pixelArt = next;
+        this._batch?.setTexture(this.texture, next);
+    }
+    _blend = 'normal';
+    get blend() {
+        return this._blend;
+    }
+    set blend(value) {
+        const next = value === 'additive' ? 'additive' : 'normal';
+        if (next === this._blend)
+            return;
+        this._blend = next;
+        this._batch?.setBlend(next);
+    }
+    _layer = 0;
+    get layer() {
+        return this._layer;
+    }
+    set layer(value) {
+        const next = Number.isFinite(value) ? value : 0;
+        if (next === this._layer)
+            return;
+        this._layer = next;
+        this._batch?.setLayer(next);
+        this._batch?.sync(this.renderContext());
+    }
+    _batch;
+    _unsubscribeRenderSync;
+    _emissionRemainder = 0;
+    _destroyed = false;
+    get active() {
+        return this._batch?.active ?? 0;
+    }
+    onReady() {
+        const capacity = Number.isFinite(this.capacity) ? Math.max(1, Math.floor(this.capacity)) : 256;
+        this._batch = new ParticleBatch({
+            capacity,
+            seed: this.seed,
+            layer: this.layer,
+            blend: this.blend,
+            assets: this.game.assets,
+        });
+        this._batch.setTexture(this.texture, this.pixelArt);
+        this.game.scene.add(this._batch.mesh);
+        this._batch.sync(this.renderContext());
+        this._unsubscribeRenderSync = this.game.onUpdate(() => this._batch?.sync(this.renderContext()));
+        this._emissionRemainder = 0;
+        this._destroyed = false;
+    }
+    onUpdate(dt) {
+        if (this._destroyed)
+            return;
+        this._batch?.advance(dt, this.renderContext());
+        if (!this.emitting)
+            return;
+        const rate = Number.isFinite(this.rate) ? Math.max(0, this.rate) : 0;
+        if (rate === 0)
+            return;
+        this._emissionRemainder += rate * dt;
+        const count = Math.floor(this._emissionRemainder);
+        if (count === 0)
+            return;
+        this._emissionRemainder -= count;
+        this.emit(count);
+    }
+    /** Emits a burst immediately and returns how many particles from it remain active. */
+    emit(value) {
+        if (this._destroyed || !this._batch)
+            return 0;
+        const accepted = this._batch.emit(value, this.overflow, this.spawnConfig());
+        this._batch.sync(this.renderContext());
+        return accepted;
+    }
+    ySortEntries() {
+        return this._batch?.ySortEntries() ?? [];
+    }
+    setSortZ(z) {
+        this._batch?.setSortZ(z);
+    }
+    setSortZs(values) {
+        this._batch?.setSortZs(values);
+    }
+    inspectState() {
+        return { active: this.active, capacity: this.capacity, emitting: this.emitting };
+    }
+    onDestroy() {
+        this._destroyed = true;
+        this._unsubscribeRenderSync?.();
+        this._unsubscribeRenderSync = undefined;
+        const batch = this._batch;
+        this._batch = undefined;
+        if (!batch)
+            return;
+        if (this.destroyMode === 'drain' && batch.active > 0) {
+            batch.detach(this.renderContext());
+            sceneDrainsOf(this.game).add(batch);
+        }
+        else {
+            batch.dispose();
+        }
+    }
+    renderContext() {
+        return {
+            owner: [this.entity.position.x, this.entity.position.y],
+            projection: this.game.projection,
+        };
+    }
+    spawnConfig() {
+        return {
+            origin: [this.entity.position.x, this.entity.position.y],
+            positionSpread: this.positionSpread,
+            velocity: this.velocity,
+            velocitySpread: this.velocitySpread,
+            gravity: this.gravity,
+            space: this.space,
+            lifetime: this.lifetime,
+            width: this.width,
+            height: this.height,
+            startScale: this.startScale,
+            endScale: this.endScale,
+            startColor: this.startColor,
+            endColor: this.endColor,
+            startAlpha: this.startAlpha,
+            endAlpha: this.endAlpha,
+        };
+    }
+}

package/dist/game.js

@@ -15,8 +15,9 @@ import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric, unprojectIsometric } from './projection.js';
-import { isYSortParticipant, ySortZ } from './render-sort.js';
+import { isYSortBatchParticipant, isYSortParticipant, ySortZ, } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
+import { sceneDrainsOf } from './scene-drains.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { anchoredPiecesOf, GameUi } from './ui.js';
@@ -202,6 +203,8 @@ export class Game {
         // Pointer holds that array by reference, so it must never be reassigned.
         for (const entity of [...this.entities])
             entity.destroy();
+        // Drains transferred by the destruction cascade above are scene-scoped too.
+        sceneDrainsOf(this).clear();
         this.registry = null;
         this.renderSort = null;
         this.sceneProjection = null;
@@ -394,6 +397,7 @@ export class Game {
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        sceneDrainsOf(this).clear();
         // After the entities: their clones go with the cascade above, the
         // cached bases go here, exactly once (ADR 0019).
         this.assets.dispose();
@@ -492,6 +496,9 @@ export class Game {
      */
     simulateStep() {
         advanceGameTime(this.time);
+        // Existing drains advance before entity updates, so one detached during
+        // this step begins on the next Simulation Step (ADR 0022).
+        sceneDrainsOf(this).advance(SIMULATION_STEP);
         for (const entity of [...this.entities]) {
             const schedule = this.componentUpdateSchedule(entity);
             if (!schedule)
@@ -534,23 +541,37 @@ export class Game {
     };
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     applyYSort() {
-        const participants = [];
+        const singles = [];
+        const batches = [];
         const entries = [];
         for (const entity of this.entities) {
             for (const component of entity.components) {
-                if (isYSortParticipant(component)) {
-                    participants.push(component);
+                if (isYSortBatchParticipant(component)) {
+                    const batchEntries = component.ySortEntries();
+                    batches.push({ participant: component, start: entries.length, count: batchEntries.length });
+                    entries.push(...batchEntries);
+                }
+                else if (isYSortParticipant(component)) {
+                    singles.push({ participant: component, index: entries.length });
                     entries.push({ layer: component.layer, y: entity.node.position.y });
                 }
             }
         }
+        for (const participant of sceneDrainsOf(this).participants()) {
+            const batchEntries = participant.ySortEntries();
+            batches.push({ participant, start: entries.length, count: batchEntries.length });
+            entries.push(...batchEntries);
+        }
         const z = ySortZ(entries);
-        for (const [index, participant] of participants.entries()) {
+        for (const { participant, index } of singles) {
             const sortZ = z[index];
             if (sortZ === undefined)
                 throw new Error(`ySortZ returned no z for y-sort participant ${index}`);
             participant.setSortZ(sortZ);
         }
+        for (const { participant, start, count } of batches) {
+            participant.setSortZs(z.slice(start, start + count));
+        }
     }
     renderSurface() {
         if (this.sceneProjection === 'isometric') {

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions
 export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
-export { isYSortParticipant, ySortZ } from './render-sort.js';
-export type { YSortEntry, YSortParticipant } from './render-sort.js';
+export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
+export type { YSortBatchParticipant, YSortEntry, YSortParticipant } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 export type { ProjectedPoint } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
@@ -44,6 +44,8 @@ export type { StatValue } from './stats.js';
 export { GameUi } from './ui.js';
 export type { AnchoredPieceHandle, AttachOptions } from './anchored-pieces.js';
 export { Sprite } from './components/sprite.js';
+export { ParticleEmitter } from './components/particle-emitter.js';
+export type { ParticleBlend, ParticleDestroyMode, ParticleOverflow, ParticleSpace, ParticleVector, } from './components/particle-emitter.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';
 export { DynamicBody } from './components/dynamic-body.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { Game } from './game.js';
 export { AssetLoader } from './assets/asset-loader.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
-export { isYSortParticipant, ySortZ } from './render-sort.js';
+export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
@@ -21,6 +21,7 @@ export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';
+export { ParticleEmitter } from './components/particle-emitter.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';
 export { DynamicBody } from './components/dynamic-body.js';

package/dist/particle-batch.d.ts

@@ -0,0 +1,54 @@
+import * as THREE from 'three';
+import type { AssetLoader } from './assets/asset-loader.js';
+import type { ParticleBlend, ParticleOverflow } from './components/particle-emitter.js';
+import { type ParticleSpawn } from './particle-pool.js';
+import type { YSortEntry } from './render-sort.js';
+import type { SceneDrain } from './scene-drains.js';
+export type { ParticleSpawn } from './particle-pool.js';
+export interface ParticleRenderContext {
+    owner: readonly [number, number];
+    projection: 'isometric' | null;
+}
+interface ParticleBatchOptions {
+    capacity: number;
+    seed: number;
+    layer: number;
+    blend: ParticleBlend;
+    assets: AssetLoader;
+}
+/** Fixed Three resources around one dense CPU particle pool. */
+export declare class ParticleBatch implements SceneDrain {
+    readonly material: THREE.MeshBasicMaterial;
+    readonly mesh: THREE.Mesh<THREE.BufferGeometry, THREE.MeshBasicMaterial>;
+    private readonly pool;
+    private readonly assets;
+    private _layer;
+    private textureRevision;
+    private drainProjection;
+    private disposed;
+    constructor({ capacity, seed, layer, blend, assets }: ParticleBatchOptions);
+    get active(): number;
+    get layer(): number;
+    setSeed(seed: number): void;
+    setLayer(layer: number): void;
+    setBlend(blend: ParticleBlend): void;
+    setTexture(uri: string, pixelArt: boolean): void;
+    resize(capacity: number): void;
+    emit(value: number, overflow: ParticleOverflow, spawn: ParticleSpawn): number;
+    detach(context: ParticleRenderContext): void;
+    advanceDrain(dt: number): boolean;
+    advance(dt: number, context: ParticleRenderContext): void;
+    sync(context: ParticleRenderContext): void;
+    ySortEntries(): readonly YSortEntry[];
+    setSortZ(z: number): void;
+    setSortZs(values: readonly number[]): void;
+    dispose(): void;
+    private settleTexture;
+    private syncSlot;
+    private writeColor;
+    private writeSortZ;
+    private sortEntrySlots;
+    private sortIndices;
+    private insertIndex;
+    private before;
+}

package/dist/particle-batch.js

@@ -0,0 +1,269 @@
+import * as THREE from 'three';
+import { reportRejection } from './report-rejection.js';
+import { ParticlePool, particleValueAt, } from './particle-pool.js';
+import { projectIsometric } from './projection.js';
+import { refreshParticleSortBounds } from './particle-sort-bounds.js';
+function createGeometry(capacity) {
+    const geometry = new THREE.BufferGeometry();
+    const uvs = new Float32Array(capacity * 8);
+    const indices = new Uint32Array(capacity * 6);
+    for (let slot = 0; slot < capacity; slot += 1) {
+        uvs.set([0, 0, 1, 0, 1, 1, 0, 1], slot * 8);
+        const vertex = slot * 4;
+        indices.set([vertex, vertex + 1, vertex + 2, vertex, vertex + 2, vertex + 3], slot * 6);
+    }
+    geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(capacity * 12), 3));
+    geometry.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
+    geometry.setAttribute('color', new THREE.BufferAttribute(new Float32Array(capacity * 16), 4));
+    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    geometry.setDrawRange(0, 0);
+    return geometry;
+}
+function lerp(start, end, progress) {
+    return start + (end - start) * progress;
+}
+/** Fixed Three resources around one dense CPU particle pool. */
+export class ParticleBatch {
+    material;
+    mesh;
+    pool;
+    assets;
+    _layer;
+    textureRevision = 0;
+    drainProjection = null;
+    disposed = false;
+    constructor({ capacity, seed, layer, blend, assets }) {
+        this.pool = new ParticlePool(capacity, seed);
+        this.assets = assets;
+        this._layer = Number.isFinite(layer) ? layer : 0;
+        this.material = new THREE.MeshBasicMaterial({
+            color: 0xffffff,
+            transparent: true,
+            vertexColors: true,
+            depthTest: true,
+            depthWrite: true,
+            blending: blend === 'additive' ? THREE.AdditiveBlending : THREE.NormalBlending,
+        });
+        this.mesh = new THREE.Mesh(createGeometry(capacity), this.material);
+        this.mesh.frustumCulled = false;
+    }
+    get active() {
+        return this.pool.active;
+    }
+    get layer() {
+        return this._layer;
+    }
+    setSeed(seed) {
+        this.pool.setSeed(seed);
+    }
+    setLayer(layer) {
+        this._layer = Number.isFinite(layer) ? layer : 0;
+    }
+    setBlend(blend) {
+        this.material.blending = blend === 'additive' ? THREE.AdditiveBlending : THREE.NormalBlending;
+        this.material.needsUpdate = true;
+    }
+    setTexture(uri, pixelArt) {
+        this.textureRevision += 1;
+        const revision = this.textureRevision;
+        this.material.map?.dispose();
+        this.material.map = null;
+        if (!uri || this.disposed) {
+            this.material.needsUpdate = true;
+            return;
+        }
+        const { texture, settled } = this.assets.texture(uri);
+        const filter = pixelArt ? THREE.NearestFilter : THREE.LinearFilter;
+        texture.minFilter = filter;
+        texture.magFilter = filter;
+        this.material.map = texture;
+        this.material.needsUpdate = true;
+        reportRejection(settled.then((outcome) => this.settleTexture(outcome, revision, texture)), 'particle texture settle');
+    }
+    resize(capacity) {
+        if (this.disposed || !this.pool.resize(capacity))
+            return;
+        const previous = this.mesh.geometry;
+        this.mesh.geometry = createGeometry(capacity);
+        previous.dispose();
+    }
+    emit(value, overflow, spawn) {
+        if (this.disposed)
+            return 0;
+        return this.pool.emit(value, overflow, spawn);
+    }
+    detach(context) {
+        this.pool.detach(context.owner);
+        this.drainProjection = context.projection;
+        this.sync({ owner: [0, 0], projection: this.drainProjection });
+    }
+    advanceDrain(dt) {
+        this.advance(dt, { owner: [0, 0], projection: this.drainProjection });
+        return this.active > 0;
+    }
+    advance(dt, context) {
+        this.pool.advance(dt);
+        this.sync(context);
+    }
+    sync(context) {
+        const positions = this.mesh.geometry.getAttribute('position');
+        const colors = this.mesh.geometry.getAttribute('color');
+        for (let slot = 0; slot < this.active; slot += 1) {
+            this.syncSlot({ positions, colors, slot, context });
+        }
+        refreshParticleSortBounds(this.mesh.geometry, this.active, this._layer * 0.01);
+        positions.needsUpdate = true;
+        colors.needsUpdate = true;
+        this.sortIndices();
+        this.mesh.geometry.setDrawRange(0, this.active * 6);
+    }
+    ySortEntries() {
+        this.sortEntrySlots();
+        const { entrySlots, renderY } = this.pool.arrays;
+        return Array.from({ length: this.active }, (_, rank) => {
+            const slot = particleValueAt(entrySlots, rank);
+            return { layer: this._layer, y: particleValueAt(renderY, slot) };
+        });
+    }
+    setSortZ(z) {
+        const positions = this.mesh.geometry.getAttribute('position');
+        for (let slot = 0; slot < this.active; slot += 1)
+            this.writeSortZ(positions, slot, z);
+        refreshParticleSortBounds(this.mesh.geometry, this.active, this._layer * 0.01);
+        positions.needsUpdate = true;
+        this.sortIndices();
+    }
+    setSortZs(values) {
+        const positions = this.mesh.geometry.getAttribute('position');
+        for (let rank = 0; rank < this.active; rank += 1) {
+            const slot = particleValueAt(this.pool.arrays.entrySlots, rank);
+            const z = values[rank];
+            if (z === undefined)
+                throw new Error(`ParticleBatch has no y-sort value for rank ${rank}`);
+            this.writeSortZ(positions, slot, z);
+        }
+        refreshParticleSortBounds(this.mesh.geometry, this.active, this._layer * 0.01);
+        positions.needsUpdate = true;
+        this.sortIndices();
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.textureRevision += 1;
+        this.pool.clear();
+        this.mesh.removeFromParent();
+        this.mesh.geometry.dispose();
+        this.material.map?.dispose();
+        this.material.map = null;
+        this.material.dispose();
+    }
+    settleTexture(outcome, revision, texture) {
+        if (outcome !== 'failed' || this.disposed || revision !== this.textureRevision
+            || this.material.map !== texture)
+            return;
+        this.material.map = null;
+        texture.dispose();
+        this.material.needsUpdate = true;
+    }
+    syncSlot({ positions, colors, slot, context }) {
+        const arrays = this.pool.arrays;
+        const local = arrays.local[slot] === 1;
+        const logicalX = particleValueAt(arrays.x, slot) + (local ? context.owner[0] : 0);
+        const logicalY = particleValueAt(arrays.y, slot) + (local ? context.owner[1] : 0);
+        const center = context.projection === 'isometric'
+            ? projectIsometric(logicalX, logicalY)
+            : { x: logicalX, y: logicalY };
+        const progress = Math.min(1, Math.max(0, particleValueAt(arrays.age, slot) / particleValueAt(arrays.lifetime, slot)));
+        const scale = lerp(particleValueAt(arrays.startScale, slot), particleValueAt(arrays.endScale, slot), progress);
+        const halfWidth = particleValueAt(arrays.width, slot) * scale / 2;
+        const halfHeight = particleValueAt(arrays.height, slot) * scale / 2;
+        const vertex = slot * 4;
+        const z = this._layer * 0.01;
+        arrays.renderY[slot] = center.y;
+        arrays.sortZ[slot] = z;
+        positions.setXYZ(vertex, center.x - halfWidth, center.y - halfHeight, z);
+        positions.setXYZ(vertex + 1, center.x + halfWidth, center.y - halfHeight, z);
+        positions.setXYZ(vertex + 2, center.x + halfWidth, center.y + halfHeight, z);
+        positions.setXYZ(vertex + 3, center.x - halfWidth, center.y + halfHeight, z);
+        this.writeColor({ colors, vertex, slot, progress, arrays });
+    }
+    writeColor({ colors, vertex, slot, progress, arrays }) {
+        const start = particleValueAt(arrays.startColor, slot);
+        const end = particleValueAt(arrays.endColor, slot);
+        const red = lerp((start >>> 16) & 0xff, (end >>> 16) & 0xff, progress) / 255;
+        const green = lerp((start >>> 8) & 0xff, (end >>> 8) & 0xff, progress) / 255;
+        const blue = lerp(start & 0xff, end & 0xff, progress) / 255;
+        const opacity = lerp(particleValueAt(arrays.startAlpha, slot), particleValueAt(arrays.endAlpha, slot), progress);
+        for (let corner = 0; corner < 4; corner += 1) {
+            colors.setXYZW(vertex + corner, red, green, blue, opacity);
+        }
+    }
+    writeSortZ(positions, slot, z) {
+        this.pool.arrays.sortZ[slot] = z;
+        const vertex = slot * 4;
+        for (let corner = 0; corner < 4; corner += 1)
+            positions.setZ(vertex + corner, z);
+    }
+    sortEntrySlots() {
+        const { entrySlots, ordinal } = this.pool.arrays;
+        for (let slot = 0; slot < this.active; slot += 1)
+            entrySlots[slot] = slot;
+        for (let rank = 1; rank < this.active; rank += 1) {
+            const candidate = particleValueAt(entrySlots, rank);
+            let cursor = rank - 1;
+            while (cursor >= 0) {
+                const previous = particleValueAt(entrySlots, cursor);
+                if (particleValueAt(ordinal, candidate) >= particleValueAt(ordinal, previous))
+                    break;
+                entrySlots[cursor + 1] = previous;
+                cursor -= 1;
+            }
+            entrySlots[cursor + 1] = candidate;
+        }
+    }
+    sortIndices() {
+        const { order } = this.pool.arrays;
+        for (let slot = 0; slot < this.active; slot += 1)
+            order[slot] = slot;
+        for (let rank = 1; rank < this.active; rank += 1)
+            this.insertIndex(rank, order);
+        const index = this.mesh.geometry.index;
+        if (!index)
+            throw new Error('ParticleBatch geometry has no index');
+        for (let rank = 0; rank < this.active; rank += 1) {
+            const vertex = particleValueAt(order, rank) * 4;
+            index.setX(rank * 6, vertex);
+            index.setX(rank * 6 + 1, vertex + 1);
+            index.setX(rank * 6 + 2, vertex + 2);
+            index.setX(rank * 6 + 3, vertex);
+            index.setX(rank * 6 + 4, vertex + 2);
+            index.setX(rank * 6 + 5, vertex + 3);
+        }
+        index.needsUpdate = true;
+    }
+    insertIndex(rank, order) {
+        const candidate = particleValueAt(order, rank);
+        let cursor = rank - 1;
+        while (cursor >= 0) {
+            const previous = particleValueAt(order, cursor);
+            if (!this.before(candidate, previous))
+                break;
+            order[cursor + 1] = previous;
+            cursor -= 1;
+        }
+        order[cursor + 1] = candidate;
+    }
+    before(left, right) {
+        const { sortZ, renderY, ordinal } = this.pool.arrays;
+        const leftZ = particleValueAt(sortZ, left);
+        const rightZ = particleValueAt(sortZ, right);
+        if (leftZ !== rightZ)
+            return leftZ < rightZ;
+        const leftY = particleValueAt(renderY, left);
+        const rightY = particleValueAt(renderY, right);
+        if (leftY !== rightY)
+            return leftY > rightY;
+        return particleValueAt(ordinal, left) < particleValueAt(ordinal, right);
+    }
+}

package/dist/particle-pool.d.ts

@@ -0,0 +1,66 @@
+import type { ParticleOverflow, ParticleSpace } from './components/particle-emitter.js';
+export interface ParticleSpawn {
+    origin: readonly number[];
+    positionSpread: unknown;
+    velocity: unknown;
+    velocitySpread: unknown;
+    gravity: unknown;
+    space: ParticleSpace;
+    lifetime: number;
+    width: number;
+    height: number;
+    startScale: number;
+    endScale: number;
+    startColor: number;
+    endColor: number;
+    startAlpha: number;
+    endAlpha: number;
+}
+export interface ParticleArrays {
+    x: Float64Array;
+    y: Float64Array;
+    vx: Float64Array;
+    vy: Float64Array;
+    gx: Float64Array;
+    gy: Float64Array;
+    age: Float64Array;
+    lifetime: Float64Array;
+    width: Float64Array;
+    height: Float64Array;
+    startScale: Float64Array;
+    endScale: Float64Array;
+    startColor: Uint32Array;
+    endColor: Uint32Array;
+    startAlpha: Float64Array;
+    endAlpha: Float64Array;
+    local: Uint8Array;
+    ordinal: Float64Array;
+    renderY: Float64Array;
+    sortZ: Float64Array;
+    order: Uint32Array;
+    entrySlots: Uint32Array;
+}
+export declare function particleValueAt(values: ArrayLike<number>, index: number): number;
+/** Dense, fixed-capacity CPU state and deterministic sampling for one particle batch. */
+export declare class ParticlePool {
+    private capacity;
+    active: number;
+    arrays: ParticleArrays;
+    private rngState;
+    private nextOrdinal;
+    constructor(capacity: number, seed: number);
+    setSeed(seed: number): void;
+    resize(capacity: number): boolean;
+    clear(): void;
+    emit(value: number, overflow: ParticleOverflow, spawn: ParticleSpawn): number;
+    detach(owner: readonly [number, number]): void;
+    advance(dt: number): void;
+    private advanceSlot;
+    private random;
+    private spawn;
+    private writeSpawnSnapshot;
+    private randomized;
+    private recycleFor;
+    private removeOldest;
+    private remove;
+}

package/dist/particle-pool.js

@@ -0,0 +1,204 @@
+function particleArrays(capacity) {
+    return {
+        x: new Float64Array(capacity),
+        y: new Float64Array(capacity),
+        vx: new Float64Array(capacity),
+        vy: new Float64Array(capacity),
+        gx: new Float64Array(capacity),
+        gy: new Float64Array(capacity),
+        age: new Float64Array(capacity),
+        lifetime: new Float64Array(capacity),
+        width: new Float64Array(capacity),
+        height: new Float64Array(capacity),
+        startScale: new Float64Array(capacity),
+        endScale: new Float64Array(capacity),
+        startColor: new Uint32Array(capacity),
+        endColor: new Uint32Array(capacity),
+        startAlpha: new Float64Array(capacity),
+        endAlpha: new Float64Array(capacity),
+        local: new Uint8Array(capacity),
+        ordinal: new Float64Array(capacity),
+        renderY: new Float64Array(capacity),
+        sortZ: new Float64Array(capacity),
+        order: new Uint32Array(capacity),
+        entrySlots: new Uint32Array(capacity),
+    };
+}
+export function particleValueAt(values, index) {
+    const value = values[index];
+    if (value === undefined)
+        throw new Error(`Particle slot ${index} is outside its capacity`);
+    return value;
+}
+function finiteAxis(value, index) {
+    if (!Array.isArray(value))
+        return 0;
+    const axis = value[index];
+    return typeof axis === 'number' && Number.isFinite(axis) ? axis : 0;
+}
+function finiteNonNegative(value, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(0, value);
+}
+function alpha(value, fallback) {
+    return Math.min(1, finiteNonNegative(value, fallback));
+}
+function color(value) {
+    return Number.isFinite(value) ? Math.min(0xffffff, Math.max(0, Math.trunc(value))) : 0xffffff;
+}
+function normalizedSeed(value) {
+    return Number.isFinite(value) ? Math.trunc(value) >>> 0 : 1;
+}
+function stateArrays(arrays) {
+    return [
+        arrays.x, arrays.y, arrays.vx, arrays.vy, arrays.gx, arrays.gy,
+        arrays.age, arrays.lifetime, arrays.width, arrays.height,
+        arrays.startScale, arrays.endScale, arrays.startColor, arrays.endColor,
+        arrays.startAlpha, arrays.endAlpha, arrays.local, arrays.ordinal,
+        arrays.renderY, arrays.sortZ,
+    ];
+}
+/** Dense, fixed-capacity CPU state and deterministic sampling for one particle batch. */
+export class ParticlePool {
+    capacity;
+    active = 0;
+    arrays;
+    rngState;
+    nextOrdinal = 0;
+    constructor(capacity, seed) {
+        this.capacity = capacity;
+        this.arrays = particleArrays(capacity);
+        this.rngState = normalizedSeed(seed);
+    }
+    setSeed(seed) {
+        this.rngState = normalizedSeed(seed);
+    }
+    resize(capacity) {
+        if (capacity === this.capacity)
+            return false;
+        this.capacity = capacity;
+        this.arrays = particleArrays(capacity);
+        this.active = 0;
+        return true;
+    }
+    clear() {
+        this.active = 0;
+    }
+    emit(value, overflow, spawn) {
+        if (!Number.isFinite(spawn.lifetime) || spawn.lifetime <= 0)
+            return 0;
+        const count = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+        const accepted = overflow === 'drop-new'
+            ? Math.min(count, this.capacity - this.active)
+            : Math.min(count, this.capacity);
+        if (overflow !== 'drop-new')
+            this.recycleFor(accepted);
+        for (let index = 0; index < accepted; index += 1)
+            this.spawn(spawn);
+        return accepted;
+    }
+    detach(owner) {
+        const { local, x, y } = this.arrays;
+        for (let slot = 0; slot < this.active; slot += 1) {
+            if (local[slot] !== 1)
+                continue;
+            x[slot] = particleValueAt(x, slot) + owner[0];
+            y[slot] = particleValueAt(y, slot) + owner[1];
+            local[slot] = 0;
+        }
+    }
+    advance(dt) {
+        let slot = 0;
+        while (slot < this.active) {
+            const age = this.advanceSlot(slot, dt);
+            if (age >= particleValueAt(this.arrays.lifetime, slot))
+                this.remove(slot);
+            else
+                slot += 1;
+        }
+    }
+    advanceSlot(slot, dt) {
+        const { vx, vy, gx, gy, x, y, age } = this.arrays;
+        const nextVx = particleValueAt(vx, slot) + particleValueAt(gx, slot) * dt;
+        const nextVy = particleValueAt(vy, slot) + particleValueAt(gy, slot) * dt;
+        const nextAge = particleValueAt(age, slot) + dt;
+        vx[slot] = nextVx;
+        vy[slot] = nextVy;
+        x[slot] = particleValueAt(x, slot) + nextVx * dt;
+        y[slot] = particleValueAt(y, slot) + nextVy * dt;
+        age[slot] = nextAge;
+        return nextAge;
+    }
+    random() {
+        this.rngState = (this.rngState + 0x6d2b79f5) >>> 0;
+        let value = this.rngState;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    }
+    spawn(config) {
+        const positionX = this.random();
+        const positionY = this.random();
+        const velocityX = this.random();
+        const velocityY = this.random();
+        const slot = this.active;
+        const local = config.space === 'local';
+        const { x, y, vx, vy, gx, gy } = this.arrays;
+        x[slot] = (local ? 0 : finiteAxis(config.origin, 0))
+            + this.randomized(finiteAxis(config.positionSpread, 0), positionX);
+        y[slot] = (local ? 0 : finiteAxis(config.origin, 1))
+            + this.randomized(finiteAxis(config.positionSpread, 1), positionY);
+        vx[slot] = finiteAxis(config.velocity, 0)
+            + this.randomized(finiteAxis(config.velocitySpread, 0), velocityX);
+        vy[slot] = finiteAxis(config.velocity, 1)
+            + this.randomized(finiteAxis(config.velocitySpread, 1), velocityY);
+        gx[slot] = finiteAxis(config.gravity, 0);
+        gy[slot] = finiteAxis(config.gravity, 1);
+        this.writeSpawnSnapshot(slot, config, local);
+        this.active += 1;
+    }
+    writeSpawnSnapshot(slot, config, local) {
+        const arrays = this.arrays;
+        arrays.age[slot] = 0;
+        arrays.lifetime[slot] = config.lifetime;
+        arrays.width[slot] = finiteNonNegative(config.width, 1);
+        arrays.height[slot] = finiteNonNegative(config.height, 1);
+        arrays.startScale[slot] = finiteNonNegative(config.startScale, 1);
+        arrays.endScale[slot] = finiteNonNegative(config.endScale, 1);
+        arrays.startColor[slot] = color(config.startColor);
+        arrays.endColor[slot] = color(config.endColor);
+        arrays.startAlpha[slot] = alpha(config.startAlpha, 1);
+        arrays.endAlpha[slot] = alpha(config.endAlpha, 0);
+        arrays.local[slot] = local ? 1 : 0;
+        arrays.ordinal[slot] = this.nextOrdinal;
+        this.nextOrdinal += 1;
+    }
+    randomized(spread, sample) {
+        return (sample * 2 - 1) * Math.max(0, spread);
+    }
+    recycleFor(accepted) {
+        const replaced = Math.max(0, this.active + accepted - this.capacity);
+        for (let index = 0; index < replaced; index += 1)
+            this.removeOldest();
+    }
+    removeOldest() {
+        if (this.active === 0)
+            return;
+        let oldest = 0;
+        for (let slot = 1; slot < this.active; slot += 1) {
+            if (particleValueAt(this.arrays.ordinal, slot) < particleValueAt(this.arrays.ordinal, oldest)) {
+                oldest = slot;
+            }
+        }
+        this.remove(oldest);
+    }
+    remove(slot) {
+        const last = this.active - 1;
+        if (slot !== last) {
+            for (const array of stateArrays(this.arrays))
+                array[slot] = particleValueAt(array, last);
+        }
+        this.active = last;
+    }
+}

package/dist/particle-sort-bounds.d.ts

@@ -0,0 +1,3 @@
+import * as THREE from 'three';
+/** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
+export declare function refreshParticleSortBounds(geometry: THREE.BufferGeometry, active: number, emptyZ: number): void;

package/dist/particle-sort-bounds.js

@@ -0,0 +1,34 @@
+import * as THREE from 'three';
+/** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
+export function refreshParticleSortBounds(geometry, active, emptyZ) {
+    const positions = geometry.getAttribute('position');
+    const sphere = geometry.boundingSphere ?? new THREE.Sphere();
+    geometry.boundingSphere = sphere;
+    if (active === 0) {
+        sphere.center.set(0, 0, emptyZ);
+        sphere.radius = 0;
+        return;
+    }
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let minZ = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let maxZ = Number.NEGATIVE_INFINITY;
+    for (let vertex = 0; vertex < active * 4; vertex += 1) {
+        const x = positions.getX(vertex);
+        const y = positions.getY(vertex);
+        const z = positions.getZ(vertex);
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        minZ = Math.min(minZ, z);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+        maxZ = Math.max(maxZ, z);
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const depth = maxZ - minZ;
+    sphere.center.set(minX + width / 2, minY + height / 2, minZ + depth / 2);
+    sphere.radius = Math.sqrt(width * width + height * height + depth * depth) / 2;
+}

package/dist/render-sort.d.ts

@@ -18,7 +18,13 @@ export interface YSortParticipant {
     /** Y-sort pass hook: overrides the layer-derived z for this frame. */
     setSortZ(z: number): void;
 }
+/** A single batched renderable that contributes one global y-sort entry per item. */
+export interface YSortBatchParticipant extends YSortParticipant {
+    ySortEntries(): readonly YSortEntry[];
+    setSortZs(values: readonly number[]): void;
+}
 export declare function isYSortParticipant(value: unknown): value is YSortParticipant;
+export declare function isYSortBatchParticipant(value: unknown): value is YSortBatchParticipant;
 /**
  * Z per entry under y-sort. Each layer keeps its 0.01 band; within a band,
  * lower Y gets a higher z (renders in front), and exact Y ties keep input

package/dist/render-sort.js

@@ -4,6 +4,11 @@ export function isYSortParticipant(value) {
         typeof value.layer === 'number' &&
         typeof value.setSortZ === 'function');
 }
+export function isYSortBatchParticipant(value) {
+    return (isYSortParticipant(value) &&
+        typeof value.ySortEntries === 'function' &&
+        typeof value.setSortZs === 'function');
+}
 /** The Y of the entry at `index`, which `ySortZ` only reads for indices it grouped from `entries`. */
 function entryY(entries, index) {
     const entry = entries[index];

package/dist/scene-drains.d.ts

@@ -0,0 +1,18 @@
+import type { Game } from './game.js';
+import type { YSortBatchParticipant } from './render-sort.js';
+/** A detached render batch that advances only on Simulation Steps. */
+export interface SceneDrain extends YSortBatchParticipant {
+    readonly active: number;
+    advanceDrain(dt: number): boolean;
+    dispose(): void;
+}
+declare class SceneDrains {
+    private readonly drains;
+    add(drain: SceneDrain): void;
+    advance(dt: number): void;
+    participants(): readonly YSortBatchParticipant[];
+    clear(): void;
+}
+/** Internal scene-owned drain registry shared by Game and engine render components. */
+export declare function sceneDrainsOf(game: Game): SceneDrains;
+export {};

package/dist/scene-drains.js

@@ -0,0 +1,36 @@
+class SceneDrains {
+    drains = [];
+    add(drain) {
+        this.drains.push(drain);
+    }
+    advance(dt) {
+        let index = 0;
+        while (index < this.drains.length) {
+            const drain = this.drains[index];
+            if (drain?.advanceDrain(dt))
+                index += 1;
+            else {
+                drain?.dispose();
+                this.drains.splice(index, 1);
+            }
+        }
+    }
+    participants() {
+        return this.drains;
+    }
+    clear() {
+        for (const drain of this.drains)
+            drain.dispose();
+        this.drains.length = 0;
+    }
+}
+const managers = new WeakMap();
+/** Internal scene-owned drain registry shared by Game and engine render components. */
+export function sceneDrainsOf(game) {
+    const existing = managers.get(game);
+    if (existing)
+        return existing;
+    const created = new SceneDrains();
+    managers.set(game, created);
+    return created;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     }
   },
   "dependencies": {
-    "@types/three": "^0.185.1",
-    "three": "^0.185.1"
+    "@types/three": "^0.186.0",
+    "three": "^0.186.1"
   }
 }