A C++ Game Engine

Table of Contents

• Getting Started
  • Prerequisites
  • Initial setup
• IDE Integration
  • Setting Up Your Development Environment
  • CLion
  • VSCode
  • Other platforms
  • Code Formatting
• Building & Running
  • Build Targets
  • Build Everything
  • Generate compile commands for IDE Support
  • Build Presets
  • Example Build Commands
  • Running Tests
• Documentation
  • Generating Documentation
• Examples & Usage
  • Running the Sandbox Example
• Community & Contributions

PixelBullet Engine is an attempt to create a modular, high-performance game engine tailored for development and education, aiming to balance efficiency and flexibility with a focus on compile-time resolution. The goal is to design a structured, interface-driven system that allows for easy extension, optimization, or system swapping without overhauling the codebase. Bazel is used to ensure clean isolation for seamless iteration. While modularity is a guiding principle, it's not absolute—some systems, like a Vulkan-only renderer, are being explored with a streamlined, dedicated approach in mind rather than full backend flexibility.

Getting Started

Prerequisites

Before you can build and run PixelBullet Engine, ensure you have Bazel installed:

• Bazelisk (recommended for managing Bazel versions)

  ‍Note: Bazelisk will also be installed in the VSCode DevContainer for convenience.

Initial setup

1. Install Bazelisk
2. Clone the repository:

   git clone https://gitlab.com/pixelbullet-labs/pixelbullet.git
   cd pixelbullet

IDE Integration

Setting Up Your Development Environment

PixelBullet repository supports multiple development environments:

CLion

CLion is the primary IDE for PixelBullet development, offering the most seamless and direct integration. It provides full support for our Bazel-based workflow, ensuring a streamlined development experience.

VSCode

VSCode is a viable alternative to CLion, offering a flexible environment with a pre-configured DevContainer. The DevContainer includes:

• Pre-installed Bazel, Bazelisk, and C++ development tools
• Debugging with LLDB
• Formatting with clang-format and clang-tidy

It requires:

• Docker and Docker for VSCode Extension
• Bazel for VSCode Extension
• DevContainer for VSCode Extension

  ‍Linux Users: Do not forget to follow the Docker post-installation guide to ensure correct setup.

Other platforms

The project is cross-platform but relies heavily on Bazel, which limits its compatibility with certain products. If possible, follow the Bazel IDE Integration Guide to configure your preferred IDE. This approach may change in the future, but for now, the benefits of Bazel seem to outweigh its drawbacks. As a result, there are challenges with Visual Studio support, as we are not willing to use tools like CMake for project generation, and modern Bazel does not provide direct support for this.

Code Formatting

The project uses clang-format for consistent code style. Format your code with:

find . -name '*.cpp' -o -name '*.h' | xargs clang-format -i

Or resort to IDE shortcuts where supported (e.g. in CLion).

Building & Running

Build Targets

• Game Engine: //engine:pixelbullet_engine
• Editor: //editor:pixelbullet-editor
• Sandbox Example: //examples/sandbox:sandbox-app
• Time Utils Tests: //engine:time_utils_tests

Build Everything

To build the entire project:

bazel build //...

Generate compile commands for IDE Support

bazel run :refresh_compile_commands

‍Note: Learn more about this here.

Build Presets

• Debug Mode: --config=debug
• Release Mode: --config=release
• Address Sanitizer: --config=asan
• Memory sanitizer --config=msan
• Thread Sanitizer: --config=tsan
• Undefined Behavior Sanitizer: --config=ubsan

Example Build Commands

• Build the game engine in debug mode:

  bazel build --config=debug //engine:pixelbullet_engine

• Build the editor in release mode:

  bazel build --config=release //editor:pixelbullet-editor

‍Note: In CLion, for Bazel projects using the Bazel extension, the Run action always maps to release mode, and the Debug action always maps to debug mode.

• Build with sanitizers:

  bazel build --config=asan //...
  bazel build --config=tsan //...
  bazel build --config=ubsan //...

Running Tests

• Run all tests:

  bazel test //...

• Run a specific test:

  bazel test //engine:time_utils_tests

• Run tests with sanitizers:

  bazel test --config=asan //...
  bazel test --config=tsan //...
  bazel test --config=ubsan //...

Documentation

Generating Documentation

To generate documentation, run:

bazel build //:doxygen

The documentation will be available in the html directory.

‍Note: The documentation is built using doxygen_rules and doxygen-awesome.

Examples & Usage

Running the Sandbox Example

To build and run the sandbox example:

bazel build --config=debug //examples/sandbox:sandbox-app
bazel run //examples/sandbox:sandbox-app

Community & Contributions

• Report issues, discuss features, and contribute via the project repository.
• Follow our updates as we expand the documentation.