Skip to content

19 · Luau Bridge (v2)

What it is

The bridge is the layer that lets Luau scripts declare and run game code on the ECS: components (as Luau types), systems (as Luau classes), plugins, events, resources, input actions and entities; capsules (actors and levels) are files, which scripts spawn through engine calls. It sits between Charles's rtype-luau runtime and the ECS's type-erased API, in the engine's ScriptPlugin / LuauPlugin.

This doc is the contract the ECS offers; the binding code itself belongs to the scripting side (Charles).

Why we need it

  • R2: games are written in Luau first. Everything a C++ plugin can register, a Luau plugin must be able to register too.
  • R3: script components must replicate exactly like C++ ones, so they need a real layout, not arbitrary Luau tables.

How others do it

Engine Scripting model
Bevy No official scripting; community crates (bevy_mod_scripting) expose reflected components to Lua/Rhai
flecs flecs script (its own language) declares components, entities, prefabs; bindings for many languages
Unity C# MonoBehaviour (object model), or DOTS ISystem in C#
Unreal Blueprint: classes and structs created in the editor, reflected like C++ ones
Roblox Luau scripts on an object tree (not an ECS)

Our choice

  • Components = Luau types, read from the source with the Luau parser, so they get a fixed binary layout.
  • Systems = Luau classes with declared access.
  • Plugins = Luau modules with a build(app) method.
  • Everything goes through the ECS's type-erased, non-throwing API; errors come back to Luau through rtype::luau::Result / Error.

How it works

Components from types

-- Shield.luau
export type Shield = {
    strength: f32,
    regen: f32,
    owner: Entity,
}

return ecs.component("game.Shield", {
    replication = "everyChange",          -- or "spawnOnly"; omitted = never sent
    defaults = { strength = 50, regen = 2 },
})
flowchart LR
    file["Shield.luau"] --> parse["Luau.Ast parser<br/>export type Shield"]
    aliases["generated .d.luau<br/>f32, i32, Entity, vec2, AssetId"] -.-> parse
    parse --> desc["ComponentDescriptor<br/>name, fields, presence,<br/>replication, defaults"]
    file --> run["Run the chunk<br/>options + defaults"]
    run --> desc
    desc --> reg["world.getComponents().registerType()"]
    reg --> layout["Deterministic layout + layoutHash"]
  • Luau erases types at runtime and has a single number type, so the bridge parses the file with Luau.Ast (the parser the compiler already uses, not the full type checker) and maps annotations to FieldTypes.
  • The aliases f32, i32, u8, Entity, vec2, AssetId... are declared in the .d.luau file produced by Charles's Runtime::generateTypes() (type f32 = number), so editors accept them.
  • Automatic type linking: when the file exports exactly one type, or one type whose name matches the last part of the component name (Shield for game.Shield), the bridge links them without a type = "Shield" option.
  • Fallback if annotation parsing is not possible: typed defaults (strength = ecs.f32(50)).

Generated declarations for script components

generateTypes() is extended to emit declarations for script-defined components, resources, events and capsules, after loading the plugins:

-- generated: game.d.luau
declare class ShieldComponent
    strength: number
    regen: number
    owner: Entity
end

type ComponentName = "rtype.Transform" | "rtype.SpriteRenderer" | "game.Shield" | "game.Health"
type CapsulePath = "actors/bydo.actor" | "scenes/level1.scene"

Editors then autocomplete component fields, and the type checker flags a typo like "game.Sheild" in a query or a capsule path before the game runs.

Systems

local ShieldRegen = ecs.system("game.ShieldRegen", {
    phase = "FixedUpdate",             -- default
    side = "server",                   -- default; see the side rule
    query = { write = { "game.Shield" }, without = { "rtype.Dead" } },
    after = { "rtype.movement" },
})

function ShieldRegen:run(ctx)
    for entity, shield in ctx.query do
        shield.strength = math.min(shield.strength + shield.regen * ctx.time.fixedDelta, 100)
    end
end

return ShieldRegen

The bridge turns the declaration into a QueryList of dynamic queries and adds a system made from a ScriptCallable: a lambda capturing a handle to run, whose DynamicQueries parameter declares the access to the scheduler. shield is a view over the component bytes, valid only during run; writing a field stamps the changed tick.

Engine calls

What a plugin does through a C++ API rather than through plain data (load an atlas, bind an input action, play a sound) is an engine call: a named C++ function registered with App::addCall(). Scripts make it by name, with a table of argument fields converted as component fields are (an assetId takes a path):

local total = engine.call("game.addPoints", { points = 3 })   -- while the script loads

engine.ecs.system("game.Scorer", {
    query = { read = { "game.Ship" } },
    calls = { "game.addPoints" },                              -- declared, like resources and events
    run = function(ctx)
        for entity, ship in ctx.query do
            ctx.call("game.addPoints", { points = 1 })
        end
    end,
})

Missing argument fields keep their defaults. A result of one field is returned as that value, a result of several as a table, and a call that returns nothing returns no value. A std::string field of a call takes and gives a Luau string of any length, and a std::vector field a Luau array; an ecs::String field is cut at 255 bytes. The arguments and the result live in CallBuffers for the time of the call, so their memory is freed after it. A system's declared calls add their access to its own, so the scheduler sees what they read and write, and runs it on the main thread when one of them needs it. Calling a call the system did not declare raises a Luau error. An unknown call, a wrong argument or a call that throws raises an error naming the call. An unknown call in calls is refused when the script loads, unless the system does not run in that App's mode: a client system may list a call only the client plugins register.

The engine's plugins register these calls, on the side they are added on (the backend plugin and the plugins it adds run on clients):

Plugin Calls
Sprite rtype.sprite.loadAtlas, rtype.sprite.createAtlas, rtype.sprite.addFrame, rtype.sprite.addAnimation (Sprites)
Backend rtype.backend.loadTexture
Text rtype.text.loadFont (Text)
Tilemap rtype.tilemap.load, rtype.tilemap.spawn (Tilemaps)
Particle rtype.particle.beginEffect, rtype.particle.addBurst, rtype.particle.addColorKey, rtype.particle.addCurveKey, rtype.particle.addEffect (clients) (Particles)
Http rtype.http.request, rtype.http.cancel (HTTP)
Json rtype.json.encode, rtype.json.decode (JSON)
Audio rtype.audio.loadSound, rtype.audio.playSound (Audio)
Input rtype.input.addAction, rtype.input.bind, rtype.input.bindAxis, rtype.input.bindVector, rtype.input.read (Input)
Physics rtype.physics.raycast, rtype.physics.shapeCast, rtype.physics.overlap, rtype.physics.moveAndSlide, rtype.physics.applyForce, rtype.physics.applyImpulse, rtype.physics.applyTorque, rtype.physics.setGravity (Physics)
Capsule rtype.capsule.spawn, rtype.capsule.load, rtype.capsule.reload (Capsules)
Replication rtype.replication.addInput, rtype.replication.readInput, rtype.replication.localClient (clients) (Replication)

Setup forms

The setup every game writes (its assets and its input actions) has declarative forms under engine.assets and engine.input, which make those calls from one table. Each plugin brings its own forms, in Luau (Plugins.md):

local ship = engine.assets.atlas({
    name = "game.ship", texture = "assets/ship.png", linear = false,
    grid = { frameSize = { x = 48, y = 48 }, count = 5, spacing = { x = 17, y = 0 } },
    animations = { fly = { frames = { 0, 1, 2, 3, 4 }, frameDuration = 0.08, direction = "pingPong" } },
})
local laser = engine.assets.atlas({
    texture = "assets/laser.png",
    frames = { { name = "shot", position = { x = 108, y = 151 }, size = { x = 80, y = 16 } } },
})
local explosion = engine.assets.atlas({
    path = "assets/explosion.json", animations = { boom = { first = 0, plays = 1 } },
})
local planet = engine.assets.texture("assets/planet.png", { linear = true, wrap = true })
local shot = engine.assets.sound("assets/shot.ogg", { stream = false })
local font = engine.assets.font("assets/fonts/main.json")
local level = engine.assets.tilemap("assets/level.tmj")

engine.input.action("move", "vector2", {
    bind = { { up = "W", down = "S", left = "A", right = "D" }, { x = "GamepadLeftX", y = "GamepadLeftY" } },
})
engine.input.action("steer", "axis", {
    bind = { { negative = "Left", positive = "Right" }, { control = "GamepadLeftX", scale = 1 } },
})
engine.input.action("fire", "button", { bind = { "Space", "GamepadSouth" } })
Form Calls Returns
engine.assets.texture(path, {linear, wrap}) rtype.backend.loadTexture the texture's AssetId
engine.assets.sound(path, {stream}) rtype.audio.loadSound the sound's AssetId
engine.assets.shader(path) rtype.shader.load the shader's AssetId
engine.assets.material({name, shader, values, textures}) rtype.shader.addMaterial, then rtype.shader.setMaterialValue and rtype.shader.setMaterialTexture the material's AssetId
engine.assets.font(path) rtype.text.loadFont the font's AssetId
engine.assets.tilemap(path) rtype.tilemap.load the map's AssetId
engine.assets.atlas{path \| texture, name, linear, grid, frames, animations} rtype.sprite.loadAtlas (a path) or rtype.sprite.createAtlas (a texture, named after it unless name is given), then rtype.sprite.addFrame per frame and rtype.sprite.addAnimation per animation, by name the atlas's AssetId
engine.assets.particle({name, ...}) rtype.particle.beginEffect (every key but the lists), then rtype.particle.addBurst per burst, rtype.particle.addColorKey per colorOverLife key and rtype.particle.addCurveKey per sizeOverLife and speedOverLife key, then rtype.particle.addEffect the effect's AssetId
engine.http.request(ctx, {url, method, headers, body, timeout}) rtype.http.request (with ctx.call, or engine.call when ctx is nil), headers written as Name: value lines sorted by name the request's id
engine.json.encode(value), decode(text), tryDecode(text), map(entries) rtype.json.encode / rtype.json.decode (with engine.call; no ctx needed, the calls take no system resource), a value or a parsed text flattened into a node stream (JSON) the text, the value, the value or nil and a message, entries (the { key, value } list) marked as an ordered object
engine.input.action(name, type, {bind}) rtype.input.addAction (type: "button" by default, "axis" or "vector2"), then one bind call per binding, in order nothing
engine.capsule.spawn(ctx, path, overrides), engine.capsule.load(ctx, path, overrides) (in a system) rtype.capsule.spawn / load through ctx.call, then ctx.commands:patch of the root per override the root Entity
engine.capsule.reload(ctx, root) (in a system) rtype.capsule.reload through ctx.call true if root was a capsule's root
  • An atlas's grid takes frameSize and count (both needed), spacing, columns and offset; a frame takes a position and a size, and an optional name (its index otherwise) and origin (its centre otherwise). grid, frames and name make an atlas from a texture, not from a path.
  • An animation's frames lists frame indices (from 0, as rtype.sprite.addFrame returns them) that follow each other, {0, 1, 2}, since an animation is a range of frames; first and count say the same (count 0 or absent: up to the last frame). It also takes frameDuration, direction and plays (0: forever).
  • A binding is a control name (rtype.input.bind), {control, scale} (rtype.input.bind with a scale), {negative, positive} (rtype.input.bindAxis), {up, down, left, right} or {x, y} (rtype.input.bindVector).

A form checks its whole table on every side: an unknown key, a value of the wrong type or a binding of no known shape is a Luau error naming the form and the part of it (engine.assets.atlas: frame 2: 'size': missing 'y'). Then, when the App does not have its calls (the plugin is not in this process: on a dedicated server, the backend plugin and the plugins it adds are not), it skips them and returns the id the asset would have, the hash of its path or name, so the same script loads on the server and the clients. What only a plugin knows, such as a control name or an animation direction, is checked where the plugin runs, and a call's error is prefixed with the form's name.

Plugins

local RtypePlugin = ecs.plugin("rtype.Game")

function RtypePlugin:build(app)
    app:load("components/Shield.luau")       -- by path: no require() across files
    app:load("systems/ShieldRegen.luau")
    app:addPlugin("scripts/rtype/weapons/plugin.luau")
    app:state("game.Phase", { "Menu", "Lobby", "Playing", "GameOver" })
    app:event("game.BossDefeated", { type = "BossDefeated" })
    app:resource("game.Score", { type = "Score", replication = "everyChange" })
end

return RtypePlugin

This section is the original proposal. Today files require each other (by string path, docs/scripting/plan.md D10, docs/luau/modules.md) and the app:load form above does not exist; only the entry points named in project.luau (scripts.main/server/client) run by themselves, and each file has its own sandboxed globals (epic #489).

Input actions from Luau

Gameplay reads PlayerInput, which is filled from Ethan's named InputActions. A script declares those actions and their default bindings with engine.input.action (see Setup forms):

engine.input.action("move", "vector2", { bind = { { up = "W", down = "S", left = "A", right = "D" } } })
engine.input.action("fire", "button", { bind = { "Space", "GamepadSouth" } })

The form forwards them to Input::addAction() / InputAction::bind...() on clients, and, where the replication plugin is added, declares them in the network InputLayout on both sides (rtype.replication.addInput), which the manifest checks. On a client run by the Engine, a system (rtype.engine.networkInput) copies each of them from Input into the PlayerInput sent to the server; a server script reads it by name with rtype.replication.readInput:

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

Rules of the boundary

Rule Why
Scripts hold Entity values, resolved on every access Pool pointers move (see Pool); matches the proposal's Handles
Nothing throws into Luau The type-erased API returns failures; the bridge raises a Luau error with an ErrorKind
Component views are only valid during run Same reason as handles
Writes to read-only terms are refused Keeps access sets truthful for the scheduler
client systems may not write replicated or server-only components, in their query terms or through ctx.commands (checked when the side is set and when a command is recorded; both systems are not checked) Replication would overwrite anything else
Hot reload re-registers a component only if its layoutHash is unchanged Existing data keeps its meaning

Where scripts run

Luau plugins load on the server and the clients (both need layouts, capsules and input actions). System sides decide what runs where: server (gameplay, default), client (presentation), both (identical simulation such as bullet motion). In standalone mode both sides run in one App.

A system is declared on both sides, whatever its side, and only its engine calls may be missing on the side it does not run on: its components, resources and events must exist there, and the systems it is ordered against too. A script that names what only one side has (the sprites, the audio, net.applyInputs) lives in files only that side's entry requires (server/main, client/main), as examples/games/rtype_duel/game/scripts/ does; a test of engine.isClient is the way to share one file:

engine.ecs.component("game.Explosion", { fields = {}, presence = "clientOnly" }) -- on both sides
if not engine.isClient then
    return
end
engine.ecs.system("game.RemoveExplosions", { side = "client", ... })

Connections

Pitfalls

  • Per-entity overhead. Each run crosses the C++/Luau boundary; iterating thousands of entities in Luau every tick (bullets) can be too slow. That is where a C++ game plugin takes over (collisions, bullet motion).
  • Table-per-entity temptation. Storing arbitrary Luau tables on entities would bypass queries, replication and the data/logic split; not supported.
  • Layout drift. Server and client running different script versions are caught by layoutHash at connection.

Open questions

  • Can the luau xmake package expose Luau.Ast? If not, use the typed-defaults fallback. (Charles)
  • Exact list of aliases emitted by generateTypes(). (Charles + ECS)
  • Hot reload in development: migrate component data by field name when the layout changes? (ECS)