GDD

Unity-Architecture-Documentation

Updated:

PDT Cyberpunk Roguelike - Unity Architecture Documentation

Overview

This document outlines the system architecture for the PDT Cyberpunk Roguelike Unity project, designed to support a turn-based tactical grid combat game with roguelike progression mechanics.

Architecture Principles

1. Service-Oriented Architecture

  • Uses Service Locator pattern for dependency management
  • Promotes loose coupling between systems
  • Enables easy testing and system swapping

2. Event-Driven Communication

  • Event Bus system for decoupled inter-system communication
  • Type-safe event handling
  • Reduces direct dependencies between game systems

3. Modular Design

  • Clear separation of concerns across layers
  • Each system has well-defined responsibilities
  • Easy to extend and maintain

System Layers

Core Infrastructure Layer

Purpose: Provides fundamental services that all other systems depend on.

Bootstrapper (Bootstrapper.cs)

  • Responsibility: System initialization and startup sequence
  • Key Features:
    • Discovers and initializes all IInitializable components
    • Manages application startup flow
    • Loads initial scenes
  • Integration: Entry point for the entire application

Service Locator (ServiceLocator.cs)

  • Responsibility: Dependency injection and service discovery
  • Key Features:
    • Type-safe service registration/retrieval
    • Prevents duplicate service registration
    • Debug logging for service lifecycle
  • Pattern: Singleton service registry

Event Bus (EventBus.cs)

  • Responsibility: Decoupled communication between systems
  • Key Features:
    • Type-safe event publishing/subscribing
    • Generic event handling
    • Automatic cleanup of event listeners
  • Usage: Post structs / data from one system out to anything that wants to listen without direct dependancy

Object Pooling System

  • Responsibility: Performance optimization through object reuse
  • Key Features:
    • Configurable pool sizes
    • Automatic object lifecycle management
    • Memory optimization for frequently instantiated objects

Asset Management System

  • Responsibility: Centralized asset loading and management
  • Key Features:
    • Asset catalogue for organized resource management
    • Scene asset management
    • Async asset loading support

Logging System (LoggingSystem.cs)

  • Responsibility: Debug information and error tracking
  • Key Features:
    • Centralized logging interface
    • Debug build optimizations
    • Error tracking and reporting

Game Systems Layer

Purpose: Implements core game mechanics and logic.

Battle System

  • Responsibility: Grid-based tactical combat
  • Key Components:
    • Grid management and cell states
    • Turn-based combat flow
    • Unit positioning and movement
    • Ability execution and effects
  • Integration: Uses Event Bus for combat events, Service Locator for dependencies

Unit Management System

  • Responsibility: Character stats, abilities, and AI
  • Key Components:
    • Character stat management
    • Ability system implementation
    • AI behavior trees
    • Animation control integration
  • Data Flow: Receives input from Battle System, outputs to Presentation Layer

Progression System

  • Responsibility: Run management and character advancement
  • Key Components:
    • Run lifecycle management
    • Character upgrade systems
    • Permanent unlock progression
    • Pact of Punishment difficulty scaling
  • Persistence: Integrates with Save System for progress tracking

World Generation System

  • Responsibility: Procedural level and suburb generation
  • Key Components:
    • Suburb map generation
    • Procedural level creation
    • Grid layout algorithms
    • Environmental object placement
  • Integration: Feeds into Battle System for combat environments

Input System (InputManager.cs)

  • Responsibility: Player input handling and mapping
  • Key Components:
    • Action-based input system
    • Device-agnostic input handling
    • UI navigation support
    • Customizable control schemes
  • Integration: Invokes Actions to relevant systems that are listening / subscribed

Save System (JsonManager.cs)

  • Responsibility: Game state persistence
  • Key Components:
    • JSON-based data serialization
    • Run progress tracking
    • Settings and preferences storage
    • Cross-session data management
  • Integration: Used by Progression System and other persistent systems

Presentation Layer

Purpose: Handles all user-facing elements and feedback.

UI System

  • Responsibility: User interface and menu management
  • Key Components:
    • Menu navigation systems
    • Battle interface elements
    • HUD and status displays
    • Inventory and character screens
  • Integration: Listens to game events, updates visual elements

Audio System

  • Responsibility: Music and sound effect management
  • Key Components:
    • Dynamic music system
    • Spatial audio for combat
    • Audio mixing and balancing
    • Performance-optimized audio streaming
  • Integration: Responds to game events for audio cues

Visual Effects System

  • Responsibility: Particle effects and visual feedback
  • Key Components:
    • Combat effect particles
    • UI transitions and animations
    • Environmental effects
    • Performance-optimized effect pooling
  • Integration: Triggered by battle and progression events

Rendering Pipeline

  • Responsibility: Graphics rendering and optimization
  • Key Components:
    • URP (Universal Render Pipeline) integration
    • 2D/3D hybrid rendering
    • Post-processing effects
    • Performance optimization techniques
  • Integration: Works with all visual systems

External Systems Layer

Purpose: Integration with platform services and external libraries.

Platform Services

  • Responsibility: Platform-specific integrations
  • Key Components:
    • Steam/platform integration
    • Achievement system
    • Cloud save synchronization
    • Analytics and telemetry
  • Integration: Uses Service Locator for registration

External Libraries

  • Key Dependencies:
    • UniTask: For async/await operations
    • Unity Services: Platform integration
    • Input System: New Unity Input System
  • Purpose: Leverages proven solutions for common problems

Data Flow Patterns

1. Initialization Flow

Bootstrapper → Service Registration → System Initialization → Scene Loading

2. Game Loop Flow

Input → Event Bus → Game Systems → State Changes → UI Updates

3. Battle Flow

Input System → Battle System → Unit Management → Visual Effects → UI Updates

4. Progression Flow

Battle Results → Progression System → Save System → UI Updates

Key Design Decisions

Service Locator vs Dependency Injection

  • Decision: Service Locator pattern
  • Rationale: Simpler implementation, Unity-friendly, easier debugging
  • Trade-off: Less explicit dependencies but more flexible for Unity workflow

Event-Driven Architecture

  • Decision: Centralized Event Bus
  • Rationale: Decoupled communication, easier to extend systems
  • Trade-off: Slight performance overhead for maximum flexibility

Async Operations with UniTask

  • Decision: UniTask over Unity Coroutines
  • Rationale: Better async/await support, more performant, easier error handling
  • Benefit: Modern async programming patterns

JSON for Save Data

  • Decision: JSON over binary serialization
  • Rationale: Human-readable, easier debugging, version-friendly
  • Benefit: Better development experience and easier save system debugging

Performance Considerations

1. Object Pooling

  • All frequently instantiated objects use pooling
  • Reduces garbage collection pressure
  • Configurable pool sizes for different object types

2. Event System Optimization

  • Events are type-safe and use generics for performance
  • Automatic cleanup prevents memory leaks
  • Minimal boxing/unboxing overhead

3. Asset Loading

  • Async asset loading prevents frame drops
  • Asset catalogue enables efficient resource management
  • Scene-based asset organization

4. Rendering Optimization

  • URP provides better performance than built-in pipeline
  • Post-processing effects are performance-tuned
  • LOD and culling systems for complex scenes

Testing Strategy

Unit Testing

  • Service Locator functionality
  • Event Bus message passing
  • Game logic systems (battle calculations, progression)

Integration Testing

  • Cross-system communication via events
  • Save/load functionality
  • Scene transition workflows

Performance Testing

  • Object pooling efficiency
  • Memory allocation patterns
  • Frame rate consistency during gameplay

Future Extensibility

Adding New Systems

  1. Implement required interfaces (IService, IInitializable)
  2. Register with Service Locator
  3. Subscribe to relevant events
  4. Follow established patterns

Modding Support

  • Event system enables external mod integration
  • Service Locator allows system replacement
  • JSON save format supports custom data

Platform Extensions

  • Service-oriented design supports new platform integrations
  • Event system enables platform-specific features
  • Modular architecture supports different build targets

Development Guidelines

Code Organization

  • Follow existing namespace conventions
  • Group related systems in folders
  • Maintain clear separation of concerns

Performance Guidelines

  • Use object pooling for frequently created objects
  • Prefer events over direct method calls between systems
  • Cache frequently accessed services from Service Locator

Testing Guidelines

  • Write unit tests for core game logic
  • Test cross-system integration via events
  • Maintain test coverage for critical systems

This architecture provides a solid foundation for the cyberpunk roguelike game while maintaining flexibility for future expansion and modification.

Graph View