particles-router

name	particles-router
description	Decision framework for particle system projects. Routes to specialized particle skills (gpu, physics, lifecycle) based on task requirements. Use when building particle effects or needing guidance on which particle techniques to combine.

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