magicciv/difficulty.json

{
  "knob_schema": {
    "production_mult": "Scales city build-queue output per turn (food, hammers). Easy=0.70 produces ~34% less total output than Normal baseline; Hard=1.30 produces ~30% more. Primary lever that separates tier progression speed. Empirically validated: Easy median prod_total=26.1 vs Normal 39.5.",
    "research_mult": "Scales per-turn tech research progress. Lower values delay tier advancement and unlock timing. Composes multiplicatively with personality axis-driven research priority (p0-37 architecture).",
    "gold_mult": "Multiplier on per-turn gold accumulation. AI 'still has to acquire' gold but each acquisition is multiplied. Activated 2026-04-27 (warcouncil p1-29 H4).",
    "culture_mult": "Multiplier on per-turn culture accumulation (city border expansion, culture victory). Same pattern as gold_mult. Added 2026-04-27.",
    "luxury_mult": "Multiplier on per-turn luxury yield (happiness contribution). Same pattern as gold_mult. Added 2026-04-27.",
    "yield_per_turn_growth": "Linear growth bonus added to ALL ai yield multipliers per turn (gold, science, culture, luxury, production). Formula: effective_mult = base_mult + turn * yield_per_turn_growth. At Hard yield_per_turn_growth=0.003, T138 ≈ 138% base. Lets AI scale into mid/late game without overpowering early game. User directive 2026-04-27.",
    "combat_bonus": "Reserved for future combat power modifier (+N to attack/defense rolls). Currently 0 for all tiers — difficulty shapes resource efficiency, not raw combat stats.",
    "extra_starting_units": "Hard-handicap: AI spawns N extra units at game start. Only Insane tier uses this (1 warrior). Gives an aggressive opener advantage.",
    "extra_unit_id": "Unit type id for the extra_starting_units spawn (e.g. 'warrior'). Ignored when extra_starting_units=0.",
    "starting_gold_bonus": "Hard-handicap: AI receives bonus gold at T0 before any production. Hard=75, Insane=150. Allows faster early expansion and unit purchases.",
    "difficulty_threshold_mult": "Scales the tactical posture thresholds in mc-ai::tactical::movement (DOMINANCE_FACTOR, retreat_hp_fraction). Easy=0.85 → AI overcommits (lower dominance required to attack); Hard=1.15 → AI waits for real superiority before engaging. Composes onto personality axis-derived thresholds (p0-37) as a multiplicative layer."
  },
  "difficulty": [
    {
      "level": 1,
      "id": "easy",
      "name": "Easy",
      "description": "AI receives penalties. Ideal for learning the game.",
      "ai_modifiers": {
        "production_mult": 0.70,
        "research_mult": 0.80,
        "gold_mult": 0.80,
        "culture_mult": 0.80,
        "luxury_mult": 0.80,
        "yield_per_turn_growth": 0.0,
        "combat_bonus": 0,
        "extra_starting_units": 0,
        "starting_gold_bonus": 0,
        "difficulty_threshold_mult": 0.85
      },
      "player_modifiers": {
        "production_mult": 1.30,
        "research_mult": 2.00,
        "gold_mult": 1.30,
        "culture_mult": 1.30,
        "luxury_mult": 1.30,
        "yield_per_turn_growth": 0.003
      }
    },
    {
      "level": 2,
      "id": "normal",
      "name": "Normal",
      "description": "Baseline challenge. No bonuses for either side.",
      "ai_modifiers": {
        "production_mult": 1.0,
        "research_mult": 1.0,
        "gold_mult": 1.0,
        "culture_mult": 1.0,
        "luxury_mult": 1.0,
        "yield_per_turn_growth": 0.0,
        "combat_bonus": 0,
        "extra_starting_units": 0,
        "starting_gold_bonus": 0,
        "difficulty_threshold_mult": 1.00
      },
      "player_modifiers": {
        "production_mult": 1.0,
        "research_mult": 1.0,
        "gold_mult": 1.0,
        "culture_mult": 1.0,
        "luxury_mult": 1.0,
        "yield_per_turn_growth": 0.0
      }
    },
    {
      "level": 3,
      "id": "hard",
      "name": "Hard",
      "description": "AI receives significant bonuses. A fair challenge for experienced players.",
      "ai_modifiers": {
        "production_mult": 1.30,
        "research_mult": 2.00,
        "gold_mult": 1.30,
        "culture_mult": 1.30,
        "luxury_mult": 1.30,
        "yield_per_turn_growth": 0.003,
        "combat_bonus": 0,
        "extra_starting_units": 0,
        "starting_gold_bonus": 75,
        "difficulty_threshold_mult": 1.15
      },
      "player_modifiers": {
        "production_mult": 1.0,
        "research_mult": 1.0,
        "gold_mult": 1.0,
        "culture_mult": 1.0,
        "luxury_mult": 1.0,
        "yield_per_turn_growth": 0.0
      }
    },
    {
      "level": 4,
      "id": "insane",
      "name": "Insane",
      "description": "AI receives major bonuses and a free starting warrior. A serious challenge.",
      "ai_modifiers": {
        "production_mult": 1.50,
        "research_mult": 3.00,
        "gold_mult": 1.50,
        "culture_mult": 1.50,
        "luxury_mult": 1.50,
        "yield_per_turn_growth": 0.005,
        "combat_bonus": 0,
        "extra_starting_units": 1,
        "extra_unit_id": "warrior",
        "starting_gold_bonus": 150,
        "difficulty_threshold_mult": 1.25
      },
      "player_modifiers": {
        "production_mult": 1.0,
        "research_mult": 1.0,
        "gold_mult": 1.0,
        "culture_mult": 1.0,
        "luxury_mult": 1.0,
        "yield_per_turn_growth": 0.0
      }
    }
  ],
  "default": "normal"
}