@@ -0,0 +1,189 @@
# Ranked Gameplay UI — Implementation Plan
## Overview
Three layers of work:
1. * * `Game.gd` autoload** — stores game state, handles server pushes, exposes helpers
2. **Matchmaking screen ** — queue join/wait/cancel, deck selection, navigates to game on match found
3. **GameScreen ** — 3D board + 2D HUD overlay, all game actions wired
---
## Files to Create / Modify
### New files (client)
| File | Purpose |
|------|---------|
| `autoloads/Game.gd` | Game state autoload |
| `scenes/matchmaking/MatchmakingScreen.tscn + .gd` | Queue waiting screen |
| `scenes/game/GameScreen.tscn + .gd` | Full 3D game scene |
### Modified files
| File | Change |
|------|--------|
| `scenes/main/main_screen.gd` | Wire MatchBtn → MatchmakingScreen |
| `project.godot` | Register Game autoload |
---
## 1. Game.gd Autoload
Signals: `match_found(session_id, opponent_name, opponent_rank)` , `state_updated(state)` , `game_over(winner_id, win_condition)`
State stored: `session_id` , `state` (full GameStateDto dict), `my_account_id`
On `Network.message_received` :
- `matchmaking.match_found` → store session_id, emit `match_found`
- `game.state_update.push` → store state, emit `state_updated`
- `game.over.push` → emit `game_over`
Public helpers: `get_my_player()` , `get_opponent()` , `is_my_turn()` , `get_board_tiles()` , `get_hand()` , `get_phase()`
---
## 2. MatchmakingScreen
Flow:
1. On `_ready` : call `collection.get_decks` to fetch player's decks
2. Show deck list for selection (or auto-pick if only one)
3. On deck selected → call `matchmaking.join` → show "Searching…" spinner with elapsed timer
4. Cancel button → `matchmaking.leave` → back to MainScreen
5. On `Game.match_found` signal → navigate to `GameScreen.tscn`
Also handles: already-in-queue case (calls `matchmaking.status` to restore state)
---
## 3. GameScreen Architecture
### 3D Scene structure
```
GameScreen (Node3D)
├── WorldEnvironment — skybox (ProceduralSky)
├── DirectionalLight3D
├── CameraRig (Node3D) — pivot at board center (0,0,0)
│ └── Camera3D — at (0, 10, 9), looking down at 48°
├── BoardRoot (Node3D)
│ ├── TilesRoot — 64 StaticBody3D + BoxMesh tiles
│ ├── UnitsRoot — dynamic unit placeholder meshes
│ └── HighlightsRoot — thin overlay planes (highlights)
└── HUD (CanvasLayer, layer=10)
```
### Tile mesh
- `BoxMesh` size `(1, 0.5, 1)` at position `(x - 3.5, 0.25, y - 3.5)` for an 8× 8 board
- Material color = affinity color (24-entry dict)
- `StaticBody3D` + `BoxShape3D` for input detection via raycast
### Unit placeholders
| Card type | Mesh | Size | Color |
|-----------|------|------|-------|
| Spirit | SphereMesh | r=0.3 | team-colored (blue/red) |
| ArchSpirit | CylinderMesh | r=0.25, h=0.8 | team-colored, bright |
| SpiritToken | SphereMesh | r=0.2 | muted team color |
| Ruin | BoxMesh | 0.25× 1.0× 0.25 | dark grey |
Units sit on top of tiles at `y = 0.5 + half_height` .
### Highlight overlays (HighlightsRoot children)
| Highlight | Color | Use |
|-----------|-------|-----|
| `green_fill` | `(0.2, 0.9, 0.2, 0.35)` | Valid play tile / movement range |
| `red_outline` | `(1.0, 0.25, 0.25, 0.5)` | Attack range / enemy unit target |
| `blue_fill` | `(0.2, 0.5, 1.0, 0.35)` | Ability target |
| `yellow_fill` | `(1.0, 0.85, 0.1, 0.45)` | Selected unit's tile |
Each highlight is a flat `BoxMesh (1, 0.02, 1)` at `y = 0.5 + 0.01` .
### Camera controls
- **Orbit** (left-mouse drag / single touch drag): rotate CameraRig Y-axis; clamp pitch
- **Zoom** (scroll wheel / pinch): translate Camera3D along its -Z axis; clamp distance 4– 20
- **Pan** (middle-mouse drag / two-finger slide): translate CameraRig in XZ plane
### HUD layout (all 2D CanvasLayer)
```
TopBar (HBoxContainer, top of screen)
PhaseLabel | TurnLabel | [Opponent: 5 cards | deck:30 | DISCARD]
HandArea (bottom, 200px tall)
ScrollContainer → HBoxContainer of GameCardWidgets
— hover: card scales up + moves up 30px (z_index = 10)
— selected: bright border; card click = select, tile click = play
RightPanel (right side, 180px wide)
SP: {n} | ST: {n}
Deck: {n} | [View Discard]
[Draw Card] [End Turn] [Concede]
ContextPopup (center popup, shows on 0.5s hold on tile)
Tile: ({x},{y}) | Affinity: {aff}
Occupant: {name} | HP: {hp}/{max} | DEF: {def}/{max}
[card abilities listed if unit present]
DiscardViewer (full overlay, shown on discard click)
ScrollContainer of card name rows
[Close]
```
### GameCardWidget (built programmatically, no .tscn)
- Sized ~100× 155px (smaller than collection widget for hand use)
- Shows: card art placeholder (colored rect by affinity), name, SP cost, type icon, key stat (Damage or HP)
- Built directly from `CardInstanceDto` dict (no definition lookup needed — server already merged)
### Selection state machine
``` gdscript
enum Mode { NONE , CARD_FROM_HAND , UNIT_SELECTED , PLACEMENT }
var _sel_mode : Mode = Mode . NONE
var _sel_card_id : String = " " # hand card instance ID
var _sel_unit_id : String = " " # field unit instance ID
```
**CARD_FROM_HAND ** : Raycast click on a green-highlighted tile → send `game.play_card`
**UNIT_SELECTED ** : Raycast click on green tile → `game.move_unit` ; red-highlighted enemy unit → `game.attack`
**PLACEMENT ** : Highlighted valid placement tiles → click → `game.place_arch_spirit`
### Phase-aware action bar
| Phase | Available actions |
|-------|-----------------|
| Placement | Place ArchSpirit button highlighted |
| Draw | Auto-draw on load (calls `game.draw` ), or "Draw Card" button |
| Main | Full bar: play cards, move, attack, sacrifice, ascend, transition, end turn |
| GameOver | "Return to Main Menu" only |
### Hold timer (context popup)
- `Timer` (0.5s, one-shot) started on `BUTTON_LEFT` pressed on a tile
- Cancelled on mouse move or release
- On timeout: show ContextPopup with tile + occupant data
### Opponent discard viewer
- Opponent's `Discard` array is always visible in `GameStateDto`
- Clicking "View Discard" opens a scrollable list of card names + types
---
## 4. Wiring MainScreen
`main_screen.gd` : add `@onready var match_btn : Button = %MatchBtn`
On pressed → `get_tree().change_scene_to_file("res://scenes/matchmaking/MatchmakingScreen.tscn")`
---
## Coord ↔ 3D mapping
``` gdscript
func coord_to_world ( x : int , y : int ) - > Vector3 :
return Vector3 ( x - 3.5 , 0.0 , y - 3.5 ) # tiles centered at origin
func world_to_coord ( pos : Vector3 ) - > Vector2i :
return Vector2i ( roundi ( pos . x + 3.5 ) , roundi ( pos . z + 3.5 ) )
```
---
## Implementation Order
1. `Game.gd` + `project.godot`
2. `MatchmakingScreen`
3. Wire `MatchBtn` in `main_screen.gd`
4. `GameScreen` — board, camera, units
5. `GameScreen` — HUD, hand, action bar
6. `GameScreen` — selection state, highlights, all game actions
7. `GameScreen` — context popup, discard viewer, game-over handling