Skip to content

GUIDES.md

Latest commit

 

History

History
89 lines (69 loc) · 3.19 KB

GUIDES.md

File metadata and controls

89 lines (69 loc) · 3.19 KB
Raw

Development Guides

Adding a New Track

To add a new track to the visualizer, you must update the configuration in everything-is-visualized-worker.js and upload assets to R2.

1. Update Worker Configuration

In everything-is-visualized-worker.js, add an entry to the TRACKS object:

TRACKS['newtrack'] = {
  name: 'NewTrack',
  bpm: 128,
  key: 'A Major',
  symbol: 'Nt',
  color: '#00ff00',
  length: '4:30',
  master: '8.NewTrack_Master.m4a',
  images: ['NewTrack-Symbol-1000x1000.png', 'NewTrack-1000x1000.png'],
  geometry: { name: 'Sphere', icon: '<svg>...</svg>' },
  particleEffects: [0, 5, 10, 15] // 4 indices from the 28 available modes
};

2. Infrastructure Setup

  1. R2 Binding: Create a new R2 bucket binding in Cloudflare named NEWTRACK (all caps).
  2. Upload Assets: Upload the .m4a and .png files directly to the new bucket.
  3. Flat Bucket: Assets are served via filename lookup only; do not include folder paths in the bucket.

Adding New Phases or Effects

The visualizer uses a Modular ES6 Registry for shader injection and double-buffered scene handling.

1. Add a New Effect Property

Step 1: Register in EFFECT_KEYS

File: modules/visualizer-config-effects.js Add your new effect name to the EFFECT_KEYS array and a default value to EFFECT_DEFAULTS.

Step 2: Implement Shader Logic

Choose the appropriate registry file:

  • Vertex (Displacement): modules/visualizer-shader-vertex.js
  • Fragment (Color/Post): modules/visualizer-shader-fragment-core.js
  • Phase (Specific): modules/visualizer-shader-phases.js

Example:

shaderRegistry.registerVertex('yourEffect', 'displacement', `
  if (uEffects[getIdx('yourEffect')] > 0.01) {
    float strength = uEffects[getIdx('yourEffect')];
    pos += normal * sin(pos.y * 10.0 + uTime) * strength;
  }
`);

Always use getIdx('effectName') for index safety. The registry automatically injects this code into the main shader during scene initialization.

2. Add a New Phase

Step 1: Add to PHASE_NAMES

File: modules/visualizer-config-phases.js

Step 2: Add Configuration to PHASE_CONFIG

{
  name: 'YOUR_PHASE',
  renderMode: 'standard',     // Options: low_poly, translucent, particles_only, etc.
  yourEffect: 1.0,            // Intensity
  motionMode: 0,              // 0-26
  cameraMode: 'standard',     // Options: macro, observer, etc.
  colorMode: 5,               // 0-5
  speed: 0.005,               // Base animation speed
  camZ: 3.5                   // Camera distance
}

Step 3: Add to Phase Pool

Add the name to SHARED_PHASES or a specific track in TRACK_PHASES.

Technical Standards

  • GC FREE: Reuse all THREE.Vector3 and THREE.Euler objects at module scope. Use Math.exp or Math.pow for frame-rate independent smoothing.
  • No build step: All imports must use the .js extension. No npm packages.
  • Scene Isolation: Do not share state between VisualizerScene instances. The TransitionManager handles visual blending.
  • Audio Reactivity: Use uAudioHistory for frequency history. Bass and Treble are pre-smoothed in the AudioController (see visualizer-audio.js).