Module `Base`

This module contains the BASE class.

1) #BASE class

The #BASE class is the super class for all the classes defined within MOOSE.

It handles:

The construction and inheritance of child classes.
The tracing of objects during mission execution within the DCS.log file, under the "Saved Games\DCS\Logs" folder.

Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes.

1.1) BASE constructor

Any class derived from BASE, must use the Base#BASE.New method how this is done.

1.2) BASE Trace functionality

The BASE class contains trace methods to trace progress within a mission execution of a certain object. Note that these trace methods are inherited by each MOOSE class interiting BASE. As such, each object created from derived class from BASE can use the tracing functions to trace its execution.

1.2.1) Tracing functions

There are basically 3 types of tracing methods available within BASE:

BASE.F: Trace the beginning of a function and its given parameters. An F is indicated at column 44 in the DCS.log file.
BASE.T: Trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.
BASE.E: Trace an exception within a function giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file. An exception will always be traced.

1.2.2) Tracing levels

There are 3 tracing levels within MOOSE.
These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.

As such, the F and T methods have additional variants to trace level 2 and 3 respectively:

BASE.F2: Trace the beginning of a function and its given parameters with tracing level 2.
BASE.F3: Trace the beginning of a function and its given parameters with tracing level 3.
BASE.T2: Trace further logic within a function giving optional variables or parameters with tracing level 2.
BASE.T3: Trace further logic within a function giving optional variables or parameters with tracing level 3.

1.2.3) Trace activation.

Tracing can be activated in several ways:

Switch tracing on or off through the BASE.TraceOnOff() method.
Activate all tracing through the BASE.TraceAll() method.
Activate only the tracing of a certain class (name) through the BASE.TraceClass() method.
Activate only the tracing of a certain method of a certain class through the BASE.TraceClassMethod() method.
Activate only the tracing of a certain level through the BASE.TraceLevel() method.
1.2.4) Check if tracing is on.

The method BASE.IsTrace() will validate if tracing is activated or not.

1.3 DCS simulator Event Handling

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.3.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.HandleEvent(): Subscribe to a DCS Event.
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

See the Event module for more information about event handling.

1.4) Class identification methods

BASE provides methods to get more information of each object:

BASE.GetClassID(): Gets the ID (number) of the object. Each object created is assigned a number, that is incremented by one.
BASE.GetClassName(): Gets the name of the object, which is the name of the class the object was instantiated from.
BASE.GetClassNameAndID(): Gets the name and ID of the object.

1.5) All objects derived from BASE can have "States"

A mechanism is in place in MOOSE, that allows to let the objects administer states. States are essentially properties of objects, which are identified by a Key and a Value. The method BASE.SetState() can be used to set a Value with a reference Key to the object. To read or retrieve a state Value based on a Key, use the BASE.GetState method. These two methods provide a very handy way to keep state at long lasting processes. Values can be stored within the objects, and later retrieved or changed when needed. There is one other important thing to note, the BASE.SetState() and BASE.GetState methods receive as the first parameter the object for which the state needs to be set. Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same object name to the method.

1.10) BASE Inheritance (tree) support

The following methods are available to support inheritance:

BASE.Inherit: Inherits from a class.
BASE.GetParent: Returns the parent object from the object it is handling, or nil if there is no parent object.

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:

AUTHORS and CONTRIBUTIONS

Contributions:

None.

Authors:

FlightControl: Design & Programming

Global(s)

BASE
FORMATION

Type `BASE`

BASE.ClassID	The ID number of the class.
BASE.ClassName	The name of the class.
BASE.ClassNameAndID	The name of the class concatenated with the ID number of the class.
BASE:ClearState(Object, StateName)
BASE:CreateEventBirth(EventTime, Initiator, IniUnitName, place, subplace)	Creation of a Birth Event.
BASE:CreateEventCrash(EventTime, Initiator)	Creation of a Crash Event.
BASE:E(Arguments)	Log an exception which will be traced always.
BASE:EventDispatcher()	Returns the event dispatcher
BASE:EventRemoveAll()	Remove all subscribed events
BASE.Events
BASE:F(Arguments)	Trace a function call.
BASE:F2(Arguments)	Trace a function call level 2.
BASE:F3(Arguments)	Trace a function call level 3.
BASE:GetClassID()	Get the ClassID of the class instance.
BASE:GetClassName()	Get the ClassName of the class instance.
BASE:GetClassNameAndID()	Get the ClassName + ClassID of the class instance.
BASE:GetEventPriority()	Get the Class Event processing Priority.
BASE:GetParent(Child)	This is the worker method to retrieve the Parent class.
BASE:GetState(Object, Key, Value)	Get a Value given a Key from the Object.
BASE:HandleEvent(Event, EventFunction)	Subscribe to a DCS Event.
BASE:Inherit(Child, Parent)	This is the worker method to inherit from a parent class.
BASE:IsTrace()	Enquires if tracing is on (for the class).
BASE:New()
BASE:OnEvent(EventData)	Occurs when an object is completely destroyed.
BASE:OnEventBaseCaptured(EventData)	Occurs when a ground unit captures either an airbase or a farp.
BASE:OnEventBirth(EventData)	Occurs when any object is spawned into the mission.
BASE:OnEventCrash(EventData)	Occurs when any aircraft crashes into the ground and is completely destroyed.
BASE:OnEventEjection(EventData)	Occurs when a pilot ejects from an aircraft initiator : The unit that has ejected
BASE:OnEventEngineShutdown(EventData)	Occurs when any aircraft shuts down its engines.
BASE:OnEventEngineStartup(EventData)	Occurs when any aircraft starts its engines.
BASE:OnEventHit(EventData)	Occurs whenever an object is hit by a weapon.
BASE:OnEventHumanFailure(EventData)	Occurs when any system fails on a human controlled aircraft.
BASE:OnEventLand(EventData)	Occurs when an aircraft lands at an airbase, farp or ship initiator : The unit that has landed place: Object that the unit landed on.
BASE:OnEventMissionEnd(EventData)	Occurs when a mission ends
BASE:OnEventMissionStart(EventData)	Occurs when a mission starts
BASE:OnEventPilotDead(EventData)	Occurs when the pilot of an aircraft is killed.
BASE:OnEventPlayerEnterUnit(EventData)	Occurs when any player assumes direct control of a unit.
BASE:OnEventPlayerLeaveUnit(EventData)	Occurs when any player relieves control of a unit to the AI.
BASE:OnEventRefueling(EventData)	Occurs when an aircraft connects with a tanker and begins taking on fuel.
BASE:OnEventRefuelingStop(EventData)	Occurs when an aircraft is finished taking fuel.
BASE:OnEventShootingEnd(EventData)	Occurs when any unit stops firing its weapon.
BASE:OnEventShootingStart(EventData)	Occurs when any unit begins firing a weapon that has a high rate of fire.
BASE:OnEventShot(EventData)	Occurs whenever any unit in a mission fires a weapon.
BASE:OnEventTakeoff(EventData)	Occurs when an aircraft takes off from an airbase, farp, or ship.
BASE:SetEventPriority(EventPriority)	Set the Class Event processing Priority.
BASE:SetState(Object, Key, Value)	Set a state or property of the Object given a Key and a Value.
BASE.States
BASE:T(Arguments)	Trace a function logic level 1.
BASE:T2(Arguments)	Trace a function logic level 2.
BASE:T3(Arguments)	Trace a function logic level 3.
BASE:TraceAll(TraceAll)	Trace all methods in MOOSE
BASE:TraceClass(Class)	Set tracing for a class
BASE:TraceClassMethod(Class, Method)	Set tracing for a specific method of class
BASE:TraceLevel(Level)	Set trace level
BASE:TraceOnOff(TraceOnOff)	Set trace on or off Note that when trace is off, no debug statement is performed, increasing performance! When Moose is loaded statically, (as one file), tracing is switched off by default.
BASE:UnHandleEvent(Event)	UnSubscribe to a DCS event.
BASE:_Destructor()
BASE:_F(Arguments, DebugInfoCurrentParam, DebugInfoFromParam)	Trace a function call.
BASE._Private
BASE:_SetDestructor()
BASE:_T(Arguments, DebugInfoCurrentParam, DebugInfoFromParam)	Trace a function logic.
BASE:onEvent(event)

Type `FORMATION`

FORMATION.Cone

A cone formation.

Global(s)

#BASE BASE

#FORMATION FORMATION

Type `Base`

Type `BASE`

The BASE Class

Field(s)

BASE.ClassID: The ID number of the class.

BASE.ClassName: The name of the class.

BASE.ClassNameAndID: The name of the class concatenated with the ID number of the class.

BASE:ClearState(Object, StateName)

Parameters

Object :
StateName :

BASE:CreateEventBirth(EventTime, Initiator, IniUnitName, place, subplace)

Creation of a Birth Event.

Parameters

Dcs.DCSTypes#Time EventTime : The time stamp of the event.
Dcs.DCSWrapper.Object#Object Initiator : The initiating object of the event.
#string IniUnitName : The initiating unit name.
place :
subplace :

BASE:CreateEventCrash(EventTime, Initiator)

Creation of a Crash Event.

Parameters

Dcs.DCSTypes#Time EventTime : The time stamp of the event.
Dcs.DCSWrapper.Object#Object Initiator : The initiating object of the event.

BASE:E(Arguments)

Log an exception which will be traced always.

Can be anywhere within the function logic.

Parameter

Arguments : A #table or any field.

BASE:EventDispatcher()

Returns the event dispatcher

Return value

Core.Event#EVENT:

BASE:EventRemoveAll()

Remove all subscribed events

Return value

#BASE:

BASE.Events

BASE:F(Arguments)

Trace a function call.

Must be at the beginning of the function logic.

Parameter

Arguments : A #table or any field.

BASE:F2(Arguments)

Trace a function call level 2.

Must be at the beginning of the function logic.

Parameter

Arguments : A #table or any field.

BASE:F3(Arguments)

Trace a function call level 3.

Must be at the beginning of the function logic.

Parameter

Arguments : A #table or any field.

BASE:GetClassID()

Get the ClassID of the class instance.

Return value

#string: The ClassID of the class instance.

BASE:GetClassName()

Get the ClassName of the class instance.

Return value

#string: The ClassName of the class instance.

BASE:GetClassNameAndID()

Get the ClassName + ClassID of the class instance.

The ClassName + ClassID is formatted as '%s#%09d'.

Return value

#string: The ClassName + ClassID of the class instance.

BASE:GetEventPriority()

Get the Class Event processing Priority.

The Event processing Priority is a number from 1 to 10, reflecting the order of the classes subscribed to the Event to be processed.

Return value

#number: The Event processing Priority.

BASE:GetParent(Child)

This is the worker method to retrieve the Parent class.

Parameter

#BASE Child : is the Child class from which the Parent class needs to be retrieved.

Return value

#BASE:

BASE:GetState(Object, Key, Value)

Get a Value given a Key from the Object.

Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.

Parameters

Object : The object that holds the Value set by the Key.
Key : The key that is used to retrieve the value. Note that the key can be a #string, but it can also be any other type!
Value : The value to is stored in the Object.

Return value

The Value retrieved.

BASE:HandleEvent(Event, EventFunction)

Subscribe to a DCS Event.

Parameters

Core.Event#EVENTS Event :
#function EventFunction : (optional) The function to be called when the event occurs for the unit.

Return value

#BASE:

BASE:Inherit(Child, Parent)

This is the worker method to inherit from a parent class.

Parameters

Child : is the Child class that inherits.
#BASE Parent : is the Parent class that the Child inherits from.

Return value

#BASE: Child

BASE:IsTrace()

Enquires if tracing is on (for the class).

Return value

#boolean:

BASE:New(): @todo need to investigate if the deepCopy is really needed... Don't think so.

BASE:OnEvent(EventData)

Occurs when an object is completely destroyed.

initiator : The unit that is was destroyed.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventBaseCaptured(EventData)

Occurs when a ground unit captures either an airbase or a farp.

initiator : The unit that captured the base place: The airbase that was captured, can be a FARP or Airbase. When calling place:getCoalition() the faction will already be the new owning faction.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventBirth(EventData)

Occurs when any object is spawned into the mission.

initiator : The unit that was spawned

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventCrash(EventData)

Occurs when any aircraft crashes into the ground and is completely destroyed.

initiator : The unit that has crashed

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventEjection(EventData)

Occurs when a pilot ejects from an aircraft initiator : The unit that has ejected

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventEngineShutdown(EventData)

Occurs when any aircraft shuts down its engines.

initiator : The unit that is stopping its engines.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventEngineStartup(EventData)

Occurs when any aircraft starts its engines.

initiator : The unit that is starting its engines.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventHit(EventData)

Occurs whenever an object is hit by a weapon.

initiator : The unit object the fired the weapon weapon: Weapon object that hit the target target: The Object that was hit.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventHumanFailure(EventData)

Occurs when any system fails on a human controlled aircraft.

initiator : The unit that had the failure

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventLand(EventData)

Occurs when an aircraft lands at an airbase, farp or ship initiator : The unit that has landed place: Object that the unit landed on.

Can be an Airbase Object, FARP, or Ships

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventMissionEnd(EventData)

Occurs when a mission ends

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventMissionStart(EventData)

Occurs when a mission starts

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventPilotDead(EventData)

Occurs when the pilot of an aircraft is killed.

Can occur either if the player is alive and crashes or if a weapon kills the pilot without completely destroying the plane. initiator : The unit that the pilot has died in.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventPlayerEnterUnit(EventData)

Occurs when any player assumes direct control of a unit.

initiator : The unit that is being taken control of.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventPlayerLeaveUnit(EventData)

Occurs when any player relieves control of a unit to the AI.

initiator : The unit that the player left.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventRefueling(EventData)

Occurs when an aircraft connects with a tanker and begins taking on fuel.

initiator : The unit that is receiving fuel.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventRefuelingStop(EventData)

Occurs when an aircraft is finished taking fuel.

initiator : The unit that was receiving fuel.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventShootingEnd(EventData)

Occurs when any unit stops firing its weapon.

Event will always correspond with a shooting start event. initiator : The unit that was doing the shooing.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventShootingStart(EventData)

Occurs when any unit begins firing a weapon that has a high rate of fire.

Most common with aircraft cannons (GAU-8), autocannons, and machine guns. initiator : The unit that is doing the shooing. target: The unit that is being targeted.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventShot(EventData)

Occurs whenever any unit in a mission fires a weapon.

But not any machine gun or autocannon based weapon, those are handled by EVENT.ShootingStart.

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:OnEventTakeoff(EventData)

Occurs when an aircraft takes off from an airbase, farp, or ship.

initiator : The unit that tookoff place: Object from where the AI took-off from. Can be an Airbase Object, FARP, or Ships

Parameter

Core.Event#EVENTDATA EventData : The EventData structure.

BASE:SetEventPriority(EventPriority)

Set the Class Event processing Priority.

The Event processing Priority is a number from 1 to 10, reflecting the order of the classes subscribed to the Event to be processed.

Parameter

#number EventPriority : The Event processing Priority.

Return value

self

BASE:SetState(Object, Key, Value)

Set a state or property of the Object given a Key and a Value.

Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.

Parameters

Object : The object that will hold the Value set by the Key.
Key : The key that is used as a reference of the value. Note that the key can be a #string, but it can also be any other type!
Value : The value to is stored in the object.

Return values

The Value set.
#nil: The Key was not found and thus the Value could not be retrieved.

BASE.States

BASE:T(Arguments)

Trace a function logic level 1.

Can be anywhere within the function logic.

Parameter

Arguments : A #table or any field.

BASE:T2(Arguments)

Trace a function logic level 2.

Can be anywhere within the function logic.

Parameter

Arguments : A #table or any field.

BASE:T3(Arguments)

Trace a function logic level 3.

Can be anywhere within the function logic.

Parameter

Arguments : A #table or any field.

BASE:TraceAll(TraceAll)

Trace all methods in MOOSE

Parameter

#boolean TraceAll : true = trace all methods in MOOSE.

BASE:TraceClass(Class)

Set tracing for a class

Parameter

#string Class :

BASE:TraceClassMethod(Class, Method)

Set tracing for a specific method of class

Parameters

#string Class :
#string Method :

BASE:TraceLevel(Level)

Set trace level

Parameter

#number Level :

BASE:TraceOnOff(TraceOnOff)

Set trace on or off Note that when trace is off, no debug statement is performed, increasing performance! When Moose is loaded statically, (as one file), tracing is switched off by default.

So tracing must be switched on manually in your mission if you are using Moose statically. When moose is loading dynamically (for moose class development), tracing is switched on by default.

Parameter

#boolean TraceOnOff : Switch the tracing on or off.

Usage:

-- Switch the tracing On
BASE:TraceOnOff( true )

-- Switch the tracing Off
BASE:TraceOnOff( false )

BASE:UnHandleEvent(Event)

UnSubscribe to a DCS event.

Parameter

Core.Event#EVENTS Event :

Return value

#BASE:

BASE:_Destructor()

BASE:_F(Arguments, DebugInfoCurrentParam, DebugInfoFromParam)

Trace a function call.

This function is private.

Parameters

Arguments : A #table or any field.
DebugInfoCurrentParam :
DebugInfoFromParam :

BASE._Private

BASE:_SetDestructor()

BASE:_T(Arguments, DebugInfoCurrentParam, DebugInfoFromParam)

Trace a function logic.

Parameters

Arguments : A #table or any field.
DebugInfoCurrentParam :
DebugInfoFromParam :

BASE:onEvent(event)

TODO: Complete Dcs.DCSTypes#Event structure.
- The main event handling function... This function captures all events generated for the class. @param #BASE self @param Dcs.DCSTypes#Event event

Parameter

event :

Type `FORMATION`

The Formation Class

Field(s)

FORMATION.Cone: A cone formation.

Modules

Module Base

1) #BASE class

1.1) BASE constructor

1.2) BASE Trace functionality

1.2.1) Tracing functions

1.2.2) Tracing levels

1.2.3) Trace activation.

1.2.4) Check if tracing is on.

1.3 DCS simulator Event Handling

1.3.1 Subscribe / Unsubscribe to DCS Events

1.3.2 Event Handling of DCS Events

1.4) Class identification methods

1.5) All objects derived from BASE can have "States"

1.10) BASE Inheritance (tree) support

API CHANGE HISTORY

AUTHORS and CONTRIBUTIONS

Contributions:

Authors:

Global(s)

Type BASE

Type FORMATION

Global(s)

Type Base

Type BASE

Field(s)

Parameters

Parameters

Parameters

Parameter

Return value

Return value

Parameter

Parameter

Parameter

Return value

Return value

Return value

Return value

Parameter

Return value

Parameters

Return value

Parameters

Return value

Parameters

Return value

Return value

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Return value

Parameters

Return values

Parameter

Parameter

Parameter

Parameter

Parameter

Parameters

Parameter

Module `Base`

Type `BASE`

Type `FORMATION`

Type `Base`

Type `BASE`

Type `FORMATION`