# Getting Started with Archon Engine

This guide will help you understand Archon Engine and get a development environment running.

## Prerequisites

Before starting, ensure you have:

- Intermediate C# knowledge
- Familiarity with Unity's component system
- Unity 2023.3+ (6000+, preferably latest LTS version)
- Universal Render Pipeline (URP)
- IL2CPP scripting backend (Mono is fine for development though)
- Burst Compiler enabled
- UI Toolkit

## Understanding the Architecture

### The Two-Layer Model

Archon uses a **dual-layer architecture**:

```
┌─────────────────────────────────────────────────────────┐
│                    YOUR GAME                            │
│  (Economy, Buildings, Units, UI, AI - game-specific)    │
├─────────────────────────────────────────────────────────┤
│                  ARCHON ENGINE                          │
│  ┌─────────────────┐  ┌─────────────────────────────┐   │
│  │   CORE LAYER    │  │        MAP LAYER            │   │
│  │  (Simulation)   │  │     (Presentation)          │   │
│  │                 │  │                             │   │
│  │ • ProvinceState │  │ • GPU Textures              │   │
│  │ • CountryState  │  │ • Border Rendering          │   │
│  │ • Commands      │  │ • Province Selection        │   │
│  │ • EventBus      │  │ • Map Modes                 │   │
│  │ • FixedPoint64  │  │ • Visual Styles             │   │
│  └─────────────────┘  └─────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

**Key principle**: Core (simulation) is deterministic. Map (presentation) is visual-only.

### ENGINE vs GAME

| Aspect | ENGINE (Archon) | GAME (Your Code) |
|--------|-----------------|------------------|
| **Provides** | Mechanisms (HOW) | Policy (WHAT) |
| **Examples** | Command processor, EventBus, ProvinceSystem | Building costs, income formulas, AI goals |
| **Location** | `Assets/Archon-Engine/` | `Assets/Game/` |
| **Modify?** | No (unless contributing) | Yes (your game logic) |

### The StarterKit

The **StarterKit** (`Assets/Archon-Engine/Scripts/StarterKit/`) is a complete example GAME layer. It includes:

- `Initializer.cs` - Entry point, system setup
- `EconomySystem.cs` - Gold income from provinces
- `BuildingSystem.cs` - Construct buildings in provinces
- `UnitSystem.cs` - Create and move military units
- `PlayerState.cs` - Track which country the player controls
- Commands, UI, map modes, and more

**Recommended**: Study the StarterKit before building your own game.

## Project Setup Options

### Option A: Start from StarterKit (Recommended)

1. **Copy the StarterKit** to your Game folder:
   ```
   Copy: Assets/Archon-Engine/Scripts/StarterKit/*
   To:   Assets/Game/
   ```

2. **Rename the namespace** from `StarterKit` to your game name (e.g., `MyStrategy`)

3. **Modify the copied code** - it's now yours to customize

### Option B: Start from Scratch

1. **Create your Game folder**: `Assets/Game/`

2. **Create an Initializer** that waits for ENGINE, then sets up your systems:
   ```csharp
   using Engine;

   public class MyGameInitializer : MonoBehaviour
   {
       IEnumerator Start()
       {
           // Wait for ENGINE to initialize
           while (ArchonEngine.Instance == null || !ArchonEngine.Instance.IsInitialized)
               yield return null;

           // Get GameState (ENGINE provides this)
           var gameState = ArchonEngine.Instance.GameState;

           // Create your systems
           myEconomySystem = new MyEconomySystem(gameState);

           // Subscribe to events
           gameState.EventBus.Subscribe<MonthlyTickEvent>(OnMonthlyTick);
       }
   }
   ```

3. **Create your systems** as plain C# classes (not MonoBehaviours)

## Scene Setup

A typical Archon game scene needs:

1. **ArchonEngine prefab** - Drag from `Assets/Archon-Engine/Prefabs/ArchonEngine.prefab`
   - Contains MapGenerator with all required components
   - Assign your map mesh renderer in the Inspector
   - Optionally assign your camera
2. **Your Game Initializer** - Initializes your GAME systems
3. **Map Quad** - GameObject with MeshRenderer and map material (provided in project)
4. **Camera** - To view the map (prefab provided in project)

The StarterKit scene (`Assets/Archon-Engine/Scenes/StarterKit.unity`) shows a working setup.

## File Organization

Recommended structure for your game:

```
Assets/Game/
├── Initializer.cs           # Entry point
├── Systems/
│   ├── EconomySystem.cs     # Your economy logic
│   ├── BuildingSystem.cs    # Your building logic
│   └── ...
├── Commands/
│   ├── BuildCommand.cs      # Your commands
│   └── ...
├── Data/
│   ├── BuildingType.cs      # Your data definitions
│   └── ...
├── UI/
│   ├── ProvinceInfoUI.cs    # Your UI panels
│   └── ...
├── MapModes/
│   └── EconomyMapMode.cs    # Your custom map modes
└── AI/
    └── BuildEconomyGoal.cs  # Your AI goals
```

## Next Steps

1. **[Your First Game](Your-First-Game.md)** - Build a minimal game step-by-step
2. **[Architecture Overview](Architecture-Overview.md)** - Deeper understanding of the architecture
3. **Study StarterKit** - Read the source code in `Assets/Archon-Engine/Scripts/StarterKit/`

## Common Mistakes to Avoid

| Mistake | Why It's Bad | What To Do Instead |
|---------|--------------|---------------------|
| Modify state directly | Breaks multiplayer, undo, save/load | Use Commands |
| Use `float` in simulation | Causes desyncs across platforms | Use `FixedPoint64` |
| Create GameObjects for provinces | Doesn't scale | Use texture-based rendering |
| Allocate in hot paths | Causes GC stutters | Pre-allocate, reuse buffers |
| Put game logic in MonoBehaviours | Hard to test, lifecycle issues | Use plain C# classes |
| Ignore EventBus | Creates tight coupling | Subscribe to events |