ASGE — A Simple Game Engine

📖 Documentation site — project overview, installation, the full API reference, and every example with screenshots and source.

ASGE is a modular, lightweight, cross-platform 2D game engine written in modern C++ (C++23), built on top of SDL3. It's developed with a focus on:

• Performance — thin abstractions over SDL, custom allocators, a thread pool for concurrent work.
• Simplicity — small, composable subsystems instead of one monolithic framework.
• Extensibility — an ECS-based gameplay layer and a signal/event system for decoupled communication between systems.
• Tooling — a debug logger, timing/profiling utilities, and a growing set of runnable examples.

The engine targets Windows, Linux and macOS, and currently renders through SDL3, with OpenGL/Vulkan/DirectX backends being considered for the future.

Current status

ASGE is under active development, worked through a roadmap split into phases. As of now:

• ✅ Core engine (application loop, logging, timing, math, memory, concurrency, filesystem)
• ✅ Rendering primitives (shapes, textures, text)
• ✅ Entity-Component-System (ECS)
• ✅ Input system (keyboard, mouse)
• ✅ Asset pipeline (virtual file system, asset handles)
• ✅ Scene management
• ✅ Physics
• ✅ Audio
• 🚧 UI, and more — see docs/roadmap for the full plan.

Separately, an in-development level editor (asge-editor, Dear ImGui-based) is being built on top of the engine — see its own roadmap doc for what's built and what's still planned.

Repository layout

src/ASGE/       Engine source (Application, Core, Events, Game, Input, Video)
examples/       Small standalone programs demonstrating each subsystem
editor/         In-development Dear ImGui level editor (asge-editor)
tests/          GoogleTest unit test suite
docs/roadmap/   Design docs and the phased implementation roadmap
scripts/        Dependency-fetching scripts (SDL3, stb, Dear ImGui) for each platform
third-party/    Vendored dependencies (fetched by the scripts above)
cmake/          CMake package config used when ASGE is installed

Installation

Prerequisites

• A C++23 compiler (MSVC on Windows, GCC/Clang on Linux, Clang on macOS)
• CMake ≥ 3.31
• Git

Building from source

git clone https://github.com/lmriccardo/a-simple-game-engine.git asge
cd asge

Fetch the vendored dependencies (SDL3 and the stb single-header libraries) for your platform:

# Windows (PowerShell)
./scripts/install-deps.ps1

# Linux / macOS
./scripts/install-deps.sh

Then configure and build using one of the provided CMake presets (also buildable without a preset, via plain cmake -S . -B build):

cmake --preset windows      # or: linux / macos
cmake --build --preset windows
ctest --preset windows-debug

Built examples land in bin/.

Using ASGE in your own C++ project

ASGE builds a static library target and installs a CMake package config, so it can be consumed as a subdirectory, via FetchContent, or as an installed package.

Option 1 — add_subdirectory

Vendor ASGE into your project (e.g. as a submodule under third-party/asge) and add it directly:

add_subdirectory(third-party/asge)

add_executable(my_game main.cpp)
target_link_libraries(my_game PRIVATE ASGE)

On Windows, my_game.exe also needs SDL3.dll next to it at runtime. Since add_subdirectory never exposes ASGE's own SDL3 target back up to your project's directory scope, use the helper ASGE defines for exactly this instead of reaching for the SDL3 target directly:

asge_copy_sdl3_runtime(my_game)

Option 2 — FetchContent

include(FetchContent)
FetchContent_Declare(
    asge
    GIT_REPOSITORY https://github.com/lmriccardo/a-simple-game-engine.git
    GIT_TAG main
    SOURCE_DIR "${CMAKE_SOURCE_DIR}/third-party/asge"
)
FetchContent_MakeAvailable(asge)

add_executable(my_game main.cpp)
target_link_libraries(my_game PRIVATE ASGE)
asge_copy_sdl3_runtime(my_game)

ASGE's own dependencies (SDL3, stb) aren't fetched by CMake — they're vendored via scripts/install-deps.ps1/.sh, run separately from the build (see Building from source above). That means the first FetchContent_MakeAvailable call above will fail: it clones ASGE into third-party/asge, then immediately tries to configure it, and find_package(SDL3) won't find anything yet. Run ASGE's install script against the freshly-cloned copy once —

./third-party/asge/scripts/install-deps.ps1     # Windows

./third-party/asge/scripts/install-deps.sh      # Linux / macOS

— then reconfigure; FetchContent sees third-party/asge already populated and it builds normally from there on.

Option 3 — installed package

Install ASGE (cmake --install build), then from your own project:

find_package(ASGE REQUIRED CONFIG)

add_executable(my_game main.cpp)
target_link_libraries(my_game PRIVATE ASGE::ASGE)

Either way, pull in the whole engine through the umbrella header:

#include <ASGE/ASGE.hpp>

Example

A game is a Game<TStateId> subclass driving a stack of IGameStates — TStateId is whatever identifies a screen (an enum class, a plain int if there's only one, ...). A minimal game with a single state that just opens a window and runs the game loop (see examples/moving_box for a complete, playable example with input and rendering):

#include <ASGE/ASGE.hpp>

class MyGameState : public asge::game::state::IGameState<int>
{
public:
    std::optional<asge::game::state::Transition<int>>
    Update(float inDeltaTime, asge::input::InputState const& inInput) override
    {
        // Game logic goes here
        return std::nullopt; // engaged instead: push/pop/replace to another state
    }

    void Render(asge::video::IRenderer& inRenderer) override
    {
        // Draw calls go here
    }

    void OnSystemEvent(asge::event::SystemEvent const& inSysEvent) override
    {
        // Handle window/system events
    }
};

class MyGame : public asge::game::Game<int>
{
public:
    explicit MyGame(asge::video::IRenderer& inRenderer) : Game(inRenderer)
    {
        SetInitialState(0);
    }

protected:
    std::unique_ptr<StateType> CreateState(int inId) override
    {
        return std::make_unique<MyGameState>();
    }
};

int main()
{
    asge::Application<MyGame> app(asge::ApplicationConfig{});
    app.Run();
    return 0;
}

Application<TGame> owns TGame, constructing it from its own IRenderer (plus any extra arguments forwarded through Application's constructor) once the window/video system is up — TGame never needs to defer renderer-dependent setup the way IGame implementations once did.

More examples covering shapes, textures, text, ECS, input handling, scenes and configuration loading live under examples/ and are built alongside the engine when ASGE_BUILD_EXAMPLES is ON. In particular, for drawing a texture and reading keyboard/mouse input — the two things a real game needs beyond the empty overrides above — see examples/texture_demo (IRenderer::DrawTexture) and examples/moving_box (InputState::IsKeyDown/IsKeyPressed).

Level editor

asge-editor is an in-development, Dear ImGui-based level editor: a separate executable that links the engine directly (no dependency on Game/IGameState) and edits scenes through the exact same SceneManager/Serializer<T> path a game itself uses — no parallel schema, no parallel renderer. It builds alongside the engine when ASGE_BUILD_EDITOR is ON (the default):

cmake --build --preset windows --target asge-editor   # or the linux / macos equivalent

Currently supports loading/saving scene files; selecting entities from the viewport or an entity list; editing every serializable component type; a world-space grid and collider-bounds overlays in the viewport; and repositioning entities via free-drag or a translate gizmo. See docs/level_editor_roadmap/roadmap.md for the phased build-out and what's still ahead.

Testing

Unit tests (GoogleTest) live under tests/ and build when BUILD_TESTING is ON:

ctest --preset windows-debug   # or the linux / macos equivalent

Contributing

Contributions are welcome — please open an issue or pull request. See docs/roadmap for the current priorities and CLAUDE.md for this repository's commit message and documentation conventions.

Contributors

• Riccardo La Marca — maintainer
• Davidizzle