particles-router

Particles Router

Routes to 3 specialized particle system skills based on task requirements.

Routing Protocol

1. Classify — Identify particle effect type and scale
2. Match — Find skill(s) with highest signal match
3. Combine — Most particle systems need 2-3 skills together
4. Load — Read matched SKILL.md files before implementation

Quick Route

Tier 1: Core (Always Consider)

Task Type	Skill	Primary Signal Words
Rendering	particles-gpu	points, instanced, buffer, shader, thousands, performance
Motion	particles-physics	gravity, wind, attract, force, velocity, turbulence, collision
Spawning	particles-lifecycle	emit, spawn, fade, trail, pool, birth, death, age

Signal Matching Rules

Priority Order

When multiple signals present, resolve by priority:

1. Performance concern — "millions of particles" → particles-gpu first
2. Motion type — "swirling", "attracted to" → particles-physics
3. Emission pattern — "burst", "continuous", "trails" → particles-lifecycle
4. Default — All three skills usually needed together

Confidence Scoring

• High (3+ signals) — Route immediately
• Medium (1-2 signals) — Include all three skills (typical)
• Low (0 signals) — Ask: "Describe the particle effect you want"

Common Combinations

Basic Particle System (All 3 skills)

particles-gpu       → Buffer setup, shader rendering
particles-physics   → Gravity, basic motion
particles-lifecycle → Emission, fade out

Wiring: GPU provides rendering foundation, lifecycle handles spawning/death, physics adds motion.

Snow/Rain Effect (3 skills)

particles-gpu       → Points with texture
particles-physics   → Gravity, wind, turbulence
particles-lifecycle → Continuous emission, recycling

Wiring: Lifecycle emits continuously, physics handles falling + drift, GPU renders efficiently.

Explosion (3 skills)

particles-gpu       → Instanced or points rendering
particles-physics   → Radial velocity, drag
particles-lifecycle → Burst emission, fade + shrink

Wiring: Lifecycle bursts particles, physics applies outward force + slowdown, GPU handles scale.

Fire/Smoke (3 skills)

particles-gpu       → Custom shader with noise
particles-physics   → Upward force, turbulence
particles-lifecycle → Continuous emit, color gradient, size over life

Wiring: Lifecycle manages color/size curves, physics adds flicker motion, GPU renders with blend modes.

Swarm/Flock (2-3 skills)

particles-gpu       → Instanced mesh (if 3D shapes)
particles-physics   → Attractors, flow fields, separation
particles-lifecycle → (Optional) Population management

Wiring: Physics dominates with behavioral forces, GPU handles rendering.

Magic Trail (3 skills)

particles-gpu       → Points with glow shader
particles-physics   → Follow path, slight randomness
particles-lifecycle → Trail history, fade along length

Wiring: Lifecycle stores position history, GPU renders with alpha gradient.

Confetti (3 skills)

particles-gpu       → Instanced flat planes
particles-physics   → Gravity, tumbling rotation, air resistance
particles-lifecycle → Burst emission, ground collision death

Wiring: Physics handles realistic falling, lifecycle manages burst and cleanup.

Decision Table

Effect Type	GPU Focus	Physics Focus	Lifecycle Focus
Stars/sparkle	Points, static	Minimal	Twinkle (alpha)
Snow/rain	Points, texture	Gravity, wind	Continuous, recycle
Fire	Shader, blend	Upward, turbulence	Color/size curves
Explosion	High count	Radial, drag	Burst, fade
Smoke	Soft shader	Rise, curl	Slow fade, grow
Swarm	Instanced	Attractors, fields	Spawn/death
Trail	Line or points	Path following	Position history
Dust	Small points	Brownian	Random spawn

Particle Count Guidelines

Count	Approach	Skills Priority
< 100	Simple, any approach	lifecycle > physics > gpu
100 - 1,000	Points or instanced	All equal
1,000 - 10,000	GPU-focused	gpu > physics > lifecycle
10,000 - 100,000	GPU essential	gpu >> physics (shader) > lifecycle
> 100,000	Full GPU/compute	gpu only, physics in shader

Skill Dependencies

particles-gpu (rendering foundation)
├── particles-physics (motion layer)
└── particles-lifecycle (management layer)

• particles-gpu is always needed for rendering
• particles-physics and particles-lifecycle are independent but complementary
• For simple effects, you might skip physics OR lifecycle, rarely both

Fallback Behavior

• Unknown effect → Start with all three skills
• Performance issues → Focus on particles-gpu optimization
• Motion problems → Deep-dive particles-physics
• Spawning/timing issues → Focus on particles-lifecycle

Quick Decision Flowchart

User Request
     │
     ▼
┌─────────────────────────┐
│ Rendering particles?    │──Yes──▶ particles-gpu (always)
└─────────────────────────┘
     │
     ▼
┌─────────────────────────┐
│ Movement/forces needed? │──Yes──▶ + particles-physics
└─────────────────────────┘
     │
     ▼
┌─────────────────────────┐
│ Birth/death/emission?   │──Yes──▶ + particles-lifecycle
└─────────────────────────┘
     │
     ▼
Most effects need all 3 skills

Effect Recipes

Quick Start Templates

Effect	Start With
Ambient dust	gpu (points) + lifecycle (continuous)
Button sparkle	gpu (points) + lifecycle (burst, fade)
Character trail	gpu + lifecycle (trail)
Weather	All three
Magic spell	All three
Data visualization	gpu + lifecycle

Integration with Other Domains

Combined With	Use Case
shader-noise	Turbulent motion, organic shapes
shader-effects	Glow, chromatic aberration on particles
r3f-performance	Optimization, culling, LOD
gsap-fundamentals	Scripted particle animations
audio-reactive	Music-driven particle effects

Reference

See individual skill files for detailed patterns:

• /mnt/skills/user/particles-gpu/SKILL.md
• /mnt/skills/user/particles-physics/SKILL.md
• /mnt/skills/user/particles-lifecycle/SKILL.md