Getting started
Run a game
The engine builds one generic program, aylo-runtime, and copies it to the repository root. It runs a game folder:
game/ in the current directory, or the folder you give as first argument. It runs the client by default and the server
(no window, no graphics) with --server. At the repository root, the scripts r-type_server and r-type_client
(.bat files on Windows) start it for you on the matching side, so ./r-type_server is ./aylo-runtime --server.
xmake build -y
./aylo-runtime --server examples/games/rtype_duel/game
./aylo-runtime examples/games/rtype_duel/game # one per player
The folder must contain a project.luau. A client also needs the assets/ folder and refuses to start without it; a
server can run with project.luau and scripts/ alone. A relative path is resolved against the working
directory when the program starts.
The command line is yours
aylo-runtime --version prints the version of the engine, the commit it was built from and the library version, and
stops: quote it in a bug report. The runtime keeps --server (it selects the server side), --ticks (see below) and --version, and the
engine keeps the game folder, which must come first. Every other --name value (or --name=value, or a bare
--name) is given to project.luau as engine.args, so your game decides its own options, and --server and --ticks are not among them:
engine.settings.network.port = engine.args.port or 4242
if engine.isClient then
engine.settings.network.host = engine.args.host or "127.0.0.1"
end
./aylo-runtime --server my_game/game --port 4243
./aylo-runtime my_game/game --host 10.0.0.2 --port 4243
Values are typed: true and false are booleans, a decimal number is a number, anything else is a string. A flag given
twice keeps its last value. Any other argument is an error.
What runs where
In project.luau, three flags tell you where the file is running: engine.isClient, engine.isServer and
engine.isDebug. They are also available to your scripts.
A process runs the scripts of its own side only: the server runs the server entry, a client the client entry, and
both run the shared main entry first (see Your scripts). So a server file never needs a test of
engine.isServer: the client does not load it.
Your first game
Create hello/game/project.luau:
engine.settings.network.port = engine.args.port or 4242
if engine.isClient then
engine.settings.platform = "glfw"
engine.settings.renderer = "vulkan"
engine.settings.window.title = "Hello"
end
and hello/game/scripts/main.luau:
engine.ecs.component("game.Counter", { fields = { value = "u32" } })
engine.ecs.system("game.Count", {
phase = "FixedUpdate",
query = { write = { "game.Counter" } },
run = function(ctx)
for entity, counter in ctx.query do
counter.value += 1
end
end,
})
Run ./aylo-runtime --server hello/game. Read on to learn what every part of it means.
Your scripts
Nothing under scripts/ runs by itself. The game starts from entry points, files you name in project.luau,
and everything else runs because an entry (or a file an entry requires) calls require on it. A file nobody requires
is never run.
my_game/game/
project.luau
scripts/
shared/main.luau components and input actions both sides declare
server/main.luau the server's gameplay
client/main.luau what the client shows and plays
-- project.luau
engine.settings.scripts.main = "shared/main"
engine.settings.scripts.server = "server/main"
engine.settings.scripts.client = "client/main"
A process requires main, then server if it is a server, then client if it is a client. A standalone process is
both, so it runs all three, and a module that two of them require runs once. A game with a single side, or a first
game like the one above, sets nothing: the entry is scripts/main.luau. See
Project settings for the rules and Modules and require for how files
share data.
When your game is ready, Shipping your game explains what to give your players.
Stopping the game and running a test
To know that the player closed the window, read the event rtype.Closed in a system (declare it under events = { read = { "rtype.Closed" } }). The engine does not stop the game by itself: send rtype.AppExit in answer, after saving for example.
A script stops the process with the event rtype.AppExit. The game finishes the frame it was sent in, and aylo-runtime
returns code as its exit code (0 is success; send another number to fail):
engine.ecs.system("game.Quit", {
phase = "Update",
query = {},
events = { send = { "rtype.AppExit" } },
run = function(ctx)
ctx.events.send("rtype.AppExit", { code = 1 })
end,
})
If several are sent, the first one read gives the code. --ticks <n> runs at most n frames and then exits with 0,
unless an rtype.AppExit came first: with it a test game checks its rules in a system and sends AppExit with a
non-zero code when one fails, so a CI job just checks the exit status:
./aylo-runtime --server --ticks 600 my_game/tests
The limit counts frames, not FixedUpdate steps: a frame runs FixedUpdate zero, one or several times depending on how
long it took, so --ticks 600 does not mean 600 fixed steps. To check something after a given amount of simulated time,
count it in your own system (for example from the time the fixed step gives you) and send AppExit then.
--ticks takes a whole number and may be given only once; a missing, negative, non-numeric or too large value, or a
second --ticks, stops the program with the exit code 84 before the game starts. With hot reload on, a rebuild that
fails during a --ticks run also ends it with 84, instead of waiting for you to fix the files as a normal run does.