# Mission JSON Schema Reference

This document defines the data structure for Game Missions. It covers configuration for World Generation, Narrative logic, Objectives, and Rewards.

## 1. The Structure (Overview)

A Mission file is a JSON object with the following top-level keys:

- **`config`**: Meta-data (ID, Title, Difficulty).
- **`biome`**: Instructions for the Procedural Generator.
- **`deployment`**: Constraints on who can go on the mission.
- **`narrative`**: Hooks for Intro/Outro and scripted events.
- **`objectives`**: Win/Loss conditions.
- **`modifiers`**: Global rules (e.g., "Fog of War", "High Gravity").
- **`rewards`**: What the player gets for success.

## 2. Complete Example (The "Kitchen Sink" Mission)

This example utilizes every capability of the system.

```json
{
  "id": "MISSION_ACT1_FINAL",
  "type": "STORY",
  "config": {
    "title": "Operation: Broken Sky",
    "description": "The Iron Legion demands we silence the Shardborn Artillery. Expect heavy resistance.",
    "difficulty_tier": 3,
    "recommended_level": 5
  },

  "biome": {
    "type": "BIOME_RUSTING_WASTES",
    "generator_config": {
      "seed_type": "RANDOM",
      "size": { "x": 30, "y": 10, "z": 30 },
      "room_count": 8,
      "density": "HIGH"
    },
    "hazards": ["HAZARD_ACID_POOLS", "HAZARD_ELECTRICITY"]
  },

  "deployment": {
    "squad_size_limit": 4,
    "forced_units": ["UNIT_HERO_VANGUARD"],
    "banned_classes": ["CLASS_SCAVENGER"]
  },

  "narrative": {
    "intro_sequence": "NARRATIVE_ACT1_FINAL_INTRO",
    "outro_success": "NARRATIVE_ACT1_FINAL_WIN",
    "outro_failure": "NARRATIVE_ACT1_FINAL_LOSE",

    "scripted_events": [
      {
        "trigger": "ON_TURN_START",
        "turn_index": 3,
        "action": "PLAY_SEQUENCE",
        "sequence_id": "NARRATIVE_MID_BATTLE_TAUNT"
      },
      {
        "trigger": "ON_UNIT_DEATH",
        "target_tag": "ENEMY_BOSS",
        "action": "PLAY_SEQUENCE",
        "sequence_id": "NARRATIVE_BOSS_PHASE_2"
      }
    ]
  },

  "objectives": {
    "primary": [
      {
        "id": "OBJ_KILL_BOSS",
        "type": "ELIMINATE_UNIT",
        "target_def_id": "ENEMY_BOSS_ARTILLERY",
        "description": "Destroy the Shardborn Artillery Construct."
      }
    ],
    "secondary": [
      {
        "id": "OBJ_TIME_LIMIT",
        "type": "COMPLETE_BEFORE_TURN",
        "turn_limit": 10,
        "description": "Finish within 10 Turns."
      },
      {
        "id": "OBJ_NO_DEATHS",
        "type": "SQUAD_SURVIVAL",
        "min_alive": 4,
        "description": "Ensure entire squad survives."
      }
    ],
    "failure_conditions": [
      { "type": "SQUAD_WIPE" },
      { "type": "VIP_DEATH", "target_tag": "VIP_ESCORT" }
    ]
  },

  "modifiers": [
    {
      "type": "GLOBAL_EFFECT",
      "effect_id": "EFFECT_ACID_RAIN",
      "description": "All units take 5 damage at start of turn."
    },
    {
      "type": "STAT_MODIFIER",
      "target_team": "ENEMY",
      "stat": "attack",
      "value": 1.2
    }
  ],

  "rewards": {
    "guaranteed": {
      "xp": 500,
      "currency": { "aether_shards": 200, "ancient_cores": 1 },
      "items": ["ITEM_ELITE_BLAST_PLATE"],
      "unlocks": ["CLASS_SAPPER"]
    },
    "conditional": [
      {
        "objective_id": "OBJ_TIME_LIMIT",
        "reward": { "currency": { "aether_shards": 100 } }
      }
    ],
    "faction_reputation": {
      "IRON_LEGION": 50,
      "COGWORK_CONCORD": -10
    }
  }
}
```

## 3. Node Types & Logic

### Common Fields (All Nodes)

- **`id`**: (Required) Unique string identifier within this sequence.
- **`type`**: `DIALOGUE` | `CHOICE` | `TUTORIAL` | `ACTION`.
- **`trigger`**: (Optional) An action payload sent to `GameLoop` upon entering this node.
- **`next`**: (Optional) ID of the next node. If `"END"` or missing, the sequence closes.

### Type: `DIALOGUE`

Standard conversation.

- **`speaker`**: Name displayed above text.
- **`portrait`**: Path to image asset.
- **`text`**: The body text.
- **`voice_clip`**: (Optional) Path to audio file.

### Type: `CHOICE`

Presents buttons to the user.

- **`choices`**: Array of options.
  - **`text`**: Button label.
  - **`next`**: Target Node ID.
  - **`condition`**: (Optional) Logic check. If false, choice is hidden or disabled.
    - `{ "type": "HAS_CLASS", "value": "ID" }`
    - `{ "type": "HAS_ITEM", "value": "ID" }`
    - `{ "type": "STAT_CHECK", "stat": "tech", "value": 5 }`

### Type: `TUTORIAL`

Overlays instructions on the UI.

- **`highlight_selector`**: CSS Selector string (e.g., `#btn-end-turn`) to visually highlight/pulse.
- **`block_input`**: (Boolean) If true, prevents clicking anything except the highlighted element.

### Type: `ACTION`

Invisible node used purely for logic/triggers. It executes its `trigger` and immediately jumps to `next`.

- _Use Case:_ Granting rewards or changing game state without showing a text box.

---

## 4. Trigger Definitions

These payloads are dispatched via the `narrative-trigger` event to the `GameLoop` or `MissionManager`.

| Trigger Type           | Params              | Description                                                     |
| :--------------------- | :------------------ | :-------------------------------------------------------------- |
| **`SPAWN_WAVE`**       | `wave_id`           | Spawns a specific set of enemies defined in the Mission config. |
| **`START_DEPLOYMENT`** | None                | Transitions GameLoop to DEPLOYMENT phase.                       |
| **`GIVE_ITEM`**        | `item_id`           | Adds item to squad inventory.                                   |
| **`MODIFY_RELATION`**  | `faction`, `amount` | Updates meta-progression reputation.                            |
| **`PLAY_SFX`**         | `file_path`         | Plays a one-shot sound.                                         |
