6.8 KiB
Ranked Gameplay UI — Implementation Plan
Overview
Three layers of work:
Game.gdautoload — stores game state, handles server pushes, exposes helpers- Matchmaking screen — queue join/wait/cancel, deck selection, navigates to game on match found
- 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, emitmatch_foundgame.state_update.push→ store state, emitstate_updatedgame.over.push→ emitgame_over
Public helpers: get_my_player(), get_opponent(), is_my_turn(), get_board_tiles(), get_hand(), get_phase()
2. MatchmakingScreen
Flow:
- On
_ready: callcollection.get_decksto fetch player's decks - Show deck list for selection (or auto-pick if only one)
- On deck selected → call
matchmaking.join→ show "Searching…" spinner with elapsed timer - Cancel button →
matchmaking.leave→ back to MainScreen - On
Game.match_foundsignal → navigate toGameScreen.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
BoxMeshsize(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+BoxShape3Dfor 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
CardInstanceDtodict (no definition lookup needed — server already merged)
Selection state machine
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 onBUTTON_LEFTpressed on a tile- Cancelled on mouse move or release
- On timeout: show ContextPopup with tile + occupant data
Opponent discard viewer
- Opponent's
Discardarray is always visible inGameStateDto - 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
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
Game.gd+project.godotMatchmakingScreen- Wire
MatchBtninmain_screen.gd GameScreen— board, camera, unitsGameScreen— HUD, hand, action barGameScreen— selection state, highlights, all game actionsGameScreen— context popup, discard viewer, game-over handling