A fast, responsive 2D side-scrolling action platformer built in modern C++ (C++20) using raylib. Developed with a shared gameplay codebase that compiles directly to a high-performance native desktop executable (macOS, Linux, Windows) as well as a WebAssembly / HTML5 build that deploys automatically to GitHub Pages.
- 1. How It Works
- 2. Tech Stack
- 3. Game Controls
- 4. How to Install and Run on Your Computer
- 5. How to Deploy to GitHub Pages
- 6. Directory Structure
- 7. Assets & Licensing
The game is written in clean, modular C++20 with strict separation between game simulation logic and rendering backends:
┌────────────────────────────────────────────────────────┐
│ main.cpp │
│ (Native Loop / Emscripten Main Loop) │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Game Engine │
│ GameStateId (State Machine) │
└───────┬───────────────────┬───────────────────┬────────┘
│ │ │
┌───────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐
│ PhysicsWorld │ │ Level & Entity │ │ UI & Camera │
│ AABB Collision │ │ Player, Enemy, │ │ HUD, Menus, │
│ Sub-stepping │ │ Boss, Hazards │ │ Letterboxing │
└────────────────┘ └────────────────┘ └────────────────┘
-
Virtual Resolution & Letterboxing: The entire game world renders to an internal
$640 \times 360$ RenderTexture2Dusing point texture sampling. This guarantees pixel-perfect retro aesthetics. - Aspect-Ratio Preserving Blit: During the final pass, the internal buffer is scaled and drawn centered with black letterbox bars to fit any monitor resolution or browser canvas without distortion.
-
Fixed Physics Updates: Delta-time is clamped (
$\le 0.05\text{s}$ ) to avoid simulation tunneling or spiraling during frame rate drops.
-
Axis-Separated AABB Resolution: Horizontal (
$X$ ) and vertical ($Y$ ) movement steps are resolved independently against level geometry colliders. -
Tunneling Prevention via Sub-Stepping: High velocities are subdivided into micro-steps (
$8\text{px}$ maximum step length) so entities never pass through walls or floors even at high speeds. -
Platformer Kinematics:
- Acceleration, deceleration, friction, gravity, and terminal fall speeds.
- Variable Jump Height: Releasing the jump button early clamps upward velocity to minimum jump threshold.
-
Coyote Time (
$0.12\text{s}$ ): Players can still jump for$120\text{ms}$ after walking off a platform ledge. -
Jump Buffering (
$0.12\text{s}$ ): Pressing jump slightly before touching the ground triggers a jump immediately upon landing.
-
One-Way Platforms: Entities can jump upward through one-way ledges and land safely on top. Pressing
S + Space(orDown + Jump) drops through one-way platforms.
-
Weapon A — Ember Blade (Melee):
- Generates an arcing hitbox sweep in front of the player.
- Deals knockback and damage to enemies.
-
Multi-Hit Prevention: Tracks each swing's unique
attackIdso a single sword swipe hits each enemy only once.
-
Weapon B — Pulse Bolts (Ranged):
- Fires high-velocity energy projectiles with cyan particle trails.
- Consumes Energy from a regenerating energy pool (
$100$ max energy,$+15/\text{s}$ regen). - Deactivates with impact sparks upon hitting solid walls or enemy targets.
- Damage & Invulnerability: Taking damage triggers invulnerability frames with visual sprite blinking and directional knockback.
The game includes 3 distinct enemy archetypes:
- Patroller: Crawls back and forth on platforms, checks ahead for cliff edges and walls before turning, and inflicts contact damage.
-
Ranged Sentry: Levitates with gentle sinusoidal bobbing, tracks player position within detection range (
$280\text{px}$ ), charges up with an energy ring telegraph, and fires plasma bolts. -
Chaser: Sleeps until the player enters its aggro radius (
$190\text{px}$ ), charges aggressively, and leaps over obstacles to attack.
- Loot Table: Enemies have a drop table rewarding Health potions, Energy crystals, or Ember Cores on death.
- Level 1 — Awakening Ruins: Platforming tutorial, patrollers, pickups, and checkpoint.
- Level 2 — The Sunken Spire: Vertical ascension, spike hazard pits, one-way ledges, ranged sentries, and chasers.
- Level 3 — Molten Catacombs: Subterranean lava caverns, falling platform steps, timing hazards, chaser packs, and sentries.
- Level 4 — The Skyward Ramparts: High-altitude citadel with floating platforms, deep chasms, and aggressive sniper sentries.
- Level 5 — The Ashen Crucible: Advanced hazard gauntlet culminating in the locked Ashen Warden boss encounter.
Level 5 culminates in a locked arena encounter against The Ashen Warden:
- Arena Gate: Crossing into the arena triggers a boundary lockdown preventing retreat.
- Phase 1 (100%–66% HP): High-altitude ground slam with a visible telegraph marker on the floor, followed by a meteoric crash and bilateral ground shockwaves.
- Phase 2 (66%–33% HP): Multi-shot fiery spread volleys (3 to 5 projectiles).
- Phase 3 (<33% HP): Enraged high-speed flaming dash charges across the arena.
- Vulnerability Windows: After executing heavy attacks, the boss enters an exhausted
Recoverystate, allowing the player clear windows to counterattack.
- Procedural Pixel Art: In AssetManager.cpp, character sprites (Hero, Patroller, Sentry, Chaser, Ashen Warden), tilesets, and effect animations are synthesized into textures in memory during engine boot.
- Procedural Sound Synthesis: In AudioPlayer.cpp, footsteps, jumps, slashes, laser blasts, impacts, boss roars, and victory fanfares are generated using mathematical wave formulas (sine, square, triangle, white noise) directly into 16-bit PCM raylib
WaveandSoundbuffers. - No Missing Asset Errors: The game requires zero external image or audio files to run, but can load overrides from
assets/if provided.
- Game States:
Boot,MainMenu,LevelSelect,Playing,Paused,Settings,GameOver,LevelComplete, andVictory. - Persistence: SaveSystem.cpp serializes highest unlocked level, total score, collected cores, and audio volume to
riftbound_save.daton desktop, and syncs via IDBFS in browser builds.
| Technology | Purpose |
|---|---|
| C++20 | Core programming language (Modern C++ features, RAII, strongly typed enums, std::unique_ptr) |
| raylib 5.5+ | Hardware-accelerated 2D rendering, audio output, window management, and input polling |
| CMake 3.20+ | Cross-platform build configuration with FetchContent dependency management |
| Emscripten | Compiles C++ code and raylib into WebAssembly (.wasm) and JavaScript glue code |
| CTest | Automated unit testing framework for physics, combat, and progression validation |
| GitHub Actions | Automated CI/CD pipeline for building, running tests, and deploying to GitHub Pages |
| GitHub Pages | Static web hosting for the WebAssembly browser build |
| Action | Primary Keyboard | Alternate / Mouse |
|---|---|---|
| Move Left | A |
Left Arrow |
| Move Right | D |
Right Arrow |
| Jump (Tap for low, hold for high) | Space |
W / Up Arrow |
| Drop Through One-Way Ledge | S + Space |
Down Arrow + Jump |
| Melee Attack (Ember Blade) | J |
Left Mouse Button |
| Ranged Attack (Pulse Bolts) | K |
Right Mouse Button |
| Switch Weapon | Q |
1 / 2 |
| Pause / Resume | Escape |
P |
| Confirm / Select | Enter |
E / Mouse Click |
| Toggle Debug Hitboxes | F1 |
— |
- Modern C++20 compiler (
clang++,g++, or MSVC) - CMake 3.20 or newer
- Git
# 1. Clone the repository
git clone https://github.com/lokeshpuma/riftbound-cpp.git
cd riftbound-cpp
# 2. Optional: Install raylib via Homebrew (CMake fetches it automatically if omitted)
brew install raylib
# 3. Configure and build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j 4
# 4. Launch the game!
./build/riftbound# 1. Install required development libraries
sudo apt-get update
sudo apt-get install -y build-essential cmake git libasound2-dev libx11-dev \
libxrandr-dev libxi-dev libgl1-mesa-dev libglu1-mesa-dev libxcursor-dev libxinerama-dev
# 2. Clone the repository
git clone https://github.com/lokeshpuma/riftbound-cpp.git
cd riftbound-cpp
# 3. Configure, build, and run
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(nproc)
./build/riftbound# 1. Open 'Developer Command Prompt for VS' or PowerShell
git clone https://github.com/lokeshpuma/riftbound-cpp.git
cd riftbound-cpp
# 2. Configure and build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
# 3. Run the executable
.\build\Release\riftbound.exeThe test suite validates AABB collision logic, platforming resolution, damage cooldowns, weapon attack IDs, boss phase transitions, and progression persistence:
ctest --test-dir build --output-on-failure
# Or run the test binary directly:
./build/riftbound_testsThis repository includes a turnkey GitHub Actions workflow at .github/workflows/deploy-pages.yml. Whenever code is pushed to the main branch, the workflow:
- Sets up the Emscripten toolchain (
emcc). - Compiles raylib and the game into WebAssembly (
index.html,index.js,index.wasm). - Packages the static web output into a GitHub Pages deployment artifact.
- Publishes it directly to GitHub Pages.
- Push this project to your GitHub repository:
git remote add origin https://github.com/lokeshpuma/riftbound-cpp.git git push -u origin main
- On GitHub, navigate to Settings > Pages (under the "Code and automation" section).
- Under Build and deployment > Source, change the dropdown from Deploy from a branch to GitHub Actions.
- That's it! GitHub Actions will trigger automatically, and your game will be live at:
https://lokeshpuma.github.io/riftbound-cpp/
To test the WebAssembly build locally before deploying:
# 1. Activate Emscripten SDK
source /path/to/emsdk/emsdk_env.sh
# 2. Configure CMake for Web
emcmake cmake -B build-web -DPLATFORM=Web -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
# 3. Build the HTML5/WASM bundle
cmake --build build-web -j 4
# 4. Start a local HTTP server (browsers block WASM via file://)
cd build-web
python3 -m http.server 8080Open http://localhost:8080/index.html in any modern web browser.
riftbound-cpp/
├── CMakeLists.txt # Cross-platform CMake build system
├── README.md # Full documentation, guides, and controls
├── PRD_2D_Action_Platformer_CPP.md # Product Requirements Document
├── ASSETS.md # Asset provenance & licensing records
├── LICENSE # MIT License
├── .gitignore # Git ignore rules
├── .github/
│ └── workflows/
│ ├── build.yml # CI build & automated CTest runner
│ └── deploy-pages.yml # Emscripten WebAssembly GitHub Pages deployer
├── assets/ # Optional audio, sprite, and level assets
├── include/
│ ├── core/ # Config, Types, AssetManager, Input, SaveSystem, Audio, Particles
│ ├── physics/ # AABB, Collider, PhysicsWorld
│ ├── combat/ # DamageInfo, Weapon, EmberBlade, PulseBolts, Projectile
│ ├── entities/ # Entity, Player, Enemy, Patroller, Sentry, Chaser, Boss
│ ├── level/ # Tile, Level, LevelManager, CameraController, Collectible, Hazard, Checkpoint
│ ├── ui/ # HUD, MenuManager, UIElements (Button, Slider)
│ └── game/ # Game, GameStateId
├── src/ # Implementations corresponding to include/
├── tests/ # CTest suite (physics, combat, progression)
└── web/
└── shell.html # Custom Emscripten HTML shell with loading bar & responsive canvas
- Game Code: Licensed under the MIT License.
- Visuals & Sounds: Documented in
ASSETS.md. All visual sprites, particles, and audio sound effects are procedurally generated original assets licensed under the MIT License and fully compliant with open-source and commercial hosting.