Modules reference

Aegis2D is a set of shared libraries, one per module. A game links the modules it needs and nothing else: this page says what each one offers, what it depends on and what it costs, and how to pick them. The headers of each module are described in detail in the Architecture overview.

At a glance

Module	Library	Offers	Depends on	Size	Builds
core	aegis2d::core	logs, clocks and main loop, events, JSON config, paths, maths, random numbers, shared libraries	GLM (public), nlohmann-json	383 KB	server, client
ecs	aegis2d::ecs	entities, components, systems, collisions, pathfinding, gameplay helpers, timers, plugins	core	90 KB	server, client
shmup	aegis2d::shmup	player ships, their controls, weapons and shots	ecs	16 KB	server, client
net	aegis2d::net	binary and bit-level serialization, packets, payload compression, UDP and TCP, reliability, network thread	core, Asio, LZ4	450 KB	server, client
platform	aegis2d::platform	window, keyboard, gamepads, actions and remapping, player settings	core, SDL3	217 KB	client
render	aegis2d::render	OpenGL renderer, camera, textures, sprite sheets, Tiled maps, text, screen effects, accessibility helpers	platform, glad, stb_image, SDL3, nlohmann-json	514 KB	client
audio	aegis2d::audio	sounds, music, volumes, sounds played by gameplay events	core, SDL3	167 KB	client

• Size: the module's library alone, in a Release build on macOS (arm64, AppleClang 21). The client modules also bring SDL3, a 2.8 MB library shipped once with the game.
• Builds: the client modules exist only when the engine is built with AEGIS2D_BUILD_CLIENT=ON (the default); a server build has none of them, nor SDL3.
• Each module links the modules it depends on, so linking aegis2d::render also links platform and core.

How to pick them

Your program	Link
A tool that reads a config or logs	core
A game server, or a simulation without a window	ecs (and core with it), plus net to talk to clients
A game with a window, sprites and sounds	render and audio (with platform, ecs and core)
A networked game client	the line above, plus net
A shoot'em up, on the server and the client	add shmup to the lines above
Everything the engine built	aegis2d::engine

Start from the smallest set and add a module when a header asks for it: the compiler says which header is missing, and the table above which module has it. A server must never link platform, render or audio (see the rules in the Architecture overview).

With the engine's sources (FetchContent), link the modules one by one, and set AEGIS2D_BUILD_CLIENT to OFF before FetchContent_MakeAvailable for a server-only game, so that SDL3 and glad are not even downloaded:

target_link_libraries(my_server PRIVATE aegis2d::ecs aegis2d::net)
target_link_libraries(my_client PRIVATE aegis2d::render aegis2d::audio aegis2d::ecs aegis2d::net)

With an installed engine, ask find_package() for the same modules as components: CMake stops with the list of the installed modules if one is missing.

find_package(Aegis2D 0.1 REQUIRED COMPONENTS ecs net)

Getting started and Make a game show both ways in full.

core

The base of every other module, and the only one with no engine dependency.

• Offers: Logger, FixedTimestep and MainLoop (fixed 60 Hz update, one render per frame), EventBus, Config (JSON with comments), asset_path() and the other paths next to the executable, Vec2 to Mat4, Random (the same numbers on every compiler), SpscQueue between two threads, SharedLibrary and load_library().
• Depends on: GLM, public, behind the aegis2d::Vec* and Mat4 aliases (header-only, installed with the engine's headers); nlohmann-json, private.
• Costs: no thread, no device, no file read unless asked.
• Pick it: always; every other module brings it.

ecs

The world model of the game: entities, their components and the systems that update them.

• Offers: Registry, View, Scheduler and ISystem; the shared components (Transform, Velocity, Sprite, Collider, Health...); collisions (grid broad phase, contacts, layers); grid pathfinding (A*), path following and targets in range; damage, score, lives, animation, movement, off-screen despawn, timers, random spawns and waves read from a data file; gameplay events; plugins loaded at start.
• Depends on: core.
• Costs: no third-party library. Most systems are header-only templates, compiled into the game: they cost the game's build time rather than the library's size.
• Pick it: for any game; a server and a client share the same world through it.

shmup

What only a shoot'em up needs, on top of the ECS. No other module mentions ships (the shmup_genre_free test checks it).

• Offers: PlayerShip, Weapon and AutoTrigger; steering and clamping of the ships, fire rate enforced by the server, ShotFired; ShipControls for the clients.
• Depends on: ecs. ShipControls (header-only) also needs platform, which the module does not link, so a server never depends on it.
• Costs: the smallest library; the code is header-only, like the ECS systems.
• Pick it: for a shoot'em up. A game of another genre leaves it out.

net

Everything a networked game needs to talk over UDP and TCP, without game messages: the game defines its own.

• Offers: BinaryWriter and BinaryReader (bounds-checked), PacketHeader, sequence numbers, acknowledgements and reliable events, round trip time, traffic counters, Endpoint, UdpSocket, TcpConnection, NetworkContext and NetworkThread.
• Depends on: core; Asio, private and header-only, so the game never sees it.
• Costs: the largest library of the server, as Asio's code is compiled into it; one thread per NetworkThread; sockets bound only when the game opens them.
• Pick it: on both sides of a networked game; a local game leaves it out.

platform

The window and the player's input, independent of the graphics API.

• Offers: Window (SDL3), Keyboard following the user's layout, Gamepad, ActionMap with remapping and KeyCapture, LatchedAction (auto-fire), control lines in words, settings_dir() and the player's settings file.
• Depends on: core; SDL3, private.
• Costs: SDL3, downloaded and built with the engine; a display at run time (the window tests are skipped without one).
• Pick it: through render, which links it; alone for a program that reads input without drawing.

render

Drawing: an OpenGL renderer behind an interface, and what a game draws with it.

• Offers: IRenderer, opengl::Renderer and HeadlessRenderer (no window, for tests and tools); Image (PNG, JPEG...), TextureManager, SpriteSheet, sprite batching by layer and texture; Camera for worlds larger than the screen; TileMap, Tiled maps (.tmj) with their tilesets, layers, objects and properties, drawn by TileMapView culled to the camera; BitmapFont with a built-in font, text sizes and layout, controls table; LogicalScreen with letterboxing; Starfield, ScreenEffects (flash, shake); colorblind simulation, contrast ratios, player styles and sound captions.
• Depends on: platform, public; glad, stb_image, GLM, SDL3 and nlohmann-json, private.
• Costs: the largest library; glad's OpenGL loader is generated at configure time, which needs Python and the packages of cmake/requirements.txt; OpenGL 4.5 at run time (4.1 on macOS with AEGIS2D_MACOS_GL41).
• Pick it: for any program with a window that draws.

audio

Sounds and music, played by the game or by gameplay events.

• Offers: AudioDevice (load WAV, play on the effects or music channel, looping music, at most 32 voices), Volumes (master, music and effects, saved with the player's settings), EventSounds (a sound per event type published on the core::EventBus, so gameplay never calls audio).
• Depends on: core; SDL3, private. It does not need platform or render.
• Costs: SDL3; an audio output at run time. Without one, AudioDevice throws AudioError and the game can go on silently.
• Pick it: for a game with sound.