Project Architecture

Zero-Day Attack Project Architecture

Expert knowledge of the Zero-Day Attack Unity codebase structure, design patterns, and architectural decisions.

Design Principles

1. Separation of Concerns

The codebase organizes into distinct layers:

CRITICAL - State Ownership:

Anti-pattern: View layer (TokenManager) directly updating GameState or making game logic decisions. Always route state changes through GameManager.

2. Board SDK Isolation

Only InputManager.cs imports Board.Input namespace. This:

• Prevents SDK types leaking throughout codebase
• Enables testing without hardware
• Centralizes coordinate conversion

3. Singleton Managers

Core systems use singleton pattern with Instance property:

GameManager.Instance   // Game state and logic
TileManager.Instance   // Tile spawning, positioning
TokenManager.Instance  // Token spawning, input handling
InputManager.Instance  // Board SDK event broadcasting

4. ScriptableObject Databases

Game data stored in ScriptableObjects:

• TileDatabase - 25 tile definitions with sprites and paths
• TokenDatabase - 6 token definitions with sprites and glyph IDs

Namespace Organization

Namespace Rules

When creating new scripts:

• Place in appropriate namespace based on responsibility
• Use full namespace declaration: namespace ZeroDayAttack.View { }
• Editor scripts: ZeroDayAttack.Editor
• Test scripts: Match the namespace being tested

Folder Structure

Assets/Scripts/
├── Config/
│   └── LayoutConfig.cs              # Static layout constants
│
├── Core/
│   ├── GameManager.cs               # Game orchestrator singleton
│   ├── Data/                        # Immutable data structures
│   │   ├── Enums.cs                 # EdgeNode, PathColor, Player, etc.
│   │   ├── PathSegment.cs           # Path connection between nodes
│   │   ├── TileData.cs              # Tile definition
│   │   ├── TileDatabase.cs          # ScriptableObject: all tiles
│   │   ├── TokenData.cs             # Token definition
│   │   └── TokenDatabase.cs         # ScriptableObject: all tokens
│   └── State/                       # Mutable runtime state
│       ├── BoardState.cs            # Grid, reserves, deck
│       ├── GameState.cs             # Phase, current player
│       └── TokenState.cs            # Token position, ownership
│
├── View/                            # Visual components
│   ├── TileManager.cs               # Singleton: tile spawning
│   ├── TileView.cs                  # Individual tile visual
│   ├── TokenManager.cs              # Singleton: token spawning
│   ├── TokenView.cs                 # Individual token visual
│   ├── BackgroundRenderer.cs        # Board background
│   ├── CameraController.cs          # Camera setup
│   └── GridOverlayRenderer.cs       # Grid lines with glow
│
├── Input/
│   └── InputManager.cs              # Board SDK wrapper (ONLY Board.Input)
│
├── Diagnostics/
│   └── SceneDiagnostic.cs           # Runtime debug
│
└── Editor/
    ├── TileParser.cs                # Menu: ZeroDayAttack > Parse Tiles
    └── TokenParser.cs               # Menu: ZeroDayAttack > Parse Tokens

Class Responsibilities

Core Layer

Data Layer

View Layer

Input Layer

Data Flow

Board Hardware (touch/glyph)
         │
         ▼
    InputManager ← Only Board.Input import
         │
    ┌────┴────┐
    ▼         ▼
TokenManager  (Future: Tile touch)
    │
    ▼
GameManager ← Game logic decisions
    │
┌───┴───┐
▼       ▼
GameState  TileManager
BoardState (spawn tiles)
TokenState

Event-Driven State Updates

GameManager should expose events for state transitions:

// GameManager events
public event Action OnSetupComplete;
public event Action<TokenState> OnTokenPlaced;
public event Action<TokenState> OnTokenMoved;
public event Action<Player> OnTurnChanged;

Flow Example (Token Placement):

1. InputManager detects glyph, fires OnContactBegan
2. TokenManager receives event, calls GameManager.PlaceToken()
3. GameManager validates placement, updates GameState
4. GameManager fires OnTokenPlaced event
5. TokenManager (subscribed) updates visual position

Scene Hierarchy

GameplayScene
├── MainCamera [CameraController]
├── GlobalLight2D
├── GameManager [GameManager]
├── TileManager [TileManager]
├── TokenManager [TokenManager]
├── InputManager [InputManager]
├── BackgroundRenderer [BackgroundRenderer]
├── GridOverlayRenderer [GridOverlayRenderer]
├── Tiles (spawned at runtime)
└── Tokens (spawned at runtime)

Coordinate Systems

Grid Coordinates

• Origin: (0, 0) = bottom-left of 5×5 grid
• Range: (0, 0) to (4, 4)
• Center tile: (2, 2)

World Coordinates

• Origin: (0, 0) = screen center = grid center
• Grid spans: -5.0 to +5.0 in X and Y
• Tile size: 2.0 world units

Conversion

// Grid to World (via LayoutConfig)
float x = LayoutConfig.GridLeft + (gridX * LayoutConfig.TileSize) + (LayoutConfig.TileSize / 2f);
float y = LayoutConfig.GridBottom + (gridY * LayoutConfig.TileSize) + (LayoutConfig.TileSize / 2f);

Key Patterns

Creating New Managers

Follow singleton pattern:

public class NewManager : MonoBehaviour
{
    public static NewManager Instance { get; private set; }

    void Awake()
    {
        if (Instance != null) { Destroy(gameObject); return; }
        Instance = this;
    }
}

Creating New Data Types

For immutable data in Core/Data/:

namespace ZeroDayAttack.Core.Data
{
    [System.Serializable]
    public class NewData
    {
        public string Id;
        // Serialized fields...
    }
}

Creating New View Components

For visual components in View/:

namespace ZeroDayAttack.View
{
    public class NewView : MonoBehaviour
    {
        [SerializeField] private SpriteRenderer spriteRenderer;
        // View logic...
    }
}

Design Rationale

Key architectural decisions and their reasoning:

For full rationale with examples, see design-decisions.md in references.

Reference Files

This skill's references/ folder contains:

Key Source Files

When modifying architecture, review: