Capsules
A capsule is an entity your game describes once and spawns as often as it wants: its components, and its child
entities, any of which can be another capsule. An enemy, a bullet, a boss with its turrets and a whole level are all
capsules. Name the file after what it is for: .actor for something that moves, .scene for a level, .capsule for
anything else. The engine treats them the same way.
Add the plugin in project.luau:
engine.settings.plugins = { "rtype.Capsule" }
What a capsule holds
A capsule is a tree of nodes. Each node becomes one entity when the capsule is spawned:
- its components, with their values;
- its children, parented to it, so a turret follows its boss;
- its side: the server by default,
clientfor what only players see (a background, a camera), orboth; - optionally, another capsule it spawns instead of a plain entity: a boss's turret node spawns
actors/turret.actor, and the node's own components replace the turret's (its position on the boss).
A level is a capsule whose root has no rtype.Transform: its children stay where the level put them. A capsule that
should move as one gives its root a rtype.Transform.
Capsule files
Put your capsules anywhere under assets/. The engine reads every .capsule, .scene and .actor file when the game
starts, after your scripts, so a file can use the components they declare. A capsule's name is its path from
assets/, for example actors/boss.actor.
[capsule format=1]
# The boss, with a turret on each side.
[node path="."]
game.Health = { value = 50 }
rtype.Transform = {}
[node path="LeftTurret" instance="actors/turret.actor"]
rtype.Transform = { position = (-40, 0) }
[node path="RightTurret" instance="actors/turret.actor"]
rtype.Transform = { position = (40, 0) }
[node path="Shadow" side=client]
rtype.SpriteRenderer = { texture = "sprites/boss_shadow.png", layer = -1 }
Each [node] is one entity: path="." is the root, instance places another capsule there (write only the fields
you change), and side=client keeps a node on the players' machines. The
Capsule file format page has the whole format: every attribute, how to write each field type,
instances and the error messages.
With hot reload on, saving a file respawns what came from it in place, and a file saved with a mistake keeps its previous version. Reading and writing capsule files says when the engine reads your files, what saving one does to a running game, and what a file looks like once the engine writes it back.
Names
Each entity a capsule spawns gets a rtype.Name: the name of its node (LeftTurret), or for the root, the file's name
without its folder and extension (boss for actors/boss.actor). A node that gives a rtype.Name of its own keeps it.
The editor shows entities by these names; a script can read them like any component.
Spawning, switching levels, reloading
The engine.capsule forms do each of these in one line, from a system's run. Each makes an engine call, so the
system lists that call in its calls:
engine.ecs.system("game.Waves", {
phase = "Update",
query = {},
calls = { "rtype.capsule.spawn", "rtype.capsule.load" },
run = function(ctx)
local bydo = engine.capsule.spawn(ctx, "actors/bydo.actor", {
["rtype.Transform"] = { position = { x = 820, y = 140 } },
})
if bossDefeated then
engine.capsule.load(ctx, "scenes/level2.scene")
end
end,
})
| Form | Needs in calls |
Returns | What it does |
|---|---|---|---|
engine.capsule.spawn(ctx, path, overrides) |
rtype.capsule.spawn |
the root entity | Spawns a copy of the capsule |
engine.capsule.load(ctx, path, overrides) |
rtype.capsule.load |
the root entity | Switches levels: the capsule loaded before is despawned, then this one is spawned |
engine.capsule.reload(ctx, root) |
rtype.capsule.reload |
true if root was a capsule's root, false otherwise |
Spawns the capsule's current version again into the same root |
path is the capsule file's path in assets/. overrides is optional: a table of component name to fields, written
over the capsule root's values. Only the fields you name change: in the example the bydo keeps the rotation, the
scale and every other component its file gives it. A component the root does not have is not added by an override;
add it with ctx.commands:add. To change a child, find it with a query once it is spawned.
- The root is ready to use at once, to keep in a table or pass to other commands.
- The entities appear when the system's commands are applied, at the end of its phase, like
ctx.commands:spawn. - Despawning the root (
ctx.commands:despawn(root)) removes the whole capsule. loadonly removes the capsule loaded before: your player and anything else spawned outside it stay.- A reload despawns the root's children, including ones you attached to it, and keeps the root's other components.
The calls underneath
The forms are thin: engine.capsule.spawn(ctx, path, overrides) is the call followed by one
ctx.commands:patch per override. You can make the calls yourself:
| Call | Arguments | Result |
|---|---|---|
rtype.capsule.spawn |
capsule (a path) |
the root entity |
rtype.capsule.load |
capsule (a path) |
the root entity |
rtype.capsule.reload |
root (an entity) |
true if it was a capsule's root |
local bydo = ctx.call("rtype.capsule.spawn", { capsule = "actors/bydo.actor" })
ctx.commands:patch(bydo, "rtype.Transform", { position = { x = 820, y = 140 } })
Sides
Each node is spawned on its side only, so one capsule loads on the server and on every client without duplicates: the server's entities reach the players by replication, and the client nodes stay local. Components marked server-only are left out on clients, and client-only ones on a dedicated server.
Errors
A call on a path no capsule has, or a capsule that contains itself through its instances, is a Luau error naming the call. Nothing is spawned then. The forms start their errors with their name:
| Message | Cause |
|---|---|
engine.capsule.spawn: expected the system's ctx first |
The first argument is not the ctx of run |
engine.capsule.spawn: expected the capsule's path second ("actors/bydo.actor") |
The path is missing, empty or not a string |
engine.capsule.spawn: overrides: 'rtype.Transform' must be a table of fields |
An override is not a table |
engine.capsule.spawn: overrides: ... followed by the field's error |
An override names a field the component does not have, or a value that does not fit; the capsule is spawned without it |
engine.capsule.spawn: ... followed by the call's error |
An unknown capsule, or the call missing from the system's calls |
engine.capsule.load and engine.capsule.reload give the same messages with their own name.