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.

{
  "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.