Architecture

CARDCHESSGAME – Architecture Document

Overview

CARDCHESSGAME (working title) is a digital strategy card game that puts a twist on regular chess gameplay. Players take turns playing cards that allow them to move chess pieces, activate effects, or equip passive abilities. The objective remains the same as chess: capture the opponent’s king. Each turn, a player can:

• Play one Active Card (optional)
• Play one Movement Card (mandatory, ends the turn)
• Play any number of Passive Cards, though only one can remain equipped.

The game is developed in GameMaker Studio as a desktop game, with singleplayer and multiplayer modes.

Release

• The game will be distributed as a Windows desktop executable (.exe) built directly from GameMaker.
• Testers (including instructors) will install the game via a double-click installer package generated using GameMaker’s “Create Executable” feature.
• No virtual machines or containers are required for development or deployment.
• Save data will be stored locally in the %APPDATA% folder or the game directory.

Models

Card (Parent Object)

• Attributes
  • card_id (int)
  • card_name (string)
  • card_type (enum: MOVEMENT, ACTIVE, PASSIVE)
  • card_description (string)
  • sprite_index (sprite)
• Methods
  • use_card()
  • can_play()
  • discard()

MovementCard (Child of Card)

• Attributes
  • piece_type (enum: PAWN, BISHOP, KNIGHT, ROOK, QUEEN, KING)
  • plus_version (bool)
• Methods
  • apply_movement(piece_type)

ActiveCard (Child of Card)

• Attributes
  • effect_type
• Methods
  • trigger_effect()

PassiveCard (Child of Card)

• Attributes
  • effect_trigger
  • is_equipped (bool)
• Methods
  • activate_on_trigger(effect_trigger)

Player

• Attributes
  • hand[] (array of Card objects)
  • equipped_passive (card_id)
  • captured_pieces[] (array of
  • is_turn (bool)
  • king_alive (bool)
• Methods
  • draw_card(num)
  • play_card(card_id)
  • equip_passive(card)
  • end_turn()
  • check_no_movement_cards()
  • refill_hand()

MatchController

• Attributes
  • player1 (Player)
  • player2 (Player)
  • turn_state (enum: START, IN_PROGRESS, END)
  • game_state (enum: SETUP, ACTIVE, GAMEOVER)
• Methods
  • check_game_state(game_state)
  • check_turn_state(turn_state)
  • start_turn()
  • end_turn()
  • check_victory()
  • piece_captured()
  • check_empty_hand()

BoardController

• Methods
  • select_piece()
  • validate_move()
  • move_piece()
  • capture_piece()
  • get_piece_rank(piece)

UIController

• Methods
  • goto_screen(screen_name)
  • draw_ui_elements()
  • update_button_states()

Common Queries

Views & Functions

Start Screen

Views

View Name	Type	Description
BackgroundPanel	Panel	The overall background frame that holds all UI components.
TitleLabel	Label	Displays the title “Start Screen” at the top of the menu.
MultiplayerButton	Button	Takes the player to the Multiplayer setup screen.
SingleplayerButton	Button	Opens the Singleplayer configuration screen.
CardEncyclopediaButton	Button	Opens the Card Encyclopedia screen to browse all cards.
StoreButton	Button	Opens the in-game Store for cosmetics or items.
OptionsButton	Button	Opens the Options screen for game settings.
ExitGameButton	Button	Opens a confirmation prompt to quit the game.

Functions

Function Name	Description
StartScreen_Init()	Called when the screen loads. Initializes music, loads the player profile, and applies saved settings (e.g., language, volume).
StartScreen_UpdateNav()	Handles keyboard/controller navigation and hover focus between buttons.
PlayUiSfx(type)	Plays sound effects for hover, click, and transitions.
OnClick_Multiplayer()	Opens the Multiplayer configuration screen.
OnClick_Singleplayer()	Opens the Singleplayer setup screen.
OnClick_Encyclopedia()	Opens the Card Encyclopedia screen.
OnClick_Store()	Opens the Store screen.
OnClick_Options()	Opens the Options screen.
OnClick_ExitGame()	Opens a confirmation dialog and, if confirmed, exits the game.
ShowExitConfirmModal()	Displays a Yes/No confirmation modal to prevent accidental exits.

Data

Data Group	Description	Example
Player Profile Data	Contains information about the player’s progress and achievements. Loaded at startup.	{ "player_name": "Suprawee", "total_wins": 25, "total_games": 47 }
Game Settings Data	Stores configuration such as audio levels, fullscreen mode, or language. Shared with the Options Screen.	{ "volume_music": 0.8, "volume_sfx": 0.7, "language": "en" }
Navigation Context	Tracks the screen transitions for back/forward navigation. Used internally by GameMaker rooms.	{ "next_screen": "Singleplayer", "previous_screen": "Start" }
Session Resume Data (Optional)	Saves information from the last match if the player exited mid-game, enabling a “Continue” prompt.	{ "last_session_exists": true, "last_mode": "Singleplayer", "last_difficulty": "Medium" }

---

Singleplayer Screen

Views

View Name	Type	Description
BackgroundPanel	Panel	Overall container for the screen.
TitleLabel	Label	“Singleplayer Game”.
CpuDifficultyDropdown	Dropdown	Select CPU difficulty (e.g., Easy/Medium/Hard).
TurnTimeLimitDropdown	Dropdown	Select per-turn time (e.g., 30s, 2m, 5m, No limit).
TurnOrderDropdown	Dropdown	Who goes first (Player, CPU, Random).
PlayerColorDropdown	Dropdown	Player’s color/side.
CpuColorDropdown	Dropdown	CPU’s color/side.
BackButton	Button	Return to Start screen.
StartGameButton	Button	Validate and start the game with the chosen config.

Functions

Function Name	Description
SingleplayerScreen_Init()	Load defaults (from save or fallback), populate dropdowns, set initial focus, start/continue menu music.
OnChange_CpuDifficulty(value)	Update selected difficulty; show optional tooltip/preview.
OnChange_TurnTimeLimit(value)	Update internal timer setting (seconds or “none”).
OnChange_TurnOrder(value)	Set first player or mark as random.
OnChange_PlayerColor(value)	Update player color; call ValidateColors().
OnChange_CpuColor(value)	Update CPU color; call ValidateColors().
ValidateColors()	Disallow PlayerColor == CpuColor; set error state/disable Start if invalid.
ValidateGameSetup()	Final gate: all fields selected, values legal; returns bool and error text if any.
BuildGameConfig()	Compose immutable config struct used by the Game room (see “Data Passed” below).
OnClick_StartGame()	If valid: config = BuildGameConfig() → stop menu music → change room to Game, handing off config.
OnClick_Back()	Return to Start screen (room change handled by GM).
PersistSingleplayerSettings()	Save last selections so the screen restores them next visit.
PlayUiSfx(type)	Hover/click sound feedback.

Data

Data Group	Description	Example
Match Config	Sent to the Match Room when Start Game is pressed. Contains all the gameplay parameters for this session.	{ "mode": "singleplayer", "difficulty": "Medium", "turn_time_limit_sec": 300, "first_player": "Random", "player_color": "White", "cpu_color": "Black" }
UI / Screen State	Runtime values used to track dropdown selections, focus targets, and validation results while on this screen.	{ "selected_indices": {"difficulty": 1, "turn_time": 3, "turn_order": 2, "player_color": 0, "cpu_color": 1}, "errors": {"color_conflict": false} }
Persisted Preferences	Stored in save data so the screen loads the same settings next time.	{ "last_singleplayer_settings": {"difficulty": "Medium", "turn_time_limit_sec": 300, "turn_order": "Random", "player_color": "White", "cpu_color": "Black"} }
Navigation Context	Tracks screen transitions for going forward/backward in GameMaker rooms.	{ "previous_screen": "Start", "next_screen": "Game" }

---

Card Encyclopedia Screen

Views

View Name	Type	Description
BackgroundPanel	Panel	Main container for all UI elements.
TitleLabel	Label	Displays “Card Encyclopedia.”
Tab_Active	Tab Button	Filters the list to show only Active cards.
Tab_Movement	Tab Button	Filters to show only Movement cards.
Tab_Passive	Tab Button	Filters to show only Passive cards.
CardPanel_1 / CardPanel_2 / CardPanel_3	Panels	Containers for displaying card previews in a grid layout.
CardImage	Image	The artwork of the card.
RarityBadge	Icon	Visual marker showing the card’s rarity.
CardTitle	Label	Displays the card’s name.
CardDescription	Label	Displays a brief summary or ability text.
TagChipsGroup	Tag Chips	Displays quick tags (e.g., Attack, Defense, Cost 2).
BackButton	Button	Returns the player to the Start Screen.

Functions

Function Name	Description
Encyclopedia_Init()	Loads all card data from the database or JSON file, sets the default tab, and builds the grid view.
OnClick_Tab(category)	Switches category (Active / Movement / Passive) and refreshes the grid.
FilterCards(category)	Filters the card list based on the selected category.
RenderCardGrid(cardList)	Displays card panels in the grid layout based on the current filtered list.
OnHover_Card(cardID)	Highlights the hovered card and optionally shows a short tooltip.
OnClick_Card(cardID)	Opens the detailed card view modal for that specific card.
OpenCardDetail(cardID)	Loads and displays the full-size card image, effects text, and stats.
CloseCardDetail()	Closes the detail modal and returns focus to the card grid.
ApplySearchOrSort(query, sortMode) (optional)	Allows text search or sorting by rarity, cost, or name.
Paginate(direction) (optional)	Moves to next or previous page of results.
OnClick_Back()	Returns to Start Screen.
PlayUiSfx(type)	Plays hover/click sound effects for interactions.

Data

Data Group	Description	Example
Card Data	The main dataset containing all card definitions loaded at initialization.	{ "id": 101, "name": "Fire Strike", "rarity": "Rare", "type": "Active", "cost": 2, "text": "Deal 3 damage to an enemy.", "image": "fire_strike.png" }
UI State	Tracks which tab, page, and card are currently active or focused.	{ "active_tab": "Active", "selected_card_id": 101, "page_index": 0 }
Search/Sort Parameters	If search or sorting is enabled, these define how cards are filtered and ordered.	{ "search_query": "strike", "sort_mode": "rarity" }
Card Detail Data	Temporary data object that stores information for the card currently viewed in detail.	{ "id": 101, "name": "Fire Strike", "description": "Deal 3 damage to an enemy.", "rarity": "Rare", "image": "fire_strike_full.png" }
Navigation Context	Keeps track of screen flow when returning to the Start Screen.	{ "previous_screen": "Start", "next_screen": null }

Team Roles

• Person 1:
• Person 2:
• Person 3:
• Person 4:
• Person 5: