18 · Capsules¶
What it is¶
A capsule is an entity described once and spawned by copy: 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: there is one behaviour, not one for templates and another for levels. Other engines split it in two (prefabs and scenes); Godot does not, and neither do we.
A capsule's file says what the developer means by its extension: .actor for a thing that moves, .scene for a level,
.capsule for anything else. The content and the behaviour are the same; the extension is only there to organize a
game's files.
Why we need it¶
- Convenience (R2): spawning
actors/bydo.actorinstead of adding five components by hand in every system that creates an enemy. - R4, data-driven content: designers describe enemies and levels in files, which an editor can read and write, without touching systems; a saved file is reloaded while the game runs.
- R3 (network): every spawned root carries a
CapsuleInstance(capsule id, version), so the server can later tell a client "spawn this capsule here" in a few bytes (see Replication).
How others do it¶
| Engine | Templates and levels |
|---|---|
| Godot | One thing: a scene is a tree of nodes, a node can instance another scene; .tscn text files |
| Unity | Prefabs (editor assets) and scenes, two concepts; DOTS bakes them to entities |
| Bevy | Bundles in code, DynamicScene files for sets of entities |
| flecs | Prefabs are entities, instances inherit their components (IsA) |
Our choice¶
- A plugin, not an ECS feature: capsules only use the ECS's public API (spawn, add a component by id and bytes,
Commands,setParent), so they live inplugin-capsule(rtype.Capsule), asbevy_scenelives outsidebevy_ecs. - One behaviour, two steps. A file is read once into a capsule: each node's components as bytes ready to copy. A spawn then only allocates entities and copies bytes, so spawning a bullet hundreds of times never parses text.
- A flat list of nodes, the file's structure one to one: name, parent, side, the capsule it instances if any, and
its components. The hierarchy is made at spawn, with
ParentandChildren. - Instances by copy, no inheritance: changing a capsule changes what is spawned after, and what was spawned before when it is reloaded.
How it works¶
Adding the plugin¶
A game names it in its project.luau, and the Engine loads it from its library (see
Plugins):
engine.settings.plugins = { "rtype.Capsule" }
A program on a bare App (tests, examples) adds rtype::plugins::capsule::CapsulePlugin{}. It inserts the Capsules
resource ("rtype.Capsules"), the LoadedCapsule resource ("rtype.LoadedCapsule"), registers the CapsuleInstance
component and the engine calls. It requires no plugin and reads no settings.
A capsule¶
A capsule is named by its path ("actors/bydo.actor"); its id is the AssetId of that path, the same in every process.
Its nodes form a flat list, a parent before its children, node 0 the root:
| Node field | Meaning |
|---|---|
| name | Its name among its parent's children (not empty, no /, unique there); a node's path is "Boss/LeftTurret" |
| parent | Its parent node |
| side | Where it is spawned: the server by default, the client, or both (ecs::runsIn(), as for systems). The root is spawned everywhere |
| instance | Another capsule it spawns instead of a plain entity: that capsule's root takes this node's components over its own, and gets this node's children too |
| components | ComponentValues: one live value per component (copied and destroyed with its type's hooks), each with the component's presence |
A Capsule is built node by node, then given to the Capsules resource with define(). Games describe capsules in
files, which the plugin reads the same way; building one in C++ is for tests and tools:
namespace capsule = rtype::plugins::capsule;
capsule::Capsule boss{"actors/boss.actor"}; // a root only; the path is normalized, the id derived
boss.editNode(0).values.set(components, Health{.value = 50});
const std::uint32_t left = boss.addNode("LeftTurret", 0);
boss.editNode(left).instance = capsule::CapsuleRef{.id = capsule::CapsuleId::fromPath("actors/turret.actor"),
.path = "actors/turret.actor"};
boss.editNode(left).values.set(components, Transform{.position = {-40.F, 0.F}});
capsules.define(std::move(boss));
An instance is looked up when the capsule is spawned, so a capsule can instance one defined, or redefined, later. A game describes its capsules in files instead (below).
| Rule | Behaviour |
|---|---|
| Names | One capsule per path; two paths with the same id are refused (CapsuleException) |
| Values | Any component (all are copyable); setting one again replaces it. Parent and Children are refused: the nodes set the hierarchy |
| Hot reload | Capsules::define() of a capsule with the same id replaces its nodes and bumps its version, keeping its id and address, so what instances it stays valid |
Capsule files¶
A game keeps its capsules under <game>/assets, as .capsule, .scene or .actor files: the same format, the
extension is for the developer. The format is specified in full (tokens, grammar, every value type, errors, how it is
written) in CapsuleFormat.md; why it is our own and not TOML is in
benchmarks/capsule-format.md. A file is a flat list of node sections, the root
first and a parent before its children, each with its components written by field name (from the
reflection):
[capsule format=1]
[node path="."]
game.Health = { value = 50 }
[node path="LeftTurret" instance="actors/turret.actor"]
rtype.Transform = { position = (-40, 0) }
[node path="Background" side=client]
rtype.SpriteRenderer = { texture = "sprites/bg.png", layer = -10 }
format::readCapsule() reads a file into a capsule (an error names the file, line and column) and
format::writeCapsule() writes one back so that it reads the same: an editor can save what it reads. Every rule of
the format, and how the writer writes, is in CapsuleFormat.md.
Loading. The CapsulePlugin reads every capsule file from its finish(), once every plugin, scripts included, is
built, so a file can name the components scripts declare. A file instancing another reads it first. A broken file stops
the start, naming the file, line and column.
Hot reload. With the engine's hot reload (hotReload, the HotReload resource), the plugin adds a
CapsuleReloadable to the engine's HotReloader, following the capsule files of the assets. Between two frames, a
saved or added file is read again (CapsuleFiles::reload()) with the files that instance it, and the capsules read go
to the ReloadedCapsules resource; the next frame, the Render system rtype.Capsule.HotReload (every side) reloads
what was spawned from them, nested roots through their outermost capsule. A file saved broken keeps its old version and
the reload is reported as failed with the file, line and column; a removed file is ignored.
Spawning¶
// in a system: reserved at once, alive when the system's commands are applied
void spawnWave(rtype::ecs::Commands& commands, rtype::ecs::Res<rtype::plugins::capsule::Capsules> capsules) {
rtype::plugins::capsule::spawnCapsule(commands, *capsules, bydoId)
.add(Transform{.position = {820.F, 140.F}}); // replaces the capsule's Transform for this entity
}
Spawning, loading and reloading are all recorded in a Commands buffer: in a system, its own; outside systems (tests,
tools), a Commands{world} flushed by hand.
flowchart LR
file["actors/boss.actor"] -->|read once| capsule["Capsule<br/>nodes with component bytes"]
capsule -->|copy per spawn| world["World<br/>one entity per node, parented"]
One walk over the nodes: a node of the other side is skipped with its subtree; a
node is a new entity, or the root its instance spawns; its kept values are added (presence: a client leaves out
kServerOnly components, a dedicated server kClientOnly ones); it is parented to its parent's entity. The root gets a
CapsuleInstance { capsule, version, nested }. A check pass runs first (every instanced capsule exists, none contains
itself), so a spawn creates everything or nothing.
A level is a capsule whose root has no Transform: the TransformPlugin treats its children as roots, so they stay in
world space. A capsule that moves as one gives its root a Transform. Despawning a root despawns the capsule: its
descendants go with it.
Loading: switching levels¶
loadCapsule() (and the rtype.capsule.load call) switches the level: it despawns the root the LoadedCapsule
resource names, spawns the new capsule and remembers it. Entities outside the old capsule's tree (the player, a game
manager) stay.
Names¶
Each spawned entity gets a rtype.Name (ecs/entity/Name.hpp) before its node's values: the node's name, the
capsule file's name (its stem) for the root. A node that gives a Name replaces it; an instance's root is named by the
node that places it.
Reloading¶
reloadCapsule(commands, capsules, root, instance, children) despawns the root's children, adds the capsule's current
root values again, spawns its children again and updates CapsuleInstance.version. The root entity and its other
components stay. A nested root (nested) is reloaded from its own capsule, which replaces the outer node's values on
it; reloading the outermost capsule it belongs to keeps them. The plugin's Render system rtype.Capsule.HotReload
reloads, at every frame, what was spawned from the capsules the ReloadedCapsules resource names, nested roots through
their outermost capsule: hot reload names the files it read again there, and a tool (the editor) the capsules it
redefined. The system and the resource are there with or without hot reload.
From scripts¶
Scripts describe nothing: files do. A system spawns, loads and reloads through three engine calls, listed in its
calls; each records into the system's own commands and adds what it reads and writes to the system's access.
| Call | Arguments | Result |
|---|---|---|
rtype.capsule.spawn |
capsule (a path) |
the root, reserved at once |
rtype.capsule.load |
capsule (a path) |
the new root; the capsule loaded before is despawned |
rtype.capsule.reload |
root |
true if it was a capsule's root |
The plugin also brings setup forms (CapsuleForms.luau, registered by addCapsuleForms() from its library and its
build step): engine.capsule.spawn(ctx, path, overrides), engine.capsule.load(ctx, path, overrides) and
engine.capsule.reload(ctx, root). A form checks its arguments, makes the call through ctx.call (so the system still
lists it) and patches the root with each override (ctx.commands:patch, Commands): only the fields
named change, over the values the capsule gives the root.
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 } }, -- rotation and scale stay the capsule's
})
-- when the boss is defeated:
engine.capsule.load(ctx, "scenes/level2.scene")
end,
})
ctx.commands:add after a spawn still replaces the whole component (its defaults with the fields given), as in C++;
patch<T>() is the C++ way to change part of it.
Connections¶
- Uses: Component registry (ids, presence), Commands,
Hooks (
copy), Hierarchy, Reflection (the file format). - Used by: Luau bridge (the calls), Replication (spawn by capsule id, later).
- Code:
src/rtype/plugins/capsule/; exampleexamples/plugins/capsule/; manual pagemanual/pages/capsules.md.
Pitfalls¶
- A node on the wrong side. A node is server-side by default: on a client, a camera or a background must be marked
client(orboth), or it is not spawned there. - Reloading a root the game added to. A reload despawns all the root's children, including ones the game parented to it, and keeps the root's other components, even ones the new version no longer sets.
- Editing a capsule after spawning. Instances are copies: they change only when reloaded.
- A file naming a component no plugin or script registers. It is refused when the files are read: list the plugin that owns the component.
Open questions¶
- Remapping
Entityfields that point inside the tree, written as node paths in the files (a turret aiming at a node of its own capsule). (Later) - Saving part of a running world back to a capsule file. The editor edits the capsules themselves and writes them with
writeCapsule()(docs/Editor.md), so this is only for "save the world as it is now". (Later) - Spawning by capsule over the network: the spawn record already has a
capsuleshort id, still unused. (Later)