# maaxxe/projet_gymnasium architecture

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

- Interactive diagram: https://gitdiagram.com/maaxxe/projet_gymnasium
- Repository: https://github.com/maaxxe/projet_gymnasium
- Video tour (about a minute): https://gitdiagram.com/maaxxe/projet_gymnasium/video

## Overview

This repository contains separate custom DQN training projects for Donkey Kong and Ms. Pac-Man, plus a small random-action Atari demo. The main workflows collect game transitions, train agents from replay memory, and save models; Ms. Pac-Man additionally shapes rewards and trains Pac-Man and four simulated ghost agents. The graph follows the sampled training code and README’s stated Gymnasium/ALE context. Ms. Pac-Man’s network and replay-buffer implementations were not sampled, so their internal wiring is shown only where imports and calls support it.

Main entry points: [`ms_pacman/run.py`](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/run.py) (Multi-agent loop), [`Donkey_Kong/run.py`](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/run.py) (Training loop), [`Donkey_Kong/agent.py`](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/agent.py) (DQN agent), [`ms_pacman/mspacman_env.py`](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/mspacman_env.py) (Environment setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dk["Donkey Kong"]
  node_dk_run["Training loop<br/>[run.py]"]
  node_dk_env["Frame preprocessing<br/>[wrapper.py]"]
  node_dk_agent["DQN agent<br/>[agent.py]"]
  node_dk_net["Q networks<br/>[dqn_self.py]"]
  node_dk_replay["Replay memory<br/>[replay_buffer.py]"]
  node_dk_model["Saved model"]
  node_dk_manual["Manual play<br/>[DK.py]"]
end

subgraph group_pac["Ms Pac-Man"]
  node_pac_run["Multi-agent loop<br/>[run.py]"]
  node_pac_env["Environment setup<br/>[mspacman_env.py]"]
  node_pac_wall["Wall detection"]
  node_pac_agent["DQN agents<br/>[agent.py]"]
  node_pac_net["Q network<br/>[dqn_self.py]"]
  node_pac_replay["Replay memory<br/>[replay_buffer.py]"]
  node_pac_shape["Reward shaping<br/>[reward_shaping.py]"]
  node_pac_models["Agent checkpoints"]
  node_pac_progress["Episode progress<br/>[progression.txt]"]
end

subgraph group_demo["Atari Demo"]
  node_atari_demo["Random-action demo<br/>[atari.py]"]
end

node_user(("User"))
node_ale["Gymnasium ALE"]

node_user -->|"starts training"| node_dk_run
node_dk_run -->|"creates environment"| node_dk_env
node_dk_env -->|"wraps game"| node_ale
node_dk_run -->|"selects and trains"| node_dk_agent
node_dk_agent -->|"evaluates and updates"| node_dk_net
node_dk_agent -->|"stores and samples"| node_dk_replay
node_dk_run -->|"loads and saves"| node_dk_model
node_user -->|"starts training"| node_pac_run
node_pac_run -->|"creates environment"| node_pac_env
node_pac_env -->|"wraps actions"| node_pac_wall
node_pac_env -->|"wraps game"| node_ale
node_pac_run -->|"selects and trains"| node_pac_agent
node_pac_agent -->|"evaluates and updates"| node_pac_net
node_pac_agent -->|"stores and samples"| node_pac_replay
node_pac_run -->|"shapes rewards"| node_pac_shape
node_pac_run -->|"loads and saves"| node_pac_models
node_pac_run -->|"reads and writes"| node_pac_progress
node_user -->|"starts demo"| node_atari_demo
node_atari_demo -->|"steps game"| node_ale
node_user -->|"starts manual play"| node_dk_manual
node_dk_manual -->|"opens game"| node_ale

click node_dk_run "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/run.py"
click node_dk_env "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/wrapper.py"
click node_dk_agent "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/agent.py"
click node_dk_net "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/dqn_self.py"
click node_dk_replay "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/replay_buffer.py"
click node_dk_model "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/donkey_kong_dqn.pth"
click node_pac_run "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/run.py"
click node_pac_env "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/mspacman_env.py"
click node_pac_wall "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/wall_avoid_wrapper.py"
click node_pac_agent "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/agent.py"
click node_pac_net "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/dqn_self.py"
click node_pac_replay "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/replay_buffer.py"
click node_pac_shape "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/reward_shaping.py"
click node_pac_models "https://github.com/maaxxe/projet_gymnasium/tree/main/ms_pacman"
click node_pac_progress "https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/progression.txt"
click node_atari_demo "https://github.com/maaxxe/projet_gymnasium/blob/main/atari.py"
click node_dk_manual "https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/DK.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_dk_run,node_dk_env,node_dk_agent,node_dk_net,node_dk_replay,node_dk_model,node_dk_manual,node_user toneBlue
class node_pac_run,node_pac_env,node_pac_wall,node_pac_agent,node_pac_net,node_pac_replay,node_pac_shape,node_pac_models,node_pac_progress toneAmber
class node_atari_demo toneMint
class node_ale toneIndigo
```

## Components

### Donkey Kong

- [Training loop](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/run.py): `Donkey_Kong/run.py`
- [Frame preprocessing](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/wrapper.py): `Donkey_Kong/wrapper.py`
- [DQN agent](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/agent.py): `Donkey_Kong/agent.py`
- [Q networks](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/dqn_self.py): `Donkey_Kong/dqn_self.py`
- [Replay memory](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/replay_buffer.py): `Donkey_Kong/replay_buffer.py`
- [Saved model](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/donkey_kong_dqn.pth): `Donkey_Kong/donkey_kong_dqn.pth`
- [Manual play](https://github.com/maaxxe/projet_gymnasium/blob/main/Donkey_Kong/DK.py): `Donkey_Kong/DK.py`

### Ms Pac-Man

- [Multi-agent loop](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/run.py): `ms_pacman/run.py`
- [Environment setup](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/mspacman_env.py): `ms_pacman/mspacman_env.py`
- [Wall detection](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/wall_avoid_wrapper.py): `ms_pacman/wall_avoid_wrapper.py`
- [DQN agents](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/agent.py): `ms_pacman/agent.py`
- [Q network](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/dqn_self.py): `ms_pacman/dqn_self.py`
- [Replay memory](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/replay_buffer.py): `ms_pacman/replay_buffer.py`
- [Reward shaping](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/reward_shaping.py): `ms_pacman/reward_shaping.py`
- [Agent checkpoints](https://github.com/maaxxe/projet_gymnasium/tree/main/ms_pacman): `ms_pacman`
- [Episode progress](https://github.com/maaxxe/projet_gymnasium/blob/main/ms_pacman/progression.txt): `ms_pacman/progression.txt`

### Atari Demo

- [Random-action demo](https://github.com/maaxxe/projet_gymnasium/blob/main/atari.py): `atari.py`

### Other components

- **User**
- **Gymnasium ALE**

## Connections

- User → Training loop: starts training
- Training loop → Frame preprocessing: creates environment
- Frame preprocessing → Gymnasium ALE: wraps game
- Training loop → DQN agent: selects and trains
- DQN agent → Q networks: evaluates and updates
- DQN agent → Replay memory: stores and samples
- Training loop → Saved model: loads and saves
- User → Multi-agent loop: starts training
- Multi-agent loop → Environment setup: creates environment
- Environment setup → Wall detection: wraps actions
- Environment setup → Gymnasium ALE: wraps game
- Multi-agent loop → DQN agents: selects and trains
- DQN agents → Q network: evaluates and updates
- DQN agents → Replay memory: stores and samples
- Multi-agent loop → Reward shaping: shapes rewards
- Multi-agent loop → Agent checkpoints: loads and saves
- Multi-agent loop → Episode progress: reads and writes
- User → Random-action demo: starts demo
- Random-action demo → Gymnasium ALE: steps game
- User → Manual play: starts manual play
- Manual play → Gymnasium ALE: opens game