4.3 KiB
ADR-0084: Engineering UI toolkit and ownership boundary
Status
Proposed, 2026-10-02. User authorized evaluating/adopting a maintained framework. Preferred candidate: Dear ImGui for the engineering client only. Adoption requires an exact source pin, licence inventory and Windows/Linux compatibility probe in M9.8a. No dependency has been added by this ADR. Final player UI remains undecided.
Context
M9.4/M9.5 intentionally used rectangles and unlabelled gauges. M9.8 now requires readable text, a launcher, dialogs, dismissible notifications, click selection and control rebinding. The existing client uses SDL3 and SDL_Renderer. The headless libraries and immutable biological views must remain toolkit-independent.
Decision proposed
Use Dear ImGui's upstream SDL3 platform and SDL_Renderer3 rendering adapters behind the private native client boundary. Implement owned application state for toasts, selection, dialogs and action bindings; do not equate toolkit widget state with simulation or session authority. Reuse toolkit text, input, layout and widgets instead of implementing those primitives. Disable unnecessary multi-window features.
Keep public biological/render snapshot contracts free of ImGui and SDL types. Toolkit initialization follows the window/renderer; shutdown precedes their teardown. UI capture is resolved before generating world intentions. Document and test event ordering, focus loss, modal capture and binding changes together with API changes.
Before merge of integration: choose a reviewed release supported by its actual source history (not an assumed latest version), record source commit/archive hash, retain MIT licence and embedded font/third-party notices, build only needed sources, measure incremental artifact size and idle/frame cost, and verify lifecycle on both supported toolchains. Normal configure must not download dependencies. Use explicit preparation and pinned sources as in ADR-0077; no new general package manager.
Alternatives considered
| Option | Assessment |
|---|---|
| Dear ImGui | C++ widget API and upstream SDL3/SDL_Renderer adapters fit the current engineering client. Low integration surface; immediate-mode work and accessibility limitations need measurement/review. Preferred. |
| RmlUi | Retained documents and styling could suit final game interfaces. Integration adds document/assets/font and render-interface work; no demonstrated M9 benefit over the existing renderer path. Keep as a later product-UI candidate. |
| Custom text/widgets | Avoids a toolkit dependency but requires fonts, editing, focus, layout and popup behavior to be built and maintained; rejects the user's preference for an established framework. |
These are integration assessments, not measured performance or binary-size rankings.
Benefits
Readable engineering tools, reusable interaction primitives and narrow dependencies. The simulation stays independent and the final game UI is not prematurely selected.
Costs
New pinned source and licence obligations, text/atlas resource lifetime, input capture integration and Windows/Linux visual validation. Toast/binding policies remain ours.
Risks
Toolkit input capture can leak movement or selection if handled after world input. Immediate-mode UI is not a hard frame-time guarantee. Font/DPI/accessibility behavior requires real review. Dependency versions and notices must be checked in the pinning segment, not inferred from this high-level comparison.
Consequences
Revisits ADR-0081's scoped decision to defer ImGui once labelled engineering UI is needed. M9.8a must change this status to accepted only with the pin and probe evidence. M9.8 delivery is tracked in ../engineering/M9_8_DELIVERY_PLAN.md.
Primary-source evidence reviewed 2026-10-02
- https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md — upstream SDL3 and SDL_Renderer3 adapters; platform/render separation.
- https://github.com/ocornut/imgui/blob/master/LICENSE.txt — MIT licence; pin-time notice audit still required.
- https://github.com/ocornut/imgui/blob/master/docs/FAQ.md — input capture guidance and integration responsibilities.
- https://github.com/ocornut/imgui/releases — release/maintenance evidence; no version selected here.
- https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html — context and rendering integration requirements for the alternative.