# Hypnotic Particle Tunnel — `particle-tunnel@1.0.0`

Fly forever through a twisting tunnel of colourful light streaks. A perfect loop.

Thousands of glowing streaks rush towards you down a slowly twisting tunnel, like hyperspace or a neon wormhole. Choose the colours, how fast you fly, how much it twists and how long the light trails are. The motion is designed so the end of the clip flows invisibly back into the start, so it can loop forever.

- Kind: effect; status: published; digest sha256:a563f6c7168273912c18a70e111abb4b2c50f8b28eec7102964750f95b1afd97
- Role: Full-frame animated background or hero effect (Canvas 2D layer).
- Implementation: canvas2d; entry `src/particle-tunnel.js`
- Files: https://aipixelwizard.com/registry/particle-tunnel/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/particle-tunnel.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/particle-tunnel/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/particle-tunnel/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness. src/particle-tunnel.js has no dependencies.

## Exports
- `createParticleTunnel({ count?, speed?, twist?, spiral?, hue?, hueRange?, hueCycles?, trail?, size?, seed?, center? }) => { draw(ctx, info, width, height) }` — Canvas 2D layer; draws additively over whatever is already on the canvas.

## Parameters
- `density` (integer 200–3000, default 1400) — Particles
- `speed` (integer 1–5, default 2) — Speed: Tunnel lengths flown per loop.
- `twist` (integer -2–2, default 1) — Twist: Turns per loop. Negative turns the other way.
- `hue` (number 0–360, default 265) — Colour: Starting hue on the colour wheel (0 red, 120 green, 240 blue).
- `colorSpread` (number 0–360, default 160) — Colour spread: 0 is one colour; 360 is the full rainbow.
- `colorCycles` (integer 0–3, default 0) — Colour cycling
- `trail` (number 0.005–0.2, default 0.06) — Trail length
- `seed` (integer 1–9999, default 11) — Variation
- `background` (color, default "#04030a") — Background

## Composition
- Inputs: Canvas 2D context, info.progress (0…1), canvas width and height.
- Outputs: Draws additive light streaks onto the canvas. Does not clear the canvas: fill your background first.
- Coordinates: Pixels. Vanishing point at center (fractions of width/height).
- Lighting: Additive ('lighter') blending; looks best on a dark background.
- Timing: Pure function of progress; any frame can be drawn out of order.
- Works with: kinetic-title, gradient-background, rolling-counter
- Layer text on top after calling draw (see Hypnotic Tunnel Title).

## Output and loop
- 1080×1080, 30 fps, 6 s, procedural
- Seamless loop: yes — Depth wraps by whole tunnel lengths, twist and colour complete whole cycles; state at progress 1 equals progress 0.
- Verified 2026-10-02 in Chrome 151.0.7922.137 headless on Linux 7.0.0-31-generic (x64), Node 22.14.0 (Canvas 2D); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a canvas, fill the background each frame, then call tunnel.draw(ctx, { progress: frame / totalFrames }, canvas.width, canvas.height).

Existing project: Copy src/particle-tunnel.js. In your existing frame loop, call draw after painting your background and before your foreground layers. If you use a WebGL or DOM scene, draw it to a separate 2D canvas behind your content.

Reuse ideas:
- Use it behind a Kinetic Title for an intro (see the Hypnotic Tunnel Title example).
- Set twist 0 and colour spread 0 for a calm white star-field background.
- Move the vanishing point (center option) off-centre for a dynamic side-on warp.

## Limitations
- 2D projection: the tunnel is always viewed straight down its axis.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License (see LICENSE in this folder).

Provenance: Original code written for AI Pixel Wizard in October 2026.