@cazala/party 0.1.0-next.45.433a20a → 0.1.0-next.46.59ce407

package/README.md

@@ -10,7 +10,7 @@ A high-performance TypeScript particle physics engine with dual runtime support
 - **Spatial Grid Optimization**: Efficient O(1) neighbor queries for collision detection
 - **Real-time Oscillators**: Animate any module parameter with configurable frequency and bounds
 - **Advanced Rendering**: Trails, particle instancing, line rendering with multiple color modes
-- **Session Management**: Export/import complete simulation configurations
+- **Export/Import Presets**: Export/import module settings (inputs + enabled state)
 - **Cross-platform**: Works in all modern browsers with automatic feature detection
 
 ## Installation
@@ -82,12 +82,11 @@ await engine.initialize();
 // Add particles
 for (let i = 0; i < 100; i++) {
   engine.addParticle({
-    x: Math.random() * canvas.width,
-    y: Math.random() * canvas.height,
-    vx: (Math.random() - 0.5) * 4,
-    vy: (Math.random() - 0.5) * 4,
+    position: { x: Math.random() * canvas.width, y: Math.random() * canvas.height },
+    velocity: { x: (Math.random() - 0.5) * 4, y: (Math.random() - 0.5) * 4 },
     mass: 1 + Math.random() * 2,
     size: 3 + Math.random() * 7,
+    color: { r: 1, g: 1, b: 1, a: 1 },
   });
 }
 
@@ -111,8 +110,8 @@ const engine = new Engine({
   constrainIterations: 50,    // Constraint solver iterations
   cellSize: 32,              // Spatial grid cell size
   maxNeighbors: 128,         // Max neighbors per particle
-  maxParticles: 10000,       // Particle capacity
-  clearColor: "#000000",     // Background color
+  maxParticles: 10000,       // WebGPU buffer allocation + effective sim/render cap
+  clearColor: { r: 0, g: 0, b: 0, a: 1 }, // Background color
 });
 
 // Lifecycle
@@ -120,7 +119,7 @@ await engine.initialize();
 engine.play();
 engine.pause();
 engine.stop();
-engine.destroy();
+await engine.destroy();
 
 // State
 const isPlaying = engine.isPlaying();
@@ -128,7 +127,13 @@ const fps = engine.getFPS();
 const count = engine.getCount();
 
 // Particles
-engine.addParticle({ x, y, vx, vy, mass, size });
+engine.addParticle({
+  position: { x, y },
+  velocity: { x: vx, y: vy },
+  mass,
+  size,
+  color: { r: 1, g: 1, b: 1, a: 1 },
+});
 engine.setParticles([...particles]);
 const particles = await engine.getParticles();
 engine.clear();
@@ -163,11 +168,11 @@ Particles are simple data structures with physics properties:
 
 ```typescript
 const particle = {
-  x: 100, y: 100,           // Position
-  vx: 1, vy: -2,            // Velocity
+  position: { x: 100, y: 100 },   // Position
+  velocity: { x: 1, y: -2 },      // Velocity
   mass: 2.5,                // Mass (negative = pinned)
   size: 8,                  // Visual size
-  color: 0xff6b35,          // Color (24-bit RGB)
+  color: { r: 1, g: 0.42, b: 0.21, a: 1 }, // Color (0..1 floats)
 };
 
 // Bulk operations (preferred for performance)
@@ -590,7 +595,13 @@ Full TypeScript support with comprehensive type definitions:
 import type { IEngine, IParticle, Module } from "@cazala/party";
 
 const engine: IEngine = new Engine({ /* ... */ });
-const particle: IParticle = { x: 0, y: 0, vx: 1, vy: 1, mass: 1, size: 5 };
+const particle: IParticle = {
+  position: { x: 0, y: 0 },
+  velocity: { x: 1, y: 1 },
+  mass: 1,
+  size: 5,
+  color: { r: 1, g: 1, b: 1, a: 1 },
+};
 ```
 
 ## License

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import { IEngine, IParticle } from "./interfaces";
+import { IEngine, IParticle, GetParticlesInRadiusOptions, GetParticlesInRadiusResult } from "./interfaces";
 import { Module } from "./module";
 export type EngineOptions = {
     canvas: HTMLCanvasElement;
@@ -76,9 +76,15 @@ export declare class Engine implements IEngine {
     getOscillatorsElapsedSeconds(): number;
     setOscillatorsElapsedSeconds(seconds: number): void;
     setParticles(p: IParticle[]): void;
-    addParticle(p: IParticle): void;
+    addParticle(p: IParticle): number;
+    setParticle(index: number, p: IParticle): void;
+    setParticleMass(index: number, mass: number): void;
     getParticles(): Promise<IParticle[]>;
     getParticle(index: number): Promise<IParticle>;
+    getParticlesInRadius(center: {
+        x: number;
+        y: number;
+    }, radius: number, opts?: GetParticlesInRadiusOptions): Promise<GetParticlesInRadiusResult>;
     pinParticles(indexes: number[]): Promise<void>;
     unpinParticles(indexes: number[]): Promise<void>;
     unpinAll(): Promise<void>;

package/dist/engine.d.ts.map

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

package/dist/index.js

@@ -399,6 +399,33 @@ class GPUResources {
             stagingBuffer.destroy();
         }
     }
+    /**
+     * Read an arbitrary GPUBuffer (storage/uniform) into an ArrayBuffer.
+     * Caller is responsible for interpreting the bytes.
+     */
+    async readBuffer(buffer, sizeBytes) {
+        const bytes = Math.max(0, Math.floor(sizeBytes));
+        if (bytes === 0)
+            return new ArrayBuffer(0);
+        const stagingBuffer = this.getDevice().createBuffer({
+            size: bytes,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+        try {
+            const encoder = this.getDevice().createCommandEncoder();
+            encoder.copyBufferToBuffer(buffer, 0, stagingBuffer, 0, bytes);
+            this.getDevice().queue.submit([encoder.finish()]);
+            await this.getDevice().queue.onSubmittedWorkDone();
+            await stagingBuffer.mapAsync(GPUMapMode.READ);
+            const mapped = stagingBuffer.getMappedRange();
+            const out = mapped.slice(0);
+            stagingBuffer.unmap();
+            return out;
+        }
+        finally {
+            stagingBuffer.destroy();
+        }
+    }
     createModuleUniformBuffers(layouts) {
         // Destroy old
         this.moduleUniformBuffers.forEach(({ buffer }) => buffer.destroy());
@@ -1160,9 +1187,22 @@ class ParticleStore {
     }
     addParticle(p) {
         if (this.count >= this.maxParticles)
-            return;
-        this.writeAtIndex(this.count, p);
+            return -1;
+        const index = this.count;
+        this.writeAtIndex(index, p);
         this.count++;
+        return index;
+    }
+    setParticle(index, p) {
+        if (index < 0 || index >= this.count)
+            return;
+        this.writeAtIndex(index, p);
+    }
+    setParticleMass(index, mass) {
+        if (index < 0 || index >= this.count)
+            return;
+        const base = index * this.floatsPerParticle;
+        this.data[base + 7] = mass;
     }
     clear() {
         this.count = 0;
@@ -1192,6 +1232,28 @@ class ParticleStore {
             },
         };
     }
+    getFloatsPerParticle() {
+        return this.floatsPerParticle;
+    }
+    /**
+     * Write a full particle record at index into GPU storage.
+     */
+    syncParticleToGPU(resources, index) {
+        if (index < 0 || index >= this.count)
+            return;
+        const base = index * this.floatsPerParticle;
+        const slice = this.data.subarray(base, base + this.floatsPerParticle);
+        resources.writeParticleSlice(base, slice);
+    }
+    /**
+     * Write a single mass value at index into GPU storage.
+     */
+    syncParticleMassToGPU(resources, index) {
+        if (index < 0 || index >= this.count)
+            return;
+        const offset = index * this.floatsPerParticle + 7;
+        resources.writeParticleSlice(offset, new Float32Array([this.data[offset]]));
+    }
     /**
      * Writes the currently active particle slice to the GPU particle buffer.
      * Assumes the GPU storage buffer has already been created with matching capacity.
@@ -3437,6 +3499,219 @@ class RenderPipeline {
     }
 }
 
+/**
+ * LocalQuery
+ *
+ * A small WebGPU compute pipeline used to query a bounded set of particles
+ * in a region without doing a full GPU→CPU readback of the entire particle buffer.
+ *
+ * This is used by tool-like features (brush/pin/remove) that need local occupancy.
+ */
+class LocalQuery {
+    constructor() {
+        Object.defineProperty(this, "pipeline", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "uniform", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "count", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "out", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "outIdx", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "capacity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "device", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    dispose() {
+        this.pipeline = null;
+        this.uniform?.destroy();
+        this.count?.destroy();
+        this.out?.destroy();
+        this.outIdx?.destroy();
+        this.uniform = null;
+        this.count = null;
+        this.out = null;
+        this.outIdx = null;
+        this.capacity = 0;
+        this.device = null;
+    }
+    ensure(resources, maxResults) {
+        const device = resources.getDevice();
+        // If device changed (runtime toggle / recreate), rebuild everything.
+        if (this.device && this.device !== device) {
+            this.dispose();
+        }
+        this.device = device;
+        // (Re)allocate buffers if capacity changed
+        if (this.capacity !== maxResults) {
+            this.capacity = maxResults;
+            this.uniform?.destroy();
+            this.count?.destroy();
+            this.out?.destroy();
+            this.outIdx?.destroy();
+            this.uniform = device.createBuffer({
+                size: 8 * 4,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            this.count = device.createBuffer({
+                size: 4,
+                usage: GPUBufferUsage.STORAGE |
+                    GPUBufferUsage.COPY_DST |
+                    GPUBufferUsage.COPY_SRC,
+            });
+            this.out = device.createBuffer({
+                size: maxResults * 16,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+            });
+            this.outIdx = device.createBuffer({
+                size: maxResults * 4,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+            });
+        }
+        if (this.pipeline)
+            return;
+        const code = `
+struct Particle {
+  position: vec2<f32>,
+  velocity: vec2<f32>,
+  acceleration: vec2<f32>,
+  size: f32,
+  mass: f32,
+  color: vec4<f32>,
+};
+
+struct QueryUniforms {
+  v0: vec4<f32>, // center.x, center.y, radius, maxResults (as f32)
+  v1: vec4<f32>, // particleCount, 0,0,0
+};
+
+@group(0) @binding(0) var<storage, read> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> query: QueryUniforms;
+@group(0) @binding(2) var<storage, read_write> outCount: atomic<u32>;
+@group(0) @binding(3) var<storage, read_write> outData: array<vec4<f32>>;
+@group(0) @binding(4) var<storage, read_write> outIndex: array<u32>;
+
+@compute @workgroup_size(256)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  let count = u32(query.v1.x);
+  if (i >= count) { return; }
+
+  let p = particles[i];
+  if (p.mass == 0.0) { return; }
+
+  let cx = query.v0.x;
+  let cy = query.v0.y;
+  let radius = query.v0.z;
+  let maxResults = u32(query.v0.w);
+
+  // Disc-intersection semantics: dist <= radius + p.size
+  let dx = p.position.x - cx;
+  let dy = p.position.y - cy;
+  let rr = radius + p.size;
+  if (dx * dx + dy * dy > rr * rr) { return; }
+
+  let outIdx = atomicAdd(&outCount, 1u);
+  if (outIdx >= maxResults) { return; }
+  outData[outIdx] = vec4<f32>(p.position.x, p.position.y, p.size, p.mass);
+  outIndex[outIdx] = i;
+}
+`;
+        this.pipeline = device.createComputePipeline({
+            layout: "auto",
+            compute: { module: device.createShaderModule({ code }), entryPoint: "main" },
+        });
+    }
+    async getParticlesInRadius(resources, center, radius, particleCount, opts) {
+        const maxResults = Math.max(1, Math.floor(opts?.maxResults ?? 20000));
+        this.ensure(resources, maxResults);
+        const device = resources.getDevice();
+        const particleBuffer = resources.getParticleBuffer();
+        if (!particleBuffer)
+            return { particles: [], truncated: false };
+        // Reset atomic counter
+        device.queue.writeBuffer(this.count, 0, new Uint32Array([0]));
+        // Uniform: v0 = [cx, cy, radius, maxResults], v1 = [particleCount, 0, 0, 0]
+        const u = new Float32Array(8);
+        u[0] = center.x;
+        u[1] = center.y;
+        u[2] = radius;
+        u[3] = maxResults;
+        u[4] = particleCount;
+        device.queue.writeBuffer(this.uniform, 0, u);
+        const bindGroup = device.createBindGroup({
+            layout: this.pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: particleBuffer } },
+                { binding: 1, resource: { buffer: this.uniform } },
+                { binding: 2, resource: { buffer: this.count } },
+                { binding: 3, resource: { buffer: this.out } },
+                { binding: 4, resource: { buffer: this.outIdx } },
+            ],
+        });
+        const encoder = device.createCommandEncoder();
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        const wg = 256;
+        const n = Math.max(0, Math.floor(particleCount));
+        pass.dispatchWorkgroups(Math.ceil(n / wg));
+        pass.end();
+        device.queue.submit([encoder.finish()]);
+        const countBuf = await resources.readBuffer(this.count, 4);
+        const found = new Uint32Array(countBuf)[0] ?? 0;
+        const truncated = found > maxResults;
+        const readCount = Math.min(found, maxResults);
+        if (readCount === 0)
+            return { particles: [], truncated };
+        const idxBuf = await resources.readBuffer(this.outIdx, readCount * 4);
+        const indices = new Uint32Array(idxBuf);
+        const outBuf = await resources.readBuffer(this.out, readCount * 16);
+        const outFloats = new Float32Array(outBuf);
+        const particles = [];
+        for (let i = 0; i < readCount; i++) {
+            const base = i * 4;
+            particles.push({
+                index: indices[i] ?? 0,
+                position: { x: outFloats[base + 0], y: outFloats[base + 1] },
+                size: outFloats[base + 2],
+                mass: outFloats[base + 3],
+            });
+        }
+        return { particles, truncated };
+    }
+}
+
 class WebGPUEngine extends AbstractEngine {
     constructor(options) {
         super({
@@ -3515,6 +3790,12 @@ class WebGPUEngine extends AbstractEngine {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "localQuery", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "animate", {
             enumerable: true,
             configurable: true,
@@ -3584,6 +3865,7 @@ class WebGPUEngine extends AbstractEngine {
         this.sim = new SimulationPipeline();
         this.render = new RenderPipeline();
         this.grid = new SpacialGrid(this.cellSize);
+        this.localQuery = new LocalQuery();
     }
     async initialize() {
         await this.resources.initialize();
@@ -3640,6 +3922,7 @@ class WebGPUEngine extends AbstractEngine {
             cancelAnimationFrame(this.animationId);
             this.animationId = null;
         }
+        this.localQuery.dispose();
         await this.resources.dispose();
     }
     // Override setSize to also update WebGPU-specific resources
@@ -3663,12 +3946,24 @@ class WebGPUEngine extends AbstractEngine {
             this.updateMaxSize(particle.size);
         }
     }
-    async addParticle(p) {
-        await this.particles.syncFromGPU(this.resources);
-        this.particles.addParticle(p);
-        this.particles.syncToGPU(this.resources);
+    addParticle(p) {
+        const index = this.particles.addParticle(p);
+        if (index < 0)
+            return -1;
+        // Push only the new particle record to GPU (no full-scene readback).
+        this.particles.syncParticleToGPU(this.resources, index);
         // Update maxSize tracking
         this.updateMaxSize(p.size);
+        return index;
+    }
+    setParticle(index, p) {
+        this.particles.setParticle(index, p);
+        this.particles.syncParticleToGPU(this.resources, index);
+        this.updateMaxSize(p.size);
+    }
+    setParticleMass(index, mass) {
+        this.particles.setParticleMass(index, mass);
+        this.particles.syncParticleMassToGPU(this.resources, index);
     }
     /**
      * Forces GPU-to-CPU synchronization and returns current particle data.
@@ -3682,6 +3977,9 @@ class WebGPUEngine extends AbstractEngine {
         await this.particles.syncFromGPU(this.resources);
         return this.particles.getParticle(index);
     }
+    async getParticlesInRadius(center, radius, opts) {
+        return await this.localQuery.getParticlesInRadius(this.resources, center, radius, this.getCount(), opts);
+    }
     getCount() {
         const actualCount = this.particles.getCount();
         if (this.maxParticles === null) {
@@ -4298,6 +4596,12 @@ class CPUEngine extends AbstractEngine {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "particleIdToIndex", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "animate", {
             enumerable: true,
             configurable: true,
@@ -4372,6 +4676,7 @@ class CPUEngine extends AbstractEngine {
         this.fpsEstimate = 60;
         // Reset maxSize tracking
         this.resetMaxSize();
+        this.particleIdToIndex.clear();
     }
     getCount() {
         const actualCount = this.particles.length;
@@ -4395,11 +4700,33 @@ class CPUEngine extends AbstractEngine {
         for (const p of particle) {
             this.updateMaxSize(p.size);
         }
+        this.particleIdToIndex.clear();
     }
     addParticle(particle) {
+        const index = this.particles.length;
         this.particles.push(new Particle(particle));
         // Update maxSize tracking
         this.updateMaxSize(particle.size);
+        const created = this.particles[index];
+        if (created)
+            this.particleIdToIndex.set(created.id, index);
+        return index;
+    }
+    setParticle(index, p) {
+        if (index < 0)
+            return;
+        if (index >= this.particles.length)
+            return;
+        this.particles[index] = new Particle(p);
+        // Best-effort maxSize tracking (monotonic)
+        this.updateMaxSize(p.size);
+    }
+    setParticleMass(index, mass) {
+        if (index < 0)
+            return;
+        if (index >= this.particles.length)
+            return;
+        this.particles[index].mass = mass;
     }
     getParticles() {
         return Promise.resolve(this.particles.map((p) => p.toJSON()));
@@ -4407,10 +4734,47 @@ class CPUEngine extends AbstractEngine {
     getParticle(index) {
         return Promise.resolve(this.particles[index]);
     }
+    async getParticlesInRadius(center, radius, opts) {
+        const maxResults = Math.max(1, Math.floor(opts?.maxResults ?? 20000));
+        // Expand search radius to ensure we can find large particles whose discs
+        // intersect the query circle: dist <= radius + p.size.
+        const searchRadius = Math.max(0, radius) + this.getMaxSize();
+        // Use the existing spatial grid (built during the last simulation tick).
+        // Snapshot semantics: this is "as of last grid build" which is good enough
+        // for tool usage and avoids global scans.
+        const neighbors = this.grid.getParticles(new Vector(center.x, center.y), searchRadius, 
+        // Ask for up to maxResults+1 so we can mark truncated more reliably.
+        maxResults + 1);
+        const out = [];
+        const r = Math.max(0, radius);
+        for (const p of neighbors) {
+            if (p.mass === 0)
+                continue;
+            const index = this.particleIdToIndex.get(p.id);
+            if (index === undefined)
+                continue;
+            const dx = p.position.x - center.x;
+            const dy = p.position.y - center.y;
+            const rr = r + p.size;
+            if (dx * dx + dy * dy <= rr * rr) {
+                out.push({
+                    index,
+                    position: { x: p.position.x, y: p.position.y },
+                    size: p.size,
+                    mass: p.mass,
+                });
+                if (out.length >= maxResults + 1)
+                    break;
+            }
+        }
+        const truncated = out.length > maxResults;
+        return { particles: truncated ? out.slice(0, maxResults) : out, truncated };
+    }
     destroy() {
         this.pause();
         this.particles = [];
         this.grid.clear();
+        this.particleIdToIndex.clear();
         return Promise.resolve();
     }
     // Handle configuration changes
@@ -4457,8 +4821,10 @@ class CPUEngine extends AbstractEngine {
         // Update spatial grid with current particle positions and camera
         this.grid.setCamera(this.view.getCamera().x, this.view.getCamera().y, this.view.getZoom());
         this.grid.clear();
+        this.particleIdToIndex.clear();
         for (let i = 0; i < effectiveCount; i++) {
             this.grid.insert(this.particles[i]);
+            this.particleIdToIndex.set(this.particles[i].id, i);
         }
         // Global state for modules that need it
         const globalState = {};
@@ -4948,7 +5314,13 @@ class Engine {
         this.engine.setParticles(p);
     }
     addParticle(p) {
-        this.engine.addParticle(p);
+        return this.engine.addParticle(p);
+    }
+    setParticle(index, p) {
+        this.engine.setParticle(index, p);
+    }
+    setParticleMass(index, mass) {
+        this.engine.setParticleMass(index, mass);
     }
     getParticles() {
         return this.engine.getParticles();
@@ -4956,6 +5328,9 @@ class Engine {
     getParticle(index) {
         return this.engine.getParticle(index);
     }
+    getParticlesInRadius(center, radius, opts) {
+        return this.engine.getParticlesInRadius(center, radius, opts);
+    }
     // Helpers for pinning/unpinning
     async pinParticles(indexes) {
         const particles = await this.getParticles();