mirror of
https://github.com/FlightControl-Master/MOOSE.git
synced 2025-10-29 16:58:06 +00:00
Event Documentation
This commit is contained in:
FlightControl
@@ -1,27 +1,155 @@
|
||||
--- This module contains the **EVENT** class, which models the dispatching of DCS Events to subscribed MOOSE classes,
|
||||
--- This core module models the dispatching of DCS Events to subscribed MOOSE classes,
|
||||
-- following a given priority.
|
||||
--
|
||||
-- ##
|
||||
--
|
||||
-- 
|
||||
-- 
|
||||
--
|
||||
-- ===
|
||||
--
|
||||
--- This module contains the EVENT class.
|
||||
-- # 1) Event Handling Overview
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- Within a running mission, various DCS events occur. Units are dynamically created, crash, die, shoot stuff, get hit etc.
|
||||
-- This module provides a mechanism to dispatch those events occuring within your running mission, to the different objects orchestrating your mission.
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- Objects can subscribe to different events. The Event dispatcher will publish the received DCS events to the subscribed MOOSE objects, in a specified order.
|
||||
-- In this way, the subscribed MOOSE objects are kept in sync with your evolving running mission.
|
||||
--
|
||||
-- ## 1.1) Event Dispatching
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- The _EVENTDISPATCHER object is automatically created within MOOSE,
|
||||
-- and handles the dispatching of DCS Events occurring
|
||||
-- in the simulator to the subscribed objects
|
||||
-- in the correct processing order.
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- There are 5 levels of kind of objects that the _EVENTDISPATCHER services:
|
||||
--
|
||||
-- * _DATABASE object: The core of the MOOSE objects. Any object that is created, deleted or updated, is done in this database.
|
||||
-- * SET_ derived classes: Subsets of the _DATABASE object. These subsets are updated by the _EVENTDISPATCHER as the second priority.
|
||||
-- * UNIT objects: UNIT objects can subscribe to DCS events. Each DCS event will be directly published to teh subscribed UNIT object.
|
||||
-- * GROUP objects: GROUP objects can subscribe to DCS events. Each DCS event will be directly published to the subscribed GROUP object.
|
||||
-- * Any other object: Various other objects can subscribe to DCS events. Each DCS event triggered will be published to each subscribed object.
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- For most DCS events, the above order of updating will be followed.1
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- But for some DCS events, the publishing order is reversed. This is due to the fact that objects need to be **erased** instead of added.
|
||||
--
|
||||
-- ## 1.2) Event Handling
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- The actual event subscribing and handling is not facilitated through the _EVENTDISPATCHER, but it is done through the @{BASE} class, @{UNIT} class and @{GROUP} class.
|
||||
-- The _EVENTDISPATCHER is a component that is quietly working in the background of MOOSE.
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator,
|
||||
-- and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.
|
||||
--
|
||||
-- ### 1.2.1 Subscribe / Unsubscribe to DCS Events
|
||||
--
|
||||
-- At first, the mission designer will need to **Subscribe** to a specific DCS event for the class.
|
||||
-- So, when the DCS event occurs, the class will be notified of that event.
|
||||
-- There are two functions which you use to subscribe to or unsubscribe from an event.
|
||||
--
|
||||
-- * @{Base#BASE.HandleEvent}(): Subscribe to a DCS Event.
|
||||
-- * @{Base#BASE.UnHandleEvent}(): Unsubscribe from a DCS Event.
|
||||
--
|
||||
-- ### 1.3.2 Event Handling of DCS Events
|
||||
--
|
||||
-- Once the class is subscribed to the event, an **Event Handling** method on the object or class needs to be written that will be called
|
||||
-- when the DCS event occurs. The Event Handling method receives an @{Event#EVENTDATA} structure, which contains a lot of information
|
||||
-- about the event that occurred.
|
||||
--
|
||||
-- Find below an example of the prototype how to write an event handling function for two units:
|
||||
--
|
||||
-- local Tank1 = UNIT:FindByName( "Tank A" )
|
||||
-- local Tank2 = UNIT:FindByName( "Tank B" )
|
||||
--
|
||||
-- -- Here we subscribe to the Dead events. So, if one of these tanks dies, the Tank1 or Tank2 objects will be notified.
|
||||
-- Tank1:HandleEvent( EVENTS.Dead )
|
||||
-- Tank2:HandleEvent( EVENTS.Dead )
|
||||
--
|
||||
-- --- This function is an Event Handling function that will be called when Tank1 is Dead.
|
||||
-- -- @param Wrapper.Unit#UNIT self
|
||||
-- -- @param Core.Event#EVENTDATA EventData
|
||||
-- function Tank1:OnEventDead( EventData )
|
||||
--
|
||||
-- self:SmokeGreen()
|
||||
-- end
|
||||
--
|
||||
-- --- This function is an Event Handling function that will be called when Tank2 is Dead.
|
||||
-- -- @param Wrapper.Unit#UNIT self
|
||||
-- -- @param Core.Event#EVENTDATA EventData
|
||||
-- function Tank2:OnEventDead( EventData )
|
||||
--
|
||||
-- self:SmokeBlue()
|
||||
-- end
|
||||
--
|
||||
-- ### 1.3.3 Event Handling methods that are automatically called upon subscribed DCS events
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- 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.
|
||||
--
|
||||
-- # 2) EVENTS type
|
||||
--
|
||||
-- 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:
|
||||
--
|
||||
-- 
|
||||
--
|
||||
-- ====
|
||||
--
|
||||
-- # **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.
|
||||
--
|
||||
-- ===
|
||||
--
|
||||
-- Takes care of EVENT dispatching between DCS events and event handling functions defined in MOOSE classes.
|
||||
-- # **AUTHORS and CONTRIBUTIONS**
|
||||
--
|
||||
-- ===
|
||||
-- ### Contributions:
|
||||
--
|
||||
-- The above menus classes **are derived** from 2 main **abstract** classes defined within the MOOSE framework (so don't use these):
|
||||
--
|
||||
-- ===
|
||||
--
|
||||
-- ### Contributions: -
|
||||
-- ### Authors: FlightControl : Design & Programming
|
||||
-- ### Authors:
|
||||
--
|
||||
-- * [**FlightControl**](https://forums.eagle.ru/member.php?u=89536): Design & Programming & documentation.
|
||||
--
|
||||
-- @module Event
|
||||
|
||||
--- The EVENT structure
|
||||
@@ -33,6 +161,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,
|
||||
@@ -59,6 +190,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] = {
|
||||
@@ -178,27 +331,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
|
||||
|
||||
Reference in New Issue
Block a user