cs381/as6

🌌 Gravity Surfing

A physics-driven endless runner built with C++ and raylib-cpp.

Steer a probe in space by placing black holes, collect stars, and survive a continuous stream of hazards.

Play the web version!

---

Extra Credit (for CS 381)

• EC: stacked README
  • Formatted in a style inspired by Microverse: KsanaDock/Microverse README_EN
• EC: doxygen-compatible comments
  • Note that the project splits header and implementation files, and only the headers are documented with doxygen comments.
• EC: publish wasm/web playable
  • Used this video as a reference for emscripten build: https://www.youtube.com/watch?v=j6akryezlzc
  • https://anguscheng.com/post/2023-12-12-wasm-game-in-c-raylib/

🎮 Key Features/Core Gameplay

• You control a probe that moves continuously through a side-scrolling world
• Black holes/gravity wells bend the probe trajectory with inverse-square pull
• Consume energy meter to place black holes
• Stars restore your energy meter and increase run score
• Asteroids and out-of-bounds movement end the run
• Null zones disable gravity influence and force repositioning

🕹️ Controls

• enter - start run (menu), retry run (death screen)
• Esc - Close game
• m - toggle mute
• left click - place/use player gravity black hole (if you have enough energy)
• right click - clear active player-created black holes

🛠️ Technology Stack

• Genre: 2D endless runner / arcade
• Language: C++20
• Framework: raylib (raylib-cpp)
• Architecture: object-orienteed component entities
• Platforms: Desktop, Web (WASM)

📋 Requirements

• CMake 3.25+
• C++20 compiler (g++, clang++, or MSVC)
• Git
• Sibling dependencies. You can get these by cloning the entire monorepo with --recursive or by following the quick start instructions below:
  • ../raylib-cpp
  • ../assets
• For web builds: Emscripten SDK

🚀 Quick Start (Developer Setup)

📦 Installation

1. Clone the repository and initialize submodules

   git clone https://github.com/humanoidsandvichdispenser/cs381.git
   cd cs381
   git submodule update --init --recursive
   

2. Navigate to as6 and generate build files

   cd as6
   mkdir -p build
   cd build
   cmake ..
   

3. Compile

   make
   

▶️ Basic Usage

1. Launch the game

   From the as6/build directory:

   ./as6-gravity-surfing
   

2. Start a run

   • Click the start button at the main menu
   • At the main menu, click the mute button to mute or press m at any time

3. Play and survive

   • Left click to place/use gravity black holes when energy meter allows
   • Right click to clear player-created black holes
   • Collect stars to refill energy meter and increase score
   • Avoid asteroids and avoid leaving the screen bounds

🌐 Web/WASM Build

1. Install Emscripten SDK

   In addition to the above requirements, you need to have Emscripten installed and activated. Follow the instructions here: https://emscripten.org/docs/getting_started/downloads.html. Your existing build directory will work for both desktop and web builds.

2. Build for web

   The repository includes a build-web.sh bash script that sets up the necessary Emscripten environment variables and invokes CMake with the appropriate toolchain file.

   From the as6 directory, run:

   ./build-web.sh
   

3. Serve the web build

   After building, you can serve the as6/build-web directory using a simple HTTP server. For example, using Python's built-in server:

   cd build-web
   python3 -m http.server 8080
   

   Then open your browser to http://localhost:8080 to play the web version.

   You can also deploy the contents of build-web to any static hosting service. The script contains extra options for deploying to Cloudflare Pages (use -h or --help to see usage instructions).

🛠️ Key Systems

• Entity/component model: gameplay logic is split into focused components (PhysicsComponent, SpawnComponent, GravityWellComponent, etc.)
• Shared game context: scene-level references and callbacks are coordinated through GameContext
• Projection preview: forward simulation predicts the probe path to support tactical placement
• Procedural spawning: stars, hazards, and null zones spawn based on scroll position
• Event-driven feedback: collectible, stats, and death callbacks keep systems loosely coupled

🗂️ Project Structure

as6/
├── components/          # gameplay component implementations
├── scene/               # start menu, gameplay, and death scenes
├── main.cpp             # app entry and frame loop
├── Entities.cpp/.hpp    # entity factory construction
├── Systems.cpp/.hpp     # per-frame update orchestration
├── GameContext.hpp      # shared scene-level state/events
├── Draw.cpp/.hpp        # drawing helpers
└── CMakeLists.txt       # build configuration

🧭 Roadmap Ideas

• Improve HUD feedback and run-end stats
• Add more hazard/collectible variety
• Expose balancing constants for easier tuning
• Add persistent high scores

Credits

• Made for CS381 Assignment 6
• Powered by raylib, raylib-cpp, and raygui