Skip to content

AYLO Engine: developer documentation

For people who work on the engine, in C++. To make a game with it, in Luau, read the game developer manual instead.

The architecture in one picture

The engine is a stack of layers. Each layer only knows the layers below it; a game sits on top and is only data and Luau scripts.

flowchart TB
    subgraph game["A game (a folder: project.luau, scripts/, assets/)"]
        luaugame["Luau gameplay: components, systems, packets"]
    end
    subgraph exe["Executables"]
        runtime["aylo-runtime: client, or --server"]
        editor["aylo-editor"]
    end
    subgraph eng["engine (static)"]
        engine["Engine: reads project.luau, loads plugins and backends, hot reload"]
    end
    subgraph mid["Bridges (static)"]
        scripting["scripting: Luau ↔ ECS"]
        replication["replication: ECS ↔ network"]
    end
    subgraph feat["Plugins (one shared library each)"]
        plugins["transform · input · graphics · sprite · text · tilemap · ui · particle · audio · physics · capsule · persistence · http"]
    end
    subgraph back["Backends behind contracts (shared libraries)"]
        render["render-vulkan"]
        platform["platform-glfw"]
        audio["audio-miniaudio"]
    end
    subgraph base["Foundations"]
        ecs["ecs: entities, components, systems, App"]
        luau["luau: the VM wrapper"]
        network["network: UDP transport, reliability"]
        contract["contract-*: one interface per kind of backend"]
        core["core: ids, hashes, settings, paths"]
    end
    game --> exe --> eng --> mid
    eng -. loads .-> feat
    eng -. loads .-> back
    scripting --> ecs
    scripting --> luau
    replication --> ecs
    replication --> network
    feat --> ecs
    feat --> contract
    back --> contract
    ecs --> core
    contract --> core
  • Rendering, networking and game logic never meet directly: rendering is a backend behind a contract, the network knows no ECS, and gameplay is ECS systems written in Luau.
  • Plugins carry the engine's features. A game lists the ones it needs, by name, in project.luau.
  • The server runs the same engine and plugins without any backend: no window, no GPU, no audio.

Where to start

You want to Read
Know the modules and their rules Modules, Plugins, Backends
Understand the ECS ECS design and its feature pages
Understand the network Overview, then design; the wire format is the protocol
See how a game is run Engine design, scripting plan
Know why we chose a library Technical and comparative study
Contribute Contributing, Code style

How to

Task Page
Build, run, test README
Add a plugin, a component, an engine call Plugins, and the skills in .agents/skills/ (add-plugin, add-component, add-engine-call)
Write a game's native plugin Plugins: writing a game's plugin
Debug the GPU GPU debugging
Release the engine Release
Make the engine accessible Accessibility