Project settings
project.luau is plain Luau, run before anything else, on the server and on every client. It sets values of
engine.settings; the engine reads them to decide what to build. Settings are nested tables
(engine.settings.window.title), and each part of the engine reads its own section.
An unknown key is an error, not ignored, so a typo fails at start with the key's name. A wrong value type is an error too.
Flags and arguments
| Name | Meaning |
|---|---|
engine.isClient, engine.isServer |
Where this file runs |
engine.isDebug |
A debug build; always true in the editor |
engine.args |
The command line flags, typed (see Getting started); engine.args.editor is true in the editor |
Hot reload
| Key | Default | Meaning |
|---|---|---|
hotReload |
true in a debug build, false otherwise |
Watch the game's files while it runs, see Hot reload |
Network
| Key | Side | Default | Check |
|---|---|---|---|
network.port |
both | 4242 |
a whole number from 1 to 65535; 0 also on a server (the system picks a free port) |
network.host |
client | "127.0.0.1" |
must resolve to an address |
Scripts
| Key | Default | Check |
|---|---|---|
scripts.main |
"main" when none of the three is set |
the entry every process runs first |
scripts.server |
none | the entry of the server side |
scripts.client |
none | the entry of the client side |
scripts.aliases.<name> |
none | the folder inside scripts/ that @<name> points to, a string |
An entry is a path inside scripts/, with no extension and no prefix: "shared/main" is
scripts/shared/main.luau (or scripts/shared/main/init.luau). A process requires main, then server if it runs
the server side, then client if it runs the client side. A standalone process runs both sides, so all three; a shared
module that several entries require runs once. An entry may return nothing.
engine.settings.scripts.main = "shared/main"
engine.settings.scripts.server = "server/main"
engine.settings.scripts.client = "client/main"
- If you set none of the three,
mainis"main"(scripts/main.luau), which suits a game in one file. When that default file does not exist, the game starts with a warning on the error output and runs no script. - A key you set whose file does not exist stops the start, with a message naming it
(
Setting 'scripts.server' = 'server/main': ...). A server does not look for thecliententry, and a client does not look for theserverone, so a game can ship without the other side's folder. - A file that no entry requires, directly or not, never runs, and saving it changes nothing while the game runs.
- The same entries work in every mode: you need no
if engine.isServerinproject.luauto choose them.
An alias is a short name for a folder of your scripts, usable in require:
engine.settings.scripts.aliases = { shared = "shared" }
-- scripts/server/main.luau
local config = require("@shared/config") -- scripts/shared/config.luau
The rules:
- A name is made of
a-z,0-9,_,.and-, and ignores case:Sharedandsharedare the same alias, so declaring both is an error. scriptsandselfare reserved:@scriptsis always thescripts/folder,@selfthe folder of the requiring file.- The target is a path relative to
scripts/and stays inside it: no absolute path, no..past the root, no link pointing out. - An invalid alias stops the start with a message naming
scripts.aliases.<name>and the reason. Any other key underscriptsthanmain,server,clientandaliasesis an unknown key and an error.
The editor does not read project.luau, so mirror each alias in the .luaurc next to it (the targets there are
relative to the game folder) or luau-lsp will flag the paths. See Modules and require.
Plugins
Plugins add engine features. A game lists the ones it wants by name, and the engine loads each from its library:
engine.settings.plugins = { "rtype.Physics" }
if engine.isClient then
engine.settings.plugins = { "rtype.Physics", "rtype.Input", "rtype.graphics", "rtype.Sprite", "rtype.SpriteDraw" }
end
| Name | What it adds | Side |
|---|---|---|
rtype.Input |
Input actions and the keyboard, mouse and gamepad | client |
rtype.graphics |
The window and the renderer, cameras and textures | client |
rtype.Shader |
Shaders and materials | client |
rtype.Sprite |
Sprites, atlases and animations | both |
rtype.SpriteDraw |
Draws the sprites | client |
rtype.Shape |
Draws filled and outlined shapes | client |
rtype.Tilemap |
Tiled maps and parallax backgrounds | client |
rtype.Text |
Text from font atlases | client |
rtype.Ui, see User interface |
Menus and HUDs: layout, buttons, sliders, text fields | client |
rtype.Editor, see Editor |
Your scenes edited in a window of panels, and the game played there. Do not list it: aylo-editor adds it |
both, in one process |
rtype.Particle, see Particles |
Particle emitters and effects | client |
rtype.audio |
Sounds, music and the listener | client |
rtype.Physics, see Physics |
2D physics | both |
rtype.PhysicsDebug |
Draws the colliders and velocities | client |
rtype.Capsule, see Capsules |
Actors and levels from capsule files | both |
rtype.Http, see HTTP |
HTTPS requests to the hosts the game names | server |
The time, the schedule and the transform are always there. A plugin that needs another brings it: listing
rtype.graphics also loads rtype.Input, with a line on the error output, so list what you use and you may leave out
what it requires. A plugin of the game's own (demo.Greeter) is named the same way, see
Native plugins. A name no library provides stops the start, and the message lists the names that
exist; the names are case-sensitive.
A plugin reads its section when it is built, so a section is only checked if its plugin is listed; an unknown key in it is then an error.
http
Every key is optional and the values are checked when rtype.Http is listed. The keys are in HTTP:
allowedHosts, allowHttp, maxConcurrent, maxQueued, timeout, maxResponseBytes and secrets.
physics
Every key is optional and the values are checked when rtype.Physics is listed.
| Key | Meaning |
|---|---|
gravity |
{ x, y }, world units per second squared, Y down |
unitsPerMeter |
world units per meter |
maxBodies, maxBodyPairs, maxContactConstraints, tempAllocatorBytes |
positive integers: the simulation's limits |
physicsDebug
| Key | Meaning |
|---|---|
enabled |
outlines shown at start (F3 toggles them in game) |
drawAll |
outline every collider, not only the entities that ask |
outlineThickness, velocityScale |
how the outlines and velocity arrows look |
editor
Read when the game runs in the editor (aylo-editor), ignored otherwise.
| Key | Meaning |
|---|---|
scene |
The capsule file, in the assets, the editor opens at start: "scenes/level.scene", or an actor, which opens alone |
textEditor |
The command that opens a file from the editor (Visual Studio Code by default): "subl", "code" |
Window, renderer and audio (client)
if engine.isClient then
engine.settings.platform = "glfw"
engine.settings.renderer = "vulkan"
engine.settings.window.title = "My game"
engine.settings.window.size = { 800, 600 }
engine.settings.audio.backend = "miniaudio"
engine.settings.audio.volume.music = 0.7
engine.settings.vulkan.virtualResolution = { 800, 600 }
end
| Key | Meaning |
|---|---|
platform, renderer |
the backends by name; required on a client. Platforms: "glfw", "sdl" (SDL3) or "raylib". Renderers: "vulkan" or "raylib". "raylib" goes with "raylib" only: its window and its drawing come together. "sdl" and "glfw" both work with "vulkan" |
window.size, window.title, window.resizable, window.fullscreen |
the window |
window.system |
Linux only: "auto" (default: Wayland in a Wayland session, X11 otherwise or if Wayland fails), "x11" or "wayland" |
audio.backend |
"miniaudio" or "null" (silent) |
audio.required |
if the device cannot open: false falls back to "null", true is an error |
audio.maxVoices |
sounds playing at once; the oldest effect is stolen beyond that |
audio.volume.master, .music, .effects |
starting volumes |
audio.panDistance |
world units from the listener at which a sound is fully left or right |
vulkan.virtualResolution |
{ width, height }: the resolution your game is designed for, scaled to the window |
raylib.virtualResolution |
the same as vulkan.virtualResolution, for the renderer "raylib" |
vulkan.presentMode |
"fifo" (default), "mailbox" or "immediate" |
vulkan.debugging, vulkan.layers |
validation, for debugging a GPU problem; layers takes { "VK_LAYER_KHRONOS_validation" } |
The vulkan section also accepts engineName, extraExtensions, minSeverity, preferredDeviceType,
synchronizationValidation and bestPractices; the miniaudio section accepts sampleRate, channels and
periodSizeInMilliseconds. Leave them unset unless you know you need them.
On Linux the window opens natively on Wayland when your desktop runs it, so a screen scaled to 150% or 200% is drawn sharp and at the right size. If a machine has trouble with Wayland (an old graphics driver), let players choose the window system with a flag of their own:
if engine.isClient then
engine.settings.window.system = engine.args.windowSystem or "auto"
end
./aylo-runtime my_game/game --windowSystem x11
A common pattern is to turn on validation only in debug builds:
if engine.isDebug then
engine.settings.vulkan.layers = { "VK_LAYER_KHRONOS_validation" }
engine.settings.vulkan.debugging = true
end