Getting Started

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:

   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 - Build a minimal game step-by-step
2. Architecture Overview - 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