🌌 LIGHT YEARS ENGINE

High-Performance C++20 2D Game Engine & Parametric Animation Pipeline // Compiled to WebAssembly

Architected & Engineered by Solomon "Captain Solo" Olufelo — Senior Game Engine & Tools Portfolio

Quick Start • System Architecture Whitepaper • Micro-Profiler • Spatial Broadphase • Developer Suite • Controls

---

"Because real engine programmers write their own memory pools, spatial partitioning grids, fixed-timestep loops, and spline evaluators before drawing a single sprite."

🚀 Architectural Highlights

Light Years is a custom C++20 game engine and real-time developer tooling suite compiled directly to WebAssembly (WASM) via Emscripten and SDL2, with native Windows x64 MSVC parity.

Designed as an unassailable portfolio piece for Senior Game Engine, Tools, Graphics, and Systems Programming roles across top-tier AAA game studios (Rockstar Games, Epic Games, Naughty Dog, Sony Santa Monica, Insomniac, Riot, Blizzard), it demonstrates production-grade systems architecture:

• Deterministic 16.66ms Frame Budget Micro-Profiler: Subsystem CPU timing instrumentation (WorldSim, CollisionBroadphase, SDLRender, ImGuiTools) with microsecond resolution and an interactive Dear ImGui stacked flamechart bar.
• Uniform 2D Spatial Hash Broadphase Grid: Bins entities across 48 spatial cells ($120 \times 120$ px), pruning collision pairs by $>90%$ over brute-force $O(N^2)$ checks with real-time culling telemetry.
• Zero Runtime Heap Allocations on Hot Paths: Cache-friendly contiguous object pools (ObjectPool<Bullet, 256>, ParticleSystem, 512, FloatingTextPool, 48) ensuring zero dynamic heap allocations per frame.
• Two-Way Parametric Animation Pipeline: Real-time Cubic Bezier & Hermite spline evaluator with live tangent manipulation directly driving spaceship kickback and thruster dynamics.
• Multi-Clip Sprite Timeline & Canvas Visualizer: Vector rasterizer featuring live playback controls, onion skinning, scrubber slider, interactive keyframe strip, and per-frame duration editing.
• Zero-Asset Procedural Web Audio Synthesizer: Directly driven from C++ via Emscripten EM_ASM, synthesizing laser sweeps, biquad-filtered noise explosions, arpeggio powerup chords, and damage impacts with zero network latency.
• Dedicated Dev Mode (F2): Color-coded spatial hitboxes, spatial grid bucket occupancy visualizer, and live engine diagnostics.
• Full-Fledged Playable Combat Experience: Interactive Start Menu, in-engine vector HUD, floating damage/score text, escalating wave director, tactical pause, and instant respawn.

---

🏛️ Comprehensive Architecture Documentation

For an in-depth technical whitepaper on memory layouts, cache line optimization, mathematical spline evaluations, spatial broadphase algorithms, and WASM compilation, consult: 👉 ARCHITECTURE.md

graph TD
    subgraph "Application Heartbeat (60.00 Hz Fixed Loop)"
        APP["ly::Application"] --> PROFILER["ly::core::Profiler (Micro-Budget Tracker)"]
        APP --> WORLD["ly::World Container"]
    end

    subgraph "Zero-Allocation Memory Subsystems"
        WORLD --> BULLETS["ly::ObjectPool<Bullet> (256 Slots)"]
        WORLD --> PARTICLES["ly::ParticleSystem (512 Slots)"]
        WORLD --> FLOATING["ly::FloatingTextPool (48 Slots)"]
    end

    subgraph "Spatial Partitioning & Combat"
        WORLD --> SPATIAL["ly::SpatialGrid (48 Uniform Cells)"]
        SPATIAL --> COLLISION["Broadphase Culling >90% Efficiency"]
        WORLD --> PLAYER["ly::PlayerSpaceship (Banking, Shields, Overdrive)"]
        WORLD --> ASTEROIDS["ly::Asteroid (Splitting Physics)"]
        WORLD --> ENEMIES["ly::EnemySpaceship (AI Formations)"]
        WORLD --> PICKUPS["ly::Pickup (Pulsing Diamond & Magnet)"]
    end

    subgraph "Developer Suite & Tooling"
        WORLD --> IMGUI["ly::tools::AnimationInspector (Dear ImGui)"]
        IMGUI --> TAB1["[Curve Pipeline] Hermite Splines & Easing"]
        IMGUI --> TAB2["[Live Entity] Parameter Tweaker"]
        IMGUI --> TAB3["[Profiler & Telemetry] Frame Budget & Spatial Stats"]
        IMGUI --> TAB4["[Combat Director] Spawner & God Mode"]
        IMGUI --> TAB5["[Sprite Timeline] Canvas Visualizer & Onion Skinning"]
        WORLD --> DEVMODE["Dev Mode Spatial Hitbox Visualizer (F2)"]
    end

Loading

---

⏱️ Subsystem Micro-Profiler & Frame Budgeting

The engine features an internal micro-profiler tracking execution times against a 16,666.67 $\mu s$ budget (60 Hz target):

[■] World Sim  [■] Broadphase Collisions  [■] Vector Render  [■] ImGui Tools  | Headroom (Green Line = 120Hz)
[██████████████████████████████████████████████████████████████████████████████████████████████████████████]

Subsystem	Target Budget	Typical Cost	Color Code	Description
WorldSim	$\le 2,500,\mu s$	$\sim 320,\mu s$	Neon Cyan	Actor physics, starfield parallax, floating text drift
CollisionBroadphase	$\le 2,000,\mu s$	$\sim 180,\mu s$	Amber Gold	Spatial grid bucket binning, candidate pruning, circle tests
AnimationCurves	$\le 1,500,\mu s$	$\sim 90,\mu s$	Neon Magenta	Parametric spline evaluations, camera shake damper
ParticleSim	$\le 2,000,\mu s$	$\sim 140,\mu s$	Emerald Green	Contiguous 512-slot particle pool update and color lerp
SDLRender	$\le 5,000,\mu s$	$\sim 1,100,\mu s$	Electric Blue	Layer-sorted hardware-accelerated vector rendering pass
ImGuiTools	$\le 3,666,\mu s$	$\sim 950,\mu s$	Deep Purple	In-engine vector UI, HUD, Dev Mode, Dear ImGui tooling
Frame Headroom	Remainder	$\sim 13,800,\mu s$	Dark Slate	Headroom available for heavy load / 120 Hz display refresh

---

🌐 Spatial Hash Broadphase Collision Grid

Instead of naive $O(N^2)$ checks across all projectiles and actors, SpatialGrid partitions the $960 \times 720$ canvas into 48 uniform buckets ($120 \times 120$ px):

• Zero-Allocation: Contiguous fixed-size cell arrays (MAX_ACTORS_PER_CELL = 32).
• Dynamic Culling Efficiency: Prunes pair evaluation by $>90%$: $$\text{Efficiency} = \left(1.0 - \frac{\text{Broadphase Checks}}{\text{Brute Force Potential Checks}}\right) \times 100% \approx 88\text{--}94%$$
• Comparative Benchmarking: The Dear ImGui Inspector allows switching between Broadphase and Brute Force modes in real time to observe performance telemetry.
• Dev Mode Overlay (F2): Visualizes cell boundaries and density-coded occupancy levels directly on screen.

---

🛠️ Developer Tooling Suite (Dear ImGui)

Toggle with F1 or ` (Tilde) at any time:

1. [Curve Pipeline]: Interactive mathematical spline graph. Click and drag Hermite tangent handles to modify spaceship recoil kickback and thruster pulse in real time.
2. [Live Entity]: Dynamic entity parameters (flight speed, fire rate, recoil distance, recovery duration, muzzle screen shake).
3. [Profiler & Telemetry]: Stacked 16.66ms frame budget bar, microsecond metrics table, spatial broadphase telemetry, and zero-allocation memory audit.
4. [Combat Director]: Immediate spawner controls for asteroids, enemy squadrons, shields, and overdrive, plus God Mode toggle.
5. [Sprite Timeline]: 2D vector canvas preview, onion skinning, clip dropdown (Thruster, Explosion, Shield, Cosmic Gem), smooth scrub slider, and interactive keyframe buttons.

---

🕹️ Controls Quick-Reference

Input	Action
W / A / S / D or Arrows	Navigate Starfighter with dynamic 3D banking roll physics
SPACE or ENTER	Launch Mission (Start Menu) / Fire Plasma Lasers
P or ESC	Toggle Tactical Mission Pause
R	Instant Respawn & Restart Run (Zero Browser Reload)
F2	Toggle Dev Mode (Spatial Hitboxes, Grid Buckets & Engine Diagnostics)
F1 or ` (Tilde)	Toggle Dear ImGui Systems & Animation Inspector
Web Shell Toolbar	Quick buttons for Launch, Dev Hitboxes, Pause, Respawn, Inspector, and Fullscreen

---

💻 Quick Start

🕸️ WebAssembly Build (Emscripten)

# Compile to WebAssembly with 0 warnings
.\build_wasm.ps1

# Launch local HTTP preview server
python -m http.server 8080 -d build_web

Open http://localhost:8080/index.html in any modern web browser.

🖥️ Native Windows Desktop Build (MSVC)

# Configure with CMake Preset
cmake --preset default

# Compile Native x64 Executable
cmake --build --preset default

# Launch Engine
.\build\default\LightYears.exe

---

📜 License

This project is open-source under the MIT License. Engineered for portfolio evaluation and technical showcase purposes.