Files
2026-03-07 10:28:32 -05:00

6.8 KiB
Raw Permalink Blame History

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

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

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