Particle Swarm Simulator

Generate massive particle swarm simulations with a clean separation of concerns: a host runtime handles Three.js rendering, camera, input, gesture recognition, and security — the AI writes only a behavior function body that positions and colors 20,000+ particles per frame.

Not a narrative canvas. Not a phase engine. A sandbox where math becomes motion.

Quick Start

# Generate a sandbox runtime with gesture controls
/particle-swarm-sim --mode sandbox dark theme, 30K particles, gesture OS enabled

# Generate a sim function body
/particle-swarm-sim --mode sim aurora borealis — curtains of light flowing along magnetic field lines

# Generate from preset
python3 scripts/swarm_generator.py --mode sim --preset galaxy-spiral --output galaxy.js

The Separation of Concerns

HOST RUNTIME                          BEHAVIOR FUNCTION BODY
(sandbox-runtime.html)                (generated by AI)
                                      
Three.js scene                        target.set(x, y, z)
BufferGeometry (20K particles)   -->  color.setHSL(h, s, l)
Camera + input + gesture OS           addControl("speed", ...)
Security validator                    setInfo("title", ...)
Code injection pipeline               annotate("label", ...)
Dynamic controls UI                   
HUD + annotations                    

The host calls the function body 20,000 times per frame — once per particle. The function body mutates the provided target and color objects. Nothing else crosses the boundary.

API Contract

Read-Only Variables

Write-Only Variables

Helper Functions

For setInfo and annotate: call only when i === 0. Calling per-particle creates 20,000 DOM updates per frame. The annotate function takes numeric coordinates (not a Vector3) to avoid per-frame allocations.

Full specification: references/api-contract.md

Mode: sandbox

Generate the complete host runtime HTML — the sandbox that executes behavior function bodies.

Configuration

Architecture

init() --> createScene() --> createParticles(count) --> setupCamera() --> setupInput()
                                                                           |
                                      setupGestureOS() --> setupInjection() --> setupHUD()
                                                                           |
animate() <-- requestAnimationFrame <-- executeSimFunction() --> updateBuffers()
    |
Per frame: for (i = 0; i < count; i++) { simFn(i, count, time, THREE, target, color, ...) }
    |
geometry.attributes.position.needsUpdate = true
geometry.attributes.color.needsUpdate = true

Templates

Full architecture: references/sandbox-architecture.md

Mode: sim

Generate particle behavior function bodies from creative concepts. Output is a JS function body — no HTML, no Three.js setup. The body gets injected into a sandbox runtime.

Concept-to-Form

Sim Presets

Galaxy Spiral — Logarithmic arms with density wave theory. i % arms grouping. HSL from arm index + distance falloff. Controls: arm count (2-8), spin rate, thickness. Reference: assets/sims/galaxy-spiral.js

DNA Helix — Double helix with base pair rungs. i % 3 splits into strand A, strand B, rungs. Controls: helix radius, pitch, rung density. Reference: assets/sims/dna-helix.js

Murmuration — Boids-like flocking approximated via phase-shifted oscillators. No neighbor search, no arrays — purely mathematical. Controls: flock radius, speed, coherence. Reference: assets/sims/flocking-murmuration.js

Torus Knot Flow — Particles trace a (p,q) torus knot with index-based phase offset. HSL from progress along the knot. Controls: p, q, flow speed.

Lorenz Attractor — Time-stepped Lorenz system positions, particle index as time offset. Color from z-height. Controls: sigma, rho, beta.

Reaction-Diffusion Shell — Cone-shaped shell with Turing-like stripe patterns computed analytically. Controls: wavelength, cone aperture.

Full gallery with math breakdowns: references/sim-gallery.md

Minimal Valid Sim

const speed = addControl('speed', 'Speed', 0.1, 5.0, 1.0);
if (i === 0) setInfo('Expanding Sphere', 'Uniform distribution on sphere surface');

const phi = (i / count) * Math.PI * 2 * 10;
const theta = Math.acos(1 - 2 * (i / count));
const r = 10 + Math.sin(time * speed + i * 0.01) * 2;

target.set(
  r * Math.sin(theta) * Math.cos(phi),
  r * Math.sin(theta) * Math.sin(phi),
  r * Math.cos(theta)
);
color.setHSL(i / count, 0.8, 0.5 + 0.2 * Math.sin(time + i * 0.1));

Performance Rules

This function runs 20,000 times per frame at 60fps = 1,200,000 calls per second.

Full performance patterns: references/performance-patterns.md

Security Sandbox

All behavior function bodies must pass validation before execution.

Forbidden Patterns

Validation Pipeline

1. Regex scan — Reject if any forbidden pattern matches
2. Syntax check — Parse as function body
3. Dry-run (runtime only) — Execute with mock values for 3 frames, check for throws and non-finite output

The Python validator (scripts/validate_sim.py) handles steps 1-2. Step 3 happens client-side in the sandbox runtime.

Full specification: references/security-sandbox.md

Gesture OS

Hand gesture camera controls via MediaPipe Hands. Optional — mouse/touch always works.

Configuration:

• maxNumHands: 1
• modelComplexity: 0 (fast mode)
• Detection runs every 3rd frame to reduce CPU load
• Dead zones prevent jitter near gesture boundaries

Full implementation: references/gesture-os.md

Generator

# Full sandbox with gesture controls
python3 scripts/swarm_generator.py --mode sandbox --particles 30000 --gesture --output sandbox.html

# Minimal sandbox for embedding
python3 scripts/swarm_generator.py --mode sandbox --minimal --output embed.html

# Sim from preset
python3 scripts/swarm_generator.py --mode sim --preset galaxy-spiral --output galaxy.js

# Sim preset list
python3 scripts/swarm_generator.py --mode sim --list

Post-Generation QA

# Validate sandbox runtime
python3 scripts/validate_sandbox.py output.html

# Validate sim function body
python3 scripts/validate_sim.py output.js

Anti-Patterns

• Never allocate objects inside the function body — mutate target and color only
• Never use new THREE.Vector3() — use target.set(x, y, z)
• Never access DOM — the sandbox blocks it
• Never use var — const/let only
• Never use if/else chains for particle grouping — use modular arithmetic and trig
• Never leave division unguarded — always add epsilon (+ 0.0001)
• Never skip setInfo — every sim needs a title and description
• Never use duplicate addControl IDs — each must be unique
• Never call setInfo/annotate without i === 0 guard
• Never pass a Vector3 to annotate — use numeric (id, x, y, z, label) to avoid allocations
• Never use framework code in the sandbox — vanilla JS + HTML only
• Never use THREE.OrbitControls — implement spherical camera directly
• Never use pure black (#000000) — use #050508
• Never skip security validation before code injection

References