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.
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:
Emotion
Rotation
Particles
Camera
Color
Threads
Stillness
delta * 0.02
low opacity, scattered
tight (r=20)
cool dominant
0
Tension
accelerating
contracting toward center
steady
warm intensifying
few, brightening
Intimacy
delta * 0.05
tight orbit (r=6), warm
close (r=18)
warm dominant
many, bright
Vastness
delta * 0.03
wide scatter, dim
far (r=50+)
cool dominant
sparse
Release
decelerating
rapid expansion
pulling back
desaturating
dissolving
Arrival
near-still
assembling from void
approaching
cool warming
emerging
Vary lerp rates between phases. The void is slow (0.008). Awakening accelerates (0.05). Conversation settles (0.03).
Composition Parameters
Parameter
Range
Default
Effect
particleCount
100-5000
1200
Particle field density
phaseCount
2-10
6
Narrative phases
cycleDuration
30-180s
90
Total cycle length
latticeGeometry
icosahedron/dodecahedron/octahedron/torus/none
concept-derived
Structural anchor
latticeSubdivision
1-4
2
Lattice complexity
coolColor
hex
concept-derived
Cool spectrum end
warmColor
hex
concept-derived
Warm spectrum end (must contrast cool)
backgroundColor
hex
#050508
Scene background (never pure black)
words
string[]
concept-derived
Labels for inspectable particles
threadCount
0-200
60
Connection threads between nodes
starCount
0-10000
2000
Background star density
cameraRadius
5-100
25
Default camera distance
fogDensity
0-0.05
0.012
Atmospheric fog
font
string
concept-derived
Display font
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
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.
Visual
Curve
Best For
Infinity loop
Lemniscate
Classic loading indicator
Flower/star
Rose curve
Organic, natural feel
Geometric loops
Spirograph
Playful, complex patterns
Figure-8 variants
Lissajous
Technical, oscilloscope aesthetic
Simple ring
Circle
Minimal, universal
Multi-arm
Triskelion
Dynamic, energetic
Romantic
Heart curve
Themed/branded loaders
3D particle cloud
Sphere
Data processing, heavy computation feel
Expanding coil
Spiral (Archimedean)
Progress, unwinding, search
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
Parameter
Default
Effect
tubularSegments
300
Tunnel mesh resolution
radius
10
Tunnel half-width
pointSpacing
20
Distance between path control points
imageDensity
0.6
Probability a ring spawns images
maxImagesPerRing
3
Spawn count per active ring
gridScale
(20, 1)
Wireframe grid density (length × width)
fogStart / fogEnd
50 / 300
Wireframe-to-bg fade distance
scrollSpeed
0.15
Wheel delta multiplier
scrollEasing
0.08
Smooth interpolation factor
theme
"dark"
Dark/light invert
fx
"none"
Set to "phosphor-vigil" for CRT
imageSource
(seed) => url
URL generator for seed mode
images
null
Static manifest — when non-null, cycled
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
Parameter
Default
Effect
modelUrl
Parrot.glb (jsdelivr)
Any rigged glTF/glb
specimenCount
3
Instance count
behaviors
["followMouse","wander","wander"]
Per-instance behavior
scales
[0.020, 0.018, 0.022]
Per-instance scale
colorShifts
[0, 0.6, 0.05]
HSL emissive tints
flapSpeed
i => 2 + 0.3*i
Per-instance animation timeScale base
releaseDecayTime
0.8s
Follow-blend decay when mouse leaves
mobileScale
0.65
Down-scale on ≤768px screens
fx
"phosphor-vigil"
Default on — the trails are the scene
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.
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
Flag
Options
Default
Effect
--label-text
any string
"VINYL"
Main text on A/B side labels
--label-subtitle
any string
""
Secondary text below main label
--label-style
warm / cool / monochrome
warm
Radial gradient palette
--groove-preset
fine / standard / deep
standard
Groove count, depth, width
--scratch-intensity
none / light / heavy
heavy
Surface scratch density
--sections
1–5
3
Scroll keyframes
--audio
none / crackle-only / full
crackle-only
Audio engine scope
--audio-url
MP3 URL
—
Music for --audio full
--theme
dark / light
dark
Page theme
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.
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
Parameter
Default
Effect
preset
"chromatic-prism"
Material preset: clear-crystal, frosted-opal, chromatic-prism
pieceCount
5
Number of glass fragments
gap
0.045
Space between panes
cornerRadius
0.045
Fragment rounding
paneDepth
0.040
Glass thickness (geometry)
hoverTilt
0.36
Rotation response to cursor
hoverRadius
1.95
Influence zone size
hoverCellPush
1.04
Z-displacement on hover
hoverEase
4.0
Animation smoothing
parallax
1.90
Depth response to cursor
flyDuration
0.90
Entry animation time (seconds)
flyDirectionDeg
60
Entry animation angle
bloomStrength
0.05
Bloom glow intensity
bloomRadius
1.80
Bloom spread
bloomThreshold
1.10
Bloom brightness cutoff
backgroundColor
#0a0a0c
Scene background
accentColor
#57FFA8
Mint — CTA/link hover
secondaryColor
#A78BFA
Violet — secondary actions
font
"Geist"
Display font (+ Space Grotesk for controls)
Material Presets
Preset
IOR
Dispersion
Roughness
Iridescence
Feel
clear-crystal
1.5
0.1
0.05
0.0
Clean, sharp, minimal distortion
frosted-opal
1.8
0.3
0.7
1.0
Soft, diffused, rainbow-shifted
chromatic-prism
2.14
0.415
0.41
1.0
Maximum drama — the Glass Hero default
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.
Scatter N random seed points within the hero rectangle
Run Lloyd relaxation (4 iterations) for even distribution
Compute Voronoi cells, clip to hero bounds
For each cell: extrude polygon to paneDepth, apply cornerRadius
Create MeshPhysicalMaterial with preset values, assign to each mesh
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.
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 = newPhosphorVigil(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.
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
