@codexo/exojs-particles 0.15.2 → 0.16.0

package/README.md

@@ -13,8 +13,8 @@ This package requires `@codexo/exojs` as a peer dependency. Both must be the sam
 ## Core compatibility
 
 | `@codexo/exojs-particles` | `@codexo/exojs` |
-|---|---|
-| 0.12.x | 0.12.x |
+| ------------------------- | --------------- |
+| 0.12.x                    | 0.12.x          |
 
 ## Usage — side-effect-free root entry
 
@@ -25,7 +25,7 @@ import { Application } from '@codexo/exojs';
 import { ParticleSystem, particlesExtension } from '@codexo/exojs-particles';
 
 const app = new Application({
-    extensions: [particlesExtension],
+  extensions: [particlesExtension],
 });
 ```
 
@@ -47,7 +47,7 @@ const app = new Application({ extensions: [particlesExtension] });
 import { createParticlesExtension } from '@codexo/exojs-particles';
 
 const app = new Application({
-    extensions: [createParticlesExtension({ batchSize: 8192 })],
+  extensions: [createParticlesExtension({ batchSize: 8192 })],
 });
 ```
 
@@ -57,57 +57,35 @@ Pass any combination of descriptors:
 
 ```ts
 const app = new Application({
-    extensions: [particlesExtension],
+  extensions: [particlesExtension],
 });
 ```
 
-## `/register` convenience entry
-
-Importing `/register` registers the default `particlesExtension` descriptor in the global `ExtensionRegistry`. Subsequently created Applications that use global defaults will automatically receive the Particles extension. This is the only side-effectful entry in this package.
+## Minimal working example
 
 ```ts
-// Side effect: registers particlesExtension in the global ExtensionRegistry.
-import '@codexo/exojs-particles/register';
+import { Application, type RenderingContext, Scene } from '@codexo/exojs';
+import { Constant, ParticleSystem, particlesExtension, RateSpawn } from '@codexo/exojs-particles';
 
-// All named exports are re-exported from /register:
-import { ParticleSystem, particlesExtension } from '@codexo/exojs-particles/register';
-```
+const app = new Application({ extensions: [particlesExtension], canvas: { mount: document.body } });
 
-**Note:** `/register` does not use automatic discovery. It explicitly calls `ExtensionRegistry.register(particlesExtension)` at module evaluation time.
-
-## Minimal working example
+class DemoScene extends Scene {
+  private system!: ParticleSystem;
 
-```ts
-import { Application, Scene, Texture } from '@codexo/exojs';
-import {
-    ParticleSystem,
-    particlesExtension,
-    RateSpawn,
-    Constant,
-} from '@codexo/exojs-particles';
+  override async load(): Promise<void> {
+    const texture = await this.loader.load('/particle.png');
 
-const app = new Application({ extensions: [particlesExtension] });
-document.body.append(app.canvas);
+    this.system = new ParticleSystem(texture, { capacity: 1024 });
+    this.systems.add(this.system);
+    this.system.addSpawnModule(new RateSpawn({ rate: new Constant(120), lifetime: new Constant(2) }));
+  }
 
-class DemoScene extends Scene {
-    system!: ParticleSystem;
-
-    override async load(loader) {
-        await loader.load(Texture, { particle: '/particle.png' });
-    }
-
-    override create(loader) {
-        this.system = new ParticleSystem(loader.get(Texture, 'particle'), {
-            capacity: 1024,
-        });
-        this.system.addSpawnModule(
-            new RateSpawn({ rate: new Constant(120), lifetime: new Constant(2) }),
-        );
-        this.addChild(this.system);
-    }
+  override draw(context: RenderingContext): void {
+    context.render(this.system);
+  }
 }
 
-app.scenes.start(DemoScene);
+app.start(DemoScene);
 ```
 
 ## WebGL2 and WebGPU support

package/dist/esm/ParticleStorage.d.ts

@@ -0,0 +1,188 @@
+/**
+ * A two-component particle channel, one array per component.
+ *
+ * The arrays are the simulation's own storage rather than a copy: writing
+ * `position.x[i]` moves particle `i`. Their length is the system's capacity, so
+ * only indices below {@link ParticleBatch.count} carry meaning.
+ */
+export interface ParticleVectorChannel {
+    readonly x: Float32Array;
+    readonly y: Float32Array;
+}
+/** The rotation channel: current angle and the speed integrated into it each frame. */
+export interface ParticleRotationChannel {
+    readonly angle: Float32Array;
+    readonly speed: Float32Array;
+}
+/** The timing channel: seconds since spawn, and total seconds before expiry. */
+export interface ParticleTimingChannel {
+    readonly elapsed: Float32Array;
+    readonly lifetime: Float32Array;
+}
+/**
+ * The live particles of one system, addressed by semantic channel.
+ *
+ * This is the bulk surface an {@link UpdateModule} and a
+ * {@link ParticleRenderMode} operate on. Channels are named for what they mean;
+ * how they are packed - one array per component today, something else tomorrow -
+ * is the simulation's business and may change. A loop reads the channel it needs
+ * once and then indexes plain typed arrays, so naming costs nothing per particle.
+ *
+ * Indices `[0, count)` are the range worth visiting. A batch can contain dead
+ * slots, so a loop that must not touch them checks {@link isAlive}; a purely
+ * arithmetic pass over dead slots is harmless and can skip the check.
+ */
+export interface ParticleBatch {
+    /** Upper bound of the range that can hold live particles. */
+    readonly count: number;
+    /** Fixed number of slots this system can ever hold. */
+    readonly capacity: number;
+    readonly position: ParticleVectorChannel;
+    readonly velocity: ParticleVectorChannel;
+    readonly scale: ParticleVectorChannel;
+    readonly rotation: ParticleRotationChannel;
+    readonly timing: ParticleTimingChannel;
+    /** Packed `0xAABBGGRR` tint, one entry per slot. */
+    readonly color: Uint32Array;
+    /** Atlas frame selector, one entry per slot. Anything that is not a declared frame index shows frame 0. */
+    readonly frame: Uint16Array;
+    /** Whether the slot at `index` currently holds a live particle. */
+    isAlive(index: number): boolean;
+}
+/** Writable two-component channel of a single particle. */
+export interface ParticleVectorWriter {
+    x: number;
+    y: number;
+    set(x: number, y: number): void;
+}
+/**
+ * A single freshly emitted particle, addressed by name.
+ *
+ * Every field starts at its default - zero position, velocity, rotation and
+ * rotation speed, unit scale, opaque white, frame 0, lifetime 1 - so a spawner
+ * writes only what it varies.
+ *
+ * The writer is a cursor onto the emitting system, not a particle object: it is
+ * reused by the next {@link ParticleEmitter.emit} call and must not be kept.
+ * Read what you need before emitting again.
+ */
+export interface ParticleWriter {
+    readonly position: ParticleVectorWriter;
+    readonly velocity: ParticleVectorWriter;
+    readonly scale: ParticleVectorWriter;
+    rotation: number;
+    rotationSpeed: number;
+    /** Packed `0xAABBGGRR` tint. */
+    color: number;
+    /** Total seconds before this particle expires. */
+    lifetime: number;
+    /** Atlas frame index. Ignored by a system that declares no frames. */
+    frame: number;
+}
+/**
+ * The emitting face of a particle system: the only supported way to bring
+ * particles into existence.
+ *
+ * Emission is the one per-particle write that is true on every backend, because
+ * spawn values always originate on the CPU and are uploaded from there.
+ */
+export interface ParticleEmitter {
+    /** Emits one particle at its default values, or returns `null` when the system is at capacity. */
+    emit(): ParticleWriter | null;
+}
+/**
+ * The state of one particle at the moment it expired.
+ *
+ * A snapshot, not a view: it is copied out of the simulation when the particle
+ * dies and stays valid for the whole callback, whichever backend ran the
+ * simulation and whether or not the slot has already been reused. It carries no
+ * slot index for that reason - there is nothing to read back afterwards.
+ */
+export interface ParticleDeathContext {
+    readonly x: number;
+    readonly y: number;
+    readonly velocityX: number;
+    readonly velocityY: number;
+    readonly rotation: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    /** Packed `0xAABBGGRR` tint at death. */
+    readonly color: number;
+    /** Seconds the particle lived. */
+    readonly elapsed: number;
+    /** Lifetime the particle was spawned with. */
+    readonly lifetime: number;
+}
+/**
+ * The simulation's own storage: one typed array per channel, sized to capacity
+ * once and never reallocated.
+ *
+ * Implements {@link ParticleBatch}, which is the face handed to modules and
+ * render modes. Nothing outside the simulation gets the object itself.
+ * @internal
+ */
+export declare class ParticleStorage implements ParticleBatch {
+    readonly capacity: number;
+    readonly posX: Float32Array;
+    readonly posY: Float32Array;
+    readonly velX: Float32Array;
+    readonly velY: Float32Array;
+    readonly scaleX: Float32Array;
+    readonly scaleY: Float32Array;
+    readonly rotations: Float32Array;
+    readonly rotationSpeeds: Float32Array;
+    readonly color: Uint32Array;
+    readonly elapsed: Float32Array;
+    readonly lifetime: Float32Array;
+    readonly frame: Uint16Array;
+    readonly alive: Uint8Array;
+    readonly position: ParticleVectorChannel;
+    readonly velocity: ParticleVectorChannel;
+    readonly scale: ParticleVectorChannel;
+    readonly rotation: ParticleRotationChannel;
+    readonly timing: ParticleTimingChannel;
+    /** Upper bound of the range that can hold live particles. Owned by the system. */
+    count: number;
+    constructor(capacity: number);
+    isAlive(index: number): boolean;
+    /** Resets one slot to the spawn defaults every writer starts from. */
+    reset(slot: number): void;
+    /** Copies every channel of `from` onto `to`, for the CPU compaction pass. */
+    copySlot(from: number, to: number): void;
+    /** Snapshots one slot for a death callback. */
+    snapshot(slot: number): ParticleDeathContext;
+}
+/** Cursor implementation of {@link ParticleWriter}, rebound to a slot by each emit. @internal */
+export declare class ParticleSlotWriter implements ParticleWriter {
+    readonly position: ParticleVectorWriter;
+    readonly velocity: ParticleVectorWriter;
+    readonly scale: ParticleVectorWriter;
+    private readonly _storage;
+    private _slot;
+    constructor(storage: ParticleStorage);
+    /** The slot this cursor currently writes to. Used by the emitter to track what a spawner produced. @internal */
+    get slot(): number;
+    bind(slot: number): this;
+    /**
+     * Marks this writer as belonging to a finished emission. Development builds
+     * hand out one writer per emission and retire the previous one here, so
+     * writing through a stale writer fails loudly instead of silently filling
+     * whatever particle was emitted since.
+     * @internal
+     */
+    retire(): void;
+    private _retired;
+    /** Resolves the bound slot, refusing a writer a later emission has taken over. */
+    private _currentSlot;
+    get rotation(): number;
+    set rotation(value: number);
+    get rotationSpeed(): number;
+    set rotationSpeed(value: number);
+    get color(): number;
+    set color(value: number);
+    get lifetime(): number;
+    set lifetime(value: number);
+    get frame(): number;
+    set frame(value: number);
+}
+//# sourceMappingURL=ParticleStorage.d.ts.map

package/dist/esm/ParticleStorage.d.ts.map

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

package/dist/esm/ParticleStorage.js

@@ -0,0 +1,208 @@
+//#region src/ParticleStorage.ts
+/**
+* The simulation's own storage: one typed array per channel, sized to capacity
+* once and never reallocated.
+*
+* Implements {@link ParticleBatch}, which is the face handed to modules and
+* render modes. Nothing outside the simulation gets the object itself.
+* @internal
+*/
+var ParticleStorage = class {
+	capacity;
+	posX;
+	posY;
+	velX;
+	velY;
+	scaleX;
+	scaleY;
+	rotations;
+	rotationSpeeds;
+	color;
+	elapsed;
+	lifetime;
+	frame;
+	alive;
+	position;
+	velocity;
+	scale;
+	rotation;
+	timing;
+	/** Upper bound of the range that can hold live particles. Owned by the system. */
+	count = 0;
+	constructor(capacity) {
+		this.capacity = capacity;
+		this.posX = new Float32Array(capacity);
+		this.posY = new Float32Array(capacity);
+		this.velX = new Float32Array(capacity);
+		this.velY = new Float32Array(capacity);
+		this.scaleX = new Float32Array(capacity);
+		this.scaleY = new Float32Array(capacity);
+		this.rotations = new Float32Array(capacity);
+		this.rotationSpeeds = new Float32Array(capacity);
+		this.color = new Uint32Array(capacity);
+		this.elapsed = new Float32Array(capacity);
+		this.lifetime = new Float32Array(capacity);
+		this.frame = new Uint16Array(capacity);
+		this.alive = new Uint8Array(capacity);
+		this.position = {
+			x: this.posX,
+			y: this.posY
+		};
+		this.velocity = {
+			x: this.velX,
+			y: this.velY
+		};
+		this.scale = {
+			x: this.scaleX,
+			y: this.scaleY
+		};
+		this.rotation = {
+			angle: this.rotations,
+			speed: this.rotationSpeeds
+		};
+		this.timing = {
+			elapsed: this.elapsed,
+			lifetime: this.lifetime
+		};
+	}
+	isAlive(index) {
+		return this.alive[index] === 1;
+	}
+	/** Resets one slot to the spawn defaults every writer starts from. */
+	reset(slot) {
+		this.posX[slot] = 0;
+		this.posY[slot] = 0;
+		this.velX[slot] = 0;
+		this.velY[slot] = 0;
+		this.scaleX[slot] = 1;
+		this.scaleY[slot] = 1;
+		this.rotations[slot] = 0;
+		this.rotationSpeeds[slot] = 0;
+		this.color[slot] = 4294967295;
+		this.elapsed[slot] = 0;
+		this.lifetime[slot] = 1;
+		this.frame[slot] = 0;
+	}
+	/** Copies every channel of `from` onto `to`, for the CPU compaction pass. */
+	copySlot(from, to) {
+		this.posX[to] = this.posX[from];
+		this.posY[to] = this.posY[from];
+		this.velX[to] = this.velX[from];
+		this.velY[to] = this.velY[from];
+		this.scaleX[to] = this.scaleX[from];
+		this.scaleY[to] = this.scaleY[from];
+		this.rotations[to] = this.rotations[from];
+		this.rotationSpeeds[to] = this.rotationSpeeds[from];
+		this.color[to] = this.color[from];
+		this.elapsed[to] = this.elapsed[from];
+		this.lifetime[to] = this.lifetime[from];
+		this.frame[to] = this.frame[from];
+	}
+	/** Snapshots one slot for a death callback. */
+	snapshot(slot) {
+		return {
+			x: this.posX[slot],
+			y: this.posY[slot],
+			velocityX: this.velX[slot],
+			velocityY: this.velY[slot],
+			rotation: this.rotations[slot],
+			scaleX: this.scaleX[slot],
+			scaleY: this.scaleY[slot],
+			color: this.color[slot],
+			elapsed: this.elapsed[slot],
+			lifetime: this.lifetime[slot]
+		};
+	}
+};
+/** Cursor implementation of {@link ParticleWriter}, rebound to a slot by each emit. @internal */
+var ParticleSlotWriter = class {
+	position;
+	velocity;
+	scale;
+	_storage;
+	_slot = 0;
+	constructor(storage) {
+		this._storage = storage;
+		const slotOf = this._currentSlot.bind(this);
+		this.position = createVectorWriter(storage.posX, storage.posY, slotOf);
+		this.velocity = createVectorWriter(storage.velX, storage.velY, slotOf);
+		this.scale = createVectorWriter(storage.scaleX, storage.scaleY, slotOf);
+	}
+	/** The slot this cursor currently writes to. Used by the emitter to track what a spawner produced. @internal */
+	get slot() {
+		return this._slot;
+	}
+	bind(slot) {
+		this._slot = slot;
+		return this;
+	}
+	/**
+	* Marks this writer as belonging to a finished emission. Development builds
+	* hand out one writer per emission and retire the previous one here, so
+	* writing through a stale writer fails loudly instead of silently filling
+	* whatever particle was emitted since.
+	* @internal
+	*/
+	retire() {
+		this._retired = true;
+	}
+	_retired = false;
+	/** Resolves the bound slot, refusing a writer a later emission has taken over. */
+	_currentSlot() {
+		if (this._retired) throw new Error("ParticleWriter: this writer belongs to an earlier emit(). Fill each emitted particle before emitting the next one.");
+		return this._slot;
+	}
+	get rotation() {
+		return this._storage.rotations[this._currentSlot()];
+	}
+	set rotation(value) {
+		this._storage.rotations[this._currentSlot()] = value;
+	}
+	get rotationSpeed() {
+		return this._storage.rotationSpeeds[this._currentSlot()];
+	}
+	set rotationSpeed(value) {
+		this._storage.rotationSpeeds[this._currentSlot()] = value;
+	}
+	get color() {
+		return this._storage.color[this._currentSlot()];
+	}
+	set color(value) {
+		this._storage.color[this._currentSlot()] = value;
+	}
+	get lifetime() {
+		return this._storage.lifetime[this._currentSlot()];
+	}
+	set lifetime(value) {
+		this._storage.lifetime[this._currentSlot()] = value;
+	}
+	get frame() {
+		return this._storage.frame[this._currentSlot()];
+	}
+	set frame(value) {
+		this._storage.frame[this._currentSlot()] = value | 0;
+	}
+};
+const createVectorWriter = (xs, ys, slotOf) => ({
+	get x() {
+		return xs[slotOf()];
+	},
+	set x(value) {
+		xs[slotOf()] = value;
+	},
+	get y() {
+		return ys[slotOf()];
+	},
+	set y(value) {
+		ys[slotOf()] = value;
+	},
+	set(x, y) {
+		const slot = slotOf();
+		xs[slot] = x;
+		ys[slot] = y;
+	}
+});
+
+//#endregion
+export { ParticleSlotWriter, ParticleStorage };
+//# sourceMappingURL=ParticleStorage.js.map

package/dist/esm/ParticleStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleStorage.js","names":[],"sources":["../../src/ParticleStorage.ts"],"sourcesContent":["/**\n * A two-component particle channel, one array per component.\n *\n * The arrays are the simulation's own storage rather than a copy: writing\n * `position.x[i]` moves particle `i`. Their length is the system's capacity, so\n * only indices below {@link ParticleBatch.count} carry meaning.\n */\nexport interface ParticleVectorChannel {\n  readonly x: Float32Array;\n  readonly y: Float32Array;\n}\n\n/** The rotation channel: current angle and the speed integrated into it each frame. */\nexport interface ParticleRotationChannel {\n  readonly angle: Float32Array;\n  readonly speed: Float32Array;\n}\n\n/** The timing channel: seconds since spawn, and total seconds before expiry. */\nexport interface ParticleTimingChannel {\n  readonly elapsed: Float32Array;\n  readonly lifetime: Float32Array;\n}\n\n/**\n * The live particles of one system, addressed by semantic channel.\n *\n * This is the bulk surface an {@link UpdateModule} and a\n * {@link ParticleRenderMode} operate on. Channels are named for what they mean;\n * how they are packed - one array per component today, something else tomorrow -\n * is the simulation's business and may change. A loop reads the channel it needs\n * once and then indexes plain typed arrays, so naming costs nothing per particle.\n *\n * Indices `[0, count)` are the range worth visiting. A batch can contain dead\n * slots, so a loop that must not touch them checks {@link isAlive}; a purely\n * arithmetic pass over dead slots is harmless and can skip the check.\n */\nexport interface ParticleBatch {\n  /** Upper bound of the range that can hold live particles. */\n  readonly count: number;\n  /** Fixed number of slots this system can ever hold. */\n  readonly capacity: number;\n  readonly position: ParticleVectorChannel;\n  readonly velocity: ParticleVectorChannel;\n  readonly scale: ParticleVectorChannel;\n  readonly rotation: ParticleRotationChannel;\n  readonly timing: ParticleTimingChannel;\n  /** Packed `0xAABBGGRR` tint, one entry per slot. */\n  readonly color: Uint32Array;\n  /** Atlas frame selector, one entry per slot. Anything that is not a declared frame index shows frame 0. */\n  readonly frame: Uint16Array;\n  /** Whether the slot at `index` currently holds a live particle. */\n  isAlive(index: number): boolean;\n}\n\n/** Writable two-component channel of a single particle. */\nexport interface ParticleVectorWriter {\n  x: number;\n  y: number;\n  set(x: number, y: number): void;\n}\n\n/**\n * A single freshly emitted particle, addressed by name.\n *\n * Every field starts at its default - zero position, velocity, rotation and\n * rotation speed, unit scale, opaque white, frame 0, lifetime 1 - so a spawner\n * writes only what it varies.\n *\n * The writer is a cursor onto the emitting system, not a particle object: it is\n * reused by the next {@link ParticleEmitter.emit} call and must not be kept.\n * Read what you need before emitting again.\n */\nexport interface ParticleWriter {\n  readonly position: ParticleVectorWriter;\n  readonly velocity: ParticleVectorWriter;\n  readonly scale: ParticleVectorWriter;\n  rotation: number;\n  rotationSpeed: number;\n  /** Packed `0xAABBGGRR` tint. */\n  color: number;\n  /** Total seconds before this particle expires. */\n  lifetime: number;\n  /** Atlas frame index. Ignored by a system that declares no frames. */\n  frame: number;\n}\n\n/**\n * The emitting face of a particle system: the only supported way to bring\n * particles into existence.\n *\n * Emission is the one per-particle write that is true on every backend, because\n * spawn values always originate on the CPU and are uploaded from there.\n */\nexport interface ParticleEmitter {\n  /** Emits one particle at its default values, or returns `null` when the system is at capacity. */\n  emit(): ParticleWriter | null;\n}\n\n/**\n * The state of one particle at the moment it expired.\n *\n * A snapshot, not a view: it is copied out of the simulation when the particle\n * dies and stays valid for the whole callback, whichever backend ran the\n * simulation and whether or not the slot has already been reused. It carries no\n * slot index for that reason - there is nothing to read back afterwards.\n */\nexport interface ParticleDeathContext {\n  readonly x: number;\n  readonly y: number;\n  readonly velocityX: number;\n  readonly velocityY: number;\n  readonly rotation: number;\n  readonly scaleX: number;\n  readonly scaleY: number;\n  /** Packed `0xAABBGGRR` tint at death. */\n  readonly color: number;\n  /** Seconds the particle lived. */\n  readonly elapsed: number;\n  /** Lifetime the particle was spawned with. */\n  readonly lifetime: number;\n}\n\n/**\n * The simulation's own storage: one typed array per channel, sized to capacity\n * once and never reallocated.\n *\n * Implements {@link ParticleBatch}, which is the face handed to modules and\n * render modes. Nothing outside the simulation gets the object itself.\n * @internal\n */\nexport class ParticleStorage implements ParticleBatch {\n  public readonly capacity: number;\n\n  public readonly posX: Float32Array;\n  public readonly posY: Float32Array;\n  public readonly velX: Float32Array;\n  public readonly velY: Float32Array;\n  public readonly scaleX: Float32Array;\n  public readonly scaleY: Float32Array;\n  public readonly rotations: Float32Array;\n  public readonly rotationSpeeds: Float32Array;\n  public readonly color: Uint32Array;\n  public readonly elapsed: Float32Array;\n  public readonly lifetime: Float32Array;\n  public readonly frame: Uint16Array;\n  public readonly alive: Uint8Array;\n\n  public readonly position: ParticleVectorChannel;\n  public readonly velocity: ParticleVectorChannel;\n  public readonly scale: ParticleVectorChannel;\n  public readonly rotation: ParticleRotationChannel;\n  public readonly timing: ParticleTimingChannel;\n\n  /** Upper bound of the range that can hold live particles. Owned by the system. */\n  public count = 0;\n\n  public constructor(capacity: number) {\n    this.capacity = capacity;\n    this.posX = new Float32Array(capacity);\n    this.posY = new Float32Array(capacity);\n    this.velX = new Float32Array(capacity);\n    this.velY = new Float32Array(capacity);\n    this.scaleX = new Float32Array(capacity);\n    this.scaleY = new Float32Array(capacity);\n    this.rotations = new Float32Array(capacity);\n    this.rotationSpeeds = new Float32Array(capacity);\n    this.color = new Uint32Array(capacity);\n    this.elapsed = new Float32Array(capacity);\n    this.lifetime = new Float32Array(capacity);\n    this.frame = new Uint16Array(capacity);\n    this.alive = new Uint8Array(capacity);\n\n    this.position = { x: this.posX, y: this.posY };\n    this.velocity = { x: this.velX, y: this.velY };\n    this.scale = { x: this.scaleX, y: this.scaleY };\n    this.rotation = { angle: this.rotations, speed: this.rotationSpeeds };\n    this.timing = { elapsed: this.elapsed, lifetime: this.lifetime };\n  }\n\n  public isAlive(index: number): boolean {\n    return this.alive[index] === 1;\n  }\n\n  /** Resets one slot to the spawn defaults every writer starts from. */\n  public reset(slot: number): void {\n    this.posX[slot] = 0;\n    this.posY[slot] = 0;\n    this.velX[slot] = 0;\n    this.velY[slot] = 0;\n    this.scaleX[slot] = 1;\n    this.scaleY[slot] = 1;\n    this.rotations[slot] = 0;\n    this.rotationSpeeds[slot] = 0;\n    this.color[slot] = 0xffffffff;\n    this.elapsed[slot] = 0;\n    this.lifetime[slot] = 1;\n    this.frame[slot] = 0;\n  }\n\n  /** Copies every channel of `from` onto `to`, for the CPU compaction pass. */\n  public copySlot(from: number, to: number): void {\n    this.posX[to] = this.posX[from]!;\n    this.posY[to] = this.posY[from]!;\n    this.velX[to] = this.velX[from]!;\n    this.velY[to] = this.velY[from]!;\n    this.scaleX[to] = this.scaleX[from]!;\n    this.scaleY[to] = this.scaleY[from]!;\n    this.rotations[to] = this.rotations[from]!;\n    this.rotationSpeeds[to] = this.rotationSpeeds[from]!;\n    this.color[to] = this.color[from]!;\n    this.elapsed[to] = this.elapsed[from]!;\n    this.lifetime[to] = this.lifetime[from]!;\n    this.frame[to] = this.frame[from]!;\n  }\n\n  /** Snapshots one slot for a death callback. */\n  public snapshot(slot: number): ParticleDeathContext {\n    return {\n      x: this.posX[slot]!,\n      y: this.posY[slot]!,\n      velocityX: this.velX[slot]!,\n      velocityY: this.velY[slot]!,\n      rotation: this.rotations[slot]!,\n      scaleX: this.scaleX[slot]!,\n      scaleY: this.scaleY[slot]!,\n      color: this.color[slot]!,\n      elapsed: this.elapsed[slot]!,\n      lifetime: this.lifetime[slot]!,\n    };\n  }\n}\n\n/** Cursor implementation of {@link ParticleWriter}, rebound to a slot by each emit. @internal */\nexport class ParticleSlotWriter implements ParticleWriter {\n  public readonly position: ParticleVectorWriter;\n  public readonly velocity: ParticleVectorWriter;\n  public readonly scale: ParticleVectorWriter;\n\n  private readonly _storage: ParticleStorage;\n  private _slot = 0;\n\n  public constructor(storage: ParticleStorage) {\n    this._storage = storage;\n\n    const slotOf = this._currentSlot.bind(this);\n\n    this.position = createVectorWriter(storage.posX, storage.posY, slotOf);\n    this.velocity = createVectorWriter(storage.velX, storage.velY, slotOf);\n    this.scale = createVectorWriter(storage.scaleX, storage.scaleY, slotOf);\n  }\n\n  /** The slot this cursor currently writes to. Used by the emitter to track what a spawner produced. @internal */\n  public get slot(): number {\n    return this._slot;\n  }\n\n  public bind(slot: number): this {\n    this._slot = slot;\n\n    return this;\n  }\n\n  /**\n   * Marks this writer as belonging to a finished emission. Development builds\n   * hand out one writer per emission and retire the previous one here, so\n   * writing through a stale writer fails loudly instead of silently filling\n   * whatever particle was emitted since.\n   * @internal\n   */\n  public retire(): void {\n    this._retired = true;\n  }\n\n  private _retired = false;\n\n  /** Resolves the bound slot, refusing a writer a later emission has taken over. */\n  private _currentSlot(): number {\n    if (this._retired) {\n      throw new Error('ParticleWriter: this writer belongs to an earlier emit(). Fill each emitted particle before emitting the next one.');\n    }\n\n    return this._slot;\n  }\n\n  public get rotation(): number {\n    return this._storage.rotations[this._currentSlot()]!;\n  }\n\n  public set rotation(value: number) {\n    this._storage.rotations[this._currentSlot()] = value;\n  }\n\n  public get rotationSpeed(): number {\n    return this._storage.rotationSpeeds[this._currentSlot()]!;\n  }\n\n  public set rotationSpeed(value: number) {\n    this._storage.rotationSpeeds[this._currentSlot()] = value;\n  }\n\n  public get color(): number {\n    return this._storage.color[this._currentSlot()]!;\n  }\n\n  public set color(value: number) {\n    this._storage.color[this._currentSlot()] = value;\n  }\n\n  public get lifetime(): number {\n    return this._storage.lifetime[this._currentSlot()]!;\n  }\n\n  public set lifetime(value: number) {\n    this._storage.lifetime[this._currentSlot()] = value;\n  }\n\n  public get frame(): number {\n    return this._storage.frame[this._currentSlot()]!;\n  }\n\n  public set frame(value: number) {\n    this._storage.frame[this._currentSlot()] = value | 0;\n  }\n}\n\nconst createVectorWriter = (xs: Float32Array, ys: Float32Array, slotOf: () => number): ParticleVectorWriter => ({\n  get x(): number {\n    return xs[slotOf()]!;\n  },\n  set x(value: number) {\n    xs[slotOf()] = value;\n  },\n  get y(): number {\n    return ys[slotOf()]!;\n  },\n  set y(value: number) {\n    ys[slotOf()] = value;\n  },\n  set(x: number, y: number): void {\n    const slot = slotOf();\n\n    xs[slot] = x;\n    ys[slot] = y;\n  },\n});\n"],"mappings":"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"}