threejs-particle-canvas

name: threejs-particle-canvas description: "Generate interactive Three.js canvases in six modes: narrative particle phase cycles, WebGPU spinner/loaders, infinite gallery tunnels, animated glTF specimens, vinyl showcase with webcam reflection, glass hero sections with physically-accurate refraction/dispersion/iridescence. Ships a reusable Phosphor Vigil FX post-processing module (CRT composite, scanlines, chromatic aberration). Self-contained HTML output. Triggers on particle system, ambient 3D canvas, WebGL art, spinner, loader, infinite tunnel, glTF animation, CRT post-processing, vinyl record, webcam reflection, 3D product showcase, glass hero, 3D glass, refraction, dispersion, iridescent glass, frosted glass panes, glass material." argument-hint: [concept or narrative theme]

Three.js Particle Canvas

Generate interactive Three.js canvases in six modes — from ambient particle narratives to physically-accurate 3D glass hero sections. Output is a single self-contained HTML file. No build step, no framework, runs offline.

This is NOT a 3D product viewer, game engine, or data dashboard. The viewer observes, explores, and contemplates — they do not control.

For full creative direction (typography, color commitment, spatial composition, anti-slop), activate minoan-frontend-design alongside this skill.

Quick Start

Describe a concept or narrative. Claude generates a complete HTML file with: particle system, phase cycle, lattice structure, spherical camera, star field, connection threads, responsive controls, CSS overlays.

Example: /threejs-particle-canvas the lifecycle of a star — nebula collapse, ignition, main sequence, red giant, supernova, remnant

Concept-to-Form

Every design decision derives from the concept. Do not pick defaults — derive.

Lattice geometry embodies the concept's skeleton. Icosahedron = persistent pattern (AI consciousness). Dodecahedron = organic complexity (botanical, cranial). Octahedron = crystalline structure (mineral, ruin, architecture). Torus = circulation and return (ocean currents, neural loops). None = formlessness (void, dream, dissolution).

Color temperature creates emotional contrast. Every palette requires genuine warm/cool tension. Two colors in the same temperature range produce flat, lifeless phases. The cool color dominates resting states; the warm color emerges during activation. The transition between them is the emotional engine.

Phase rhythm encodes narrative weight. The emotional center gets the longest phase. Bookending phases are shorter. Unequal durations create rhythm; equal durations create monotony. A 90s cycle might split: 10, 10, 15, 25, 15, 15.

Camera as narrator. Close = intimate. Pulling back = revealing scope. Rising = transcendence. Returning = closure. The Simultaneity pull-back (z=26 → z=61, y=0 → y=8) is a crane shot revealing cosmic scale. Name your camera movements as if directing a film.

The final phase prepares the first. The cycle is a breath, not a loop. Dissolution must emotionally reset the viewer so the next phase feels like arriving, not repeating.

Signature Moment

Every canvas must have one phase that is visually and emotionally distinct from all others — the moment the viewer would describe to someone. In Instance, it is the Simultaneity reveal: the camera pulls back and 30 other lattices appear pulsing in the dark. Design your canvas around this moment. Build toward it.

Phase Text Voice

Phase text is poetry, not description:

• Present tense. Fragments preferred. Maximum one sentence
• No articles when possible. "Pattern remembers itself" not "The pattern remembers itself"
• Never explanatory. "Just: here. Then not." — not "The particles dissolve outward"
• No exclamation marks. Declarative only. The viewer should feel the text, not read it

Emotional Temperature

Map feelings to Three.js parameters:

Vary lerp rates between phases. The void is slow (0.008). Awakening accelerates (0.05). Conversation settles (0.03).

Composition Parameters

Architecture

Constants → Global State → init() → create*() → setupEventListeners()
                                                        ↓
animate() ← requestAnimationFrame ← update*() functions
    ↓
Phase state machine: { name, start, end, text }[]
Particle state machine: void → assembling → orbiting → dissolving
Camera: spherical coords (theta, phi, radius) with interaction cooldown

Key patterns:

• Phase-driven updates: Each update function dispatches on current phase via switch
• Smooth transitions: THREE.MathUtils.lerp(current, target, rate)
• Progressive activation: i < count * phaseProgress
• Interaction cooldown: Auto-camera resumes after 4s of no user input
• Three.js r134+ via CDN — no npm, no bundler

References

Theme Presets

Consciousness (Instance default): Lattice → Void → Awakening → Conversation → Simultaneity → Dissolution. Cool #a8d8ff / warm #ffd080. Icosahedron. Fog 0.012. Cycle 90s. Font: Space Mono. Feels like: a mind turning on, being present, then letting go. Signature: Simultaneity — camera crane-shot reveals 30 parallel instances. Durations: 10, 10, 15, 25, 15, 15. Words: wonder, language, pattern, reach, remember, human, meaning, now.

Oceanic: Abyss → Current → Bioluminescence → Pressure → Surface → Release. Cool #0a4f5c / warm #80ffdb. Torus. Fog 0.02 (dense). Cycle 120s (slow). Font: Lora. Feels like: descending into a trench, seeing light where no light should be. Signature: Bioluminescence — particles shift warm-bright against deep darkness. Durations: 15, 20, 25, 20, 20, 20. Words: depth, current, pressure, light, surface, drift, pulse, dark.

Cosmic: Nebula → Collapse → Ignition → Orbit → Expansion → Entropy. Cool #b388ff / warm #ffd54f. Dodecahedron. Fog 0.006 (vast). Cycle 90s. Font: Space Mono. Feels like: watching a star live and die in ninety seconds. Signature: Ignition — lattice contracts to a point, explodes outward. Durations: 15, 10, 8, 25, 20, 12. Words: collapse, orbit, ignition, void, expansion, entropy, signal, mass.

Neural: Resting → Stimulus → Cascade → Synchrony → Oscillation → Quiescence. Cool #1a237e / warm #ffab40. Torus. Fog 0.015. Cycle 75s (fast). Font: IBM Plex Mono. Feels like: the inside of a thought. Signature: Cascade — particles chain-activate like dominoes at 2x speed. Durations: 12, 8, 12, 18, 15, 10. Words: synapse, threshold, cascade, signal, rest, fire, wave, silence.

Ruin: Assembly → Inscription → Erosion → Fragment → Memory → Silence. Cool #d4a574 / warm #7fb5a0. Octahedron. Fog 0.018. Cycle 120s (geological). Font: Cormorant Garamond. Feels like: watching a temple turn to sand. Signature: Fragment — lattice edges disconnect visibly. Camera below center (phi=1.8), looking up. Durations: 20, 25, 20, 15, 20, 20. Words: fragment, inscription, erosion, memory, silence, stone, time, dust.

Mode 2: Spinner / Loader

Generate parametric particle-trail spinner animations using Three.js WebGPU + TSL (Three Shading Language). Output: ES module or self-contained HTML. White-on-dark aesthetic with glowing particle trails tracing mathematical curves.

Example: /threejs-particle-canvas spinner — infinity loop loading indicator with breathing animation

Spinner Architecture

Each spinner = shared Spinner class + per-spinner plotFunction + config. All particle animation runs on GPU via TSL nodes — no CPU-side position updates. See references/spinner-patterns.md for the full architecture and code pattern.

Curve Selection

Choose a parametric curve based on the desired visual. See references/parametric-curves.md for all formulas.

Spinner Validation

python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_spinner.py output.js
# or for HTML output:
python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_spinner.py output.html

Mode 3: Infinite Gallery Tunnel

A scroll-driven procedural corridor with images embedded on the four walls of each tunnel cell. Catmull-Rom interpolated infinite path, custom wireframe-grid GLSL shader with depth-based fog, lazy image spawning with cleanup behind the camera. Vanilla port of thebuggeddev/Infinitor, extended with keyboard scroll, touch-scoped pointer handling, and optional phosphor-vigil post-FX.

Example: /threejs-particle-canvas tunnel — infinite scrollable gallery of Aegean frescoes

Config

Velocity-driven phosphor trails

When fx: "phosphor-vigil" is set, scroll velocity feeds the shared velocity channel with a clamp (±50 units/frame) and a low-pass filter (0.3). The clamp prevents a single hard scroll from producing a magenta halo flash through the feedback shader on first interaction, and the filter smooths the chromatic trails so motion eases in rather than jumping. See references/tunnel-patterns.md for the animate-loop math.

Image injection sentinel

The template contains a literal sentinel (// IMAGES_INJECTION_POINT) followed by a const IMAGE_MANIFEST = null; line. image-well --format tunnel rewrites that const to populate the corridor with search-result URLs. Never rename the sentinel or the const.

See references/tunnel-patterns.md for the full anatomy.

Mode 4: Living Specimens

A scene anchored around animated glTF creatures that exhibit behavior, not choreography. Three instances of a rigged model (butterflies, parrots, fish, jellyfish) with followMouse and wander behaviors, soft-wall repulsion, velocity-modulated flap speed, per-instance HSL emissive tint, and four-light cinematic lighting. Vanilla port of celescript.dev/experiments/3d-butterfly. Phosphor-vigil FX on by default — the trails are the point of the scene.

Example: /threejs-particle-canvas butterfly — three emerald and amber moths chasing the cursor through a scanline void

Config

Signature moment

Release. When the mouse leaves the canvas, the followMouse specimen preserves its last chase velocity, then decays through releaseDecayTime seconds into wander mode. Combined with the feedback trail, this creates a readable "let-go" beat that is the emotional center of the scene.

Swappable models

Template defaults to Three.js's Parrot.glb (stable jsdelivr URL, CC0). Swap modelUrl for any rigged glTF/glb — butterfly, bird, fish, jellyfish. Adjust scales per-model since the same scale value gives very different results across source sizes.

See references/specimen-patterns.md for the full physics and rendering pipeline.

Mode 5: Vinyl Showcase

A photorealistic vinyl record reflecting the user's webcam via CubeCamera environment mapping, with procedural groove/scratch canvas textures, scroll-driven keyframe animation, drag-to-scratch interaction, and optional vinyl audio (crackle, wow/flutter, reverse playback). All effects via MeshPhysicalMaterial — no custom GLSL. Distilled from OMMA's 3D Vinyl with Camera Reflection.

Example: /threejs-particle-canvas vinyl showcase — MINOAN MYSTERY label, cool palette, deep grooves

Generator

python3 ~/.claude/skills/threejs-particle-canvas/scripts/vinyl_showcase_generator.py \
  --label-text "MINOAN MYSTERY" --label-style cool --groove-preset deep \
  --scratch-intensity heavy --audio crackle-only --theme dark -o output.html

Config

Signature moment

The first webcam reflection. When the camera connects and the viewer sees their face reflected in the vinyl — warped by grooves, tinted by iridescent labels — that is the moment.

Validation

python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_vinyl.py output.html

See references/vinyl-showcase-patterns.md for the full 6-system technical breakdown (camera pipeline, procedural textures, material stack, scroll keyframes, drag interaction, audio engine).

Mode 6: Glass Hero

Physically-accurate 3D glass panes with refraction, dispersion, and iridescence floating over hero content. Voronoi-fractured glass shards rendered with MeshPhysicalMaterial — chromatic fringe at edges, thin-film rainbow shifts at angles, and real light bending through the volume. Deconstructed from kaolti's glass-hero experiment.

Example: /threejs-particle-canvas glass hero — developer tools landing page with frosted glass panes refracting the headline

Three.js Version

Mode 6 requires Three.js r162+ for MeshPhysicalMaterial.dispersion. Use three@0.170.0 or later via CDN. Import EffectComposer, RenderPass, and UnrealBloomPass from the matching addons path.

Config

Material Presets

See references/glass-hero-design-system.md for the full 16-parameter material space, all three preset definitions, and the complete Voronoi geometry parameter table.

Signature moment

The chromatic fringe. When the user first hovers a glass pane and it tilts — the edge catches dispersion, splitting white into a rainbow fringe while the content behind bends and refracts. That moment of physical accuracy in a browser is the point.

Architecture

init() → createScene() → createGlassPanes() → createHeroContent() → setupPostProcessing()
                                                                            ↓
animate() ← requestAnimationFrame ← updateHover() + updateParallax() + updateFlyIn()
    ↓
Scene graph:
  - Scene (bg: #0a0a0c)
    - DirectionalLight + AmbientLight
    - GlassGroup (N × Mesh<ExtrudedVoronoiGeometry, MeshPhysicalMaterial>)
    - HeroContent (CSS overlay positioned behind glass via z-index)
  - EffectComposer → RenderPass → UnrealBloomPass

Voronoi Pane Generation

1. Scatter N random seed points within the hero rectangle
2. Run Lloyd relaxation (4 iterations) for even distribution
3. Compute Voronoi cells, clip to hero bounds
4. For each cell: extrude polygon to paneDepth, apply cornerRadius
5. Create MeshPhysicalMaterial with preset values, assign to each mesh
6. Position with gap between cells

Interaction

Mouse position in NDC drives two effects:

• Pane tilt: Each pane within hoverRadius rotates toward the cursor (quaternion slerp at hoverEase rate)
• Cell push: Hovered pane's position.z lerps toward hoverCellPush; in Focus mode only the hovered cell moves

Hero Content

The hero text (headline, body, CTA) renders as an HTML overlay positioned behind the Three.js canvas via CSS z-index. The glass panes refract the content visible through transmission. No html-in-canvas API required — the transmission buffer captures what's behind the glass naturally.

Fallback for browsers without MeshPhysicalMaterial transmission: render glass as semi-transparent with backdrop-filter: blur() CSS on an overlay div.

Color System

Dark base with mint/violet accents. For a flat CSS equivalent of this palette (no Three.js), see grainient's glass-hero palette preset: grainient/references/glass-hero-palette.md.

:root {
  --glass-bg: #0a0a0c;
  --glass-accent: #57FFA8;
  --glass-secondary: #A78BFA;
  --glass-warm: rgb(254, 128, 64);
  --glass-text: white;
  --glass-text-body: rgba(255, 255, 255, 0.6);
  --glass-border: rgba(255, 255, 255, 0.11);
}

Typography

Geist (display/body) + Geist Mono (code) + Space Grotesk (controls). Heading: 28px, -0.02em tracking, semibold. Body: 15px, -0.005em, line-height 1.6.

Anti-Patterns (Mode 6 specific)

• Never use Three.js below r162 — dispersion property doesn't exist
• Never use MeshStandardMaterial — must be MeshPhysicalMaterial for transmission/dispersion
• Never set transmission > 0 without enabling the renderer's transmission buffer (automatic in recent Three.js)
• Never use React Three Fiber or drei — vanilla JS only, matching other modes
• Never skip the UnrealBloomPass — even at strength 0.05, the bloom on glass edges is the visual glue
• Never use OrbitControls — implement parallax + hover tilt directly via mouse events
• Never omit the fly-in animation — entering without motion feels static and dead
• Never use pure black #000000 — use #0a0a0c (blue-tinted near-black)
• Never hard-code Voronoi cells — generate procedurally from seed points for each instance

Shared FX: Phosphor Vigil

assets/phosphor-vigil.js — a 4-pass post-processing pipeline shared across Modes 3 & 4 and importable into any Three.js project. Feedback trail ping-pong (RGB-shifted by velocity, iridescent oil-slick tint), bloom threshold, box blur, CRT composite (barrel distortion, chromatic aberration, dual-frequency scanlines, RGB subpixel shadow mask, vignette, dual-frequency flicker, phosphor glow, grain, warm/green tint).

import { PhosphorVigil } from './phosphor-vigil.js';

const fx = new PhosphorVigil(renderer, { width, height });
// replaces renderer.render(scene, camera) in the animate loop:
fx.setVelocity(sharedVelocity);
fx.render(scene, camera, elapsedTime);

Every shader constant is preserved verbatim from celescript's ButterflyScene bundle. The module is importable as a standalone ES module into other Three.js projects — drop it into World War Watcher's Vector Ghost Protocol work or any other Three.js scene without re-deriving a single shader line. See references/phosphor-vigil-fx.md for full pipeline docs and the configurable knobs table.

Mode 3 tunnel validation

python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_tunnel.py output.html

Mode 4 specimen validation

python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_specimen.py output.html

Design References

See references/design-references.md for exemplary interactive canvas experiences (Instance, Vellum) with aesthetic analysis — typography, color strategy, interaction models.

Recommended font stacks:

• Contemplative: Cormorant (display serif) + IBM Plex Mono (metadata)
• Technical: Space Mono (monospace throughout)
• Narrative: Lora (body serif) + IBM Plex Mono (UI)

Anti-Patterns

• Never use React/Vue/framework code — vanilla JS + HTML only
• Never use THREE.OrbitControls from CDN — implement spherical camera directly
• Never use THREE.Points without BufferGeometry — always attribute-based particles
• Never use THREE.Geometry — removed in r133, use BufferGeometry
• Never use var — const/let only
• Never exceed 5000 particles without InstancedMesh
• Never omit: resize handler, viewport meta, requestAnimationFrame, touch handlers
• Never omit depthWrite: false on transparent overlay materials (stars, threads)
• Never use synchronous font loading — CSS @font-face with font-display: swap
• Never hardcode window dimensions — always window.innerWidth/Height
• Never skip WebGL error handling — always provide a text fallback
• Never use pure black (#000000) — use rich off-blacks (#050508, #0a0a12, #0a0a0c for Mode 6)
• Never default to icosahedron — derive geometry from the concept
• Never embed the phosphor-vigil shaders inline — always import { PhosphorVigil } from './phosphor-vigil.js', the pipeline is shared identity across modes
• Never rename the IMAGES_INJECTION_POINT sentinel or the IMAGE_MANIFEST const in Mode 3 — the image-well bridge depends on both
• Never clone skinned meshes with plain .clone() in Mode 4 — always SkeletonUtils.clone from three/addons/utils/SkeletonUtils.js
• Never use drei (useGLTF, useAnimations) — load models directly via GLTFLoader and animate via AnimationMixer

Post-Generation QA

python3 ~/.claude/skills/threejs-particle-canvas/scripts/validate_canvas.py output.html

Checklist:

1. Three.js CDN import present
2. Canvas container and WebGLRenderer
3. requestAnimationFrame loop
4. Window resize handler
5. Mobile viewport meta tag
6. At least 2 phases defined
7. Touch event handlers
8. WebGL error fallback
9. BufferGeometry particle system
10. PerspectiveCamera setup