Octarine Engine

Octarine Engine is a lightweight, high-performance 2D game engine built with C++20. It features a custom archetype-based Entity-Component System (ECS), integrated Lua scripting, and a unique yellowish-purple aesthetic.

New here? Start with docs/QUICKSTART.md — the shortest path from a fresh clone to a verified code change.

Tech Stack

• Graphics: SDL3
• Scripting: Lua 5.4 with sol2 bindings
• ECS: Custom Archetype-based implementation
• Math: GLM
• UI: ImGui with custom sol2 bindings
• Logging: spdlog
• Dependency Management: vcpkg

---

Third-Party Licenses

Octarine Engine itself is MIT-licensed (see LICENSE). Every shipped package (desktop ZIP/TGZ/DMG, Android AAB) ships a build-time-aggregated THIRD_PARTY_LICENSES.txt covering every linked dependency. Aggregation lives in cmake/octarine-licenses.cmake.

Portions of this software are copyright © The FreeType Project (www.freetype.org). All rights reserved. FreeType is used under the terms of the FreeType License (FTL); see the bundled THIRD_PARTY_LICENSES.txt for the full text and for every other linked dependency.

---

Prerequisites

• CMake: Version 3.15+
• C++ Compiler: C++20 compliant (GCC 11+, Clang 13+, MSVC 2022+)
• vcpkg: For managing dependencies.
• Git: To clone the repo and submodules.

---

Building the Engine

The engine uses CMake Presets to manage different build configurations. There are three primary variants:

• Editor: Includes ImGui and the yellowish-purple editor tools. Best for development and level design.
• Player: A minimal, high-performance runtime without the editor.
• Profile: An optimized player with performance instrumentation (spdlog timers) enabled.

Build Commands

# Clone the repository
git clone https://github.com/mblackman/Octarine-Engine.git
cd Octarine-Engine

# List all available presets
cmake --list-presets

# Build the Editor (Standard development)
cmake --preset editor-debug
cmake --build --preset editor-debug

# Build the Player (optimized dev runtime, live-scan catalog)
cmake --preset player-release
cmake --build --preset player-release

# Build the Profiling Player (For performance analysis)
cmake --preset player-profile
cmake --build --preset player-profile

The compiled binaries will be located in build/[preset-name]/bin/.

For producing shippable artifacts (Windows ZIP/NSIS, Linux TGZ, macOS DMG, Android APK/AAB) see docs/device-builds.md. Shipping config is the ship-release preset (and ship-mac-universal for universal macOS).

Contributing? See CONTRIBUTING.md for workflow, coding standards, commit style, and the SRC_FILES rule.

Running the Engine

Octarine Engine accepts the game directory as a positional argument:

# Run a game project
./OctarineEngine ./projects/my-game

# Run with a specific startup mode (e.g. for benchmarking)
./OctarineEngine ./projects/my-game --startup-mode stress

---

Benchmarking

Continuous Benchmarking

The engine runs automated performance benchmarks via GitHub Actions on every push to main and Pull Request.

Interactive historical performance dashboard: Octarine Engine Performance Dashboard

Local Profiling

The player-profile preset is optimized for performance analysis. scripts/bench.sh uses this build to stream timing data:

# Run for 8s using player-profile preset against Octarine-Engine-Example.
scripts/bench.sh

# Run against a specific game directory
OCT_BENCH_GAME=/path/to/game scripts/bench.sh

For ad-hoc profiling runs:

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
  ./build/player-profile/bin/relwithdebinfo/OctarineEngine /path/to/game --startup-mode bench