Neolution & Grid Engine (Controller Support)

Live Demo Here - https://garebear99.github.io/Neolution/

Neolution Repo - https://github.com/GareBear99/Neolution

Bonus Song Included!

The Payment is for the engine backend grid concept math formula, with the Neolution working engine combined and deployed functionally. 

What Neolution is

Neolution is an 8-lane neon rhythm game set on a TRON-style perspective grid. It focuses on:

• deterministic chart generation from audio
• keyboard + controller support
• lightweight Canvas2D rendering
• sharp synthwave / arcade presentation
• a future path toward a full desktop release with progression, persistence, achievements, and Steam packaging

Current feature set

Rhythm gameplay

• 8-lane input matrix using arrows + WASD
• Difficulty range 0–4
• Deterministic chart generation from audio analysis
• Gamepad support with PlayStation-style lane mapping
• Looping and seed regeneration for repeated runs

Visual systems

• TRON-style perspective grid
• CPU-light Canvas2D renderer
• Real-time spectrum analyzer
• Waveform display
• Layered neon glow compositing

Audio systems

• Web Audio API analysis
• Custom song upload
• Playback timing offset slider
• Realtime energy-based onset extraction

Development surfaces

• Debug side panel
• Immediate playable browser build
• No dependency runtime

================================================================================

          LIGHTWEIGHT CANVAS2D PERSPECTIVE ENGINE & RHYTHM MATH SPEC

================================================================================

1. OVERVIEW

-----------

This file outlines the architecture and mathematical foundations used to build a 

high-performance, single-file pseudo-3D perspective environment using standard 

HTML5 Canvas2D. By bypassing heavy 4x4 matrix multiplications, WebGL shaders, and 

external framework dependencies, the rendering pipeline relies entirely on 

algebraic depth-scaling and screen-space localized projections.

2. THE PERSPECTIVE TRANSFORMATION FORMULA

-----------------------------------------

To project virtual 3D world coordinates (X, Y, Z) onto a flat 2D pixel space 

(x, y), the engine simulates a standard pinhole camera model with a shifting 

horizon line.

The mathematical mapping is defined as:

    x = x_center  + (X * f) / Z

    y = y_horizon + (Y * f) / Z

Where:

    - (X, Y, Z) = Coordinate positions inside the virtual 3D world space.

    - f         = Focal length (directly controls the Field of View / FOV).

    - x_center  = The exact horizontal midpoint of the canvas viewport.

    - y_horizon = The vertical pixel height where the parallel lines converge.

Inside the infinite-grid architecture, this relationship is handled via a 

normalized, non-linear depth scaling factor (t):

    t = 1 / (1 + d * k)

As the virtual distance (d) approaches infinity, the scaling factor (t) cleanly 

approaches 0. Elements are multiplied by this factor to compress visually as 

they get closer to the horizon line.

3. GRID LINE SPACING & ARCHITECTURE

-----------------------------------

A. Horizontal Vanishing Lines

To prevent visual stretching and accurately replicate 3D depth, the vertical 

spacing between horizontal lines is compressed exponentially using a power curve 

rather than linear steps:

    For each line (i) from 0 to maxLines:

        rawDepth     = i / maxLines

        perspectiveY = y_horizon + (canvasHeight - y_horizon) * (rawDepth^3)

This ensures dense visual crowding near the horizon line, simulating a true 

isometric/perspective ground plane.

B. Vertical Convergence Lines

Vertical lines represent lane dividers or grid boundaries. They originate 

exactly at the single vanishing point (x_center, y_horizon) and radiate outward 

to fixed offsets along the bottom edge of the screen, creating an immediate 

sense of depth.

C. The Modulo Scroll Trick (Infinite World Illusion)

To maintain a locked 60 FPS without memory bloat, floating-point degradation, 

or massive world map arrays, the system calculates rendering positions using 

a modulo operation against localized unit cell widths:

    Render_Offset = Player_World_Position MOD Cell_Width

When moving forward or sideways, the player's world position increments infinitely 

in memory, but the rendering loop only draws lines based on the remainder. The 

moment a grid line scrolls past the bottom edge of the screen, a new line 

seamlessly replaces it right below the horizon.

4. NEO-VECTR RHYTHM ENGINE PROCESSING

-------------------------------------

A. Timeline Synchronization

Rhythm synchronization bypasses unreliable CPU timeout loops by utilizing the 

high-resolution browser clock via `performance.now()`. Audio positioning is mapped 

linearly to game time:

    Current_Game_Time = (Current_Time - Audio_Start_Time) * Playback_Rate

B. Note Positioning & Spawn Mechanics

Notes are placed on the timeline based on their absolute timestamp in milliseconds. 

The visual position of a note in the 3D lane is determined by calculating how much 

time remains before the note must be hit:

    Time_Delta = Note_Target_Time - Current_Game_Time

    Normalized_Distance = Time_Delta / Visual_Approach_Window

If Normalized_Distance = 1.0, the note spawns right at the vanishing point (horizon).

If Normalized_Distance = 0.0, the note has reached the judgment line at the bottom.

This value is then plugged directly into the perspective scaling equations to 

ensure that notes accelerate realistically as they approach the player.

5. OPTIMIZATION STRATEGIES FOR ITCH.IO RELEASE

----------------------------------------------

- Zero Garabage Collection (GC) Overhead: Avoid initializing object literals 

  "{}" or arrays "[]" inside the `requestAnimationFrame` loop to prevent 

  micro-stuttering. Pre-allocate all particle pools and vertex arrays.

- Web Audio API Resiliency: When loading local files over the "file://" protocol 

  (which blocks standard audio decoding), ensure the deterministic fallback seed 

  generator triggers automatically so the system remains fully playable offline.

================================================================================