From 8e4c0bf9578793e1cb92c1c1980c841a1a6a953c Mon Sep 17 00:00:00 2001 From: Phillip Tarrant Date: Sat, 11 Jul 2026 10:27:08 -0500 Subject: [PATCH] docs(plan): Title screen (M3) + unified version implementation plan Co-Authored-By: Claude Opus 4.8 (1M context) --- .../plans/2026-07-11-title-screen.md | 967 ++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-11-title-screen.md diff --git a/docs/superpowers/plans/2026-07-11-title-screen.md b/docs/superpowers/plans/2026-07-11-title-screen.md new file mode 100644 index 0000000..85d20da --- /dev/null +++ b/docs/superpowers/plans/2026-07-11-title-screen.md @@ -0,0 +1,967 @@ +# Title screen (M3) + unified version — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build the editor-first Title screen (entry point) from the mock, and stand up a single `/VERSION` source of truth shared by the client and API. + +**Architecture:** Editor-first UI scene (ADR 0001): layout in `.tscn`, script does on-load work only. A root `/VERSION` file feeds the API (read at startup) and the client (synced into `project.godot`, read via `ProjectSettings`). Distinct title text and atmosphere reuse the theme/Palette system. + +**Tech Stack:** Godot 4.7 / GDScript / GUT; Python / FastAPI / pytest. Reuses the M3 Theme, `Palette`, `VignetteOverlay`, and the `MainWindowShell` scene (New Game target). + +## Global Constraints + +- **Godot 4.7 / GDScript; Python / FastAPI.** No C#. +- **`Palette` is the only home for hex** — no colour literal in any script, `.tscn`, or shader (shaders take `Palette` values as uniforms set in code, the `DarkBay` precedent). +- **Theme styling via `ThemeKeys` constants**; new title text styles are theme variations built from `Palette` in `build_game_theme.gd`, then the `.tres` is **regenerated** (never hand-edited): `godot --headless -s res://scripts/theme/build_game_theme.gd`. +- **Editor-first (ADR 0001):** author the scene tree in `.tscn`; the script only binds/wires. New `class_name` scripts resolve only after `godot --headless --import`, which `./run_tests.sh` runs first. +- **Scene-root sizing:** the `.tscn` root gets a fixed size (1920×1080) but **no full-rect anchors on the root**; the script keeps `size = get_viewport_rect().size` + `size_changed` (M3-a collapse rule). +- **Version value now:** `0.01-alpha`. Client footer renders `v0.01-alpha · BUILT IN GODOT 4.7 · © 2026`. +- **GUT `.gutconfig`** promotes any engine error/warning to a failure — load defensively, keep output pristine. +- **§2:** presentation/state, code-owned. No AI text on this screen. + +--- + +### Task 1: Root `/VERSION` + API reads it (+ `/version` endpoint) + +**Files:** +- Create: `VERSION` (repo root) +- Create: `api/app/version.py` +- Modify: `api/app/main.py` +- Test: `api/tests/test_version.py` + +**Interfaces:** +- Consumes: nothing. +- Produces: `api/app/version.py` — `get_version() -> str` (reads `/VERSION`, cached) and module constant `VERSION: str`. `GET /version` → `{"version": VERSION}`. `FastAPI(version=VERSION)`. + +- [ ] **Step 1: Create the source-of-truth file** + +Create `VERSION` (repo root) with exactly one line: + +``` +0.01-alpha +``` + +- [ ] **Step 2: Write the failing test** + +Create `api/tests/test_version.py`: + +```python +from pathlib import Path + +from fastapi.testclient import TestClient + +from app.main import app +from app.version import VERSION, get_version + +client = TestClient(app) +ROOT_VERSION = Path(__file__).resolve().parents[2] / "VERSION" + + +def test_get_version_matches_file(): + assert ROOT_VERSION.is_file() + assert get_version() == ROOT_VERSION.read_text(encoding="utf-8").strip() + + +def test_app_version_matches(): + assert app.version == VERSION == get_version() + + +def test_version_endpoint(): + assert client.get("/version").json() == {"version": VERSION} +``` + +- [ ] **Step 3: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_version.py -q` +Expected: FAIL — `ModuleNotFoundError: No module named 'app.version'`. + +- [ ] **Step 4: Write `version.py`** + +Create `api/app/version.py`: + +```python +"""Single source of truth for the app version (charter §4: client and API share +one version). Reads the repo-root /VERSION file — the ONLY place a human edits the +version. Mirrors canon_log._schema_dir's env-override + walk-up so it resolves in +a local checkout and (once /VERSION is bundled) an image alike. +""" +import os +from functools import lru_cache +from pathlib import Path + +LAST_RESORT = "0.0.0-dev" + + +def _version_file() -> Path | None: + env = os.environ.get("COC_VERSION_FILE") + if env: + return Path(env) + here = Path(__file__).resolve() + for parent in here.parents: + candidate = parent / "VERSION" + if candidate.is_file(): + return candidate + return None + + +@lru_cache(maxsize=1) +def get_version() -> str: + path = _version_file() + if path is None or not path.is_file(): + return LAST_RESORT + return path.read_text(encoding="utf-8").strip() or LAST_RESORT + + +VERSION = get_version() +``` + +- [ ] **Step 5: Wire it into `main.py`** + +In `api/app/main.py`, add the import near the other `from .` imports: + +```python +from .version import VERSION +``` + +Change the app construction from `app = FastAPI(title="coc-rpg proxy", version="0.0.1")` to: + +```python +app = FastAPI(title="coc-rpg proxy", version=VERSION) +``` + +Add the endpoint (next to the existing `/health` route): + +```python +@app.get("/version") +def version() -> dict: + return {"version": VERSION} +``` + +- [ ] **Step 6: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_version.py -q` +Expected: PASS — 3 passed. + +- [ ] **Step 7: Commit** + +```bash +git add VERSION api/app/version.py api/app/main.py api/tests/test_version.py +git commit -m "feat(api): /VERSION single source read at startup + GET /version" +``` + +--- + +### Task 2: Client version plumbing (`Version` helper + sync script) + +**Files:** +- Create: `scripts/sync-version` +- Modify: `client/project.godot` (via the script) +- Create: `client/scripts/util/version.gd` +- Test: `client/tests/unit/test_version.gd` + +**Interfaces:** +- Consumes: root `/VERSION` (Task 1). +- Produces: `class_name Version` — `func string() -> String` (reads `application/config/version`, `LAST_RESORT` if empty) and `func footer() -> String`. `project.godot` now has `application/config/version="0.01-alpha"`. + +- [ ] **Step 1: Write the sync script** + +Create `scripts/sync-version` (make it executable): + +```bash +#!/usr/bin/env bash +# Sync the single source of truth (/VERSION) into the Godot client's project.godot +# (application/config/version). Run after bumping /VERSION. +set -euo pipefail +root="$(cd "$(dirname "$0")/.." && pwd)" +version="$(tr -d '[:space:]' < "$root/VERSION")" +proj="$root/client/project.godot" +if grep -q '^config/version=' "$proj"; then + sed -i "s|^config/version=.*|config/version=\"$version\"|" "$proj" +else + sed -i "s|^\(config/name=.*\)|\1\nconfig/version=\"$version\"|" "$proj" +fi +echo "synced client config/version = \"$version\"" +``` + +Then: `chmod +x scripts/sync-version` + +- [ ] **Step 2: Run the sync script** + +Run: `./scripts/sync-version` +Expected: prints `synced client config/version = "0.01-alpha"`. Verify `client/project.godot`'s `[application]` block now contains `config/version="0.01-alpha"` (run `grep 'config/version' client/project.godot`). + +- [ ] **Step 3: Write the failing test** + +Create `client/tests/unit/test_version.gd`: + +```gdscript +extends "res://addons/gut/test.gd" + + +func test_string_matches_project_setting(): + var expected := str(ProjectSettings.get_setting("application/config/version", "")) + assert_ne(expected, "", "project.godot must carry application/config/version (run scripts/sync-version)") + assert_eq(Version.new().string(), expected) + + +func test_footer_contains_version_and_engine(): + var v := Version.new() + assert_string_contains(v.footer(), v.string()) + assert_string_contains(v.footer(), "BUILT IN GODOT 4.7") +``` + +- [ ] **Step 4: Run test to verify it fails** + +Run: `cd client && ./run_tests.sh -gselect=test_version.gd` +Expected: FAIL — `Version` is an unknown identifier. + +- [ ] **Step 5: Write the `Version` helper** + +Create `client/scripts/util/version.gd`: + +```gdscript +class_name Version +extends RefCounted +## The client's view of the single source of truth (/VERSION, charter §4). The +## value is baked into project.godot's application/config/version by +## scripts/sync-version on each bump; read it via ProjectSettings so an exported +## build (which has no repo-root /VERSION) still knows its own version. + +const SETTING := "application/config/version" +const LAST_RESORT := "0.0.0-dev" + + +func string() -> String: + var v := str(ProjectSettings.get_setting(SETTING, "")) + return v if v != "" else LAST_RESORT + + +func footer() -> String: + return "v%s · BUILT IN GODOT 4.7 · © 2026" % string() +``` + +- [ ] **Step 6: Run test to verify it passes** + +Run: `cd client && ./run_tests.sh -gselect=test_version.gd` +Expected: PASS — 2 tests. + +- [ ] **Step 7: Commit** + +```bash +git add scripts/sync-version client/project.godot client/scripts/util/version.gd client/scripts/util/version.gd.uid client/tests/unit/test_version.gd client/tests/unit/test_version.gd.uid +git commit -m "feat(client): Version helper + sync-version script; project.godot config/version" +``` + +--- + +### Task 3: Theme title text variations (`TitleLogo`, `TitleKicker`) + +**Files:** +- Modify: `client/scripts/theme/theme_keys.gd` +- Modify: `client/scripts/theme/build_game_theme.gd` +- Modify: `client/assets/theme/game_theme.tres` (regenerated) +- Test: `client/tests/unit/test_title_theme.gd` + +**Interfaces:** +- Consumes: `Palette` (`CREAM`, `GOLD`). +- Produces: `ThemeKeys.TITLE_LOGO`, `ThemeKeys.TITLE_KICKER` (Label variations). `TitleLogo` = serif 116px `CREAM`; `TitleKicker` = mono 13px `GOLD`. + +- [ ] **Step 1: Write the failing test** + +Create `client/tests/unit/test_title_theme.gd`: + +```gdscript +extends "res://addons/gut/test.gd" + +const Builder = preload("res://scripts/theme/build_game_theme.gd") + + +func test_title_variations_built(): + var t: Theme = Builder.build_theme() + assert_eq(t.get_font_size(&"font_size", ThemeKeys.TITLE_LOGO), 116) + assert_eq(t.get_color(&"font_color", ThemeKeys.TITLE_LOGO), Palette.CREAM) + assert_eq(t.get_color(&"font_color", ThemeKeys.TITLE_KICKER), Palette.GOLD) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd client && ./run_tests.sh -gselect=test_title_theme.gd` +Expected: FAIL — `ThemeKeys.TITLE_LOGO` is not defined (parse error). + +- [ ] **Step 3: Add the ThemeKeys constants** + +In `client/scripts/theme/theme_keys.gd`, alongside the font-role consts `HEADING`/`ACCENT`/`MONO` (these are Label font-roles kept OUT of `ALL`, so do NOT add the new ones to `ALL`): + +```gdscript +const TITLE_LOGO := &"TitleLogo" +const TITLE_KICKER := &"TitleKicker" +``` + +- [ ] **Step 4: Build the variations** + +In `client/scripts/theme/build_game_theme.gd`, add a call inside `build_theme()` right after `_fonts(theme)`: + +```gdscript + _title_type(theme) +``` + +And define the function (place it after `_fonts`): + +```gdscript +static func _title_type(theme: Theme) -> void: + # Title-screen display type (mock Title Screen): the big serif logo + the mono + # kicker above it. Label font-role variations (font/size/colour), the same + # shape as Heading/Accent/Mono. + theme.set_type_variation(ThemeKeys.TITLE_LOGO, "Label") + theme.set_font(&"font", ThemeKeys.TITLE_LOGO, load(SERIF)) + theme.set_font_size(&"font_size", ThemeKeys.TITLE_LOGO, 116) + theme.set_color(&"font_color", ThemeKeys.TITLE_LOGO, Palette.CREAM) + theme.set_type_variation(ThemeKeys.TITLE_KICKER, "Label") + theme.set_font(&"font", ThemeKeys.TITLE_KICKER, load(MONO)) + theme.set_font_size(&"font_size", ThemeKeys.TITLE_KICKER, 13) + theme.set_color(&"font_color", ThemeKeys.TITLE_KICKER, Palette.GOLD) +``` + +- [ ] **Step 5: Regenerate the committed theme** + +Run: `cd client && godot --headless -s res://scripts/theme/build_game_theme.gd` +Expected: prints `wrote res://assets/theme/game_theme.tres`. + +- [ ] **Step 6: Run tests to verify they pass** + +Run: `cd client && ./run_tests.sh -gselect=test_title_theme.gd` → PASS. +Then: `cd client && ./run_tests.sh -gselect=test_theme_resource.gd` → still PASS (no drift regression). + +- [ ] **Step 7: Commit** + +```bash +git add client/scripts/theme/theme_keys.gd client/scripts/theme/build_game_theme.gd client/assets/theme/game_theme.tres client/tests/unit/test_title_theme.gd client/tests/unit/test_title_theme.gd.uid +git commit -m "feat(theme): TitleLogo + TitleKicker display variations" +``` + +--- + +### Task 4: TitleScreen core scene + script + boot + +**Files:** +- Create: `client/scripts/ui/title/title_screen.gd` +- Create: `client/scenes/title/TitleScreen.tscn` +- Modify: `client/project.godot` (set `run/main_scene`) +- Test: `client/tests/unit/test_title_screen.gd` + +**Interfaces:** +- Consumes: `Version` (Task 2), `ThemeKeys.TITLE_LOGO/TITLE_KICKER` (Task 3), `Palette`, `VignetteOverlay` scene, `MainWindowShell` scene. +- Produces: `class_name TitleScreen extends Control` — `signal menu_activated(id: StringName)`; `var _rows: Array`; `var _sel: int`; `func _move(delta)`, `func _activate(i)`. The atmosphere (bg shader/glow/embers) is added in Task 5; this task builds the composition + interaction. + +- [ ] **Step 1: Write the failing test** + +Create `client/tests/unit/test_title_screen.gd`: + +```gdscript +extends "res://addons/gut/test.gd" + +const SCENE := "res://scenes/title/TitleScreen.tscn" + + +func _title() -> TitleScreen: + var t = load(SCENE).instantiate() + add_child_autofree(t) # runs _ready() + return t + + +func _index_of(t: TitleScreen, action: StringName) -> int: + for i in range(t._rows.size()): + if t._rows[i].get_meta("action") == action: + return i + return -1 + + +func test_six_menu_rows_each_with_an_action(): + var t := _title() + assert_eq(t._rows.size(), 6) + for row in t._rows: + assert_true(row.has_meta("action")) + + +func test_down_moves_selection(): + var t := _title() + assert_eq(t._sel, 0) + t._move(1) + assert_eq(t._sel, 1) + + +func test_up_from_first_wraps_to_last(): + var t := _title() + t._move(-1) + assert_eq(t._sel, t._rows.size() - 1) + + +func test_new_game_and_quit_emit_their_action(): + var t := _title() + # Isolate the signal seam so the test does not actually change scene / quit. + t.menu_activated.disconnect(t._on_menu_activated) + watch_signals(t) + t._activate(_index_of(t, &"new_game")) + assert_signal_emitted_with_parameters(t, "menu_activated", [&"new_game"]) + t._activate(_index_of(t, &"quit")) + assert_signal_emitted_with_parameters(t, "menu_activated", [&"quit"]) + + +func test_footer_shows_version(): + var t := _title() + assert_string_contains(t._footer_left.text, Version.new().string()) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd client && ./run_tests.sh -gselect=test_title_screen.gd` +Expected: FAIL — cannot load `TitleScreen.tscn` / `TitleScreen` unknown. + +- [ ] **Step 3: Write the script** + +Create `client/scripts/ui/title/title_screen.gd`: + +```gdscript +class_name TitleScreen +extends Control +## The entry-point screen (mock Title Screen). Editor-first (ADR 0001): the whole +## composition lives in TitleScreen.tscn; this script drives selection, input, and +## dispatches the menu. §2: presentation/state — no AI here (the DM enters at the +## shell). The atmosphere (bg shader, glow, embers) is layered on in a later task. + +signal menu_activated(id: StringName) + +const SHELL := "res://scenes/shell/MainWindowShell.tscn" + +var _rows: Array = [] +var _sel: int = 0 + +@onready var _menu: VBoxContainer = $Content/Menu +@onready var _footer_left: Label = $FooterLeft + + +func _ready() -> void: + # Root Control run via F6 is not sized by full-rect anchors — size explicitly. + _fit_to_viewport() + get_viewport().size_changed.connect(_fit_to_viewport) + + _rows = [] + for row in _menu.get_children(): + if row.has_meta("action"): + _rows.append(row) + (row.get_node("Marker") as Label).add_theme_color_override("font_color", Palette.GOLD) + _wire_row_mouse() + + _footer_left.text = Version.new().footer() + menu_activated.connect(_on_menu_activated) + _update_selection() + + +func _fit_to_viewport() -> void: + size = get_viewport_rect().size + + +func _wire_row_mouse() -> void: + for i in range(_rows.size()): + var idx := i # fresh per-iteration binding for the closures + var row: Control = _rows[idx] + row.mouse_entered.connect(func(): + _sel = idx + _update_selection()) + row.gui_input.connect(func(e: InputEvent): + if e is InputEventMouseButton and e.pressed and e.button_index == MOUSE_BUTTON_LEFT: + _activate(idx)) + + +func _unhandled_input(event: InputEvent) -> void: + if event.is_action_pressed("ui_down"): + _move(1) + elif event.is_action_pressed("ui_up"): + _move(-1) + elif event.is_action_pressed("ui_accept"): + _activate(_sel) + + +func _move(delta: int) -> void: + if _rows.is_empty(): + return + _sel = wrapi(_sel + delta, 0, _rows.size()) + _update_selection() + + +func _activate(i: int) -> void: + if i < 0 or i >= _rows.size(): + return + menu_activated.emit(_rows[i].get_meta("action")) + + +func _on_menu_activated(id: StringName) -> void: + match id: + &"new_game": + get_tree().change_scene_to_file(SHELL) + &"quit": + get_tree().quit() + _: + pass # inert placeholder — the screen lands in a later milestone + + +func _update_selection() -> void: + for i in range(_rows.size()): + var row: Control = _rows[i] + var selected := i == _sel + (row.get_node("Marker") as Label).modulate.a = 1.0 if selected else 0.0 + var label := row.get_node("Body/Label") as Label + label.add_theme_color_override("font_color", Palette.CREAM_BRIGHT if selected else Palette.MUTED_MONO) +``` + +- [ ] **Step 4: Write the scene** + +Create `client/scenes/title/TitleScreen.tscn` (root has a fixed size but **no full-rect anchors**; menu rows carry an `action` meta and `mouse_filter = 0` so they receive hover/click): + +``` +[gd_scene load_steps=4 format=3] + +[ext_resource type="Script" path="res://scripts/ui/title/title_screen.gd" id="1"] +[ext_resource type="Theme" path="res://assets/theme/game_theme.tres" id="2"] +[ext_resource type="PackedScene" path="res://scenes/theme/surfaces/VignetteOverlay.tscn" id="3"] + +[node name="TitleScreen" type="Control"] +layout_mode = 3 +anchors_preset = 0 +offset_right = 1920.0 +offset_bottom = 1080.0 +theme = ExtResource("2") +script = ExtResource("1") + +[node name="Background" type="ColorRect" parent="."] +layout_mode = 1 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +color = Color(0.039216, 0.031373, 0.023529, 1) + +[node name="KeyArt" type="Label" parent="."] +layout_mode = 1 +anchors_preset = 6 +anchor_left = 1.0 +anchor_top = 0.5 +anchor_right = 1.0 +anchor_bottom = 0.5 +offset_left = -520.0 +offset_top = -20.0 +offset_right = -120.0 +offset_bottom = 20.0 +grow_horizontal = 0 +grow_vertical = 2 +theme_type_variation = &"Mono" +text = "KEY ART DROPS IN HERE" +horizontal_alignment = 1 + +[node name="Vignette" parent="." instance=ExtResource("3")] +layout_mode = 1 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +mouse_filter = 2 + +[node name="Content" type="VBoxContainer" parent="."] +layout_mode = 1 +anchors_preset = 4 +anchor_top = 0.5 +anchor_bottom = 0.5 +offset_left = 120.0 +offset_top = -260.0 +offset_right = 900.0 +offset_bottom = 260.0 +grow_vertical = 2 +theme_override_constants/separation = 10 + +[node name="Kicker" type="Label" parent="Content"] +layout_mode = 2 +theme_type_variation = &"TitleKicker" +text = "A DARK FANTASY RPG" + +[node name="Logo" type="Label" parent="Content"] +layout_mode = 2 +theme_type_variation = &"TitleLogo" +text = "CODE OF +CONQUEST" + +[node name="Rule" type="ColorRect" parent="Content"] +custom_minimum_size = Vector2(220, 2) +layout_mode = 2 +color = Color(0.662745, 0.517647, 0.247059, 1) + +[node name="Tagline" type="Label" parent="Content"] +layout_mode = 2 +theme_type_variation = &"Accent" +text = "The world has real problems, and it does not care about you." + +[node name="Menu" type="VBoxContainer" parent="Content"] +layout_mode = 2 +theme_override_constants/separation = 5 + +[node name="NewGame" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"new_game" + +[node name="Marker" type="Label" parent="Content/Menu/NewGame"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/NewGame"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/NewGame/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "New Game" + +[node name="Continue" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"continue" + +[node name="Marker" type="Label" parent="Content/Menu/Continue"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/Continue"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/Continue/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "Continue" + +[node name="Sub" type="Label" parent="Content/Menu/Continue/Body"] +layout_mode = 2 +theme_type_variation = &"Mono" +text = "CHAPTER II · VEXCCA · 14:22:07" + +[node name="LoadGame" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"load_game" + +[node name="Marker" type="Label" parent="Content/Menu/LoadGame"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/LoadGame"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/LoadGame/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "Load Game" + +[node name="Settings" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"settings" + +[node name="Marker" type="Label" parent="Content/Menu/Settings"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/Settings"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/Settings/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "Settings" + +[node name="Credits" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"credits" + +[node name="Marker" type="Label" parent="Content/Menu/Credits"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/Credits"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/Credits/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "Credits" + +[node name="Quit" type="HBoxContainer" parent="Content/Menu"] +layout_mode = 2 +mouse_filter = 0 +theme_override_constants/separation = 16 +metadata/action = &"quit" + +[node name="Marker" type="Label" parent="Content/Menu/Quit"] +layout_mode = 2 +theme_override_font_sizes/font_size = 15 +text = "◆" + +[node name="Body" type="VBoxContainer" parent="Content/Menu/Quit"] +layout_mode = 2 + +[node name="Label" type="Label" parent="Content/Menu/Quit/Body"] +layout_mode = 2 +theme_override_font_sizes/font_size = 30 +text = "Quit" + +[node name="FooterLeft" type="Label" parent="."] +layout_mode = 1 +anchors_preset = 2 +anchor_top = 1.0 +anchor_bottom = 1.0 +offset_left = 120.0 +offset_top = -60.0 +offset_right = 700.0 +offset_bottom = -32.0 +grow_vertical = 0 +theme_type_variation = &"Mono" +text = "v0.01-alpha · BUILT IN GODOT 4.7 · © 2026" + +[node name="FooterRight" type="Label" parent="."] +layout_mode = 1 +anchors_preset = 3 +anchor_left = 1.0 +anchor_top = 1.0 +anchor_right = 1.0 +anchor_bottom = 1.0 +offset_left = -520.0 +offset_top = -60.0 +offset_right = -120.0 +offset_bottom = -32.0 +grow_horizontal = 0 +grow_vertical = 0 +theme_type_variation = &"Mono" +text = "[ ↑ ↓ ] CHOOSE [ ↵ ] ENTER" +horizontal_alignment = 2 +``` + +Note the two `Color(...)` literals in the `.tscn` (`Background` fallback + `Rule`) are the stage-black and gold Palette values; they are the one allowed spot (an authored `ColorRect.color` has no theme-variation equivalent) — they equal `Palette.STAGE_1` / `Palette.GOLD` and the real background is the Palette-driven shader added in Task 5. If a reviewer objects, the alternative is setting them in `_ready` from `Palette` (loses editor preview). + +- [ ] **Step 5: Set the boot scene** + +In `client/project.godot`, under `[application]`, add (or set): + +``` +run/main_scene="res://scenes/title/TitleScreen.tscn" +``` + +- [ ] **Step 6: Run test to verify it passes** + +Run: `cd client && ./run_tests.sh -gselect=test_title_screen.gd` +Expected: PASS — 5 tests. + +- [ ] **Step 7: Run the full suite** + +Run: `cd client && ./run_tests.sh` +Expected: PASS — all prior tests plus the new title tests, 0 failing. + +- [ ] **Step 8: Commit** + +```bash +git add client/scripts/ui/title/title_screen.gd client/scripts/ui/title/title_screen.gd.uid client/scenes/title/TitleScreen.tscn client/project.godot client/tests/unit/test_title_screen.gd client/tests/unit/test_title_screen.gd.uid +git commit -m "feat(title): TitleScreen composition, menu + selection, boot scene" +``` + +--- + +### Task 5: Atmosphere — warm background, glow pulse, embers + +**Files:** +- Modify: `client/scripts/theme/palette.gd` (warm tokens) +- Create: `client/assets/theme/shaders/title_background.gdshader` +- Modify: `client/scenes/title/TitleScreen.tscn` (add `Glow` + `Embers` nodes) +- Modify: `client/scripts/ui/title/title_screen.gd` (configure bg/glow/embers in `_ready`) + +**Interfaces:** +- Consumes: `Palette` (new `TITLE_WARM`, `TITLE_MID`, existing `STAGE_1`, `GOLD_BRIGHT`, `BLOOD`). +- Produces: no new public API. Visual only — verified by the F6 gate (Task 6), not by a unit test. + +- [ ] **Step 1: Add warm Palette tokens** + +In `client/scripts/theme/palette.gd`, after the dark-background block: + +```gdscript +# --- Title-screen ambiance (warm radial background) --- +const TITLE_WARM := Color("2a2018") # radial centre +const TITLE_MID := Color("160f0a") # radial midpoint (STAGE_1 is the edge) +``` + +- [ ] **Step 2: Write the background shader** + +Create `client/assets/theme/shaders/title_background.gdshader`: + +```glsl +shader_type canvas_item; +// Warm radial for the Title screen (mock: radial-gradient warm centre -> near +// black edge, centred at 70% 20%). Colours are Palette uniforms set by the title +// script (the DarkBay precedent), so no hex lives in the shader. +uniform vec4 warm : source_color; +uniform vec4 mid : source_color; +uniform vec4 edge : source_color; +uniform vec2 center = vec2(0.7, 0.2); + +void fragment() { + float d = distance(UV, center); + vec3 c = mix(warm.rgb, mid.rgb, clamp(d / 0.45, 0.0, 1.0)); + c = mix(c, edge.rgb, clamp((d - 0.45) / 0.55, 0.0, 1.0)); + COLOR = vec4(c, 1.0); +} +``` + +- [ ] **Step 3: Add the Glow + Embers nodes to the scene** + +In `client/scenes/title/TitleScreen.tscn`, add these two nodes as children of the root (after `Background`, before `Vignette` so the vignette sits over them). Insert into the node list: + +``` +[node name="Glow" type="ColorRect" parent="."] +layout_mode = 1 +anchors_preset = 12 +anchor_top = 1.0 +anchor_right = 1.0 +anchor_bottom = 1.0 +offset_top = -420.0 +mouse_filter = 2 +color = Color(0.560784, 0.227451, 0.203922, 0.22) + +[node name="Embers" type="GPUParticles2D" parent="."] +position = Vector2(960, 1080) +amount = 24 +lifetime = 9.0 +preprocess = 4.0 +``` + +(The `Glow` colour is `Palette.BLOOD` at low alpha — a warm member of the fire glow; its pulse is driven in code. `Embers` gets its process material in code so the colour comes from `Palette`.) + +- [ ] **Step 4: Configure bg, glow, embers in the script** + +In `client/scripts/ui/title/title_screen.gd`, add `@onready` refs beside the existing ones: + +```gdscript +@onready var _background: ColorRect = $Background +@onready var _glow: ColorRect = $Glow +@onready var _embers: GPUParticles2D = $Embers +``` + +In `_ready()`, add these calls (after `_fit_to_viewport()` / before the menu harvest is fine): + +```gdscript + _apply_background() + _configure_embers() + _pulse_glow() +``` + +Add the three functions: + +```gdscript +func _apply_background() -> void: + # Palette-driven shader material set in code (the DarkBay precedent) so no hex + # lives in the shader/scene; the editor shows the ColorRect fallback. + var mat := ShaderMaterial.new() + mat.shader = load("res://assets/theme/shaders/title_background.gdshader") + mat.set_shader_parameter("warm", Palette.TITLE_WARM) + mat.set_shader_parameter("mid", Palette.TITLE_MID) + mat.set_shader_parameter("edge", Palette.STAGE_1) + _background.material = mat + + +func _configure_embers() -> void: + var pm := ParticleProcessMaterial.new() + pm.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX + pm.emission_box_extents = Vector3(760, 4, 0) # a wide strip along the bottom + pm.direction = Vector3(0, -1, 0) + pm.spread = 12.0 + pm.gravity = Vector3(0, -18, 0) + pm.initial_velocity_min = 24.0 + pm.initial_velocity_max = 52.0 + pm.scale_min = 0.4 + pm.scale_max = 1.0 + pm.color = Palette.GOLD_BRIGHT + # fade out over life + var ramp := Gradient.new() + ramp.set_color(0, Color(Palette.GOLD_BRIGHT, 0.0)) + ramp.set_color(1, Color(Palette.GOLD_BRIGHT, 0.0)) + ramp.add_point(0.15, Palette.GOLD_BRIGHT) + var tex := GradientTexture1D.new() + tex.gradient = ramp + pm.color_ramp = tex + _embers.process_material = pm + + +func _pulse_glow() -> void: + # A slow warm pulse (the off-screen fire). A code tween, not an AnimationPlayer: + # a 2-keyframe modulate loop is trivial in code and motion is runtime-only anyway. + var tween := create_tween().set_loops().set_trans(Tween.TRANS_SINE) + tween.tween_property(_glow, "modulate:a", 0.8, 3.0) + tween.tween_property(_glow, "modulate:a", 0.5, 3.0) +``` + +- [ ] **Step 5: Run the title + full suite (no regression)** + +Run: `cd client && ./run_tests.sh -gselect=test_title_screen.gd` → PASS (the added nodes/refs must not break `_ready`). +Then: `cd client && ./run_tests.sh` → PASS, all tests. + +- [ ] **Step 6: Commit** + +```bash +git add client/scripts/theme/palette.gd client/assets/theme/shaders/title_background.gdshader client/assets/theme/shaders/title_background.gdshader.uid client/scenes/title/TitleScreen.tscn client/scripts/ui/title/title_screen.gd +git commit -m "feat(title): warm shader background, pulsing glow, drifting embers" +``` + +--- + +### Task 6: Visual gate — human F6 + boot check + +**Not automatable.** Headless GUT proves structure and interaction wiring, not rendering or motion. + +- [ ] **Step 1: Run the project (boot path)** + +In the Godot editor press **F5** (run project) — it should boot straight to the Title screen (proves `run/main_scene`). Also open `client/scenes/title/TitleScreen.tscn` and press **F6**. + +- [ ] **Step 2: Confirm by eye** + + - Warm radial background (bright toward upper-right), heavy vignette, the key-art dashed slot on the right. + - Drifting embers rising from the bottom; the fire glow along the bottom slowly pulsing. + - Logo block: kicker "A DARK FANTASY RPG" (gold, tracked), "CODE OF CONQUEST" (large cream serif), gold rule, tagline. + - Menu: ◆ marker + brightened label on the selected item; `↑`/`↓` move it (and wrap), the mouse hovering an item selects it. + - Footer: `v0.01-alpha · BUILT IN GODOT 4.7 · © 2026` (left), the controls hint (right). + - **New Game** (Enter or click) → the Main Window shell; **Quit** exits. + +- [ ] **Step 3: Report the outcome** + +If anything is collapsed, mis-placed, or the boot/nav doesn't work, fix and re-run before the milestone is done. When it looks right, the Title is eyeball-confirmed and ready to merge. + +--- + +## Self-Review + +**Spec coverage:** +- Root `/VERSION` + API reads it + `/version` → Task 1. ✓ +- Client `Version` helper + sync script + `project.godot` config/version → Task 2. ✓ +- `TitleLogo`/`TitleKicker` theme variations → Task 3. ✓ +- Title composition (logo/menu/footer/key-art/vignette), selection + keyboard/mouse, `menu_activated` seam, New Game→shell / Quit / inert → Task 4. ✓ +- Boot scene (`run/main_scene`) → Task 4 Step 5. ✓ +- Warm shader background (palette uniforms) + Palette warm tokens + embers (GPUParticles) + glow → Task 5. ✓ +- Editor-first, viewport-fit rule, palette-clean → Global Constraints + honored per task. ✓ +- Tests (Version, API version, title selection/activation/footer) + F6 gate → Tasks 1–4 + Task 6. ✓ + +**Placeholder scan:** no "TBD"/"handle edge cases"/"similar to". Every code step has full code. ✓ + +**Type consistency:** `Version.string()`/`footer()`; `get_version()`/`VERSION`; `ThemeKeys.TITLE_LOGO`/`TITLE_KICKER`; `TitleScreen._rows`/`_sel`/`_move`/`_activate`/`_on_menu_activated`/`menu_activated`/`_footer_left`/`_menu`/`_background`/`_glow`/`_embers`; `Palette.TITLE_WARM`/`TITLE_MID`/`STAGE_1`/`GOLD`/`GOLD_BRIGHT`/`CREAM`/`CREAM_BRIGHT`/`MUTED_MONO` — consistent across tasks and match the existing code read during planning. ✓ + +**Noted deviation from the spec:** the glow uses a **code Tween**, not an `AnimationPlayer` — a 2-keyframe modulate loop is trivial in code and motion is runtime-only regardless; the embers `ParticleProcessMaterial` and the bg `ShaderMaterial` are set in code (the `DarkBay` precedent) rather than authored in the `.tscn`, keeping colours Palette-sourced at the cost of an editor preview of the motion. Flagged here so it is a conscious call, not a silent drift.