@cazala/party 0.4.0 → 0.5.0

package/README.md

@@ -12,7 +12,7 @@ A high-performance TypeScript particle physics engine with dual runtime support
 - **Advanced Rendering**: Trails, particle instancing, line rendering with multiple color modes
 - **Export/Import Presets**: Export/import module settings (inputs + enabled state)
 - **Cross-platform**: Works in all modern browsers with automatic feature detection
-- **Spawner Utility**: Generate particle shapes, including text
+- **Spawner Utility**: Generate particle shapes, including text and images
 
 ## Installation
 
@@ -192,7 +192,7 @@ engine.unpinAll();
 
 ### Spawner
 
-Generate particle arrays from common shapes (including text) using `Spawner`:
+Generate particle arrays from common shapes (including text and images) using `Spawner`:
 
 ```typescript
 import { Spawner } from "@cazala/party";
@@ -220,6 +220,28 @@ Notes:
 - `size` controls particle radius; `textSize` is the font size used to rasterize text.
 - Playground font options: `sans-serif`, `serif`, `monospace`.
 
+Image example:
+
+```typescript
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+const imageParticles = spawner.initParticles({
+  count: 12000,
+  shape: "image",
+  center: { x: 0, y: 0 },
+  position: { x: 0, y: 0 },
+  align: { horizontal: "center", vertical: "center" },
+  imageData,
+  imageSize: 400, // scales to this max dimension
+  size: 3,
+  mass: 1,
+});
+```
+
+Notes:
+
+- `imageData` must be provided synchronously (no URL fetching inside the spawner).
+- Fully transparent pixels are skipped; particle colors come from image pixels.
+
 ### Modules
 
 Modules are pluggable components that contribute to simulation or rendering:

package/dist/index.js

@@ -5473,7 +5473,7 @@ function calculateVelocity(position, center, cfg) {
 }
 class Spawner {
     initParticles(options) {
-        const { count, shape, center, spacing = 25, radius = 100, innerRadius = 50, squareSize = 200, cornerRadius = 0, size = 5, mass = 1, bounds, velocity, colors, text = "Party", font = "sans-serif", textSize = 64, position, align, } = options;
+        const { count, shape, center, spacing = 25, radius = 100, innerRadius = 50, squareSize = 200, cornerRadius = 0, size = 5, mass = 1, bounds, velocity, colors, text = "Party", font = "sans-serif", textSize = 64, position, align, imageData, imageSize, } = options;
         const particles = [];
         if (count <= 0)
             return particles;
@@ -5587,6 +5587,99 @@ class Spawner {
             }
             return particles;
         }
+        if (shape === "image") {
+            if (!imageData)
+                return particles;
+            const width = Math.floor(imageData.width);
+            const height = Math.floor(imageData.height);
+            if (!Number.isFinite(width) ||
+                !Number.isFinite(height) ||
+                width <= 0 ||
+                height <= 0)
+                return particles;
+            const data = imageData.data;
+            const sampleStepTarget = Math.max(1, Math.round(size));
+            const targetSize = typeof imageSize === "number" && Number.isFinite(imageSize) && imageSize > 0
+                ? imageSize
+                : Math.max(width, height);
+            const scale = Math.max(0.0001, targetSize / Math.max(width, height));
+            const sampleStepSource = Math.max(1, Math.round(sampleStepTarget / scale));
+            const points = [];
+            for (let y = 0; y < height; y += sampleStepSource) {
+                for (let x = 0; x < width; x += sampleStepSource) {
+                    const idx = (y * width + x) * 4;
+                    const alpha = data[idx + 3];
+                    if (alpha === 0)
+                        continue;
+                    points.push({
+                        x: x * scale,
+                        y: y * scale,
+                        color: {
+                            r: data[idx] / 255,
+                            g: data[idx + 1] / 255,
+                            b: data[idx + 2] / 255,
+                            a: alpha / 255,
+                        },
+                    });
+                }
+            }
+            const maxCount = Math.max(0, Math.floor(count));
+            if (maxCount <= 0 || points.length === 0)
+                return particles;
+            const imagePosition = position ?? center;
+            const horizontal = align?.horizontal ?? "center";
+            const vertical = align?.vertical ?? "center";
+            const scaledWidth = width * scale;
+            const scaledHeight = height * scale;
+            const originX = horizontal === "left"
+                ? imagePosition.x
+                : horizontal === "right"
+                    ? imagePosition.x - scaledWidth
+                    : imagePosition.x - scaledWidth / 2;
+            const originY = vertical === "top"
+                ? imagePosition.y
+                : vertical === "bottom"
+                    ? imagePosition.y - scaledHeight
+                    : imagePosition.y - scaledHeight / 2;
+            const baseCount = Math.min(maxCount, points.length);
+            const stride = points.length / baseCount;
+            for (let i = 0; i < baseCount; i++) {
+                const idx = Math.floor(i * stride);
+                const point = points[idx];
+                if (!point)
+                    continue;
+                const x = originX + point.x;
+                const y = originY + point.y;
+                const { vx, vy } = calculateVelocity({ x, y }, imagePosition, velocity);
+                particles.push({
+                    position: { x, y },
+                    velocity: { x: vx, y: vy },
+                    size,
+                    mass,
+                    color: point.color,
+                });
+            }
+            const extraCount = maxCount - baseCount;
+            if (extraCount > 0) {
+                const jitter = sampleStepTarget * 0.4;
+                for (let i = 0; i < extraCount; i++) {
+                    const point = points[Math.floor(Math.random() * points.length)];
+                    if (!point)
+                        continue;
+                    const x = originX + point.x + (Math.random() - 0.5) * jitter;
+                    const y = originY + point.y + (Math.random() - 0.5) * jitter;
+                    const { vx, vy } = calculateVelocity({ x, y }, imagePosition, velocity);
+                    particles.push({
+                        position: { x, y },
+                        velocity: { x: vx, y: vy },
+                        size,
+                        mass,
+                        color: point.color,
+                    });
+                }
+            }
+            return particles;
+        }
         if (shape === "grid") {
             const cols = Math.ceil(Math.sqrt(count));
             const rows = Math.ceil(count / cols);