How p1manav/3d_space_shooter works
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