Skip to content

Getting-Started.md

Latest commit

 

History

History
301 lines (223 loc) · 10.7 KB

Getting-Started.md

File metadata and controls

301 lines (223 loc) · 10.7 KB

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:

  • Unity 6000+ (2023.3+, latest LTS recommended)
  • Git for version control
  • Intermediate C# knowledge
  • Familiarity with Unity's component system

Installation

Option 1: Git Submodule (Recommended)

If your project uses Git, add Archon as a submodule:

cd YourUnityProject/Assets
git submodule add https://github.com/YourUsername/Archon-Engine.git Archon-Engine

This keeps Archon versioned separately and makes updates easy with git submodule update.

Option 2: Manual Download

  1. Download or clone the Archon-Engine repository
  2. Copy the entire Archon-Engine folder into your Unity project's Assets/ folder

After Installation

  1. Open Unity - Let it import all assets and compile scripts (may take a few minutes)

  2. Install required packages via Package Manager (Window → Package Manager):

    • Click + → Add package by name
    • Enter: com.unity.nuget.newtonsoft-json → Click Add
    • Enter: com.unity.transport → Click Add (for multiplayer)

  3. Verify URP is configured:

    • Check Edit → Project Settings → Graphics has a URP asset assigned
    • If not, create one: Assets → Create → Rendering → URP Asset

  4. Test the StarterKit:

    • Open scene: Assets/Archon-Engine/Scenes/StarterKit.unity
    • Press Play
    • You should see a map with provinces, be able to click on them, and see UI panels

Troubleshooting Installation

Issue Solution
Pink/magenta materials URP not configured - assign URP asset in Graphics settings
Compiler errors about Json Install Newtonsoft Json.NET package
Compiler errors about Transport Install Unity Transport package (com.unity.transport)
Nothing renders Check MapGenerator has mesh renderer assigned in Inspector
Console spam on Play Check Logs/ folder for detailed error info

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)

Key Concepts to Understand

1. GameState is the Hub

GameState is the central access point for all ENGINE systems:

var gameState = GameState.Instance;

// Access systems
gameState.Provinces      // Province data
gameState.Countries      // Country data
gameState.EventBus       // Event system
gameState.TryExecuteCommand()  // Execute commands

// Access queries (read-only helpers)
gameState.ProvinceQueries  // Query province data
gameState.CountryQueries   // Query country data

2. Commands for State Changes

Never modify state directly. Use commands:

// ❌ WRONG - direct modification
province.ownerID = newOwner;

// ✅ CORRECT - use a command
var cmd = new TransferProvinceCommand {
    ProvinceId = provinceId,
    NewOwner = newOwner
};
gameState.TryExecuteCommand(cmd);

Commands enable: multiplayer sync, undo, replay, save/load.

3. Events for Communication

Systems communicate via EventBus:

// Subscribe (usually in constructor or Initialize)
gameState.EventBus.Subscribe<ProvinceOwnershipChangedEvent>(OnOwnerChanged);

// Handler
void OnOwnerChanged(ProvinceOwnershipChangedEvent evt)
{
    if (evt.NewOwner == playerCountryId)
        RefreshUI();
}

// Emit (when something happens)
gameState.EventBus.Emit(new MyCustomEvent { Data = value });

4. FixedPoint64 for Determinism

Avoid use of float or double in simulation code. Use FixedPoint64:

// ❌ WRONG - floats cause desyncs in multiplayer
float income = provinces * 1.5f;

// ✅ CORRECT - FixedPoint64 is deterministic
FixedPoint64 income = provinceCount * FixedPoint64.FromFraction(3, 2); // 1.5

If you're doing strictly singleplayer it's more accepted to use normal numeric datatypes, however the engine still expects FixedPoint mostly. Important for determinism.

5. Hot vs Cold Data

  • Hot data: Accessed every frame (ProvinceState, CountryState) - keep small
  • Cold data: Accessed rarely (history, detailed info) - can be larger
// Hot: 8-byte struct, accessed constantly
ProvinceState state = gameState.Provinces.GetProvinceState(provinceId);

// Cold: loaded on-demand when player clicks
ProvinceHistoryData history = historySystem.GetHistory(provinceId);

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
  4. Camera - To view the map
  5. UI Canvas - For your UI panels

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
│   └── ...
├── Shaders/
│   ├── YourFlatMap.shader   # Copied from ENGINE, customized
│   ├── YourTerrainMap.shader
│   └── MapModes/
│       ├── YourMapModes.hlsl       # Dispatcher (includes ENGINE + your modes)
│       ├── MapModePolitical.hlsl   # Your political mode visuals
│       └── MapModeTerrain.hlsl     # Your terrain mode visuals
├── UI/
│   ├── ProvinceInfoUI.cs    # Your UI panels
│   └── ...
├── MapModes/
│   └── EconomyMapMode.cs    # Your custom map modes (C# GradientMapMode)
└── AI/
    └── BuildEconomyGoal.cs  # Your AI goals

Next Steps

  1. Your First Game - Build a minimal game step-by-step
  2. Cookbook - Common recipes and patterns
  3. Architecture Overview - Deeper understanding of the architecture
  4. 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