Skip to content

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

Pitfalls

  • Doing work in build. build only registers; loading files or opening windows belongs in Startup systems, 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 in getDependencies(), 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; Schedules is per world so that either stays possible.
  • CollisionPlugin scope: AABB only, or circles too? (Team)