## Goal Ship a game with image-driven GUI worth a public announcement. **Guinevere** is Turian's in-game GUI — a component-based document-model UI built on dvui. This epic tracks the implementation. ## Architecture summary (final) ### Document model — `.uidoc` JSON asset - UI lives in a `.uidoc` JSON asset (UI-Toolkit-shaped), instantiated via a `ui_document` scene component. - UI nodes are **not** SceneNodes and never touch `engine/scene/Transform.zig`. - Nodes are generic containers with behavior through `UiComponent` (closed union): `image`, `text`, `layout`, `button` in v1. ### Module split (engine stays dvui-free) - `engine/ui/` — pure data + logic, **zero dvui imports**: `UiDocument.zig`, `UiEvents.zig`. Unit-testable. - `subsystems/ui_render/` — new build module. Contains the **single** tree-walk mapping `UiNode`s → dvui calls. Consumed by both Studio's viewport overlay and the shipped game. ### Events — strings at rest, handles at runtime - `EventBinding = union(enum) { named: []const u8, ... }` — serialized as JSON, resolved to dense `EventId` (u32) at load. - Type-based dispatch: `ui_events.register(PlayClicked); ui_events.on(PlayClicked, ctx, onPlay)`. ### Styling — guarantees now, tech later - All appearance fields live in grouped `StyleBlock`, never loose among fields. - dvui's existing `Theme.Style.Name` provides per-state colors and ninepatches. - Styling spike (timeboxed) validates image-driven workflow before assets proliferate. ### Authoring - Studio: viewport overlay draws the `.uidoc` tree letterboxed at reference resolution. - `UiDocumentEditor` (registered through EditorRegistry #40) with node tree panel + control templates. - Game runtime: dvui `sdl3gpu-ontop` pass in `editor/GameCodegen.zig`'s main loop. ### Post-MVP (tracked in sub-issues, not blocking) Theme assets, transitions, style assets & class lists, Inspector-wired bindings, typed input handles, font assets, 9-slice editor, gamepad nav, event dropdown, toggle/scroll components, drag/drop authoring, reflection data-binding, debug dump. ## MVP checklist (Part 2 — dependency order) - [ ] #92 — **A**: UI: drop dvui fork pin — native `EditorFrameTiming` in Studio (M0) - [ ] #93 — **B**: UI: `.uidoc` asset — component-based node schema in `engine/ui` (ADR) (M1) - [ ] #94 — **C**: UI: `ui_document` scene component + asset-registry integration (M1) - [ ] #95 — **D**: UI: `UiEvents` typed event registry (strings at rest, handles at runtime) (M1) - [ ] #96 — **E**: UI: styling spike — image-driven workflow over dvui theme/styles (M2) - [ ] #97 — **F**: UI: `ui_render` module — shared node-tree → dvui draw walk, stable IDs (M2) - [ ] #98 — **G**: Studio: scene-viewport UI overlay ("Show UI overlay" toggle) (M2) - [ ] #99 — **H**: Studio: `UiDocumentEditor` + built-in control template library (M2) - [ ] #100 — **I**: UI: button interaction + event dispatch (M2) - [ ] #101 — **J**: Studio: PlayMode input priority — respect `e.handled` (M2) - [ ] #102 — **K**: Game runtime: dvui `sdl3gpu-ontop` pass in generated game (M3) - [ ] #103 — **L**: Example: image-driven GUI demo game (announcement artifact) (M3) ## Deferred issues (Part 3 — tracked, not blocking) - #104 — `.uitheme` theme asset - #105 — `transition` component - #106 — style assets & class lists - #107 — Inspector-wired event bindings - #108 — InputActions → typed handles - #109 — font assets - #110 — 9-slice slice-rect visual editor - #111 — gamepad/keyboard navigation - #112 — event dropdown enumeration - #113 — `toggle`, `scroll` interaction components - #114 — drag/drop UI layout authoring - #115 — `struct_ui` reflection data-binding - #116 — frame/widget debug dump ## Related - Closes the intent of #9 (GUI library evaluation). - #40 (EditorRegistry) — prerequisite for H. - #41 (SOAP layer) — related via EventBinding; post-MVP. - #10/#42 (Input API / rebinding) — related via typed handles; post-MVP. ## Finish line "Ship a game with image-driven GUI worth a public announcement."