settled-reach/docs/design/character-creation-screen-wireframe.md

title, description, type, status, sprint, ticket, created

title	description	type	status	sprint	ticket	created
Character Creation Screen Wireframe	UI layout specification for the character creation screen — wireframe deliverable for ticket #685	design	active	28	685	2026-03-19

Character Creation Screen Wireframe

Ticket: #685 Designed by: Jeroen (project lead) Tool: Frame0 Downstream: #694 (client: character creation screen), #705 (character editor Godot tool)

---

Wireframe Files

All source JSON and exported PNGs in docs/design/wireframes/character-creation/:

File	Description
main-layout.json/.png	Body tab (default view on open)
head-tab.json/.png	Head template + eyebrows tab
hair-tab.json/.png	Hair style + facial hair tab
clothing-tab.json/.png	Clothing slot selector tab
accessories-tab.json/.png	Accessories slot selector tab
color-picker.json/.png	Color picker modal (opens on swatch click)

---

Screen Layout

Preview pane (left, ~60% of screen)

• Live 3D compositor in SubViewport (D-149, D-146)
• Default camera: frontal (-5°) for editor (D-158), toggle to dramatic (-30°)
• Default facing: South (face-forward)
• [Q] / [E] rotate buttons — incremental cardinal rotation (D-155)
• Always LOD Tier 0, no degradation

Tab panel (right, ~35% of screen)

5 tabs: Body, Head, Hair, Clothing, Accessories

Each tab follows the same layout pattern:

1. Search bar (top, fixed) — scoped to current tab contents
2. Scrollable content grid (middle) — item/option thumbnails
3. Color dock (bottom, fixed, non-scrolling) — context-sensitive color controls

Footer (full width, bottom)

• [ESC] Back — return to main menu
• [R] Randomise — randomize all slots
• [ENTER] Start — confirm character and begin game

---

Tab Contents

Body

• Skin tone dock (bottom): 9 preset swatches (separate from the D-165 clothing palette)
• Body type grid: 11 options (D-159) organized as:
  • Female row: Thin, Average, Muscular, Heavy, Teen
  • Male row: Thin, Average, Muscular, Heavy, Teen
  • Child (unlabeled row — no gendered framing)

Head

• Head template grid: Trellis-generated unique heads (D-163), scrollable. Starts with 4 Quaternius starters.
• Skin tone dock (bottom): same 9 swatches as Body tab (shared state)

Hair

• Hair style grid: Short A, Short B, Medium A, Medium B, Long A, Bald (and more via scroll)
• Facial hair selector: None, Stubble, Beard, Moustache
• Eyebrow selector: Regular, Female, Teen, Thick (matches Source tier asset keys)
• Hair color dock (bottom): Hair primary + Hair highlight (auto) + Eyebrow tint (auto from hair, independent override) + Facial hair tint (auto from hair, independent override — single tint for both beard and moustache)

Clothing

• Slot selector (fixed): Torso, Legs, Feet, Hands — click to filter the grid below
• Item grid: Shows items for the selected slot (Coveralls, Jacket, Shirt, etc.)
• Item color dock (bottom): Primary / Secondary / Accent swatches. Secondary and Accent auto-derive if unset.

Accessories

• Slot selector (fixed): Hat, Goggles, Mask, Backpack, Belt, Wrist L, Wrist R, Earring L, Earring R, Necklace
• Item grid: Shows items for the selected slot
• Item color dock (bottom): Primary / Secondary swatches

---

Color Picker Modal

Opens when any color swatch in a dock is clicked. Overlays the tab panel.

• 54-swatch palette (6 rows × 9 columns, D-165):
  1. Reds (H=0° S=35%)
  2. Greens (H=150° S=28%)
  3. Blues (H=215° S=35%)
  4. Purples (H=275° S=28%)
  5. Browns (H=28° S=35%)
  6. Neutral grays (#000000 → #ffffff, even steps)
• Hex input field with Apply button for custom colors
• Recent custom colors: 9 slots, persisted at game (save) level
• Cancel / OK buttons

---

Keyboard Navigation

Full keyboard/controller support required (existing character_select.gd is keyboard-friendly):

• Tab / Shift+Tab: cycle between tabs
• Arrow keys: navigate within grids
• Enter: select item / confirm
• Q / E: rotate character in preview
• R: randomize
• ESC: back to main menu

---

Design Decisions Referenced

Decision	Summary
D-146	Tile-scale preview with heavy zoom (compatible with 3D via SubViewport)
D-149	3D characters rendered live
D-153	Player not visually distinct from NPCs
D-155	Cardinal rotation only in editor
D-157	Game start = alarm clock / fade from black (editor is separate context)
D-158	Frontal camera default for editor
D-159	11 body types (5 types × 2 genders + 1 child)
D-163	Trellis-generated unique heads
D-160	18 body segments (clothing hides covered segments)
D-165	Color picker palette (5×9 muted hues + 1×9 neutral gray — clothing colors only, not skin tones)

---

Notes for Implementation (#694)

• Held items (held_l, held_r) are not in the character creator — those are play-time decisions. Wrist slots replace them.
• The color picker modal should preview changes live on the 3D model before OK is pressed.
• Search filters items by name within the active tab only.
• The skin tone dock appears on both Body and Head tabs and shares state — changing it on one updates the other.
• Compositor coverage: Changing body type or clothing in the editor must update segment visibility on the CharacterCompositor. Clothing items hide the body segments they cover (e.g. torso clothing hides seg_torso). The preview must reflect this in real time — switching from a tank top to a jacket should hide the arm segments underneath.
• Eyebrow tint and facial hair tint are independent from hair color. Default: auto-derive from hair primary. Player can override to any color via the color picker.
• Earring L/R and Necklace are jewelry accessory slots — they use accessory_primary / accessory_secondary color regions like other accessories.