# marblexu/pythonsupermario architecture

> Architecture diagram of the GitHub repository marblexu/pythonsupermario, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marblexu/pythonsupermario
- Repository: https://github.com/marblexu/pythonsupermario

## Overview

SuperMario is a Pygame platform game. The player chooses a game from the menu; the state controller runs screens and levels, while the level loads map data and coordinates movement, collisions, scoring, and progression. The graph preserves the documented four-level, pipe, enemy, and slider capabilities. Some level and component source was only sampled, so edges are limited to shown references and documented behavior.

Main entry points: [`source/states/level.py`](https://github.com/marblexu/pythonsupermario/blob/master/source/states/level.py) (Level runtime), [`source/main.py`](https://github.com/marblexu/pythonsupermario/blob/master/source/main.py) (Game bootstrap), [`source/tools.py`](https://github.com/marblexu/pythonsupermario/blob/master/source/tools.py) (State controller), [`source/states/load_screen.py`](https://github.com/marblexu/pythonsupermario/blob/master/source/states/load_screen.py) (Load and end screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_launcher["Game entry<br/>[main.py]"]
  node_game["Game bootstrap<br/>[main.py]"]
  node_controller["State controller<br/>[tools.py]"]
  node_assets["Pygame setup and assets<br/>[setup.py]"]
  node_constants["Game constants<br/>[constants.py]"]
end

subgraph group_world["Level World"]
  node_level["Level runtime<br/>[level.py]"]
  node_maps["Level map data"]
  node_playerdata["Player data"]
end

subgraph group_entities["Game Entities"]
  node_playerchar["Player character<br/>[player.py]"]
  node_terrain["Bricks and boxes<br/>[brick.py]"]
  node_enemy["Enemies<br/>[enemy.py]"]
  node_powerups["Power-ups and fireballs<br/>[powerup.py]"]
  node_coins["Coins<br/>[coin.py]"]
  node_worldobjects["World objects<br/>[stuff.py]"]
  node_boxes["Question boxes<br/>[box.py]"]
end

subgraph group_presentation["Screens and HUD"]
  node_menu["Main menu<br/>[main_menu.py]"]
  node_loadscreen["Load and end screens<br/>[load_screen.py]"]
  node_hud["HUD and status<br/>[info.py]"]
end

node_player(("Player"))

node_player -->|"starts game"| node_launcher
node_launcher -->|"calls entry"| node_game
node_game -->|"creates controller"| node_controller
node_game -->|"registers states"| node_menu
node_game -->|"registers states"| node_loadscreen
node_game -->|"registers state"| node_level
node_controller -->|"dispatches states"| node_menu
node_controller -->|"dispatches states"| node_loadscreen
node_controller -->|"dispatches states"| node_level
node_level -->|"loads map data"| node_maps
node_level -->|"coordinates gameplay"| node_playerchar
node_level -->|"builds and checks"| node_terrain
node_level -->|"checks interactions"| node_boxes
node_level -->|"manages encounters"| node_enemy
node_level -->|"manages items"| node_powerups
node_level -->|"updates score"| node_coins
node_level -->|"builds world objects"| node_worldobjects
node_level -->|"updates HUD"| node_hud
node_loadscreen -->|"renders status"| node_hud
node_level -.->|"loads player settings"| node_playerdata

click node_launcher "https://github.com/marblexu/pythonsupermario/blob/master/main.py"
click node_game "https://github.com/marblexu/pythonsupermario/blob/master/source/main.py"
click node_controller "https://github.com/marblexu/pythonsupermario/blob/master/source/tools.py"
click node_assets "https://github.com/marblexu/pythonsupermario/blob/master/source/setup.py"
click node_constants "https://github.com/marblexu/pythonsupermario/blob/master/source/constants.py"
click node_menu "https://github.com/marblexu/pythonsupermario/blob/master/source/states/main_menu.py"
click node_loadscreen "https://github.com/marblexu/pythonsupermario/blob/master/source/states/load_screen.py"
click node_hud "https://github.com/marblexu/pythonsupermario/blob/master/source/components/info.py"
click node_level "https://github.com/marblexu/pythonsupermario/blob/master/source/states/level.py"
click node_maps "https://github.com/marblexu/pythonsupermario/tree/master/source/data/maps"
click node_playerdata "https://github.com/marblexu/pythonsupermario/tree/master/source/data/player"
click node_playerchar "https://github.com/marblexu/pythonsupermario/blob/master/source/components/player.py"
click node_terrain "https://github.com/marblexu/pythonsupermario/blob/master/source/components/brick.py"
click node_enemy "https://github.com/marblexu/pythonsupermario/blob/master/source/components/enemy.py"
click node_powerups "https://github.com/marblexu/pythonsupermario/blob/master/source/components/powerup.py"
click node_coins "https://github.com/marblexu/pythonsupermario/blob/master/source/components/coin.py"
click node_worldobjects "https://github.com/marblexu/pythonsupermario/blob/master/source/components/stuff.py"
click node_boxes "https://github.com/marblexu/pythonsupermario/blob/master/source/components/box.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_game,node_controller,node_assets,node_constants toneBlue
class node_level,node_maps,node_playerdata toneAmber
class node_playerchar,node_terrain,node_enemy,node_powerups,node_coins,node_worldobjects,node_boxes toneMint
class node_menu,node_loadscreen,node_hud toneRose
class node_player toneIndigo
```

## Components

### Game Runtime

- [Game entry](https://github.com/marblexu/pythonsupermario/blob/master/main.py): `main.py`
- [Game bootstrap](https://github.com/marblexu/pythonsupermario/blob/master/source/main.py): `source/main.py`
- [State controller](https://github.com/marblexu/pythonsupermario/blob/master/source/tools.py): `source/tools.py`
- [Pygame setup and assets](https://github.com/marblexu/pythonsupermario/blob/master/source/setup.py): `source/setup.py`
- [Game constants](https://github.com/marblexu/pythonsupermario/blob/master/source/constants.py): `source/constants.py`

### Level World

- [Level runtime](https://github.com/marblexu/pythonsupermario/blob/master/source/states/level.py): `source/states/level.py`
- [Level map data](https://github.com/marblexu/pythonsupermario/tree/master/source/data/maps): `source/data/maps`
- [Player data](https://github.com/marblexu/pythonsupermario/tree/master/source/data/player): `source/data/player`

### Game Entities

- [Player character](https://github.com/marblexu/pythonsupermario/blob/master/source/components/player.py): `source/components/player.py`
- [Bricks and boxes](https://github.com/marblexu/pythonsupermario/blob/master/source/components/brick.py): `source/components/brick.py`
- [Enemies](https://github.com/marblexu/pythonsupermario/blob/master/source/components/enemy.py): `source/components/enemy.py`
- [Power-ups and fireballs](https://github.com/marblexu/pythonsupermario/blob/master/source/components/powerup.py): `source/components/powerup.py`
- [Coins](https://github.com/marblexu/pythonsupermario/blob/master/source/components/coin.py): `source/components/coin.py`
- [World objects](https://github.com/marblexu/pythonsupermario/blob/master/source/components/stuff.py): `source/components/stuff.py`
- [Question boxes](https://github.com/marblexu/pythonsupermario/blob/master/source/components/box.py): `source/components/box.py`

### Screens and HUD

- [Main menu](https://github.com/marblexu/pythonsupermario/blob/master/source/states/main_menu.py): `source/states/main_menu.py`
- [Load and end screens](https://github.com/marblexu/pythonsupermario/blob/master/source/states/load_screen.py): `source/states/load_screen.py`
- [HUD and status](https://github.com/marblexu/pythonsupermario/blob/master/source/components/info.py): `source/components/info.py`

### Other components

- **Player**

## Connections

- Player → Game entry: starts game (evidence: `README.md`)
- Game entry → Game bootstrap: calls entry (evidence: `main.py`)
- Game bootstrap → State controller: creates controller (evidence: `source/main.py`)
- Game bootstrap → Main menu: registers states (evidence: `source/main.py`)
- Game bootstrap → Load and end screens: registers states (evidence: `source/main.py`)
- Game bootstrap → Level runtime: registers state (evidence: `source/main.py`)
- State controller → Main menu: dispatches states (evidence: `source/tools.py`)
- State controller → Load and end screens: dispatches states (evidence: `source/tools.py`)
- State controller → Level runtime: dispatches states (evidence: `source/tools.py`)
- Level runtime → Level map data: loads map data (evidence: `README.md`)
- Level runtime → Player character: coordinates gameplay (evidence: `source/states/level.py`)
- Level runtime → Bricks and boxes: builds and checks (evidence: `source/states/level.py`)
- Level runtime → Question boxes: checks interactions (evidence: `source/states/level.py`)
- Level runtime → Enemies: manages encounters (evidence: `source/states/level.py`)
- Level runtime → Power-ups and fireballs: manages items (evidence: `source/states/level.py`)
- Level runtime → Coins: updates score (evidence: `source/states/level.py`)
- Level runtime → World objects: builds world objects (evidence: `source/states/level.py`)
- Level runtime → HUD and status: updates HUD (evidence: `source/states/level.py`)
- Load and end screens → HUD and status: renders status (evidence: `source/states/load_screen.py`)
- Level runtime → Player data: loads player settings