Add Events and Section File

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.