Architecture Overview

Medieval Deck is built using a modular, state-based architecture designed for clarity and scalability. This approach separates different parts of the game (e.g., menu, gameplay, asset generation) into distinct, manageable components.

State-Based Game Loop

The core of the game is managed by a state machine in main.py. The MedievalDeck class orchestrates the main game loop, while the GameState enum defines the possible states the game can be in.

# From main.py
class GameState:
    """Game state constants for state machine"""
    MENU = "menu"
    SELECTION = "selection"
    GAMEPLAY = "gameplay"
    EVENTS = "events"
    GAMEOVER = "gameover"

The main MedievalDeck class holds an instance of each screen and transitions between them based on player actions. The handle_events, update, and render methods in the main loop delegate all logic to the active screen module.

# Simplified game loop logic from main.py
class MedievalDeck:
    # ... initialization ...

    def run(self):
        """Main game loop"""
        while self.running:
            # Delegate event handling to the current screen
            self.screens[self.current_state].handle_events(events)

            # Delegate updates to the current screen
            self.screens[self.current_state].update()

            # Delegate rendering to the current screen
            self.screens[self.current_state].render(self.screen)

            self.clock.tick(FPS)

This design makes it easy to add new game states (like a shop or a map screen) without modifying the core game loop.

Project Structure

The project is organized into logical directories, each with a specific responsibility:

Medieval-Deck/
├── main.py                 # Main game entry point and state machine
├── config.py               # Global constants and settings
├── screens/                # Game state modules (Menu, Selection, etc.)
├── gen_assets/             # AI asset generation pipeline and art direction
├── assets/                 # Generated visual assets (images, sprites)
├── cards/                  # Card and deck system definitions
├── utils/                  # Shared utilities like buttons and transitions
├── tests/                  # Unit and integration tests for each sprint
└── audio/                  # Sound effects and music

• /screens: Each file corresponds to a GameState and handles all logic and rendering for that specific screen.
• /gen_assets: Contains all the logic for the AI asset generation pipeline. It's completely decoupled from the game logic, only producing image files that the game can then load.
• /utils: Home to reusable components, such as the Button system, which are used across multiple screens.
• /cards: Will contain the logic for cards, decks, and relics as the project develops.