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

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 28 — Client Briefing	Sprite layer compositor and character creation screen implementation	sprint	planning	28	client

Sprint 28: Character Visuals — Client Tasks

Goal: Move beyond placeholder art to final product candidate character visuals, from design specs through asset production and compositor implementation.

Branch: client Agents: Stig (dev), Tyre (arch), Hoshe (QA)

New Tickets

#	Title	Blocked by
#693	Sprite layer compositor	#684 (workshop), #686 (body type sprites)
#694	Character creation screen	#685 (wireframe), #693 (compositor)

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

Key Decisions

• decisions/architecture.md — D-134 (full character customisation: hair, clothing, colors at tile scale), D-146 (character creation preview: tile-scale sprite with heavy zoom — the compositor IS the preview renderer, no separate portrait system), D-043 (art direction: "functional warmth"), D-044 (visual hierarchy)
• decisions/content.md — D-147 (aesthetic taste as character personality trait — compositor reads layer choices, does not write to apartment generator)

Notes

Existing code to understand first

Before starting either ticket, read:

• client/scripts/rendering/entity_renderer.gd — the current entity sprite system. It creates one Sprite2D per entity, loads textures from client/assets/sprites/npc_generic_{direction}_64.png, applies self_modulate for D-033 relationship tinting, and handles 4-direction rotation. The compositor replaces the single-sprite model for the player character with a multi-layer node stack.
• client/scenes/character_select.tscn + client/ui/character_select.gd — the existing character archetype selection panel (two-card overlay, keyboard + mouse). The new character creation screen (#694) lives in the same flow, after archetype selection.
• client/scripts/constants.gd — TILE_SIZE, entity footprint constants (ENTITY_WIDTH=24, ENTITY_HEIGHT=32), color constants.
• client/scripts/autoloads/game_state.gd — player entity ID and state. The compositor will need to know the player entity to apply the correct layer stack during gameplay.

#693 — Sprite layer compositor

Blocked by: #684 (workshop spec) and #686 (body type sprites available as test input).

Wait for docs/design/compositor-api-spec.md (output of #684) before writing the compositor architecture. Do not design the layer API yourself — the workshop decides the layer ordering, color override struct, and Godot node architecture. This note describes what the compositor must accomplish, not how.

What the compositor must do:

• Accept a character definition (layer choices + color overrides) and render the composited character sprite in the correct layer order
• Support 8-direction rotation (or 4-direction if workshop spec reduces this) — swaps all layer textures simultaneously
• Apply color mesh recoloring per layer (color region ID → Color mapping) using the mesh regions defined in the visual spec
• Handle occlusion rules (e.g. helmet clothing hides hair layer)
• Expose a node or API that EntityRenderer can use for the player character in gameplay
• Expose the same node/API for use in the character creation screen preview pane (#694)

Integration point with EntityRenderer: The current EntityRenderer creates a bare Sprite2D for each entity. For the player character, the compositor replaces this with a layered Node2D subtree. The cleanest integration: compositor exports a Node2D root that EntityRenderer parents under the entity position node, same as it would a Sprite2D. EntityRenderer detects entity_id == GameState.player_entity_id and uses the compositor node instead of a single sprite.

Color mesh recoloring approach in Godot: Godot 4 does not have a built-in color mesh system. Options:

1. Per-layer self_modulate (works only for solid single-color regions — too limited)
2. Shader-based recoloring: pass a from_color and to_color uniform, replace pixels matching from_color within a threshold. This is the standard tile-game approach.
3. Multiple texture layers per sprite (premultiplied masks).

Wait for workshop spec to select the approach. If the workshop spec is silent on implementation, use option 2 (shader-based) — it is the most flexible and supports arbitrary palette swaps without new textures.

File locations:

• Compositor script: client/scripts/rendering/character_compositor.gd
• Compositor scene (if needed as a PackedScene): client/scenes/character_compositor.tscn
• Shader (if approach 2): client/shaders/character_recolor.gdshader

#694 — Character creation screen

Blocked by: #685 (wireframe design) and #693 (compositor for the preview pane).

This is the full implementation of the wireframe produced by #685. Do not start until docs/design/character-creation-screen-wireframe.md exists and is approved.

What the screen must deliver:

• Layer selection controls for each character layer type (body, face, hair, clothing, accessories, scars, tattoos)
• Live preview pane showing the composited character at heavy zoom (tile-scale sprite, zoomed in — same sprite that appears in gameplay)
• Color picker or palette selector per colorable region
• Randomise button (randomises all layer choices and color selections)
• Confirm / Back navigation
• Full keyboard + mouse support (matching existing character_select.gd pattern — left/right/tab navigation, Enter to confirm, Esc to cancel)

Integration into game flow: The existing flow: main_menu.tscn → character_select.tscn (archetype card). The new flow inserts character creation after archetype selection (or replaces the archetype select, depending on how #684 resolves the bookmark/archetype question). Wire the scene transition from the existing entry point.

Preview pane — D-146: The preview is the gameplay sprite, zoomed. The compositor (#693) provides this. The preview pane is a SubViewport or a simple Node2D with the compositor node, scaled up. Heavy zoom means: render the 32×32 gameplay sprite at 4× or 6× scale so individual pixels are visible and character detail reads clearly. Rimworld uses approximately 4×–6× zoom on its character customisation screen.

Data flow:

• Character creation screen maintains a CharacterDefinition (layer choices + color overrides)
• On any change, pushes the updated definition to the compositor — compositor re-renders the preview in real time
• On confirmation, stores CharacterDefinition to GameState (or session state) for use by the game on load
• The CharacterDefinition structure is defined by the compositor API spec (from #684)

File locations:

• Scene: client/scenes/character_creation.tscn
• Script: client/ui/character_creation.gd

Dependency Chain

#684 (workshop) ──┬──> #693 (compositor)
#686 (body sprites) ──┘         └──> #694 (creation screen)
                                      ↑
#685 (wireframe) ────────────────────┘

Both #693 and #685 must be complete before #694 can start. #693 and #685 can run in parallel.

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(client): character sprite compositor and creation screen" --description "body" --base main --head client