Event Documentation

Moose Mission Setup/Moose Mission Update/l10n/DEFAULT/Moose.lua

@@ -1,5 +1,5 @@
 env.info( '*** MOOSE STATIC INCLUDE START *** ' ) 
-env.info( 'Moose Generation Timestamp: 20170207_1733' ) 
+env.info( 'Moose Generation Timestamp: 20170207_2151' ) 
 local base = _G
 
 Include = {}
@@ -4121,20 +4121,56 @@ end
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia10.JPG)
 -- 
--- The following list outlines which EVENTS item in the structure corresponds to which Event Handling method:
+-- The following list outlines which EVENTS item in the structure corresponds to which Event Handling method.
+-- Always ensure that your event handling methods align with the events being subscribed to, or nothing will be executed.
 -- 
--- First Header | Second Header
--- ------------ | -------------
--- Content from cell 1 | Content from cell 2
--- Content in the first column | Content in the second column
+-- # 2) EVENTS type
 -- 
--- The above menus classes **are derived** from 2 main **abstract** classes defined within the MOOSE framework (so don't use these):
+-- The EVENTS structure contains names for all the different DCS events that objects can subscribe to using the 
+-- @{Base#BASE.HandleEvent}() method.
+-- 
+-- # 3) EVENTDATA type
+-- 
+-- The EVENTDATA contains all the fields that are populated with event information before 
+-- an Event Handler method is being called by the event dispatcher.
+-- The Event Handler received the EVENTDATA object as a parameter, and can be used to investigate further the different events.
+-- There are basically 4 main categories of information stored in the EVENTDATA structure:
+-- 
+--    * Initiator Unit data: Several fields documenting the initiator unit related to the event.
+--    * Target Unit data: Several fields documenting the target unit related to the event.
+--    * Weapon data: Certain events populate weapon information.
+--    * Place data: Certain events populate place information.
+-- 
+-- Find below an overview which events populate which information categories:
+-- 
+-- ![Objects](..\Presentations\EVENT\Dia14.JPG)
+-- 
+-- ====
+-- 
+-- # **API CHANGE HISTORY**
+-- 
+-- The underlying change log documents the API changes. Please read this carefully. The following notation is used:
+-- 
+--   * **Added** parts are expressed in bold type face.
+--   * _Removed_ parts are expressed in italic type face.
+-- 
+-- YYYY-MM-DD: CLASS:**NewFunction**( Params ) replaces CLASS:_OldFunction_( Params )
+-- YYYY-MM-DD: CLASS:**NewFunction( Params )** added
+-- 
+-- Hereby the change log:
+-- 
+--   * 2016-02-07: Did a complete revision of the Event Handing API and underlying mechanisms.
 -- 
 -- ===
 -- 
--- ### Contributions: -
--- ### Authors: FlightControl : Design & Programming
+-- # **AUTHORS and CONTRIBUTIONS**
 -- 
+-- ### Contributions: 
+-- 
+-- ### Authors: 
+-- 
+--   * [**FlightControl**](https://forums.eagle.ru/member.php?u=89536): Design & Programming & documentation.
+--
 -- @module Event
 
 --- The EVENT structure
@@ -4146,6 +4182,9 @@ EVENT = {
   ClassID = 0,
 }
 
+--- The different types of events supported by MOOSE.
+-- Use this structure to subscribe to events using the @{Base#BASE.HandleEvent}() method.
+-- @type EVENTS
 EVENTS = {
   Shot =              world.event.S_EVENT_SHOT,
   Hit =               world.event.S_EVENT_HIT,
@@ -4172,6 +4211,28 @@ EVENTS = {
   ShootingEnd =       world.event.S_EVENT_SHOOTING_END,
 }
 
+--- The Event structure
+-- @type EVENTDATA
+-- @field id
+-- @field initiator
+-- @field target
+-- @field weapon
+-- @field IniDCSUnit
+-- @field IniDCSUnitName
+-- @field Wrapper.Unit#UNIT           IniUnit
+-- @field #string             IniUnitName
+-- @field IniDCSGroup
+-- @field IniDCSGroupName
+-- @field TgtDCSUnit
+-- @field TgtDCSUnitName
+-- @field Wrapper.Unit#UNIT           TgtUnit
+-- @field #string             TgtUnitName
+-- @field TgtDCSGroup
+-- @field TgtDCSGroupName
+-- @field Weapon
+-- @field WeaponName
+-- @field WeaponTgtDCSUnit
+
 
 local _EVENTMETA = {
    [world.event.S_EVENT_SHOT] = {
@@ -4291,27 +4352,6 @@ local _EVENTMETA = {
    },
 }
 
---- The Event structure
--- @type EVENTDATA
--- @field id
--- @field initiator
--- @field target
--- @field weapon
--- @field IniDCSUnit
--- @field IniDCSUnitName
--- @field Wrapper.Unit#UNIT           IniUnit
--- @field #string             IniUnitName
--- @field IniDCSGroup
--- @field IniDCSGroupName
--- @field TgtDCSUnit
--- @field TgtDCSUnitName
--- @field Wrapper.Unit#UNIT           TgtUnit
--- @field #string             TgtUnitName
--- @field TgtDCSGroup
--- @field TgtDCSGroupName
--- @field Weapon
--- @field WeaponName
--- @field WeaponTgtDCSUnit
 
 --- The Events structure
 -- @type EVENT.Events

Moose Mission Setup/Moose.lua

@@ -1,5 +1,5 @@
 env.info( '*** MOOSE STATIC INCLUDE START *** ' ) 
-env.info( 'Moose Generation Timestamp: 20170207_1733' ) 
+env.info( 'Moose Generation Timestamp: 20170207_2151' ) 
 local base = _G
 
 Include = {}
@@ -4121,20 +4121,56 @@ end
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia10.JPG)
 -- 
--- The following list outlines which EVENTS item in the structure corresponds to which Event Handling method:
+-- The following list outlines which EVENTS item in the structure corresponds to which Event Handling method.
+-- Always ensure that your event handling methods align with the events being subscribed to, or nothing will be executed.
 -- 
--- First Header | Second Header
--- ------------ | -------------
--- Content from cell 1 | Content from cell 2
--- Content in the first column | Content in the second column
+-- # 2) EVENTS type
 -- 
--- The above menus classes **are derived** from 2 main **abstract** classes defined within the MOOSE framework (so don't use these):
+-- The EVENTS structure contains names for all the different DCS events that objects can subscribe to using the 
+-- @{Base#BASE.HandleEvent}() method.
+-- 
+-- # 3) EVENTDATA type
+-- 
+-- The EVENTDATA contains all the fields that are populated with event information before 
+-- an Event Handler method is being called by the event dispatcher.
+-- The Event Handler received the EVENTDATA object as a parameter, and can be used to investigate further the different events.
+-- There are basically 4 main categories of information stored in the EVENTDATA structure:
+-- 
+--    * Initiator Unit data: Several fields documenting the initiator unit related to the event.
+--    * Target Unit data: Several fields documenting the target unit related to the event.
+--    * Weapon data: Certain events populate weapon information.
+--    * Place data: Certain events populate place information.
+-- 
+-- Find below an overview which events populate which information categories:
+-- 
+-- ![Objects](..\Presentations\EVENT\Dia14.JPG)
+-- 
+-- ====
+-- 
+-- # **API CHANGE HISTORY**
+-- 
+-- The underlying change log documents the API changes. Please read this carefully. The following notation is used:
+-- 
+--   * **Added** parts are expressed in bold type face.
+--   * _Removed_ parts are expressed in italic type face.
+-- 
+-- YYYY-MM-DD: CLASS:**NewFunction**( Params ) replaces CLASS:_OldFunction_( Params )
+-- YYYY-MM-DD: CLASS:**NewFunction( Params )** added
+-- 
+-- Hereby the change log:
+-- 
+--   * 2016-02-07: Did a complete revision of the Event Handing API and underlying mechanisms.
 -- 
 -- ===
 -- 
--- ### Contributions: -
--- ### Authors: FlightControl : Design & Programming
+-- # **AUTHORS and CONTRIBUTIONS**
 -- 
+-- ### Contributions: 
+-- 
+-- ### Authors: 
+-- 
+--   * [**FlightControl**](https://forums.eagle.ru/member.php?u=89536): Design & Programming & documentation.
+--
 -- @module Event
 
 --- The EVENT structure
@@ -4146,6 +4182,9 @@ EVENT = {
   ClassID = 0,
 }
 
+--- The different types of events supported by MOOSE.
+-- Use this structure to subscribe to events using the @{Base#BASE.HandleEvent}() method.
+-- @type EVENTS
 EVENTS = {
   Shot =              world.event.S_EVENT_SHOT,
   Hit =               world.event.S_EVENT_HIT,
@@ -4172,6 +4211,28 @@ EVENTS = {
   ShootingEnd =       world.event.S_EVENT_SHOOTING_END,
 }
 
+--- The Event structure
+-- @type EVENTDATA
+-- @field id
+-- @field initiator
+-- @field target
+-- @field weapon
+-- @field IniDCSUnit
+-- @field IniDCSUnitName
+-- @field Wrapper.Unit#UNIT           IniUnit
+-- @field #string             IniUnitName
+-- @field IniDCSGroup
+-- @field IniDCSGroupName
+-- @field TgtDCSUnit
+-- @field TgtDCSUnitName
+-- @field Wrapper.Unit#UNIT           TgtUnit
+-- @field #string             TgtUnitName
+-- @field TgtDCSGroup
+-- @field TgtDCSGroupName
+-- @field Weapon
+-- @field WeaponName
+-- @field WeaponTgtDCSUnit
+
 
 local _EVENTMETA = {
    [world.event.S_EVENT_SHOT] = {
@@ -4291,27 +4352,6 @@ local _EVENTMETA = {
    },
 }
 
---- The Event structure
--- @type EVENTDATA
--- @field id
--- @field initiator
--- @field target
--- @field weapon
--- @field IniDCSUnit
--- @field IniDCSUnitName
--- @field Wrapper.Unit#UNIT           IniUnit
--- @field #string             IniUnitName
--- @field IniDCSGroup
--- @field IniDCSGroupName
--- @field TgtDCSUnit
--- @field TgtDCSUnitName
--- @field Wrapper.Unit#UNIT           TgtUnit
--- @field #string             TgtUnitName
--- @field TgtDCSGroup
--- @field TgtDCSGroupName
--- @field Weapon
--- @field WeaponName
--- @field WeaponTgtDCSUnit
 
 --- The Events structure
 -- @type EVENT.Events

Moose Test Missions/EVT - Event Handling/EVT-103 - OnEventLand Example/EVT-103 - OnEventLand Example.lua

@@ -0,0 +1,38 @@
+---
+-- Name: EVT-103 - OnEventLand Example
+-- Author: FlightControl
+-- Date Created: 7 February 2017
+--
+-- # Situation:
+--
+-- An AI plane is landing on an airfield.
+-- When the plane landed, a new plane is spawned.
+-- 
+-- # Test cases:
+-- 
+-- 1. Observe the plane landing.
+-- 2. When the AI plane lands, observe the new plane being spawned.
+-- 3. Check the contents of the fields of the S_EVENT_LAND entry in the dcs.log file.
+
+-- Create a variable PlaneAI that holds a reference to UNIT object (created by moose at the beginning of the mission) with the name "PlaneAI".
+local PlaneAI = UNIT:FindByName( "PlaneAI" )
+
+-- Create a SPAWN object to spawn a new plane once the hold one lands.
+local SpawnPlane = SPAWN:New( "SpawnPlaneAI" )
+
+-- Declare a new variable that will hold the new spawned SpawnPlaneAI
+local NewPlane
+
+
+-- Subscribe to the event Land. The Land event occurs when a plane lands at an airfield.
+PlaneAI:HandleEvent( EVENTS.Land )
+
+-- Because the PlaneAI object is subscribed to the Land event, the following method will be automatically
+-- called when the land event is happening FOR THE PlaneAI UNIT only!
+function PlaneAI:OnEventLand( EventData )
+
+  -- Okay, the PlaneAI has landed, now spawn the new plane ( a predator )
+  NewPlane = SpawnPlane:Spawn()
+end
+
+

Moose Test Missions/EVT - Event Handling/EVT-104 - OnEventCrash Example/EVT-104 - OnEventCrash Example.lua

@@ -0,0 +1,35 @@
+---
+-- Name: EVT-104 - OnEventCrash Example
+-- Author: FlightControl
+-- Date Created: 7 February 2017
+--
+-- # Situation:
+--
+-- A human plane is fyling in the air. Crash it into the ground.
+-- Once you are crashed into the ground, at the place where you crashed, a smoke should start burning ...
+-- 
+-- # Test cases:
+-- 
+-- 1. Fly the plane into the ground.
+-- 2. When your plane crashes, observe a smoke starting to burn right were you crashed.
+-- 3. Check the contents of the fields of the S_EVENT_CRASH entry in the dcs.log file.
+
+-- Create a variable PlaneHuman that holds a reference to UNIT object (created by moose at the beginning of the mission) with the name "PlaneHuman".
+local PlaneHuman = UNIT:FindByName( "PlaneHuman" )
+
+-- Subscribe to the event Crash. The Crash event occurs when a plane crashes into the ground (or into something else).
+PlaneHuman:HandleEvent( EVENTS.Crash )
+
+-- Because the PlaneHuman object is subscribed to the Crash event, the following method will be automatically
+-- called when the Crash event is happening FOR THE PlaneHuman UNIT only!
+
+--- @param self
+-- @param Core.Event#EVENTDATA EventData
+function PlaneHuman:OnEventCrash( EventData )
+
+  -- Okay, the PlaneHuman has crashed, now smoke at the x, z position.
+  self:E( "Smoking at the position" )
+  EventData.IniUnit:SmokeOrange()
+end
+
+