cubeforge 0.4.10 → 0.4.12

package/dist/index.d.ts

@@ -531,8 +531,42 @@ interface ParticleEmitterProps {
      * - `'screen'` — lightens, softer than additive
      */
     blendMode?: 'normal' | 'additive' | 'multiply' | 'screen';
+    /**
+     * Visual shape of each particle.
+     * - `'soft'` (default) — radial gradient with glow halo; pairs well with `blendMode="additive"`
+     * - `'circle'` — hard-edged anti-aliased circle, no glow falloff
+     * - `'square'` — solid quad (fastest, no texture lookup)
+     */
+    particleShape?: 'soft' | 'circle' | 'square';
+    /**
+     * Formation mode: particles lerp toward fixed target positions instead of
+     * being emitted with velocity. Enables logo reveals, constellations, shape morphing.
+     * - `'standard'` (default) — normal emit/gravity/lifetime behaviour
+     * - `'formation'` — particles seek `formationPoints`; no gravity, no expiry
+     */
+    mode?: 'standard' | 'formation';
+    /**
+     * Target positions for formation mode. One particle is spawned per point.
+     * Change this array to morph the formation — particles smoothly lerp to new targets.
+     */
+    formationPoints?: {
+        x: number;
+        y: number;
+    }[];
+    /**
+     * How strongly particles seek their target each frame in formation mode.
+     * Exponential lerp factor (0–1). Default 0.055 (~5.5% per frame at 60 fps).
+     */
+    seekStrength?: number;
+    /**
+     * Smoothly transition all particles to this color.
+     * Works in both standard and formation modes.
+     */
+    targetColor?: string;
+    /** Duration of the global color transition in seconds. Default 0.5. */
+    colorTransitionDuration?: number;
 }
-declare function ParticleEmitter({ active, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, burstCount, emitShape, emitRadius, emitWidth, emitHeight, textureSrc, enableRotation, rotationSpeedRange, sizeOverLife, attractors, colorOverLife, blendMode, }: ParticleEmitterProps): null;
+declare function ParticleEmitter({ active, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, burstCount, emitShape, emitRadius, emitWidth, emitHeight, textureSrc, enableRotation, rotationSpeedRange, sizeOverLife, attractors, colorOverLife, blendMode, mode, formationPoints, seekStrength, targetColor, colorTransitionDuration, particleShape, }: ParticleEmitterProps): null;
 
 interface VirtualJoystickProps {
     /** Diameter of the joystick base in pixels (default 120) */

package/dist/index.js

@@ -2793,6 +2793,8 @@ var RenderSystem = class {
     this.uTexture = gl.getUniformLocation(this.program, "u_texture");
     this.uUseTexture = gl.getUniformLocation(this.program, "u_useTexture");
     this.whiteTexture = createWhiteTexture(gl);
+    this.particleTextureSoft = this._createParticleTexture("soft");
+    this.particleTextureCircle = this._createParticleTexture("circle");
     this.parallaxProgram = createProgram(gl, PARALLAX_VERT_SRC, PARALLAX_FRAG_SRC);
     const fsVerts = new Float32Array([-1, -1, 1, -1, -1, 1, 1, -1, 1, 1, -1, 1]);
     this.parallaxVAO = gl.createVertexArray();
@@ -2819,6 +2821,8 @@ var RenderSystem = class {
   instanceBuffer;
   instanceData;
   whiteTexture;
+  particleTextureSoft;
+  particleTextureCircle;
   textures = /* @__PURE__ */ new Map();
   /** Tracks texture access order for LRU eviction (most recent at end). */
   textureLRU = [];
@@ -3041,6 +3045,38 @@ var RenderSystem = class {
     gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
     gl.activeTexture(gl.TEXTURE0);
   }
+  /** Pre-baked particle shape textures: white alpha mask, tinted by instance color at render time. */
+  _createParticleTexture(shape) {
+    const { gl } = this;
+    const SIZE = 64;
+    const canvas = document.createElement("canvas");
+    canvas.width = SIZE;
+    canvas.height = SIZE;
+    const ctx = canvas.getContext("2d");
+    const cx = SIZE / 2;
+    if (shape === "soft") {
+      const g = ctx.createRadialGradient(cx, cx, 0, cx, cx, cx);
+      g.addColorStop(0, "rgba(255,255,255,1)");
+      g.addColorStop(0.25, "rgba(255,255,255,0.9)");
+      g.addColorStop(0.5, "rgba(255,255,255,0.2)");
+      g.addColorStop(1, "rgba(255,255,255,0)");
+      ctx.fillStyle = g;
+      ctx.fillRect(0, 0, SIZE, SIZE);
+    } else {
+      ctx.fillStyle = "white";
+      ctx.beginPath();
+      ctx.arc(cx, cx, cx - 1, 0, Math.PI * 2);
+      ctx.fill();
+    }
+    const tex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, canvas);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return tex;
+  }
   // ── Texture management (sprite textures — CLAMP_TO_EDGE) ──────────────────
   loadTexture(src) {
     const cached = this.textures.get(src);
@@ -3283,6 +3319,8 @@ var RenderSystem = class {
     const { gl, canvas } = this;
     const W = canvas.width;
     const H = canvas.height;
+    const Wl = canvas.clientWidth || W;
+    const Hl = canvas.clientHeight || H;
     let camX = 0, camY = 0, zoom = 1;
     let background = this.defaultBackground;
     let shakeX = 0, shakeY = 0;
@@ -3472,7 +3510,7 @@ var RenderSystem = class {
     gl.useProgram(this.program);
     gl.uniform2f(this.uCamPos, camX, camY);
     gl.uniform1f(this.uZoom, zoom);
-    gl.uniform2f(this.uCanvasSize, W, H);
+    gl.uniform2f(this.uCanvasSize, Wl, Hl);
     gl.uniform2f(this.uShake, shakeX, shakeY);
     gl.uniform1i(this.uTexture, 0);
     gl.activeTexture(gl.TEXTURE0);
@@ -3653,15 +3691,87 @@ var RenderSystem = class {
     for (const id of world.query("Transform", "ParticlePool")) {
       const t = world.getComponent(id, "Transform");
       const pool = world.getComponent(id, "ParticlePool");
+      if (pool.targetColor && pool._colorTransitionFrom !== void 0) {
+        pool._colorTransitionElapsed = (pool._colorTransitionElapsed ?? 0) + dt;
+        const dur = pool.colorTransitionDuration ?? 0.5;
+        const ct = Math.min((pool._colorTransitionElapsed ?? 0) / dur, 1);
+        const ease = ct * ct * (3 - 2 * ct);
+        const [cr0, cg0, cb0] = parseCSSColor(pool._colorTransitionFrom);
+        const [cr1, cg1, cb1] = parseCSSColor(pool.targetColor);
+        const ri = Math.round((cr0 + (cr1 - cr0) * ease) * 255);
+        const gi = Math.round((cg0 + (cg1 - cg0) * ease) * 255);
+        const bi = Math.round((cb0 + (cb1 - cb0) * ease) * 255);
+        pool.color = `rgb(${ri},${gi},${bi})`;
+        if (ct >= 1) {
+          pool._colorTransitionFrom = void 0;
+          pool._colorTransitionElapsed = void 0;
+        }
+      }
+      const isFormation = pool.mode === "formation";
       pool.particles = pool.particles.filter((p) => {
+        if (isFormation) {
+          if (p.targetX !== void 0 && p.targetY !== void 0) {
+            const seek2 = pool.seekStrength ?? 0.055;
+            p.x += (p.targetX - p.x) * seek2;
+            p.y += (p.targetY - p.y) * seek2;
+          }
+          if (pool.attractors) {
+            for (const attr of pool.attractors) {
+              const adx = p.x - attr.x;
+              const ady = p.y - attr.y;
+              const dist = Math.sqrt(adx * adx + ady * ady);
+              if (dist < attr.radius && dist > 0) {
+                const magnitude = -attr.strength * (1 - dist / attr.radius) * dt;
+                p.x += adx / dist * magnitude;
+                p.y += ady / dist * magnitude;
+              }
+            }
+          }
+          return true;
+        }
         p.life -= dt;
+        if (pool.attractors) {
+          for (const attr of pool.attractors) {
+            const adx = attr.x - p.x;
+            const ady = attr.y - p.y;
+            const dist = Math.sqrt(adx * adx + ady * ady);
+            if (dist < attr.radius && dist > 0) {
+              const force = attr.strength * (1 - dist / attr.radius);
+              p.vx += adx / dist * force * dt;
+              p.vy += ady / dist * force * dt;
+            }
+          }
+        }
         p.x += p.vx * dt;
         p.y += p.vy * dt;
         p.vy += p.gravity * dt;
         if (p.rotationSpeed !== void 0) p.rotation = (p.rotation ?? 0) + p.rotationSpeed * dt;
         return p.life > 0;
       });
-      if (pool.active && pool.particles.length < pool.maxParticles) {
+      if (isFormation) {
+        const fp = pool.formationPoints ?? [];
+        while (pool.particles.length < fp.length) {
+          const idx = pool.particles.length;
+          const startSize = pool.sizeOverLife?.start ?? pool.particleSize;
+          const endSize = pool.sizeOverLife?.end ?? pool.particleSize;
+          pool.particles.push({
+            x: t.x + (world.rng() - 0.5) * 20,
+            y: t.y + (world.rng() - 0.5) * 20,
+            vx: 0,
+            vy: 0,
+            life: 1,
+            maxLife: 1,
+            size: startSize,
+            startSize,
+            endSize,
+            color: pool.color,
+            gravity: 0,
+            rotation: 0,
+            targetX: fp[idx].x,
+            targetY: fp[idx].y
+          });
+        }
+      } else if (pool.active && pool.particles.length < pool.maxParticles) {
         let spawnCount;
         if (pool.burstCount != null && pool.burstCount > 0) {
           spawnCount = pool.burstCount;
@@ -3711,11 +3821,22 @@ var RenderSystem = class {
         }
       }
       let pCount = 0;
-      const pKey = `__color__`;
+      const pShape = pool.particleShape ?? "soft";
       const pBlend = pool.blendMode ?? "normal";
+      const flushParticles = (n) => {
+        if (n === 0) return;
+        if (pBlend !== "normal") this.applyBlendMode(pBlend);
+        if (pShape === "square") {
+          this.flush(n, "__color__");
+        } else {
+          const tex = pShape === "circle" ? this.particleTextureCircle : this.particleTextureSoft;
+          this.flushWithTex(n, tex, true);
+        }
+        if (pBlend !== "normal") this.applyBlendMode("normal");
+      };
       for (const p of pool.particles) {
         if (pCount >= MAX_INSTANCES) {
-          this.flush(pCount, pKey, void 0, pBlend);
+          flushParticles(pCount);
           pCount = 0;
         }
         const lifeFrac = p.life / p.maxLife;
@@ -3762,7 +3883,7 @@ var RenderSystem = class {
         );
         pCount++;
       }
-      if (pCount > 0) this.flush(pCount, pKey, void 0, pBlend);
+      if (pCount > 0) flushParticles(pCount);
     }
     for (const id of world.query("Transform", "Trail")) {
       const t = world.getComponent(id, "Transform");
@@ -15556,7 +15677,13 @@ function ParticleEmitter({
   sizeOverLife,
   attractors,
   colorOverLife,
-  blendMode
+  blendMode,
+  mode,
+  formationPoints,
+  seekStrength,
+  targetColor,
+  colorTransitionDuration,
+  particleShape
 }) {
   const presetConfig = preset ? PARTICLE_PRESETS[preset] : {};
   const resolvedRate = rate ?? presetConfig.rate ?? 20;
@@ -15596,7 +15723,12 @@ function ParticleEmitter({
       sizeOverLife,
       attractors,
       colorOverLife,
-      blendMode
+      blendMode,
+      mode,
+      formationPoints,
+      seekStrength,
+      colorTransitionDuration,
+      particleShape
     });
     return () => engine.ecs.removeComponent(entityId, "ParticlePool");
   }, []);
@@ -15605,6 +15737,37 @@ function ParticleEmitter({
     if (!pool) return;
     pool.active = active;
   }, [active, engine, entityId]);
+  useEffect28(() => {
+    const pool = engine.ecs.getComponent(entityId, "ParticlePool");
+    if (!pool) return;
+    pool.blendMode = blendMode;
+    pool.particleShape = particleShape;
+  }, [blendMode, particleShape, engine, entityId]);
+  useEffect28(() => {
+    const pool = engine.ecs.getComponent(entityId, "ParticlePool");
+    if (!pool) return;
+    pool.attractors = attractors;
+  }, [attractors, engine, entityId]);
+  useEffect28(() => {
+    const pool = engine.ecs.getComponent(entityId, "ParticlePool");
+    if (!pool || pool.mode !== "formation" || !formationPoints) return;
+    pool.formationPoints = formationPoints;
+    const shuffled = [...formationPoints].sort(() => Math.random() - 0.5);
+    pool.particles.forEach((p, i) => {
+      if (shuffled[i]) {
+        p.targetX = shuffled[i].x;
+        p.targetY = shuffled[i].y;
+      }
+    });
+  }, [formationPoints, engine, entityId]);
+  useEffect28(() => {
+    const pool = engine.ecs.getComponent(entityId, "ParticlePool");
+    if (!pool || !targetColor) return;
+    pool._colorTransitionFrom = pool.color;
+    pool._colorTransitionElapsed = 0;
+    pool.targetColor = targetColor;
+    pool.colorTransitionDuration = colorTransitionDuration;
+  }, [targetColor, colorTransitionDuration, engine, entityId]);
   return null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "React-first 2D browser game engine",
   "type": "module",
   "main": "./dist/index.js",