From 977f0473c35093a9ce3a60f7b221aa460bbec15f Mon Sep 17 00:00:00 2001
From: Bruno Carneiro <brunocarneiro@protonmail.com>
Date: Fri, 13 Feb 2026 20:24:44 +0000
Subject: [PATCH] Add Mission Script API

---
 Mission-Script-API.md | 46 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 Mission-Script-API.md

diff --git a/Mission-Script-API.md b/Mission-Script-API.md
new file mode 100644
index 0000000..334571f
--- /dev/null
+++ b/Mission-Script-API.md
@@ -0,0 +1,46 @@
+# Mission Script API — Documentation
+
+This folder documents the API available to mission scripts. Mission scripts derive from `AMission` and are loaded by the game at runtime.
+
+Mission scripts also use additional types such as `LimbNames`, `NamedDamageTypes`, `Point2d`, and `Point3d`; those are summarized in [external-types.md](external-types.md).
+
+## How mission scripts are loaded
+
+1. The game loads a **battle** (one `ABattle` instance) via `IScriptRemote.loadBattleScript`.
+2. Missions are attached with `loadMissionScript(fileName, missionNumber, scriptFileName)`, which instantiates a class named `Mission` that inherits from `AMission`.
+3. Each mission’s `Init(battle, missionNumber)` is called; then the battle runs and invokes the mission’s virtual `On*` methods in response to game events.
+
+## Documentation index
+
+### Core
+
+| Document | Description |
+|----------|-------------|
+| [01-mission-and-battle.md](01-mission-and-battle.md) | **AMission**, **ABattle**, **IBattle**, **DoTimeout** |
+| [02-gameplay.md](02-gameplay.md) | **IGamePlay** — main interface to the game (actors, HUD, triggers, section files, etc.) |
+| [03-time-and-difficulty.md](03-time-and-difficulty.md) | **ITime**, **DifficultySetting** |
+| [04-player.md](04-player.md) | **Player** |
+| [05-events-and-section-file.md](05-events-and-section-file.md) | **GameEventId**, **ISectionFile** |
+| [06-pathfinding-and-terrain.md](06-pathfinding-and-terrain.md) | **RecalcPathState**, **PathType**, **LandTypes**, **IRecalcPathParams**, **ActorName** |
+| [07-script-loading.md](07-script-loading.md) | **IScriptRemote**, **ScriptRemote** |
+| [external-types.md](external-types.md) | Additional types used by missions (limbs, damage, geometry) |
+
+### World
+
+| Document | Description |
+|----------|-------------|
+| [world/README.md](world/README.md) | Index of world types |
+| [world/01-actor-hierarchy.md](world/01-actor-hierarchy.md) | **AiActor**, **AiPerson**, **AiCart**, **AiGroup**, damage types, **CrewFunction** |
+| [world/02-air.md](world/02-air.md) | **AiAircraft**, **AiAirGroup**, air waypoints, enums, **EnemyAirInterf** |
+| [world/03-ground.md](world/03-ground.md) | **AiGroundActor**, **GroundStationary**, buildings, bomb explosion, enums |
+| [world/04-triggers-spawns-targets.md](world/04-triggers-spawns-targets.md) | **AiTrigger**, **AiAction**, **AiBirthPlace**, **AiAirport**, **AiTarget**, **Regiment** |
+| [world/05-time-and-user-labels.md](world/05-time-and-user-labels.md) | **ITime** (cross-link), **GPUserLabel**, **GPUserIconType** |
+
+## Quick start
+
+1. Create a class `Mission` that inherits from `AMission`.
+2. Override `OnBattleInit`, `OnBattleStarted`, and any `On*` events you need (e.g. `OnTrigger`, `OnActorCreated`, `OnAircraftKilled`).
+3. Use `GamePlay` (IGamePlay) for querying actors, triggers, spawning groups, HUD messages, and section files.
+4. Use `Time` (ITime) for game time and tick conversion (e.g. with `Timeout`).
+
+Reference the API documented here when building your mission script project.