How the Bioluminescent Water Ripple & Procedural Koi Engine Works
Watching koi fish glide effortlessly through dark, mirror-still water while concentric ripples catch the glow of floating lanterns is a time-tested visual anchor for easing anxiety and restoring mental focus. Bioluminescent Koi & Ripple Pond combines a real-time 2D wave heightfield solver, multi-jointed fish spine kinematics, and a procedural Web Audio kalimba synthesizer in a single zero-dependency browser experience.
How to Interact With the Midnight Pond
- Drop Glowing Food Pellets: Click or tap anywhere on the pond surface. A warm bioluminescent pellet plops into the water, radiating concentric cyan-magenta interference waves and plucking a resonant pentatonic kalimba tine. Nearby koi immediately sense the ripple and steer smoothly toward the food.
- Swirl Bioluminescent Plankton Trails: Drag your finger or cursor across the water. Your movement disturbs hundreds of microscopic dinoflagellate plankton motes that glow neon aqua and violet in your wake while triggering a soft hydro-swish sound.
- Release Floating Lotus Lanterns: Click + Lotus Lantern in the bottom dock (or switch Tap Mode to Float Lotus Lantern) to place warm candle-lit blossoms that drift across the surface currents and gently repel passing ripples.
- Enter Fullscreen Landscape or Portrait Sanctuary: Click Fullscreen Landscape or Fullscreen Portrait at the top right to hide all adjustment sliders and expand the pitch-black pond across 100% of your screen.
Mathematical & Physical Models Under the Hood
Instead of playing pre-recorded video loops, every visual and acoustic element is computed live at 60 frames per second:
1. 2D Discrete Wave Propagation: u_next[x,y] = ((u[x-1,y] + u[x+1,y] + u[x,y-1] + u[x,y+1]) / 2 - u_prev[x,y]) × Damping (0.975)
2. Kinematic Spine Constraint (12 Segments): P_i = P_{i-1} - normalize(P_{i-1} - P_i) × Segment_Length + Lateral_Sinusoid(t, i)
3. Reynolds Arrival Steering Force: F_steer = clamp(Desired_Velocity - Current_Velocity, Max_Force)
2. Kinematic Spine Constraint (12 Segments): P_i = P_{i-1} - normalize(P_{i-1} - P_i) × Segment_Length + Lateral_Sinusoid(t, i)
3. Reynolds Arrival Steering Force: F_steer = clamp(Desired_Velocity - Current_Velocity, Max_Force)
Worked Example: Triggering the "Scatter Feast" Feeding Cascade
Click Scatter Feast (Load Example) in the floating pond dock to observe the multi-agent boid steering and pentatonic acoustics in action:
- Six glowing food pellets drop across the pond over a 900-millisecond cascade, playing an ascending C-major pentatonic kalimba arpeggio (
523.25 Hz → 587.33 Hz → 659.25 Hz → 783.99 Hz → 880.00 Hz → 1046.50 Hz). - Each koi evaluates the Euclidean distance $d = \sqrt{\Delta x^2 + \Delta y^2}$ to all active pellets and locks onto the closest unclaimed target, smoothly banking its 12-node spine curve and accelerating its tail beat frequency until it consumes the pellet with a soft water plop and burst of glowing particles.