@cazala/party 0.3.0 → 0.5.0

package/README.md

@@ -12,6 +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 and images
 
 ## Installation
 
@@ -189,6 +190,58 @@ engine.unpinParticles([0, 1, 2]);
 engine.unpinAll();
 ```
 
+### Spawner
+
+Generate particle arrays from common shapes (including text and images) using `Spawner`:
+
+```typescript
+import { Spawner } from "@cazala/party";
+
+const spawner = new Spawner();
+const particles = spawner.initParticles({
+  count: 5000,
+  shape: "text",
+  center: { x: 0, y: 0 },
+  position: { x: 0, y: 0 },
+  align: { horizontal: "center", vertical: "center" },
+  text: "Party",
+  font: "sans-serif",
+  textSize: 80,
+  size: 3,
+  mass: 1,
+  colors: ["#ffffff"],
+});
+
+engine.setParticles(particles);
+```
+
+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

@@ -5431,6 +5431,7 @@ class Engine {
     }
 }
 
+const TEXT_SPAWNER_FONTS = ["sans-serif", "serif", "monospace"];
 function calculateVelocity(position, center, cfg) {
     if (!cfg || cfg.speed === 0)
         return { vx: 0, vy: 0 };
@@ -5472,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, } = 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;
@@ -5499,6 +5500,186 @@ class Spawner {
                 return { r: 1, g: 1, b: 1, a: 1 };
             return toColor(colors[Math.floor(Math.random() * colors.length)]);
         };
+        if (shape === "text") {
+            const textValue = text.trim();
+            if (!textValue)
+                return particles;
+            const createCanvas = () => {
+                if (typeof OffscreenCanvas !== "undefined") {
+                    return new OffscreenCanvas(1, 1);
+                }
+                if (typeof document !== "undefined") {
+                    return document.createElement("canvas");
+                }
+                return null;
+            };
+            const canvas = createCanvas();
+            if (!canvas)
+                return particles;
+            const ctx = canvas.getContext("2d");
+            if (!ctx)
+                return particles;
+            const fontSize = Math.max(1, Math.floor(textSize));
+            const fontSpec = `${fontSize}px ${font}`;
+            ctx.font = fontSpec;
+            ctx.textBaseline = "alphabetic";
+            ctx.textAlign = "left";
+            const metrics = ctx.measureText(textValue);
+            const ascent = metrics.actualBoundingBoxAscent || fontSize;
+            const descent = metrics.actualBoundingBoxDescent || fontSize * 0.25;
+            const left = metrics.actualBoundingBoxLeft || 0;
+            const right = metrics.actualBoundingBoxRight || metrics.width;
+            const textWidth = Math.max(1, Math.ceil(left + right));
+            const textHeight = Math.max(1, Math.ceil(ascent + descent));
+            const padding = Math.ceil(fontSize * 0.25);
+            canvas.width = textWidth + padding * 2;
+            canvas.height = textHeight + padding * 2;
+            ctx.clearRect(0, 0, canvas.width, canvas.height);
+            ctx.font = fontSpec;
+            ctx.textBaseline = "alphabetic";
+            ctx.textAlign = "left";
+            ctx.fillStyle = "#ffffff";
+            ctx.fillText(textValue, padding + left, padding + ascent);
+            const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            const data = imageData.data;
+            const sampleStep = Math.max(1, Math.round(size));
+            const points = [];
+            for (let y = 0; y < canvas.height; y += sampleStep) {
+                for (let x = 0; x < canvas.width; x += sampleStep) {
+                    const idx = (y * canvas.width + x) * 4 + 3;
+                    if (data[idx] > 0) {
+                        points.push({ x, y });
+                    }
+                }
+            }
+            const maxCount = Math.min(count, points.length);
+            if (maxCount <= 0)
+                return particles;
+            const textPosition = position ?? center;
+            const horizontal = align?.horizontal ?? "center";
+            const vertical = align?.vertical ?? "center";
+            const originX = horizontal === "left"
+                ? textPosition.x
+                : horizontal === "right"
+                    ? textPosition.x - textWidth
+                    : textPosition.x - textWidth / 2;
+            const originY = vertical === "top"
+                ? textPosition.y
+                : vertical === "bottom"
+                    ? textPosition.y - textHeight
+                    : textPosition.y - textHeight / 2;
+            const stride = points.length / maxCount;
+            for (let i = 0; i < maxCount; i++) {
+                const idx = Math.floor(i * stride);
+                const point = points[idx];
+                if (!point)
+                    continue;
+                const x = originX + (point.x - padding);
+                const y = originY + (point.y - padding);
+                const { vx, vy } = calculateVelocity({ x, y }, textPosition, velocity);
+                particles.push({
+                    position: { x, y },
+                    velocity: { x: vx, y: vy },
+                    size,
+                    mass,
+                    color: getColor(),
+                });
+            }
+            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);
@@ -10392,5 +10573,5 @@ class Particles extends Module {
     }
 }
 
-export { AbstractEngine, Behavior, Boundary, CanvasComposition, Collisions, DEFAULT_BEHAVIOR_ALIGNMENT, DEFAULT_BEHAVIOR_AVOID, DEFAULT_BEHAVIOR_CHASE, DEFAULT_BEHAVIOR_COHESION, DEFAULT_BEHAVIOR_REPULSION, DEFAULT_BEHAVIOR_SEPARATION, DEFAULT_BEHAVIOR_VIEW_ANGLE, DEFAULT_BEHAVIOR_VIEW_RADIUS, DEFAULT_BEHAVIOR_WANDER, DEFAULT_BOUNDARY_FRICTION, DEFAULT_BOUNDARY_MODE, DEFAULT_BOUNDARY_REPEL_DISTANCE, DEFAULT_BOUNDARY_REPEL_STRENGTH, DEFAULT_BOUNDARY_RESTITUTION, DEFAULT_COLLISIONS_RESTITUTION, DEFAULT_ENVIRONMENT_DAMPING, DEFAULT_ENVIRONMENT_FRICTION, DEFAULT_ENVIRONMENT_GRAVITY_ANGLE, DEFAULT_ENVIRONMENT_GRAVITY_DIRECTION, DEFAULT_ENVIRONMENT_GRAVITY_STRENGTH, DEFAULT_ENVIRONMENT_INERTIA, DEFAULT_FLUIDS_ENABLE_NEAR_PRESSURE, DEFAULT_FLUIDS_INFLUENCE_RADIUS, DEFAULT_FLUIDS_MAX_ACCELERATION, DEFAULT_FLUIDS_NEAR_PRESSURE_MULTIPLIER, DEFAULT_FLUIDS_NEAR_THRESHOLD, DEFAULT_FLUIDS_PRESSURE_MULTIPLIER, DEFAULT_FLUIDS_TARGET_DENSITY, DEFAULT_FLUIDS_VISCOSITY, DEFAULT_GRAB_GRABBED_INDEX, DEFAULT_GRAB_POSITION_X, DEFAULT_GRAB_POSITION_Y, DEFAULT_INTERACTION_MODE, DEFAULT_INTERACTION_RADIUS, DEFAULT_INTERACTION_STRENGTH, DEFAULT_JOINTS_ENABLE_JOINT_COLLISIONS, DEFAULT_JOINTS_ENABLE_PARTICLE_COLLISIONS, DEFAULT_JOINTS_FRICTION, DEFAULT_JOINTS_MOMENTUM, DEFAULT_JOINTS_RESTITUTION, DEFAULT_JOINTS_SEPARATION, DEFAULT_JOINTS_STEPS, DEFAULT_PICFLIP_DENSITY, DEFAULT_PICFLIP_FLIP_RATIO, DEFAULT_PICFLIP_INFLUENCE_RADIUS, DEFAULT_PICFLIP_INTERNAL_MAX_ACCELERATION, DEFAULT_PICFLIP_PRESSURE, DEFAULT_PICFLIP_PRESSURE_MULTIPLIER, DEFAULT_PICFLIP_RADIUS, DEFAULT_PICFLIP_TARGET_DENSITY, DEFAULT_SENSORS_COLOR_SIMILARITY_THRESHOLD, DEFAULT_SENSORS_FLEE_ANGLE, DEFAULT_SENSORS_FLEE_BEHAVIOR, DEFAULT_SENSORS_FOLLOW_BEHAVIOR, DEFAULT_SENSORS_SENSOR_ANGLE, DEFAULT_SENSORS_SENSOR_DISTANCE, DEFAULT_SENSORS_SENSOR_RADIUS, DEFAULT_SENSORS_SENSOR_STRENGTH, DEFAULT_SENSORS_SENSOR_THRESHOLD, DEFAULT_TRAILS_TRAIL_DECAY, DEFAULT_TRAILS_TRAIL_DIFFUSE, DataType, Engine, Environment, Fluids, FluidsMethod, Grab, Interaction, Joints, Lines, Module, ModuleRole, OscillatorManager, Particles, ParticlesColorType, RenderPassKind, Sensors, Spawner, Trails, Vector, degToRad, radToDeg };
+export { AbstractEngine, Behavior, Boundary, CanvasComposition, Collisions, DEFAULT_BEHAVIOR_ALIGNMENT, DEFAULT_BEHAVIOR_AVOID, DEFAULT_BEHAVIOR_CHASE, DEFAULT_BEHAVIOR_COHESION, DEFAULT_BEHAVIOR_REPULSION, DEFAULT_BEHAVIOR_SEPARATION, DEFAULT_BEHAVIOR_VIEW_ANGLE, DEFAULT_BEHAVIOR_VIEW_RADIUS, DEFAULT_BEHAVIOR_WANDER, DEFAULT_BOUNDARY_FRICTION, DEFAULT_BOUNDARY_MODE, DEFAULT_BOUNDARY_REPEL_DISTANCE, DEFAULT_BOUNDARY_REPEL_STRENGTH, DEFAULT_BOUNDARY_RESTITUTION, DEFAULT_COLLISIONS_RESTITUTION, DEFAULT_ENVIRONMENT_DAMPING, DEFAULT_ENVIRONMENT_FRICTION, DEFAULT_ENVIRONMENT_GRAVITY_ANGLE, DEFAULT_ENVIRONMENT_GRAVITY_DIRECTION, DEFAULT_ENVIRONMENT_GRAVITY_STRENGTH, DEFAULT_ENVIRONMENT_INERTIA, DEFAULT_FLUIDS_ENABLE_NEAR_PRESSURE, DEFAULT_FLUIDS_INFLUENCE_RADIUS, DEFAULT_FLUIDS_MAX_ACCELERATION, DEFAULT_FLUIDS_NEAR_PRESSURE_MULTIPLIER, DEFAULT_FLUIDS_NEAR_THRESHOLD, DEFAULT_FLUIDS_PRESSURE_MULTIPLIER, DEFAULT_FLUIDS_TARGET_DENSITY, DEFAULT_FLUIDS_VISCOSITY, DEFAULT_GRAB_GRABBED_INDEX, DEFAULT_GRAB_POSITION_X, DEFAULT_GRAB_POSITION_Y, DEFAULT_INTERACTION_MODE, DEFAULT_INTERACTION_RADIUS, DEFAULT_INTERACTION_STRENGTH, DEFAULT_JOINTS_ENABLE_JOINT_COLLISIONS, DEFAULT_JOINTS_ENABLE_PARTICLE_COLLISIONS, DEFAULT_JOINTS_FRICTION, DEFAULT_JOINTS_MOMENTUM, DEFAULT_JOINTS_RESTITUTION, DEFAULT_JOINTS_SEPARATION, DEFAULT_JOINTS_STEPS, DEFAULT_PICFLIP_DENSITY, DEFAULT_PICFLIP_FLIP_RATIO, DEFAULT_PICFLIP_INFLUENCE_RADIUS, DEFAULT_PICFLIP_INTERNAL_MAX_ACCELERATION, DEFAULT_PICFLIP_PRESSURE, DEFAULT_PICFLIP_PRESSURE_MULTIPLIER, DEFAULT_PICFLIP_RADIUS, DEFAULT_PICFLIP_TARGET_DENSITY, DEFAULT_SENSORS_COLOR_SIMILARITY_THRESHOLD, DEFAULT_SENSORS_FLEE_ANGLE, DEFAULT_SENSORS_FLEE_BEHAVIOR, DEFAULT_SENSORS_FOLLOW_BEHAVIOR, DEFAULT_SENSORS_SENSOR_ANGLE, DEFAULT_SENSORS_SENSOR_DISTANCE, DEFAULT_SENSORS_SENSOR_RADIUS, DEFAULT_SENSORS_SENSOR_STRENGTH, DEFAULT_SENSORS_SENSOR_THRESHOLD, DEFAULT_TRAILS_TRAIL_DECAY, DEFAULT_TRAILS_TRAIL_DIFFUSE, DataType, Engine, Environment, Fluids, FluidsMethod, Grab, Interaction, Joints, Lines, Module, ModuleRole, OscillatorManager, Particles, ParticlesColorType, RenderPassKind, Sensors, Spawner, TEXT_SPAWNER_FONTS, Trails, Vector, degToRad, radToDeg };
 //# sourceMappingURL=index.js.map