particles

PURPOSE

Thin convenience wrapper around the Particles singleton in engine/vfx/particles.ts. Exposes named, gameplay-flavored spawn helpers (spawnImpact, spawnDeath, spawnHeal, spawnShieldHit, spawnStun) so caller systems do not need to remember per-effect counts, colors, and speeds. Each helper resolves to a single Particles.burst(...) call.

OWNS

• The ParticleHelpers object literal and its five spawn methods.
• The per-effect tuning constants embedded in each helper: particle count, default RGB color, and burst speed.

READS FROM

• WorldState type from ../core/types (helpers accept a world: WorldState parameter but currently do not dereference it; it is passed through for signature stability and future use).
• Optional caller-supplied color: { r, g, b } override on spawnImpact and spawnDeath.

PUSHES TO

• Particles.burst(...) in ../vfx/particles, which in turn pushes particle objects into world.particles via an internal object pool.

DOES NOT

• Does not allocate or manage particle objects directly (pooling lives in engine/vfx/particles.ts).
• Does not update or render particles (update loop and draw live in the VFX module / renderer).
• Does not check CFG.MAX_PARTICLES; the underlying Particles.burst and Particles.add enforce the cap.
• Does not dispatch any events or write to telemetry.
• Does not read from the world argument despite accepting it.
• Does not expose smoke, exhaust, muzzle-flash, warp-arrival, star-burst, or impact-burst variants — those remain only on the underlying Particles singleton.

Signals

None. Pure helper functions; no events emitted, subscribed, or dispatched.

Entry points

Re-exported from engine/world/index.ts as ParticleHelpers. Each method has the shape:

• spawnImpact(world, x, y, color?) — 8 spark particles, default color (200, 200, 200), burst speed 30.
• spawnDeath(world, x, y, color?) — 20 spark particles, default color (255, 100, 0), burst speed 80.
• spawnHeal(world, x, y) — 12 spark particles, color (100, 255, 100), burst speed 40.
• spawnShieldHit(world, x, y) — 6 spark particles, color (100, 150, 255), burst speed 30.
• spawnStun(world, x, y) — 8 spark particles, color (255, 255, 100), burst speed 25.

All helpers spawn the 'spark' particle kind. Lifetime, size, and per-particle alpha are determined inside Particles.burst (lifetime randomized in [0.1, 0.35]s, size randomized in [1.0, 2.5]px for sparks, alpha 0.9).

Pattern notes

• Object-literal namespace pattern (export const ParticleHelpers = { ... }) rather than free functions, matching the style of the underlying Particles singleton.
• Each helper is a one-liner that forwards to Particles.burst. The only behavior is the choice of count/color/speed; this is intentional content-in-constants placement so designers can tune feel without touching call sites.
• The world parameter is currently unused inside the helpers but is part of the public signature so that callers can pass their existing world handle without conditional branches, and so that future variants can read world state without an API break.
• Color overrides on spawnImpact and spawnDeath allow callers (e.g., per-enemy tinted death bursts) to recolor without duplicating the helper.
• All effects share the 'spark' kind, so they participate in the underlying particle pool (POOL_MAX = 600) and respect the CFG.MAX_PARTICLES * 0.8 soft cap that Particles.add applies to sparks and smoke.