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": "Reserved for future gold income scaling. Currently 1.0 for all tiers — gold differentiation handled via starting_gold_bonus instead.",
    "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": 1.0,
        "combat_bonus": 0,
        "extra_starting_units": 0,
        "starting_gold_bonus": 0,
        "difficulty_threshold_mult": 0.85
      },
      "player_modifiers": {
        "production_mult": 1.0,
        "research_mult": 1.0
      }
    },
    {
      "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,
        "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
      }
    },
    {
      "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.0,
        "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
      }
    },
    {
      "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.0,
        "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
      }
    }
  ],
  "default": "normal"
}