14 · App and Plugins¶
What it is¶
The App is the entry point of a game: it owns the world, the schedule and the main loop. A plugin is a reusable bundle that registers components, resources, events, systems and other plugins into the App. A game is an App plus a list of plugins.
Why we need it¶
- R1: this is the Bevy-style engine: window, input, rendering, audio, assets, scripting and networking are each a plugin.
- R2: games are written as Luau plugins whenever possible.
- R3: a client and a dedicated server are the same game plugins with different engine plugins.
- R4: plugins are the unit of reuse between games.
How others do it¶
| ECS / engine | Mechanism |
|---|---|
| Bevy | App + Plugin trait + plugin groups (DefaultPlugins, MinimalPlugins); sub-apps for rendering |
| flecs | Modules (world.import<Module>()) |
| Unreal | Modules + subsystems; Mass processors registered by modules |
| Godot / Unity | Not ECS-based: scenes and scripts, with editor-driven composition |
Our choice¶
Bevy's model: rtype::ecs::App, rtype::ecs::Plugin, and plugin groups. Plus two things specific to
us: Luau plugins loaded through LuauPlugin, and a standalone mode that runs server and client
sides in one App.
How it works¶
The plugin interface¶
namespace rtype::ecs {
/// @brief A reusable bundle of components, resources, events and systems.
class RTYPE_ECS_API Plugin {
public:
virtual ~Plugin();
[[nodiscard]] virtual std::string_view getName() const noexcept = 0;
[[nodiscard]] virtual std::span<const std::string_view> getDependencies() const noexcept; // none by default
virtual void build(App& app) = 0;
virtual void finish(App& app); // once every plugin is built; nothing by default
protected: // plugins are values moved into the App; protected copy/move prevents slicing
Plugin() = default;
// copy and move constructors and assignments = default
};
} // namespace rtype::ecs
build registers things; it does not run gameplay. A plugin is built as soon as it is added, and
adding a plugin whose name was already added does nothing. A plugin is recorded before it is built, so two
plugins adding each other from build are each built once. A PluginGroup (app/PluginGroup.hpp) adds
several plugins through the App with its own build.
finish runs once on every plugin, in the order they were added, after all of them are built and before the
first frame (App::finishPlugins(), which runFrame() calls; a test or a tool that never runs a frame calls it
itself). It is for work that needs what later plugins registered: a plugin added before the scripting plugin cannot
see the components scripts declare from its build, but it can from its finish (the capsule plugin reads its
files there). A plugin added after that point is finished right after its build.
Plugin dependencies¶
A plugin names the plugins it requires in getDependencies(), by their getName(), instead of adding them
itself. Names, not types: a plugin loaded from a library can require another one without including its header.
It returns a static array, so the names outlive the call:
class TextPlugin : public rtype::ecs::Plugin {
public:
static constexpr std::array<std::string_view, 2> kDependencies{TransformPlugin::kName, TilemapPlugin::kName};
std::span<const std::string_view> getDependencies() const noexcept override { return kDependencies; }
// getName(), build()...
};
App::addPlugin builds the dependencies first, whatever order the plugins are added in, so a plugin's
build always finds what its dependencies registered. For each dependency, depth first:
| The dependency is | The App |
|---|---|
| already added | moves on |
registered in the App's PluginRegistry |
builds it from its factory (default settings) and warns on std::cerr: [App] Plugin 'rtype.Transform' added because 'rtype.Text' requires it |
| neither | throws exceptions::PluginException: Plugin 'rtype.Text' requires 'rtype.Tilemap', which was not added and is not registered; registered: ... |
| already being resolved | throws PluginException with the cycle: Plugin dependency cycle: 'a' -> 'b' -> 'a' |
A factory building a plugin with another name than the one it is registered under is refused the same way. After an error the plugin is not added (the dependencies built before it stay) and the App stays usable.
The PluginRegistry (app/PluginRegistry.hpp, app.getPluginRegistry()) holds a factory per plugin name,
taking no argument: the engine fills it with the plugins it knows, so a project lists only the plugins it wants
and gets their dependencies with a warning.
app.getPluginRegistry().add(std::string{TransformPlugin::kName}, [] { return std::make_unique<TransformPlugin>(); });
app.addPlugin(TextPlugin{}); // builds TransformPlugin first (warning), throws if TilemapPlugin is not registered
The App¶
rtype::ecs::App (app/App.hpp) owns one world, its Schedules and one run mode, the plugins added to
it, and the loop:
class GamePlugin : public rtype::ecs::Plugin {
public:
std::string_view getName() const noexcept override { return "game"; }
void build(rtype::ecs::App& app) override {
app.insertResource(Score{.value = 0});
app.addSystem(rtype::ecs::Phase::kStartup, "game.spawnPlayer", &spawnPlayer);
app.addSystem(rtype::ecs::Phase::kFixedUpdate, "game.movement", &movement);
app.addSystem(rtype::ecs::Phase::kRender, "game.drawScore", &drawScore).setSide(rtype::ecs::Side::kClient);
}
};
rtype::ecs::App app{rtype::ecs::RunMode::kStandalone};
app.addPlugins(rtype::ecs::MinimalPlugins{}).addPlugin(GamePlugin{});
return app.run(); // Startup once, then frames until a system sends AppExit; returns its code
| Member | Does |
|---|---|
App(RunMode = kStandalone) |
The run mode decides which systems run, from their side. Neither copyable nor movable: its schedules point to its world. |
addPlugin(plugin) / addPlugins(group) / hasPlugin(name) |
Plugins, built at once after their dependencies, skipped by name when already added |
getPluginRegistry() |
The factories by name the App uses for dependencies not added (above) |
addSystem(phase, name, function) |
Schedules::addSystem(), returning the system's configuration (after, before, setSide) |
insertResource(value) |
A resource of the world |
insertResourceIfAbsent(value = T{}) |
A resource of the world, only if it has no value yet (a plugin's default) |
getWorld(), getSchedules() |
The world and its schedules |
runFrame() |
One frame (scheduler), adding the default time plugin first if none was added |
run() |
Frames until an AppExit is read; returns its code |
AppExit (app/AppExit.hpp, "rtype.AppExit") is an event: any system sends it (the window plugin on
event::Closed, the server on a signal), several may, and the App stops after the frame it was sent in,
returning the code of the first one read.
Time¶
Every App has a TimePlugin (time/TimePlugin.hpp, named "rtype.time"): it inserts the Time
resource and installs the frame clock that runs FixedUpdate at a fixed rate
(Scheduler). If none was added, the App adds one with the defaults (60 ticks
per second, at most 5 per frame) before its first frame; MinimalPlugins adds the same default. To configure
it, add your own before MinimalPlugins and before the first frame: the default one is then skipped, by name.
app.addPlugin(rtype::ecs::TimePlugin{rtype::ecs::FixedTimestep{30, 5}}) // 30 Hz
.addPlugins(rtype::ecs::MinimalPlugins{});
app.addPlugin(rtype::ecs::TimePlugin::manual(std::chrono::milliseconds{50})); // tests: every frame lasts 50 ms
TimePlugin measures std::chrono::steady_clock; manual() makes every frame last a fixed duration, so tests
and replays are deterministic. A clock installed directly with getSchedules().setClock() is replaced by the
default plugin's on the first frame: a custom clock comes from a plugin named "rtype.time" added in place
of TimePlugin.
Three ways to start¶
// Client: rtype::ecs::App app{rtype::ecs::RunMode::kClient};
app.addPlugins(rtype::plugins::DefaultPlugins{}) // window, input, render, audio, assets, script
.addPlugin(rtype::plugins::ClientPlugin{"127.0.0.1", 4242})
.addPlugin(rtype::plugins::LuauPlugin{"scripts/rtype/plugin.luau"})
.run();
// Dedicated server (headless): rtype::ecs::App app{rtype::ecs::RunMode::kServer};
app.addPlugins(rtype::ecs::MinimalPlugins{}) // time (later assets metadata, script)
.addPlugin(rtype::plugins::ServerPlugin{4242})
.addPlugin(rtype::plugins::LuauPlugin{"scripts/rtype/plugin.luau"})
.run();
// Standalone (single player, tests): rtype::ecs::App app{rtype::ecs::RunMode::kStandalone};
app.addPlugins(rtype::plugins::DefaultPlugins{})
.addPlugin(rtype::plugins::StandalonePlugin{})
.addPlugin(rtype::plugins::LuauPlugin{"scripts/rtype/plugin.luau"})
.run();
The game plugin is the same file in all three.
Standalone mode¶
Single player should not require running a server. An App made with RunMode::kStandalone runs both
sides: server systems (gameplay) and client systems (presentation) in the same world. StandalonePlugin
fills PlayerInput directly from local input instead of from the network. Because gameplay reads
PlayerInput and never the keyboard, nothing in the game changes.
| Mode | Server systems | Client systems | PlayerInput comes from |
|---|---|---|---|
| Client | no | yes | local input → sent to the server |
| Server | yes | no | the network |
| Standalone | yes | yes | local input, directly |
Default plugin groups¶
| Group | Plugins |
|---|---|
MinimalPlugins (rtype::ecs) |
TimePlugin; later AssetPlugin (metadata only), ScriptPlugin |
DefaultPlugins |
MinimalPlugins + WindowPlugin, InputPlugin, RenderPlugin, AudioPlugin, TransformPlugin, HierarchyPlugin |
| Opt-in | ClientPlugin, ServerPlugin, StandalonePlugin, CollisionPlugin |
Wiring Ethan's backends¶
GraphicsPlugin (plugins/backend/, rtype::plugins::backend) reuses BackendRegistry unchanged. The executable,
the only place that knows GLFW and Vulkan, fills a registry and hands it to the plugin with the Settings, so the
plugins depend on no backend:
auto registry = std::make_unique<rtype::plugins::graphics::BackendRegistry>();
rtype::platform::glfw::registerPlatform(registry->platforms);
rtype::render::vulkan::registerRenderer(registry->renderers);
app.addPlugins(rtype::ecs::MinimalPlugins{})
.addPlugin(rtype::plugins::graphics::GraphicsPlugin{std::move(registry), settings}); // brings InputPlugin
return app.run();
build() only registers: the window opens in the Startup system, which calls registry.createBackend(settings)
(keeping the setup → init → init order) into the Backend main-thread resource. Every system
of the plugin is a client one, so a dedicated server has no window.
sequenceDiagram
participant App
participant BP as GraphicsPlugin
participant BR as BackendRegistry
App->>BP: build(app): resources, events, systems
App->>BP: Startup: rtype.graphics.create
BP->>BR: createBackend(settings)
BR-->>BP: Backend (platform + renderer)
loop Every frame
App->>BP: PreUpdate: rtype.graphics.events (pollEvents → PlatformEvent in order + typed events, resize, AppExit)
App->>BP: Render: rtype.graphics.beginFrame (ClearColor), drawing systems, rtype.graphics.endFrame
end
Between the two frame systems, rtype.graphics.camera shows the world from the entity with a Camera (the highest
priority) and a GlobalTransform, through renderer.setView(); with no camera entity, the renderer keeps its default view. While the window is minimized,
the events system waits for an event instead of polling, and the render systems skip the frame. A window always comes with input: the GraphicsPlugin adds the InputPlugin and orders its events system
before rtype.Input.Update, which reads the PlatformEvents in order. The dependency goes one way only: the input
plugin knows nothing of the backend. Named system sets ("send platform events" before "read platform events") will
later replace the explicit ordering, so other producers (replays, the network) join without knowing the input plugin.
Luau plugins¶
LuauPlugin is a C++ plugin that loads a Luau plugin file and forwards its registrations to the App
(see Luau bridge):
local RtypePlugin = ecs.plugin("rtype.Game")
function RtypePlugin:build(app)
app:load("components/Shield.luau")
app:load("systems/ShieldRegen.luau")
app:addPlugin("scripts/rtype/weapons/plugin.luau")
end
return RtypePlugin
A C++ game plugin is added beside it when part of the game needs native speed
(rtype::game::CollisionPlugin).
The loop¶
app.run() runs frames (Schedules::runFrame(): Startup on the first one, then the phases, FixedUpdate
as many times as the clock says) until a system sends AppExit (the window plugin does so on
event::Closed; the server on a signal), then returns its code. app.runFrame() runs a single frame, for
tests and for engines that drive the loop themselves.
Connections¶
- Uses: World, Scheduler, Resources, Events.
- Used by: every plugin, Luau bridge, Replication, Hierarchy.
Pitfalls¶
- Doing work in
build.buildonly registers; loading files or opening windows belongs inStartupsystems, so registration stays fast and order-independent. - Plugins reaching into each other. Plugins communicate through components, resources and events, never by calling each other's functions.
- Undeclared dependencies. A plugin ordering its systems against another plugin's (
.after("rtype.Text.Draw")) requires that plugin: declare it ingetDependencies(), or the schedule fails to build when the other plugin is left out. - Mode-specific game code. If game code checks "am I the server?", it is in the wrong place; use system sides.
Open questions¶
- Should rooms on the server be separate Apps (each with its own schedules) or one App with several
worlds? (ECS + network) For now one App has one world;
Schedulesis per world so that either stays possible. CollisionPluginscope: AABB only, or circles too? (Team)