Skip to content

Systems

A system is a function that runs on a schedule, on the entities that match a query. You declare one with engine.ecs.system.

engine.ecs.system("game.MoveShips", {
    phase = "FixedUpdate",
    side = "server",
    query = { write = { "game.Ship", "rtype.Transform" }, with = { "net.PlayerInput" } },
    calls = { "rtype.replication.readInput" },
    after = { "net.applyInputs" },
    run = function(ctx)
        for entity, ship, transform in ctx.query do
            local move = ctx.call("rtype.replication.readInput", { entity = entity, action = "move" }).vector
            transform.position = { x = transform.position.x + move.x * 4, y = transform.position.y - move.y * 4 }
        end
    end,
})

The declaration

Option Meaning
phase Required. When it runs, see below.
query Required. Which entities it visits; {} for a system that visits none.
run Required. The function, called with ctx.
side "server" (default), "client" or "both": where it runs.
resources { read = {...}, write = {...} }: the resources it uses.
events { read = {...}, send = {...} }: the events it reads or sends.
calls The engine calls it makes with ctx.call.
after, before Names of systems it must run after or before.

Any other option is an error naming the system. A system must declare everything it touches: using an undeclared resource, event or call is an error.

Phases

A frame runs its phases in this order.

Phase Use
Startup Once, before the first frame: setup, initial entities.
PreUpdate Polling the window and input, receiving network packets.
FixedUpdate Gameplay at a fixed rate; also the physics and the server's network send.
Update Once per frame: animation, camera, UI.
PostUpdate Transform propagation, sending input (client).
Render Extracting and drawing.

Gameplay on the server goes in FixedUpdate; what a client shows goes in Update. Use after and before to order systems of the same phase, including the engine's (the physics names are in Physics).

Queries

query = {
    read = { "rtype.Transform" },
    write = { "game.Ship" },
    optionalRead = {}, optionalWrite = {},
    with = { "net.Owner" }, without = { "game.Dead" },
    added = { "game.Laser" }, changed = { "game.Ship" },
}
Term Meaning
read, write The entity must have the component, and the loop gets a view of it (read-only, or writable).
optionalRead, optionalWrite A view, or nil when the entity does not have it.
with, without The entity must have, or must not have, the component. No view.
added The entity must have it, and it was added since this system last ran.
changed The entity must have it, and it was added or written since this system last ran.

for entity, a, b in ctx.query do gives the entity, then one view per read/write term in the order read, write, optionalRead, optionalWrite (inside each, in the order you listed them). The views are valid only during the call to run. An unknown term name is an error.

ctx

Field What it gives
ctx.query The loop over matching entities.
ctx.side The side the system runs on: "server" (the default), "client" or "both".
ctx.time delta (seconds of the frame), fixedDelta (the fixed step), elapsed, tick and alpha (progress between two fixed steps). ctx.delta and ctx.fixedDelta also exist.
ctx.commands Deferred changes to the world, see below.
ctx.resources The resources the system declared: ctx.resources["rtype.Input"] is a view (read-only unless declared in write).
ctx.events ctx.events.read(name) loops over the events not read yet; ctx.events.send(name, fields) sends one. Both need the name in events.
ctx.call(name, args) Makes an engine call the system listed in calls.

Commands

Changes to the world are recorded and applied after the system, not during the loop (a spawned entity cannot be queried by the loop that spawned it):

local ship = ctx.commands:spawn({
    ["game.Ship"] = { position = position, player = 0 },
    ["rtype.Transform"] = { position = position },
})
ctx.commands:add(ship, "rtype.RigidBody", { type = 1 })
ctx.commands:patch(ship, "game.Ship", { player = 1 })
ctx.commands:setParent(child, parent)
ctx.commands:removeParent(child)
ctx.commands:despawn(ship)

spawn takes a table of component name to fields (fields left out keep their defaults) and returns the entity. It also builds the engine's components, such as rtype.Collider or rtype.TextRenderer. A command that names an unknown component, or that a client system may not write, is an error and records nothing.

add and patch differ in what they keep:

Command The component afterwards
ctx.commands:add(entity, name, fields) Its defaults with fields written over them: the value the entity had is replaced, and the entity gets the component if it did not have it.
ctx.commands:patch(entity, name, fields) The value the entity has when the commands are applied, with only fields written over it. Nothing happens if the entity does not have the component then.

Use patch to change one field of something you did not build yourself, such as the position of a capsule you just spawned:

local bydo = ctx.call("rtype.capsule.spawn", { capsule = "actors/bydo.actor" })
ctx.commands:patch(bydo, "rtype.Transform", { position = { x = 820, y = 140 } })   -- its rotation and scale stay

A patch sees the commands recorded before it in the same system, like that spawn. A field is written whole: a position takes both x and y, and a list is replaced by the one you give. rtype.Parent and rtype.Children cannot be patched; use setParent and removeParent.

Events

An event is a message between systems. Declare the ones you use under events, then:

events = { read = { "rtype.CollisionStarted" }, send = { "rtype.PlayMusic" } },
run = function(ctx)
    for collision in ctx.events.read("rtype.CollisionStarted") do
        print(collision.first, collision.second)
    end
    ctx.events.send("rtype.PlayMusic", { sound = music, crossfade = 1 })
end

Events are local to one machine and are not replicated: to tell the other side something, put it in a replicated component. Declaring your own event types from Luau is not available yet (planned); you use the engine's, such as rtype.CollisionStarted, rtype.PlayMusic, and the network ones in Networking.

Where a system runs

A system lives in the file that declares it, and a file runs only where an entry requires it. Put what only the server needs under the server entry and what only a client needs under the client entry, so a file of the client never runs on the server and needs no test of engine.isClient. The components and input actions both sides must declare alike go in a file that the shared main entry requires, see Getting started.

A system's side still decides where it runs. A client system may not write replicated or server-only components. What exists on only one side (sprites and audio on a client) must be named only by files that side loads. Only engine calls may be missing on the side a system does not run on. See Networking.

Errors

A bad declaration (an unknown option, a missing phase, an undeclared name) is an error naming the system, raised when the script loads, and the script fails to load. A mistake inside run (an undeclared resource, a call that was not listed, a stale view) is a Luau error naming the cause. Read the output of the program.