diff --git a/01-mission-and-battle.-.md b/01-mission-and-battle.-.md new file mode 100644 index 0000000..ecd5418 --- /dev/null +++ b/01-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 < 0, listens to all. Set e.g. in `OnBattleStarted`. | + +### Static / shared + +| Member | Type | Description | +|--------|------|-------------| +| `DataDictionary` | `Dictionary` | 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` < 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 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."); + }); +} +```