docs(plan): Title screen (M3) + unified version implementation plan
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
967
docs/superpowers/plans/2026-07-11-title-screen.md
Normal file
967
docs/superpowers/plans/2026-07-11-title-screen.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user