aether-shards/src/assets/data/missions/mission-schema.md

# **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.
- **enemy_spawns**: Specific enemy types and counts to spawn at mission start.
- **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.

```js
{
  "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"
      }
    ]
  },
  "enemy_spawns": [
    {
      "enemy_def_id": "ENEMY_BOSS_ARTILLERY",
      "count": 1
    },
    {
      "enemy_def_id": "ENEMY_SHARDBORN_SENTINEL",
      "count": 3
    }
  ],
  "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\. Field Definitions & Logic Requirements**

### **Deployment Constraints**

- **forced_units**: The TeamBuilder UI must check this array and auto-fill slots with these units (locking them so they can't be removed).
- **banned_classes**: The UI must disable these cards in the Roster.
- **suggested_units**: (Optional) Array of class/unit IDs recommended for this mission. Useful for tutorials to guide player selection. The UI should highlight or recommend these units.
- **tutorial_hint**: (Optional) Text to display as a tutorial overlay during the deployment phase. Should point to UI elements (e.g., "Drag units from the bench to the Green Zone.").

### **Enemy Spawns**

- **enemy_spawns**: Array of enemy spawn definitions. Each entry specifies an enemy definition ID and count.
  - **enemy_def_id**: The enemy unit definition ID (e.g., 'ENEMY_SHARDBORN_SENTINEL'). Must match an enemy definition in the UnitRegistry.
  - **count**: Number of this enemy type to spawn at mission start.
  - The GameLoop's `finalizeDeployment()` method should read this array and spawn the specified enemies in the enemy spawn zone.

### **Objectives Types**

The MissionManager needs logic to handle these specific types:

| Type               | Data Required    | Logic                                                   |
| :----------------- | :--------------- | :------------------------------------------------------ |
| **ELIMINATE_ALL**  | None             | Monitor unitManager. If enemies.length \=== 0, Success. |
| **ELIMINATE_UNIT** | target_def_id    | Monitor ON_DEATH events. If victim ID matches, Success. |
| **INTERACT**       | target_object_id | Monitor ON_INTERACT. If object matches, Success.        |
| **REACH_ZONE**     | zone_coords      | Monitor ON_MOVE. If unit ends turn in zone, Success.    |
| **SURVIVE**        | turn_count       | Monitor ON_TURN_END. If count reached, Success.         |
| **ESCORT**         | vip_id           | If VIP dies, Immediate Failure.                         |

### **Scripted Events (Triggers)**

The GameLoop needs an Event Bus listener that checks these triggers every time an action happens.

- **ON_TURN_START**: Checks turnSystem.currentTurn.
- **ON_UNIT_SPAWN**: Useful for ambush events.
- **ON_HEALTH_PERCENT**: "Boss enters Phase 2 at 50% HP".

### **Rewards**

- **unlocks**: Must call MetaProgression.unlockClass(id).
- **faction_reputation**: Must update the persistent UserProfile faction standing.