SDL3 + FLECS Template

A scaffold/template for building games using SDL3 and the FLECS Entity Component System.

Features

• SDL3 - Modern cross-platform multimedia library
• FLECS - Fast and lightweight Entity Component System
• CMake - Cross-platform build system with FetchContent for dependencies
• Clean Architecture - Separated components, systems, and game logic

Project Structure

.
├── CMakeLists.txt          # Build configuration
├── include/
│   ├── components/         # ECS component definitions
│   │   ├── transform.h     # Position, Velocity, Rotation, Scale
│   │   ├── render.h        # Color, Sprite, RectShape, CircleShape
│   │   ├── input.h         # PlayerControlled, InputState
│   │   └── common.h        # Name, ToDestroy, Lifetime, Health
│   ├── components.h        # Master component include
│   ├── systems.h           # System declarations
│   └── game.h              # Game context and main loop
├── src/
│   ├── main.c              # Entry point
│   ├── game.c              # Game initialization and loop
│   └── systems.c           # ECS system implementations
└── external/               # (unused - deps fetched via CMake)

Building

Prerequisites

• CMake 3.20+
• C11 compatible compiler (GCC, Clang, MSVC)
• Git (for fetching dependencies)

Linux/macOS

# Create build directory
mkdir build && cd build

# Configure
cmake ..

# Build
cmake --build .

# Run
./sdl3_flecs_template

Windows (Visual Studio)

mkdir build && cd build
cmake .. -G "Visual Studio 17 2022"
cmake --build . --config Release
.\Release\sdl3_flecs_template.exe

Windows (MinGW)

mkdir build && cd build
cmake .. -G "MinGW Makefiles"
cmake --build .
.\sdl3_flecs_template.exe

Usage Guide

Adding Components

1. Create a new header in include/components/ (e.g., physics.h)
2. Define your component struct:

   typedef struct RigidBody {
       float mass;
       float friction;
   } RigidBody;
   

3. Include it in include/components.h
4. Register it in src/systems.c:

   ECS_COMPONENT_DECLARE(RigidBody);
   // In register_components():
   ECS_COMPONENT_DEFINE(world, RigidBody);
   

Adding Systems

1. Declare the system in include/systems.h:

   void PhysicsSystem(ecs_iter_t* it);
   

2. Implement it in src/systems.c:

   void PhysicsSystem(ecs_iter_t* it) {
       Position* pos = ecs_field(it, Position, 0);
       RigidBody* rb = ecs_field(it, RigidBody, 1);
   
       for (int i = 0; i < it->count; i++) {
           // Physics logic here
       }
   }
   

3. Register it in register_systems():

   ecs_system(world, {
       .entity = ecs_entity(world, {
           .name = "PhysicsSystem",
           .add = ecs_ids(ecs_dependson(EcsOnUpdate))
       }),
       .query.terms = {
           { .id = ecs_id(Position), .inout = EcsInOut },
           { .id = ecs_id(RigidBody), .inout = EcsIn }
       },
       .callback = PhysicsSystem
   });
   

Creating Entities

ecs_entity_t player = ecs_new(world);

ecs_set(world, player, Position, { .x = 100, .y = 100 });
ecs_set(world, player, Velocity, { .x = 0, .y = 0 });
ecs_set(world, player, RectShape, { .width = 32, .height = 32 });
ecs_set(world, player, Color, { .r = 0, .g = 255, .b = 0, .a = 255 });
ecs_set(world, player, PlayerControlled, { .player_id = 0 });

System Phases

FLECS provides built-in phases for ordering systems:

• EcsOnLoad - Load external data
• EcsPostLoad - Process loaded data
• EcsPreUpdate - Prepare for update
• EcsOnUpdate - Main update logic
• EcsOnValidate - Validate state
• EcsPostUpdate - Post-update cleanup
• EcsPreStore - Prepare for rendering
• EcsOnStore - Render/store output

Controls

• ESC - Quit
• P - Pause/unpause

License

This template is released into the public domain. Use it however you like!

Resources

• SDL3 Documentation
• FLECS Documentation
• FLECS Examples