119 lines
7.2 KiB
Markdown
119 lines
7.2 KiB
Markdown
[Reviewed]
|
|
# ADR-0084: Engineering UI toolkit and ownership boundary
|
|
|
|
## Status
|
|
Accepted for the isolated M9.8a engineering UI probe, 2026-10-02. User delegated
|
|
UI selection. Dear ImGui 1.92.9b, MIT, upstream commit
|
|
`f1cc2ae15e53a861a874c3034aae6798fde194ab`; archive SHA-256
|
|
`21d8a0a565e85dce943e375db00812c2f3f0ab21f3f0f7964e364a63422d7f99`.
|
|
Published 2026-07-31; upstream latest-release API and tag checked 2026-10-02.
|
|
Checksum is locally measured over the upstream HTTPS archive, not an independent
|
|
signature. The pin is in tools/imgui-pin.cmake. Broader application integration
|
|
follows the probe. 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
|
|
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 records the pin and executed probe evidence in VALIDATION.md.
|
|
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; notice inventory in third_party/imgui/README.md.
|
|
- 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; v1.92.9b selected above.
|
|
- https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html — context and rendering integration requirements for the alternative.
|
|
|
|
|
|
The probe compiles core, draw, tables, widgets and the SDL3/SDL_Renderer3 backends;
|
|
no demo, docking, multi-viewport, FreeType or external font dependency is introduced.
|
|
Use the embedded ProggyClean bitmap font explicitly for the probe. Retain LICENSE.txt,
|
|
docs/FONTS.md, imgui_draw.cpp and the stb headers' embedded notices at
|
|
packaging. The bundled ProggyForever data also carries notices in imgui_draw.cpp;
|
|
include the source notice inventory even when that font is not selected.
|
|
Normal headless/client configuration does not require ImGui until explicitly enabled.
|
|
|
|
|
|
## M9.8b application state contract
|
|
Accepted for bounded toolkit-independent state. See
|
|
[CLIENT_UI_STATE](../engineering/CLIENT_UI_STATE.md): eight notifications with
|
|
240-byte text and explicit expiry/overflow; one id-matched modal. Input capture
|
|
requested by an external UI cannot be disabled by the legacy Tab shortcut.
|
|
Rendering and toolkit focus integration remain M9.8c.
|
|
|
|
SessionClient's local event delivery is capped at 1024, reserving room for all 256
|
|
unresolved intentions plus loss/backpressure events. On backlog it disconnects,
|
|
marks views stale and waits for the consumer to drain before reconnecting. Earlier
|
|
queued outcomes are preserved. This changes no wire format or biological rules.
|
|
|
|
## M9.8c integration
|
|
Accepted for the engineering client. The toolkit context is owned by the platform
|
|
`Application` (created after and destroyed before the SDL renderer, reattached on
|
|
device reset), with ini/log files disabled and the embedded bitmap font. Toolkit
|
|
events are routed before world input; `WantCaptureKeyboard`/`WantCaptureMouse`
|
|
feed the same capture path as external capture, so typing in a field or clicking
|
|
a panel never moves, pans, zooms or selects. Only the app's panels file draws
|
|
widgets; launcher/selection/label/outcome-log state stays toolkit-independent and
|
|
tested without SDL. Remote failures are reported through fixed launcher text; no
|
|
path, certificate or grant byte is displayed, logged or saved.
|
|
|
|
`SessionClient::unreachable_attempts()` (additive API) counts connection attempts
|
|
that fail before any session event, so the launcher bounds "unreachable" without
|
|
an event per retry. No wire format, grant or biological rule changes.
|
|
|
|
M9.8c review corrections: the adapter reads the pinned toolkit's internal window
|
|
list (`imgui_internal.h`: active, unhidden windows' clipped rectangles and the open
|
|
popup stack) to decide pointer ownership per SDL event; `WantCaptureMouse` alone is
|
|
one frame late for same-batch input. This internal use is tied to the 1.92.9b pin
|
|
and must be rechecked on any toolkit update (the lifecycle and panel tests fail if
|
|
it regresses). External capture no longer cancels the Tab toggle. Mode and remote
|
|
session lifetime are owned together (`SessionHost`).
|