TEAM ONBOARDING GUIDELINES

Project: Procedurally Generated Tower Defense Version: 1.0 Last Updated: December 2025

---

📋 Table of Contents

1. Overview

2. Getting Started

3. Development Environment Setup

4. Code Style & Standards

5. Architecture Guidelines

6. Git Workflow

7. Testing Requirements

8. Documentation Standards

9. Performance Guidelines

10. Code Review Process

11. Onboarding Checklist

---

Overview

This document provides comprehensive guidelines for working on similar projects to the Procedurally Generated Tower Defense project. It ensures code quality, architectural consistency, and smooth team collaboration.

Target Audience

• New team members joining the project

• Client development teams taking over maintenance

• External contributors (if applicable)

• Code reviewers ensuring quality standards

Goals

• ✅ Maintain clean, readable, and maintainable codebase

• ✅ Ensure consistent architecture patterns (system-based design)

• ✅ Preserve performance optimizations (+125% FPS)

• ✅ Facilitate smooth onboarding for new developers

• ✅ Enable efficient code review process

---

Getting Started

Prerequisites

Before contributing, ensure you have:

Required Software:

• Unity 2022.3 LTS or newer (Download)

• Visual Studio 2022 or JetBrains Rider 2023.3+ (recommended)

• Git 2.30+ for version control

Required Knowledge:

• C# programming (intermediate level)

• Unity fundamentals (GameObjects, Components, Prefabs)

• Basic understanding of ECS principles (recommended)

• Git workflow (branching, merging, pull requests)

Recommended Reading:

• Architecture Handbook - Read first!

• Developer Guide - Setup and workflows

• Performance Optimization Guide - Performance rules

---

Development Environment Setup

Step 1: Clone Repository

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

Step 2: Unity Setup

1. Open Unity Hub
2. Add project (Unity Hub → Projects → Add)
3. Select project folder
4. Open with Unity 2022.3 LTS
5. Wait for asset import (~2 minutes)

Step 3: IDE Configuration

Visual Studio 2022:

1. Unity → Preferences → External Tools
2. External Script Editor → Visual Studio 2022
3. Install Unity Tools extension in VS

JetBrains Rider (Recommended):

1. Unity → Preferences → External Tools
2. External Script Editor → Rider
3. Enable "Regenerate project files"
4. Rider auto-configures Unity support

Step 4: Verify Setup

1. Open any C# script in IDE
2. Verify IntelliSense/code completion works
3. Build project (Ctrl+B) - should succeed
4. Enter Play Mode - game should run at 100+ FPS

---

Code Style & Standards

Naming Conventions

Classes & Structs:

// ✅ Correct: PascalCase
public class MovementSystem : MonoBehaviour { }
public struct EnemyData { }

// ❌ Wrong: camelCase or snake_case
public class movementSystem { }
public class movement_system { }

Methods:

// ✅ Correct: PascalCase
public void RegisterMoveable(IMoveable moveable) { }

// ❌ Wrong: camelCase
public void registerMoveable(IMoveable moveable) { }

Fields:

// ✅ Correct: camelCase with underscore prefix for private
private List<IMoveable> _moveables;
private float _currentSpeed;

// ✅ Correct: camelCase for serialized fields (no underscore)
[SerializeField] private float moveSpeed;

// ❌ Wrong: PascalCase for private fields
private List<IMoveable> Moveables;

Properties:

// ✅ Correct: PascalCase
public Transform Transform { get; private set; }
public float Speed => _moveSpeed;

// ❌ Wrong: camelCase
public float speed { get; set; }

Interfaces:

// ✅ Correct: PascalCase with "I" prefix
public interface IMoveable { }
public interface IGameSystem { }

// ❌ Wrong: No "I" prefix
public interface Moveable { }

Constants:

// ✅ Correct: ALL_CAPS with underscores
private const int MAX_ENEMIES = 100;
private const float DEFAULT_SPEED = 5f;

// ❌ Wrong: PascalCase or camelCase
private const int MaxEnemies = 100;

Code Formatting

Indentation:

• Use 4 spaces (not tabs)

• Configure IDE: Ctrl+K, Ctrl+D (VS) or Ctrl+Alt+L (Rider)

Braces:

// ✅ Correct: Opening brace on new line (Allman style)
public void Update()
{
    if (isActive)
    {
        ProcessEntities();
    }
}

// ❌ Wrong: Opening brace on same line (K&R style)
public void Update() {
    if (isActive) {
        ProcessEntities();
    }
}

Line Length:

• Maximum 120 characters per line

• Break long method chains into multiple lines

Whitespace:

// ✅ Correct: Space after keywords, around operators
if (value > 0)
{
    result = a + b;
}

// ❌ Wrong: No spaces
if(value>0)
{
    result=a+b;
}

File Organization

Using Directives:

// Order: System → Unity → Project
using System.Collections.Generic;
using UnityEngine;
using ProjectName.Systems;

Class Structure:

public class Example : MonoBehaviour
{
    // 1. Constants
    private const int MAX_CAPACITY = 100;
    
    // 2. Serialized fields
    [SerializeField] private float speed = 5f;
    
    // 3. Private fields
    private List<Enemy> _enemies;
    private float _currentTime;
    
    // 4. Properties
    public float Speed => speed;
    
    // 5. Unity lifecycle methods (alphabetical)
    private void Awake() { }
    private void OnDestroy() { }
    private void OnDisable() { }
    private void OnEnable() { }
    private void Start() { }
    private void Update() { }
    
    // 6. Public methods (alphabetical)
    public void Attack() { }
    public void Move() { }
    
    // 7. Private methods (alphabetical)
    private void ProcessTarget() { }
    private void UpdatePosition() { }
}

---

Architecture Guidelines

Core Principles

1. System-Based Design

⚠️ CRITICAL: This project uses system-based architecture. DO NOT add Update() methods to entities!

// ❌ WRONG: Update() in entity
public class Enemy : MonoBehaviour
{
    void Update() // DON'T DO THIS!
    {
        transform.position += direction * speed * Time.deltaTime;
    }
}

// ✅ CORRECT: Implement interface, register with system
public class Enemy : MonoBehaviour, IMoveable
{
    // NO Update() method!
    
    void OnEnable()
    {
        MovementSystem.Instance?.RegisterMoveable(this);
    }
    
    void OnDisable()
    {
        MovementSystem.Instance?.UnregisterMoveable(this);
    }
    
    public void UpdatePosition(float deltaTime)
    {
        transform.position += Direction * Speed * deltaTime;
    }
}

2. Interface-Driven Design

Always use interfaces to define entity capabilities:

// ✅ CORRECT: Composition via interfaces
public class Enemy : MonoBehaviour, IMoveable, IDamageable, ITargetable
{
    // Multiple capabilities through interfaces
}

// ❌ WRONG: Inheritance hierarchy
public class Enemy : BaseEntity
{
    // Tight coupling, hard to extend
}

3. Separation of Concerns

• Entities = Data providers (state + interface implementation)

• Systems = Logic processors (batch operations)

• Managers = Orchestrators (system lifecycle)

Adding New Features

Adding a New System:

// 1. Define interface
public interface INewCapability
{
    void DoSomething();
}

// 2. Create system
public class NewSystem : MonoBehaviour, IGameSystem
{
    public int Priority => 10; // Set execution order
    public bool IsActive { get; set; } = true;
    
    private List<INewCapability> _entities = new();
    
    public void Initialize() { }
    
    public void Tick(float deltaTime)
    {
        foreach (var entity in _entities)
        {
            entity.DoSomething();
        }
    }
    
    public void Shutdown() 
    {
        _entities.Clear();
    }
    
    public void Register(INewCapability entity) 
    {
        _entities.Add(entity);
    }
    
    public void Unregister(INewCapability entity) 
    {
        _entities.Remove(entity);
    }
}

// 3. Register system in GameSystemsManager

Adding a New Entity Type:

public class NewEntity : MonoBehaviour, IMoveable, INewCapability
{
    // Implement ALL interface members
    
    private void OnEnable()
    {
        MovementSystem.Instance?.RegisterMoveable(this);
        NewSystem.Instance?.Register(this);
    }
    
    private void OnDisable()
    {
        MovementSystem.Instance?.UnregisterMoveable(this);
        NewSystem.Instance?.Unregister(this);
    }
}

What NOT to Do

❌ Never:

• Add Update() methods to entities

• Use FindObjectOfType() in Update/Tick loops

• Use LINQ in hot paths (Update/Tick)

• Use string concatenation in frequent calls

• Instantiate/Destroy objects (use object pooling)

• Use GetComponent() in Update/Tick (cache in Awake)

---

Git Workflow

Branch Naming

Feature Branches:

feature/add-laser-tower
feature/save-load-system
feature/boss-enemies

Bugfix Branches:

bugfix/tower-rotation-issue
bugfix/projectile-pooling

Performance Branches:

perf/optimize-pathfinding
perf/reduce-draw-calls

Refactor Branches:

refactor/ui-system
refactor/enemy-ai

Commit Messages

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature

• fix: Bug fix

• perf: Performance improvement

• refactor: Code refactoring

• docs: Documentation changes

• test: Adding/updating tests

• style: Code style changes (formatting)

Examples:

feat(tower): Add laser tower with pierce mechanic

- Implemented LaserTower class with IAttacker interface
- Added pierce damage to projectile system
- Created laser visual effects
- Updated tower UI with laser tower button

Closes #45

fix(pooling): Fix OnEnable not called for pooled objects

Objects returned from pool weren't resetting state properly.
Changed initialization from Start() to OnEnable().

Related to #78

perf(rendering): Enable SRP Batcher for grid nodes

Reduced draw calls from 400 to 6 (-98.5%).
FPS improved from 120 to 144 (+20%).

Benchmark results in commit description.

Pull Request Process

1. Create Feature Branch

git checkout -b feature/my-feature

2. Make Changes

# Make changes
git add .
git commit -m "feat(scope): description"

3. Push to Remote

git push origin feature/my-feature

4. Create Pull Request

PR Template:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Performance improvement
- [ ] Refactoring
- [ ] Documentation

## Testing
- [ ] Tested in Unity Editor
- [ ] Tested in build
- [ ] FPS verified (no regression)
- [ ] No new compiler warnings

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added to complex code
- [ ] Documentation updated
- [ ] No Update() methods added to entities

## Performance Impact
Before: XXX FPS
After: XXX FPS
Change: +X% / -X%

## Screenshots (if applicable)
[Add screenshots]

5. Code Review

• Minimum 1 approval required

• Address all review comments

• Resolve merge conflicts

6. Merge

# Squash and merge (preferred for clean history)
# Or merge commit (for large features)

---

Testing Requirements

Unit Tests

Location: Assets/Tests/EditMode/

Example:

using NUnit.Framework;

public class MovementSystemTests
{
    [Test]
    public void RegisterMoveable_AddsToList()
    {
        // Arrange
        var system = new MovementSystem();
        var entity = new MockMoveable();
        
        // Act
        system.RegisterMoveable(entity);
        
        // Assert
        Assert.AreEqual(1, system.GetMoveableCount());
    }
}

Requirements:

• ✅ Test all public methods

• ✅ Test edge cases (null, empty, negative values)

• ✅ Target 75%+ code coverage

Integration Tests

Location: Assets/Tests/PlayMode/

Example:

using UnityEngine.TestTools;
using System.Collections;

public class AttackSystemIntegrationTests
{
    [UnityTest]
    public IEnumerator Tower_AttacksEnemy_DealsDamage()
    {
        // Arrange
        var tower = CreateTower();
        var enemy = CreateEnemy();
        
        // Act
        yield return new WaitForSeconds(1f); // Wait for attack
        
        // Assert
        Assert.Less(enemy.CurrentHealth, enemy.MaxHealth);
    }
}

Performance Tests

Verify NO performance regression:

[Test, Performance]
public void MovementSystem_100Entities_UnderBudget()
{
    using (Measure.Frames().WarmupCount(10).MeasurementCount(100).Run())
    {
        // System should process 100 entities in <1ms
    }
}

Before Merge Checklist:

• FPS not decreased (compare baseline)

• No new GC allocations in hot paths

• Profiler shows no new spikes

---

Documentation Standards

Code Comments

When to Comment:

// ✅ GOOD: Explain WHY, not WHAT
// Using SqrMagnitude instead of Distance to avoid expensive sqrt calculation
float distanceSq = Vector3.SqrMagnitude(target.Position - transform.position);

// ❌ BAD: Redundant comment
// Get the distance
float distance = Vector3.Distance(a, b);

XML Documentation:

/// <summary>
/// Registers a moveable entity with the movement system for batch processing.
/// </summary>
/// <param name="moveable">Entity implementing IMoveable interface</param>
/// <remarks>
/// Entities are automatically processed in MovementSystem.Tick().
/// Call from OnEnable() to support object pooling.
/// </remarks>
public void RegisterMoveable(IMoveable moveable)
{
    if (moveable == null)
    {
        Debug.LogWarning("[MovementSystem] Attempted to register null moveable");
        return;
    }
    
    _moveables.Add(moveable);
}

Required Documentation:

• ✅ All public methods (XML summary)

• ✅ All public properties (XML summary)

• ✅ Complex algorithms (inline comments)

• ✅ Performance-critical code (explain optimizations)

• ✅ Workarounds (explain why + issue link)

Architecture Documentation

When adding new systems or major features, update:

• Architecture Handbook - Add system documentation

• Developer Guide - Add API reference

• Performance Guide - If performance-related

---

Performance Guidelines

Critical Rules

⚠️ These rules preserve +125% FPS improvement. DO NOT violate!

Rule 1: No Update() in Entities

// ❌ BREAKS PERFORMANCE!
public class Enemy : MonoBehaviour
{
    void Update() { } // NO!
}

Rule 2: No LINQ in Hot Paths

// ❌ SLOW: LINQ in Tick/Update
var target = enemies.OrderBy(e => e.Health).FirstOrDefault();

// ✅ FAST: Manual iteration
Enemy target = enemies[0];
for (int i = 1; i < enemies.Count; i++)
{
    if (enemies[i].Health < target.Health)
        target = enemies[i];
}

Rule 3: Cache Component References

// ❌ SLOW: GetComponent every frame
void Update()
{
    GetComponent<Rigidbody>().velocity = Vector3.forward;
}

// ✅ FAST: Cache in Awake
private Rigidbody _rb;
void Awake() { _rb = GetComponent<Rigidbody>(); }
void Update() { _rb.velocity = Vector3.forward; }

Rule 4: Use Object Pooling

// ❌ SLOW: Instantiate/Destroy
var projectile = Instantiate(prefab);
Destroy(projectile);

// ✅ FAST: Pool
var projectile = PoolManager.Instance.Pull(prefab);
PoolManager.Instance.Push(projectile);

Rule 5: Use OnEnable, Not Start (for pooled objects)

// ❌ BREAKS POOLING: Start() only called once
void Start() { ResetState(); }

// ✅ WORKS WITH POOLING: OnEnable() called every activation
void OnEnable() { ResetState(); }

Profiling Requirements

Before merging performance-related changes:

1. Baseline Measurement

   • Record FPS in Wave 7 (standard benchmark)

   • Record CPU/GPU time in Profiler

   • Record batch count in Stats window

2. Change Measurement

   • Apply changes

   • Record same metrics

   • Compare Before/After

3. Validation

   • FPS improved or maintained (no regression)

   • CPU/GPU time reduced or maintained

   • No new GC allocations

4. Documentation

   • Add performance numbers to commit message

   • Update Performance Guide if significant improvement

---

Code Review Process

For Reviewers

Review Checklist:

Architecture:

• Follows system-based design (no Update() in entities)

• Uses interfaces correctly

• Proper registration/unregistration in OnEnable/OnDisable

Performance:

• No LINQ in hot paths

• No GetComponent() in Update/Tick

• Uses object pooling where applicable

• No string concatenation in frequent calls

Code Quality:

• Follows naming conventions

• Properly formatted (4 spaces, Allman braces)

• XML documentation for public members

• No compiler warnings introduced

Testing:

• Unit tests added (if applicable)

• Integration tests pass

• Performance verified (no regression)

Review Timeline:

• Respond within 24 hours

• Complete review within 48 hours

• Approve or request changes with clear feedback

For Authors

Before Requesting Review:

• Self-review completed

• All tests passing

• Code formatted (Ctrl+K, Ctrl+D)

• No merge conflicts

• Documentation updated

Responding to Feedback:

• Address all comments (or provide reasoning)

• Push changes as new commits (don't force-push)

• Re-request review when ready

---

Onboarding Checklist

Day 1: Environment Setup

• Clone repository and open in Unity

• Configure IDE (Visual Studio or Rider)

• Verify build succeeds (no errors)

• Run game - should get 100+ FPS

• Read Architecture Handbook (2-3 hours)

Day 2-3: Codebase Exploration

• Read Developer Guide

• Browse Assets/Scripts/Systems/ folder

• Examine MovementSystem implementation (example system)

• Examine Enemy implementation (example entity)

• Run Unity Profiler - understand baseline metrics

Week 1: First Contribution

• Pick a "good first issue" from issue tracker

• Create feature branch

• Implement change following guidelines

• Write unit tests

• Submit pull request

• Address code review feedback

Week 2-4: Full Onboarding

• Read Performance Optimization Guide

• Implement a new tower type

• Implement a new enemy variant

• Add a new status effect

• Mentor other new team members

---

Questions & Support

Getting Help

Documentation:

• 📘 Architecture Handbook - Design patterns and systems

• 🔧 Developer Guide - Setup and workflows

• ⚡ Performance Guide - Optimization techniques

• 📊 Sales Deck - Project overview and results

Communication & Support:

• All questions, proposals, and discussions: [e-mail]

• Preferred format: Email or direct message (LinkedIn/Telegram/WhatsApp)

• Response time: Within 24–48 hours (weekdays)

Post-project support and minor clarifications are included for 30 days after handover. Extended maintenance available on separate agreement.

Response Times:

• Critical bugs: 4-8 hours

• Questions: 24 hours

• Code reviews: 48 hours

---

Continuous Improvement

This document is a living guide. Suggestions for improvement are welcome!

How to Suggest Changes:

1. Create issue with documentation label

2. Describe proposed change

3. Explain reasoning/benefits

4. Submit PR with changes

---

Document Version: 1.0 Maintained By: Aztoon Lab

Thank you for contributing to clean, performant, and maintainable code! 🚀