forgotten_caves/notes/05-ui_renderer.md

UI Renderer

Current state

No UI primitives exist. The framebuffer is currently filled by the game world only (render_viewport in game.rs: tile pass + entity sprite pass). pixelhelper.rs has low-level pixel/blit helpers but nothing higher-level.

Goal

Draw common roguelike UI elements (panels, borders, HUD bars, etc.) procedurally into the u8 framebuffer, composited on top of the game world.

Design notes

The virtual resolution is 320×240, so UI layout should be designed in those pixel units.

Likely primitives needed (built on top of pixelhelper.rs):

• fill_rect(frame, x, y, w, h, color) — solid filled rectangle
• draw_rect(frame, x, y, w, h, color) — 1-pixel border rectangle
• draw_border_box(frame, x, y, w, h, tileset) — box drawn with corner/edge tiles from a tileset (classic roguelike panel look)
• draw_hbar(frame, x, y, w, value, max, fg, bg) — horizontal progress/HP bar

Panels are typically fixed regions of the screen (e.g. a status bar at the bottom 40px, a message log on the right). Hard-coding these regions first is fine; extract to a layout system only if needed.

The UI layer draws after the world layer so it always appears on top. Draw order within the UI should be back-to-front (backgrounds before text).

Open questions

• Tileset-based borders vs. line-drawing: which look are we going for?
• Does the message log need scrolling? Probably not at first.