Macroquad Graphical Client — Gfx Play Client

Summary

Ship flatland3-gfx as the only interactive play client. It connects through flatland-client-lib, implements full play behavior (movement, combat, inventory, quests, NPC chat, rotation editor, etc.), and renders the world with Macroquad + egui HUD/overlays.

Retired: Ratatui play (tools/flatland default play, make dev-play), flatland-dev embedded play. flatland3 CLI is kept for auth and agent subcommands (inventory --json, etc.) — not for human play.

Decisions (locked for v1)

Current architecture (what we're cloning)

Pain points to fix while porting:

• ~1,700-line play loop in tools/flatland/src/play.rs duplicated in tools/flatland-dev/src/play.rs
• crates/tui/src/map_presentation.rs and crates/tui/src/world.rs are engine-agnostic but depend on ratatui::style::Color
• Input in crates/tui/src/app.rs is tied to crossterm::event::KeyEvent

Target architecture

Phase 0 — Extract flatland-client-ui

New crate: crates/client-ui/

Move engine-agnostic code out of flatland-tui (TUI becomes thin adapters):

New input abstraction in client-ui/src/input.rs:

pub enum UiKeyEventKind { Press, Release, Repeat }
pub struct UiKeyEvent { pub kind, pub code: UiKeyCode, pub modifiers }
pub enum UiPointerEvent { Move { x, y }, Click { x, y, button }, Scroll { .. } }

• crates/tui/src/input.rs: map crossterm::Event → UiKeyEvent / UiPointerEvent
• Gfx crate maps macroquad keys/mouse → same types
• MovementState::apply_key becomes apply_ui_key(&UiKeyEvent, ...)

Refactor flatland-tui: re-export from client-ui where needed; render.rs converts RgbColor → ratatui::Color at draw time only.

Gate: cargo test -p flatland-client-ui -p flatland-tui must stay green before gfx work.

Phase 1 — Extract flatland-play-loop

New crate: crates/play-loop/

Single async session driver extracted from tools/flatland/src/play.rs:

pub struct PlaySessionConfig { pub keys, pub auto_reconnect, ... }
pub struct PlaySession<S: PlayConnection> { client, movement, overlays, chat, ... }

impl<S> PlaySession<S> {
  pub async fn tick(&mut self, input: &[PlayInput], renderer: &mut impl PlayRenderer) -> PlayTickResult;
}

Responsibilities (lifted verbatim from play.rs):

• client.drain_events() + stall logging
• 100 ms intent interval: movement / auto-nav / move_by / stop
• InputAction → GameClient method dispatch (83 actions today)
• Chat mode buffer, reconnect/backoff
• Builds PlayHud snapshot for renderer

Trait for front ends:

pub trait PlayRenderer {
  fn draw(&mut self, state: &GameState, hud: &PlayHud, ui: &PlayUiState);
  fn world_rect(&self) -> ScreenRect; // for mouse_to_world
}

Refactor tools/flatland/src/play.rs and tools/flatland-dev/src/play.rs to call PlaySession — behavior must not change (regression: manual make dev-play smoke).

Phase 2 — flatland-gfx shell (world map + connect)

New crate: crates/gfx/

Dependencies: macroquad, egui-miniquad (or egui_macroquad), flatland-client-ui, flatland-client-lib, flatland-play-loop

Window / loop (crates/gfx/src/lib.rs):

#[macroquad::main("Flatland3")]
async fn run_gfx(connect_opts: ConnectOptions) {
  loop {
    let input = poll_macroquad_input();
    session.tick(&input, &mut renderer).await;
    clear_background(BLACK);
    renderer.draw_world();         // macroquad
    renderer.draw_egui(&egui_ctx); // panels
    next_frame().await;
  }
}

World rendering (Macroquad, not egui):

• 1 world meter = CELL_PX (start 16px, configurable)
• WorldView::build_with_target unchanged; draw each cell with draw_text_ex using bundled monospace TTF
• Square cells fix TUI's tall-font stretch noted in crates/tui/src/world.rs
• Target rings: colored cell background rects (red T1, blue T2) matching TUI logic in render.rs draw_world
• Hover cursor: + glyph in dark gray
• Camera: center on player; optional zoom later

Mouse: port mouse_to_world from render.rs using renderer.world_rect() + same grid math from grid_to_world.

Milestone: connect, walk with WASD, click-to-walk, map-target mode, see AOI terrain/entities with YAML colors.

Phase 3 — egui HUD panels

Use egui for all non-map UI. Implement panel modules mirroring TUI:

Layout: reuse HudLayout from client-ui to position egui panels per HudViewMode (Normal / Compact / Map).

Input routing: when egui wants keyboard (egui_ctx.wants_keyboard_input()), skip movement; otherwise forward to MovementState.

Phase 4 — Ship flatland3-gfx binary

New package: tools/flatland-gfx/

• Clap args mirror PlayArgs in tools/flatland/src/play.rs: --name, --server, --no-reconnect
• Reuse auth path from tools/flatland/src/game_session.rs (prepare_remote_play)
• Workspace wiring in root Cargo.toml:

members = [ ..., "crates/client-ui", "crates/play-loop", "crates/gfx", "tools/flatland-gfx" ]
macroquad = "0.4"
egui = "0.29"
egui-miniquad = "..."  # pin compatible pair at implementation time

Makefile / docs:

• make dev-play-gfx → ./scripts/dev-play-gfx.sh (parallel to scripts/dev-play.sh)
• Update specification binaries table
• Short docs/graphical-client.md: build, run, keybind parity note

No content-admin changes for v1 — same YAML catalogs; gfx reads map-glyphs.yaml via existing client-ui loader.

Phase 5 — Parity checklist and tests

Automated:

• cargo test -p flatland-client-ui -p flatland-tui -p flatland-play-loop -p flatland-gfx
• Headless gfx smoke: PlaySession + mock renderer asserting WorldView dimensions and InputAction mapping (no GPU in CI)
• Keep existing flatland-client-lib connect tests

Manual parity matrix (must pass before calling v1 done):

• Movement: WASD (chord diagonals), sprint toggle, vertical axis, Space stop, Shift+Space lunge
• Map: click walk, m target mode, auto-nav cancel
• Combat: Tab targets, hotbar 1–9, dodge (c)/block (q)/lunge, rotations
• Social: say/whisper chat, NPC interact (f)
• Economy: inventory, craft [, harvest ,, pickup p, shop
• Meta: ? help, . HUD cycle, reconnect

Suggested implementation order (PR slices)

1. client-ui extraction + tui refactor (no gfx yet) — largest refactor, zero user-visible change
2. play-loop extraction + flatland/flatland-dev thin wrappers
3. gfx world-only + flatland3-gfx connects and walks
4. egui status + log + help
5. egui combat + inventory + overlays (batch by related actions)
6. rotation editor + NPC chat + shop (last — most UI complexity)
7. docs + makefile + smoke test

Implementation todos

Risk notes

Out of scope (later)

• Removing or freezing TUI development — done: TUI play retired; no Tier 4+ work on crates/tui play path
• flatland-dev embedded play — retired; use gfx + dev gateway

Next: client foundation (specification)

After gfx sprite / world-sheet work (4.7.0), prioritize in order:

1. Extract crates/play-loop — single PlaySession for flatland3-gfx only
2. Gfx UX completeness — combat HUD, shop, rotation editor, remaining modals
3. Presentation pipeline — crates/presentation + YAML sprite_modes + admin validate
4. WASM — deferred (browser play not a goal)

Gate: Tier 4.7 exit in specification before 4.5b directional jump or new gameplay features.

Local play / testing: make dev-restart + make dev-play-gfx (dev gateway + worker stack) — not flatland-dev.

Out of scope (historical v1 notes)

• YAML-driven NPC/terrain sprite catalogs + content-admin art pipeline → moved to 4.7c in 29
• Authoritative server player yaw / rotate keys
• Extracting crates/play-loop → 4.7a in 29 (was deferred; gfx had local loop)
• Web/WASM build → 4.7d deferred

Foundation pass (2026-07-15) — primary client polish

Shipped on gfx/macroquad-client:

• UI toolkit: theme, list/tree/overlay helpers, input_router
• Smooth camera + client facing yaw + player sprite atlas (assets/gfx/player/hero.png)
• Hierarchical inventory browser (shared inventory_browser_lines / format_inventory_row)
• Interactive rotation editor overlay; reconnect loop; docs mark gfx as primary