Flutter & shipping
App structure
Structure an app in three layers, the engine, signals and the widgets that show them, the way the subtitle and dialogue widgets are built.
Engine · Signal · Presentation — a three-layer pattern for structuring an app on top of Just Game Engine. It isn't new machinery: it's the same shape already backing the Subtitle (SubtitleController + SubtitleOverlay) and Narrative (NarrativeSignals) subsystems (see ARCHITECTURE.md), generalized for app code and built from pieces that already exist — the engine's EventBus and reactive ECS (ComponentSignal, EntitySignal, WorldSignal), and just_signals' Signal, Computed and SignalBuilder.
Engine layer State layer Presentation layer
(ECS: World, Entity, (plain Dart, no (Flutter widgets,
Component, System) Flutter imports) SignalBuilder<T>)
│ │ │
System.update() ──writes──▶ Signal<T> ◀──reads (SignalBuilder)───┤
│ ▲ │
world.events.fire(event) ──▶ EventBus.on<T>() ──▶ translates to Signal writes / callback calls- Engine layer:
Systems,Components,Entitys — the only layer that imports ECS types. Pushes data outward two ways: continuous values viaSignal.value =, one-shot transitions viaworld.events.fire(event)(delivered synchronously to the subscribers of the event's exact runtime type). - State layer: plain Dart classes holding
Signal<T>/Computed<T>fields (one*Signalsclass per feature, followingNarrativeSignals'/SubtitleController's shape), plus small controller classes exposing named transition methods instead of a raw settableSignal. Depends only onjust_signals— noflutter/material.dart, no ECS types. Testable in isolation, with no widget tree required. - Presentation layer: Flutter widgets that read the state layer exclusively through
SignalBuilder<T>/SignalSelector<T, R>, and call back out through closures/controller methods instead of reaching intoWorld/Entitydirectly. Zero ECS imports.
Where the presentation layer attaches
GameWidget has two slots for widgets drawn over the game:
GameWidget(overlay: ...)— a widget stacked over the game canvas, inside the game's ownFocusnode. It gets taps but can never hold keyboard focus, which keepsengine.input's key state reliable. Good for a HUD and buttons driven by pointer or touch.engine.layers— register aGameLayer(anid, anorder, andcreateController(engine)). EveryGameWidgetshowing the engine asks it for its ownGameLayerController, whosebuilddraws the widgets and whoseonFrameruns once a frame after the game has stepped. Layers sit *outside* the game'sFocusnode, so a text field can be typed into and a menu walked with the arrow keys; keys a layer does not use still reach the game. Use a layer for menus, pause screens and anything that needs the keyboard.engine.layers.setEnabled(id, false)hides one and keeps its state.
Either way the widgets read signals from the state layer; neither slot needs the widgets to know about entities. When engine.context.localization is set, both sit under a LocalizationScope for it.
Pros
- Surgical rebuilds, not polling.
SignalBuilderis aStatefulWidgetholding one listener per instance; aSignal.value =write notifies only its own listener set directly, with noInheritedWidgetdependency walk and noTimer-driven cadence decoupled from the frame loop. UI updates land the same tick the underlying data changed, instead of up to one polling-interval late. - One-shot state has zero steady-state cost.
EventBus.fire()only does work when something actually happens (a death, a level-complete, a dialogue line) — there's no "is it still true?" check running every frame the way inferring state from component presence/absence would require. - A clear seam for hot-path discipline. Because the presentation layer only ever touches the state layer, it's easy to audit exactly what runs on every tick (the engine-layer systems writing into it) versus what only runs on user interaction — a natural place to enforce "no per-frame allocations, no per-frame O(n) scans" in review.
- Independently testable state. The state layer has no Flutter dependency, so
Signal/controller logic can be unit-tested without pumping a widget tree. - Reuses pieces the engine already exercises — the same shape as the Narrative and Subtitle subsystems, so there is no new state-management package or mental model for code already using the engine's reactive ECS.
Cons (and how to mitigate each)
- Signals make the *presentation* side cheap, not the engine layer automatically. A
System.update()that hunts for an entity every frame — walkingworld.entities, or a broadworld.query(...)result, to find one thing — pays that walk every frame, no matter how cheap the signal write after it is. The world's own lookups are indexed:findEntityByName,findTaggedandallTaggedare map lookups (andallTaggedreturns a cached list, so it does not allocate), andqueryresults are cached until a matching archetype changes. *Mitigation*: use those lookups rather than scanning, and for an entity a system touches every frame, resolve it once (e.g. at spawn time) and keep the reference, checkingentity.isAlivebefore use. This exact mistake — a HUD-sync system, plus two older systems, resolving the same entities every frame — was caught and fixed in the app that motivated this document. - More files/indirection than a single local toggle needs. Three layers for one boolean is overhead. *Mitigation*: reserve this pattern for state genuinely shared across multiple widgets or updated continuously by the engine layer — a one-off, widget-local UI toggle can stay a plain
setStatefield. - No built-in write-ordering guarantee if two systems touch the same signal in one frame.
Signalhas no scheduling of its own — whichever system runs first, its listeners fire immediately on that write. *Mitigation*: give the writing system an explicitpriorityplacing it after everything it reads from, so a signal is only ever written once per frame with fully-settled data (e.g. a HUD-sync system reading post-gameplay health should run afterHealthSystem, prioritySystemPriorities.gameplay, not before).
Performance Tips (specific to this pattern)
- Keep entity lookups out of per-frame loops when the answer is stable.
world.findEntityByName(name),world.findTagged(tag)andworld.allTagged(tag)are indexed and cheap;world.query([HealthComponent, TagComponent])is cached per set of component types. What stays expensive is scanning — iteratingworld.entitiesor a large query result to find one entity. Cache a reference when you can. - Prefer one
Signalper meaningfully-independent value over batching unrelated values into a single tuple/record signal, unless they're always consumed together by the same widget — finer-grained signals mean fewer unrelated widgets rebuild per write. Signal.value =already no-ops when the new value equals the old one — don't hand-roll an extra equality check before assigning.