Columba Engine Blog

How I Run Local AI with n8n on a Schedule (No Server, No API Costs)

Wed, 25 Mar 2026 00:00:00 GMT

Most AI workflows run 24/7 and waste resources. Mine runs once a day, on my own machine, processes everything, and shuts down before I even wake up.

Why always-on AI is wasteful

A lot of AI workflows are set up to run continuously by default, but plenty of them don’t actually need real-time execution. If what you’re doing is batch-style monitoring, scraping, content processing, or scheduled analysis, keeping a server alive all day is mostly wasted uptime. You end up paying for idle compute, ongoing server costs, and infrastructure that just sits there between runs.

That’s the problem this setup is meant to solve. Not every AI system needs to be on 24/7. For batch-style workflows, it often makes more sense to run on a schedule, finish the work, and shut down.

I wanted to avoid paying for a server that would sit idle most of the day, so I started running everything on my own machine instead. Once I did that, the question changed. It stopped being “how do I keep this AI workflow running all the time?” and became “when does it actually need to run?” In my case, the answer was simple: wake up at 5AM, process everything in one batch, then shut down cleanly. That’s really the whole idea here. For a lot of AI automations, better timing beats more infrastructure.

A concrete example: my Reddit monitoring pipeline

In my case, the pipeline is for Reddit monitoring. Once a day, n8n wakes up, fetches posts from the sources I care about, and runs them through a local AI step that filters noise and keeps the signal.

I don’t need to watch Reddit in real time. I don’t need a system running all day to track every new post or comment. I just need one scheduled pass that gathers fresh content, sorts through the volume, and leaves me with a short list of posts worth reading.

That’s why this works well as a batch job. Fetch posts, filter noise, keep signal.

The workflow is simple once you see the shape of it: Reddit -> fetch, AI -> analyze/filter, Store -> results. First, the scheduled job starts the local model server. Then n8n fetches the Reddit posts, sends them through the model to filter out the noise, and keeps the useful items. After that, the workflow stores the results and stops the model cleanly.

That order matters because the AI server only exists for the duration of the batch. Start the model, process everything in one pass, store the output, and shut it down.

Treat your machine like a scheduled worker

The basic mental model is simple: let the machine wake up on a schedule, do the job, and shut down. Instead of keeping AI infrastructure alive all day, you bring your own computer online only when there’s work to do. That’s a much better fit for batch jobs, monitoring, scraping, and other tasks that don’t need constant uptime.

This works best when the job already has a natural batch shape. Monitoring, scraping, and batch processing are good examples because they can run on a schedule, finish, and get out of the way. If a workflow only needs a daily insight, then daily compute is enough.

There’s an obvious boundary here. This is not a fit for chat apps, live agents, or anything else that depends on low-latency interaction. Those workloads need something that stays responsive all the time. This setup is for doing one focused pass on a local machine, processing the data, and shutting everything down cleanly. Here’s your section rewritten with the actual working setup (Windows + n8n + schtasks + llama.cpp) while keeping your tone and flow.

What n8n needs for this to work

One n8n capability makes this possible: Execute Command. You need it for local automation because it lets the workflow trigger processes on your own machine. In practical terms, this is what allows n8n to start your local LLM server at the right moment, use it during the workflow, and shut it down afterward.

It’s disabled by default, so you have to enable it first. If you’re running n8n locally on Windows, set this environment variable before starting n8n:

$env:NODES_EXCLUDE = "[]"
n8n start

That removes executeCommand and readWriteFile from the excluded nodes list and gives you what matters here: the ability to run local scripts from inside your workflow.

This setup only works in the right environment. n8n Cloud won’t allow it, and Docker setups are usually restricted for this kind of direct system access. The configuration that works is a local n8n instance running on the same Windows machine that will launch the LLM server, run the workflow, and shut it down again.

Starting the local AI server from n8n

Once n8n can execute commands locally, the next step is launching your LLM server on demand. In my case, that’s llama.cpp, but the exact model doesn’t matter. What matters is the pattern: n8n triggers something, the server starts, and the rest of the workflow uses it.

The important detail is that you don’t call the script directly from n8n. Instead, you wrap it in a Windows scheduled task, and n8n only triggers that task.

Here’s the actual start script:

# start-llama.ps1
$ErrorActionPreference = "Stop"

$Root = "Z:\Ai\llama.cpp"
$Exe  = Join-Path $Root "build\bin\Release\llama-server.exe"
$PidFile = Join-Path $Root "llama-server.pid"

Start-Process `
    -FilePath $Exe `
    -ArgumentList "-m models\mistral-7b.gguf --port 8081 -ngl 999 -np 1 -cb -fa --mlock --no-mmap -t 4" `
    -WorkingDirectory $Root `
    -WindowStyle Hidden

# wait until server is ready
$ready = $false
for ($i = 0; $i -lt 180; $i++) {
    Start-Sleep -Seconds 1
    try {
        $resp = Invoke-WebRequest -Uri "http://127.0.0.1:8081/health" -UseBasicParsing -TimeoutSec 2
        if ($resp.StatusCode -eq 200) {
            $ready = $true
            break
        }
    } catch {}
}

if (-not $ready) {
    throw "llama-server did not become ready"
}

# resolve PID after startup
$proc = Get-CimInstance Win32_Process |
    Where-Object {
        $_.Name -eq "llama-server.exe" -and
        $_.CommandLine -match "--port 8081"
    } |
    Select-Object -First 1

$proc.ProcessId | Set-Content $PidFile
exit 0

This script does three things:

starts the server in the background,
waits until it’s actually reachable via HTTP,
saves the PID so it can be stopped later.

That middle step is critical. Instead of guessing with a fixed delay, the script waits until the server is actually ready.

The key technical constraint

This was the part that broke my first version. n8n’s Execute Command node waits for the command to finish before continuing the workflow. That’s fine for short scripts, but a local LLM server is a long-running process by design.

If you try to start the server directly from n8n, the workflow just sits there. From n8n’s point of view, the command never finishes, so nothing else runs.

The problem isn’t the model. It’s that a server is not a one-shot command.

That’s the core constraint: Execute Command expects something that exits, but your LLM server is meant to stay alive. Until you handle that mismatch, the workflow stalls.

The fix: delegate to Windows

The fix was to stop letting n8n manage the process directly and let Windows handle it instead.

Instead of calling the PowerShell script directly, I created a scheduled task:

schtasks /Create /TN "LlamaServerStart" /TR "\"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe\" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File \"Z:\Ai\llama.cpp\start-llama.ps1\"" /SC ONCE /ST 00:00 /F

Then from n8n, I only run:

schtasks /Run /TN "LlamaServerStart"

That’s the key difference.

schtasks /Run returns immediately
Windows runs the script independently
n8n doesn’t get stuck waiting

So instead of trying to force a long-running server into a short-lived command model, I hand off execution to the OS and let n8n just trigger it.

That’s what makes the workflow actually usable.

Shutting the server down cleanly

Stopping the server uses the same pattern.

First, the stop script:

# stop-llama.ps1
$Root = "Z:\Ai\llama.cpp"
$PidFile = Join-Path $Root "llama-server.pid"

$pidValue = Get-Content $PidFile -ErrorAction SilentlyContinue

if ($pidValue -and (Get-Process -Id $pidValue -ErrorAction SilentlyContinue)) {
    Stop-Process -Id $pidValue -Force
}

Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
exit 0

Then create the task:

schtasks /Create /TN "LlamaServerStop" /TR "\"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe\" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File \"Z:\Ai\llama.cpp\stop-llama.ps1\"" /SC ONCE /ST 00:00 /F

And call it from n8n:

schtasks /Run /TN "LlamaServerStop"

Why this setup works

The key idea is simple once you see it:

n8n orchestrates
Windows executes
the LLM runs independently

The PID file connects start and stop, the HTTP check guarantees readiness, and schtasks prevents n8n from blocking on a long-running process.

That combination is what makes the start–use–stop cycle reliable.

Without it, you’re fighting the execution model of n8n. With it, everything behaves like a normal service lifecycle: bring it up, use it, shut it down cleanly, and start fresh on the next run.

Why 5AM is the real trick

The timing is what makes this setup practical instead of just clever on paper. I scheduled mine for 5AM, when my machine is idle and nothing else I’m doing is competing with it. That gives the workflow a quiet compute window to start the local LLM server, run the batch job, and shut everything back down before the day begins.

And 5AM is just my choice, not a rule. The broader idea is to schedule around your own idle time. For batch work, scraping, monitoring, or any once-a-day automation, that shift makes local compute a lot more practical.

Results and trade-offs

What this setup buys me is pretty simple: zero infrastructure cost beyond the machine I already own, automated daily insights, and time saved. In practice, the machine wakes up, checks Reddit once a day, filters out the noise, and leaves me with a small set of posts worth reading. I don’t have to pay for an extra always-on server or babysit the process. It’s not magic, and it won’t fit every use case, but for a scheduled batch job like this, it’s genuinely useful.

The trade-offs are real too. This only works if the machine is on at the scheduled time, so it’s best for a local-only setup where you control the hardware. There’s also some scripting complexity, since you need to start the LLM server in the background, track its process, and stop it cleanly afterward. That’s a good fit for batch jobs, monitoring, and other workflows that don’t need 24/7 uptime, but it’s not the right fit for everything.

That’s the main lesson I took from this: most AI automations don’t need a bigger stack, a cloud bill, or a server running all day. They need better timing. If the job is batchable, run it in the quiet window, spin up the local model just long enough to do the work, then shut it down.

Once you stop treating every workflow like a 24/7 service, the whole problem gets simpler. You don’t need more infrastructure. You need better timing.

Persistent Storage in C++ Web Apps: WASMFS + OPFS with Emscripten

Wed, 11 Mar 2026 00:00:00 GMT

How to use WASMFS to get persistent storage for a web app in C++

Ever wanted to create an app in C++ and serve it on the web, but you need to store some data of the user and you can't find any guide on the web? Here I will show you how to use the OPFS backend of the new WASMFS storage layer for any app built with emscripten.

The problem

I am making a game engine fully written in C++ and I want to use it to create some small scope games for game jams and such, so a web export is pretty much mandatory to have players test and play those games on itch. So for my web builds I naturally use emscripten for this.

What is emscripten? Emscripten is a cross compiling tool that enables devs to port a C++ app to webassembly so that it can run in browsers. It works really well with my usecase as I use SDL as the backend for all of my render calls and input handling and it is backed into emscripten so it pretty much builds out of the box without doing too much handling on my part.

But one of the major issues I faced using emscripten was the handling of files and more specifically the persistent storage of my saves. There are multiple ways given by this tool to access files. First, for all the static files (such as resources or shaders), you can precompile them directly into the binary with the linker flag --preload-file. This directly compiles the files into the wasm and you can access them with any basic file accessor such as fopen or fstream. This works really well for all the files known at compile time and is quite easy to use for the tradeoff of having a bigger .wasm size.

set_target_properties(${TARGET} PROPERTIES
    LINK_FLAGS "--preload-file res \
                --preload-file shader \
                --preload-file scripts")

Those files get baked in and are read-only, which is fine for shaders, scripts or any asset that doesn't change at runtime.

The main issue comes from files that are not present during compile time or need to evolve during runtime such as save files. For those we need to use a different kind of file handling.

Thats where WASMFS comes into play.

WASMFS

So if you skim through the emscripten docs, you will see that there are a lot of different ways to access, manage and store files in emscripten. For a quick runthrough you have access to:

IDBFS — the original persistent storage backend, backed by the browser's IndexedDB. It works but requires you to synchronize explicitly using EM_ASM and JavaScript callbacks every time you want to flush data to disk. It's now being deprecated in favor of WASMFS.
PROXYFS — lets you proxy filesystem calls to another Emscripten worker or shared memory. Useful for sharing a filesystem between workers but not really relevant if you just want to persist save data.
WASMFS — the new filesystem layer. It's a fully C++ API, supports multiple backends (including OPFS), and handles threading out of the box. This is the one we want.

Here the two mains filesystem solutions that interest us are the IDBFS backend and the newer WASMFS + OPFS backend.

Why WASMFS over IDBFS

First, IDBFS is being deprecated for the newer WASMFS so if you want to future-proof your app and you don't know which to choose, it is better to onboard with the more user friendly WASMFS. Next is a simpler and fully C++ API for WASMFS so the integration is faster and easier with existing C++ code, whereas before the IDBFS functions like mounting or flushing a directory required you to drop into EM_ASM and JavaScript callbacks to manage the filesystem. Finally you get better threading support as WASMFS supports it out of the box, something that was not supported by the previous implementation.

That said, be careful: WASMFS still doesn't have support for all backends, so if you are targeting browsers that don't support OPFS you will still need to work with the old API if you want to have access to persistent storage.

Let's get into it

Now that we know why we want WASMFS, let's go through the actual setup step by step.

CMake configuration

So first things first, before you can even think about mounting OPFS you need to have the right linker flags in your CMake. The three that matter here are -sWASMFS to enable the new filesystem layer, -s FORCE_FILESYSTEM=1 so the filesystem actually gets linked even if emscripten doesn't detect any explicit FS calls in your code, and then -pthread with -sPTHREAD_POOL_SIZE for threading:

set_target_properties(${TARGET} PROPERTIES
    LINK_FLAGS "-sWASMFS \
                -s FORCE_FILESYSTEM=1 \
                -sPTHREAD_POOL_SIZE=4 \
                -pthread \
                -s ALLOW_MEMORY_GROWTH=1")

One thing to be careful about with the thread pool size: WASMFS internally defers its async operations to a background thread, so you always need to account for that extra thread on top of whatever your app already uses. If you don't allocate enough threads your app can just stall waiting on IO with no obvious error.

Mounting the OPFS backend

Now for the actual mounting, first you need to include the wasmfs header, under an __EMSCRIPTEN__ guard of course:

#ifdef __EMSCRIPTEN__
#include <emscripten/wasmfs.h>
#endif

Then before you start your main loop you create the backend and mount it to a directory:

#ifdef __EMSCRIPTEN__
    std::string savePath = "/" + config.saveFolder;   // e.g. "/save"
    backend_t backend = wasmfs_create_opfs_backend();
    int err = wasmfs_create_directory(savePath.c_str(), 0777, backend);
    if (err != 0 && errno != EEXIST)
        printf("Warning: OPFS mount returned %d (errno=%d)\n", err, errno);
#endif

Two things to watch out for here. First the path needs to start with /, that's just how emscripten's virtual filesystem works, the root is always /. On desktop you use relative paths but on web everything has to be absolute. Second don't worry about EEXIST in your error check, that just means the directory was already there from a previous session which is actually the happy path for save data.

Since the path format differs between builds you need a small conditional when you construct it:

std::string constructSavePath() const
{
#ifdef __EMSCRIPTEN__
    return "/" + saveFolder + "/" + saveSystemFile;
#else
    return saveFolder + "/" + saveSystemFile;
#endif
}

On desktop you get save/system.sz, on web /save/system.sz. Same logical location, just the web one maps into the OPFS-backed virtual directory you just mounted.

Reading and writing files

This is actually the nicest part of WASMFS compared to IDBFS: once the backend is mounted you don't need any special API to read or write to it. Standard C++ file I/O just works:

// Write
std::ofstream out{"/save/system.sz"};
out << data;

// Read
std::ifstream in{"/save/system.sz"};
std::string content((std::istreambuf_iterator<char>(in)),
                     std::istreambuf_iterator<char>());

WASMFS transparently routes anything under /save/ to the OPFS backend and persists it across sessions. No manual flush, no sync call, no JS callbacks. That's pretty much the whole point of switching to it.

Saving on browser lifecycle events

One thing that can catch you off guard: the browser doesn't guarantee your writes make it through if the user just slams the tab closed. To cover that you need to hook into two browser lifecycle events.

The first is visibilitychange which fires when the tab becomes hidden, so things like switching tabs or minimizing the window. The second is beforeunload which fires synchronously right before the page unloads on refresh or close. Together they cover pretty much all the cases:

#ifdef __EMSCRIPTEN__
    // Tab hidden: user switched tabs, minimized, etc.
    emscripten_set_visibilitychange_callback(nullptr, false,
        [](int, const EmscriptenVisibilityChangeEvent* e, void*) -> EM_BOOL {
            if (e->hidden)
                saveNow();
            return EM_TRUE;
        });

    // Page close / refresh
    emscripten_set_beforeunload_callback(nullptr,
        [](int, const void*, void*) -> const char* {
            saveNow();
            return nullptr;  // nullptr = no "Are you sure?" dialog
        });
#endif

beforeunload fires synchronously so a blocking write is fine there. visibilitychange is the one that covers mobile browsers where beforeunload is unreliable, so you really want both.

Threading and initialization order

The last piece of the puzzle is the initialization order, and this one matters more than it looks. The full sequence needs to go like this:

exec()
  ├─ wasmfs_create_opfs_backend()     ← must happen before the main loop
  ├─ wasmfs_create_directory(...)
  ├─ SDL_Init(...)
  ├─ SDL_CreateWindow(...)
  ├─ std::thread initThread { initializeWindow() }   ← window/ECS init in background
  └─ emscripten_set_main_loop_arg(mainLoopCallback)  ← hands control to the browser

The OPFS mount has to happen before emscripten_set_main_loop_arg because WASMFS internally creates promises that need a running browser event loop to resolve. If you mount after handing control to the browser you can end up in a situation where the promises never resolve.

The window initialization goes into a background thread so the main loop can start right away and give those promises room to process. Then in the main loop callback you just check an atomic flag before doing anything:

static void mainLoopCallback(void* arg)
{
    Engine* engine = ...;

    if (not engine->windowReady.load())
        return;  // still waiting for initThread

    if (not engine->initialized)
    {
        engine->initializeECS();
        engine->initialized = true;
    }

    // normal render / event loop
}

This is what avoids the deadlock where all your pthread pool threads are sitting blocked on OPFS operations with nobody left to run the event loop and resolve the pending promises. If you ever find your app just hanging on startup with no error, this is probably why.

Wrapping up

That's all there is to it. WASMFS with the OPFS backend is honestly a much cleaner solution than what came before — no JS callbacks, no manual syncing, just standard C++ file I/O that persists across sessions. The only real gotchas are the thread pool size and the initialization order, and now you know about both.

If this was useful to you or you ran into a different issue with the setup feel free to leave a comment, I'd be happy to extend the article with more edge cases.

If you are curious about the engine this was built for, PgEngine is a C++ game engine targeting both desktop and web. You can check it out and leave a star on the repo here: ColumbaEngine repository

Live demos at: columbaengine.org/demos

Discord: Join our community

If you played one of the games made with it and want to leave some feedback or just say hi, you can find them on my itch page here: Itch

The Code Generator Journey: From Manual Hell to Declarative Heaven

Fri, 30 Jan 2026 00:00:00 GMT

The Problem: Writing the Same Code for the 50th Time

Picture this: You're building a game engine with a pure Entity Component System (ECS) architecture. You need to add a new component—let's call it HealthComponent. Simple enough, right? You need a few fields: currentHealth, maxHealth, and isDead.

But wait. In practice, here's what you actually need to write:

Component struct definition - Fields, getters, setters
Event-firing setters - Notify systems when values change
VM proxy schema - Expose component to scripting system
Serialization code - Save/load support
Attach handlers - Let scripts create and attach components

For our "simple" HealthComponent, that's easily 100+ lines of boilerplate code. And you'll write it all by hand. Again. For the 50th time.

The Real Cost: PositionComponent

Let me show you what "boilerplate" really means with a real example from ColumbaEngine. Our PositionComponent handles 2D position, size, rotation, and visibility. It has 8 fields. Here's what we had to maintain:

position.h: 359 lines - Struct definition, enums, helper structs
position.cpp: 150 lines - Setter implementations, utility functions
ecsserialization.cpp: 98 lines - VM proxy and serialization

Total: ~607 lines of code for ONE component with 8 fields.

Every time we wanted to add a field:

Update the struct definition
Write getter/setter with event firing
Add to VM proxy schema
Update serialization code
Register with attach handler
Hope we didn't forget anything

The Maintenance Nightmare

Copy-paste errors were common. Event firing was inconsistent. Adding viewport to TTFText? I forgot to update the serialization. Position's rotation setter wasn't firing events properly. The serialization for colors used a different pattern than other fields.

Every component felt like writing the same code with slightly different names.

And that's when I asked: What if we didn't have to?

The Vision: Declarative Components

What if defining a component looked like this instead:

name: PositionComponent
namespace: pg
base_class: Component

fields:
  - name: x
    type: float
    default: 0.0f
    setter: event

  - name: y
    type: float
    default: 0.0f
    setter: event

  - name: rotation
    type: float
    default: 0.0f
    setter: event

That's it. Just declare what you want. The code writes itself.

Benefits:

Single source of truth - One .pgcomp file defines everything
Consistency guaranteed - Generated code follows the same patterns
Easy to read and modify - YAML is human-friendly
Regenerate anytime - Change something? Regenerate. No fear.

Why Build Our Own Generator?

Before diving in, we considered alternatives:

Option 1: External Templating (Jinja2, Mustache, etc.)

Pros: Mature, well-tested Cons: Python dependency, another language to learn, separate tooling

Option 2: Python Generator Scripts

Pros: Flexible, easy to write Cons: External dependency, not integrated with engine

Option 3: C++ Template Metaprogramming

Pros: No runtime overhead Cons: Compile-time cost, hard to read, limited flexibility

Our Choice: PgScript

We chose to write the generator in PgScript, ColumbaEngine's own scripting language.

Why?

Dogfooding - Use the engine's own language to build engine tools
Zero external dependencies - Ships with the engine
Demonstrates capability - Shows PgScript is production-ready
Faster iteration - No recompilation needed
Educational - Others can read and learn from it

The decision to use PgScript forced us to make the language better. And that benefited everyone.

Building the Foundation: Native Modules

Before we could write a component generator in PgScript, we needed to enhance the language itself.

String Module: 349 Lines of Utilities

A YAML parser needs string manipulation. Lots of it. So we added:

// String inspection
startsWith(str, prefix)    // "PositionComponent" starts with "Position"
endsWith(str, suffix)      // "component.h" ends with ".h"
contains(str, substring)   // "type: float" contains "float"

// String manipulation
substring(str, start, end) // Extract portions
trim(str)                  // Remove whitespace
replace(str, from, to)     // Replace all occurrences

// String transformation
capitalize(str)            // "position" -> "Position"
indexOf(str, substring)    // Find position of substring

Commit: 191babed - Added 349 lines to stringmodule.h

File Module: Reading and Writing

import "file"

var content = readFile("PositionComponent.pgcomp")
var success = writeFile("PositionComponent.generated.h", generatedCode)

Simple but essential. The generator reads .pgcomp files and writes generated .h and .cpp files.

Algorithm Module: Vector Operations

YAML has arrays. Arrays everywhere. Field lists, include lists, method lists. We needed robust array manipulation to build the generator.

What we added to the algorithm module:

import "algorithm"

// Array operations
var fields = []
push(fields, fieldDef)           // Add to end
insert(fields, 0, fieldDef)      // Insert at index
var field = pop(fields)          // Remove and return last
removeAt(fields, 2)              // Remove at specific index

// Length and access
var count = len(fields)          // Get array length
var field = fields[0]            // Access by index

// Type checking and introspection
var type = typeOf(fields)        // Returns "array"
if (typeOf(value) == "string")   // Dynamic type checking

// Table/object operations
if (contain(currentItem, "name")) // Check if key exists
{
    var name = currentItem["name"]
}

// Type conversion
var number = toInt("42")         // String to integer

Why these functions matter:

push() and pop() - Essential for building arrays during parsing
len() - Needed for loops and bounds checking
contain() - Critical for checking if YAML fields exist before accessing
typeOf() - Dynamic type checking for flexible parsing
toInt() - Converting string numbers in YAML to integers

Without these utilities, we'd have no way to work with the structured data coming from YAML. Arrays are first-class citizens in the component generator.

Commit: 4db26392 - Added 158 lines of vector manipulation

Commit: ebc08c06 - Added typeOf() utility

With these modules in place, PgScript had everything needed for the generator: string manipulation, file I/O, and data structure operations.

The YAML Parser Challenge

Why YAML?

We needed a format for .pgcomp files that was:

Human-readable - Developers edit these by hand
Structured - Support nested objects and arrays
Standard - Don't invent a new format
Comment-friendly - Documentation inline

YAML checked all the boxes. But... we had to write a YAML parser. In PgScript.

Parser Architecture

Here's the core structure from component_generator.pg:

class YamlParser
{
    init()
    {
        this.indentStack = []
    }

    parse(content)
    {
        var lines = splitLines(content)
        var result = {}
        var currentSection = ""
        var currentArray = []
        var currentItem = {}

        for (var i = 0; i < len(lines); i++)
        {
            var line = lines[i]
            var trimmed = trim(line)

            // Skip empty lines and comments
            if (len(trimmed) > 0 and not startsWith(trimmed, "#"))
            {
                var indent = this.getIndent(line)

                if (startsWith(trimmed, "-"))
                {
                    // Array item
                    this.parseArrayItem(trimmed, currentItem, currentArray)
                }
                else if (contains(trimmed, ":"))
                {
                    // Key-value pair
                    this.parseKeyValue(trimmed, indent, result, currentSection)
                }
            }
        }

        return result
    }
}

The Tricky Parts

Writing a YAML parser from scratch revealed complexity we didn't anticipate. Here are the challenges we had to solve:

1. Indentation Tracking

YAML uses indentation for nesting. We needed to count spaces to determine structure:

getIndent(line)
{
    var indent = 0
    for (var i = 0; i < len(line); i++)
    {
        var char = substring(line, i, i + 1)
        if (char == " ")
            indent = indent + 1
        else
            break
    }
    return indent
}

The challenge: Different indent levels mean different things:

fields:              # indent = 0 (top-level)
  - name: x          # indent = 2 (array item)
    type: float      # indent = 4 (nested property)
    default: 0.0f    # indent = 4 (same level)

We maintain a state machine tracking current section, current array, and current object. When indent decreases, we know we're back to a parent level.

2. Array Items with Key-Value Pairs

This YAML pattern was particularly tricky:

fields:
  - name: x          # Array item with nested key-value
    type: float
    default: 0.0f
  - name: y          # Next array item
    type: float

The problem: The - starts a new array item, but the following indented lines are properties of that item.

Our solution:

var currentItem = {}

if (startsWith(trimmed, "-"))
{
    // Save previous item if it exists
    if (contain(currentItem, "name") or contain(currentItem, "params"))
    {
        push(currentArray, currentItem)
    }

    // Start new item
    currentItem = {}

    // Parse the line after the dash
    var afterDash = trim(substring(trimmed, 1, len(trimmed)))

    if (contains(afterDash, ":"))
    {
        // "- name: x" format
        var parts = this.splitFirst(afterDash, ":")
        var key = trim(parts[0])
        var value = trim(parts[1])
        currentItem[key] = this.parseValue(value)
    }
}
else if (indent > 0 and contains(trimmed, ":"))
{
    // Nested property of current item
    var parts = this.splitFirst(trimmed, ":")
    var key = trim(parts[0])
    var value = trim(parts[1])
    currentItem[key] = this.parseValue(value)
}

We accumulate properties into currentItem, then push it to the array when we see the next - or reach a different section.

3. Type Inference for Values

YAML values can be strings, numbers, booleans, arrays, or objects. We needed to parse them correctly:

parseValue(value)
{
    // Parse inline arrays: [item1, item2, item3]
    if (startsWith(value, "[") and endsWith(value, "]"))
    {
        var innerContent = substring(value, 1, len(value) - 1)
        var items = split(innerContent, ",")
        var result = []

        for (var i = 0; i < len(items); i = i + 1)
        {
            push(result, trim(items[i]))
        }

        return result
    }

    // Parse inline objects: {key1: value1, key2: value2}
    if (startsWith(value, "{") and endsWith(value, "}"))
    {
        // ... parse object
        return obj
    }

    // Parse booleans
    if (value == "true")
        return true
    if (value == "false")
        return false

    // Parse numbers (kept as strings for simplicity)
    // Everything else is a string
    return value
}

For simplicity, we keep most values as strings and let the code generator handle type conversion. This avoided complex number parsing.

4. Comment Handling

Comments (#) should be ignored:

fields:
  - name: x           # X coordinate
    type: float       # Using float for precision

Simple solution:

// Skip empty lines and comments
if (len(trimmed) > 0 and not startsWith(trimmed, "#"))
{
    // Process line
}

We check this early and skip commented lines entirely.

Parser Statistics

The complete YAML parser is:

~400 lines of PgScript
Supports:
- Top-level key-value pairs
- Nested sections
- Arrays with - notation
- Objects within arrays
- Inline arrays [a, b, c]
- Inline objects {key: value}
- Comments
Does NOT support:
- Multiline strings
- Anchors and aliases (&, *)
- Complex multiline syntax (|, >)
- Explicit typing (!!str, !!int)
- Merge keys (<<:)

Why this is enough: We control the .pgcomp format. We don't need full YAML spec compliance—just enough to make component definitions readable and writable by humans.

The parser works perfectly for our needs, and we can extend it when new features require new YAML constructs.

Code Generation: The Heart of the System

Now for the interesting part: generating C++ code from YAML definitions.

The .pgcomp Format

Here's a complete example - our Health component:

name: HealthComponent
namespace: pg

includes:
  - <cstdint>

fields:
  - name: currentHealth
    type: int32_t
    default: 100
    setter: event

  - name: maxHealth
    type: int32_t
    default: 100
    setter: basic

  - name: isDead
    type: bool
    default: false
    setter: none

Simple, readable, and complete. Let's see what gets generated.

Header Generation

From the YAML above, we generate:

// PositionComponent.generated.h
// AUTO-GENERATED - DO NOT EDIT

#pragma once

#include <cstdint>
#include "ECS/system.h"

namespace pg
{
    struct HealthComponent : public Component
    {
        // Fields
        int32_t currentHealth = 100;
        int32_t maxHealth = 100;
        bool isDead = false;

        // Setters
        void setCurrentHealth(int32_t value);  // event setter
        void setMaxHealth(int32_t value);      // basic setter
        // No setter for isDead (setter: none)

        // ECS integration
        _unique_id id = 0;
        EntitySystem* ecsRef = nullptr;
    };
}

Clean, consistent, and complete.

Setter Levels

This is where the system shines. We support 4 levels of setters, each for different needs:

Level 1: No Setter (Direct Access)

- name: isDead
  type: bool
  default: false
  setter: none

Generated: Just the field. Scripts access it directly.

Use case: Derived state, internal flags

Level 2: Basic Setter

- name: maxHealth
  type: int32_t
  default: 100
  setter: basic

Generated:

void setMaxHealth(int32_t value) {
    maxHealth = value;
}

Use case: Simple assignment with validation opportunity

Level 3: Event Setter (The Key Innovation)

- name: currentHealth
  type: int32_t
  default: 100
  setter: event

Generated:

void setCurrentHealth(int32_t value)
{
    if (this->currentHealth != value) // Only fire if changed!
    {
        this->currentHealth = value;

        if (ecsRef)
        {
            ecsRef->sendEvent(HealthComponentChangedEvent{id});
        }
    }
}

The optimization: if (this->currentHealth != value)

This one line prevents cascading updates. Before code generation, we wrote this check manually (sometimes). Now it's guaranteed for every event setter.

Before the generator, we had code like this in PositionComponent:

void PositionComponent::setX(float x)
{
    if (areNotAlmostEqual(this->x, x))  // Sometimes we remembered the check
    {
        LOG_THIS(DOM);
        this->x = x;

        if (ecsRef)
            ecsRef->sendEvent(PositionComponentChangedEvent{id});
    }
}

But other setters forgot the check. Inconsistent. Now it's automatic.

Use case: Components that trigger system updates, fields that affect rendering or game state

Future: Level 4 - Custom Setters

We're planning a 4th level for complex custom logic:

- name: wrap
  type: bool
  default: false
  setter: custom
  custom_code: |
    this->wrap = value;
    this->changed = true;  // Custom logic
    recalculateLayout();   // More custom logic
    fireEvent();

This will allow embedding arbitrary C++ code for setters that need more than just event firing. Not yet implemented, but on the roadmap!

Constructor Generation

Components often need constructors with default parameters:

constructors:
  - params: [text, fontPath, scale, colors]
    defaults: {colors: "{255.0f, 255.0f, 255.0f, 255.0f}"}

Generated:

TTFText(const std::string& text,
        const std::string& fontPath,
        float scale,
        constant::Vector4D colors = {255.0f, 255.0f, 255.0f, 255.0f})
    : text(text)
    , fontPath(fontPath)
    , scale(scale)
    , colors(colors)
{}

Member initialization, default parameters, proper formatting—all automatic.

The Bootstrap Problem

Now we hit an interesting challenge: How do you build an engine that needs components when the components are generated by the engine?

This is a classic chicken-and-egg problem:

We need the engine to run PgScript
PgScript runs the component generator
The component generator creates components
The engine needs those components to build

Solution: The Bootstrap Compiler

Commit: b7508293 - "Can now build a minimal pgcompiler without any graphical deps"

We created a minimal PgCompiler that:

Has zero graphical dependencies (no SDL, no OpenGL)
Can run PgScript programs
Compiles separately from the main engine
Runs during CMake configuration phase

CMake Integration

# Build minimal bootstrap compiler first
add_executable(pgcompiler_bootstrap
    src/Engine/Compiler/*.cpp
    # Exclude graphical systems
)

# Generate components before main build
file(GLOB PGCOMP_FILES "src/Engine/Components/*.pgcomp")

foreach(PGCOMP_FILE ${PGCOMP_FILES})
    get_filename_component(COMP_NAME ${PGCOMP_FILE} NAME_WE)

    add_custom_command(
        OUTPUT "${CMAKE_BINARY_DIR}/Generated/${COMP_NAME}.generated.h"
        COMMAND pgcompiler_bootstrap
                tools/component_generator.pg
                ${PGCOMP_FILE}
        DEPENDS ${PGCOMP_FILE} tools/component_generator.pg
        COMMENT "Generating ${COMP_NAME} component..."
    )
endforeach()

Build flow:

CMake configures
Bootstrap compiler builds (fast, no graphics deps)
Component generator runs for each .pgcomp file
Generated files created in build/Generated/
Main engine build includes generated files

Beautiful.

Preventing Rebuild Loops

Problem: The generator ran every time, triggering full rebuilds even when nothing changed.

Commit: 3f771c7d - "Only regenerate .pgcomp file on change"

Solution:

add_custom_command(
    OUTPUT "${GENERATED_FILE}"
    COMMAND pgcompiler_bootstrap ... > "${GENERATED_FILE}.tmp"
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${GENERATED_FILE}.tmp"
            "${GENERATED_FILE}"
    DEPENDS ${PGCOMP_FILE}
)

copy_if_different only updates the file if content actually changed. This preserves timestamps and prevents unnecessary recompilation.

Migration: Real Impact with Real Numbers

Time to migrate our existing components and measure the impact.

PositionComponent - The Big One

PositionComponent is complex. It handles 2D transforms, anchoring, visibility, events, and more.

Before: The Manual Implementation

position.h (359 lines):

#pragma once

#include "ECS/system.h"
#include "pgconstant.h"

namespace pg
{
    enum class AnchorType : uint8_t { ... };
    enum class ResizeHandle : uint8_t { ... };

    struct PositionComponentChangedEvent
    {
        _unique_id id = 0;
    };

    struct PositionComponent : public Component
    {
        float x = 0.0f;
        float y = 0.0f;
        float z = 0.0f;
        float width = 0.0f;
        float height = 0.0f;
        float rotation = 0.0f;
        bool visible = true;
        bool observable = true;

        // Getters
        float getX() const { return x; }
        float getY() const { return y; }
        // ... 6 more getters

        // Setters with event firing
        void setX(float x);
        void setY(float y);
        // ... 6 more setters

        // Utility methods
        bool isVisible() const { return visible; }
        bool isObservable() const { return observable; }
        bool isRenderable() const { return visible && observable; }

        // ... more methods

        _unique_id id = 0;
        EntitySystem* ecsRef = nullptr;
    };
}

position.cpp (150 lines):

void PositionComponent::setX(float x)
{
    if (areNotAlmostEqual(this->x, x))
    {
        LOG_THIS(DOM);
        this->x = x;

        if (ecsRef)
            ecsRef->sendEvent(PositionComponentChangedEvent{id});
    }
}

// Repeat for setY, setZ, setWidth, setHeight, setRotation...

ecsserialization.cpp (98 lines for this component):

// VM proxy schema
auto positionProxySchema = [](VM* vm, EntityRef entity) -> Value {
    auto component = entity.getComponent<PositionComponent>();
    // ... 100 lines of proxy setup
};

// Serialization
archive("x", component->x);
archive("y", component->y);
// ... serialization for each field

Total: ~607 lines

After: The Declarative Implementation

PositionComponent.pgcomp (62 lines):

name: PositionComponent
namespace: pg
base_class: Component

includes:
  - "ECS/system.h"
  - "pgconstant.h"

forwards:
  - "struct UiAnchor;"

fields:
  - name: x
    type: float
    default: 0.0f
    setter: event

  - name: y
    type: float
    default: 0.0f
    setter: event

  - name: z
    type: float
    default: 0.0f
    setter: event

  - name: width
    type: float
    default: 0.0f
    setter: event

  - name: height
    type: float
    default: 0.0f
    setter: event

  - name: rotation
    type: float
    default: 0.0f
    setter: event

  - name: visible
    type: bool
    default: true
    setter: event

  - name: observable
    type: bool
    default: true
    setter: event

methods:
  - "bool isVisible() const { return visible; }"
  - "bool isObservable() const { return observable; }"
  - "bool isRenderable() const { return visible and observable; }"
  - "bool updatefromAnchor(const UiAnchor& anchor);"
  - "void setVisibility(const bool& value);"

events:
  - PositionComponentChangedEvent

Total: 62 lines

The Numbers

Reduction: 607 lines → 62 lines = 90% smaller

The Impact: Beyond Line Counts

Development Velocity

Adding a new component:

Before:
- Write struct definition
- Implement setters with event firing
- Add VM proxy schema
- Write serialization code
- Register attach handler
- Debug inconsistencies
After:
- Write .pgcomp definition
- Run generator
- Done

Adding a field to existing component:

Before:
- Update struct
- Add getter/setter
- Update proxy
- Update serialization
- Pray you didn't forget anything
After:
- Add 4 lines to .pgcomp
- Regenerate

Faster iteration, and less bug prone

Bug Reduction: The "Only Fire When Changed" Story

During code generation implementation, we discovered an important optimization:

void setX(float value)
{
    if (this->x != value) // This check!
    {  
        this->x = value;

        if (ecsRef)
        {
            ecsRef->sendEvent(PositionComponentChangedEvent{id});
        }
    }
}

The problem: Without the if (this->x != value) check, setting a field to its current value fires an event. Systems respond to that event. Those systems might set more fields. More events fire. Cascading updates.

Before the generator: This check was manual. Sometimes we remembered. Sometimes we forgot. Inconsistent.

After the generator: This check is in every event setter. Guaranteed. Consistent.

Commit: 25754476 - "Fixed event generation in component to only fire when the value changes"

One fix in the generator → all components benefit forever.

Documentation Benefits

The .pgcomp files double as documentation:

Before: "What fields does PositionComponent have?" → Open position.h, scroll through 359 lines of code

After: "What fields does PositionComponent have?" → Open PositionComponent.pgcomp, see 8 clear field definitions

fields:
  - name: x
    type: float
    default: 0.0f
    setter: event

Type, default value, behavior—all visible at a glance.

New team members understand components in minutes, not hours.

Lessons Learned: What Worked and What Didn't

What Went Exceptionally Well

Dogfooding Accelerated Language Development

Using PgScript to build engine tools revealed gaps:

String manipulation was basic → Added 46+ utility functions
File I/O needed write support → Added writeFile()
Array operations needed helpers → Added vector module
Type introspection was missing → Added typeof()

Every gap we filled made PgScript more capable. Not just for the generator, but for all PgScript users.

Lesson: Use your own tools. The pain you feel is real user pain.

Incremental Approach Reduced Risk

We didn't migrate everything at once:

Phase 1: Write the generator (simple Health component example)
Phase 2: Migrate PositionComponent (medium complexity)
Phase 3: Migrate TTFText (complex, with custom constructors)
Phase 4: Generate serialization and VM proxies

Each phase validated the approach. Each success built confidence.

Lesson: Small iterations makes it easier for refactoring old or complex systems.

What Was Challenging

YAML Parsing Complexity

Writing a YAML parser is harder than it looks:

Indentation tracking - Spaces vs tabs, mixed indentation
Nested structures - Objects within arrays within objects
Edge cases - Empty values, comments, multiline strings
Error handling - Where exactly did parsing fail?

The parser is now 400+ lines and still doesn't handle all YAML edge cases. We support the subset we need, but adding new .pgcomp features sometimes means parser changes.

Lesson: Consider an existing parser library if your language supports it. We couldn't, but you might be able to.

Build System Integration Took Iteration

The bootstrap compiler solution works, but we went through multiple iterations:

Attempt 1: Generate during build -> rebuild loops
Attempt 2: Generate in separate step -> dependency issues
Attempt 3: Bootstrap compiler -> chicken-and-egg problem
Final solution: Minimal bootstrap + copy_if_different

CMake's dependency tracking is subtle. Getting it right required patience and testing.

Lesson: Build system integration is never as simple as you think. Plan extra time.

Balancing Flexibility vs Simplicity

We have 4 setter levels. Is that too many? Not enough?

Some components need custom logic
Most components need simple patterns
Adding flexibility adds complexity

We're still finding the right balance. Too many options overwhelm users. Too few options make the system inflexible.

Lesson: Start simple. Add flexibility only when needed. Resist feature creep.

Future Improvements

Ideas for next iteration:

Better error messages - Parser errors should show line numbers
Validation - Catch typos in setter levels, invalid types
Component relationships - Parent/child components, dependencies
IDE integration - Syntax highlighting for .pgcomp files
Hot-reload - Change .pgcomp, see changes in editor without rebuild
Type checking - Validate field types against C++ types
Automatic Docs Creation - Reuse the YAML parser to automatically create the docs of the components in our official docs

Conclusion: The Power of Meta-Programming

Let's return to where we started: the 50th component.

Before the generator: Sigh. Another component. Open position.h, copy-paste struct definition, update field names, write 8 setters, add proxy schema, write serialization, register attach handler, test, debug, commit. 45 minutes later...

After the generator: Create WeaponComponent.pgcomp, define 5 fields, run generator. Done. 5 minutes.

That's the power of code generation. But the benefits run deeper:

Key Takeaways

1. Boilerplate is a Signal

Repetitive code isn't just annoying—it's a signal. If you're writing the same pattern over and over, automate it.

2. Dogfooding Accelerates Development

Using PgScript to build PgScript tools made the language better. Use your own creations. Feel the pain. Fix it.

3. Declarative > Imperative

Compare these:

607 lines of imperative C++
62 lines of declarative YAML

Which would you rather maintain?

4. Code Generation Compounds

The first component saved 545 lines. The second saved 200 more. The third will save even more. Benefits multiply with scale.

5. Meta-Programming is Accessible

You don't need complex C++ template magic. A simple script can generate code. YAML + string concatenation is often enough.

What's Your Boilerplate?

Think about your codebase:

What do you copy-paste frequently?
What patterns do you repeat?
Where do inconsistencies creep in?

That's your opportunity for code generation.

Maybe it's:

Database models
API endpoints
Serialization code
Unit test boilerplate
UI component definitions

Whatever it is, consider: Could a generator help?

Final Thought

"The best code is the code you don't have to write."

The component generator doesn't just save time—it eliminates entire classes of bugs, enforces consistency, and makes our ECS architecture more accessible to everyone on the team.

559 lines eliminated. Countless bugs prevented. Infinite time saved.

That's the journey from manual hell to declarative heaven.

Resources

ColumbaEngine Repository: github.com/Gallasko/ColumbaEngine
Component Generator Source: tools/component_generator.pg
Documentation:
- COMPONENT_GENERATOR.md
- COMPONENT_SCHEMA_REFERENCE.md

Key Commits Referenced

9f061bb6 - Start working on generator tool
191babed - Added native functions for string/file manipulation
3883d054 - Working basic component generator
4c6f4b5a - Added bootstrap compiler
b7508293 - Minimal pgcompiler without graphical deps
3f2ecc26 - Position component migration (-208 lines)
a9f154a4 - TTFText migration with constructor generation
25754476 - Fixed event generation optimization
3f771c7d - Only regenerate on change

Want to discuss code generation, ECS architecture, or game engine development? Find me on Discord or check out columbaengine.org.

Building Resize Handles That Actually Work: Lessons from a Game Engine Editor

Tue, 26 Aug 2025 00:00:00 GMT

Building Resize Handles That Actually Work: Lessons from a Game Engine Editor

You know that moment when you're using a design tool and you grab the corner of an element, expecting to resize it, but instead you accidentally move the whole thing? Or worse—nothing happens at all.

I just spent the afternoon implementing proper resize handles for a game engine editor, and it reminded me why good editor UX is so much harder than it looks. Here's what I learned building a system that prioritizes handle clicks over dragging, integrates with undo/redo, and doesn't break when you have complex UI hierarchies.

The Problem with "Simple" Resize Systems

Most resize implementations I've seen follow this pattern:

Draw some handles on a selection outline
Check if mouse clicks hit the handles
Resize on drag

Sounds straightforward. But the devil lives in the interaction priority. When you click near a resize handle, what should happen? In many editors, there's an annoying ambiguity—sometimes you resize, sometimes you select a different element, sometimes you start dragging.

The key insight: Handle clicks need absolute priority in the hit detection hierarchy.

Building Priority-Based Click Detection

Here's how I structured the click detection in the EntityFinder system:

virtual void onEvent(const OnMouseClick& event) override
{
    bool hit = false;

    // Priority 1: Check resize handles first
    for (const auto& elem : viewGroup<PositionComponent, ResizeHandleComponent>())
    {
        if (inClipBound(elem->entity, event.pos.x, event.pos.y))
        {
            hit = true;
            auto selectedId = selectionOutline.get<SelectedEntity>()->id;
            if (selectedId != 0)
            {
                ecsRef->sendEvent(StartResize{ selectedId, 
                    elem->get<ResizeHandleComponent>()->handle, 
                    event.pos.x, event.pos.y });
            }
            break;
        }
    }

    // Priority 2: Only check entities if no handle was clicked
    if (not hit)
    {
        // ... existing entity selection logic
    }
}

This priority system eliminates the frustrating "did I click the handle or the element?" problem. Handles always win.

The Eight-Handle Layout

I went with the classic eight-handle approach: four corners plus four edge midpoints. Each handle type maps to specific resize behavior:

enum class ResizeHandle : uint8_t
{
    None = 0,
    TopLeft, Top, TopRight,
    Left, Right,
    BottomLeft, Bottom, BottomRight
};

The tricky part is positioning these handles correctly. They need to:

Anchor to the selection outline's boundaries
Stay visible at different zoom levels
Have a consistent hit target size (8px)

I solved this with a helper function in the outline creation:

auto createResizeHandle = [&](ResizeHandle handleType, AnchorType anchorX, AnchorType anchorY) {
    auto handle = makeUiSimple2DShape(ecs, Shape2D::Square, handleSize, handleSize, handleColor);
    
    auto handleAnchor = handle.get<UiAnchor>();
    auto handleResizeComp = ecs->attach<ResizeHandleComponent>(handle.entity);
    handleResizeComp->handle = handleType;
    
    // Position based on anchor types
    if (anchorX == AnchorType::Left)
        handleAnchor->setLeftAnchor({outline.entity.id, AnchorType::Left, -handleSize/2});
    else if (anchorX == AnchorType::Right)
        handleAnchor->setRightAnchor({outline.entity.id, AnchorType::Right, -handleSize/2});
    // ... etc for all positions
};

The offset of -handleSize/2 centers the handle on the outline edge—a small detail that makes the interaction feel precise.

Resize Logic That Doesn't Fight You

The actual resize math varies by handle type. Corner handles modify both position and size, while edge handles only change one dimension:

switch (activeHandle)
{
    case ResizeHandle::TopLeft:
        newX = resizeStartX + deltaX;
        newY = resizeStartY + deltaY;
        newWidth = resizeStartWidth - deltaX;
        newHeight = resizeStartHeight - deltaY;
        break;
    case ResizeHandle::Right:
        newWidth = resizeStartWidth + deltaX;
        break;
    // ... other cases
}

Notice that when resizing from the top-left, the position changes inverse to the delta. This keeps the bottom-right corner fixed while the top-left moves—exactly what users expect.

I added a minimum size constraint to prevent elements from disappearing:

constexpr float minSize = 10.0f;
if (newWidth < minSize || newHeight < minSize)
    return;

Undo/Redo Integration

The resize system needed to play nicely with the existing command pattern. I created a ResizeCommand that captures the complete before/after state:

struct ResizeCommand : public InspectorCommands
{
    _unique_id entityId;
    ResizeHandle handle;
    float startWidth, startHeight, startX, startY;
    float endWidth, endHeight, endX, endY;
    
    virtual void execute() override {
        auto pos = ecsRef->getComponent<PositionComponent>(entityId);
        pos->setX(endX);
        pos->setY(endY);
        pos->setWidth(endWidth);
        pos->setHeight(endHeight);
    }
    
    virtual void undo() override {
        auto pos = ecsRef->getComponent<PositionComponent>(entityId);
        pos->setX(startX);
        pos->setY(startY);
        pos->setWidth(startWidth);
        pos->setHeight(startHeight);
    }
};

The command gets created when the resize operation ends, capturing the full transformation in one atomic operation.

Real-Time Visual Feedback

During resize, both the element and its selection outline update in real-time. This required careful coordination between the resize logic and the outline positioning:

// Update the element
pos->setX(newX);
pos->setY(newY);
pos->setWidth(newWidth);
pos->setHeight(newHeight);

// Update selection outline to match
auto ent = ecsRef->getEntity("SelectionOutline");
if (ent && ent->get<SelectedEntity>()->id == resizingEntity)
{
    auto outlinePos = ent->get<PositionComponent>();
    outlinePos->setX(newX - 2.f);
    outlinePos->setY(newY - 2.f);
    outlinePos->setWidth(newWidth + 4.f);
    outlinePos->setHeight(newHeight + 4.f);
}

The outline stays 2 pixels larger than the element on all sides, maintaining the visual relationship throughout the resize operation.

What I'd Do Differently

If I were starting fresh, I'd consider:

Constraint system integration

The current implementation checks for anchor constraints but could be smarter about respecting layout relationships during resize.

Aspect ratio locking

Adding Shift+drag to maintain proportions would make the tool more flexible.

Visual cursor feedback

Changing the cursor to resize arrows when hovering over handles would improve discoverability.

The Bigger Picture

Building resize handles taught me that good editor UX comes down to eliminating ambiguity. Users should never wonder "what will happen if I click here?" The system should handle the complexity so they can focus on their creative work.

The technical implementation—events, commands, hit detection—is just scaffolding. The real challenge is making interactions feel natural and predictable. When someone grabs a corner handle, they expect to resize from that corner. When they press Ctrl+Z, they expect the resize to undo completely.

Meeting those expectations requires thinking beyond the happy path to all the edge cases and failure modes. But when it works, the editor just disappears and lets users create.

Want to see the full implementation? The complete code is available in the ColumbaEngine repository with all the resize handle logic, priority-based detection, and undo/redo integration.

CMake for Complex Projects (Part 2): Building a C++ Game Engine from Scratch for Desktop and WebAssembly

Mon, 18 Aug 2025 00:00:00 GMT

A practical guide to modern CMake through a real-world C++ game engine project - Deployment & Distribution

Welcome back! In Part 1, we built a robust compilation and build system for our ColumbaEngine game engine. We covered project setup, dependency management, cross-platform builds, and testing. The response has been incredible - thank you to everyone who shared feedback, corrections, and suggestions!

Now it's time for the deployment side - the part where most CMake tutorials stop, but arguably the most important for real projects. How do you make your carefully crafted library actually usable by other developers? How do you create professional installers? How do you handle the complex world of package distribution?

This is where CMake really shows its power (and complexity). We'll dive deep into installation systems, export mechanisms, package configuration, and distribution strategies that turn your project from "works on my machine" to "works for everyone."

Note: The feedback from Part 1 has been fantastic, and several CMake experts have pointed out areas where my approach could be improved (modern FILE_SET usage, superbuild patterns, better dependency defaults, etc.). I'll be publishing an appendix soon addressing these insights - it's amazing how much you can learn from the community!

Recap: What We Built in Part 1

Our ColumbaEngine now has:

80+ source files compiled into a robust static library
Cross-platform support (Windows, Linux, Web)
Complex dependency management with vendored libraries
Precompiled headers for fast builds
Multiple executables and comprehensive testing

The Missing Piece: How do other developers use our engine?

Right now, they'd have to:

Clone our entire repository (including 500MB of dependencies)
Build everything from source
Manually figure out include paths and linking
Hope it works on their system

That's not professional. Let's fix it.

Step 9: Installation - Making Your Library Usable

This is where most tutorials stop, but it's crucial for real projects. How do other developers use your library?

The installation code goes at the end of your main CMakeLists.txt, after all targets have been defined:

# Install the library and its dependencies
install(TARGETS ColumbaEngine SDL2-static glm libglew_static freetype
    EXPORT ColumbaEngineTargets
    ARCHIVE DESTINATION lib        # .a files
    LIBRARY DESTINATION lib        # .so files
    RUNTIME DESTINATION bin        # .exe/.dll files
    INCLUDES DESTINATION include   # Header search path
)

# Install headers
install(DIRECTORY src/Engine/
    DESTINATION include/ColumbaEngine
    FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
)

# Create the package config files
install(EXPORT ColumbaEngineTargets
    FILE ColumbaEngineTargets.cmake
    NAMESPACE ColumbaEngine::
    DESTINATION lib/cmake/ColumbaEngine
)

After running make install (or sudo make install for system-wide installation), other projects can use your library like this:

find_package(ColumbaEngine REQUIRED)
target_link_libraries(MyGame PRIVATE ColumbaEngine::ColumbaEngine)

No manual include paths, no hunting for library files - just clean, simple usage.

The Export/Import Mechanism

The installation system is probably the most complex part of CMake. Let's break down what happens:

1. During Build (Export)

install(TARGETS ColumbaEngine SDL2-static glm
    EXPORT ColumbaEngineTargets  # ← This creates a target "export set"
    ARCHIVE DESTINATION lib
    INCLUDES DESTINATION include
)

This tells CMake: "When installing, remember these targets and their properties."

2. Target Properties Get Captured CMake captures each target's:

Include directories (target_include_directories)
Compile definitions (target_compile_definitions)
Link libraries (target_link_libraries)
Compile features (target_compile_features)

3. Export File Generation

install(EXPORT ColumbaEngineTargets
    FILE ColumbaEngineTargets.cmake
    NAMESPACE ColumbaEngine::        # ← Creates ColumbaEngine::ColumbaEngine
    DESTINATION lib/cmake/ColumbaEngine
)

This generates ColumbaEngineTargets.cmake containing:

# Generated file - don't edit!
add_library(ColumbaEngine::ColumbaEngine STATIC IMPORTED)
set_target_properties(ColumbaEngine::ColumbaEngine PROPERTIES
    INTERFACE_INCLUDE_DIRECTORIES "/usr/local/include/ColumbaEngine;/usr/local/include"
    INTERFACE_LINK_LIBRARIES "ColumbaEngine::SDL2-static;ColumbaEngine::glm;OpenGL::GL"
    # ... more properties
)

4. Package Configuration The ColumbaEngineConfig.cmake.in template becomes ColumbaEngineConfig.cmake:

# This runs when someone does find_package(ColumbaEngine)
find_dependency(OpenGL REQUIRED)  # Ensure dependencies are found first
include("${CMAKE_CURRENT_LIST_DIR}/ColumbaEngineTargets.cmake")  # Import our targets

5. User Experience When another project does find_package(ColumbaEngine):

CMake finds ColumbaEngineConfig.cmake
Runs the config script (finds OpenGL, loads targets)
ColumbaEngine::ColumbaEngine target becomes available
Users link to it and get all the transitive dependencies automatically

Why the Namespace?

The NAMESPACE ColumbaEngine:: is crucial:

Prevents conflicts: Multiple libraries might have a "Engine" target
Clear API: ColumbaEngine::ColumbaEngine is unambiguous
Import detection: Can check if(TARGET ColumbaEngine::ColumbaEngine)

Step 10: Package Configuration

Create cmake/ColumbaEngineConfig.cmake.in:

@PACKAGE_INIT@

include(CMakeFindDependencyMacro)

# Find required system dependencies that consumers need
if(NOT ${CMAKE_SYSTEM_NAME} MATCHES "Emscripten")
    find_dependency(OpenGL REQUIRED)
    find_dependency(Threads REQUIRED)

    # Find X11 libraries for SDL2
    find_package(X11 QUIET)
    if(X11_FOUND)
        # Create imported targets for X11 if they don't exist
        if(NOT TARGET X11::X11)
            add_library(X11::X11 UNKNOWN IMPORTED)
            set_target_properties(X11::X11 PROPERTIES
                IMPORTED_LOCATION "${X11_X11_LIB}"
                INTERFACE_INCLUDE_DIRECTORIES "${X11_X11_INCLUDE_PATH}"
            )
        endif()

        if(NOT TARGET X11::Xext AND X11_Xext_FOUND)
            add_library(X11::Xext UNKNOWN IMPORTED)
            set_target_properties(X11::Xext PROPERTIES
                IMPORTED_LOCATION "${X11_Xext_LIB}"
                INTERFACE_INCLUDE_DIRECTORIES "${X11_X11_INCLUDE_PATH}"
            )
        endif()
    endif()

    # Find other system dependencies that SDL2 might need
    find_package(PkgConfig QUIET)
    if(PKG_CONFIG_FOUND)
        pkg_check_modules(ALSA QUIET alsa)
        pkg_check_modules(PULSE QUIET libpulse-simple)
    endif()
endif()

# Include our targets
include("${CMAKE_CURRENT_LIST_DIR}/ColumbaEngineTargets.cmake")

# Provide variables for backward compatibility
set(ColumbaEngine_LIBRARIES ColumbaEngine::ColumbaEngine)

# Set include directories based on the imported target
get_target_property(ColumbaEngine_INCLUDE_DIRS ColumbaEngine::ColumbaEngine INTERFACE_INCLUDE_DIRECTORIES)

# Create an alias for easier consumption if it doesn't exist
if(NOT TARGET ColumbaEngine)
    add_library(ColumbaEngine ALIAS ColumbaEngine::ColumbaEngine)
endif()

check_required_components(ColumbaEngine)

This gets processed into ColumbaEngineConfig.cmake and installed. It ensures that when someone does find_package(ColumbaEngine), all dependencies are found automatically.

The Package Configuration Template System

The .cmake.in template system is CMake's way of generating configuration files with proper path handling. Let's see what each part does:

@PACKAGE_INIT@

This special macro expands to several helper functions and variables:

set_and_check(): Sets a variable and verifies the path exists
check_required_components(): Validates that requested components are available
PACKAGE_PREFIX_DIR: The installation prefix, relocated if needed

Why relocatable? If you install to /usr/local but someone copies the installation to /opt/columbaengine, the paths need to update automatically.

include(CMakeFindDependencyMacro)
find_dependency(OpenGL REQUIRED)

find_dependency is like find_package, but:

Forwards the QUIET and REQUIRED flags from the parent find_package call
Properly handles the dependency chain for error reporting
Works correctly with package components

Example: If someone calls find_package(ColumbaEngine REQUIRED QUIET), the OpenGL search will also be QUIET and REQUIRED.

include("${CMAKE_CURRENT_LIST_DIR}/ColumbaEngineTargets.cmake")

This loads the exported targets. The ${CMAKE_CURRENT_LIST_DIR} ensures we load from the same directory as the config file, making the installation relocatable.

check_required_components(ColumbaEngine)

This validates that all requested components are available. Our engine doesn't have components yet, but you might add them later:

find_package(ColumbaEngine REQUIRED COMPONENTS Renderer Audio Networking)

Advanced: Component-Based Installation

Here's how you could extend the engine with components:

# Install different parts as components
install(TARGETS ColumbaEngine_Core
    EXPORT ColumbaEngineTargets
    COMPONENT ColumbaEngine_Core
    ARCHIVE DESTINATION lib
)

install(TARGETS ColumbaEngine_Renderer
    EXPORT ColumbaEngineTargets
    COMPONENT ColumbaEngine_Renderer
    ARCHIVE DESTINATION lib
)

# In ColumbaEngineConfig.cmake.in
set(ColumbaEngine_Core_FOUND TRUE)

find_dependency(OpenGL)
if(OpenGL_FOUND)
    set(ColumbaEngine_Renderer_FOUND TRUE)
endif()

include("${CMAKE_CURRENT_LIST_DIR}/ColumbaEngineTargets.cmake")
check_required_components(ColumbaEngine)

Users could then request only the parts they need:

find_package(ColumbaEngine REQUIRED COMPONENTS Core)  # No renderer

Step 11: Package Distribution with CPack

Want to create installers? CPack has you covered. Currently, ColumbaEngine has basic CPack configuration:

# CPack configuration for creating installers
set(CPACK_PACKAGE_NAME "ColumbaEngine")
set(CPACK_PACKAGE_VENDOR "PigeonCodeur")
set(CPACK_PACKAGE_VERSION_MAJOR "1")
set(CPACK_PACKAGE_VERSION_MINOR "0")
set(CPACK_PACKAGE_VERSION_PATCH "0")
set(CPACK_PACKAGE_VERSION "${CPACK_PACKAGE_VERSION_MAJOR}.${CPACK_PACKAGE_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "ColumbaEngine - A modern C++ game engine")
set(CPACK_PACKAGE_CONTACT "pigeoncodeur@gmail.com")
set(CPACK_PACKAGE_HOMEPAGE_URL "https://github.com/Gallasko/ColumbaEngine")

# Detect available generators
set(CPACK_GENERATOR "TGZ")

# Check for DEB tools
find_program(DPKG_CMD dpkg)
if(DPKG_CMD)
    list(APPEND CPACK_GENERATOR "DEB")
endif()

# Check for RPM tools
find_program(RPMBUILD_CMD rpmbuild)
if(RPMBUILD_CMD)
    list(APPEND CPACK_GENERATOR "RPM")
endif()

include(CPack)

Run cpack and get basic installers for multiple package managers. The CPack configuration is still evolving and will be enhanced with more sophisticated packaging options in future updates.

CPack - From Source to Distribution

CPack is CMake's packaging system that transforms your built project into distributable packages. Let's understand how it works:

1. Package Discovery and Generator Selection

# Detect available packaging tools on the system
set(CPACK_GENERATOR "TGZ")  # Always available

find_program(DPKG_CMD dpkg)
if(DPKG_CMD)
    list(APPEND CPACK_GENERATOR "DEB")
endif()

find_program(RPMBUILD_CMD rpmbuild)
if(RPMBUILD_CMD)
    list(APPEND CPACK_GENERATOR "RPM")
endif()

This auto-detection means:

Linux systems with dpkg: Get .deb packages for Ubuntu/Debian
Linux systems with rpmbuild: Get .rpm packages for RHEL/Fedora
All systems: Get .tar.gz archives as fallback

2. Dependency Declaration

set(CPACK_DEBIAN_PACKAGE_DEPENDS "libgl1-mesa-dev, libfreetype6-dev")
set(CPACK_RPM_PACKAGE_REQUIRES "mesa-libGL-devel, freetype-devel")

This tells the package manager what system libraries your package needs. When users install your .deb, it automatically installs OpenGL and FreeType development packages.

3. Package Structure Control

# What gets packaged?
install(TARGETS ColumbaEngine COMPONENT Runtime)
install(DIRECTORY include/ DESTINATION include COMPONENT Development)
install(DIRECTORY examples/ DESTINATION share/ColumbaEngine/examples COMPONENT Examples)

# Create separate packages for different use cases
set(CPACK_COMPONENTS_ALL Runtime Development Examples)
set(CPACK_COMPONENT_RUNTIME_DESCRIPTION "ColumbaEngine runtime libraries")
set(CPACK_COMPONENT_DEVELOPMENT_DESCRIPTION "Headers and development files")

4. The Package Build Process When you run make package:

File Collection: CPack gathers all install() commands
Dependency Resolution: Checks what system libraries are needed
Metadata Generation: Creates package info (version, description, etc.)
Archive Creation: Builds the actual package file
Validation: Runs package-specific tests

Real-World Package Examples

Debian Package Contents:

columbaengine_1.0.0_amd64.deb
├── DEBIAN/
│   ├── control          # Package metadata
│   ├── postinst        # Post-installation script
│   └── prerm           # Pre-removal script
├── usr/
│   ├── lib/
│   │   ├── libColumbaEngine.a
│   │   └── cmake/ColumbaEngine/
│   └── include/ColumbaEngine/

RPM Package Structure:

columbaengine-1.0.0-1.x86_64.rpm
├── usr/lib64/libColumbaEngine.a
├── usr/include/ColumbaEngine/
└── usr/lib64/cmake/ColumbaEngine/

Advanced CPack: Custom Package Scripts

You can add custom installation behavior:

# Custom post-installation script
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/postinst;${CMAKE_CURRENT_SOURCE_DIR}/cmake/prerm")

Example postinst script:

#!/bin/bash
# Update library cache after installation
ldconfig
# Create symlinks for backward compatibility
ln -sf /usr/lib/libColumbaEngine.a /usr/lib/libGameEngine.a

Advanced Distribution Strategies

1. Multi-Package Strategy

For complex libraries, consider splitting into multiple packages:

# Runtime package - just the libraries
set(CPACK_COMPONENT_RUNTIME_DESCRIPTION "ColumbaEngine runtime libraries")
set(CPACK_COMPONENT_RUNTIME_REQUIRED TRUE)

# Development package - headers and CMake files
set(CPACK_COMPONENT_DEVELOPMENT_DESCRIPTION "Development files for ColumbaEngine")
set(CPACK_COMPONENT_DEVELOPMENT_DEPENDS Runtime)

# Documentation package - optional docs and examples
set(CPACK_COMPONENT_DOCUMENTATION_DESCRIPTION "Documentation and examples")
set(CPACK_COMPONENT_DOCUMENTATION_DEPENDS Development)

# Configure Debian packages
set(CPACK_DEB_COMPONENT_INSTALL ON)
set(CPACK_DEBIAN_RUNTIME_PACKAGE_NAME "libcolumbaengine1")
set(CPACK_DEBIAN_DEVELOPMENT_PACKAGE_NAME "libcolumbaengine-dev")
set(CPACK_DEBIAN_DOCUMENTATION_PACKAGE_NAME "libcolumbaengine-doc")

This creates three separate .deb files:

libcolumbaengine1.deb - Runtime libraries
libcolumbaengine-dev.deb - Development headers (depends on runtime)
libcolumbaengine-doc.deb - Documentation (optional)

2. Cross-Platform Packaging

# Platform-specific package settings
if(WIN32)
    set(CPACK_GENERATOR "ZIP;NSIS")
    set(CPACK_NSIS_DISPLAY_NAME "ColumbaEngine Game Engine")
    set(CPACK_NSIS_HELP_LINK "https://github.com/Gallasko/ColumbaEngine")
    set(CPACK_NSIS_URL_INFO_ABOUT "https://github.com/Gallasko/ColumbaEngine")
    set(CPACK_NSIS_MODIFY_PATH ON)
elseif(APPLE)
    set(CPACK_GENERATOR "TGZ;DragNDrop")
    set(CPACK_DMG_FORMAT "UDBZ")
    set(CPACK_DMG_VOLUME_NAME "ColumbaEngine")
elseif(UNIX)
    set(CPACK_GENERATOR "TGZ;DEB;RPM")
endif()

3. Version Management and Compatibility

# Semantic versioning
set(COLUMBAENGINE_VERSION_MAJOR 1)
set(COLUMBAENGINE_VERSION_MINOR 2)
set(COLUMBAENGINE_VERSION_PATCH 3)
set(COLUMBAENGINE_VERSION "${COLUMBAENGINE_VERSION_MAJOR}.${COLUMBAENGINE_VERSION_MINOR}.${COLUMBAENGINE_VERSION_PATCH}")

# ABI compatibility
set(COLUMBAENGINE_SOVERSION ${COLUMBAENGINE_VERSION_MAJOR})

# Set target properties for shared libraries
if(BUILD_SHARED_LIBS)
    set_target_properties(ColumbaEngine PROPERTIES
        VERSION ${COLUMBAENGINE_VERSION}
        SOVERSION ${COLUMBAENGINE_SOVERSION}
    )
endif()

# Package version file
write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/ColumbaEngineConfigVersion.cmake"
    VERSION ${COLUMBAENGINE_VERSION}
    COMPATIBILITY SameMajorVersion  # 1.x.x is compatible with 1.y.z
)

Real-World Distribution Workflows

1. Automated Package Building with CI

# .github/workflows/release.yml
name: Release
on:
  release:
    types: [published]

jobs:
  build-packages:
    strategy:
      matrix:
        os: [ubuntu-20.04, ubuntu-22.04, windows-latest]

    runs-on: ${{ matrix.os }}

    steps:
    - uses: actions/checkout@v3

    - name: Install dependencies (Linux)
      if: runner.os == 'Linux'
      run: |
        sudo apt-get update
        sudo apt-get install -y libgl1-mesa-dev libfreetype6-dev

    - name: Configure CMake
      run: |
        mkdir build
        cd build
        cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=OFF

    - name: Build
      run: cmake --build build --parallel

    - name: Create packages
      run: |
        cd build
        cpack

    - name: Upload packages
      uses: actions/upload-release-asset@v1
      with:
        upload_url: ${{ github.event.release.upload_url }}
        asset_path: build/*.deb
        asset_name: columbaengine-${{ github.event.release.tag_name }}-${{ matrix.os }}.deb
        asset_content_type: application/vnd.debian.binary-package

2. Package Repository Integration

For professional distribution, integrate with package repositories:

Debian/Ubuntu PPA:

# Configure for PPA upload
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Pigeon Codeur pigeoncodeur@gmail.com>")
set(CPACK_DEBIAN_PACKAGE_SECTION "libdevel")
set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
set(CPACK_DEBIAN_PACKAGE_HOMEPAGE "https://github.com/Gallasko/ColumbaEngine")

# Source package for PPA
set(CPACK_SOURCE_GENERATOR "TGZ")
set(CPACK_SOURCE_IGNORE_FILES "/build/;/.git/;/.github/;/import/")

3. (Future Work:) Documentation Integration

Include documentation in your packages:

# Find Doxygen
find_package(Doxygen)
if(DOXYGEN_FOUND)
    set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/docs)
    set(DOXYGEN_PROJECT_NAME "ColumbaEngine")
    set(DOXYGEN_PROJECT_VERSION ${PROJECT_VERSION})

    doxygen_add_docs(docs
        ${CMAKE_SOURCE_DIR}/src/Engine
        COMMENT "Generate API documentation"
    )

    # Install documentation
    install(DIRECTORY ${CMAKE_BINARY_DIR}/docs/html/
        DESTINATION share/doc/columbaengine
        COMPONENT Documentation
        OPTIONAL
    )
endif()

# Man pages for command-line tools
install(FILES
    ${CMAKE_SOURCE_DIR}/docs/columbaengine.1
    DESTINATION share/man/man1
    COMPONENT Documentation
    OPTIONAL
)

Testing Your Distribution

1. Installation Testing

Create a separate test project to verify your package works:

# test-installation/CMakeLists.txt
cmake_minimum_required(VERSION 3.18)
project(TestColumbaEngine)

find_package(ColumbaEngine REQUIRED)

add_executable(test_app main.cpp)
target_link_libraries(test_app PRIVATE ColumbaEngine::ColumbaEngine)

// test-installation/main.cpp
#include <ColumbaEngine/engine.h>

int main() {
    ColumbaEngine::Engine engine;
    if (engine.initialize()) {
        std::cout << "ColumbaEngine loaded successfully!" << std::endl;
        return 0;
    }
    return 1;
}

Testing script:

#!/bin/bash
# test-installation.sh

# Install the package
sudo dpkg -i columbaengine-dev_1.0.0_amd64.deb

# Test that find_package works
mkdir test-build && cd test-build
cmake ../test-installation
make

# Run the test
./test_app

# Clean up
cd ..
rm -rf test-build
sudo dpkg -r columbaengine-dev

2. Cross-Platform Validation

For consistent testing across different platforms and distributions, you can use Docker containers or virtual machines to validate that your packages install and work correctly on clean systems. This helps catch missing dependencies or platform-specific issues before your users encounter them.

The Complete User Experience

After implementing all these deployment concepts, here's what we achieved:

For Package Maintainers:

# Build and create all packages
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j8
cpack

# Results in:
# columbaengine-1.0.0-Linux.tar.gz
# (and .deb/.rpm if tools are available)

For System Installation:

# Install to system directories
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j8
sudo make install

# Now available system-wide
find_package(ColumbaEngine REQUIRED)  # Works in any CMake project

For End Users (Ubuntu/Debian):

# Install from package
sudo dpkg -i columbaengine-dev_1.0.0_amd64.deb

# Or from PPA
sudo add-apt-repository ppa:yourusername/columbaengine
sudo apt update
sudo apt install libcolumbaengine-dev

For Developers:

# In their CMakeLists.txt
find_package(ColumbaEngine 1.0 REQUIRED)
add_executable(MyGame src/main.cpp)
target_link_libraries(MyGame PRIVATE ColumbaEngine::ColumbaEngine)

# That's it! No manual configuration needed.

(Future Work): For Package Managers

# These integrations are planned for future releases

# Conan
conan install columbaengine/1.0.0@

# vcpkg
vcpkg install columbaengine

# CPM
CPMAddPackage("gh:Gallasko/ColumbaEngine@1.0.0")

Lessons Learned and Future Improvements

What Worked Well

Target-based approach: Made the export/import system much cleaner
Component separation: Allows users to install only what they need
Cross-platform packaging: Same CMake code generates packages for multiple platforms
Automated testing: Catches installation issues before users see them

Areas for Improvement

Based on the excellent feedback from Part 1, there are several areas I want to improve:

Modern CMake patterns: Exploring FILE_SET instead of target_include_directories
Superbuild approaches: For better dependency management and packaging
Dependency defaults: Making find_package the default with vendoring as fallback
Generator expression usage: Using them more judiciously

I'm working on an appendix that will address these improvements in detail - the CMake community feedback has been invaluable!

Conclusion

Building a professional distribution system with CMake involves several sophisticated concepts:

Export/Import Systems - Making your targets available to other projects
Package Configuration - Handling dependencies and relocatable installations
Multi-format Packaging - Supporting different package managers and platforms
Component Architecture - Allowing users to install only what they need
Version Management - Ensuring compatibility across different versions
Testing Infrastructure - Validating that your packages actually work

The deployment system we've built transforms ColumbaEngine from a complex, hard-to-use source project into a professional library that integrates seamlessly into any CMake-based project.

Remember: Distribution is not an afterthought - it's a core part of your project's success. A library that's hard to install and use won't get adopted, no matter how good the code is.

Your deployment system is your project's handshake with the world. Make it count.

The complete source code for ColumbaEngine with all the CMake patterns from this series is available on GitHub. These patterns scale from small libraries to large, complex applications.

Coming Next: An appendix addressing the excellent feedback from the CMake community, covering modern patterns like FILE_SET, superbuild approaches, and improved dependency management strategies.

What distribution challenges have you faced? Share your experiences in the comments below!

Self-hosting WebAssembly game with Astro

Tue, 12 Aug 2025 00:00:00 GMT

Embedding WASM games in Astro like itch.io does

I wanted to embed multiple playable WASM demos directly on my Astro site - click play, game loads in a modal, no page navigation. Basically what itch.io does, but self-hosted. Sounds simple, but WASM has some specific requirements that made this more complex than expected.

The problem

I had compiled my game engine (ColumbaEngine) to WebAssembly and wanted to showcase multiple demos on my site. Just dropping the files into Astro and calling it a day? Not happening. WASM needs specific headers, correct MIME types, and SharedArrayBuffer support for threading. Plus, I wanted a smooth experience where users could switch between demos without page reloads.

First attempt - just drop files in src/

Started by putting WASM files directly in the src directory. Astro's build process immediately broke this - files got hashed, moved around, and the WASM loader couldn't find anything.

// This doesn't work - Astro will process these files
Module.locateFile = (filename) => {
  return '/src/demos/' + filename; // Files won't be there after build
}

Moving to public/ - better but not enough

Moved everything to public/demos/. Files stay untouched during build, paths are predictable. Each demo gets its own directory:

public/demos/
├── demo1/
│   ├── demo1.wasm
│   ├── demo1.js
│   ├── demo1.data
│   └── demo1.worker.js
└── demo2/
    ├── game.wasm    # Some demos use different naming
    ├── game.js
    └── game.data

Created a flexible path resolver to handle naming variations

Different build tools and Emscripten versions produce different file naming patterns. Some demos had demo1.wasm, others had generic game.wasm. Instead of renaming everything manually (and breaking future builds), I built a fallback system that checks multiple naming patterns. First it looks for files matching the demo slug name, then falls back to generic names. This way I can drop in any WASM build and it just works.

function getGameConfig(slug) {
  return {
    wasmFile: `/demos/${slug}/${slug}.wasm`,
    jsFile: `/demos/${slug}/${slug}.js`,
    dataFile: `/demos/${slug}/${slug}.data`,
    workerFile: `/demos/${slug}/${slug}.worker.js`,
    fallbacks: {
      wasmFile: `/demos/${slug}/game.wasm`,
      jsFile: `/demos/${slug}/game.js`,
      dataFile: `/demos/${slug}/game.data`,
      workerFile: `/demos/${slug}/game.worker.js`
    }
  };
}

async function getWorkingPath(primary, fallback) {
  if (await checkFileExists(primary)) return primary;
  if (fallback && await checkFileExists(fallback)) return fallback;
  return primary;
}

With the files in place and the paths sorted, I thought I was done. Then I tried enabling threading and hit the next wall.

The CORS nightmare - SharedArrayBuffer requirements

SharedArrayBuffer enables true multi-threading in WASM, but browsers disabled it after Spectre/Meltdown unless you promise you know what you're doing via specific headers. Without Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy, your multi-threaded WASM silently falls back to single-threaded mode or just crashes with "SharedArrayBuffer is not defined". The worst part? These headers must be set everywhere - on the HTML page, on the WASM files, on the worker scripts. Miss one place and everything breaks.

Development setup via Vite plugin in astro.config.mjs:

function addCrossOriginHeaders() {
  return {
    name: 'add-cross-origin-headers',
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
        res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');

        // Correct MIME type for WASM
        if (req.url?.endsWith('.wasm')) {
          res.setHeader('Content-Type', 'application/wasm');
        }
        next();
      });
    }
  };
}

Production headers via public/_headers file (this is Cloudflare Pages' way of setting headers - other hosts use different methods like .htaccess or vercel.json):

/demos/*
  Cross-Origin-Embedder-Policy: require-corp
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Resource-Policy: cross-origin

The _headers file tells Cloudflare to apply these headers to anything under /demos/. But that's not enough - the HTML page loading the game also needs these headers, otherwise the browser blocks SharedArrayBuffer at the page level. So in the Astro page component itself:

// In src/pages/demos/index.astro
if (Astro.response) {
  Astro.response.headers.set('Cross-Origin-Embedder-Policy', 'require-corp');
  Astro.response.headers.set('Cross-Origin-Opener-Policy', 'same-origin');
}

Headers fixed, threading working. Now I needed a way to manage all these demos without editing code every time I added a new one.

Automating demo discovery

Instead of manually maintaining a list of demos, built a system that scans the demos directory at build time. Every time I add a new demo folder, it automatically appears on the site after rebuild. No config files to update, no hardcoded lists to maintain. Just drop a new WASM build in a folder and it's live. If a demo has a metadata.json file, it uses that for the title and description. Otherwise, it generates them from the folder name.

async function getDemos() {
  const fs = await import('fs/promises');
  const path = await import('path');
  const demosDir = 'public/demos';
  const demosList = [];

  const entries = await fs.readdir(demosDir);

  for (const entry of entries) {
    const demoPath = path.join(demosDir, entry);
    const stats = await fs.stat(demoPath);

    if (stats.isDirectory()) {
      const files = await fs.readdir(demoPath);

      // Optional metadata.json for custom info
      let metadata = {};
      try {
        const metadataPath = path.join(demoPath, 'metadata.json');
        const metadataContent = await fs.readFile(metadataPath, 'utf-8');
        metadata = JSON.parse(metadataContent);
      } catch {
        // Use defaults if no metadata
      }

      demosList.push({
        slug: entry,
        title: metadata.title || entry.charAt(0).toUpperCase() + entry.slice(1).replace(/-/g, ' '),
        description: metadata.description || `WebAssembly demo: ${entry}`,
        coverImage: files.find(f => f.match(/^cover\.(png|jpg|webp)$/)) ?
                    `/demos/${entry}/${coverImage}` : null,
        tags: metadata.tags || ['Demo']
      });
    }
  }
  return demosList;
}

So now I had a nice grid of demos that auto-populated from the file system. Clicking on them though? That's where things got interesting with Emscripten's expectations about DOM structure.

The modal loader

Built a modal system that creates a fresh canvas for each game. The key insight was that Emscripten expects a specific canvas element to exist before initialization, and it gets confused if you try to reuse the same canvas for different games. So instead of complex canvas recycling logic, I just create a new canvas element each time a user clicks play. The modal handles the overlay, escape key binding, and click-outside-to-close behavior, while the canvas container gets completely replaced for each game:

async function openGameModal(slug, title) {
  currentDemoSlug = slug;
  modal.classList.add('active');
  document.body.style.overflow = 'hidden';

  // Fresh canvas every time
  const canvas = document.createElement('canvas');
  canvas.id = 'canvas';
  canvas.width = 820;
  canvas.height = 640;

  canvasContainer.innerHTML = '';
  canvasContainer.appendChild(canvas);

  await loadGame(slug);
}

The actual WASM loading with Emscripten module setup:

async function loadGame(slug) {
  const canvas = document.getElementById('canvas');
  const config = getGameConfig(slug);

  // Get actual file paths with fallbacks
  const GAME_CONFIG = {
    wasmFile: await getWorkingPath(config.wasmFile, config.fallbacks.wasmFile),
    jsFile: await getWorkingPath(config.jsFile, config.fallbacks.jsFile),
    dataFile: await getWorkingPath(config.dataFile, config.fallbacks.dataFile),
    workerFile: await getWorkingPath(config.workerFile, config.fallbacks.workerFile)
  };

  // Module configuration
  window.Module = {
    canvas,

    locateFile(filename) {
      if (filename.endsWith('.wasm')) return GAME_CONFIG.wasmFile;
      if (filename.endsWith('.data')) return GAME_CONFIG.dataFile;
      if (filename.endsWith('.worker.js')) return GAME_CONFIG.workerFile;
      return `/demos/${slug}/` + filename;
    },

    monitorRunDependencies(left) {
      updateLoadingText(left ? `Loading... (${left} files)` : 'Starting...');
    },

    onRuntimeInitialized() {
      console.log('[WASM] Runtime initialized');
      updateLoadingText('Ready!');
      hideLoadingSoon();
      canvas.focus();
    },

    print: (t) => console.log('[GAME]', t),
    printErr: (t) => console.error('[GAME ERROR]', t)
  };

  // Enable threading if available
  const hasWorker = await checkFileExists(GAME_CONFIG.workerFile);
  const hasSAB = typeof SharedArrayBuffer !== 'undefined';

  if (hasWorker && hasSAB) {
    gameModule.PTHREAD_POOL_SIZE = 2;
    // Worker wrapper setup for SharedArrayBuffer support...
  }

  // Load WASM binary first
  const wasmResponse = await fetch(GAME_CONFIG.wasmFile);
  const wasmBuffer = await wasmResponse.arrayBuffer();
  gameModule.wasmBinary = wasmBuffer;

  // Then load the JS glue code
  const script = document.createElement('script');
  script.src = GAME_CONFIG.jsFile + '?t=' + Date.now();
  document.head.appendChild(script);
}

Everything was working great - games loaded, ran smoothly, modal closed properly. But then I noticed the browser getting slower after loading multiple demos. Time to deal with cleanup.

Memory management - the nuclear option

Tried implementing proper cleanup for switching between demos. Module cleanup, GL context disposal, worker termination - worked sometimes, crashed randomly. The games would leak memory, and after 4-5 demos the browser tab would die.

The solution? Page refresh:

function exitGame() {
  console.log('[WASM] Refreshing page to clean up game...');
  window.location.reload();
}

Sounds crude, but it's actually brilliant. The browser's built-in cleanup on page navigation is bulletproof. Since everything is static and cached (thanks to Astro's build process), the refresh is nearly instant. Users get a clean slate every time, no memory leaks, no accumulated state.

Production build considerations

Astro build configuration that keeps everything working:

export default defineConfig({
  output: 'static',

  adapter: cloudflare({
    mode: 'directory'
  }),

  vite: {
    plugins: [addCrossOriginHeaders()],
    assetsInclude: ['**/*.wasm', '**/*.data'],
    optimizeDeps: {
      exclude: ['*.wasm', '*.data', '*.worker.js']
    },
    build: {
      format: 'file' // Generates .html files for all routes
    }
  }
});

The result

A seamless WASM game embedding system that:

Loads games in modals without page navigation
Handles multiple file naming conventions
Supports SharedArrayBuffer and threading
Cleans up perfectly via page refresh
Works in development and production (Cloudflare Pages)
Auto-discovers demos from the file system

Live demos at: columbaengine.org/demos

The key lesson: stop fighting the platform. Browsers are really good at certain things - use those strengths instead of trying to reinvent them. WASM in the browser is complex enough without adding unnecessary complexity on top.

Understanding Modern Game Engine Architecture with ECS

Mon, 11 Aug 2025 00:00:00 GMT

Reading time: ~5 minutes | Level: Intermediate | Next: Building Complete Games with ColumbaEngine

Your Game Architecture Probably Sucks (And That's Not Your Fault)

Let's be honest. If you've built games the "traditional" way—with inheritance hierarchies, GameObject base classes, and virtual functions everywhere—you've probably hit that moment. You know the one. Where adding a simple feature means refactoring half your codebase. Where your "Player" class is 2,000 lines long. Where making a treasure chest that can be destroyed requires multiple inheritance gymnastics that would make a C++ compiler cry.

You're not alone. I've been there. The entire industry has been there. That's why Unity rewrote their entire engine with DOTS. Why Unreal built Mass Entity. Why id Software moved to ECS for DOOM Eternal. The old way of building games is fundamentally broken.

But here's the thing: there's a better way. It's called Entity Component System (ECS), and it's not just another programming pattern—it's a completely different way of thinking about game architecture. Today, I'll show you exactly how it works using ColumbaEngine, our production-ready ECS engine, with real code you can compile and run right now.

No theory. No abstract concepts. Just practical, working examples that will change how you build games forever.

Why Traditional Game Programming Is Broken

Let's say you're building an action RPG. You start with a reasonable class hierarchy:

class GameObject {
public:
    virtual void update(float deltaTime) = 0;
    virtual void render() = 0;
};

class Character : public GameObject {
protected:
    float health;
    float x, y;
    Sprite sprite;
public:
    void takeDamage(float amount) { health -= amount; }
    void move(float dx, float dy) { x += dx; y += dy; }
};

class Player : public Character { /* ... */ };
class Enemy : public Character { /* ... */ };

Looks good, right? Then reality hits:

"We need treasure chests" - They render and have position, but don't move or have health. Where do they fit?

"We need moving platforms" - They move but aren't characters. Another branch?

"We need ghosts that pass through walls" - Enemies that don't collide normally. Special case?

"We need destructible walls" - Have health but don't move. Now what?

Soon your clean hierarchy becomes a nightmare:

class GameObject { };
class PhysicalObject : public GameObject { };
class AnimatedObject : public GameObject { };
class AnimatedPhysicalObject : public PhysicalObject, public AnimatedObject { };
class Character : public AnimatedPhysicalObject { };
// ... endless combinations leading to chaos

I've seen real game projects with 147 GameObject subclasses, 23 levels of inheritance, and 40% of development time spent refactoring this mess. Adding a simple enemy type—something that should take hours—takes days of carefully threading it through the inheritance maze.

Enter ECS: A Radically Simple Solution

Entity Component System (ECS) completely reimagines game architecture. Instead of asking "what IS this object?" (inheritance), ECS asks "what DATA does this object have?" and "what SYSTEMS operate on that data?"

The Three Pillars of ECS

Entities: Just an ID

In ColumbaEngine, an entity is remarkably simple:

class Entity {
    _unique_id id;                    // Unique identifier
    std::list<EntityHeld> components;  // What components this entity has
    std::string name;                  // For debugging
};

That's it. An entity is just a unique ID that groups components together—a container, or even simpler, a sticky note saying "these components belong together."

Components: Pure Data

Components hold your game's state with zero logic:

struct Position : public Component {
    float x, y;
    DEFAULT_COMPONENT_MEMBERS(Position)
};

struct Velocity : public Component {
    float dx, dy;
    DEFAULT_COMPONENT_MEMBERS(Velocity)
};

struct Health : public Component {
    float current, max;
    DEFAULT_COMPONENT_MEMBERS(Health)
};

struct Sprite : public Component {
    std::string texturePath;
    int width, height;
    DEFAULT_COMPONENT_MEMBERS(Sprite)
};

No methods. No behavior. Just data. This separation is powerful—components are trivial to serialize, network, and modify with tools.

Systems: Pure Logic

Systems contain all your game logic, operating on entities with specific component combinations:

// Movement system - processes entities with Position AND Velocity
class MovementSystem : public System<Own<Position>, Own<Velocity>> {
public:
    void execute() override {
        float deltaTime = timer.getDeltaTime();

        // Process ALL entities that have both Position and Velocity
        for (auto [entity, pos, vel] : getEntities()) {
            pos->x += vel->dx * deltaTime;
            pos->y += vel->dy * deltaTime;
        }
    }
};

// Render system - draws entities with Position AND Sprite
class RenderSystem : public System<Own<Position>, Own<Sprite>> {
public:
    void execute() override {
        for (auto [entity, pos, sprite] : getEntities()) {
            drawSprite(sprite->texturePath, pos->x, pos->y);
        }
    }
};

The system doesn't care what entity it's processing—player, enemy, projectile—if it has the required components, it gets processed.

The Power of Composition

Here's how those problematic game objects look in ColumbaEngine:

// Player - moves, renders, takes damage, player-controlled
Entity player = ecs->createEntity("Player");
ecs->attach<Position>(player, {100, 100});
ecs->attach<Velocity>(player, {0, 0});
ecs->attach<Sprite>(player, {"player.png", 32, 32});
ecs->attach<Health>(player, {100, 100});
ecs->attach<PlayerController>(player);

// Enemy - same as player but AI-controlled
Entity enemy = ecs->createEntity("Goblin");
ecs->attach<Position>(enemy, {300, 100});
ecs->attach<Velocity>(enemy, {0, 0});
ecs->attach<Sprite>(enemy, {"goblin.png", 32, 32});
ecs->attach<Health>(enemy, {50, 50});
ecs->attach<AIController>(enemy);  // Only difference!

// Treasure chest - renders, has position, but doesn't move
Entity chest = ecs->createEntity("TreasureChest");
ecs->attach<Position>(chest, {200, 200});
ecs->attach<Sprite>(chest, {"chest.png", 32, 32});
ecs->attach<Container>(chest, {{"gold", 100}});

// Ghost - enemy that passes through walls
Entity ghost = ecs->createEntity("Ghost");
ecs->attach<Position>(ghost, {400, 400});
ecs->attach<Velocity>(ghost, {0, 0});
ecs->attach<Sprite>(ghost, {"ghost.png", 32, 32});
ecs->attach<Health>(ghost, {30, 30});
ecs->attach<AIController>(ghost);
// Note: No Collider component = passes through walls!

// Moving platform - moves but no health or AI
Entity platform = ecs->createEntity("MovingPlatform");
ecs->attach<Position>(platform, {150, 300});
ecs->attach<Velocity>(platform, {50, 0});
ecs->attach<Sprite>(platform, {"platform.png", 64, 16});
ecs->attach<Path>(platform, {{150, 300}, {250, 300}});

No inheritance hierarchies. No virtual functions. No "is-a" relationships. Just entities with exactly the components they need.

Want the chest to be destructible? Add a Health component. Want the ghost to leave a trail? Add a ParticleEmitter. Each change is one line that doesn't affect anything else.

Real-World Example: Building Tetris with ECS

Let's build something real. Here's how Tetris works in ColumbaEngine:

// Tetris-specific components
struct GridPosition : public Component {
    int x, y;  // Position in game grid (not pixels)
    DEFAULT_COMPONENT_MEMBERS(GridPosition)
};

struct TetrisPiece : public Component {
    enum Type { I, O, T, S, Z, J, L } type;
    int rotation = 0;
    DEFAULT_COMPONENT_MEMBERS(TetrisPiece)
};

struct FallTimer : public Component {
    float timeUntilFall;
    float fallSpeed;
    DEFAULT_COMPONENT_MEMBERS(FallTimer)
};

// Create a falling piece
Entity piece = ecs->createEntity("ActivePiece");
ecs->attach<GridPosition>(piece, {5, 0});        // Start at top
ecs->attach<TetrisPiece>(piece, {Type::T, 0});   // T-shaped piece
ecs->attach<FallTimer>(piece, {1.0f, 1.0f});     // Fall every second
ecs->attach<Sprite>(piece, {"t_piece.png", 30, 30});
ecs->attach<PlayerControllable>(piece);          // Player can control

Now the systems that make it work:

// Handles piece falling
class TetrisFallSystem : public System<Own<GridPosition>,
                                       Own<TetrisPiece>,
                                       Own<FallTimer>> {
public:
    void execute() override {
        float deltaTime = timer.getDeltaTime();

        for (auto [entity, gridPos, piece, fallTimer] : getEntities()) {
            fallTimer->timeUntilFall -= deltaTime;

            if (fallTimer->timeUntilFall <= 0) {
                fallTimer->timeUntilFall = fallTimer->fallSpeed;

                if (canMoveTo(gridPos->x, gridPos->y + 1, piece)) {
                    gridPos->y += 1;
                } else {
                    lockPiece(entity);
                }
            }
        }
    }

private:
    void lockPiece(Entity entity) {
        ecs->detach<PlayerControllable>(entity);
        ecs->detach<FallTimer>(entity);
        ecs->sendEvent(PieceLocked{entity});
        ecs->sendEvent(CheckForLines{});
        ecs->sendEvent(SpawnNewPiece{});
    }
};

// Handles player input
class TetrisInputSystem : public System<Own<PlayerControllable>,
                                        Own<GridPosition>,
                                        Own<TetrisPiece>> {
public:
    void onKeyPressed(int key) {
        for (auto [entity, control, gridPos, piece] : getEntities()) {
            switch(key) {
                case KEY_LEFT:
                    if (canMoveTo(gridPos->x - 1, gridPos->y, piece))
                        gridPos->x -= 1;
                    break;

                case KEY_RIGHT:
                    if (canMoveTo(gridPos->x + 1, gridPos->y, piece))
                        gridPos->x += 1;
                    break;

                case KEY_UP:
                    rotatePiece(piece);
                    break;

                case KEY_DOWN:
                    // Speed up falling
                    if (auto timer = ecs->getComponent<FallTimer>(entity))
                        timer->fallSpeed = 0.05f;
                    break;
            }
        }
    }
};

Notice the magic? The FallSystem doesn't know about input or rendering. The InputSystem doesn't know about the board state. The RenderSystem (which we already defined) will automatically draw anything with Position and Sprite. They communicate through events without knowing about each other.

Why This Changes Everything

Performance That Scales

ECS provides massive performance benefits through data locality:

// Traditional OOP - objects scattered in memory
GameObject* objects[1000];
for (int i = 0; i < 1000; i++) {
    objects[i]->update();  // Cache miss likely for each object
}

// ECS - components stored contiguously
Position positions[1000];
Velocity velocities[1000];
for (int i = 0; i < 1000; i++) {
    positions[i].x += velocities[i].dx * deltaTime;  // Cache-friendly!
}

Real measurements show 5-10x performance improvements for systems processing many entities.

Flexibility Without Complexity

Need to add a feature? Just create a new component and system:

// Add particle effects to any entity
struct ParticleEmitter : public Component {
    std::string particleType;
    float rate;
};

class ParticleSystem : public System<Own<Position>, Own<ParticleEmitter>> {
    void execute() override {
        for (auto [entity, pos, emitter] : getEntities()) {
            spawnParticles(pos->x, pos->y, emitter->particleType, emitter->rate);
        }
    }
};

// Now ANY entity can have particles
ecs->attach<ParticleEmitter>(player, {"sparkle", 10.0f});
ecs->attach<ParticleEmitter>(treasure, {"glow", 5.0f});

Parallel Processing for Free

Systems that don't share components can run in parallel:

// These can run simultaneously
parallel_execute(
    movementSystem,      // Modifies: Position
    animationSystem,     // Modifies: Sprite
    particleSystem,      // Modifies: ParticleEmitter
    audioSystem          // Modifies: AudioSource
);

ColumbaEngine automatically detects parallelization opportunities, giving you free performance on multi-core processors.

The Industry Is Moving to ECS

This isn't just theory. Major engines are adopting ECS because it works:

Unity DOTS: Complete ECS rewrite for 100x performance gains
Unreal Mass Entity: ECS for massive crowds and simulations
Bevy: Rust engine built entirely on ECS
Godot: Experimenting with ECS for Godot 4.x

By learning ECS through ColumbaEngine's clean implementation, you're learning the future of game development.

Start Building with ColumbaEngine Today

Ready to experience ECS yourself? Here's how to start:

1. Clone and Build:

git clone https://github.com/columbaengine/columba
cd columba && mkdir build && cd build
cmake .. && make
./examples/tetris  # Play the Tetris example

2. Create Your First Game:

auto ecs = std::make_unique<EntitySystem>();

// Create player
auto player = ecs->createEntity("Player");
ecs->attach<Position>(player, {100, 100});
ecs->attach<Velocity>(player, {0, 0});
ecs->attach<Sprite>(player, {"player.png", 32, 32});

// Create enemy
auto enemy = ecs->createEntity("Enemy");
ecs->attach<Position>(enemy, {200, 100});
ecs->attach<Velocity>(enemy, {-10, 0});
ecs->attach<Sprite>(enemy, {"enemy.png", 32, 32});

// Systems automatically process them!

3. Join the Community:

GitHub: github.com/columbaengine
Discord: Active developers building real games
Docs: Complete API reference and tutorials

Why ColumbaEngine?

ColumbaEngine isn't just another engine—it's a learning platform for modern game architecture. With clean, readable code and a pure ECS implementation, it's perfect for:

Learning: Understand how modern engines really work
Prototyping: Build games quickly with minimal boilerplate
Production: Ships with WebAssembly support for browser deployment
Teaching: Clear architecture perfect for education

Whether you're building your first game or your hundredth, ColumbaEngine's ECS architecture provides the foundation you need without the complexity you don't.

Next Steps

The best way to understand ECS is to use it. Download ColumbaEngine, run the examples, and build something. Start small—a Pong clone, a simple shooter—and watch how naturally features come together.

In future articles, we'll explore:

Advanced ECS patterns and optimizations
Building multiplayer with component synchronization
WebAssembly deployment for browser games
Creating custom tools and editors

The game industry is moving toward data-driven architectures. Join us at the forefront with ColumbaEngine.

Ready to revolutionize how you build games? Star us on GitHub and join our Discord community.

CMake for Complex Projects (Part 1): Building a C++ Game Engine from Scratch for Desktop and WebAssembly

Thu, 07 Aug 2025 00:00:00 GMT

A practical guide to modern CMake through a real-world C++ game engine project - Compilation & Build Management

If you've ever tried to build a C++ project with multiple dependencies and cross-platform support, you know the pain. Makefiles become unwieldy, Visual Studio solutions don't work on Linux, and don't even get me started on trying to distribute your library for others to use.

This is where CMake shines. But most CMake tutorials show you toy examples with a single hello.cpp file. Today, we're going deep with a complex project - a complete game engine called ColumbaEngine (source code available here) with 80+ source files, multiple platforms (including web compilation), and a sophisticated build system.

This is Part 1 of a two-part series. In this article, we'll focus on the compilation and build management aspects: setting up the project, handling dependencies, cross-platform builds, and testing. In Part 2, we'll cover the deployment side: installation systems, package generation, and distribution.

By the end of this article, you'll understand how to structure CMake for medium to large projects, handle complex dependencies, and create professional build systems that compile reliably across platforms.

What Makes This Project Interesting?

Before we dive into CMake, let's understand what we're building:

80+ C++ source files organized in modules (ECS, Renderer, Audio, UI, etc.)
Cross-platform: Windows, Linux, and Web (via Emscripten)
Multiple dependencies: SDL2, OpenGL, FreeType, custom libraries
Installable library: Other projects can use it with find_package()
Example applications: Several games and tools
Package generation: Creates .deb, .rpm, and other installers

This isn't a toy project - it's a real game engine that needs a robust build system.

Project Structure: The Foundation

Here's how our game engine is organized:

ColumbaEngine/
├── CMakeLists.txt             # Main build file
├── src/
│   ├── Engine/                # Core engine code
│   │   ├── ECS/               # Entity-Component-System
│   │   ├── Renderer/          # Graphics rendering
│   │   └── Audio/             # Sound system
│   └── main.cpp               # Editor application
├── examples/                  # Example games
├── import/                    # Vendored dependencies
├── cmake/                     # CMake modules
└── test/                      # Unit tests

The CMakeLists.txt is our blueprint. Let's build it step by step.

Step 1: Project Setup and Configuration

cmake_minimum_required(VERSION 3.18)
project(ColumbaEngine VERSION 1.0)

# User-configurable options
option(BUILD_EXAMPLES "Build example applications" ON)
option(BUILD_STATIC_LIB "Build static library only" OFF)
option(ENABLE_TIME_TRACE "Add -ftime-trace to Clang builds" OFF)

# Global settings
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)  # For IDE support
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)

Key concepts here:

cmake_minimum_required: We use 3.18+ for modern features like precompiled headers
option(): Creates user-configurable boolean flags. Users can run cmake -DBUILD_EXAMPLES=OFF ..
CMAKE_EXPORT_COMPILE_COMMANDS: Generates compile_commands.json for IDEs and tools like clangd

Step 2: The Dependency Challenge

Real projects have dependencies. Lots of them. Our game engine needs SDL2 for windowing, FreeType for text rendering, OpenGL for graphics, and more.

We use a vendoring approach - including dependencies directly in our source tree:

# Dependency paths - everything is self-contained
set(SDL2_DIR "import/SDL2-2.28.5")
set(SDL2MIXER_DIR "import/SDL2_mixer-2.6.3")
set(GLM_DIR "import/glm")
set(TASKFLOW_DIR "import/taskflow-3.6.0")
set(GTEST_DIR "import/googletest-1.14.0")

# Configure dependencies before building them
set(TF_BUILD_EXAMPLES OFF)    # Don't build taskflow examples
set(TF_BUILD_TESTS OFF)       # Don't build taskflow tests
set(BUILD_SHARED_LIBS OFF)    # Force static linking
set(SDL2_DISABLE_INSTALL ON)  # We'll handle installation ourselves

Why vendor dependencies?

✅ Pros: Exact version control, works offline, simplified build

❌ Cons: Larger repo size, manual updates

For a game engine where stability is crucial, vendoring makes sense. For web services that need frequent security updates, you might prefer package managers.

Deep Dive: Dependency Management Strategies

Choosing how to handle dependencies is one of the most critical architectural decisions in C++. Let's compare the approaches:

1. Vendoring (Our Current Approach)

# Everything is self-contained in import/
set(SDL2_DIR "import/SDL2-2.28.5")
set(GLM_DIR "import/glm")
add_subdirectory(${SDL2_DIR})
add_subdirectory(${GLM_DIR})

Advantages:

Reproducible builds: Exact same versions everywhere
Offline builds: No internet required after initial clone
Control: Can patch dependencies if needed
Simplicity: No external tools or package managers

Disadvantages:

Repository size: Our import/ folder is 500MB+
Update overhead: Manual process to update dependencies
Security: Must manually track and update vulnerable dependencies
License complexity: Must distribute all licenses

2. Package Managers (Conan, vcpkg)

# With Conan
include(conan)
conan_cmake_run(REQUIRES
    SDL2/2.28.5
    glm/0.9.9.8
    BASIC_SETUP CMAKE_TARGETS
    BUILD missing
)
target_link_libraries(ColumbaEngine PRIVATE CONAN_PKG::SDL2 CONAN_PKG::glm)

Advantages:

Smaller repos: Dependencies downloaded on-demand
Easy updates: conan install --update
Binary packages: Pre-built binaries for faster builds
Ecosystem: Thousands of packages available

Disadvantages:

External dependency: Requires internet and package manager
Version conflicts: Diamond dependency problems
Platform support: Not all packages support all platforms
Learning curve: Another tool to learn and maintain

3. FetchContent (Modern CMake)

include(FetchContent)

FetchContent_Declare(glm
    GIT_REPOSITORY https://github.com/g-truc/glm.git
    GIT_TAG 0.9.9.8
    GIT_SHALLOW TRUE
)

FetchContent_Declare(SDL2
    URL https://github.com/libsdl-org/SDL/releases/download/release-2.28.5/SDL2-2.28.5.tar.gz
    URL_HASH SHA256=332cb37d0be20cb9541739c61f79bae5a477427d79ae85e352089afdaf6666e4
)

FetchContent_MakeAvailable(glm SDL2)
target_link_libraries(ColumbaEngine PRIVATE glm SDL2::SDL2)

Advantages:

CMake native: No external tools required
Flexible sources: Git repos, URLs, local paths
Version pinning: Exact commits/tags
Cross-platform: Works everywhere CMake works

Disadvantages:

Build time: Downloads and builds on first configure
Internet required: At least for first build
No binary caching: Always builds from source

Hybrid Approach: The Best of Both Worlds

For ColumbaEngine, we could evolve to a hybrid approach:

# Critical, stable dependencies: Vendor them
set(SDL2_DIR "import/SDL2-2.28.5")
add_subdirectory(${SDL2_DIR})

# Development/testing dependencies: FetchContent
if(BUILD_TESTS)
    include(FetchContent)
    FetchContent_Declare(googletest
        GIT_REPOSITORY https://github.com/google/googletest.git
        GIT_TAG v1.14.0
        GIT_SHALLOW TRUE
    )
    FetchContent_MakeAvailable(googletest)
endif()

# Optional dependencies: find_package with fallback
find_package(Doxygen)
if(NOT Doxygen_FOUND AND ENABLE_DOCS)
    FetchContent_Declare(doxygen
        URL https://github.com/doxygen/doxygen/releases/download/Release_1_9_8/doxygen-1.9.8.src.tar.gz
    )
    FetchContent_MakeAvailable(doxygen)
endif()

Step 3: Cross-Platform Reality Check

Our engine supports three platforms, with different flags and need:

Native (Windows/Linux): Build everything from source
Emscripten (Web): Use system-provided libraries

if(${CMAKE_SYSTEM_NAME} MATCHES "Emscripten")
    # Web build - use Emscripten's built-in libraries
    set(USE_FLAGS "-O3 -sUSE_SDL=2 -sUSE_SDL_MIXER=2 -sUSE_FREETYPE=1 -fwasm-exceptions")
    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${USE_FLAGS}")
else()
    # Native build - compile dependencies from source
    add_subdirectory(${SDL2_DIR})
    add_subdirectory(${SDL2MIXER_DIR})
    add_subdirectory(${GLEW_DIR})
    add_subdirectory(${TTF_DIR})
endif()

# GLM is header-only, works everywhere
add_subdirectory(${GLM_DIR})

Platform detection patterns:

CMAKE_SYSTEM_NAME: Target platform (Windows, Linux, Darwin, Emscripten)
CMAKE_HOST_SYSTEM: Build machine platform
Use generator expressions for conditional compilation: $<$<PLATFORM_ID:Windows>:WIN32_CODE>

Step 4: Creating the Main Target

Now for the heart of our build - the engine library itself:

# List all source files (80+ files in our case!)
set(ENGINESOURCE
    src/Engine/window.cpp
    src/Engine/configuration.cpp
    src/Engine/logger.cpp
    # ... 70+ more files
    src/Engine/UI/uisystem.cpp
)

# Create the static library
add_library(ColumbaEngine STATIC ${ENGINESOURCE})

# Modern CMake magic - precompiled headers for faster builds
target_precompile_headers(ColumbaEngine PUBLIC src/Engine/stdafx.h)

Precompiled headers can cut build times by 50%+ in large projects. They compile commonly used headers once and reuse the result.

Precompiled Headers - The Build Speed Game Changer

Precompiled headers (PCH) are one of the most impactful optimizations for C++ build times, yet they're often overlooked. Let's understand how they work:

The Problem: Header Parsing Overhead

// Every .cpp file typically includes these
#include <iostream>    // ~15,000 lines when fully expanded
#include <vector>      // ~8,000 lines
#include <string>      // ~12,000 lines
#include <memory>      // ~6,000 lines
#include <SDL2/SDL.h>  // ~25,000 lines
// Total: ~66,000 lines to parse per source file!

With 80 source files, that's 5.2 million lines of redundant header parsing!

The Solution: Precompiled Headers

target_precompile_headers(ColumbaEngine PUBLIC src/Engine/stdafx.h)

Our stdafx.h contains the most commonly used headers:

// stdafx.h - precompiled header
#pragma once

// Standard library
#include <iostream>
#include <vector>
#include <string>
#include <memory>
#include <unordered_map>
#include <algorithm>

// Third-party libraries
#include <SDL2/SDL.h>
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>

// Engine fundamentals used everywhere
#include "types.h"
#include "logger.h"
#include "configuration.h"

How It Works:

Compilation: CMake compiles stdafx.h once into stdafx.h.gch (GCC) or stdafx.pch (MSVC)
Reuse: Every source file automatically uses the precompiled version
Speed: 66,000 lines → 0 lines to parse per file

Build Time Results (80 source files):

Without PCH: ~8 minutes clean build
With PCH: ~3 minutes clean build
Incremental: Single file changes drop from 15s to 3s

PUBLIC vs PRIVATE PCH:

# PUBLIC: Users of your library get the PCH benefits too
target_precompile_headers(ColumbaEngine PUBLIC stdafx.h)

# PRIVATE: Only internal compilation uses PCH
target_precompile_headers(ColumbaEngine PRIVATE stdafx.h)

Best Practices for PCH:

// Good PCH content: Stable, frequently used headers
#include <vector>          // Used in 90% of files
#include <SDL2/SDL.h>      // Core dependency

// Bad PCH content: Frequently changing headers
#include "GameLogic.h"     // Changes often, invalidates PCH
#include "debug_temp.h"    // Temporary debugging code

PCH Pitfalls:

Overuse: Adding changing headers defeats the purpose
Platform differences: MSVC vs GCC handle PCH differently
Dependencies: PCH creates implicit dependencies between files

Step 5: Usage Requirements - The Secret Sauce

This is where modern CMake really shines. Instead of users manually figuring out include paths and linking, we specify usage requirements:

target_include_directories(ColumbaEngine PUBLIC
    # When building this library
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src/Engine>
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src/GameElements>
    # When using installed version
    $<INSTALL_INTERFACE:include/ColumbaEngine>
    $<INSTALL_INTERFACE:include/ColumbaEngine/GameElements>
)

Generator expressions ($<...>) are evaluated during build generation:

BUILD_INTERFACE: Only when building this project
INSTALL_INTERFACE: Only when using the installed version
$<CONFIG:Debug>: Only in Debug builds
$<PLATFORM_ID:Windows>: Only on Windows

Why Generator Expressions Matter

Let's understand why this is so powerful. Consider this traditional approach:

# The old, problematic way
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DDEBUG_MODE")
endif()

Problems with this approach:

Build-time evaluation: The condition is checked when CMake configures, not when you build
Global pollution: Affects ALL targets in the project
Multi-config generators: Breaks with Visual Studio, Xcode which support multiple configs

Generator expressions solve this:

# Modern, correct approach
target_compile_definitions(MyTarget PRIVATE
    $<$<CONFIG:Debug>:DEBUG_MODE>
    $<$<CONFIG:Release>:NDEBUG>
    $<$<PLATFORM_ID:Windows>:WIN32_LEAN_AND_MEAN>
)

This is evaluated per-target, per-configuration, at build time. Much more flexible and robust.

Common Generator Expression Patterns

# Conditional compilation flags
target_compile_options(MyTarget PRIVATE
    $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra>
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
)

# Debug vs Release libraries
target_link_libraries(MyTarget PRIVATE
    $<$<CONFIG:Debug>:MyLib_d>
    $<$<CONFIG:Release>:MyLib>
)

# Platform-specific linking
target_link_libraries(MyTarget PRIVATE
    $<$<PLATFORM_ID:Windows>:ws2_32>
    $<$<PLATFORM_ID:Linux>:pthread>
)

Step 6: Dependency Linking - Getting Scope Right

Here's a crucial concept: PUBLIC vs PRIVATE vs INTERFACE

if (${CMAKE_SYSTEM_NAME} MATCHES "Emscripten")
    # Web build
    target_link_libraries(ColumbaEngine PUBLIC glm)
else()
    # Native build - note the scoping!
    target_link_libraries(ColumbaEngine PUBLIC
        SDL2::SDL2-static      # Users need SDL2 headers
        glm                    # Header-only math library
        OpenGL::GL            # Graphics API
    )

    target_link_libraries(ColumbaEngine PRIVATE
        libglew_static        # Internal OpenGL extension loading
        freetype              # Internal text rendering
    )
endif()

Scope meanings:

PUBLIC: "I use this, and my users will need it too"
PRIVATE: "I use this internally, but my users don't need to know"
INTERFACE: "I don't use this, but my users will need it"

Get this right, and users of your library automatically get the right dependencies. Get it wrong, and you'll have angry developers filing issues.

Understanding Transitive Dependencies

Let's look at a real example from our engine. Imagine this dependency chain:

MyGame → ColumbaEngine → SDL2 → OpenGL

If we declare SDL2 as PRIVATE to ColumbaEngine:

target_link_libraries(ColumbaEngine PRIVATE SDL2::SDL2-static)

Problem: MyGame won't be able to use SDL2 types in the public API. If ColumbaEngine's headers include <SDL2/SDL.h>, users get compile errors.

If we declare SDL2 as PUBLIC:

target_link_libraries(ColumbaEngine PUBLIC SDL2::SDL2-static)

Result: MyGame automatically gets SDL2 headers and libraries. Perfect for our engine where users need SDL2 types.

The INTERFACE Scope Mystery

INTERFACE is the trickiest to understand. It means "I don't use this, but my users will."

Real-world example: Header-only libraries with dependencies

# HeaderOnlyMath library depends on Eigen, but is itself header-only
add_library(HeaderOnlyMath INTERFACE)
target_link_libraries(HeaderOnlyMath INTERFACE Eigen3::Eigen)

# Users of HeaderOnlyMath automatically get Eigen
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE HeaderOnlyMath)  # Gets Eigen too!

Mixing Scopes: The Real World

Most real projects use mixed scopes:

target_link_libraries(ColumbaEngine
    # Users need these APIs
    PUBLIC
        SDL2::SDL2-static      # Window/input handling in public API
        glm                    # Math types in public headers
        OpenGL::GL            # Graphics API exposed to users

    # Internal implementation details
    PRIVATE
        libglew_static        # OpenGL extension loading (wrapped)
        freetype              # Text rendering (abstracted away)
        ${CMAKE_DL_LIBS}      # Dynamic library loading (platform detail)
)

Step 7: Multiple Executables and Examples

A game engine isn't just a library - it includes tools and examples:

if(NOT BUILD_STATIC_LIB AND BUILD_EXAMPLES)
    # Main editor application
    add_executable(ColumbaEngineEditor src/main.cpp)
    target_sources(ColumbaEngineEditor PRIVATE
        src/application.cpp
        src/Editor/Gui/inspector.cpp
        src/Editor/Gui/projectmanager.cpp
    )
    target_link_libraries(ColumbaEngineEditor PRIVATE ColumbaEngine)

    # Game examples
    add_executable(GameOff examples/GameOff/main.cpp)
    target_sources(GameOff PRIVATE
        examples/GameOff/application.cpp
        examples/GameOff/character.cpp
        examples/GameOff/inventory.cpp
    )
    target_link_libraries(GameOff PRIVATE ColumbaEngine)
endif()

Pattern: Create multiple executables that all link to your main library. This way, the library code is compiled once and reused.

Step 8: Testing Infrastructure

Professional projects need tests:

if(NOT BUILD_STATIC_LIB)
    enable_testing()
    add_subdirectory(${GTEST_DIR})

    add_executable(t1 test/maintest.cc)
    target_sources(t1 PRIVATE
        test/collision2d.cc
        test/ecssystem.cc
        test/interpreter.cc
        test/renderer.cc
    )
    target_link_libraries(t1 PRIVATE gtest gtest_main ColumbaEngine)

    # Auto-discover tests
    include(GoogleTest)
    gtest_discover_tests(t1)
endif()

gtest_discover_tests() automatically finds all test cases and creates individual CTest entries. Run with ctest or make test.

Common Build Pitfalls

1. Global Variables vs Target Properties

# BAD: Affects everything globally
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DDEBUG")

# GOOD: Only affects specific target
target_compile_definitions(MyTarget PRIVATE DEBUG)

2. Not Using Generator Expressions

# BAD: Debug symbols in release builds
target_compile_options(MyTarget PRIVATE -g)

# GOOD: Only in debug builds
target_compile_options(MyTarget PRIVATE $<$<CONFIG:Debug>:-g>)

3. Wrong Dependency Scopes

# If users of your library need OpenGL headers:
target_link_libraries(MyLib PUBLIC OpenGL::GL)

# If only your implementation uses OpenGL:
target_link_libraries(MyLib PRIVATE OpenGL::GL)

What We've Achieved: Build System Results

After implementing all these concepts, here's what we achieved:

Developer Experience:

# Simple build
git clone https://github.com/user/ColumbaEngine
cd ColumbaEngine
mkdir build && cd build
cmake ..
make -j8

# Custom configuration
cmake -DBUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release ..

# Run tests
ctest

Cross-platform Support:

Same CMakeLists.txt works on Windows, Linux, and web
Automatic dependency resolution per platform
Platform-specific optimizations where needed

Build Performance:

Precompiled headers cut build times by 60%
Parallel compilation across all targets
Incremental builds under 10 seconds for single-file changes

Coming Up in Part 2

In the next article, we'll cover the deployment and distribution side of CMake:

Installation Systems: How to make your library usable by others with find_package()
Export/Import Mechanisms: The complex but powerful system that makes modern CMake libraries work
Package Configuration: Creating relocatable, dependency-aware packages
CPack Integration: Generating professional installers for multiple platforms
Real-world Distribution: Getting your library into the hands of users

Conclusion

Building a robust CMake build system for complex projects requires understanding several key concepts:

Target-centric thinking - Everything revolves around targets and their usage requirements
Proper dependency management - Choose the right strategy for your project's needs
Cross-platform abstractions - Let CMake handle platform differences
Generator expressions - Enable conditional behavior without complex if/else logic
Build optimization - Use precompiled headers and other modern features

The game engine we've built demonstrates these concepts in action with a real, production-ready build system that handles complex, multi-platform C++ projects.

Remember: CMake is about expressing intent, not implementation details. Focus on what you want to achieve, and let CMake figure out how to do it on each platform.

Don't miss [Part 2] where we'll cover installation, packaging, and distribution - making your library actually usable by the world!

What's your biggest CMake build challenge? Share your experiences in the comments below!

The complete source code for ColumbaEngine with all the CMake patterns from this series is available on GitHub. These patterns scale from small libraries to large, complex applications.