BattleBeyz

BattleBeyz is the first 3D Beyblade game with accurate spinning top physics.

I also wanted to learn from the process of creating a game from scratch, so everything is written in C++ (OpenGL / ImGui) with no physics libraries. Any collaboration or feedback is welcome!

Features (So far!)

• Centralized Game Engine and States
• Realistic Beyblade Physics
• JSON-style saving and loading
• Profile and Input Manager
• 3D Camera Control and Rendering
• Texture, Mesh, Lighting/Shading
• Logging and Debug Mode
• Mesh import (.obj), loaded off the main thread
• Pre-match screen: drag beyblades into place, set spin, launch
• Fixed-timestep physics with interpolated rendering

Coming Soon

• Round-end logic and rematch
• Opposite-spin collision modelling

Installation

1. Clone the Repository

git clone https://github.com/TheRickyZhang/BattleBeyz
cd BattleBeyz

2. Install System Dependencies

All dependencies are downloaded and built by CMake. Only Linux needs system packages, and only because GLFW links against the display server libraries.

Windows

No additional system dependencies required.

macOS

brew install cmake

Linux (Debian/Ubuntu)

sudo apt install build-essential cmake pkg-config libgl1-mesa-dev \
    libwayland-dev libxkbcommon-dev libx11-dev libxrandr-dev \
    libxinerama-dev libxcursor-dev libxi-dev

Linux (Arch)

sudo pacman -S base-devel cmake wayland libxkbcommon \
    libx11 libxrandr libxinerama libxcursor libxi

3. Build the Project

cmake -S . -B build
cmake --build build -j$(nproc)

The first build will take longer as CMake downloads dependencies (GLFW, GLEW, GLM, ImGui, etc.).

4. Run the Game

Linux/macOS

./build/BattleBeyz

Windows (Visual Studio)

1. Open build/BattleBeyz.sln in Visual Studio 2022
2. Choose Debug or Release configuration
3. Run with Ctrl+F5 or debug with F5

Windows (Command Line)

.\build\Debug\BattleBeyz.exe
# or
.\build\Release\BattleBeyz.exe

Project Structure

BattleBeyz/
├── src/                     # Source files
├── tests/                   # Unit tests (doctest)
├── assets/                  # Game assets (textures, models, etc.)
├── build/                   # Build files (generated by CMake)
└── CMakeLists.txt           # CMake build configuration

Running the Tests

Unit tests cover the units system and the physics that does not need a GL context. They are built by default alongside the game.

cd build && ctest --output-on-failure

# Or run the binary directly for per-case output
./build/battlebeyz_tests

Configure with -DBATTLEBEYZ_BUILD_TESTS=OFF to skip them.

Dependencies (Automatically Downloaded)

The following libraries are automatically fetched by CMake during configuration:

• GLFW - Window and input handling
• GLEW - OpenGL extension loading
• GLM - Mathematics library
• Dear ImGui - Immediate mode GUI
• ImGuiFileDialog - File dialog for ImGui
• nlohmann/json - JSON parsing
• stb - Image loading
• tinyobjloader - OBJ model loading
• FreeType - Font rasterisation
• doctest - Unit test framework