Skip to content

Architecture

DuncanSzabaga edited this page Oct 20, 2025 · 6 revisions

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.

Database Use

CARDCHESSGAME does not use a traditional relational database. All data is stored and loaded locally using GameMaker’s built-in file handling systems. Therefore, there are no SQL-style queries or table joins in this project.

Storage Methods

JSON Files:

Used for saving user cosmetics, unlocked items, and progress.

Example file: playerdata.json

Structure:

{
  "username": "Player1",
  "playerUUID": 90b6060a-2937-4cdf-a334-eb8ce103c255,
  "gamesWon": 12,
  "gamesPlayed": 20,
  "cash": 10000,
  "friendslist": [75792229-86be-4541-b6c4-448f7a2fcc9a],
  "cosmetics": [true, false],
  "settings": {
    "musicVolume": 0.8,
    "sfxVolume": 0.7
  }
}

INI Files:

Used for saving options and configurations.

Example: config.ini

[audio]
volume_music=0.8
volume_sfx=0.7

[video]
fullscreen=true
resolution=1920x1080

Card Data:

Stored as a JSON file (cards.json) containing all card definitions, which the game loads at startup.

Example entry:

{
  "name": "Move Pawn",
  "card_id": 1
  "type": "MOVEMENT",
  "description": "Allows you to move a Pawn piece."
}

Common Queries

Even though there’s no database, the following are examples of equivalent data lookups done in memory:

  • get_card_by_id(card_id) → returns a card struct from the loaded JSON.
  • get_player_cosmetics(playerUUID) → loads player cosmetics from profile.
  • get_available_rooms() → retrieves list of lobbies from obj_network_manager.

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(): Executes the effect of the card
    • can_play(): Checks if a card can be played
    • discard(): Sends the card to the discard pile

MovementCard (Child of Card)

  • Attributes
    • card_piece (Piece)
    • plus_version (bool)
  • Methods
    • apply_movement(piece_type, plus_version): Movement effect for the piece based on card used

ActiveCard (Child of Card)

  • Methods
    • trigger_effect(): Trigger the active effect of the card

PassiveCard (Child of Card)

  • Methods
    • activate_on_trigger(): Trigger the passive effect of the card

Player

  • Attributes
    • username (string)
    • playerUUID (string)
    • gamesWon (int)
    • gamesPlayed (int)
    • cash (int)
    • friendslist[] (array of strings)
    • ownedCosmetics[] (array of booleans)

GamePlayer

  • Attributes
    • hand[] (array of Card objects)
    • equipped_passive (card_id)
    • captured_pieces[] (array of Pieces)
    • is_turn (bool)
    • king_alive (bool)
    • opponent (bool)
  • Methods
    • draw_card(num): Draw a card to the player's hand
    • play_card(Card): Play a card from the player's hand
    • equip_passive(Card): Equip a passive card
    • end_turn(): End the player's turn
    • check_no_movement_cards(): Check if the player has movement cards in hand
    • refill_hand(): Give the player cards if their hand is empty

Piece

  • Attributes
    • piece_type (enum: PAWN, BISHOP, KNIGHT, ROOK, QUEEN, KING)
    • alive (bool)
    • location (string)
    • rank (int)

TotalGameStateController

  • Attributes
    • current_room (string)
    • previous_room (string)
    • music_loader (type)
    • sfx_loader (type)
    • user_info (Player)
  • Methods
    • goto_screen(room_name): Used to navigate to different Rooms in GameMaker
    • PlayUiSfx(sfx_loader): Plays sound effects for hover, click, and transitions
    • PlayRoomMusic(music_loader): Handles music state between Rooms

Views & Functions

Start Screen

image

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.
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

  • Session Resume Data (Optional)
    • Saves information from the last match if the player exited mid-game, enabling a “Continue” prompt
    • Ex: { "last_session_exists": true }

Singleplayer Screen

image

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

No unique Data required.


Multiplayer Screen

image

Views

View Name Type Description
BackgroundPanel Panel Base for all UI Elements of this screen
MultiplayerScreenTitle Label Displays "Multiplayer" text
BoardPreview Image Displays a sample board preview where the Match Screen is loaded
SelectRankedMatch Button Goes to the matchmaking screen for a ranked match
SelectCasualMatch Button Goes to the matchmaking screen for a casual match
SelectFriendMatch Button Goes to the matchmaking screen for a friend match
BackButton Button Goes to the main menu

Functions

Function Name Description
Start_Multiplayer_Screen() Loads all UI elements and music assets to be used. Only called when screen is first loaded.
OnClick_RankedMatch() Begins searching for an opponent in a ranked match and triggers transition to Ranked Match screen
OnClick_CasualMatch() Opens the Casual Match screen
OnClick_FriendMatch() Opens the Friend Match screen

Data

No unique Data required.


Casual Match Screen

image

Views

View Name Type Description
BackgroundPanel Panel Overall contiainer for the screen.
TitleLabel Label "Casual Matches".
JoinButton Button Join a lobby.
RulesButton Button Show the rules.
TagSearchBox Search Box Filter by tag.
IDSearchBox Search Box Filter by lobby ID.
CreateLobbyButton Button Create a game lobby.

Functions

Function Name Description
CasualMatchScreen_Init() Draw UI elements, call ScanForGames().
ScanForGames() Scan for open game lobbies.
ScanForGames(value, type) Scan for games with filters for tags and Lobby ID.
JoinGame(type) Join a game lobby and begin loading into the game.
PlayUiSfx(type) Hover/click sound feedback.
ShowRules(type) Shows the rules for a game lobby. Shown when "View Rules" is clicked.
CreateLobbyScreen_Init() Start using the Lobbby Screen UI. Called when Create Lobby is clicked.

Data

No unique Data required.


Friend Match Screen

image

Views

View Name Type Description
BackgroundPanel Panel Overall contiainer for the screen.
TitleLabel Label "Friend Matches".
JoinButton Button Join a lobby.
FriendSearchBox Search Box Filter by friend name.
CreateLobbyButton Button Create a game lobby.

Functions

Function Name Description
FriendMatchScreen_Init() Draw UI elements, call ScanforFriendGames().
ScanForFriendGames() Scans for game lobbies with the user's friends.
ScanfForGames(value) Scans for games with a filter for a specific friend.
CreateLobbyScreen_Init() Start using the Lobby Screen UI. Called when Create Lobby is clicked.

Data

  • Player Friend Data
    • Contains the user's friend list and number of friends.
    • Ex: { "friendlist": [75792229-86be-4541-b6c4-448f7a2fcc9a] }

Lobby Screen

image

Views

View Name Type Description
BackgroundPanel Panel Overall contiainer for the screen.
TitleLabel Label "Lobby Rules"
LobbyName Text Box The name of the game lobby to create.
TurnTimeLimit Dropdown The time limit of the game.
Tags Dropdown Tags of the lobby to create.
VisibilityPublic Button Set public visibility for the lobby.
VisibilityFriends Button Set friends only visibility for the lobby.
Password Toggle Toggle the use of a password.
PasswordBox Text Box The password to be used for the game lobby.
ManageCards Button Manage the allowed cards.
CreateLobbyButton Button Create a game lobby.

Functions

Function Name Description
CreateLobbyScreen_Init() Draw UI elements.
ManageCards() Shows the menu for card management.
CreateLobby(value name, value timelimit, value tags, value visibility, value password) Create a game lobby with the specified options.

Data

No unique Data required.


Match Screen

image

Views

View Name Type Description
BackgroundPanel Panel Base for all UI elements of this screen
MatchScreenTitle Label Displays "Multiplayer" text
BoardPreview Image Displays a sample board preview where the Match Screen is loaded
CancelMatchmaking Button Goes back to the Multiplayer Screen
SelectRankedMatch Button Button from Multiplayer screen, can't be interacted with on Match Screen
SelectCasualMatch Button Button from Multiplayer screen, can't be interacted with on Match Screen
SelectFriendMatch Button Button from Multiplayer screen, can't be interacted with on Match Screen
PlayerReadyStatus Image Reflects whether the player has pressed the ConfirmReadyButton
OpponentReadyStatues Image Reflects whether the opponent has pressed the ConfirmReadyButton
ConfirmReadyButton Button Changes player to ready state
PlayerProfilePreview Image Shows your account name and profile picture (displayed to player and opponent
OpponentProfilePreview Image Shows opponent's account name and profile picture (displayed to player and opponent

Functions

Function Name Description
Start_Match_Screen() Loads all UI elements and music assets to be used. Only called when screen is first loaded.
OnClick_Cancel() Stops searching for an opponent if one has yet to be found or cancels the match for both players and returns to the Multiplayer Screen (not visible on Ranked Matches)
Search_For_Opponent() Find other players at similar skill level for a Ranked Match
OnClick_Ready() Changes the player's state to ready and updates the PlayerReadyStatus
Start_Game_Match() Sends the players to the Game Screen

Data

  • Get User profile data
    • User profile data is needed to display to opponents
    • Ex: { "username": "Player1", "gamesWon": 12, "gamesPlayed": 20 }

Card Encyclopedia Screen

image

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

  • Load Card Data
    • The main dataset containing all card definitions loaded at initialization
    • Ex: { "name": "Move Pawn", "card_id": "1", "type": "MOVEMENT", "description": "Allows you to move a Pawn piece" }

Store Screen

image

Views

View Name Type Description
BackgroundPanel Panel The main background frame that contains all store elements.
ScreenLabel Label Displays the title “STORE” at the top of the screen.
CoinDisplay Label Shows the player’s current coin balance in the top-right corner.
BoardDesignsLabel Panel Displays available board designs with left and right arrow buttons for scrolling.
CardDesginsLabel Panel Displays available card designs with navigation arrows for scrolling.
PieceDesignsLabel Panel Displays available piece designs with navigation arrows for scrolling.
BoardDesignsLeftArrow Button Scrolls to the previous set of board designs.
BoardDesignsRightArrow Button Scrolls to the next set of board designs.
CardDesignsLeftArrow Button Scrolls to the previous set of card designs.
CardDesignsRightArrow Button Scrolls to the next set of card designs.
PieceDesignsLeftArrow Button Scrolls to the previous set of piece designs.
PieceDesignsRightArrow Button Scrolls to the next set of piece designs.
BackButton Button Returns the player to the previous menu screen.
InventoryButton Button Opens the player’s inventory to view owned and equipped items.
ItemSlot Button Represents a single item (board/card/piece) that can be purchased or equipped.
PurchaseFeedbackLabel Label Displays messages like “Not enough coins” or “Item purchased successfully.”

Functions

Function Name Description
StoreScreen_Init() Initializes all store data, loads items, and sets up player profile information.
StoreScreen_UpdateNav() Updates the navigation arrows and page selection for each category row.
OnClick_BoardLeftArrow() Scrolls to the previous set of board designs.
OnClick_BoardRightArrow() Scrolls to the next set of board designs.
OnClick_CardLeftArrow() Scrolls to the previous set of card designs.
OnClick_CardRightArrow() Scrolls to the next set of card designs.
OnClick_PieceLeftArrow() Scrolls to the previous set of piece designs.
OnClick_PieceRightArrow() Scrolls to the next set of piece designs.
OnClick_Back() Returns the player to the previous menu screen.
OnClick_Inventory() Opens the player’s inventory screen to view owned and equipped items.
OnClick_BuyItem() Attempts to purchase the selected item if the player can afford it.
OnClick_EquipItem() Equips the selected item from the owned inventory.
Wallet_GetBalance() Returns the player’s current coin balance for display in the UI.
Wallet_SpendCoins(amount) Deducts coins if affordable and confirms purchase success.
SaveProfile() Saves player progress, including owned and equipped items, to storage.
LoadProfile() Loads previously saved player data when entering the store.
ShowPurchaseToast(message) Displays short on-screen notifications like “Purchase successful” or “Not enough coins.”

Data

  • Load User Cosmetic Data
    • Owned cosmetics are stored as an array of booleans, where "true" means the cosmetic that matches that index is owned
    • Ex: { "cosmetics": [true, false, ...] }

Inventory Screen

image

Views

View Name Type Description
InventoryTitle Label Displays the title “Inventory Screen” at the top of the interface.
CoinTotal Label Shows the player’s current total coins in the top-right corner.
BoardSection Panel Contains the “Board” label and all owned board design slots.
BoardItemSlot Button Represents each owned board design that can be equipped.
PieceSection Panel Contains the “Pieces” label and all owned chess piece sets.
PieceItemSlot Button Represents each owned chess piece set that can be equipped.
CardSection Panel Contains the “Cards” label and all owned card designs.
CardItemSlot Button Represents each owned card design that can be equipped.
EquippedCheckmark Icon Indicates which item (board, piece, or card) is currently equipped.
ViewStoreButton Button Navigates the player to the Store screen.
BackButton Button Returns the player to the previous or main menu screen.

Functions

Function Name Description
InventoryScreen_Init() Initializes the inventory screen and loads all owned items from the player’s profile.
InventoryScreen_Update() Refreshes the display of items and updates which ones are currently equipped.
OnClick_BoardItem() Equips the selected board design when clicked.
OnClick_PieceItem() Equips the selected chess piece design when clicked.
OnClick_CardItem() Equips the selected card design when clicked.
OnClick_ViewStore() Navigates the player back to the Store screen.
OnClick_Back() Returns the player to the previous or main menu screen.
Wallet_GetBalance() Returns the player’s current coin balance for display in the top-right corner.
SaveProfile() Saves all equipped and owned items to persistent storage.
LoadProfile() Loads the player’s saved data, including equipped items and inventory.
ShowEquipToast(message) Displays an on-screen notification confirming an item has been equipped.

Data

  • Load User Cosmetic Data
    • Owned cosmetics are stored as an array of booleans, where "true" means the cosmetic that matches that index is owned
    • Ex: { "cosmetics": [true, false, ...] }

Options Screens

image image image

Views

View Name Type Description
OptionsTitle Label Displays the title “Options” at the top of the screen.
VideoTab Button Switches to the Video settings panel.
AudioTab Button Switches to the Audio settings panel.
ControlsTab Button Switches to the Controls settings panel.
AudioPanel Panel Contains all audio-related settings and sliders.
MasterVolumeLabel Label Displays the label “Master Volume.”
MasterVolumeSlider Slider Adjusts the overall sound level of the game.
MusicVolumeLabel Label Displays the label “Music Volume.”
MusicVolumeSlider Slider Adjusts background music volume.
SfxVolumeLabel Label Displays the label “SFX Volume.”
SfxVolumeSlider Slider Adjusts sound effects volume (e.g., UI clicks, game sounds).
GameplaySection Panel Displays gameplay-related keybindings for player actions.
MovePieceLabel Label Displays the “Move Piece” control label.
MovePieceKeybind Keybind Allows players to view or remap the keys used to move pieces (WASD or arrows).
PlayCardLabel Label Displays the “Play Card” control label.
PlayCardKeybind Keybind Shows or allows changing the key used to play a card (default: Space).
EndTurnLabel Label Displays the “End Turn” control label.
EndTurnKeybind Keybind Shows or allows changing the key used to end a turn (default: Enter).
InterfaceSection Panel Displays interface-related keybindings such as menu and zoom.
OpenMenuLabel Label Displays the “Open Menu” control label.
OpenMenuKeybind Keybind Shows or allows changing the key used to open the menu (default: Esc).
ToggleEncyclopediaLabel Label Displays the “Toggle Encyclopedia” control label.
ToggleEncyclopediaKeybind Keybind Shows or allows changing the key used to toggle the encyclopedia (default: E).
ToggleZoomLabel Label Displays the “Toggle Zoom” control label.
ToggleZoomKeybind Keybind Shows or allows changing the key used to toggle zoom (default: Z).
ResetDefaultsButton Button Resets all control settings back to their default values.
BackButton Button Returns the player to the previous or main menu screen.

Functions

Function Name Description
OptionsScreen_Init() Initializes the Options screen and loads the player’s saved audio settings.
OptionsScreen_UpdateTabs() Updates which tab (Video, Audio, or Controls) is currently active.
OnClick_VideoTab() Switches the interface to the Video settings section.
OnClick_AudioTab() Switches the interface to the Audio settings section.
OnClick_ControlsTab() Switches the interface to the Controls settings section.
OnChange_MasterVolume() Adjusts the game’s overall sound level and saves the change.
OnChange_MusicVolume() Updates and saves the background music volume.
OnChange_SfxVolume() Updates and saves sound effects volume for UI and gameplay.
OnChange_Resolution() Applies a new screen resolution selected from the dropdown.
OnChange_Fullscreen() Toggles fullscreen mode based on the user’s selection.
OnChange_Volume() Updates audio levels when the volume setting is changed.
OnChange_KeyBinding() Updates control bindings when the player changes an input.
SaveSettings() Saves all current audio settings (volume levels) to persistent storage.
LoadSettings() Loads previously saved audio settings when the player opens this screen.
OnClick_Back() Returns the player to the previous or main menu screen.

Game Screen

image

Views

View Name Type Description
BackgroundPanel Panel Main container for all UI elements.
TimerDisplay Label Displays “Timer: (turn_timer)”.
TurnDisplay Label Displays “Current Turn: (Player)”.
GameBoard Panel Container for the board used during a game.
DrawPile Image Sprite representation of a draw pile, used for draw card animations.
DiscardPile Panel Container for the last card that was used during the game.
PlayerHand Panel Container that holds the cards currently in the player’s hand.
OpponentHand Panel Container that holds the cards currently in the opponent’s hand.
PlayerPassive Panel Container where the player’s equipped passive card goes.
OpponentPassive Panel Container where the opponent’s equipped passive card goes.

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.
check_game_state(game_state) Check the game's progress
check_turn_state(turn_state) Check the turn's progress
start_turn(Player) Start a player's turn
end_turn() End a player's turn
check_victory(Player, Player) Check if both player's still have their king's
capture_piece(Piece) Executes when a piece is captured
check_empty_hand(Player) Check if the player's hand is empty
select_piece(Piece) Actives when a player selects a piece
validate_move() Check if a move a player tries to make can be made
move_piece(Piece) Moves the selected piece
capture_piece(Piece) Executes when a piece is captured
get_piece_rank(int) Gets the rank value of the piece

Data

  • Load Card Data
    • The main dataset containing all card definitions loaded at initialization
    • Ex: { "name": "Move Pawn", "card_id": "1", "type": "MOVEMENT", "description": "Allows you to move a Pawn piece" }

Team Roles

  • Card system developer
  • AI/CPU developer
  • Store/Economy System Developer
  • UI/UX developer
  • Core Gameplay developer

Clone this wiki locally