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.

Database Use

CARDCHESSGAME does not use a traditional relational database. All data is stored 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",
  "cosmetics": ["RedBoard", "GoldPieces"],
  "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": "Knight Move",
  "type": "Movement",
  "description": "Allows you to move a Knight piece.",
  "effect": "move_knight"
}

Common Queries

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

• get_card_by_name(name) → returns a card struct from the loaded JSON.
• get_player_cosmetics(player_id) → loads player cosmetics from local save.
• get_available_rooms() → retrieves list of lobbies from obj_network_manager.
• get_unlocked_items() → filters local data for owned cosmetics.

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
  • 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)

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

BoardController

• Attributes
  • tiles[] (array of Strings)
• Methods
  • 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

UIController

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

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: