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 |