# p1manav/3d_space_shooter architecture

> Architecture diagram of the GitHub repository p1manav/3d_space_shooter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p1manav/3d_space_shooter
- Repository: https://github.com/p1manav/3d_space_shooter

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time 3D game built in Unity (C#) with an external Python-based reinforcement-learning (RL) backend.
- Unity handles rendering, physics, input, and gameplay logic; the Python server implements the Deep Q-Network (DQN), training loop, and model persistence.

##### File Structure
- Top-level “Assets” folder: Unity scenes, prefabs, materials, and key C# scripts (BotController.cs, PlayerController.cs, Bullet.cs, PositionSender.cs, etc.).
- Root-level Python scripts: dqn_server.py (dedicated DQN server), dqn model files (.pth), dqn_server communicates via TCP.
- ProjectSettings & Packages: Unity configuration for rendering pipeline, input, physics, and version control.
- ML-Agents folder & rl_server.py: earlier prototypes, now replaced by dqn_server.py.

##### README for Additional Insights
- README outlines:
- Unity side components & their responsibilities
- Python side: state encoding, action decoding, experience replay, model checkpoints, target network
- Communication protocol: TCP sockets, newline-terminated JSON messages

##### Main Components and Their Interactions
a. Unity Front-End
- GameObjects & Controllers
- PlayerController: reads user input, moves player ship, fires bullets.
- BotController: applies yaw/pitch/roll & shoot commands from RL server.
- Bullet: spawns projectiles, handles collisions, and reports hits back to RL server.
- PositionSender: serializes game state (positions, velocities, rotations) each frame into JSON and sends over TCP.
- Unity Engine Subsystems: Physics, Rendering, Input, Scene Manager.
b. Networking Layer
- TCP Client (Unity) ↔ TCP Server (Python).
- JSON messages terminated with “\n”; batching on Unity side to reduce latency.
c. Python Back-End (dqn_server.py)
- State Encoder: normalizes and packs Unity state into tensors.
- DQN Agent:
- Selects discrete action index → yaw/pitch/roll deltas + shoot flag.
- Maintains replay buffer, target network, training loop.
- Reward Shaper: computes rewards (alignment, distance, hit/miss penalties).
- Model Persistence:
- Loads latest checkpoint at startup.
- Saves full model and periodic checkpoints to disk (.pth files).
d. Data Store
- Model files on disk (bot_brain_latest.pth, checkpoints).
- Replay buffer (in-memory).

##### Architectural Patterns and Design Principles
- Client-Server: clear separation between game loop (Unity) and learning algorithm (Python).
- MVC-like in Unity: GameObjects (Model), Controllers (BotController, PlayerController), Renderer (View).
- Publish/Subscribe: PositionSender publishes state updates, Python server subscribes and returns actions; Bullet publishes hit events.
- Separation of Concerns: Unity handles deterministic simulation; Python handles stochastic learning.

##### Technologies, Frameworks, and Libraries
- Unity 2021+ with Universal Render Pipeline (URP)
- C# .NET sockets for TCP
- Python 3.x, PyTorch for DQN
- JSON for message serialization

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Unity Front-End"
        PhysicsRendering["Scene & Physics Engine"]:::unity
        PlayerController["PlayerController"]:::unity
        BotController["BotController"]:::unity
        PositionSender["PositionSender"]:::unity
        BulletHandler["Bullet Module"]:::unity
        Scenes["Scenes (Level1, Level2)"]:::unity
        URPSettings["URP Settings"]:::unity
    end

    subgraph "Python RL Server"
        TCPServer["TCP Server"]:::python
        StateEncoder["State Encoder"]:::python
        DQNAgent["DQN Agent"]:::python
        ActionDecoder["Action Decoder"]:::python
        RewardShaper["Reward Shaper"]:::python
        CheckpointManager["Checkpoint Manager"]:::python
    end

    ModelStorage["Model Persistence"]:::storage
    Legacy["ML-Agents Prototype"]:::legacy
    DrawIOSource["System Design Diagram"]:::doc

    PositionSender -->|"State JSON"| TCPServer
    TCPServer -->|"State JSON"| StateEncoder
    StateEncoder -->|tensors| DQNAgent
    DQNAgent -->|action index| ActionDecoder
    ActionDecoder -->|"Action JSON"| TCPServer
    TCPServer -->|"Action JSON"| BotController
    BulletHandler -->|"HitEvent JSON"| TCPServer
    CheckpointManager -->|"Save Model"| ModelStorage
    ModelStorage -->|"Load Model"| CheckpointManager

    classDef unity fill:#cfe2f3,stroke:#6fa8dc,stroke-width:1px
    classDef python fill:#d9ead3,stroke:#93c47d,stroke-width:1px
    classDef storage fill:#eeeeee,stroke:#aaaaaa,stroke-width:1px
    classDef legacy fill:#f4cccc,stroke:#e06666,stroke-width:1px
    classDef doc fill:#fff2cc,stroke:#f1c232,stroke-width:1px

    click PlayerController "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/PlayerController.cs"
    click BotController "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/BotController.cs"
    click BulletHandler "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/Bullet.cs"
    click bullet_prefab "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/bullet.prefab"
    click PositionSender "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/PositionSender.cs"
    click TCPServer "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click StateEncoder "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click DQNAgent "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click ActionDecoder "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click RewardShaper "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click CheckpointManager "https://github.com/p1manav/3d_space_shooter/blob/main/dqn_server.py"
    click bot_brain_pth "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/bot_brain.pth"
    click bot_brain_latest "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/bot_brain_latest.pth"
    click MLAgents "https://github.com/p1manav/3d_space_shooter/tree/main/Assets/ML-Agents"
    click DrawIOSource "https://github.com/p1manav/3d_space_shooter/blob/main/PPO_3D_Space_Shooter.drawio"
    click Scenes "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/Scenes/Level1.unity"
    click Scenes "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/Scenes/Level2.unity"
    click URPSettings "https://github.com/p1manav/3d_space_shooter/blob/main/Assets/Settings/UniversalRenderPipelineGlobalSettings.asset"
```
