DEVELOPER_GUIDE

Developer Guide

Complete Reference for Tower Defense Developers

Version: 1.0 Date: December 2025 Project: Procedurally Generated Tower Defense

---

Table of Contents

1. Getting Started

   • 1.1 Project Setup

   • 1.2 Required Tools

   • 1.3 First Launch Checklist

   • 1.4 Project Structure Overview

2. Project Structure

   • 2.1 Folder Organization

   • 2.2 Naming Conventions

   • 2.3 Asset Organization

3. Core Scripts Reference

   • 3.1 System Scripts

   • 3.2 Entity Scripts

   • 3.3 Manager Scripts

   • 3.4 Interface Scripts

   • 3.5 Utility Scripts

4. API Reference

   • 4.1 GameSystemsManager API

   • 4.2 MovementSystem API

   • 4.3 AttackSystem API

   • 4.4 ProjectileSystem API

   • 4.5 EffectSystem API

5. Development Workflows

   • 5.1 How to Add New Tower Type

   • 5.2 How to Add New Enemy Type

   • 5.3 How to Add New System

   • 5.4 How to Add New Targeting Strategy

   • 5.5 How to Add New Status Effect

   • 5.6 Safe Modification Points

6. Onboarding Timeline

   • 6.1 Day 1: Environment Setup

   • 6.2 Days 2-3: Code Exploration

   • 6.3 Week 1: First Task

   • 6.4 Week 2: Independent Development

7. Debugging & Maintenance

   • 7.1 Debugging Techniques

   • 7.2 Common Issues & Solutions

   • 7.3 Performance Profiling

   • 7.4 Code Review Checklist

8. Testing Guidelines

   • 8.1 Unit Testing Setup

   • 8.2 Integration Testing

   • 8.3 Performance Testing

---

1. Getting Started

1.1 Project Setup

Prerequisites

✅ Unity 2022.3 LTS or newer ✅ Universal Render Pipeline (URP) package ✅ Git (for version control) ✅ Visual Studio 2022 or Rider 2024 ✅ Windows 10/11, Mac, or Linux

Setup Steps

Step 1: Clone Repository

git clone https://github.com/aztoon-lab/unity-optimization-case-TD.git
cd procedural-tower-defense

Step 2: Open in Unity

1. Open Unity Hub

2. Click "Open" → Select project folder

3. Unity will import assets automatically (5-10 minutes first time)

Step 3: Verify URP Asset

1. Edit → Project Settings → Graphics

2. Verify URP Asset is assigned

3. Check SRP Batcher is enabled ✓

Step 4: First Run Test

1. Open scene: Assets/Scenes/MainGame.unity

2. Press Play

3. Expected: Game runs at 100+ FPS

📝 Note: If FPS is low (<60), check VSync settings: Edit → Project Settings → Quality → VSync Count: Don't Sync

---

1.2 Required Tools

Tool	Purpose	Location
Unity Profiler	Performance analysis	Window → Analysis → Profiler
Frame Debugger	Rendering optimization	Window → Analysis → Frame Debugger
Stats Window	Real-time FPS/batch monitoring	Game View → Stats
Console	Debug logs, errors, warnings	Window → General → Console

---

1.3 First Launch Checklist

✅ Game runs without errors ✅ FPS ≥100 in Game View ✅ Console shows system initialization logs:

[GameSystemsManager] Initialized 4 systems
[MovementSystem] Initialized
[AttackSystem] Initialized with 6 targeting strategies
[ProjectileSystem] Initialized
[EffectSystem] Initialized

✅ Towers can be placed on grid ✅ Enemies spawn and move ✅ Towers attack enemies ✅ Projectiles hit targets

---

1.4 Project Structure Overview

Assets/
├── Scenes/
│   └── MainGame.unity (main gameplay scene)
├── Scripts/
│   ├── Systems/              ⭐ CORE SYSTEMS
│   │   ├── GameSystemsManager.cs
│   │   ├── MovementSystem.cs
│   │   ├── AttackSystem.cs
│   │   ├── ProjectileSystem.cs
│   │   └── EffectSystem.cs
│   ├── Entities/             ⭐ GAME ENTITIES
│   │   ├── Enemy.cs
│   │   ├── Tower.cs
│   │   └── Projectile.cs
│   ├── Managers/             ⭐ GAMEPLAY MANAGERS
│   │   ├── WaveManager.cs
│   │   ├── BuildManager.cs
│   │   └── UIManager.cs
│   ├── Interfaces/           ⭐ CONTRACTS
│   │   ├── IGameSystem.cs
│   │   ├── IMoveable.cs
│   │   └── IAttacker.cs
│   └── Utilities/
│       ├── PoolManager.cs
│       └── GridGenerator.cs
├── Prefabs/
│   ├── Towers/
│   ├── Enemies/
│   └── Projectiles/
├── Materials/
└── URP/
    └── UniversalRenderPipelineAsset.asset

---

2. Project Structure

2.1 Folder Organization

/Scripts/Systems/ - Core Game Systems

Purpose: Centralized logic processors. Each system handles one responsibility.

Files:

• GameSystemsManager.cs - Master orchestrator

• MovementSystem.cs - Batch movement processing

• AttackSystem.cs - Combat & targeting

• ProjectileSystem.cs - Projectile lifecycle

• EffectSystem.cs - Status effects (burn, slow, etc.)

Rules:

• ✅ Systems implement IGameSystem

• ✅ No Update() - use Tick(deltaTime)

• ✅ Register/unregister entities via OnEnable/OnDisable

• ❌ Never directly reference other systems

---

/Scripts/Entities/ - Game Entities

Purpose: Data providers. Entities implement interfaces, contain no logic.

Files:

• Enemy.cs - Base enemy class

• Tower.cs - Base tower class

• Projectile.cs - Base projectile class

• StatusEffect.cs - Base effect class

Rules:

• ✅ Implement interfaces (IMoveable, IAttacker, etc.)

• ✅ Register with appropriate system in OnEnable()

• ❌ No Update() methods allowed

• ❌ No direct references to other entities

---

/Scripts/Interfaces/ - Contracts

Purpose: Define contracts for systems and entities.

Files:

• IGameSystem.cs - System lifecycle contract

• IMoveable.cs - Movement capability

• IAttacker.cs - Combat capability

• ITargetable.cs - Can be targeted

• IDamageable.cs - Can take damage

• IProjectile.cs - Projectile behavior

• IEffect.cs - Status effect behavior

• IPoolable.cs - Object pooling support

Rules:

• ✅ Interface segregation (small, focused interfaces)

• ✅ Properties only (no methods in data interfaces)

• ❌ No implementation logic in interfaces

---

/Scripts/Managers/ - Gameplay Managers

Purpose: High-level game flow control.

Files:

• WaveManager.cs - Enemy wave spawning

• BuildManager.cs - Tower placement

• UIManager.cs - UI updates

• GameState.cs - Game state persistence

• PoolManager.cs - Object pooling

Rules:

• ✅ Singleton pattern (managed lifetime)

• ✅ Event-driven communication

• ❌ No direct entity manipulation (use systems)

---

2.2 Naming Conventions

Type	Convention	Example
Classes	PascalCase	GameSystemsManager, Enemy
Interfaces	IPascalCase	IMoveable, IGameSystem
Public Fields/Props	PascalCase	Speed, AttackRange
Private Fields	camelCase	currentHealth, moveSpeed
Methods	PascalCase	RegisterMoveable(), Tick()
Constants	UPPER_SNAKE_CASE	MAX_ENEMIES, GRID_SIZE
Enums	PascalCase	TargetingMode, EffectType
Events	PascalCase + Event	OnEnemyDied, OnWaveComplete

---

2.3 Asset Organization

Prefabs

Prefabs/
├── Towers/
│   ├── BasicTower.prefab
│   ├── SniperTower.prefab
│   ├── SplashTower.prefab
│   └── ...
├── Enemies/
│   ├── Enemy.prefab
│   ├── FastEnemy.prefab
│   ├── TankEnemy.prefab
│   └── ...
├── Projectiles/
│   ├── Bullet.prefab
│   ├── Missile.prefab
│   └── ...
└── Effects/
    ├── BurnEffect.prefab
    ├── SlowEffect.prefab
    └── ...

ScriptableObjects

ScriptableObjects/
├── Towers/
│   ├── BasicTowerSO.asset
│   ├── SniperTowerSO.asset
│   └── ...
├── Enemies/
│   ├── FastEnemySO.asset
│   └── ...
└── Waves/
    ├── Wave1Config.asset
    └── ...

---

3. Core Scripts Reference

3.1 System Scripts

GameSystemsManager.cs

Location: Assets/Scripts/Systems/GameSystemsManager.cs

Purpose: Master orchestrator that manages all game systems. Handles initialization, execution order, and lifecycle.

Key Responsibilities:

• Initialize all systems on scene load

• Execute systems in priority order

• Manage system lifecycle (Initialize → Tick → Shutdown)

• Provide system lookup API

Architecture:

public class GameSystemsManager : MonoBehaviour
{
    [SerializeField] private MovementSystem movementSystem;
    [SerializeField] private AttackSystem attackSystem;
    [SerializeField] private ProjectileSystem projectileSystem;
    [SerializeField] private EffectSystem effectSystem;
    
    private List<IGameSystem> systems = new List<IGameSystem>();
    
    private void Awake()
    {
        InitializeSystems();
    }
    
    private void InitializeSystems()
    {
        // Create systems if not assigned
        // Register systems (sorted by Priority)
        // Call Initialize() on each
    }
    
    private void Update()
    {
        float deltaTime = Time.deltaTime;
        
        // Execute systems in priority order
        foreach (var system in systems)
        {
            if (system.IsActive)
            {
                system.Tick(deltaTime);
            }
        }
    }
}

Public API:

Method	Description	Returns
GetSystem<T>()	Retrieve specific system by type	T where T : IGameSystem
RegisterSystem(IGameSystem)	Add system to managed list	void

Usage Example:

// Get reference to AttackSystem
var attackSystem = GameSystemsManager.Instance.GetSystem<AttackSystem>();

// Check if system is active
if (attackSystem != null && attackSystem.IsActive)
{
    // Do something
}

⚠️ Critical Notes:

• ✅ GameSystemsManager MUST exist in every gameplay scene!

• ✅ Systems execute in priority order (0 = first)

• ❌ Do NOT modify Update() loop - breaks execution order

• ❌ Do NOT manually call Tick() - let manager handle it

Expected Console Output:

[GameSystemsManager] Initialized 4 systems
[MovementSystem] Initialized
[AttackSystem] Initialized with 6 targeting strategies
[ProjectileSystem] Initialized
[EffectSystem] Initialized

---

MovementSystem.cs

Location: Assets/Scripts/Systems/MovementSystem.cs

Purpose: Centralized movement processor for all entities implementing IMoveable. Eliminates individual Update() calls.

Priority: 0 (executes first)

Key Responsibilities:

• Batch process all moving entities

• Update entity positions

• Handle waypoint progression

• Notify entities on destination reached

Architecture:

public class MovementSystem : MonoBehaviour, IGameSystem
{
    public int Priority => 0; // Execute first
    public bool IsActive { get; set; } = true;
    
    private List<IMoveable> moveables = new List<IMoveable>();
    
    public void Initialize()
    {
        Debug.Log("[MovementSystem] Initialized");
    }
    
    public void Tick(float deltaTime)
    {
        // BATCH PROCESSING - single pass for ALL entities
        for (int i = 0; i < moveables.Count; i++)
        {
            IMoveable moveable = moveables[i];
            
            if (!moveable.IsMoving)
                continue;
            
            // Update position
            moveable.UpdatePosition(deltaTime);
        }
    }
    
    public void RegisterMoveable(IMoveable moveable)
    {
        if (!moveables.Contains(moveable))
        {
            moveables.Add(moveable);
            Debug.Log($"[MovementSystem] Registered: {moveable.Transform.name}");
        }
    }
    
    public void UnregisterMoveable(IMoveable moveable)
    {
        moveables.Remove(moveable);
    }
    
    public void Shutdown()
    {
        moveables.Clear();
    }
}

Public API:

Method	Parameters	Description	Returns
RegisterMoveable	IMoveable moveable	Add entity to movement processing	void
UnregisterMoveable	IMoveable moveable	Remove entity from processing	void
Tick	float deltaTime	Process all moving entities	void

Usage Example:

public class Enemy : MonoBehaviour, IMoveable
{
    private void OnEnable()
    {
        // Register with system when enabled
        MovementSystem.Instance?.RegisterMoveable(this);
    }
    
    private void OnDisable()
    {
        // CRITICAL: Unregister when disabled!
        MovementSystem.Instance?.UnregisterMoveable(this);
    }
    
    // IMoveable implementation
    public Transform Transform => transform;
    public float Speed => 5f;
    public bool IsMoving { get; set; } = true;
    
    public void UpdatePosition(float deltaTime)
    {
        // Move logic here
        transform.position += transform.forward * Speed * deltaTime;
    }
}

Performance Impact:

BEFORE: 50 enemies × Update() = 3,000 calls/sec
AFTER:  1 MovementSystem.Tick() = 60 calls/sec
REDUCTION: -98%

⚠️ Critical Notes:

• ✅ Always register in OnEnable(), not Start()

• ✅ Always unregister in OnDisable()

• ❌ Never call UpdatePosition() directly

• ❌ Never implement Update() in IMoveable entities

---

AttackSystem.cs

Location: Assets/Scripts/Systems/AttackSystem.cs

Purpose: Centralized combat processor. Handles targeting, cooldowns, and attack execution for all towers.

Priority: 1 (after movement)

Key Responsibilities:

• Manage attack cooldowns

• Target selection (6 strategies)

• Focus towers on targets

• Execute attacks

• Spatial optimization (coroutine-based scanning)

Architecture:

public class AttackSystem : MonoBehaviour, IGameSystem
{
    public int Priority => 1; // After movement
    public bool IsActive { get; set; } = true;
    
    private List<IAttacker> attackers = new List<IAttacker>();
    private Dictionary<IAttacker, List<ITargetable>> cachedTargets = 
        new Dictionary<IAttacker, List<ITargetable>>();
    
    // Targeting strategies (replaces LINQ!)
    private Dictionary<TargetingMode, ITargetingStrategy> strategies =
        new Dictionary<TargetingMode, ITargetingStrategy>();
    
    public void Initialize()
    {
        // Register targeting strategies
        strategies[TargetingMode.First] = new FirstTargetingStrategy();
        strategies[TargetingMode.Last] = new LastTargetingStrategy();
        strategies[TargetingMode.Closest] = new ClosestTargetingStrategy();
        strategies[TargetingMode.Furthest] = new FurthestTargetingStrategy();
        strategies[TargetingMode.Strongest] = new StrongestTargetingStrategy();
        strategies[TargetingMode.Weakest] = new WeakestTargetingStrategy();
        
        Debug.Log($"[AttackSystem] Initialized with {strategies.Count} targeting strategies");
    }
    
    public void Tick(float deltaTime)
    {
        // BATCH PROCESSING - process all attackers
        foreach (var attacker in attackers)
        {
            // 1. Update cooldown
            if (attacker.CurrentCooldown > 0f)
            {
                attacker.CurrentCooldown -= deltaTime;
                continue;
            }
            
            // 2. Target selection
            if (attacker.CurrentTarget == null || !IsValidTarget(attacker.CurrentTarget))
            {
                attacker.CurrentTarget = SelectTarget(attacker);
                
                if (attacker.CurrentTarget != null)
                {
                    attacker.OnTargetAcquired(attacker.CurrentTarget);
                }
                else
                {
                    attacker.OnTargetLost();
                }
            }
            
            // 3. Focus on target
            if (attacker.CurrentTarget != null)
            {
                attacker.FocusOnTarget(attacker.CurrentTarget.Position);
            }
            
            // 4. Perform attack
            if (attacker.CanAttack && attacker.CurrentTarget != null)
            {
                attacker.PerformAttack(attacker.CurrentTarget);
                attacker.CurrentCooldown = attacker.AttackCooldown;
                attacker.OnAttackCompleted();
            }
        }
    }
    
    private ITargetable SelectTarget(IAttacker attacker)
    {
        // Get cached targets for this attacker
        if (!cachedTargets.TryGetValue(attacker, out var targets) || targets.Count == 0)
            return null;
        
        // Use strategy (NO LINQ - manual iteration!)
        ITargetingStrategy strategy = strategies[attacker.TargetingMode];
        return strategy.SelectTarget(attacker, targets);
    }
    
    private bool IsValidTarget(ITargetable target)
    {
        return target != null && target.IsAlive;
    }
}

Public API:

Method	Parameters	Description	Returns
RegisterAttacker	IAttacker attacker	Add attacker to system	void
UnregisterAttacker	IAttacker attacker	Remove attacker from system	void
UpdateTargetsInRange	IAttacker attacker, List<ITargetable> targets	Update cached targets for attacker	void
Tick	float deltaTime	Process all attackers	void

Targeting Strategies:

Strategy	Description	Use Case
First	Targets enemy closest to goal (highest waypoint index)	Prevent early leaks
Last	Targets enemy furthest from goal (lowest waypoint index)	Clear backlog
Closest	Targets nearest enemy (SqrMagnitude)	Maximize DPS uptime
Furthest	Targets farthest enemy	Sniper towers
Strongest	Targets highest HP enemy	Focus fire tanks
Weakest	Targets lowest HP enemy	Clear low HP quickly

Usage Example:

public class Tower : MonoBehaviour, IAttacker
{
    [SerializeField] private float attackRange = 5f;
    [SerializeField] private float attackCooldown = 1f;
    [SerializeField] private TargetingMode targetingMode = TargetingMode.First;
    
    private void Start()
    {
        // Register with AttackSystem
        AttackSystem.Instance?.RegisterAttacker(this);
        
        // Start coroutine for target scanning
        StartCoroutine(UpdateTargetsCoroutine());
    }
    
    private IEnumerator UpdateTargetsCoroutine()
    {
        WaitForSeconds wait = new WaitForSeconds(0.2f); // 5 times/sec
        
        while (true)
        {
            yield return wait;
            
            // Scan for targets
            List<ITargetable> targets = new List<ITargetable>();
            Collider[] colliders = Physics.OverlapSphere(transform.position, attackRange);
            
            foreach (var col in colliders)
            {
                if (col.TryGetComponent<ITargetable>(out var targetable))
                {
                    targets.Add(targetable);
                }
            }
            
            // Update system cache
            AttackSystem.Instance?.UpdateTargetsInRange(this, targets);
        }
    }
    
    // IAttacker implementation
    public Transform Transform => transform;
    public float AttackRange => attackRange;
    public float AttackCooldown => attackCooldown;
    public float CurrentCooldown { get; set; }
    public ITargetable CurrentTarget { get; set; }
    public TargetingMode TargetingMode => targetingMode;
    public bool CanAttack => CurrentCooldown <= 0f;
    
    public void PerformAttack(ITargetable target)
    {
        // Spawn projectile, play effects, etc.
        var projectile = PoolManager.Instance.Pull(projectilePrefab);
        // Configure projectile...
    }
    
    public void FocusOnTarget(Vector3 targetPosition)
    {
        // Rotate tower to face target
        Vector3 direction = targetPosition - transform.position;
        Quaternion targetRotation = Quaternion.LookRotation(direction);
        rotationPart.rotation = Quaternion.Slerp(
            rotationPart.rotation, 
            targetRotation, 
            rotationSpeed * Time.deltaTime
        );
    }
    
    public void OnTargetAcquired(ITargetable target) { }
    public void OnTargetLost() { }
    public void OnAttackCompleted() { }
}

Performance Impact:

BEFORE: 
- 10 towers × FixedUpdate() = 500 calls/sec
- 10 towers × Update() = 600 calls/sec
- 500 LINQ operations/sec
TOTAL: 1,600 calls/sec

AFTER:
- 1 AttackSystem.Tick() = 60 calls/sec
- 50 coroutine updates/sec (target scanning)
TOTAL: 110 calls/sec

REDUCTION: -93%

⚠️ Critical Notes:

• ✅ Target scanning via coroutine, not FixedUpdate!

• ✅ Use SqrMagnitude for distance checks (avoid sqrt)

• ✅ Manual iteration, NO LINQ in hot paths

• ❌ Never call PerformAttack() directly

• ❌ Never implement Update() in towers

---

ProjectileSystem.cs

Location: Assets/Scripts/Systems/ProjectileSystem.cs

Purpose: Manages projectile lifecycle, pooling, and collision detection.

Priority: 2 (after attack)

Key Responsibilities:

• Batch process projectile movement

• Handle collision detection

• Manage projectile lifetime

• Object pooling integration

Architecture:

public class ProjectileSystem : MonoBehaviour, IGameSystem
{
    public int Priority => 2;
    public bool IsActive { get; set; } = true;
    
    private List<IProjectile> activeProjectiles = new List<IProjectile>();
    
    public void Tick(float deltaTime)
    {
        for (int i = activeProjectiles.Count - 1; i >= 0; i--)
        {
            IProjectile projectile = activeProjectiles[i];
            
            // Update lifetime
            projectile.CurrentLifetime += deltaTime;
            if (projectile.CurrentLifetime >= projectile.MaxLifetime)
            {
                // Return to pool
                PoolManager.Instance.Push(projectile.GameObject);
                activeProjectiles.RemoveAt(i);
                continue;
            }
            
            // Update movement
            projectile.UpdatePosition(deltaTime);
            
            // Check collision
            if (projectile.CheckHit(out ITargetable target))
            {
                projectile.OnHit(target);
                PoolManager.Instance.Push(projectile.GameObject);
                activeProjectiles.RemoveAt(i);
            }
        }
    }
    
    public void RegisterProjectile(IProjectile projectile)
    {
        if (!activeProjectiles.Contains(projectile))
        {
            activeProjectiles.Add(projectile);
        }
    }
    
    public void UnregisterProjectile(IProjectile projectile)
    {
        activeProjectiles.Remove(projectile);
    }
}

⚠️ Critical: Object Pooling Gotcha

// ❌ WRONG: Start() only runs ONCE per GameObject
void Start()
{
    rb.velocity = direction * speed; // Won't work after first spawn!
}

// ✅ CORRECT: OnEnable() runs every time pooled object is reused
void OnEnable()
{
    rb.velocity = direction * speed; // Works every spawn!
    currentLifetime = 0f;
}

Public API:

Method	Parameters	Description	Returns
RegisterProjectile	IProjectile projectile	Add projectile to tracking	void
UnregisterProjectile	IProjectile projectile	Remove projectile	void
Tick	float deltaTime	Process all projectiles	void

Usage Example:

public class Projectile : MonoBehaviour, IProjectile
{
    [SerializeField] private float speed = 10f;
    [SerializeField] private float maxLifetime = 5f;
    
    private Rigidbody rb;
    private Vector3 direction;
    
    private void Awake()
    {
        rb = GetComponent<Rigidbody>();
    }
    
    // ⚠️ CRITICAL: Use OnEnable for pooled objects!
    private void OnEnable()
    {
        // Register with system
        ProjectileSystem.Instance?.RegisterProjectile(this);
        
        // Reset state (runs every spawn)
        CurrentLifetime = 0f;
    }
    
    private void OnDisable()
    {
        ProjectileSystem.Instance?.UnregisterProjectile(this);
    }
    
    public void Launch(Vector3 targetDirection)
    {
        direction = targetDirection.normalized;
        rb.velocity = direction * speed;
    }
    
    // IProjectile implementation
    public GameObject GameObject => gameObject;
    public float CurrentLifetime { get; set; }
    public float MaxLifetime => maxLifetime;
    
    public void UpdatePosition(float deltaTime)
    {
        // Physics handles movement via Rigidbody
    }
    
    public bool CheckHit(out ITargetable target)
    {
        // Raycast or trigger check
        // ...
    }
    
    public void OnHit(ITargetable target)
    {
        // Deal damage, apply effects, etc.
        if (target is IDamageable damageable)
        {
            damageable.TakeDamage(damage);
        }
    }
}

---

EffectSystem.cs

Location: Assets/Scripts/Systems/EffectSystem.cs

Purpose: Centralized status effect processor (burn, slow, stun, poison, etc.).

Priority: 3 (after projectiles)

Key Responsibilities:

• Process DOT (damage over time)

• Update effect timers

• Manage effect stacking/overrides

• Clean up expired effects

Architecture:

public class EffectSystem : MonoBehaviour, IGameSystem
{
    public int Priority => 3;
    public bool IsActive { get; set; } = true;
    
    private List<IEffect> activeEffects = new List<IEffect>();
    
    public void Tick(float deltaTime)
    {
        for (int i = activeEffects.Count - 1; i >= 0; i--)
        {
            IEffect effect = activeEffects[i];
            
            // 1. Update duration
            if (!effect.IsInfinite)
            {
                effect.CurrentDuration -= deltaTime;
                
                if (effect.CurrentDuration <= 0f)
                {
                    // Effect expired
                    effect.ExpireEffect();
                    activeEffects.RemoveAt(i);
                    continue;
                }
            }
            
            // 2. Update tick timer
            effect.CurrentTickTime -= deltaTime;
            
            // 3. Perform tick if ready
            if (effect.CurrentTickTime <= 0f)
            {
                effect.PerformTick();
                effect.CurrentTickTime = effect.TickInterval;
            }
        }
    }
    
    public void RegisterEffect(IEffect effect)
    {
        if (!activeEffects.Contains(effect))
        {
            activeEffects.Add(effect);
            effect.OnEffectStarted();
        }
    }
    
    public void UnregisterEffect(IEffect effect)
    {
        activeEffects.Remove(effect);
        effect.OnEffectEnded();
    }
    
    public void ApplyEffect(GameObject target, IEffect effect)
    {
        // Apply effect to target
        RegisterEffect(effect);
    }
}

Public API:

Method	Parameters	Description	Returns
RegisterEffect	IEffect effect	Add effect to processing	void
UnregisterEffect	IEffect effect	Remove effect	void
ApplyEffect	GameObject target, IEffect effect	Apply effect to entity	void
Tick	float deltaTime	Process all effects	void

Usage Example:

public class BurnEffect : StatusEffect, IEffect
{
    [SerializeField] private float damagePerTick = 5f;
    
    protected override void Tick()
    {
        // Called by EffectSystem every tick interval
        if (affectedUnit is IDamageable damageable)
        {
            damageable.TakeDamage(damagePerTick);
        }
    }
    
    public override void Initialize(GameObject target, float duration)
    {
        base.Initialize(target, duration);
        
        // Register with system
        EffectSystem.Instance?.RegisterEffect(this);
    }
    
    public override void DestroyStatus()
    {
        // Unregister from system
        EffectSystem.Instance?.UnregisterEffect(this);
        
        base.DestroyStatus();
    }
    
    // IEffect implementation
    public float CurrentDuration { get; set; }
    public float CurrentTickTime { get; set; }
    public float TickInterval => 1f; // Tick every second
    public bool IsInfinite => false;
    
    public void PerformTick()
    {
        Tick(); // Call virtual method for subclasses
    }
    
    public void ExpireEffect()
    {
        OnEffectEnded();
        DestroyStatus();
    }
    
    public void OnEffectStarted() { }
    public void OnEffectEnded() { }
}

Performance Impact:

BEFORE: 30 StatusEffect × Update() = 1,800 calls/sec
AFTER:  1 EffectSystem.Tick() = 60 calls/sec
REDUCTION: -97%

---

3.2 Entity Scripts

Enemy.cs

Location: Assets/Scripts/Entities/Enemy.cs

Purpose: Base class for all enemy types. Implements IMoveable, IDamageable, ITargetable.

Key Responsibilities:

• Provide movement data to MovementSystem

• Handle damage reception

• Track health

• Emit death events

Architecture:

public class Enemy : MonoBehaviour, IMoveable, IDamageable, ITargetable
{
    [Header("Movement")]
    [SerializeField] protected float moveSpeed = 5f;
    
    [Header("Combat")]
    [SerializeField] protected float maxHealth = 100f;
    
    [Header("Rewards")]
    [SerializeField] protected int goldReward = 10;
    
    protected float currentHealth;
    
    protected virtual void Awake()
    {
        currentHealth = maxHealth;
    }
    
    protected virtual void OnEnable()
    {
        // Register with MovementSystem
        MovementSystem.Instance?.RegisterMoveable(this);
    }
    
    protected virtual void OnDisable()
    {
        // CRITICAL: Always unregister!
        MovementSystem.Instance?.UnregisterMoveable(this);
    }
    
    // IMoveable implementation
    public Transform Transform => transform;
    public float Speed => moveSpeed;
    public bool IsMoving { get; set; } = true;
    public Vector3 Direction { get; set; }
    
    public void UpdatePosition(float deltaTime)
    {
        // Move along path
        transform.position += Direction * Speed * deltaTime;
    }
    
    // IDamageable implementation
    public void TakeDamage(float amount)
    {
        currentHealth -= amount;
        
        if (currentHealth <= 0)
        {
            Die();
        }
    }
    
    // ITargetable implementation
    public Vector3 Position => transform.position;
    public bool IsAlive => currentHealth > 0;
    public int WaypointIndex { get; set; }
    
    protected virtual void Die()
    {
        // Award gold
        GameState.Instance.AddGold(goldReward);
        
        // Emit event
        OnEnemyDied?.Invoke(this);
        
        // Return to pool
        PoolManager.Instance.Push(gameObject);
    }
    
    public event Action<Enemy> OnEnemyDied;
}

How to Extend:

// Create subclass for enemy variants
public class FastEnemy : Enemy
{
    protected override void Awake()
    {
        base.Awake();
        
        // Override stats
        moveSpeed = 10f;  // 2x faster
        maxHealth = 50f;  // Half HP
        goldReward = 5;   // Less reward
    }
}

⚠️ Common Mistakes:

// ❌ WRONG: Implementing Update()
protected void Update()
{
    transform.position += Direction * Speed * Time.deltaTime;
}

// ✅ CORRECT: Let MovementSystem handle it
// (no Update method at all!)

// ❌ WRONG: Not unregistering
protected void OnDestroy()
{
    // Missing unregister - causes NullReferenceException!
}

// ✅ CORRECT: Always unregister in OnDisable()
protected virtual void OnDisable()
{
    MovementSystem.Instance?.UnregisterMoveable(this);
}

---

Tower.cs

Location: Assets/Scripts/Entities/Towers/Tower.cs

Purpose: Base class for all towers. Implements IAttacker.

Key Responsibilities:

• Provide attack data to AttackSystem

• Scan for targets (coroutine-based)

• Rotate to face targets

• Spawn projectiles

Architecture:

public class Tower : MonoBehaviour, IAttacker
{
    [Header("Attack")]
    [SerializeField] protected float attackRange = 5f;
    [SerializeField] protected float attackCooldown = 1f;
    [SerializeField] protected float damage = 10f;
    
    [Header("Targeting")]
    [SerializeField] protected TargetingMode targetingMode = TargetingMode.First;
    
    [Header("Projectile")]
    [SerializeField] protected GameObject projectilePrefab;
    [SerializeField] protected Transform shootAnchor;
    [SerializeField] protected float projectileSpeed = 15f;
    
    [Header("Rotation")]
    [SerializeField] protected Transform rotationPart;
    [SerializeField] protected float rotationSpeed = 5f;
    
    protected List<ITargetable> targetsInRange = new List<ITargetable>();
    
    protected virtual void Start()
    {
        // Register with AttackSystem
        AttackSystem.Instance?.RegisterAttacker(this);
        
        // Start target scanning coroutine
        StartCoroutine(UpdateTargetsCoroutine());
    }
    
    protected virtual IEnumerator UpdateTargetsCoroutine()
    {
        WaitForSeconds wait = new WaitForSeconds(0.2f); // 5 scans/sec
        
        while (true)
        {
            yield return wait;
            
            // Scan for targets
            targetsInRange.Clear();
            Collider[] colliders = Physics.OverlapSphere(
                transform.position, 
                attackRange, 
                LayerMask.GetMask("Enemy")
            );
            
            foreach (var col in colliders)
            {
                if (col.TryGetComponent<ITargetable>(out var targetable))
                {
                    targetsInRange.Add(targetable);
                }
            }
            
            // Update AttackSystem cache
            AttackSystem.Instance?.UpdateTargetsInRange(this, targetsInRange);
        }
    }
    
    // IAttacker implementation
    public Transform Transform => transform;
    public GameObject GameObject => gameObject;
    public float AttackRange => attackRange;
    public float AttackCooldown => attackCooldown;
    public float CurrentCooldown { get; set; }
    public bool CanAttack => CurrentCooldown <= 0f;
    public ITargetable CurrentTarget { get; set; }
    public TargetingMode TargetingMode => targetingMode;
    public float Damage => damage;
    public GameObject ProjectilePrefab => projectilePrefab;
    public Transform ShootAnchor => shootAnchor;
    
    public virtual void PerformAttack(ITargetable target)
    {
        // Spawn projectile from pool
        GameObject projObj = PoolManager.Instance.Pull(projectilePrefab);
        projObj.transform.position = shootAnchor.position;
        projObj.transform.rotation = shootAnchor.rotation;
        
        // Configure projectile
        if (projObj.TryGetComponent<Projectile>(out var projectile))
        {
            Vector3 direction = (target.Position - shootAnchor.position).normalized;
            projectile.Launch(direction, projectileSpeed, damage);
        }
    }
    
    public void FocusOnTarget(Vector3 targetPosition)
    {
        Vector3 direction = targetPosition - transform.position;
        direction.y = 0; // Keep horizontal
        
        if (direction != Vector3.zero)
        {
            Quaternion targetRotation = Quaternion.LookRotation(direction);
            rotationPart.rotation = Quaternion.Slerp(
                rotationPart.rotation,
                targetRotation,
                rotationSpeed * Time.deltaTime
            );
        }
    }
    
    public virtual void OnTargetAcquired(ITargetable target) { }
    public virtual void OnTargetLost() { }
    public virtual void OnAttackCompleted() { }
}

Tower Variants:

// BasicTower.cs - Standard damage, medium range
public class BasicTower : Tower
{
    // Uses base implementation
}

// SniperTower.cs - High damage, long range, slow fire rate
public class SniperTower : Tower
{
    protected override void Start()
    {
        base.Start();
        
        attackRange = 15f;
        attackCooldown = 3f;
        damage = 50f;
    }
}

// SplashTower.cs - AOE damage
public class SplashTower : Tower
{
    [SerializeField] private float splashRadius = 3f;
    
    public override void PerformAttack(ITargetable target)
    {
        base.PerformAttack(target);
        
        // Apply splash damage to nearby enemies
        Collider[] nearbyEnemies = Physics.OverlapSphere(
            target.Position, 
            splashRadius
        );
        
        foreach (var col in nearbyEnemies)
        {
            if (col.TryGetComponent<IDamageable>(out var damageable))
            {
                damageable.TakeDamage(damage * 0.5f); // Half damage to nearby
            }
        }
    }
}

// SlowTower.cs - Applies slow effect
public class SlowTower : Tower
{
    [SerializeField] private GameObject slowEffectPrefab;
    [SerializeField] private float slowDuration = 3f;
    
    public override void OnAttackCompleted()
    {
        base.OnAttackCompleted();
        
        // Apply slow effect
        if (CurrentTarget != null)
        {
            GameObject effectObj = Instantiate(slowEffectPrefab);
            var slowEffect = effectObj.GetComponent<SlowEffect>();
            slowEffect.Initialize(CurrentTarget.GameObject, slowDuration);
        }
    }
}

⚠️ Critical Notes:

• ✅ Target scanning via coroutine (not FixedUpdate!)

• ✅ Use WaitForSeconds to control scan frequency

• ✅ Always register with AttackSystem in Start()

• ❌ Never implement Update() or FixedUpdate()

• ❌ Never use LINQ for target sorting

---

Projectile.cs

Location: Assets/Scripts/Entities/Projectiles/Projectile.cs

Purpose: Base class for projectiles. Implements IProjectile.

Key Responsibilities:

• Move towards target

• Check collision

• Deal damage on hit

• Return to pool when expired

Architecture:

public class Projectile : MonoBehaviour, IProjectile
{
    [SerializeField] protected float speed = 15f;
    [SerializeField] protected float maxLifetime = 5f;
    [SerializeField] protected float damage = 10f;
    
    protected Rigidbody rb;
    protected Vector3 direction;
    protected float currentLifetime;
    
    protected virtual void Awake()
    {
        rb = GetComponent<Rigidbody>();
    }
    
    // ⚠️ CRITICAL: Use OnEnable for pooled objects!
    protected virtual void OnEnable()
    {
        // Register with system
        ProjectileSystem.Instance?.RegisterProjectile(this);
        
        // Reset state
        currentLifetime = 0f;
    }
    
    protected virtual void OnDisable()
    {
        // Unregister from system
        ProjectileSystem.Instance?.UnregisterProjectile(this);
    }
    
    public void Launch(Vector3 targetDirection, float launchSpeed, float dmg)
    {
        direction = targetDirection.normalized;
        speed = launchSpeed;
        damage = dmg;
        
        rb.velocity = direction * speed;
    }
    
    // IProjectile implementation
    public GameObject GameObject => gameObject;
    public float CurrentLifetime 
    { 
        get => currentLifetime;
        set => currentLifetime = value;
    }
    public float MaxLifetime => maxLifetime;
    
    public void UpdatePosition(float deltaTime)
    {
        // Physics handles movement via Rigidbody
        // Override for homing projectiles
    }
    
    public bool CheckHit(out ITargetable target)
    {
        target = null;
        
        // Raycast check
        RaycastHit hit;
        if (Physics.Raycast(transform.position, direction, out hit, speed * Time.deltaTime))
        {
            if (hit.collider.TryGetComponent<ITargetable>(out target))
            {
                return true;
            }
        }
        
        return false;
    }
    
    public void OnHit(ITargetable target)
    {
        // Deal damage
        if (target is IDamageable damageable)
        {
            damageable.TakeDamage(damage);
        }
        
        // Play hit effect
        // ...
    }
}

Projectile Variants:

// HomingProjectile.cs - Follows moving target
public class HomingProjectile : Projectile
{
    [SerializeField] private float homingStrength = 5f;
    
    private ITargetable target;
    
    public void SetTarget(ITargetable newTarget)
    {
        target = newTarget;
    }
    
    public override void UpdatePosition(float deltaTime)
    {
        if (target == null || !target.IsAlive)
        {
            // Target lost - continue straight
            return;
        }
        
        // Calculate direction to target
        Vector3 targetDirection = (target.Position - transform.position).normalized;
        
        // Blend current direction with target direction
        direction = Vector3.Lerp(direction, targetDirection, homingStrength * deltaTime).normalized;
        
        // Update velocity
        rb.velocity = direction * speed;
        
        // Rotate projectile
        transform.rotation = Quaternion.LookRotation(direction);
    }
}

// SplashProjectile.cs - AOE damage on impact
public class SplashProjectile : Projectile
{
    [SerializeField] private float splashRadius = 3f;
    [SerializeField] private float splashDamagePercent = 0.5f;
    
    public override void OnHit(ITargetable target)
    {
        base.OnHit(target); // Direct damage
        
        // Splash damage
        Collider[] nearby = Physics.OverlapSphere(target.Position, splashRadius);
        
        foreach (var col in nearby)
        {
            if (col.TryGetComponent<IDamageable>(out var damageable))
            {
                if (col.gameObject != target.GameObject)
                {
                    damageable.TakeDamage(damage * splashDamagePercent);
                }
            }
        }
    }
}

⚠️ Critical: Pooling Gotcha

// ❌ WRONG: Start() only runs ONCE per GameObject
void Start()
{
    rb.velocity = direction * speed; // Won't work after first spawn!
    currentLifetime = 0f;
}

// ✅ CORRECT: OnEnable() runs every time object is reused
void OnEnable()
{
    rb.velocity = direction * speed; // Works every spawn!
    currentLifetime = 0f;
    ProjectileSystem.Instance?.RegisterProjectile(this);
}

---

3.3 Manager Scripts

WaveManager.cs

Location: Assets/Scripts/Managers/WaveManager.cs

Purpose: Manages enemy wave spawning, difficulty scaling, and wave progression.

Key Responsibilities:

• Spawn waves of enemies

• Track wave progression

• Scale difficulty

• Emit wave events

Usage:

public class WaveManager : MonoBehaviour
{
    [SerializeField] private List<WaveConfig> waves = new List<WaveConfig>();
    
    private int currentWave = 0;
    private int enemiesRemaining = 0;
    
    public event Action<int> OnWaveStarted;
    public event Action<int> OnWaveCompleted;
    
    public void StartNextWave()
    {
        if (currentWave >= waves.Count)
        {
            // All waves completed
            OnAllWavesCompleted?.Invoke();
            return;
        }
        
        WaveConfig wave = waves[currentWave];
        enemiesRemaining = wave.enemyCount;
        
        OnWaveStarted?.Invoke(currentWave);
        
        StartCoroutine(SpawnWaveCoroutine(wave));
    }
    
    private IEnumerator SpawnWaveCoroutine(WaveConfig wave)
    {
        for (int i = 0; i < wave.enemyCount; i++)
        {
            // Spawn enemy
            GameObject enemyObj = PoolManager.Instance.Pull(wave.enemyPrefab);
            // Configure enemy...
            
            yield return new WaitForSeconds(wave.spawnInterval);
        }
    }
    
    public void OnEnemyDied(Enemy enemy)
    {
        enemiesRemaining--;
        
        if (enemiesRemaining <= 0)
        {
            OnWaveCompleted?.Invoke(currentWave);
            currentWave++;
        }
    }
}

---

BuildManager.cs

Location: Assets/Scripts/Managers/BuildManager.cs

Purpose: Handles tower placement on grid.

Key Responsibilities:

• Validate placement positions

• Spend currency

• Instantiate towers

• Update grid state

Usage:

public class BuildManager : MonoBehaviour
{
    [SerializeField] private LayerMask gridLayerMask;
    
    private TowerSO selectedTower;
    
    public void SelectTower(TowerSO towerSO)
    {
        selectedTower = towerSO;
    }
    
    public bool TryPlaceTower(Vector3 position)
    {
        // Check if position is valid
        if (!IsValidPlacement(position))
            return false;
        
        // Check if player has enough currency
        if (GameState.Instance.Gold < selectedTower.cost)
            return false;
        
        // Spawn tower
        GameObject towerObj = Instantiate(
            selectedTower.prefab,
            position,
            Quaternion.identity
        );
        
        // Spend currency
        GameState.Instance.SpendGold(selectedTower.cost);
        
        return true;
    }
    
    private bool IsValidPlacement(Vector3 position)
    {
        // Raycast to check for grid node
        RaycastHit hit;
        if (Physics.Raycast(position + Vector3.up * 10f, Vector3.down, out hit, 20f, gridLayerMask))
        {
            // Check if node is empty
            GridNode node = hit.collider.GetComponent<GridNode>();
            return node != null && !node.IsOccupied;
        }
        
        return false;
    }
}

---

UIManager.cs

Location: Assets/Scripts/Managers/UIManager.cs

Purpose: Updates UI elements based on game state.

Key Responsibilities:

• Display gold, health, wave number

• Update tower shop

• Show game over screen

Usage:

public class UIManager : MonoBehaviour
{
    [SerializeField] private TextMeshProUGUI goldText;
    [SerializeField] private TextMeshProUGUI waveText;
    [SerializeField] private TextMeshProUGUI healthText;
    
    private void OnEnable()
    {
        // Subscribe to events
        GameState.Instance.OnGoldChanged += UpdateGoldDisplay;
        WaveManager.Instance.OnWaveStarted += UpdateWaveDisplay;
        GameState.Instance.OnHealthChanged += UpdateHealthDisplay;
    }
    
    private void OnDisable()
    {
        // Unsubscribe from events
        GameState.Instance.OnGoldChanged -= UpdateGoldDisplay;
        WaveManager.Instance.OnWaveStarted -= UpdateWaveDisplay;
        GameState.Instance.OnHealthChanged -= UpdateHealthDisplay;
    }
    
    private void UpdateGoldDisplay(int gold)
    {
        goldText.text = $"Gold: {gold}";
    }
    
    private void UpdateWaveDisplay(int wave)
    {
        waveText.text = $"Wave {wave + 1}";
    }
    
    private void UpdateHealthDisplay(int health)
    {
        healthText.text = $"HP: {health}";
    }
}

---

3.4 Interface Scripts

Complete Interface Reference

// ========== SYSTEM INTERFACES ==========

/// <summary>
/// Base interface for all game systems.
/// Systems are centralized processors that handle specific gameplay aspects.
/// </summary>
public interface IGameSystem
{
    /// <summary>
    /// Execution priority. Lower values execute first.
    /// Typical values: MovementSystem=0, AttackSystem=1, ProjectileSystem=2, EffectSystem=3
    /// </summary>
    int Priority { get; }
    
    /// <summary>
    /// Whether system is currently active. Inactive systems don't execute Tick().
    /// </summary>
    bool IsActive { get; set; }
    
    /// <summary>
    /// Called once on system creation. Setup resources, register strategies, etc.
    /// </summary>
    void Initialize();
    
    /// <summary>
    /// Main update loop. Called every frame by GameSystemsManager.
    /// </summary>
    /// <param name="deltaTime">Time since last frame</param>
    void Tick(float deltaTime);
    
    /// <summary>
    /// Called on system shutdown. Cleanup resources, unregister entities.
    /// </summary>
    void Shutdown();
}

// ========== ENTITY INTERFACES ==========

/// <summary>
/// Entities that can move. Managed by MovementSystem.
/// </summary>
public interface IMoveable
{
    Transform Transform { get; }
    float Speed { get; }
    Vector3 Direction { get; set; }
    bool IsMoving { get; set; }
    
    /// <summary>
    /// Called by MovementSystem to update entity position.
    /// </summary>
    void UpdatePosition(float deltaTime);
}

/// <summary>
/// Entities that can attack. Managed by AttackSystem.
/// </summary>
public interface IAttacker
{
    Transform Transform { get; }
    GameObject GameObject { get; }
    
    // Attack properties
    float AttackRange { get; }
    float AttackCooldown { get; }
    float CurrentCooldown { get; set; }
    bool CanAttack { get; }
    
    // Targeting
    ITargetable CurrentTarget { get; set; }
    TargetingMode TargetingMode { get; }
    
    // Combat stats
    float Damage { get; }
    
    // Projectile data
    GameObject ProjectilePrefab { get; }
    Transform ShootAnchor { get; }
    
    /// <summary>
    /// Called by AttackSystem when cooldown ready and target valid.
    /// </summary>
    void PerformAttack(ITargetable target);
    
    /// <summary>
    /// Called by AttackSystem to rotate tower towards target.
    /// </summary>
    void FocusOnTarget(Vector3 targetPosition);
    
    /// <summary>
    /// Called when new target acquired.
    /// </summary>
    void OnTargetAcquired(ITargetable target);
    
    /// <summary>
    /// Called when target lost (died or out of range).
    /// </summary>
    void OnTargetLost();
    
    /// <summary>
    /// Called after attack completed.
    /// </summary>
    void OnAttackCompleted();
}

/// <summary>
/// Entities that can be targeted by attackers.
/// </summary>
public interface ITargetable
{
    Transform Transform { get; }
    GameObject GameObject { get; }
    Vector3 Position { get; }
    bool IsAlive { get; }
    
    /// <summary>
    /// Current waypoint index on path. Used by targeting strategies.
    /// </summary>
    int WaypointIndex { get; set; }
}

/// <summary>
/// Entities that can take damage.
/// </summary>
public interface IDamageable
{
    float MaxHealth { get; }
    float CurrentHealth { get; }
    
    void TakeDamage(float amount);
    void Heal(float amount);
}

/// <summary>
/// Projectiles managed by ProjectileSystem.
/// </summary>
public interface IProjectile
{
    GameObject GameObject { get; }
    float CurrentLifetime { get; set; }
    float MaxLifetime { get; }
    
    /// <summary>
    /// Called by ProjectileSystem to update position.
    /// </summary>
    void UpdatePosition(float deltaTime);
    
    /// <summary>
    /// Check if projectile hit something.
    /// </summary>
    bool CheckHit(out ITargetable target);
    
    /// <summary>
    /// Called when projectile hits target.
    /// </summary>
    void OnHit(ITargetable target);
}

/// <summary>
/// Status effects managed by EffectSystem.
/// </summary>
public interface IEffect
{
    GameObject TargetGameObject { get; }
    float CurrentDuration { get; set; }
    float CurrentTickTime { get; set; }
    float TickInterval { get; }
    bool IsInfinite { get; }
    
    /// <summary>
    /// Called by EffectSystem every tick interval.
    /// </summary>
    void PerformTick();
    
    /// <summary>
    /// Called when effect duration expires.
    /// </summary>
    void ExpireEffect();
    
    void OnEffectStarted();
    void OnEffectEnded();
}

/// <summary>
/// Objects that support pooling. Used with PoolManager.
/// </summary>
public interface IPoolable
{
    GameObject GameObject { get; }
    bool IsInPool { get; set; }
    
    /// <summary>
    /// Called when object pulled from pool.
    /// </summary>
    void OnSpawnedFromPool();
    
    /// <summary>
    /// Called when object returned to pool.
    /// </summary>
    void OnReturnedToPool();
}

// ========== STRATEGY INTERFACES ==========

/// <summary>
/// Target selection strategy. Used by AttackSystem.
/// </summary>
public interface ITargetingStrategy
{
    /// <summary>
    /// Select best target from available targets.
    /// </summary>
    ITargetable SelectTarget(IAttacker attacker, List<ITargetable> targets);
}

public enum TargetingMode
{
    First,      // Closest to goal (highest waypoint index)
    Last,       // Furthest from goal (lowest waypoint index)
    Closest,    // Nearest to tower (SqrMagnitude)
    Furthest,   // Farthest from tower
    Strongest,  // Highest HP
    Weakest     // Lowest HP
}

---

3.5 Utility Scripts

PoolManager.cs

Location: Assets/Scripts/Utilities/PoolManager.cs

Purpose: Object pooling to reduce Instantiate/Destroy overhead.

Usage:

// Pull object from pool
GameObject obj = PoolManager.Instance.Pull(prefab);

// Return object to pool
PoolManager.Instance.Push(obj);

// Pre-spawn pool (optional, at game start)
PoolManager.Instance.CreatePool(projectilePrefab, preSpawnAmount: 20);

---

GridGenerator.cs

Location: Assets/Scripts/Utilities/GridGenerator.cs

Purpose: Procedurally generate game grid at runtime.

Usage:

// Generate 32x32 grid
gridGenerator.GenerateGrid(32, 32);

---

4. API Reference

4.1 GameSystemsManager API

Public Methods

GetSystem<T>() where T : IGameSystem

Retrieve specific system by type.

Parameters: None

Returns: T - System instance, or null if not found

Example:

var attackSystem = GameSystemsManager.Instance.GetSystem<AttackSystem>();
if (attackSystem != null)
{
    attackSystem.IsActive = false; // Pause attacks
}

RegisterSystem(IGameSystem system)

Add system to managed list. Systems are automatically sorted by Priority.

Parameters:

• system - System to register

Returns: void

Example:

MyCustomSystem customSystem = gameObject.AddComponent<MyCustomSystem>();
GameSystemsManager.Instance.RegisterSystem(customSystem);

---

4.2 MovementSystem API

Public Methods

RegisterMoveable(IMoveable moveable)

Add entity to movement processing list.

Parameters:

• moveable - Entity implementing IMoveable

Returns: void

Example:

void OnEnable()
{
    MovementSystem.Instance?.RegisterMoveable(this);
}

UnregisterMoveable(IMoveable moveable)

Remove entity from movement processing.

Parameters:

• moveable - Entity to remove

Returns: void

Example:

void OnDisable()
{
    MovementSystem.Instance?.UnregisterMoveable(this);
}

---

4.3 AttackSystem API

Public Methods

RegisterAttacker(IAttacker attacker)

Add attacker to combat processing.

Parameters:

• attacker - Entity implementing IAttacker

Returns: void

Example:

void Start()
{
    AttackSystem.Instance?.RegisterAttacker(this);
}

UnregisterAttacker(IAttacker attacker)

Remove attacker from processing.

Parameters:

• attacker - Entity to remove

Returns: void

UpdateTargetsInRange(IAttacker attacker, List<ITargetable> targets)

Update cached targets for specific attacker. Called by tower's scan coroutine.

Parameters:

• attacker - Attacker whose targets to update

• targets - List of targetable entities in range

Returns: void

Example:

IEnumerator UpdateTargetsCoroutine()
{
    WaitForSeconds wait = new WaitForSeconds(0.2f);
    
    while (true)
    {
        yield return wait;
        
        // Scan for targets
        List<ITargetable> targets = ScanForTargets();
        
        // Update system cache
        AttackSystem.Instance?.UpdateTargetsInRange(this, targets);
    }
}

---

4.4 ProjectileSystem API

Public Methods

RegisterProjectile(IProjectile projectile)

Add projectile to lifecycle management.

Parameters:

• projectile - Entity implementing IProjectile

Returns: void

UnregisterProjectile(IProjectile projectile)

Remove projectile from processing.

Parameters:

• projectile - Entity to remove

Returns: void

---

4.5 EffectSystem API

Public Methods

RegisterEffect(IEffect effect)

Add status effect to processing.

Parameters:

• effect - Entity implementing IEffect

Returns: void

UnregisterEffect(IEffect effect)

Remove effect from processing.

Parameters:

• effect - Entity to remove

Returns: void

ApplyEffect(GameObject target, IEffect effect)

Apply status effect to specific target.

Parameters:

• target - GameObject to apply effect to

• effect - Effect to apply

Returns: void

Example:

// Apply burn effect to enemy
GameObject burnEffectObj = Instantiate(burnEffectPrefab);
BurnEffect burnEffect = burnEffectObj.GetComponent<BurnEffect>();
burnEffect.Initialize(enemy.gameObject, duration: 5f);

EffectSystem.Instance?.ApplyEffect(enemy.gameObject, burnEffect);

---

5. Development Workflows

5.1 How to Add New Tower Type

Step-by-Step Tutorial: Ice Tower

Goal: Create a tower that slows enemies by 50% for 3 seconds.

Step 1: Create Script

Create file: Assets/Scripts/Entities/Towers/IceTower.cs

using UnityEngine;

public class IceTower : Tower
{
    [Header("Ice Tower Settings")]
    [SerializeField] private float slowPercent = 0.5f; // 50% slow
    [SerializeField] private float slowDuration = 3f;
    [SerializeField] private GameObject slowEffectPrefab;
    
    public override void OnAttackCompleted()
    {
        base.OnAttackCompleted();
        
        // Apply slow effect to target
        if (CurrentTarget != null && CurrentTarget.GameObject != null)
        {
            ApplySlowEffect(CurrentTarget.GameObject);
        }
    }
    
    private void ApplySlowEffect(GameObject target)
    {
        // Check if target can be slowed
        if (!target.TryGetComponent<IMoveable>(out var moveable))
            return;
        
        // Instantiate slow effect
        GameObject effectObj = Instantiate(slowEffectPrefab);
        SlowEffect slowEffect = effectObj.GetComponent<SlowEffect>();
        
        if (slowEffect != null)
        {
            slowEffect.Initialize(target, slowDuration, slowPercent);
            EffectSystem.Instance?.ApplyEffect(target, slowEffect);
        }
    }
}

Step 2: Create Prefab

1. Create empty GameObject in scene: "IceTower"

2. Add components:

   • IceTower script

   • Add 3D model (or primitive Cube)

   • Add RotationPart child (for aiming)

   • Add ShootAnchor child (projectile spawn point)

3. Configure Inspector:

   • Attack Range: 6

   • Attack Cooldown: 1.5

   • Damage: 8

   • Targeting Mode: First

   • Projectile Prefab: IceProjectile (drag from Prefabs)

   • Slow Effect Prefab: SlowEffect (drag from Prefabs)

   • Rotation Part: Assign RotationPart child

   • Shoot Anchor: Assign ShootAnchor child

4. Save as prefab: Assets/Prefabs/Towers/IceTower.prefab

Step 3: Create ScriptableObject

1. Right-click in Project → Create → Scriptable Objects → Tower Data

2. Name: IceTowerSO

3. Configure:

   • Name: "Ice Tower"

   • Prefab: IceTower.prefab

   • Cost: 150

   • Description: "Slows enemies by 50%"

   • Icon: (assign sprite)

Step 4: Register in BuildManager

1. Open BuildManager in Inspector

2. Find "Available Towers" list

3. Add element → Drag IceTowerSO

Step 5: Test

1. Play game

2. Check shop - Ice Tower should appear

3. Place tower, verify it:

   • ✅ Appears in shop

   • ✅ Can be placed on grid

   • ✅ Attacks enemies

   • ✅ Enemies slow down when hit

   • ✅ Console shows: [AttackSystem] Registered: IceTower(Clone)

Expected Console Output:

[AttackSystem] Registered: IceTower(Clone)
[EffectSystem] Applied SlowEffect to Enemy(Clone)

---

5.2 How to Add New Enemy Type

Step-by-Step Tutorial: Tank Enemy

Goal: High HP, slow movement, high gold reward.

Step 1: Create Script

Create file: Assets/Scripts/Entities/Enemies/TankEnemy.cs

using UnityEngine;

public class TankEnemy : Enemy
{
    protected override void Awake()
    {
        base.Awake();
        
        // Override base stats
        moveSpeed = 2f;      // Slow (normal = 5f)
        maxHealth = 300f;    // High HP (normal = 100f)
        goldReward = 50;     // High reward (normal = 10)
        
        currentHealth = maxHealth;
    }
    
    protected override void Die()
    {
        // Optional: Special death effects
        // Spawn explosion, drop bonus items, etc.
        
        base.Die();
    }
}

Step 2: Create Prefab

1. Create GameObject: "TankEnemy"

2. Add components:

   • TankEnemy script

   • 3D model (make it look tanky!)

   • Collider (for targeting)

   • Health bar UI (optional)

3. Configure Inspector:

   • Layer: Enemy

   • (Stats auto-set in script)

4. Save as prefab: Assets/Prefabs/Enemies/TankEnemy.prefab

Step 3: Create Wave Configuration

1. Open WaveManager

2. Find wave where you want TankEnemy

3. Add to enemy spawn list:

   • Enemy Prefab: TankEnemy

   • Count: 5

   • Spawn Interval: 2 seconds

Step 4: Test

1. Play game

2. Start wave with TankEnemy

3. Verify:

   • ✅ Spawns correctly

   • ✅ Moves slowly

   • ✅ Takes lot of damage before dying

   • ✅ Awards 50 gold on death

   • ✅ Console: [MovementSystem] Registered: TankEnemy(Clone)

---

5.3 How to Add New System

Step-by-Step Tutorial: AbilitySystem

Goal: Centralize enemy ability processing (remove Update() from EnemyUnit.cs).

Step 1: Create Interface

Add to InterfaceDefinitions.cs:

public interface IAbilityUser
{
    GameObject GameObject { get; }
    float AbilityCooldown { get; }
    float CurrentAbilityCooldown { get; set; }
    bool CanUseAbility { get; }
    
    void UseAbility();
}

Step 2: Create System

Create file: Assets/Scripts/Systems/AbilitySystem.cs

using System.Collections.Generic;
using UnityEngine;

public class AbilitySystem : MonoBehaviour, IGameSystem
{
    public int Priority => 4; // After EffectSystem
    public bool IsActive { get; set; } = true;
    
    private List<IAbilityUser> abilityUsers = new List<IAbilityUser>();
    
    public void Initialize()
    {
        Debug.Log("[AbilitySystem] Initialized");
    }
    
    public void Tick(float deltaTime)
    {
        // BATCH PROCESSING
        foreach (var user in abilityUsers)
        {
            // Update cooldown
            if (user.CurrentAbilityCooldown > 0f)
            {
                user.CurrentAbilityCooldown -= deltaTime;
                continue;
            }
            
            // Use ability if ready
            if (user.CanUseAbility)
            {
                user.UseAbility();
                user.CurrentAbilityCooldown = user.AbilityCooldown;
            }
        }
    }
    
    public void RegisterAbilityUser(IAbilityUser user)
    {
        if (!abilityUsers.Contains(user))
        {
            abilityUsers.Add(user);
        }
    }
    
    public void UnregisterAbilityUser(IAbilityUser user)
    {
        abilityUsers.Remove(user);
    }
    
    public void Shutdown()
    {
        abilityUsers.Clear();
    }
}

Step 3: Register with GameSystemsManager

Modify GameSystemsManager.cs:

[SerializeField] private AbilitySystem abilitySystem; // Add field

private void InitializeSystems()
{
    // Create AbilitySystem if not assigned
    if (abilitySystem == null)
    {
        GameObject systemObj = new GameObject("AbilitySystem");
        systemObj.transform.SetParent(transform);
        abilitySystem = systemObj.AddComponent<AbilitySystem>();
    }
    
    // Register with other systems
    RegisterSystem(movementSystem);
    RegisterSystem(attackSystem);
    RegisterSystem(projectileSystem);
    RegisterSystem(effectSystem);
    RegisterSystem(abilitySystem); // Add here
    
    // ...rest of initialization
}

Step 4: Update Entities to Use System

Modify EnemyUnit.cs:

public class EnemyUnit : Enemy, IAbilityUser
{
    [Header("Ability")]
    [SerializeField] private float abilityCooldown = 5f;
    
    private float currentAbilityCooldown;
    
    protected override void OnEnable()
    {
        base.OnEnable();
        
        // Register with AbilitySystem
        AbilitySystem.Instance?.RegisterAbilityUser(this);
    }
    
    protected override void OnDisable()
    {
        base.OnDisable();
        
        AbilitySystem.Instance?.UnregisterAbilityUser(this);
    }
    
    // REMOVE Update() method - no longer needed!
    
    // IAbilityUser implementation
    public float AbilityCooldown => abilityCooldown;
    public float CurrentAbilityCooldown 
    { 
        get => currentAbilityCooldown;
        set => currentAbilityCooldown = value;
    }
    public bool CanUseAbility => currentAbilityCooldown <= 0f;
    
    public void UseAbility()
    {
        // Use ability logic here
        // Cast spell, spawn minion, etc.
    }
}

Step 5: Test

1. Play game

2. Check console:

   • ✅ [AbilitySystem] Initialized

   • ✅ [AbilitySystem] Registered: EnemyUnit(Clone)

3. Verify abilities still work

4. Check Profiler - Update() calls reduced

---

5.4 How to Add New Targeting Strategy

Step-by-Step Tutorial: RandomTargetingStrategy

Goal: Target random enemy (for fun/chaos towers).

Step 1: Create Strategy Class

Create file: Assets/Scripts/Systems/Targeting/RandomTargetingStrategy.cs

using System.Collections.Generic;
using UnityEngine;

public class RandomTargetingStrategy : ITargetingStrategy
{
    public ITargetable SelectTarget(IAttacker attacker, List<ITargetable> targets)
    {
        if (targets == null || targets.Count == 0)
            return null;
        
        // Select random target
        int randomIndex = Random.Range(0, targets.Count);
        return targets[randomIndex];
    }
}

Step 2: Add to TargetingMode Enum

Modify InterfaceDefinitions.cs:

public enum TargetingMode
{
    First,
    Last,
    Closest,
    Furthest,
    Strongest,
    Weakest,
    Random  // Add this
}

Step 3: Register in AttackSystem

Modify AttackSystem.Initialize():

public void Initialize()
{
    strategies[TargetingMode.First] = new FirstTargetingStrategy();
    strategies[TargetingMode.Last] = new LastTargetingStrategy();
    strategies[TargetingMode.Closest] = new ClosestTargetingStrategy();
    strategies[TargetingMode.Furthest] = new FurthestTargetingStrategy();
    strategies[TargetingMode.Strongest] = new StrongestTargetingStrategy();
    strategies[TargetingMode.Weakest] = new WeakestTargetingStrategy();
    strategies[TargetingMode.Random] = new RandomTargetingStrategy(); // Add this
    
    Debug.Log($"[AttackSystem] Initialized with {strategies.Count} targeting strategies");
}

Step 4: Use in Tower

public class ChaosTower : Tower
{
    protected override void Start()
    {
        base.Start();
        
        // Set targeting mode to Random
        targetingMode = TargetingMode.Random;
    }
}

Step 5: Test

1. Place ChaosTower

2. Watch it attack random enemies

3. Verify targets change unpredictably

---

5.5 How to Add New Status Effect

Step-by-Step Tutorial: Poison Effect

Goal: Deal 3 damage per second for 10 seconds.

Step 1: Create Effect Script

Create file: Assets/Scripts/StatusEffects/PoisonEffect.cs

using UnityEngine;

public class PoisonEffect : StatusEffect, IEffect
{
    [SerializeField] private float damagePerTick = 3f;
    [SerializeField] private float tickInterval = 1f; // 1 second
    
    protected override void Tick()
    {
        // Called by EffectSystem every tick
        if (affectedUnit is IDamageable damageable)
        {
            damageable.TakeDamage(damagePerTick);
            
            // Visual feedback
            ShowPoisonVFX();
        }
    }
    
    private void ShowPoisonVFX()
    {
        // Spawn poison cloud particles
        // Play poison sound
    }
    
    // IEffect implementation
    public float TickInterval => tickInterval;
    public GameObject TargetGameObject => affectedUnit?.gameObject;
    
    public override void Initialize(GameObject target, float duration)
    {
        base.Initialize(target, duration);
        
        // Register with EffectSystem
        EffectSystem.Instance?.RegisterEffect(this);
        
        // Visual: Change enemy color to green
        if (target.TryGetComponent<Renderer>(out var renderer))
        {
            renderer.material.color = Color.green;
        }
    }
    
    public override void DestroyStatus()
    {
        // Unregister from system
        EffectSystem.Instance?.UnregisterEffect(this);
        
        // Restore original color
        if (affectedUnit != null)
        {
            if (affectedUnit.TryGetComponent<Renderer>(out var renderer))
            {
                renderer.material.color = Color.white;
            }
        }
        
        base.DestroyStatus();
    }
}

Step 2: Create Prefab

1. Create GameObject: "PoisonEffect"

2. Add PoisonEffect script

3. Configure Inspector:

   • Damage Per Tick: 3

   • Tick Interval: 1

   • Add particle system (green poison cloud)

4. Save as prefab

Step 3: Use in Projectile/Tower

public class PoisonTower : Tower
{
    [SerializeField] private GameObject poisonEffectPrefab;
    [SerializeField] private float poisonDuration = 10f;
    
    public override void OnAttackCompleted()
    {
        base.OnAttackCompleted();
        
        if (CurrentTarget != null)
        {
            // Apply poison effect
            GameObject effectObj = Instantiate(poisonEffectPrefab);
            PoisonEffect poisonEffect = effectObj.GetComponent<PoisonEffect>();
            poisonEffect.Initialize(CurrentTarget.GameObject, poisonDuration);
        }
    }
}

Step 4: Test

1. Place PoisonTower

2. Attack enemy

3. Verify:

   • ✅ Enemy turns green

   • ✅ Takes 3 damage per second

   • ✅ Effect lasts 10 seconds

   • ✅ Console: [EffectSystem] Applied PoisonEffect

---

5.6 Safe Modification Points

✅ What You CAN Safely Change

Entity Stats:

• Health, speed, damage values in Inspector

• Cooldown timers

• Range values

• Costs and rewards

Prefabs:

• Visual meshes, materials, textures

• Particle effects

• Audio clips

• UI layouts

ScriptableObjects:

• Tower/Enemy configurations

• Wave setups

• Shop items

Constants:

• GRID_SIZE, MAX_ENEMIES, etc.

• Default values in scripts

UI:

• Text, colors, fonts

• Button positions

• HUD elements

Wave Configuration:

• Enemy counts

• Spawn intervals

• Wave progression

❌ What You Should NOT Change

System Architecture:

• GameSystemsManager Update() loop

• System Priority values (breaks execution order!)

• Interface definitions (breaks all implementations)

Registration Logic:

• OnEnable/OnDisable patterns

• Registration order

Object Pooling:

• Pool lifecycle (Start vs OnEnable)

• Return to pool logic

Batch Processing:

• System Tick() implementations

• Iteration patterns (manual, not LINQ)

Performance Critical:

• SqrMagnitude vs Distance

• Coroutine frequencies

• Cache invalidation logic

⚠️ Modify With Caution

Targeting Strategies:

• Can add new strategies

• Don't modify existing strategy logic without testing

Effect Processing:

• Can add new effects

• Don't change EffectSystem Tick() logic

Collision Detection:

• Can adjust layers

• Don't change detection method without profiling

---

6. Onboarding Timeline

6.1 Day 1: Environment Setup

Time: 2-4 hours

Tasks:

✅ Install Unity 2022.3 LTS ✅ Install Visual Studio 2022 or Rider 2024 ✅ Clone repository ✅ Open project in Unity ✅ Wait for asset import (5-10 minutes) ✅ Run first Play Mode test ✅ Verify FPS ≥100

Reading:

📖 Read README.md (5 minutes) 📖 Skim Architecture Handbook (30 minutes) 📖 Review this document: Chapters 1-2 (30 minutes)

Success Criteria:

• ✅ Game runs without errors

• ✅ Console shows system initialization logs

• ✅ Can place towers and start waves

• ✅ Understand folder structure

• ✅ Know where Systems, Entities, Managers are located

---

6.2 Days 2-3: Code Exploration

Time: 1-2 days

Tasks:

Day 2 Morning: Systems

📖 Read GameSystemsManager.cs - understand orchestration 📖 Read MovementSystem.cs - see batch processing 📖 Read AttackSystem.cs - understand targeting & cooldowns

Exercise: Add Debug.Log to each system's Tick() and watch execution order.

Day 2 Afternoon: Entities

📖 Read Enemy.cs - entity example 📖 Read Tower.cs - interface implementation 📖 Read Projectile.cs - pooling gotcha (OnEnable vs Start!)

Exercise: Create FastEnemy subclass (2x speed, half HP).

Day 3 Morning: Interfaces

📖 Review all interfaces in InterfaceDefinitions.cs 📖 Understand IMoveable, IAttacker, ITargetable, IEffect

Exercise: Implement mock interface for testing:

public class MockEnemy : ITargetable
{
    public Transform Transform => null;
    public GameObject GameObject => null;
    public Vector3 Position => Vector3.zero;
    public bool IsAlive => true;
    public int WaypointIndex { get; set; }
}

Day 3 Afternoon: Profiling

🔬 Open Unity Profiler (Window → Analysis → Profiler) 🔬 Run game, observe CPU Usage module 🔬 Look for MovementSystem.Tick, AttackSystem.Tick 🔬 Open Frame Debugger, verify batching

Exercise: Compare FPS with/without VSync enabled.

Success Criteria:

• ✅ Understand system-based architecture

• ✅ Can explain batch processing benefits

• ✅ Know difference between entity/system

• ✅ Familiar with all interfaces

• ✅ Can use Profiler to identify bottlenecks

---

6.3 Week 1: First Task

Time: 5 days

Assignment: Create Freeze Tower

Requirements:

1. Extends Tower class

2. Stops enemies for 2 seconds (speed = 0)

3. Uses FreezeTowerSO for configuration

4. Registers with AttackSystem

5. Applies FreezeEffect via EffectSystem

6. Visual: Enemy turns blue when frozen

Steps:

Day 4: Planning & Setup

• Read Section 5.1 (How to Add New Tower)

• Create FreezeTower.cs script

• Create FreezeEffect.cs script

• Define interface requirements

Day 5: Implementation

• Implement FreezeTower

• Implement FreezeEffect

• Register with systems

Day 6-7: Prefabs & Testing

• Create tower prefab

• Create effect prefab

• Create ScriptableObject

• Test in game

Day 8: Polish & Documentation

• Add visual effects (particles, shader)

• Add sound effects

• Write documentation (what changed, how to use)

• Code review with senior dev

Success Criteria:

✅ Tower appears in shop ✅ Can be placed on grid ✅ Attacks enemies in range ✅ Freeze effect applies (enemy stops moving) ✅ Effect expires after 2 seconds ✅ Console shows:

[AttackSystem] Registered: FreezeTower(Clone)
[EffectSystem] Applied FreezeEffect to Enemy(Clone)

✅ No errors in console ✅ FPS stable (≥100) ✅ Code follows naming conventions ✅ Documentation complete

---

6.4 Week 2: Independent Development

Time: 1 week

Assignment: Choose One

Pick one task based on your interests:

Option A: Gameplay Feature

Task: Create Lightning Tower

• Chains between enemies (hits up to 3 targets)

• Each chain does reduced damage (100%, 50%, 25%)

• Uses TargetingMode.Strongest

• Adds ChainLightningEffect for visual

Option B: System Enhancement

Task: Upgrade AttackSystem with Range Indicators

• Visual range circles around towers

• Color-coded by tower type

• Toggle on/off with hotkey

Option C: Performance Optimization

Task: Implement Spatial Hashing

• Replace Physics.OverlapSphere in towers

• Use grid-based spatial hash

• Measure FPS improvement

Deliverables:

1. Code Implementation

   • Clean, commented code

   • Follows naming conventions

   • No warnings in console

2. Testing Report

   • Test cases documented

   • Edge cases handled

   • Performance metrics (if applicable)

3. Documentation

   • README with screenshots

   • Usage instructions

   • Known limitations

4. Code Review

   • Present to senior developer

   • Answer questions about design choices

   • Incorporate feedback

Success Criteria:

✅ Feature complete and working ✅ Zero console errors/warnings ✅ Passes code review ✅ Documentation clear and accurate ✅ Tests written and passing ✅ FPS impact measured (if performance-related)

---

7. Debugging & Maintenance

7.1 Debugging Techniques

Console Logs to Watch

Expected on Game Start:

[GameSystemsManager] Initialized 4 systems
[MovementSystem] Initialized
[AttackSystem] Initialized with 6 targeting strategies
[ProjectileSystem] Initialized
[EffectSystem] Initialized

Expected on Entity Spawn:

[MovementSystem] Registered: Enemy(Clone)
[AttackSystem] Registered: Tower(Clone)
[ProjectileSystem] Registered: Projectile(Clone)
[EffectSystem] Applied BurnEffect to Enemy(Clone)

Debugging Tools

Unity Profiler

How to Use:

1. Window → Analysis → Profiler

2. Play game

3. Click slow frame in timeline

4. Expand CPU Usage module

5. Look for expensive methods

What to Look For:

• AttackSystem.Tick > 1ms = suspicious

• MovementSystem.Tick > 0.5ms = check entity count

• Any Update() methods = should be removed!

Frame Debugger

How to Use:

1. Window → Analysis → Frame Debugger

2. Click "Enable"

3. Game pauses, shows every draw call

What to Look For:

• Batches ~2,000 = good

• Batches >5,000 = investigate

• Look for "SRP Batch" groups = good!

• Separate draw calls for same material = bad

Stats Window

How to Use:

1. Game View → Stats button (top right)

2. Displays real-time metrics

What to Monitor:

• FPS: Should be 100+ (with VSync off)

• Batches: Target ~2,000

• Tris: Keep under 1M

• Saved by batching: Higher = better

---

7.2 Common Issues & Solutions

Issue: Enemies don't move

Symptom: Enemies spawn but stand still

Possible Causes:

1. MovementSystem not in scene

2. Enemy not implementing IMoveable correctly

3. Enemy not registering with system

Solution:

// Check 1: Is GameSystemsManager in scene?
GameObject gsm = GameObject.Find("GameSystemsManager");
if (gsm == null)
{
    Debug.LogError("GameSystemsManager not found in scene!");
}

// Check 2: Is Enemy implementing IMoveable?
// Verify Enemy.cs has:
public class Enemy : MonoBehaviour, IMoveable { }

// Check 3: Is registration happening?
protected virtual void OnEnable()
{
    Debug.Log("Enemy OnEnable - Registering with MovementSystem");
    MovementSystem.Instance?.RegisterMoveable(this);
}

---

Issue: Towers don't attack

Symptom: Towers placed, enemies in range, but no attacks

Possible Causes:

1. AttackSystem not in scene

2. Tower not registering

3. Target scan coroutine not running

4. Projectile prefab not assigned

Solution:

// Check 1: AttackSystem exists?
if (AttackSystem.Instance == null)
{
    Debug.LogError("AttackSystem not found!");
}

// Check 2: Tower registering?
protected virtual void Start()
{
    Debug.Log($"Tower Start - Registering {name}");
    AttackSystem.Instance?.RegisterAttacker(this);
    StartCoroutine(UpdateTargetsCoroutine());
}

// Check 3: Coroutine running?
protected virtual IEnumerator UpdateTargetsCoroutine()
{
    Debug.Log($"Tower scan coroutine started: {name}");
    // ...
}

// Check 4: Projectile prefab assigned?
if (projectilePrefab == null)
{
    Debug.LogError($"Tower {name} missing projectile prefab!");
}

---

Issue: Projectiles don't move after first spawn

Symptom: First projectile works, subsequent spawns don't move

Cause: Using Start() instead of OnEnable() for pooled objects

Solution:

// ❌ WRONG:
void Start()
{
    rb.velocity = direction * speed; // Only runs once!
}

// ✅ CORRECT:
void OnEnable()
{
    rb.velocity = direction * speed; // Runs every spawn!
    currentLifetime = 0f;
    ProjectileSystem.Instance?.RegisterProjectile(this);
}

---

Issue: Low FPS (<100)

Symptom: Game runs slowly, FPS below 100

Possible Causes:

1. VSync enabled

2. Update() methods in entities

3. Too many enemies/towers

4. Shadow casters not optimized

5. Batching broken

Solutions:

// Check 1: Disable VSync
// Edit → Project Settings → Quality
// VSync Count: Don't Sync

// Check 2: Search for Update() in entities
// ❌ Bad: Enemy.cs has Update()
// ✅ Good: Enemy.cs has NO Update()

// Check 3: Profile with Profiler
// Window → Analysis → Profiler
// Look for CPU spike

// Check 4: Check shadow casters
// Select Grid Node prefab
// Mesh Renderer → Cast Shadows: Off

// Check 5: Verify SRP Batcher
// Frame Debugger → Look for "SRP Batch" groups

---

Issue: NullReferenceException in System

Symptom: Error: NullReferenceException: Object reference not set to an instance

Common Cause: Entity destroyed but not unregistered from system

Solution:

// ALWAYS unregister in OnDisable()
protected virtual void OnDisable()
{
    MovementSystem.Instance?.UnregisterMoveable(this);
    AttackSystem.Instance?.UnregisterAttacker(this);
    ProjectileSystem.Instance?.UnregisterProjectile(this);
    EffectSystem.Instance?.UnregisterEffect(this);
}

// Use null-conditional operator (?)
public void Tick(float deltaTime)
{
    foreach (var entity in entities)
    {
        if (entity?.GameObject == null) // Check for null!
        {
            entities.Remove(entity);
            continue;
        }
        
        // Process entity...
    }
}

---

Issue: Effects not expiring

Symptom: Burn/slow effects never expire, stay forever

Cause: EffectSystem not ticking, or effect not unregistering

Solution:

// Check 1: Is EffectSystem active?
if (!EffectSystem.Instance.IsActive)
{
    Debug.LogError("EffectSystem is inactive!");
}

// Check 2: Effect unregistering on destroy?
public override void DestroyStatus()
{
    EffectSystem.Instance?.UnregisterEffect(this);
    base.DestroyStatus();
}

// Check 3: Duration being updated?
public void Tick(float deltaTime)
{
    if (!effect.IsInfinite)
    {
        effect.CurrentDuration -= deltaTime; // This must happen!
    }
}

---

7.3 Performance Profiling

Quick Profiling Checklist

CPU Performance

1. Unity Profiler → CPU Usage

   • Look for methods taking >1ms

   • Check GameSystemsManager.Update() time

   • Verify systems execute in order

2. Expected Values:

   • MovementSystem.Tick: 0.1-0.5ms

   • AttackSystem.Tick: 0.2-0.8ms

   • ProjectileSystem.Tick: 0.1-0.4ms

   • EffectSystem.Tick: 0.1-0.3ms

3. Red Flags:

   • Any Update() in entity scripts

   • LINQ operations in Tick()

   • GetComponent in hot paths

   • Instantiate/Destroy (should use pooling)

GPU Performance

1. Frame Debugger

   • Check batch count (~2,000 is good)

   • Look for "SRP Batch" groups

   • Verify static batching working

2. Stats Window

   • Batches: ~2,000

   • Saved by batching: 1,000+

   • SetPass calls: <500

   • Tris: <1M

3. Red Flags:

   • Batches >5,000

   • No SRP batching

   • Each object = separate draw call

Memory Performance

1. Profiler → Memory

   • Check GC allocations per frame

   • Should be <1KB/frame

2. Red Flags:

   • GC allocations every frame

   • Memory growing over time (leak)

   • Frequent GC.Collect (>1 per second)

Profiling Workflow

1. Record baseline (Wave 2, 10 enemies)
   ↓
2. Play to Wave 7 (high load)
   ↓
3. Pause, examine Profiler
   ↓
4. Identify bottleneck (CPU vs GPU)
   ↓
5. Make targeted fix
   ↓
6. Measure again, compare
   ↓
7. Verify no regression

---

7.4 Code Review Checklist

Before Submitting Code

Architecture

• Entity implements correct interfaces?

• No Update() methods in entities?

• System registered with GameSystemsManager?

• Priority set correctly?

Registration

• OnEnable() registers with system?

• OnDisable() unregisters from system?

• No Start() logic that should be in OnEnable()?

Performance

• No LINQ in hot paths?

• Using SqrMagnitude instead of Distance?

• No GetComponent in Tick()?

• Object pooling used for frequent spawns?

Error Handling

• Null checks before accessing references?

• Try-catch for risky operations?

• Graceful degradation if system missing?

Code Quality

• Follows naming conventions?

• Public API documented with XML comments?

• Constants used instead of magic numbers?

• No code duplication?

Testing

• Tested with 1 entity?

• Tested with 100 entities?

• Tested scene transitions?

• Tested object pooling (spawn/despawn cycle)?

---

8. Testing Guidelines

8.1 Unit Testing Setup

Installing Unity Test Framework

1. Window → Package Manager

2. Search "Test Framework"

3. Install

Creating Test Assembly

1. Create folder: Assets/Tests/

2. Right-click → Create → Testing → Tests Assembly Folder

3. Two assemblies created:

   • EditMode/ - Editor tests

   • PlayMode/ - Runtime tests

Example Test: MovementSystem

using NUnit.Framework;
using UnityEngine;

public class MovementSystemTests
{
    private GameObject systemObj;
    private MovementSystem system;
    
    [SetUp]
    public void Setup()
    {
        systemObj = new GameObject("MovementSystem");
        system = systemObj.AddComponent<MovementSystem>();
        system.Initialize();
    }
    
    [TearDown]
    public void Teardown()
    {
        Object.Destroy(systemObj);
    }
    
    [Test]
    public void RegisterMoveable_AddsToList()
    {
        // Arrange
        MockMoveable moveable = new MockMoveable();
        
        // Act
        system.RegisterMoveable(moveable);
        
        // Assert
        Assert.IsTrue(system.GetMoveableCount() == 1);
    }
    
    [Test]
    public void Tick_UpdatesPosition()
    {
        // Arrange
        MockMoveable moveable = new MockMoveable
        {
            IsMoving = true,
            Speed = 5f,
            Direction = Vector3.forward
        };
        system.RegisterMoveable(moveable);
        
        Vector3 startPos = moveable.Position;
        
        // Act
        system.Tick(1f); // 1 second
        
        // Assert
        Vector3 expectedPos = startPos + Vector3.forward * 5f;
        Assert.AreEqual(expectedPos, moveable.Position);
    }
}

// Mock for testing
public class MockMoveable : IMoveable
{
    public Transform Transform { get; set; }
    public Vector3 Position { get; set; }
    public float Speed { get; set; }
    public Vector3 Direction { get; set; }
    public bool IsMoving { get; set; }
    
    public void UpdatePosition(float deltaTime)
    {
        Position += Direction * Speed * deltaTime;
    }
}

---

8.2 Integration Testing

Testing System Integration

[UnityTest]
public IEnumerator AttackSystem_SelectsTarget_WithMovementSystem()
{
    // Arrange
    GameSystemsManager manager = CreateGameSystemsManager();
    AttackSystem attackSystem = manager.GetSystem<AttackSystem>();
    MovementSystem movementSystem = manager.GetSystem<MovementSystem>();
    
    // Spawn tower
    GameObject towerObj = CreateMockTower();
    Tower tower = towerObj.GetComponent<Tower>();
    
    // Spawn enemy
    GameObject enemyObj = CreateMockEnemy();
    Enemy enemy = enemyObj.GetComponent<Enemy>();
    
    // Wait for systems to register entities
    yield return null;
    
    // Simulate target scan
    tower.UpdateTargetsInRange();
    
    // Wait for attack
    yield return new WaitForSeconds(tower.AttackCooldown + 0.1f);
    
    // Assert
    Assert.IsNotNull(tower.CurrentTarget);
    Assert.AreEqual(enemy, tower.CurrentTarget);
}

---

8.3 Performance Testing

Automated Performance Tests

[UnityTest, Performance]
public IEnumerator MovementSystem_Performance_100Entities()
{
    // Arrange
    MovementSystem system = CreateMovementSystem();
    
    for (int i = 0; i < 100; i++)
    {
        MockMoveable moveable = new MockMoveable
        {
            IsMoving = true,
            Speed = 5f
        };
        system.RegisterMoveable(moveable);
    }
    
    // Measure
    using (Measure.Scope())
    {
        system.Tick(Time.deltaTime);
    }
    
    yield return null;
    
    // Assert performance target
    // Should process 100 entities in <1ms
}

---

Conclusion

This Developer Guide provides comprehensive documentation for all aspects of the tower defense project. For additional resources:

• Architecture Handbook - Deep dive into design patterns and principles

• Performance Optimization Guide - Advanced profiling and optimization techniques

• Project Files - /mnt/project/ contains all phase reports and implementation details

Remember:

• 🔍 Profile before optimizing

• 📝 Document as you code

• ✅ Test early and often

• 🤝 Ask for help when stuck

• 🚀 Iterate and improve

Happy Coding! 🎮

---

Last Updated: December 2025 Version: 1.0 Maintainer: Senior Unity Developer