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

```bash
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
```