settled-reach/docs/sprints/sprint-36/client.md

Sprint 36: Forge — Client Tasks

Goal: Close Phase 3 Atlas (unified nav chain, brand corps, content refinement) and establish Phase 4 foundations (bookmark system, location-culture resolution, character creation skeleton).

Branch: sprint-36/client Agents: Stig (dev), Tyre (arch), Hoshe (QA)

New Tickets

#	Title	Blocked by
#844	Unify star map and atlas into single implant/map chain	—
#618	CK3-style character creation screen	#614 (server)
#680	Location picker in character creation UI	#679 (server)
#722	Add --help flag to custom DB scripts	—
#724	Show client and server version on loading screen	—

Use tooling/db/ticket show <id> for full details.

Key Decisions

• decisions/architecture.md — D-191 (atlas scope, zoom hierarchy, implant/map chain), D-170 (HUD layer groups), D-169 (implant component library)
• decisions/scope.md — D-115 (character creation scoped to skills + bookmark), D-146 (character creation preview — tile-scale sprite), D-155 (cardinal rotation only), D-158 (frontal camera default), D-159 (11 body types)
• decisions/content.md — D-128 (culture implicit in starting location)

Notes

#844 — Unify star map and atlas into single implant/map chain

• Current state: client/ui/star_map.gd registers as implant/map/starchart and client/ui/implant/atlas_panel.gd registers as implant/map/atlas. They are two separate HudGroups apps with separate key bindings (M for starchart, A for atlas).
• D-191: the atlas is the star map extended downward — not a separate app. The unified chain should be a single implant/map app with internal level navigation. The star map (hop-ring view) becomes Level 0 of the atlas hierarchy.
• Approach: AtlasPanel already has a 4-level Level enum (SYSTEM_PICKER, ORBITAL_DIAGRAM, BODY_ENTRY, HEIGHTMAP_VIEWER). Extend it with a Level -1 or REACH_MAP that renders the star map view. Star map rendering logic can be lifted from star_map.gd into a method called by AtlasPanel._draw().
• StarMapRenderer registers itself with HudGroups — after unification, de-register it or make it a sub-component rather than an independent app. Don't break the implant/map/starchart path for existing callers until the unified path is confirmed working.
• client/ui/implant/atlas_viewer.gd and client/ui/implant/atlas_overlay_bar.gd are the heightmap layer — preserve these.

#618 — CK3-style character creation screen

• IMPORTANT: extend the EXISTING character creation screen (client/ui/character_creation.gd, client/scenes/character_creation.tscn) — do NOT create a separate screen.
• D-146: character creation preview is the tile-scale sprite at heavy zoom. The existing screen already implements this correctly. The CK3-style extension adds a skills tab and a bookmark selector to the existing TabContainer.
• D-115: creation is limited to skills + bookmark. No family/culture/religion sliders.
• The existing tab structure: Body, Head, Hair, Clothing, Accessories, Debug. Add two new tabs: "Skills" and "Bookmark". The Bookmark tab consumes the bookmark data from #614 (server). The skills tab is a stub for this sprint — display placeholder content until the skills system is implemented.
• Blocked by #614 until the bookmark data structure is available from the server. Coordinate with Tyre on what the server exposes.
• Game flow does not change: main_menu → character_select → character_creation → main.tscn. The creation_confirmed(descriptor) signal already carries CharacterVisualDescriptor — that type will need a bookmark field added.

#680 — Location picker in character creation UI

• Client side of the location/culture system. The player selects their starting location in the character creation screen — this feeds into the bookmark selection flow.
• Blocked by #679 (server). Once the server exposes a location-to-culture resolution endpoint, the client needs a picker UI that shows selectable starting locations and displays the resolved culture.
• Integrate into the character creation screen as part of the Bookmark tab (coordinate with #618). The location picker is a sub-component of the bookmark selector, not a standalone screen.
• The CharacterVisualDescriptor or a new CharacterProfile struct will need to carry the selected location/bookmark.

#722 — Add --help flag to custom DB scripts

• tooling/db/ scripts: ticket, sprint, decision, sqlite-query, sqlite-exec.
• These scripts already print usage on bad args. Wire --help as an alias to that same usage output.
• This is a tooling/DX improvement — no game code impact. Low priority, parallelizable with everything else.
• Note: ticket is assigned to client team but touches tooling/db/ — this is a tooling ticket, not client game code.

#724 — Show client and server version on loading screen

• client/ui/loading_screen.gd currently shows only a loading message. Add version display.
• Client version: read from project.yaml at the repo root (root version field, format 0.1.{sprint}). Use GDScript's FileAccess or a preload JSON export — choose the simplest approach that doesn't require a plugin.
• Server version: the bridge protocol already has PROTOCOL_VERSION (server/src/bridge/types.rs). The server can emit this in the initial handshake or a version ping. Alternatively, display it from the ObserverSnapshot if it carries a version field.
• The loading screen is client/ui/loading_screen.tscn — it is a simple overlay with a label. Add a second label below for version text.

Dependency Chain

#614 (server bookmark) → #618 (CK3 character creation)
#679 (server location-culture) → #680 (location picker)
#844 → standalone (no server dependency)
#722, #724 → standalone, parallel

PR Workflow

tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(client): sprint 36 — unified map chain, character creation foundations" \
  --description "body" \
  --base main --head sprint-36/client