fledge_ui library
Retained-mode game HUD/UI for Fledge.
Phase 7 of the restructure: anchor-based layout with containers, text, images, and solid panels painted on top of the sprite pipeline.
Contents
- UiNode, UiSize, UiOffset, UiComputedRect — foundational components every UI entity carries.
- UiAnchor, UiAnchorComponent — anchor within the parent's rect.
- UiContainer, LayoutMode — row / column / stack layout.
- UiText, UiImage, UiRect — visual node kinds.
- LayoutSystem — walks the UI hierarchy and computes screen
rects (runs in
Schedules.postUpdate). - UiExtractor, ExtractedUiElement / ExtractedUiImage / ExtractedUiRect / ExtractedUiText — main→render-world handoff.
- FledgeUiOverlay — widget wrapper that layers the UI paint pass on top of a game render view.
- UiPlugin — wires the layout system and extractor.
Focus, keyboard, and gamepad navigation are deliberately out of scope for this phase — see the phase 7b plan.
Classes
- ExtractedUiElement
- Common base for extracted UI elements.
- ExtractedUiImage
- Extracted image UI element — a tinted textured quad.
- ExtractedUiRect
- Extracted solid-colour UI panel.
- ExtractedUiText
- Extracted text UI element.
- FledgeUiOverlay
-
Composes an
App's game view with a UI paint pass drawn on top. - LayoutSystem
- Walks the UI hierarchy each frame and writes a UiComputedRect on every entity that carries UiNode.
- PlacedEntityRef
-
Ties a placed entity back to its registry record (
PlacedRecord.id). -
PlacedEntityRegistry<
TRecord extends PlacedRecord> - The placed things in the world, per map, plus a deterministic id allocator (generic core).
- PlacedRecord
- What PlacedEntityRegistry needs to know about a record: its id and the map it is on. The rest of the record is the game's.
- PlacementAccess
-
What a game PlacementValidator (and anything else
PlacementSystemruns for the game) reads, declared onPlacementSystem'sSystemMeta. - PlacementCancelled
- Placement of key was cancelled (a cancel request, or entering a different placeable). Placement mode has ended.
- PlacementCancelRequested
- Leave placement mode without placing (PlacementCancelled). Ignored unless placing.
- PlacementConfirmed
- The player confirmed placing key on tile (validated in that run). Placement mode has ended. The game spawns the entity (and takes the item, registers the record, ...) in response.
- PlacementConfirmRequested
-
Place the placeable at the preview tile. Ignored unless placing with a
valid preview (
PlacementState.isValid, re-checked in the same run). Confirming ends placement mode (PlacementConfirmed). - PlacementCorePlugin
- The generic placement layer (design §8.2):
- PlacementEntered
- Placement mode was entered for key (no preview tile yet, unless a preview request came in the same tick).
- PlacementEnterRequested
- Enter placement mode for the placeable key (an opaque id supplied by the game). Placing something else is cancelled first (PlacementCancelled); already placing key is a no-op. Several in one tick: the last one wins.
- PlacementGhost
- Marks the one ghost-preview entity (generic core): what it shows and where. Kept up to date by PlacementGhostSystem.
- PlacementGhostConfig
-
How the ghost looks and where a tile is in world space — supplied by the
game (
PlacementCorePlugin(ghost:)), stored as a resource. - PlacementGhostSystem
-
Keeps one world-space ghost entity at the preview tile while placing
(generic core): PlacementGhost +
Transform2D+GlobalTransform2D+ the game'sSprite(PlacementGhostConfig.ghostSpriteFor) tinted PlacementGhostConfig.validColor or PlacementGhostConfig.invalidColor. It is drawn by the normal sprite extraction, so it follows the camera. - PlacementPreviewMoved
- The preview moved to tile, or its validity (or refusal reason) changed on the same tile.
- PlacementPreviewRequested
- Move the preview to tile (x, y) of map mapKey. Ignored unless placing. Several in one tick: the last one wins.
- PlacementState
- The one placement in progress (or none). Transient: never saved.
- PlacementSystem
- The only writer of PlacementState (generic core).
- PlacementTile
- A tile on a map, as the placement core sees it: mapKey is an opaque map id supplied by the game, x / y the tile coordinates on that map.
- PlacementValidator
-
Decides where a placeable may go — supplied by the game and registered
as the
PlacementValidatorresource (PlacementCorePlugin(validator:)). - UiAnchorComponent
- Anchor point of this node within its parent's rect.
- UiComputedRect
- Output of LayoutSystem — the entity's laid-out screen-space rect.
- UiContainer
- A container that lays out its children according to mode.
- UiExtractor
- Extracts UI entities into the render world as ExtractedUiElements.
- UiImage
- An image UI node.
- UiNode
- Marker: this entity is a UI node.
- UiOffset
- Screen-space offset from the anchor point.
- UiPlugin
-
Wires the retained-mode UI pipeline into an
App. - UiRect
- A solid-colour panel UI node.
- UiSize
- Explicit size in logical pixels.
- UiText
- A text UI node.
Enums
- LayoutMode
- How a UiContainer arranges its children.
- PlacementMode
- What placement mode is doing.
- UiAnchor
- Where a UI node anchors relative to its parent's padded interior (or the viewport, for root nodes).
Properties
- placementActive → RunCondition
-
Whether placement mode is active (a
RunCondition; callable as a plain check too). False without a PlacementState.final