Rhombus Runner

What This Is

Rhombus Runner is a small 3D endless-runner prototype built in C with SDL2.
You dodge and clear obstacles by moving, jumping, and sliding while speed scales up with score.
The codebase is intentionally modular and compact so it is easy to extend with new mechanics.

Play In 60 Seconds

1) Install dependencies

• CMake 3.16+
• C compiler (clang or gcc; MSVC on Windows is also supported)
• SDL2 development libraries

Quick dependency notes:

• macOS (Homebrew): brew install cmake sdl2
• Ubuntu/Debian: sudo apt install cmake build-essential libsdl2-dev
• Fedora: sudo dnf install cmake gcc SDL2-devel
• Arch: sudo pacman -S cmake gcc sdl2
• Windows:
  • MSYS2: install mingw-w64-x86_64-cmake, toolchain, and mingw-w64-x86_64-SDL2
  • or use vcpkg SDL2 with CMake toolchain integration

2) Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

3) Run

./build/rhombus_runner

If you prefer the helper scripts:

./scripts/build.sh
./scripts/run.sh

Controls

• A / D: move left/right across the road
• W / S: move forward/back in the runner corridor
• Space: jump
• Ctrl: short low slide tackle (cooldown + reduced movement speed)
• Esc: pause/resume
• Enter: resume from pause menu
• R: restart from pause or game over
• Q: quit from pause or game over

Current Features

• Endless cube-road recycling
• Obstacle set:
  • spinning rhombus
  • red jump hurdle
  • overhead slide-gate (slide-under)
• Capsule player with lean and slide posture
• Trail particles during movement/slide
• Death burst FX
• Pickup/reward system (speed boost currently implemented)
• HUD + pause/game-over menus + in-game controls hint
• Unit tests for core gameplay logic

Known Limitations

• No signed installer/notarized app pipeline yet.
• Cross-platform source build is supported, but packaged binaries are not shipped.
• Difficulty/balance values are still prototype-level.

Project Structure

• src/: gameplay and rendering modules
• tests/: unit/integration-style logic tests
• scripts/: build/run/test helpers
• docs/: controls, delivery phases, release docs

Module map (high level):

• game.*: game loop + state machine
• world.*: road, obstacles, pickups, speed scaling
• player.*: movement, jump, slide state
• collision.*: player-vs-obstacle checks
• renderer.*: 3D software-ish draw path over SDL2
• fx.*, trail_fx.*: death and movement particles
• reward.*: timed reward effects and pickup activation
• ui.*: bitmap-text HUD and menus
• input.*: keyboard polling and edge detection

Architecture Notes

• Fixed timestep simulation in game.c (FIXED_DT).
• world_step owns world motion and recycling (road, obstacles, pickups).
• player_step owns movement/jump/slide state and local movement constraints.
• collision only decides hit/miss; it does not mutate world state.
• Renderer is fed pure state snapshots each frame.

How To Extend

Add a new obstacle type

1. Add enum in src/world.h.
2. Add spawn/setup branch in reset_obstacle (src/world.c).
3. Add collision branch in src/collision.c.
4. Add material + wireframe rendering in src/renderer.c.
5. Add tests in tests/test_collision.c and any spawn tests in tests/test_world.c.

Add a new reward effect

1. Add effect enum in src/reward.h.
2. Implement modifier application in reward_step_active (src/reward.c).
3. Optionally spawn selective pickup type in src/world.c.
4. Add HUD indicator in src/ui.c and pass-through from src/renderer.c / src/game.c.
5. Add tests in tests/test_reward.c.

Add a new player action

1. Input fields in src/input.h + polling logic in src/input.c.
2. Player state and step logic in src/player.h/.c.
3. Collision/rule updates if needed in src/collision.c.
4. Visual feedback in src/renderer.c and HUD copy in src/ui.c.
5. Add behavior tests in tests/test_player.c.

Development Workflow

Build:

./scripts/build.sh

Run tests:

./scripts/test.sh

Recommended before pushing:

1. ./scripts/test.sh
2. ./scripts/build.sh
3. quick manual run for controls + collision + menu flow

LLM Context Block

• Core loop invariants:
  • Fixed-step update drives gameplay.
  • World speed is score-scaled and capped.
  • GAME_RUNNING is the only state where gameplay mutates.
• Data ownership:
  • World owns road/obstacles/pickups RNG and score.
  • Player owns movement state, slide timers, and runtime modifiers.
  • Reward system mutates player multipliers each tick, then resets when expired.
• Extension seams:
  • Obstacles: world + collision + renderer.
  • Rewards: reward + world + game + ui.
  • New action: input + player + renderer (+collision if needed).
• Do not break:
  • Camera constants and existing control mappings unless intentionally changed.
  • Pause/restart/game-over flow.
  • Existing test contracts in tests/.
• Test requirements before merge:
  • scripts/test.sh passing
  • scripts/build.sh passing
  • no regression in manual control loop