Core Gameplay & Hit Windows

Keyboard Symphony coordinates physical keystrokes with musical rhythms flowing down a vertically oriented 10-lane scrolling space. The input grid is physically mapped directly to the top row of a standard QWERTY keyboard:

Lanes feature dynamic neon HSL color coding to guide the player's peripheral vision and timing focus:

• Lanes 0 & 9 (Neon Red): Color(1.5, 0.2, 0.2)
• Lanes 1 & 8 (Neon Orange): Color(1.5, 0.8, 0.2)
• Lanes 2 & 7 (Neon Yellow): Color(1.5, 1.5, 0.2)
• Lanes 3 & 6 (Neon Green): Color(0.2, 1.5, 0.2)
• Lanes 4 & 5 (Neon Cyan): Color(0.2, 1.5, 1.5)

Judgment Decision Flowchart

The Asymmetric Judgement System

To accommodate natural human motor speed profiles—where physical anticipation commonly triggers early clicks, whereas late keypress dragging represents sluggish reaction speeds and is heavily penalized—the rhythm engine implements highly responsive, **Asymmetric Hit Windows**:

• Pure Perfect: Displays a vibrant green flare on the receptor line and records a perfect accuracy mark on the accuracy indicator.
• Instant Late Miss (Auto-Miss): Any note passing the active receptor line by more than +45ms is instantly wiped from play memory and registered as a Miss. The note is colored dark gray (Color(0.4, 0.4, 0.4, 0.35)) to provide immediate, snappy sensory response.
• Dynamic Key BG Tinting: Octagonal lane key backgrounds (KeyBG) dynamically adapt and tint to match their respective lane note colors.
• Event-Driven Glow Caching: Key highlights utilize high-performance event-driven cached states (_lane_last_glow_state) to eliminate redundant per-frame draw operations.
• Sleek Hold Notes: Elongated hold note trail bodies are rendered with a highly customized slim profile, scaled down to 45% thickness (width * 0.45) compared to regular tap notes in both the editor and live gameplay grids for a premium aesthetic.

Visual Triggers & Screen FX Overlay Engine

Visual scripting triggers are positioned across specialized script tracks, Lanes 10 to 13, in the timeline charts. The graphics pipeline parses these triggers dynamically at runtime to load GLSL shaders and animate coordinate camera space transforms.

Shading Suites (assets/shaders/)

1. Digital Glitch Shader (glitch.gdshader): Slices viewport screen coordinates horizontally into 30 distinct bands, shifting random bands horizontally based on high-frequency noise and doing split red/blue chromatic offsets.
2. Chromatic Aberration Shader (chromatic_aberration.gdshader): Shifts red, green, and blue color channels outward from the center, creating simulated high-intensity camera lens warp.
3. Lens Circle Vignette Shader (lens_circle.gdshader): Computes pixel radial distances from the screen center, maintaining a transparent circle while blending a deep dark-blue quadratic vignette falloff towards the viewport borders.
4. Pixel Inversion Shader (invert.gdshader): Initiates a high-speed bitwise pixel color inversion (1.0 - Color) across viewport space.

FX Triggers & Node Specifications

• SNC (Sync Note Color): Eases the HSL color coordinates of notes bearing a specific target ID over a custom beat duration.
• SSH (Screen Shake): Triggers 2D screen shake on the active gameplay camera based on custom intensity amplitude and decay settings.
• LCI (Lens Circle Vignette): Snaps the vignette closed, holds it for a designated beat length, and opens it slowly using a cubic ease-in-out transition.
• BGC (Background Color): Interpolates the background canvas color smoothly between hex values over a defined beat length.
• FLS (Screen Flash): Floods the screen with an opaque neon color, which decays out using a quadratic ease-out decay curve.
• CRA (Chromatic Aberration) & GLT (Glitch): Initiates high-intensity visual glitches that ease back to zero over a designated period.
• INV (Color Invert): Flashes the pixel inversion shader, reversing all colors on screen.
• CBP (Change Background Path): Instantly swaps the gameplay's active background image on the fly.
• SHS (Set Hit Sound): Swaps the game's active hitsound asset to a different sound file (e.g. Kick or Percussion) mid-level.
• SST (Skip Song To) [NEW]: A specialized non-scalable node (duration 0.0) that triggers a decoupled audio skip when crossed.
• ROT (Rotate), ZOM (Zoom), and MOV (Move): Coordinate solid 2D camera rotations, scaling zoom offsets, and X/Y displacements.

The Professional Level Editor & Audio Visualizer

The level editor provides creators with premium vertical-grid charting, snappable subdivisions (ranging from 1/4 Snap to ultra-precise 1/32 Snap), and a decoupled "Run Level" Playtest Launcher system.

Decoupled Playtest Workflow & 60 FPS Guarantee

To avoid massive CPU/GPU simulation and rendering lag inherent to embedding live gameplay loops inside the editor viewport, the live editor panel relies on a dedicated round-trip playtest launcher. Launching the playtest spawns a decoupled standalone Godot sub-process, enabling 60+ FPS high-fidelity testing on the fly, and automatically returning the creator to their exact chart edit state upon exit.

Audacity-Style Dual Peak/RMS Waveform Visualizer

The editor features a professional-grade audio visualizer modeled directly after advanced Digital Audio Workstations (DAWs) and Audacity:

1. Asynchronous Transcoder: Spawns a background Thread which leverages FFmpeg to convert imported OGG/MP3/WAV audio streams to 44.1kHz Mono 16-bit WAV PCM formats instantly.
2. High-Fidelity Peak & RMS Extraction: Reads the raw PCM buffers (processing over 10 million samples for a 4-minute song) and computes both:
   • Peak Amplitude: The maximum absolute transient spikes, drawn as a wider, semi-transparent outer envelope (using colors rgba(0, 102, 204, 0.40) upper, and rgba(178, 0, 89, 0.35) lower).
   • RMS Energy: The root-mean-square average energy, representing the perceived core loudness, drawn as a bright, centered neon inner core (using colors rgba(0, 166, 255, 0.95) upper, and rgba(255, 0, 127, 0.90) lower).
3. Waveform Caching: Decoded Peak/RMS buffers are stored locally inside highly compressed binary files under user://cache/waveforms/ (hashed via MD5 of the stream resource path). Subsequent loads bypass decoding and load **instantly (0.0s)**.
4. Glassmorphic Pulse Scanner: While background decoding is in progress, the visualizer renders a glassmorphic blur panel overlay with an animated progress scanner, keeping the editor interactive and running at 60+ FPS.

Decoupled Playback & Millisecond Formatting

The transport panel implements premium seeking controls:

• Millisecond Formatting: The timeline updates current and total song durations in a human-readable millisecond-precise format: X min, Y secs, Z ms / A min, B secs, C ms.
• Skip Song To (Decoupled Seeking): Allows entering target skip timestamps (supporting flexible inputs like 01:20:250, 1:20.25, or 80). Clicking Skip seeks the music player instantly to that time *without* moving the chart's current beat position. During playback, the chart playhead advances synthetically based on delta time while the song plays independently. Clicking the timeline seekbar, waveform, or skipping via ⏮ -10s / +10s ⏭ instantly re-syncs the audio back to the playhead.

SST (Skip Song To) Effect Node

Creators can place the **SST** effect node directly onto the timeline grid (Lanes 10-13):

• Visual Style: Labeled as SST in a striking Teal/Emerald color (Color(0.0, 0.8, 0.5)) with duration locked to 0.0 (non-scalable).
• Inspector Properties: Selecting an `SST` note displays a custom `Skip Target` text box in the inspector sidebar where creators can input target skip timestamps.
• Gameplay Execution: When the playhead crosses the `SST` note in-game or during preview, it triggers decoupled audio playback—the music tracks immediately jump to the skip target while the gameplay playhead advances synthetically at its own pace.

Authentication, User Cloud Sync & Account Security

Keyboard Symphony bridges client-side safety with online progression through Supabase backend services.

Cryptographic Save Verification

Player statistics (XP, Currency, Stars, Levels Completed, and Joined Time) are securely written locally in user://player_stats.json. The file is encrypted utilizing **AES-256 (Advanced Encryption Standard)** with a highly secure 32-character passkey. If a player attempts to edit their local file, decryption fails, safeguarding leaderboard integrity.

Google OAuth TCPServer Redirect Listener

Online login uses a custom secure redirect handler to coordinate browser authentication:

1. The Godot client spawns a local TCPServer listening on port 9999.
2. The OS shell opens the player's web browser to the Supabase Google auth link.
3. Upon authorization, Supabase redirects the browser to http://localhost:9999/#access_token=...
4. An inline script in the redirect page extracts the hash parameters, sends a GET fetch back to the client TCPServer, and closes the browser tab.
5. The game processes the HTTP headers, reads the tokens, and securely logs the user in.

Account Verification & The Verified Badge

A multi-tiered account validation system awards verified players a glowing, glassmorphic **Verified Badge** (cyan neon tag border overlay). Verification requires two conditions:

1. Email Verification: Active confirmation of the user's email address in the database (requested directly from the Profile UI).
2. Google Linkage: Secure linkage of their third-party Google Account.

Once verified, players unlock a unique, database-indexed Member ID (PID) which displays on their profile card (e.g. MEMBER #0024).

Core Autoload Architecture

Underpinning the user interface and main game loops are six core autoload singletons that coordinate data, layouts, sound, performance diagnostics, and synchronization layers recursively:

• SoundManager (src/core/sound_manager.gd): A procedural audio synthesizer that generates all UI sounds dynamically in memory on boot (sine sweep hovers, retro mechanical click presses, and major-chime chord successes). It intercepts node additions (get_tree().node_added) and automatically binds hover/press sound effects to all BaseButton nodes recursively, guaranteeing game-wide responsiveness with zero manual wiring.
• ToastManager (src/core/toast_manager.gd): Stacks glassmorphic, glowing alerts vertically on layer 128 utilizing cubic scaling transitions and smooth sliding collapse animations.
• SceneTransition (src/core/scene_transition.gd): Handles system-wide switching using canvas layer 100 and a diagonal neon panel that swipes across the viewport with HSL color-shifting glow edges.
• SettingsManager (src/core/settings_manager.gd): Manages local settings configuration, inputs, graphics rendering presets, and gameplay calibrations.
• SyncManager (src/core/sync_manager.gd): Performs bidirectional cloud sync with Supabase by comparing save timestamps, preventing client resets from overwriting cloud database truths.
• PerformanceProfiler (src/core/performance_profiler.gd): Orchestrates continuous tracing logs and visual performance auditing. To maintain absolute gaming stability, the profiler is gracefully decoupled at runtime startup—automatically running dormant with 0% CPU/GPU overhead unless intentionally triggered via development keystrokes (Ctrl+P), protecting runtime frames.