Add 01-mission-and-battle
parent
ce05d61085
commit
f9a9790379
199
01-mission-and-battle.-.md
Normal file
199
01-mission-and-battle.-.md
Normal file
@ -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<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` < 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.");
|
||||
});
|
||||
}
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user