# aadit-n3rdy/smart_asteroids architecture

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

- Interactive diagram: https://gitdiagram.com/aadit-n3rdy/smart_asteroids
- Repository: https://github.com/aadit-n3rdy/smart_asteroids

## Overview

#### Purpose and entry points
Smart Asteroids is a local Python/Pygame game where a player-controlled rocket fights asteroids whose movement behavior is driven by neural networks and improved through genetic evolution. The runnable entry point is `main.py`, with application startup likely delegated to `src/main.py`.

#### Game orchestration and state control
The central runtime loop and game-wide coordination live in `src/core/game.py`. It manages frame updates, input dispatch, entity lifecycles, collision/game-over conditions, and transitions between menu, active play, and paused/game-over states. State definitions or state-machine support are separated in `src/core/game_states.py`.

#### Player and combat entities
Gameplay actors are isolated under `src/entities/`:
- `src/entities/rocket.py` implements mouse-aimed player movement, thrust, and firing.
- `src/entities/bullet.py` represents player projectiles and their update/collision lifetime.
- `src/entities/asteroid.py` owns asteroid movement and likely exposes the inputs/fitness signals used by AI evolution.

The game loop is the boundary that creates, updates, renders, and removes these entities.

#### Neural-network-controlled asteroid behavior
`src/utils/neural_network.py` provides the model representation or inference/math used to map game observations into asteroid actions. Asteroids in `src/entities/asteroid.py` consume these networks during frame updates; the game supplies the world context needed for decisions, such as player position or survival/combat outcomes. `numpy` is a material dependency for this numerical layer.

#### Evolution framework
Evolution is deliberately modular:
- `src/evolution/base.py` defines the common evolution-strategy contract.
- `src/evolution/factory.py` selects an implementation from configuration.
- `src/evolution/crossover_evolution.py` creates offspring from high-performing parents.
- `src/evolution/tournament_evolution.py` selects candidates through tournament competition.

At generation boundaries, asteroid fitness/performance feeds the selected strategy; it returns new neural-network genomes/models for the next asteroid population. This keeps selection/reproduction independent of game rendering and core entity control.

#### Configuration and strategy boundary
`src/utils/constants.py` contains shared simulation settings, including the `EVOLUTION_STRATEGY` selector. The factory in `src/evolution/factory.py` is the architectural seam between fixed game orchestration and interchangeable genetic algorithms: adding a strategy should require implementing the base interface and registering it with the factory rather than changing entity logic.

#### UI, assets, and runtime dependencies
Pygame-ce provides the window, event loop, rendering, audio-capable runtime primitives, and input handling. `pygame-gui` supports structured UI screens:
- `src/ui/main_menu.py`
- `src/ui/user_guide.py`

Theme assets are externalized in `assets/themes/main_menu_theme.json`, `assets/themes/pause_menu_theme.json`, and `assets/themes/game_over_theme.json`; images and fonts are loaded from `assets/images` and `assets/fonts`. UI screens control transitions back into the core game/state layer rather than owning simulation logic.

Main entry points: [`src/core/game.py`](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/core/game.py) (Game loop), [`src/ui/main_menu.py`](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/ui/main_menu.py) (Main menu), [`src/evolution/base.py`](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/base.py) (Evolution contract), [`src/entities/asteroid.py`](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/asteroid.py) (Asteroid)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Launcher<br/>Python entry point<br/>[main.py]"]
  node_app["Application startup<br/>Python bootstrap<br/>[main.py]"]
  node_game["Game loop<br/>orchestrator<br/>[game.py]"]
  node_states["Game states<br/>state machine<br/>[game_states.py]"]
  node_pygame["Pygame-ce<br/>runtime dependency"]
end

subgraph group_gameplay["Gameplay &amp; AI"]
  node_rocket["Rocket<br/>player entity<br/>[rocket.py]"]
  node_bullet["Bullet<br/>projectile entity<br/>[bullet.py]"]
  node_asteroid["Asteroid<br/>AI entity<br/>[asteroid.py]"]
  node_network["Neural network<br/>model layer<br/>[neural_network.py]"]
  node_numpy["NumPy<br/>numerical dependency"]
end

subgraph group_evolution["Evolution"]
  node_constants["Simulation settings<br/>configuration<br/>[constants.py]"]
  node_evolution_base["Evolution contract<br/>strategy interface<br/>[base.py]"]
  node_evolution_factory["Strategy factory<br/>strategy selector<br/>[factory.py]"]
  node_crossover["Crossover evolution<br/>evolution strategy"]
  node_tournament["Tournament evolution<br/>evolution strategy"]
end

subgraph group_ui["UI &amp; Assets"]
  node_main_menu["Main menu<br/>UI screen<br/>[main_menu.py]"]
  node_user_guide["User guide<br/>UI screen<br/>[user_guide.py]"]
  node_pygame_gui["pygame-gui<br/>UI dependency"]
  node_themes["Menu themes<br/>theme asset"]
  node_media["Images &amp; fonts<br/>asset bundle"]
end

node_entry -->|"starts"| node_app
node_app -->|"initializes"| node_game
node_game -->|"runs on"| node_pygame
node_game -->|"transitions through"| node_states
node_game -->|"updates and renders"| node_rocket
node_game -->|"creates and manages"| node_bullet
node_game -->|"creates and manages"| node_asteroid
node_rocket -->|"fires"| node_bullet
node_asteroid -->|"uses for actions"| node_network
node_network -->|"computes with"| node_numpy
node_asteroid -->|"reports fitness to"| node_evolution_factory
node_constants -->|"selects strategy"| node_evolution_factory
node_evolution_factory -->|"returns contract"| node_evolution_base
node_crossover -->|"implements"| node_evolution_base
node_tournament -->|"implements"| node_evolution_base
node_evolution_base -->|"produces next genomes"| node_network
node_main_menu -->|"controls transitions"| node_game
node_user_guide -->|"returns to"| node_main_menu
node_main_menu -->|"uses"| node_pygame_gui
node_main_menu -->|"loads"| node_themes
node_game -->|"loads"| node_media

click node_entry "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/main.py"
click node_app "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/main.py"
click node_game "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/core/game.py"
click node_states "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/core/game_states.py"
click node_rocket "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/rocket.py"
click node_bullet "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/bullet.py"
click node_asteroid "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/asteroid.py"
click node_network "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/utils/neural_network.py"
click node_constants "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/utils/constants.py"
click node_evolution_base "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/base.py"
click node_evolution_factory "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/factory.py"
click node_crossover "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/crossover_evolution.py"
click node_tournament "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/tournament_evolution.py"
click node_main_menu "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/ui/main_menu.py"
click node_user_guide "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/ui/user_guide.py"
click node_themes "https://github.com/aadit-n3rdy/smart_asteroids/blob/master/assets/themes/main_menu_theme.json"

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_entry,node_app,node_game,node_states,node_pygame toneBlue
class node_rocket,node_bullet,node_asteroid,node_network,node_numpy toneAmber
class node_constants,node_evolution_base,node_evolution_factory,node_crossover,node_tournament toneMint
class node_main_menu,node_user_guide,node_pygame_gui,node_themes,node_media toneRose
```

## Components

### Runtime

- [Launcher](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/main.py): Python entry point · `main.py`
- [Application startup](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/main.py): Python bootstrap · `src/main.py`
- [Game loop](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/core/game.py): orchestrator · Coordinates frames, entities, collisions, and game lifecycle. · `src/core/game.py`
- [Game states](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/core/game_states.py): state machine · `src/core/game_states.py`
- **Pygame-ce**: runtime dependency · Provides windowing, rendering, events, and input.

### Gameplay & AI

- [Rocket](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/rocket.py): player entity · Mouse-aimed movement, thrust, and firing. · `src/entities/rocket.py`
- [Bullet](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/bullet.py): projectile entity · `src/entities/bullet.py`
- [Asteroid](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/entities/asteroid.py): AI entity · Uses network decisions and produces fitness signals. · `src/entities/asteroid.py`
- [Neural network](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/utils/neural_network.py): model layer · Maps game observations to asteroid actions. · `src/utils/neural_network.py`
- **NumPy**: numerical dependency

### Evolution

- [Simulation settings](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/utils/constants.py): configuration · Includes the evolution-strategy selector. · `src/utils/constants.py`
- [Evolution contract](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/base.py): strategy interface · `src/evolution/base.py`
- [Strategy factory](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/factory.py): strategy selector · Selects the configured genetic algorithm. · `src/evolution/factory.py`
- [Crossover evolution](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/crossover_evolution.py): evolution strategy · Produces offspring from high-performing parents. · `src/evolution/crossover_evolution.py`
- [Tournament evolution](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/evolution/tournament_evolution.py): evolution strategy · Selects candidates through tournament competition. · `src/evolution/tournament_evolution.py`

### UI & Assets

- [Main menu](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/ui/main_menu.py): UI screen · `src/ui/main_menu.py`
- [User guide](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/src/ui/user_guide.py): UI screen · `src/ui/user_guide.py`
- **pygame-gui**: UI dependency
- [Menu themes](https://github.com/aadit-n3rdy/smart_asteroids/blob/master/assets/themes/main_menu_theme.json): theme asset · Theme JSON defines menu, pause, and game-over presentation. · `assets/themes/main_menu_theme.json`
- **Images & fonts**: asset bundle

## Connections

- Launcher → Application startup: starts
- Application startup → Game loop: initializes
- Game loop → Pygame-ce: runs on
- Game loop → Game states: transitions through
- Game loop → Rocket: updates and renders
- Game loop → Bullet: creates and manages
- Game loop → Asteroid: creates and manages
- Rocket → Bullet: fires
- Asteroid → Neural network: uses for actions
- Neural network → NumPy: computes with
- Asteroid → Strategy factory: reports fitness to
- Simulation settings → Strategy factory: selects strategy
- Strategy factory → Evolution contract: returns contract
- Crossover evolution → Evolution contract: implements
- Tournament evolution → Evolution contract: implements
- Evolution contract → Neural network: produces next genomes
- Main menu → Game loop: controls transitions
- User guide → Main menu: returns to
- Main menu → pygame-gui: uses
- Main menu → Menu themes: loads
- Game loop → Images & fonts: loads