Add Mission Script API pages

2026-02-13 18:21:58 -03:00 · 2026-02-13 18:21:58 -03:00 · b1cf074279
commit b1cf074279
parent cd1269478a
16 changed files with 1658 additions and 2 deletions
--- a/Home.md
+++ b/Home.md
@ -1,3 +1,3 @@
-# Home2
+# Home

-[Mission Script API](wiki/mission-script-api)
+[Mission Script API](mission-script-api)
--- a/mission-script-api.md
+++ 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](mission-script-api/external-types).
+
+## 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 |
+|----------|-------------|
+| [Mission And Battle](mission-script-api/mission-and-battle) | **AMission**, **ABattle**, **IBattle**, **DoTimeout** |
+| [Gameplay](mission-script-api/gameplay) | **IGamePlay** — main interface to the game (actors, HUD, triggers, section files, etc.) |
+| [Time And Difficulty](mission-script-api/time-and-difficulty) | **ITime**, **DifficultySetting** |
+| [Player](mission-script-api/player) | **Player** |
+| [Events And Section File](mission-script-api/events-and-section-file) | **GameEventId**, **ISectionFile** |
+| [Pathfinding And Terrain](mission-script-api/pathfinding-and-terrain) | **RecalcPathState**, **PathType**, **LandTypes**, **IRecalcPathParams**, **ActorName** |
+| [Script Loading](mission-script-api/script-loading) | **IScriptRemote**, **ScriptRemote** |
+| [External Types](mission-script-api/external-types) | Additional types used by missions (limbs, damage, geometry) |
+
+### World
+
+| Document | Description |
+|----------|-------------|
+| [World](mission-script-api/world) | Index of world types |
+| [Actor Hierarchy](mission-script-api/world/actor-hierarchy) | **AiActor**, **AiPerson**, **AiCart**, **AiGroup**, damage types, **CrewFunction** |
+| [Air](mission-script-api/world/air) | **AiAircraft**, **AiAirGroup**, air waypoints, enums, **EnemyAirInterf** |
+| [Ground](mission-script-api/world/ground) | **AiGroundActor**, **GroundStationary**, buildings, bomb explosion, enums |
+| [Triggers Spawns And Targets](mission-script-api/world/triggers-spawns-targets) | **AiTrigger**, **AiAction**, **AiBirthPlace**, **AiAirport**, **AiTarget**, **Regiment** |
+| [Time And User Labels](mission-script-api/world/time-and-user-labels) | **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.
--- a/mission-script-api/events-and-section-file.md
+++ b/mission-script-api/events-and-section-file.md
@ -0,0 +1,102 @@
+# Events and Section File
+
+Mission scripts react to game events by overriding **AMission** `On*` methods. The raw event identifiers are **GameEventId**; the game translates these into the corresponding `On*` calls. For reading and writing config or mission data, use **ISectionFile** (obtained from `GamePlay.gpConfigUserFile()`, `gpLoadSectionFile()`, etc.).
+
+---
+
+## GameEventId
+
+**Kind:** enum  
+
+Identifies game events. Missions typically do **not** use this enum directly; they override the virtual `On*` methods on **AMission**, which are invoked when these events occur.
+
+| Value | Typical args | Corresponding AMission method |
+|-------|----------------|-------------------------------|
+| `GameStarted` | — | — |
+| `GameStoped` | — | — |
+| `BattleInit` | — | OnBattleInit |
+| `BattleStarted` | — | OnBattleStarted |
+| `BattleStoped` | — | OnBattleStoped |
+| `MissionLoaded` | null, null, missionNumber | OnMissionLoaded |
+| `PlayerConnected` | player, null, 0 | OnPlayerConnected |
+| `ClientAddInActivated` | player, null, 0 | — |
+| `PlayerDisconnected` | player, diagnostic, 0 | OnPlayerDisconnected |
+| `PlayerArmy` | player, null, army | OnPlayerArmy |
+| `AdminIn` / `AdminOut` | player, initiator, army | — |
+| `ActorCreated` | actor, null, 0 | OnActorCreated |
+| `ActorDestroyed` | actor, null, 0 | OnActorDestroyed |
+| `ActorDamaged` | actor, damageInitiator, damageId | OnActorDamaged |
+| `ActorDead` | actor, damageInitiator, 0 | OnActorDead |
+| `ActorTaskCompleted` | actor, null, 0 | OnActorTaskCompleted |
+| `Trigger` | name, null, Active?1:0 | OnTrigger |
+| `AircraftDamaged` / `AircraftLimbDamaged` / `AircraftCutLimb` | actor, … | OnAircraftDamaged / OnAircraftLimbDamaged / OnAircraftCutLimb |
+| `AircraftTookOff` / `AircraftLanded` / `AircraftCrashLanded` / `AircraftKilled` | actor, null, 0 | OnAircraftTookOff / OnAircraftLanded / OnAircraftCrashLanded / OnAircraftKilled |
+| `PersonMoved` / `PersonHealth` / `PersonParachuteLanded` / `PersonParachuteFailed` | person, … | OnPersonMoved / OnPersonHealth / OnPersonParachuteLanded / OnPersonParachuteFailed |
+| `PlaceEnter` / `PlaceLeave` | player, actor, placeIndex | OnPlaceEnter / OnPlaceLeave |
+| `Carter` / `AutopilotOn` / `AutopilotOff` | actor, null, placeIndex | OnCarter / OnAutopilotOn / OnAutopilotOff |
+| `AiAirNewEnemy` | AiAirEnemyElement, null, army | OnAiAirNewEnemy |
+| `OrderMissionMenuSelected` | player, ID, menuItemIndex | OnOrderMissionMenuSelected |
+| `StationaryKilled` / `BuildingKilled` / `BombExplosion` | stationary/building/pos, initiator, … | OnStationaryKilled / OnBuildingKilled / OnBombExplosion |
+| `UserCreateUserLabel` / `UserLabelDelete` | GPUserLabel, … | OnUserCreateUserLabel / OnUserDeleteUserLabel |
+
+---
+
+## ISectionFile
+
+**Kind:** interface  
+
+Represents an ini-style section file (sections and key-value pairs). Use it to read/write user config or mission data. Get instances from `GamePlay.gpConfigUserFile()`, `gpLoadSectionFile(fileName)`, `gpCreateSectionFile()`, or `gpCreateSectionFile(line, out firstWord)`.
+
+### Read-only and existence
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool isReadOnly()` | bool | True if the file is read-only. |
+| `bool exist(string section, string key)` | bool | True if the key exists in the section. |
+| `bool exist(string section)` | bool | True if the section exists. |
+
+### Get values
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `string get(string section, string key)` | string | Value for key; null if missing. |
+| `string get(string section, string key, string def)` | string | Value or default. |
+| `float get(string section, string key, float def)` | float | Float value or default. |
+| `float get(string section, string key, float def, float min, float max)` | float | Float clamped to [min, max]. |
+| `int get(string section, string key, int def)` | int | Int value or default. |
+| `int get(string section, string key, int def, int min, int max)` | int | Int clamped to [min, max]. |
+| `bool get(string section, string key, bool def)` | bool | Bool value or default. |
+
+### Set values
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `void set(string section, string key, string value)` | — | Set string. |
+| `void set(string section, string key, int value)` | — | Set int. |
+| `void set(string section, string key, float value)` | — | Set float. |
+| `void set(string section, string key, bool value)` | — | Set bool. |
+
+### Sections and lines
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `int lines(string section)` | int | Number of lines (key-value pairs) in the section. |
+| `void get(string section, int line, out string key, out string value)` | — | Get key and value by line index. |
+| `void delete(string section)` | — | Delete entire section. |
+| `void delete(string section, int line)` | — | Delete one line in the section. |
+| `void add(string section, string key, string value)` | — | Add a key-value line to the section. |
+
+### Persistence
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `void save()` | — | Save to the default file. |
+| `void save(string fileName)` | — | Save to the given file path. |
+
+### Usage
+
+- Load user config: `GamePlay.gpConfigUserFile()`.
+- Load a mission or data file: `GamePlay.gpLoadSectionFile(fileName)`.
+- Create in memory: `GamePlay.gpCreateSectionFile()`.
+- Always check `exist(section, key)` or use the `get(..., def)` overloads when reading.
+- Call `save()` or `save(fileName)` after changes if the file should be persisted.
--- a/mission-script-api/external-types.md
+++ b/mission-script-api/external-types.md
@ -0,0 +1,41 @@
+# External Types Used by Mission Scripts
+
+Mission scripts use some types that are not documented in the main API. This page lists the ones commonly used; their full definitions are provided by the game at runtime.
+
+---
+
+## Limb and damage types
+
+Mission scripts use these for damage and parameters in **AMission** callbacks and **AiAircraft** methods.
+
+| Type | Kind | Description |
+|------|------|-------------|
+| **LimbNames** | enum | Limb identifiers (e.g. wings, tail, rudder). Used in `OnAircraftCutLimb`, `AiAircraft.hitLimb`, `cutLimb`, and **AiLimbDamage.LimbId**. |
+| **NamedDamageTypes** | enum | Named damage type identifiers. Used in `OnActorDamaged`, `OnAircraftDamaged`, and **AiAircraft.hitNamed** / **hitSelfNamed**. |
+| **ParameterTypes** | enum | Parameter identifiers for `AiAircraft.getParameter(type, subtype)`. |
+
+When building your mission script, ensure your project can resolve these types (they are supplied by the game or its dependencies).
+
+---
+
+## Geometry types
+
+Used for positions, directions, and other geometry in **IGamePlay**, **AMission** callbacks, and world interfaces.
+
+| Type | Kind | Description |
+|------|------|-------------|
+| **Point2d** | struct/class | 2D point (x, y). Used in `gpFindPath`, `gpMakeUserLabel`, **GPUserLabel.pos** (when 2D). |
+| **Point3d** | struct/class | 3D point (x, y, z). Used in **AiActor.Pos()**, **OnBuildingKilled**, **OnBombExplosion**, **GroundBuilding**, **GroundStationary**, **AiBirthPlace.Pos()**, waypoints, etc. |
+| **Vector2d** | struct/class | 2D vector. Used in **EnemyAirInterf.V_**. |
+| **Vector3d** | struct/class | 3D vector. Used in **AiAirGroup.Vwld()** and other world APIs. |
+
+You can use these types by adding the appropriate reference or using directive so that names like `Point3d` and `Point2d` resolve when compiling your mission script.
+
+---
+
+## Summary
+
+- Limb and damage: `LimbNames`, `NamedDamageTypes`, `ParameterTypes`.
+- Geometry: `Point2d`, `Point3d`, `Vector2d`, `Vector3d`.
+
+No further API detail for these types is documented here; see the game SDK or runtime for member lists and semantics.
--- a/mission-script-api/gameplay.md
+++ b/mission-script-api/gameplay.md
@ -0,0 +1,169 @@
+# IGamePlay
+
+**Kind:** interface
+
+**IGamePlay** is the main interface for mission scripts to interact with the game: time, players, actors, birth places, airports, triggers, HUD messages, section files, pathfinding, and user labels. Access it via `Mission.GamePlay` (or `Battle.GamePlay`).
+
+---
+
+## Access and mode
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool gpIsValidAccess()` | bool | Whether the current context may call gameplay methods. |
+| `object[] gpInvoke(object[] args)` | object[] | Invoke internal gameplay logic (implementation-specific). |
+| `bool gpIsServerSingle()` | bool | True if single-player server. |
+| `bool gpIsServerDedicated()` | bool | True if dedicated server. |
+| `bool gpBattleIsRun()` | bool | True if battle is running. |
+
+---
+
+## Time and difficulty
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `double gpTimeofDay()` | double | Time of day. |
+| `ITime gpTime()` | ITime | Time interface (ticks, current time, conversion). |
+| `DifficultySetting gpDifficultyGet()` | DifficultySetting | Current difficulty settings. |
+
+---
+
+## Players
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `Player gpPlayer()` | Player | Local player. |
+| `Player[] gpRemotePlayers()` | Player[] | Remote players (multiplayer). |
+
+---
+
+## Actors and world objects
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool gpActorIsValid(AiActor actor)` | bool | Whether the actor reference is still valid. |
+| `AiActor gpActorByName(string actorName)` | AiActor | Find actor by full name (e.g. `"0:ShortName"`). |
+| `int[] gpArmies()` | int[] | Army indices. |
+| `string gpArmyName(int army)` | string | Name of the army. |
+| `AiBirthPlace[] gpBirthPlaces()` | AiBirthPlace[] | All spawn points. |
+| `AiAirport[] gpAirports()` | AiAirport[] | All airports. |
+| `AiAirGroup[] gpAirGroups(int Army)` | AiAirGroup[] | Air groups for the given army. |
+| `GroundStationary[] gpGroundStationarys()` | GroundStationary[] | All stationary objects. |
+| `GroundStationary[] gpGroundStationarys(string Country)` | GroundStationary[] | Stationaries filtered by country. |
+| `GroundStationary[] gpGroundStationarys(double x, double y, double r)` | GroundStationary[] | Stationaries in radius `r` around (x, y). |
+| `GroundStationary[] gpGroundStationarys(string Country, double x, double y, double r)` | GroundStationary[] | By country and position/radius. |
+| `AiGroundGroup[] gpGroundGroups(int Army)` | AiGroundGroup[] | Ground groups for the given army. |
+
+---
+
+## Air groups (create / get)
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `AiAirGroup gpMakeAirGroup(AiAircraft[] items, AiAirWayPoint[] way)` | AiAirGroup | Create an air group from aircraft and waypoints. |
+| `AiAirGroup gpAiAirGroup(int ID, int army)` | AiAirGroup | Get air group by ID and army. |
+
+---
+
+## Triggers and actions
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `AiTrigger gpGetTrigger(string name)` | AiTrigger | Get trigger by name. |
+| `AiAction gpGetAction(string name)` | AiAction | Get action by name (e.g. to call `Do()` when a trigger fires). |
+
+---
+
+## Front and terrain
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool gpFrontExist()` | bool | Whether a front exists. |
+| `int gpFrontArmy(double x, double y)` | int | Army at front at (x, y). |
+| `double gpFrontDistance(int army, double x, double y)` | double | Front distance for army at (x, y). |
+| `string gpSectorName(double x, double y)` | string | Sector name at (x, y). |
+| `LandTypes gpLandType(double x, double y)` | LandTypes | Land type at (x, y). |
+| `IRecalcPathParams gpFindPath(Point2d a, double ra, Point2d b, double rb, PathType type, int army)` | IRecalcPathParams | Find path between two circles; see [Pathfinding And Terrain](mission-script-api/pathfinding-and-terrain). |
+
+---
+
+## Missions and battle control
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `int gpNextMissionNumber()` | int | Next mission number (for loading additional missions). |
+| `void gpPostMissionLoad(string fileName)` | — | Load mission by file name. |
+| `void gpPostMissionLoad(ISectionFile file)` | — | Load mission from section file. |
+| `void gpBattleStop()` | — | Stop the battle. |
+
+---
+
+## HUD and logging
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `void gpAviPlay(string args)` | — | Play AVI (arguments format is implementation-specific). |
+| `void gpHUDLogCenter(string msg)` | — | Show message in HUD center (all). |
+| `void gpHUDLogCenter(Player[] to, string msg)` | — | Show to specific players. |
+| `void gpHUDLogCenter(Player[] to, string msg, object[] parms)` | — | With format parameters. |
+| `void gpHUDLogCenter(Player[] to, string msg, object[] parms, double lifeTime)` | — | With format parameters and lifetime. |
+| `void gpLogServer(string format)` | — | Log on server. |
+| `void gpLogServer(string format, object[] args)` | — | Log with format args. |
+| `void gpLogServer(Player[] to, string format, object[] args)` | — | Log to specific players. |
+| `void gpLogServerBegin(Player[] to, string format)` | — | Begin multi-part log. |
+| `void gpLogServerArg(bool newArg, string format, object[] parms)` | — | Add log argument. |
+| `void gpLogServerEnd()` | — | End multi-part log. |
+
+---
+
+## Section files (config / data)
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `ISectionFile gpConfigUserFile()` | ISectionFile | User config section file. |
+| `ISectionFile gpCreateSectionFile()` | ISectionFile | Create empty section file. |
+| `ISectionFile gpCreateSectionFile(string line, out string firstWord)` | ISectionFile | Create from line; `firstWord` is first token. |
+| `ISectionFile gpLoadSectionFile(string fileName)` | ISectionFile | Load section file from path. |
+
+---
+
+## Order mission menu
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `void gpSetOrderMissionMenu(Player player, bool thisSubMenu, int ID, string[] keys, bool[] bSubMenu)` | — | Set order mission menu for player (keys and submenu flags). |
+
+---
+
+## Translator
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `gpDictionaryFilePath` | string | Path to dictionary (get/set). |
+| `string gpTranslate(string msg, string language, int debugLevel)` | string | Translate message for language. |
+
+---
+
+## User labels (map labels)
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `GPUserLabel gpMakeUserLabel(Point2d pos, Player Player, string Text, double Time, int type)` | GPUserLabel | Create a user label. |
+| `void gpDrawUserLabel(GPUserLabel ul)` | — | Draw label (all). |
+| `void gpDrawUserLabel(Player[] to, GPUserLabel ul)` | — | Draw for specific players. |
+| `void gpDrawUserLabel(int army, GPUserLabel ul)` | — | Draw for army. |
+| `void gpDeleteUserLabel(GPUserLabel ul)` | — | Delete label (all). |
+| `void gpDeleteUserLabel(Player[] to, GPUserLabel ul)` | — | Delete for specific players. |
+| `void gpDeleteUserLabel(int army, GPUserLabel ul)` | — | Delete for army. |
+
+---
+
+## Typical usage
+
+- Resolve actors with `gpActorByName`; check with `gpActorIsValid` before use.
+- Get spawn points and airports with `gpBirthPlaces()`, `gpAirports()`.
+- Create or get air groups with `gpMakeAirGroup`, `gpAiAirGroup`.
+- Fire actions when triggers activate (e.g. in `OnTrigger`) by getting the action with `gpGetAction(name)` and calling `Do()`.
+- Show messages with `gpHUDLogCenter` or `gpLogServer`.
+- Load/save config or mission data with `gpLoadSectionFile`, `gpCreateSectionFile`, `gpConfigUserFile`, and the **ISectionFile** API (see [Events And Section File](mission-script-api/events-and-section-file)).
+- Pathfinding: `gpFindPath` with **PathType** and **IRecalcPathParams** (see [Pathfinding And Terrain](mission-script-api/pathfinding-and-terrain)).
--- a/mission-script-api/mission-and-battle.md
+++ b/mission-script-api/mission-and-battle.md
@ -0,0 +1,199 @@
+# Mission and Battle
+
+Mission scripts derive from **AMission** and run inside an **ABattle**. The battle provides **GamePlay** and **Time**; missions override virtual methods to react to game events and schedule delayed callbacks with **Timeout** / **DoTimeout**.
+
+---
+
+## AMission
+
+**Kind:** abstract class  
+
+Base class for all mission scripts. The game loads a class named `Mission` that inherits from `AMission` and calls its virtual methods when battle and game events occur.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sPathMyself` | string | Deprecated; path of the mission script. Will be removed. |
+| `PathMyself` | string | Path of the mission script. |
+| `BaseMissionPath` | static string | Path of the "zero" mission with trailing directory separator. |
+| `MissionFileName` | string | Name of the mission file (e.g. for mission code). |
+| `ScriptFileName` | string | Name of the script file. |
+| `GamePlay` | IGamePlay | Shortcut for `Battle.GamePlay`. Main API for actors, HUD, triggers, etc. |
+| `Time` | ITime | Shortcut for `Battle.Time`. Game and real time, ticks. |
+| `Battle` | ABattle | The battle this mission belongs to. |
+| `MissionNumber` | int | This mission's number (set in `Init`). |
+| `MissionNumberListener` | int | Mission number this instance listens to; if &lt; 0, listens to all. Set e.g. in `OnBattleStarted`. |
+
+### Static / shared
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `DataDictionary` | `Dictionary<string, object>` | Shared key-value store for mission data. |
+
+### Methods (virtual; override in your mission)
+
+#### Lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `void Init(ABattle battle, int missionNumber)` | Called when the mission is attached. Sets `Battle`, `MissionNumber`, `MissionNumberListener`; then calls `Inited()`. |
+| `void Inited()` | Override for one-time setup after `Init`. |
+| `double GetBattleLengthTicks()` | Default: 4 hours in ticks. Override to define battle length. |
+| `bool IsMissionListener(int missionNumber)` | Default: true if `MissionNumberListener` &lt; 0, else true when `missionNumber == MissionNumberListener`. |
+
+#### Battle lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `void OnBattleInit()` | Battle is initializing. |
+| `void OnBattleStarted()` | Battle has started. |
+| `void OnBattleStoped()` | Battle has stopped. |
+
+#### Ticks
+
+| Method | Description |
+|--------|-------------|
+| `void OnTickGame()` | Called each game tick. |
+| `void OnTickReal()` | Called each real-time tick. |
+
+#### Missions and players
+
+| Method | Description |
+|--------|-------------|
+| `void OnMissionLoaded(int missionNumber)` | A mission was loaded. |
+| `void OnPlayerConnected(Player player)` | Player connected. |
+| `void OnPlayerDisconnected(Player player, string diagnostic)` | Player disconnected. |
+| `void OnPlayerArmy(Player player, int army)` | Player selected an army. |
+
+#### Actors (generic)
+
+| Method | Description |
+|--------|-------------|
+| `void OnActorCreated(int missionNumber, string shortName, AiActor actor)` | Actor created. |
+| `void OnActorDestroyed(int missionNumber, string shortName, AiActor actor)` | Actor destroyed. |
+| `void OnActorDamaged(... AiActor actor, AiDamageInitiator initiator, NamedDamageTypes damageType)` | Actor received damage. |
+| `void OnActorDead(int missionNumber, string shortName, AiActor actor, List<DamagerScore> damages)` | Actor killed. |
+| `void OnActorTaskCompleted(int missionNumber, string shortName, AiActor actor)` | Actor task completed. |
+
+#### Triggers
+
+| Method | Description |
+|--------|-------------|
+| `void OnTrigger(int missionNumber, string shortName, bool active)` | Trigger activated or deactivated. |
+
+#### Aircraft
+
+| Method | Description |
+|--------|-------------|
+| `void OnAircraftDamaged(... AiAircraft aircraft, AiDamageInitiator initiator, NamedDamageTypes damageType)` | Aircraft damaged. |
+| `void OnAircraftLimbDamaged(... AiAircraft aircraft, AiLimbDamage limbDamage)` | Aircraft limb damaged. |
+| `void OnAircraftCutLimb(... AiAircraft aircraft, AiDamageInitiator initiator, LimbNames limbName)` | Aircraft limb cut off. |
+| `void OnAircraftTookOff(... AiAircraft aircraft)` | Aircraft took off. |
+| `void OnAircraftLanded(... AiAircraft aircraft)` | Aircraft landed. |
+| `void OnAircraftCrashLanded(... AiAircraft aircraft)` | Aircraft crash-landed. |
+| `void OnAircraftKilled(... AiAircraft aircraft)` | Aircraft killed. |
+
+#### Persons (crew, parachutists)
+
+| Method | Description |
+|--------|-------------|
+| `void OnPersonMoved(AiPerson person, AiActor fromCart, int fromPlaceIndex)` | Person moved to another cart/place. |
+| `void OnPersonHealth(AiPerson person, AiDamageInitiator initiator, float deltaHealth)` | Person health changed. |
+| `void OnPersonParachuteLanded(AiPerson person)` | Person landed by parachute. |
+| `void OnPersonParachuteFailed(AiPerson person)` | Parachute failed. |
+
+#### Places (player entering/leaving vehicles)
+
+| Method | Description |
+|--------|-------------|
+| `void OnPlaceEnter(Player player, AiActor actor, int placeIndex)` | Player entered a place (seat) in an actor. |
+| `void OnPlaceLeave(Player player, AiActor actor, int placeIndex)` | Player left a place. |
+| `void OnCarter(AiActor actor, int placeIndex)` | Carter event. |
+| `void OnAutopilotOn(AiActor actor, int placeIndex)` | Autopilot turned on. |
+| `void OnAutopilotOff(AiActor actor, int placeIndex)` | Autopilot turned off. |
+
+#### Other events
+
+| Method | Description |
+|--------|-------------|
+| `void OnAiAirNewEnemy(AiAirEnemyElement element, int army)` | New air enemy detected. |
+| `void OnSingleBattleSuccess(bool success)` | Single battle success/failure. |
+| `void OnOrderMissionMenuSelected(Player player, int ID, int menuItemIndex)` | Player selected an order mission menu item. |
+| `void OnBuildingKilled(string title, GP.Point3d pos, AiDamageInitiator initiator, int eventArgInt)` | Building destroyed. |
+| `void OnStationaryKilled(int missionNumber, GroundStationary _stationary, AiDamageInitiator initiator, int eventArgInt)` | Stationary object destroyed. |
+| `void OnBombExplosion(string title, double mass, GP.Point3d pos, AiDamageInitiator initiator, int eventArgInt)` | Bomb exploded. |
+| `void OnUserCreateUserLabel(GPUserLabel ul)` | User created a map label. |
+| `void OnUserDeleteUserLabel(GPUserLabel ul)` | User deleted a map label. |
+
+#### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `void Timeout(double sec, DoTimeout doTimeout)` | Schedules `doTimeout` to be invoked after `sec` seconds (game time). Forwards to `Battle.Timeout`. |
+| `object[] OnIntraMissionsMessage(string sMsg, object[] args = null)` | Optional handler for inter-mission messages; default returns null. |
+
+### Usage
+
+- Access game state via `GamePlay` and `Time`.
+- Override only the `On*` methods you need; others have empty default implementations.
+- Use `MissionNumberListener` (e.g. set to `-1` in `OnBattleStarted` to listen to all missions) so your mission receives events for the intended mission number.
+- Use `Timeout(seconds, callback)` for delayed logic (e.g. spawn after N seconds).
+
+---
+
+## ABattle
+
+**Kind:** class (implements `IBattle`)  
+
+The battle is the environment where missions run. There is one battle per game session. Missions are registered with the battle and receive events through it.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `GamePlay` | IGamePlay | Gameplay interface (time, players, actors, HUD, etc.). |
+| `Time` | ITime | Time interface (game/real time, ticks). |
+
+### Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `AMission GetBaseMission()` | AMission or null | Returns the first registered mission (mission number 0), or null if none. |
+| `void Timeout(double sec, DoTimeout doTimeout)` | — | Schedules `doTimeout` to run after `sec` seconds of game time. |
+
+Mission code typically uses `Battle` from `AMission.Battle` and calls `Timeout` via `Mission.Timeout(sec, doTimeout)`.
+
+---
+
+## IBattle
+
+**Kind:** interface  
+
+Internal interface implemented by **ABattle**. Mission scripts usually work with **ABattle** and **AMission** only.
+
+Methods include: `OnTickGame`, `OnTickReal`, `OnEventGame`, `GetEnemyAirGroupIDs`, `GetDamageVictims`, `GetDamageInitiators`, `ComputePlayerScore`.
+
+---
+
+## DoTimeout
+
+**Kind:** delegate  
+
+```csharp
+public delegate void DoTimeout();
+```
+
+Callback type for delayed execution. Pass a parameterless method to `Timeout(double sec, DoTimeout doTimeout)` to run it after `sec` seconds of game time.
+
+### Example
+
+```csharp
+public override void OnBattleStarted()
+{
+    base.OnBattleStarted();
+    Timeout(30.0, () => {
+        GamePlay.gpHUDLogCenter("Message after 30 seconds.");
+    });
+}
+```
--- a/mission-script-api/pathfinding-and-terrain.md
+++ b/mission-script-api/pathfinding-and-terrain.md
@ -0,0 +1,99 @@
+# Pathfinding and Terrain
+
+Mission scripts use **PathType**, **LandTypes**, and **IRecalcPathParams** with `GamePlay.gpFindPath()` for pathfinding. **RecalcPathState** indicates the result. **ActorName** provides helpers for parsing and building actor names (mission number + short name).
+
+---
+
+## RecalcPathState
+
+**Kind:** enum  
+
+Result of a pathfinding request.
+
+| Value | Description |
+|-------|-------------|
+| `FAILED` | Path finding failed. |
+| `SUCCESS` | Path found. |
+| `WAIT` | Still computing. |
+
+Check `IRecalcPathParams.State` after calling `gpFindPath`.
+
+---
+
+## PathType
+
+**Kind:** enum  
+
+Type of path to compute.
+
+| Value | Description |
+|-------|-------------|
+| `GROUND` | Ground path. |
+| `RAIL` | Rail path. |
+| `WATER` | Water path. |
+| `AVIA` | Air path. |
+
+Pass to `GamePlay.gpFindPath(Point2d a, double ra, Point2d b, double rb, PathType type, int army)`.
+
+---
+
+## LandTypes
+
+**Kind:** enum (Flags)  
+
+Terrain type at a point (from `GamePlay.gpLandType(double x, double y)`).
+
+| Value | Description |
+|-------|-------------|
+| `NONE` | 0 |
+| `CITY` | 0x10 |
+| `ROAD` | 0x20 |
+| `RAIL` | 0x40 |
+| `HIGHWAY` | 0x80 |
+| `WATER` | 0x1C |
+| `OBJECTS_MASK` | 0x03 |
+| `ROAD_MASK` | 0xE0 |
+
+---
+
+## IRecalcPathParams
+
+**Kind:** interface  
+
+Returned by `GamePlay.gpFindPath()`. Contains the result state, path waypoints, bridges, and length.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `State` | RecalcPathState | FAILED, SUCCESS, or WAIT. |
+| `Bridges` | AiBridge[] | Bridges on the path. |
+| `Path` | AiWayPoint[] | Waypoints of the path. |
+| `Length` | double | Path length. |
+
+### Usage
+
+```csharp
+var prms = GamePlay.gpFindPath(start, rStart, end, rEnd, PathType.GROUND, army);
+if (prms.State == RecalcPathState.SUCCESS)
+{
+    foreach (var wp in prms.Path)
+        // use wp.P, wp.Speed
+}
+```
+
+---
+
+## ActorName
+
+**Kind:** static class  
+
+Utility for actor names: full names are `"missionNumber:shortName"` (e.g. `"0:PlayerSpawn"`).
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool IsShort(string actorName)` | bool | True if the name has no `':'` (short name only). |
+| `string Full(int missionNumber, string shortActorName)` | string | Build full name: `"missionNumber:shortName"`. |
+| `void Parce(string fullActorName, out int missionNumber, out string shortName)` | — | Parse full name into mission number and short name. (Note: method name is "Parce", not "Parse".) |
+| `string Short(string fullActorName)` | string | Get short name part (after `':'`). |
+| `int MissionNumber(string fullActorName)` | int | Get mission number part (before `':'`). |
+
+Use when building names for `GamePlay.gpActorByName()` or when parsing actor names from events (e.g. in `OnActorCreated` the actor’s `Name()` is the full name).
--- a/mission-script-api/player.md
+++ b/mission-script-api/player.md
@ -0,0 +1,61 @@
+# Player
+
+**Kind:** interface
+
+**Player** represents a local or remote player. Mission scripts get the local player from `GamePlay.gpPlayer()` and remote players from `GamePlay.gpRemotePlayers()`. Player references are passed into many **AMission** events (e.g. `OnPlayerConnected`, `OnPlaceEnter`, `OnOrderMissionMenuSelected`).
+
+---
+
+## Identity and connection
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `string Name()` | string | Player name. |
+| `bool IsConnected()` | bool | Whether the player is connected. |
+| `int Channel()` | int | Channel index. |
+| `string ConnectAddress()` | string | Connection address. |
+| `int ConnectPort()` | int | Connection port. |
+| `int Ping()` | int | Ping (typically milliseconds). |
+| `string LanguageName()` | string | Player language. |
+
+---
+
+## Army and place
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `int Army()` | int | Current army index. |
+| `AiActor Place()` | AiActor | Actor the player is in (vehicle/aircraft); null if none. |
+| `int PlacePrimary()` | int | Primary place (seat) index. |
+| `int PlaceSecondary()` | int | Secondary place index. |
+| `AiPerson PersonPrimary()` | AiPerson | Person (crew) in primary place. |
+| `AiPerson PersonSecondary()` | AiPerson | Person in secondary place. |
+| `bool AutopilotPrimary()` | bool | Autopilot on for primary place. |
+| `bool AutopilotSecondary()` | bool | Autopilot on for secondary place. |
+
+---
+
+## Army selection and restrictions
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool IsExpelArmy(int army)` | bool | Whether the player is expelled from the army. |
+| `bool IsExpelUnit(AiActor unit)` | bool | Whether the player is expelled from the unit. |
+| `void SelectArmy(int army)` | — | Select army for the player. |
+
+---
+
+## Entering and leaving places
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `void PlaceEnter(AiActor actor, int indxPlace)` | — | Put the player into the given place (seat) of the actor. |
+| `void PlaceLeave(int indxPlace)` | — | Remove the player from the current place. |
+
+---
+
+## Usage
+
+- Use `gpPlayer()` for the local player and `gpRemotePlayers()` for others (e.g. to target HUD or log messages).
+- In `OnPlaceEnter` / `OnPlaceLeave`, the `Player` and `placeIndex` identify who entered which seat of which `AiActor`.
+- Use `Army()` to filter or assign sides; use `Place()` and `PersonPrimary()` / `PersonSecondary()` to know what the player is controlling.
--- a/mission-script-api/script-loading.md
+++ b/mission-script-api/script-loading.md
@ -0,0 +1,36 @@
+# Script Loading
+
+**IScriptRemote** and **ScriptRemote** are used by the game to load the battle and mission scripts. Most mission authors do not implement or call these; they write the `Mission` class that gets loaded by the game.
+
+---
+
+## IScriptRemote
+
+**Kind:** interface  
+
+Contract for loading battle and mission scripts.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `IBattle Battle` | IBattle | The current battle instance after loading. |
+
+### Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `string loadBattleScript(string fileName, IGamePlay gamePlay)` | string | Load the battle script from the given file. If `fileName` is null, a default **ABattle** is created. The script must contain a class named `Battle` that inherits from **ABattle**. On success returns null; on error returns an error message. |
+| `string loadMissionScript(string fileName, int missionNumber, string sScriptFileName)` | string | Load a mission script from the given file. The script must contain a class named `Mission` that inherits from **AMission**. On success returns null; on error returns the exception message. |
+
+---
+
+## ScriptRemote
+
+**Kind:** class (implements IScriptRemote)  
+
+Default implementation of **IScriptRemote**. Loads the script file, creates instances of `Battle` and `Mission` by name, and wires them to the battle.
+
+### Usage
+
+Mission script authors need to ensure their script exposes a class named `Mission` deriving from **AMission** and (if providing a custom battle) a class named `Battle` deriving from **ABattle**.
--- a/mission-script-api/time-and-difficulty.md
+++ b/mission-script-api/time-and-difficulty.md
@ -0,0 +1,97 @@
+# Time and Difficulty
+
+Mission scripts use **ITime** for game and real time and tick conversion, and **DifficultySetting** to read or apply difficulty flags (realism, fuel, ammo, views, etc.).
+
+---
+
+## ITime
+
+**Kind:** interface  
+
+Application (game) time and real time, both in seconds. Game time can pause; real time always advances. Access via `Mission.Time` or `GamePlay.gpTime()`.
+
+### Pause and mode
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `bool isPaused()` | bool | True if game time is paused. |
+| `bool isRealOnly()` | bool | True if game time is constantly stopped (real-time only). |
+
+### Ticks
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `int tickCounter()` | int | Current tick number. |
+| `double tick()` | double | Start time of current tick (seconds). |
+| `double tickNext()` | double | Start time of next tick (seconds). |
+| `double tickLen()` | double | Tick duration (seconds). |
+| `double tickConstLen()` | double | Constant tick length (seconds). |
+| `double tickOffset()` | double | Relative position in current tick (0–1). |
+| `double tickOffset(double t)` | double | Relative position of time `t` in its tick (0–1). |
+
+### Current time
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `double current()` | double | Current game time (seconds); changes during the real tick. |
+| `double currentReal()` | double | Current real time (seconds); non-negative. |
+| `double end()` | double | End of game time in the current real tick. |
+| `double endReal()` | double | End of real time in the current real tick. |
+| `double raw()` | double | Time since application start in seconds; always advances. |
+
+### Conversion
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `double fromReal(double real)` | double | Convert real time to game time. |
+| `double toReal(double t)` | double | Convert game time to real time. |
+| `double TicksToSecs(long tm)` | double | Convert ticks to seconds. |
+| `long SecsToTicks(double tm)` | long | Convert seconds to ticks. |
+
+### Usage
+
+- Use `current()` for in-game delays and `Timeout(sec, callback)` (game time).
+- Use `SecsToTicks` / `TicksToSecs` when APIs or **AMission.GetBattleLengthTicks()** work in ticks.
+
+---
+
+## DifficultySetting
+
+**Kind:** class  
+
+Holds difficulty options as boolean flags. Get current settings with `GamePlay.gpDifficultyGet()`. Use `get()` / `set(long)` for bitmask I/O, or the preset methods and properties.
+
+### Preset masks and methods
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `REALISTIC_MASK` | static long | Bitmask for full realism. |
+| `EASY_MASK` | static long | Bitmask for easy. |
+| `NORMAL_MASK` | static long | Bitmask for normal. |
+| `bool isRealistic()` | bool | True if current flags match realism preset. |
+| `bool isNormal()` | bool | True if match normal preset. |
+| `bool isEasy()` | bool | True if match easy preset. |
+| `bool isCustom()` | bool | True if not exactly one of the presets. |
+| `void setRealistic()` | — | Apply realism preset. |
+| `void setNormal()` | — | Apply normal preset. |
+| `void setEasy()` | — | Apply easy preset. |
+| `void set(DifficultySetting s)` | — | Copy from another instance. |
+| `void set(long state)` | — | Set from bitmask. |
+| `long get()` | long | Current state as bitmask. |
+
+### Main properties (flags)
+
+Flight and systems: `Wind_N_Turbulence`, `Flutter_Effect`, `Stalls_N_Spins`, `Blackouts_N_Redouts`, `Engine_Temperature_Effects`, `Torque_N_Gyro_Effects`, `Realistic_Landings`, `Takeoff_N_Landing`, `ComplexEManagement`.
+
+Views and HUD: `Cockpit_Always_On`, `No_Outside_Views`, `Head_Shake`, `No_Icons`, `No_Padlock`, `Clouds`, `No_Map_Icons`, `NoMinimapPath`.
+
+Weapons and vulnerability: `Realistic_Gunnery`, `Limited_Ammo`, `Limited_Fuel`, `Vulnerability`, `Realistic_Bombing`.
+
+Game rules: `NoAutopilot`, `NoReplacement`, `NoSelect`, `NoReplacementArmy`, `NoReplacementPlace`, `NoSelectArmy`, `NoCreate`, `NoGroundControlTargets`.
+
+`AntropomorphicControl` exists but is disabled in the current implementation.
+
+### Usage
+
+- Read difficulty with `GamePlay.gpDifficultyGet()` and check flags or `isRealistic()` / `isNormal()` / `isEasy()`.
+- Modify only if your mission is intended to change global difficulty; use `set(long)` or the preset methods.
--- a/mission-script-api/world/actor-hierarchy.md
+++ b/mission-script-api/world/actor-hierarchy.md
@ -0,0 +1,196 @@
+# Actor Hierarchy and Damage
+
+Actors are game objects: persons (crew), carts (vehicles, aircraft), and groups. All share **AiActor**; **AiPerson** and **AiCart** extend it. Damage events use **AiDamageInitiator**, **AiDamageTool**, **DamagerScore**, and **AiLimbDamage**. **AiWayPoint** and **AiGroup** are used for movement and formation; **AiBridge** for bridges. **CrewFunction** identifies crew roles.
+
+---
+
+## AiActor
+
+**Kind:** interface  
+
+Base interface for all game objects (units, vehicles, aircraft, groups).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Tag` | object | Get/set; mission script can store arbitrary data. |
+| `bool IsValid()` | bool | Whether the actor reference is still valid. |
+| `bool IsAlive()` | bool | Whether the actor is alive. |
+| `bool IsTaskComplete()` | bool | Whether the actor’s task is complete. |
+| `int Army()` | int | Army index. |
+| `string Name()` | string | Full name (e.g. `"missionNumber:shortName"`). |
+| `AiGroup Group()` | AiGroup | Group this actor belongs to; null if none. |
+| `Point3d Pos()` | Point3d | Position. |
+
+---
+
+## AiPerson
+
+**Kind:** interface (extends AiActor)  
+
+Represents a person (pilot, gunner, etc.) in the world.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Id` | string | Get/set identifier. |
+| `Health` | float | Current health. |
+| `AiCart Cart()` | AiCart | Cart (vehicle) the person is in; null if none. |
+| `int Place()` | int | Place (seat) index in the cart. |
+| `Player Player()` | Player | Player controlling this person; null if AI. |
+| `void SayNiceKill()` | — | Trigger “nice kill” feedback. |
+
+---
+
+## AiCart
+
+**Kind:** interface (extends AiActor)  
+
+Represents a vehicle or aircraft that has places (seats) and can have crew.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `int Carter()` | int | Carter (driver/pilot) place index. |
+| `int Places()` | int | Number of places (seats). |
+| `CrewFunction CrewFunctionPlace(int place)` | CrewFunction | Role at the given place. |
+| `bool ExistCabin(int place)` | bool | Whether the place has a cabin. |
+| `AiPerson Person(int place)` | AiPerson | Person at the place; null if empty. |
+| `Player Player(int place)` | Player | Player at the place; null if AI or empty. |
+| `void Destroy()` | — | Destroy the cart. |
+| `string InternalTypeName()` | string | Internal type name. |
+
+---
+
+## AiGroup
+
+**Kind:** interface (extends AiActor)  
+
+Group of actors with shared waypoints.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Idle` | bool | Get/set idle flag. |
+| `AiActor[] GetItems()` | AiActor[] | Members of the group. |
+| `AiWayPoint[] GetWay()` | AiWayPoint[] | Current waypoints. |
+| `int GetCurrentWayPoint()` | int | Index of current waypoint. |
+| `void SetWay(AiWayPoint[] way)` | — | Set new waypoints. |
+
+---
+
+## AiWayPoint
+
+**Kind:** class  
+
+Single waypoint: position and speed.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `P` | Point3d | Position. |
+| `Speed` | double | Speed. |
+| `AiWayPoint(ref Point3d p, double speed)` | constructor | Build waypoint. |
+
+Base for **AiAirWayPoint** and **AiGroundWayPoint** (see [Air](mission-script-api/world/air), [Ground](mission-script-api/world/ground)).
+
+---
+
+## AiBridge
+
+**Kind:** interface (extends AiActor)  
+
+Bridge actor; can notify life state change.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void LifeChanged(bool bLive)` | — | Notify that the bridge is now live or not. |
+
+---
+
+## AiDamageToolType
+
+**Kind:** enum  
+
+Type of damage tool.
+
+| Value | Description |
+|-------|-------------|
+| `Unknown` | 0 |
+| `Cannon` | Cannon. |
+| `Ordance` | Bomb/ordnance. |
+| `Collision` | Collision. |
+
+---
+
+## AiDamageTool
+
+**Kind:** class  
+
+Identifies the tool that caused damage (e.g. cannon, bomb).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Type` | AiDamageToolType | Kind of tool. |
+| `Name` | string | Tool name. |
+| `AiDamageTool(AiDamageToolType Type, string Name)` | constructor | Construct. |
+
+---
+
+## AiDamageInitiator
+
+**Kind:** class  
+
+Describes who or what caused damage: actor, person, player, and tool. Passed in damage callbacks (e.g. **OnActorDamaged**, **OnActorDead**, **OnAircraftKilled**).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Actor` | AiActor | Actor that caused damage; can be null. |
+| `Person` | AiPerson | Person (e.g. gunner); can be null. |
+| `Player` | Player | Player; can be null. |
+| `Tool` | AiDamageTool | Tool used; can be null. |
+| `static string DamageNameById(NamedDamageTypes DamageId)` | string | Name for a damage type. |
+
+---
+
+## DamagerScore
+
+**Kind:** class  
+
+Score entry for a damager (e.g. in **OnActorDead**).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `initiator` | AiDamageInitiator | Who caused damage. |
+| `score` | double | Score value. |
+| `time` | double | Time of damage. |
+
+Overrides `Equals` and `GetHashCode` based on initiator identity.
+
+---
+
+## AiLimbDamage
+
+**Kind:** class  
+
+Describes limb damage (used in **OnAircraftLimbDamaged** and **AiAircraft** limb APIs).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Initiator` | AiDamageInitiator | Who caused the damage. |
+| `LimbId` | LimbNames | Limb identifier. |
+| `OuterIntegrity` | float | Outer integrity. |
+| `InnerIntegrity` | float | Inner integrity. |
+| `static string LimbNameById(LimbNames LimbId)` | string | Name for limb. |
+
+---
+
+## CrewFunction
+
+**Kind:** enum  
+
+Crew role at a place.
+
+| Value | Description |
+|-------|-------------|
+| `Nil` | 0 |
+| `Pilot`, `CoPilot` | Pilot / co-pilot. |
+| `Bombardier`, `Radioman`, `Engineer`, `Observer` | Other crew. |
+| `Gunner`, `NoseGunner`, `TopGunner`, `WaistGunner`, `VentralGunner`, `RearGunner` | Gunners. |
+
+Use with **AiCart.CrewFunctionPlace(int place)**.
--- a/mission-script-api/world/air.md
+++ b/mission-script-api/world/air.md
@ -0,0 +1,243 @@
+# Air Actors and Groups
+
+**AiAircraft** extends **AiCart** and adds aircraft-specific state (regiment, fuel, weapons, damage). **AiAirGroup** represents a group of aircraft with waypoints and tasks. **AiAirWayPoint** and related enums define waypoint behavior. **AiAirEnemyElement** and **EnemyAirInterf** describe air enemies. Use **IGamePlay.gpAirGroups**, **gpMakeAirGroup**, **gpAiAirGroup** to get or create air groups.
+
+---
+
+## AiAircraft
+
+**Kind:** interface (extends AiCart)  
+
+Aircraft unit: regiment, fuel, rearm/refuel, limb and named damage, parameters.
+
+### Identity and regiment
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `bool IsKilled()` | bool | True if aircraft is killed. |
+| `Regiment Regiment()` | Regiment | Regiment info. |
+| `string HullNumber()` | string | Hull number. |
+| `string CallSign()` | string | Call sign. |
+| `int CallSignNumber()` | int | Call sign number. |
+| `string TypedName()` | string | Type name. |
+| `string VariantName()` | string | Variant name. |
+| `AircraftType Type()` | AircraftType | Aircraft type (fighter, bomber, etc.). |
+| `bool IsAirborne()` | bool | True if in the air. |
+| `AiAirGroup AirGroup()` | AiAirGroup | Air group this aircraft belongs to. |
+
+### Fuel and weapons
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void RearmPlane(bool gunsOnly)` | — | Rearm; if gunsOnly, only guns. |
+| `void RefuelPlane(int percentage)` | — | Refuel to given percentage. |
+| `int GetMinimumFuelInPercent()` | int | Minimum fuel (from aircraft.ini). |
+| `double GetFuelCapacity()` | double | Total fuel capacity (liters). |
+| `double GetCurrentFuelQuantity()` | double | Current fuel (liters). |
+| `int GetCurrentFuelQuantityInPercent()` | int | Current fuel (percent). |
+
+### Damage (limbs and named)
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void hitLimb(LimbNames limb, double value)` | — | Modify limb integrity (negative = damage, positive = set). |
+| `void cutLimb(LimbNames limb)` | — | Detach limb. |
+| `void hitNamed(NamedDamageTypes type)` | — | Activate named damage. |
+| `void hitSelfNamed(NamedDamageTypes type)` | — | Activate self named damage. |
+| `double getParameter(ParameterTypes type, int subtype)` | double | Get parameter; subtype -1 for generic. |
+
+### Communication
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void SayToGroup(AiAirGroup group, string msg)` | — | Send message to group. |
+
+---
+
+## AiAirGroup
+
+**Kind:** interface (extends AiGroup)  
+Air group: ID, army, aircraft count, task, waypoints, and enemy/friendly group relations.
+
+### Identity and counts
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `int ID()` | int | Group ID. |
+| `int getArmy()` | int | Army. |
+| `NOfAirc` | int | Current number of aircraft. |
+| `DiedAircrafts` | int | Number of dead aircraft. |
+| `InitNOfAirc` | int | Initial number of aircraft. |
+
+### Hierarchy and relations
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `AiAirGroup motherGroup()` | AiAirGroup | Mother group. |
+| `AiAirGroup clientGroup()` | AiAirGroup | Client group. |
+| `AiAirGroup leaderGroup()` | AiAirGroup | Leader group. |
+| `AiAirGroup[] candidates()` | AiAirGroup[] | Candidate groups. |
+| `AiAirGroup[] enemies()` | AiAirGroup[] | Enemy groups. |
+| `AiAirGroup[] attachedGroups()` | AiAirGroup[] | Attached groups. |
+| `AiAirGroup[] daughterGroups()` | AiAirGroup[] | Daughter groups. |
+| `Vector3d Vwld()` | Vector3d | World velocity. |
+
+### Type and weapons
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `bool isAircraftType(AircraftType t)` | bool | True if group has this aircraft type. |
+| `int aircraftEnginesNum()` | int | Number of engines. |
+| `bool hasBombs()` | bool | Has bombs. |
+| `bool hasRockets()` | bool | Has rockets. |
+| `bool hasCourseCannon()` | bool | Has course cannon. |
+| `bool hasCourseWeapon()` | bool | Has course weapon. |
+| `bool hasCourseTracers()` | bool | Has course tracers. |
+| `bool hasPayload()` | bool | Has payload. |
+| `bool hasBombsInInternalBays()` | bool | Has bombs in internal bays. |
+| `bool hasTorpedos()` | bool | Has torpedoes. |
+
+### Task and targets
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void calcDangerType(double[] dt)` | — | Compute danger type array. |
+| `AiAirGroupTask getTask()` | AiAirGroupTask | Current task. |
+| `void setTask(AiAirGroupTask task, AiAirGroup taskArg)` | — | Set task and optional target group. |
+| `void changeGoalTarget(AiActor taskArg)` | — | Change goal target actor. |
+
+### Enemy reporting
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void SayNewEnemyGroup(EnemyAirInterf EE)` | — | Report new enemy group. |
+| `void SayEnemyGroupChangedCourse(EnemyAirInterf EE)` | — | Report enemy course change. |
+| `void SayEnemyGroupChangedHeight(EnemyAirInterf EE)` | — | Report enemy height change. |
+| `void SayEnemyGroupChangedIdent(EnemyAirInterf EE)` | — | Report enemy identification change. |
+
+---
+
+## AiAirWayPoint
+
+**Kind:** class (extends AiWayPoint)  
+Air waypoint with action type, target, and attack/loiter options.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Action` | AiAirWayPointType | Waypoint action. |
+| `Target` | AiActor | Target actor (for attack waypoints). |
+| `GAttackType` | AiAirWayPointGAttackType | Ground attack type. |
+| `GAttackPasses` | AiAirWayPointGAttackPasses | Number of passes. |
+| `LoiterBegin` | bool | Loiter at start. |
+| `LoiterEnd` | bool | Loiter at end. |
+| `LoiterTime` | int | Loiter time. |
+
+Inherits `P` (Point3d) and `Speed` from **AiWayPoint**.
+
+---
+
+## AiAirWayPointType
+
+**Kind:** enum  
+| Value | Description |
+|-------|-------------|
+| `NORMFLY` | Normal fly. |
+| `TAKEOFF` | Take off (e.g. carrier). |
+| `LANDING` | Landing. |
+| `GATTACK_TARG` | Ground attack target. |
+| `GATTACK_POINT` | Ground attack point. |
+| `AATTACK_BOMBERS` | Attack bombers. |
+| `AATTACK_FIGHTERS` | Attack fighters. |
+| `HUNTING` | Hunting. |
+| `FOLLOW` | Follow friendly group. |
+| `ESCORT` | Escort. |
+| `COVER` | Cover friendly ground. |
+| `RECON` | Recon. |
+
+---
+
+## AiAirWayPointGAttackType / AiAirWayPointGAttackPasses
+
+**Kind:** enum  
+- **AiAirWayPointGAttackType**: `AUTO`, `LEVEL`, `DIVE`, `TOP_MAST`, `SHALLOW_DIVE`.
+- **AiAirWayPointGAttackPasses**: `AUTO`, `_1`, `_2`, `_3`, `_4`, `ALL_OUT`.
+
+---
+
+## AiAirGroupTask
+
+**Kind:** enum  
+| Value | Description |
+|-------|-------------|
+| `UNKNOWN` | 0 |
+| `FLY_WAYPOINT` | Flying waypoints. |
+| `ATTACH` | Attach. |
+| `DEFENDING` | Defending. |
+| `ATTACK_AIR` | Attack air. |
+| `ATTACK_GROUND` | Attack ground. |
+| `PURSUIT` | Pursuit. |
+| `TAKEOFF` | Takeoff. |
+| `RETURN` | Return. |
+| `LANDING` | Landing. |
+| `DO_NOTHING` | Idle. |
+
+---
+
+## AiAirEnemyElement
+
+**Kind:** class  
+Passed to **OnAiAirNewEnemy**. Describes an air enemy element.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `agID` | int | Air group ID. |
+| `army` | int | Army. |
+| `state` | int | State. |
+
+---
+
+## EnemyAirInterf
+
+**Kind:** interface  
+Snapshot of an enemy air entity (position, velocity, identification).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `ID_` | int | ID. |
+| `army_` | int | Army. |
+| `ident_` | IDState | Identification state. |
+| `P_` | Point3d | Position. |
+| `V_` | Vector2d | Velocity. |
+| `nOfAirc_` | int | Number of aircraft. |
+
+---
+
+## IDState
+
+**Kind:** enum  
+| Value | Description |
+|-------|-------------|
+| `NONE` | No identification. |
+| `TYPE` | Type known. |
+| `MARK` | Mark known. |
+| `ALL` | Full identification. |
+
+---
+
+## AircraftType
+
+**Kind:** enum (Flags)  
+Fighter, bomber, transport, etc. (e.g. `Fighter`, `Bomber`, `DiveBomber`, `TorpedoBomber`, `Scout`, `Transport`, `Glider`, `SailPlane`, `Sturmovik`, `JaBo`, `HeavyFighter`, `Blenheim`, …). Used with **AiAircraft.Type()** and **AiAirGroup.isAircraftType()**.
+
+---
+
+## DangerType
+
+**Kind:** enum  
+| Value | Description |
+|-------|-------------|
+| `VAL` | Valid. |
+| `BOMB` | Bomb. |
+| `STORM` | Storm. |
+| `FIGHT` | Fight. |
+| `RECON` | Recon. |
--- a/mission-script-api/world/ground.md
+++ b/mission-script-api/world/ground.md
@ -0,0 +1,126 @@
+# Ground Actors and Stationary Objects
+
+**AiGroundActor** and **AiGroundGroup** represent ground units (vehicles, ships, artillery, etc.). **GroundStationary** is for static objects (buildings, AA guns, etc.) that can be queried and destroyed. **GroundBuilding** and **GroundBombExplosion** are data holders for building titles/positions and bomb explosions. Use **IGamePlay.gpGroundGroups**, **gpGroundStationarys** to get ground groups and stationaries.
+
+---
+
+## AiGroundActor
+
+**Kind:** interface (extends AiCart)  
+Ground unit: type, fuel, health.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `AiGroundActorType Type()` | AiGroundActorType | Unit type (tank, truck, ship, etc.). |
+| `int Fuel()` | int | Fuel. |
+| `double Health()` | double | Health. |
+
+---
+
+## AiGroundGroup
+
+**Kind:** interface (extends AiGroup)  
+Ground group: position, group type, and string ID.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `void GetPos(out Point3d pos)` | — | Get group position. |
+| `AiGroundGroupType GroupType()` | AiGroundGroupType | Vehicle, train, ship, artillery, town. |
+| `string ID()` | string | Group ID. |
+
+---
+
+## AiGroundWayPoint
+
+**Kind:** class (extends AiWayPoint)  
+Ground waypoint with wait time and road/bridge info.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `waitTime` | double | Wait time at waypoint. |
+| `roadWidth` | double | Road width; also used for bridge index. |
+| `BridgeIdx` | int | Property: bridge index derived from roadWidth. |
+| `AiGroundWayPoint(ref Point3d p, double speed, double wait_time, double road_width)` | constructor | Construct. |
+
+---
+
+## AiGroundGroupType
+
+**Kind:** enum  
+| Value | Description |
+|-------|-------------|
+| `Vehicle` | 1 |
+| `Train` | |
+| `Ship` | |
+| `Artillery` | |
+| `Town` | |
+
+---
+
+## AiGroundActorType
+
+**Kind:** enum  
+Categories include: vehicles (Medic, Motorcycle, ArmoredCar, Tractor, Car, Amphibian, SPG, Tank, Bus, LightTruck, Truck, Trailer), stationary (Balloon, Generator, Predictor, Radar, Artillery, AAGun, Plane, GroundCrew, …), trains (EngineWagon, FreightWagon, PassengerWagon), ships (ShipMisc, ShipTransport, ShipDestroyer, ShipCruiser, ShipBattleship, ShipCarrier, ShipSubmarine), and statics (Bridge, House).
+
+---
+
+## AiAIChiefType
+
+**Kind:** static class  
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `GROUND` | 0x01 | Ground chief type. |
+
+---
+
+## AiAIChief
+
+**Kind:** interface (extends AiGroundGroup)  
+Chief ground group with field radius.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `double FieldR()` | double | Field radius. |
+
+---
+
+## GroundStationary
+
+**Kind:** interface  
+Static object on the map (building, AA, etc.). Obtain from **GamePlay.gpGroundStationarys()** overloads.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Title` | string | Title. |
+| `Name` | string | Name. |
+| `country` | string | Country. |
+| `Category` | string | Category. |
+| `pos` | Point3d | Position. |
+| `Type` | AiGroundActorType | Type. |
+| `void Destroy()` | — | Destroy the stationary. |
+| `IsAlive` | bool | True if still alive. |
+
+---
+
+## GroundBuilding
+
+**Kind:** class  
+Simple container for building title and position (e.g. in **OnBuildingKilled**-related events).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Title` | string | Building title. |
+| `pos` | Point3d | Position. |
+
+---
+
+## GroundBombExplosion
+
+**Kind:** class  
+Container for bomb explosion data (title, mass, position). Used in bomb explosion events and **OnBombExplosion**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Title` | string | Title. |
+| `Mass` | double | Mass. |
+| `pos` | Point3d | Position. |
--- a/mission-script-api/world/time-and-user-labels.md
+++ b/mission-script-api/world/time-and-user-labels.md
@ -0,0 +1,54 @@
+# Time and User Labels
+
+**ITime** is documented in the main docs: [Time And Difficulty](mission-script-api/time-and-difficulty). Mission scripts use **Mission.Time** or **GamePlay.gpTime()**. **GPUserLabel** and **GPUserIconType** are used with **IGamePlay** user-label methods (gpMakeUserLabel, gpDrawUserLabel, gpDeleteUserLabel) and in **OnUserCreateUserLabel** / **OnUserDeleteUserLabel**.
+
+---
+
+## ITime (cross-link)
+
+**Kind:** interface  
+See **[Time And Difficulty](mission-script-api/time-and-difficulty)** for the full **ITime** API: `current()`, `currentReal()`, `tick()`, `SecsToTicks`, `TicksToSecs`, `isPaused()`, etc.
+
+Access in mission scripts: `Mission.Time` or `GamePlay.gpTime()`.
+
+---
+
+## GPUserIconType
+
+**Kind:** enum  
+Icon type for a user map label.
+
+| Value | Description |
+|-------|-------------|
+| `Waypoint` | Waypoint. |
+| `Plane` | Plane. |
+| `AAGun` | AA gun. |
+| `Ship` | Ship. |
+| `Factory` | Factory. |
+| `Tank` | Tank. |
+| `Car` | Car. |
+| `Label` | Label. |
+
+Use when creating a label with **GamePlay.gpMakeUserLabel(Point2d pos, Player Player, string Text, double Time, int type)** (pass the enum value or equivalent int).
+
+---
+
+## GPUserLabel
+
+**Kind:** interface  
+Represents a user-created map label. Created with **GamePlay.gpMakeUserLabel()**; drawn/deleted with **gpDrawUserLabel** / **gpDeleteUserLabel**. Passed to **OnUserCreateUserLabel** and **OnUserDeleteUserLabel**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `pos` | Point2d | Position (get/set). |
+| `Player` | Player | Player (get/set). |
+| `Text` | string | Label text (get/set). |
+| `time` | double | Time (get/set). |
+| `type` | int | Icon type, e.g. **GPUserIconType** (get/set). |
+
+### Usage
+
+- Create: `var ul = GamePlay.gpMakeUserLabel(pos, player, text, time, (int)GPUserIconType.Waypoint);`
+- Show: `GamePlay.gpDrawUserLabel(ul);` or overloads for specific players/army.
+- Remove: `GamePlay.gpDeleteUserLabel(ul);` or overloads.
+- In **OnUserCreateUserLabel(ul)** / **OnUserDeleteUserLabel(ul)** you can read or modify label data as needed.
--- a/mission-script-api/world/triggers-spawns-targets.md
+++ b/mission-script-api/world/triggers-spawns-targets.md
@ -0,0 +1,162 @@
+# Triggers, Spawns, Airports, Targets, and Regiments
+
+**AiTrigger** and **AiAction** represent mission triggers and actions (get via **GamePlay.gpGetTrigger**, **gpGetAction**). **AiBirthPlace** is a spawn point; **AiAirport** is an airfield or carrier. **AiTarget** represents a mission target; **AiTargetType** and **AiTargetGoal** are constants. **Regiment** provides regiment metadata (army, name, country, etc.).
+
+---
+
+## AiTrigger
+
+**Kind:** interface  
+Mission trigger. Get with **GamePlay.gpGetTrigger(string name)**. When a trigger fires, **OnTrigger** is called; you can also get the associated **AiAction** and call **Do()**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Name` | string | Trigger name. |
+| `Enable` | bool | Get/set enabled state. |
+| `Active` | bool | True when trigger is active. |
+| `Multiple` | bool | True if trigger can fire multiple times. |
+
+---
+
+## AiAction
+
+**Kind:** interface  
+Action linked to a trigger or callable by name. Get with **GamePlay.gpGetAction(string name)**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Name` | string | Action name. |
+| `void Do()` | — | Execute the action. |
+| `CounterOperations` | int | Counter of operations. |
+
+---
+
+## AiBirthPlace
+
+**Kind:** interface  
+Spawn point (airfield, carrier, etc.). Get array from **GamePlay.gpBirthPlaces()**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `Tag` | object | Get/set; custom data. |
+| `bool IsValid()` | bool | True if spawn is valid. |
+| `string Name()` | string | Spawn name. |
+| `int Army()` | int | Army. |
+| `string Country()` | string | Country. |
+| `string Hierarchy()` | string | Hierarchy. |
+| `Regiment Regiment()` | Regiment | Regiment. |
+| `Point3d Pos()` | Point3d | Position. |
+| `int MaxPlanes()` | int | Max planes. |
+| `bool IsParachute()` | bool | Parachute spawn. |
+| `bool IsSetOnPark()` | bool | Set on park. |
+| `bool IsScramble()` | bool | Scramble spawn. |
+| `string[] GetAircraftTypes()` | string[] | Available aircraft types. |
+| `BitArray GetWeaponsMask(string aircraft)` | BitArray | Weapons mask for aircraft. |
+| `string CheckWeapons(string aircraft, string weapons)` | string | Validate weapons for aircraft. |
+| `void destroy()` | — | Destroy the birth place. |
+
+---
+
+## AiAirport
+
+**Kind:** interface (extends AiActor)  
+Airfield or carrier. Get array from **GamePlay.gpAirports()**.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `int Type()` | int | AiAirportType flags (GROUND, MARITIME, CARRIER). |
+| `double FieldR()` | double | Field radius. |
+| `double CoverageR()` | double | Coverage radius. |
+| `int StripCount()` | int | Number of strips. |
+| `int StripState(int indxStrip)` | int | AiAirportStripState for strip. |
+| `double StripWidth(int indxStrip)` | double | Strip width. |
+| `double StripLength(int indxStrip)` | double | Strip length. |
+| `double StripDirection(int indxStrip)` | double | Strip direction. |
+| `int ParkCountAll()` | int | Total park count. |
+| `int ParkCountFree()` | int | Free park count. |
+| `AiActor[] QueueTakeoff()` | AiActor[] | Takeoff queue. |
+| `AiActor[] QueueLanding()` | AiActor[] | Landing queue. |
+
+---
+
+## AiAirportType
+
+**Kind:** static class  
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `GROUND` | 0x01 | Ground airfield. |
+| `MARITIME` | 0x02 | Maritime. |
+| `CARRIER` | 0x04 | Carrier. |
+
+---
+
+## AiAirportStripState
+
+**Kind:** static class  
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `EMPTY` | 0 | Empty. |
+| `TAKEOFF` | 1 | Takeoff. |
+| `LANDING` | 2 | Landing. |
+| `BLOCKED` | 3 | Blocked. |
+| `DAMAGED` | 4 | Damaged. |
+
+---
+
+## AiTarget
+
+**Kind:** interface (extends AiActor)  
+Mission target (primary/secondary/secret, destroy/escort/etc.).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `int Type()` | int | AiTargetType (PRIMARY, SECONDARY, SECRET). |
+| `int Goal()` | int | AiTargetGoal (DESTROY, ESCORT, etc.). |
+| `int AppliesArmy()` | int | Army the target applies to. |
+| `AiActor TargetActor()` | AiActor | Target actor. |
+| `void Destroy()` | — | Destroy the target. |
+
+---
+
+## AiTargetType
+
+**Kind:** static class  
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `PRIMARY` | 0 | Primary target. |
+| `SECONDARY` | 1 | Secondary target. |
+| `SECRET` | 2 | Secret target. |
+
+---
+
+## AiTargetGoal
+
+**Kind:** static class  
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `DESTROY` | 0 | Destroy (e.g. aircraft). |
+| `DESTROY_COLUMN` | 1 | Destroy column (e.g. tanks). |
+| `DESTROY_GROUND` | 2 | Destroy ground. |
+| `DESTROY_BRIDGE` | 3 | Destroy bridge. |
+| `INSPECT` | 4 | Inspect. |
+| `ESCORT` | 5 | Escort (e.g. aircraft). |
+| `DEFENCE_COLUMN` | 6 | Defence column. |
+| `DEFENCE_GROUND` | 7 | Defence ground. |
+| `DEFENCE_BRIDGE` | 8 | Defence bridge. |
+
+---
+
+## Regiment
+
+**Kind:** interface  
+Regiment info (from **AiBirthPlace.Regiment()** or **AiAircraft.Regiment()**).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `int army()` | int | Army. |
+| `string name()` | string | Regiment name. |
+| `string fileNameEmblem()` | string | Emblem file name. |
+| `string country()` | string | Country. |
+| `string speech()` | string | Speech. |
+| `string id()` | string | Id. |
+| `int gruppeNumber()` | int | Gruppe number. |
--- a/mission-script-api/world/world.md
+++ b/mission-script-api/world/world.md
@ -0,0 +1,25 @@
+# World API (maddox.game.world)
+
+Types in **maddox.game.world** represent actors (air, ground), triggers, spawn points, airports, targets, time, and user labels. Mission scripts get these from **IGamePlay** (e.g. `gpActorByName`, `gpBirthPlaces`, `gpGetTrigger`) or receive them in **AMission** event arguments.
+
+---
+
+## Documentation index
+
+| Document | Description |
+|----------|-------------|
+| [Actor Hierarchy](mission-script-api/world/actor-hierarchy) | **AiActor**, **AiPerson**, **AiCart**, **AiGroup**, **AiBridge**, **AiWayPoint**; damage types (**AiDamageInitiator**, **AiDamageTool**, **DamagerScore**, **AiLimbDamage**); **CrewFunction** |
+| [Air](mission-script-api/world/air) | **AiAircraft**, **AiAirGroup**, **AiAirWayPoint**, **AiAirEnemyElement**; enums **IDState**, **AircraftType**, **DangerType**, **AiAirWayPointType**, **AiAirWayPointGAttackType**, **AiAirWayPointGAttackPasses**, **AiAirGroupTask**; **EnemyAirInterf** |
+| [Ground](mission-script-api/world/ground) | **AiGroundActor**, **AiGroundGroup**, **AiGroundWayPoint**, **AiAIChief**; **GroundStationary**, **GroundBuilding**, **GroundBombExplosion**; **AiGroundGroupType**, **AiGroundActorType**; **AiAIChiefType** |
+| [Triggers Spawns And Targets](mission-script-api/world/triggers-spawns-targets) | **AiTrigger**, **AiAction**; **AiBirthPlace**; **AiAirport**, **AiAirportType**, **AiAirportStripState**; **AiTarget**, **AiTargetType**, **AiTargetGoal**; **Regiment** |
+| [Time And User Labels](mission-script-api/world/time-and-user-labels) | **ITime** (cross-link), **GPUserLabel**, **GPUserIconType** |
+
+---
+
+## When to use which
+
+- **Actors** — Resolve by name with `GamePlay.gpActorByName()`; check `gpActorIsValid()`. Use **AiActor** for position, army, group; **AiCart** for vehicles/aircraft (places, crew, destroy); **AiAircraft** for fuel, rearm, damage; **AiGroundActor** for ground units.
+- **Triggers / actions** — `GamePlay.gpGetTrigger(name)`, `gpGetAction(name)`. In **OnTrigger**, get the action and call `Do()` to run it.
+- **Spawns / airports** — `GamePlay.gpBirthPlaces()`, `gpAirports()` for spawn and airfield data.
+- **User labels** — Create with `GamePlay.gpMakeUserLabel()`; draw/delete with `gpDrawUserLabel` / `gpDeleteUserLabel`. Use **GPUserLabel** and **GPUserIconType** for properties and icon type.
+- **Time** — Use **ITime** from `Mission.Time` or `GamePlay.gpTime()` (see also [Time And Difficulty](mission-script-api/time-and-difficulty)).