Banner Image

Module Functional.ZoneCaptureCoalition

Functional -- Models the process to zone guarding and capturing.


Features:

  • Models the possible state transitions between the Guarded, Attacked, Empty and Captured states.
  • A zone has an owning coalition, that means that at a specific point in time, a zone can be owned by the red or blue coalition.
  • Provide event handlers to tailor the actions when a zone changes coalition or state.

Missions:

CAZ - Capture Zones


Player Experience

States

The above models the possible state transitions between the Guarded, Attacked, Empty and Captured states.
A zone has an owning coalition, that means that at a specific point in time, a zone can be owned by the red or blue coalition.

The Zone can be in the state Guarded by the owning coalition, which is the coalition that initially occupies the zone with units of its coalition.
Once units of an other coalition are entering the Zone, the state will change to Attacked. As long as these units remain in the zone, the state keeps set to Attacked.
When all units are destroyed in the Zone, the state will change to Empty, which expresses that the Zone is empty, and can be captured.
When units of the other coalition are in the Zone, and no other units of the owning coalition is in the Zone, the Zone is captured, and its state will change to Captured.

The zone needs to be monitored regularly for the presence of units to interprete the correct state transition required.
This monitoring process MUST be started using the ZONE_CAPTURE_COALITION.Start() method.
Otherwise no monitoring will be active and the zone will stay in the current state forever.


YouTube Playlist


Author: FlightControl

Contributions: Millertime - Concept, funkyfranky


Global(s)

Global ZONE_CAPTURE_COALITION

Models the process to capture a Zone for a Coalition, which is guarded by another Coalition.

#ZONE_CAPTURE_COALITION ZONE_CAPTURE_COALITION

Models the process to capture a Zone for a Coalition, which is guarded by another Coalition.

This is a powerful concept that allows to create very dynamic missions based on the different state transitions of various zones.


In order to use ZONE_CAPTURE_COALITION, you need to:

  • Create a Zone object from one of the ZONE_ classes.
    Note that ZONE_POLYGON_ classes are not yet functional.
    The only functional ZONE_ classses are those derived from a ZONE_RADIUS.
  • Set the state of the zone. Most of the time, Guarded would be the initial state.
  • Start the zone capturing monitoring process.
    This will check the presence of friendly and/or enemy units within the zone and will transition the state of the zone when the tactical situation changed. The frequency of the monitoring must not be real-time, a 30 second interval to execute the checks is sufficient.

New

Important:

You must start the monitoring process within your code, or there won't be any state transition checks executed.
See further the start/stop monitoring process.

Important:

Ensure that the object containing the ZONE_CAPTURE_COALITION object is persistent. Otherwise the garbage collector of lua will remove the object and the monitoring process will stop. This will result in your object to be destroyed (removed) from internal memory and there won't be any zone state transitions anymore detected! So use the local keyword in lua with thought! Most of the time, you can declare your object gobally.

Example:

  -- Define a new ZONE object, which is based on the trigger zone `CaptureZone`, which is defined within the mission editor.
  CaptureZone = ZONE:New( "CaptureZone" )

  -- Here we create a new ZONE_CAPTURE_COALITION object, using the :New constructor.
  ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( CaptureZone, coalition.side.RED )

  -- Set the zone to Guarding state.
  ZoneCaptureCoalition:__Guard( 1 )

  -- Start the zone monitoring process in 30 seconds and check every 30 seconds.
  ZoneCaptureCoalition:Start( 30, 30 ) 

Constructor:

Use the ZONE_CAPTURE_COALITION.New() constructor to create a new ZONE_CAPTURE_COALITION object.

ZONE_CAPTURE_COALITION is a finite state machine (FSM).

States

ZONE_CAPTURE_COALITION States

  • Captured: The Zone has been captured by an other coalition.
  • Attacked: The Zone is currently intruded by an other coalition. There are units of the owning coalition and an other coalition in the Zone.
  • Guarded: The Zone is guarded by the owning coalition. There is no other unit of an other coalition in the Zone.
  • Empty: The Zone is empty. There is not valid unit in the Zone.

2.2 ZONE_CAPTURE_COALITION Events

  • Capture: The Zone has been captured by an other coalition.
  • Attack: The Zone is currently intruded by an other coalition. There are units of the owning coalition and an other coalition in the Zone.
  • Guard: The Zone is guarded by the owning coalition. There is no other unit of an other coalition in the Zone.
  • Empty: The Zone is empty. There is not valid unit in the Zone.

"Script It"

ZONE_CAPTURE_COALITION allows to take action on the various state transitions and add your custom code and logic.

Take action using state- and event handlers.

States

The most important to understand is how states and events can be tailored. Carefully study the diagram and the explanations.

State Handlers capture the moment:

  • On Leave from the old state. Return false to cancel the transition.
  • On Enter to the new state.

Event Handlers capture the moment:

  • On Before the event is triggered. Return false to cancel the transition.
  • On After the event is triggered.

States

Each handler can receive optionally 3 parameters:

  • From: A string containing the From State.
  • Event: A string containing the Event.
  • To: A string containing the To State.

The mission designer can use these values to alter the logic. For example:

--- @param Functional.ZoneCaptureCoalition#ZONE_CAPTURE_COALITION self
function ZoneCaptureCoalition:OnEnterGuarded( From, Event, To )
  if From ~= "Empty" then
    -- Display a message
  end
end

This code checks that when the Guarded state has been reached, that if the From state was Empty, then display a message.

Example Event Handler.

--- @param Functional.ZoneCaptureCoalition#ZONE_CAPTURE_COALITION self
function ZoneCaptureCoalition:OnEnterGuarded( From, Event, To )
  if From ~= To then
    local Coalition = self:GetCoalition()
    self:E( { Coalition = Coalition } )
    if Coalition == coalition.side.BLUE then
      ZoneCaptureCoalition:Smoke( SMOKECOLOR.Blue )
      US_CC:MessageTypeToCoalition( string.format( "%s is under protection of the USA", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
      RU_CC:MessageTypeToCoalition( string.format( "%s is under protection of the USA", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
    else
      ZoneCaptureCoalition:Smoke( SMOKECOLOR.Red )
      RU_CC:MessageTypeToCoalition( string.format( "%s is under protection of Russia", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
      US_CC:MessageTypeToCoalition( string.format( "%s is under protection of Russia", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
    end
  end
end

Stop and Start the zone monitoring process.

At regular intervals, the state of the zone needs to be monitored. The zone needs to be scanned for the presence of units within the zone boundaries. Depending on the owning coalition of the zone and the presence of units (of the owning and/or other coalition(s)), the zone will transition to another state.

However, ... this scanning process is rather CPU intensive. Imagine you have 10 of these capture zone objects setup within your mission. That would mean that your mission would check 10 capture zones simultaneously, each checking for the presence of units. It would be highly CPU inefficient, as some of these zones are not required to be monitored (yet).

Therefore, the mission designer is given 2 methods that allow to take control of the CPU utilization efficiency:

IMPORTANT

Each capture zone object must have the monitoring process started specifically. The monitoring process is NOT started by default!

Full Example

The following annotated code shows a real example of how ZONE_CAPTURE_COALITION can be applied.

The concept is simple.

The USA (US), blue coalition, needs to capture the Russian (RU), red coalition, zone, which is near groom lake.

A capture zone has been setup that guards the presence of the troops. Troops are guarded by red forces. Blue is required to destroy the red forces and capture the zones.

At first, we setup the Command Centers

 do

   RU_CC = COMMANDCENTER:New( GROUP:FindByName( "REDHQ" ), "Russia HQ" )
   US_CC = COMMANDCENTER:New( GROUP:FindByName( "BLUEHQ" ), "USA HQ" )

 end

Next, we define the mission, and add some scoring to it.

 do -- Missions

   US_Mission_EchoBay = MISSION:New( US_CC, "Echo Bay", "Primary",
     "Welcome trainee. The airport Groom Lake in Echo Bay needs to be captured.\n" ..
     "There are five random capture zones located at the airbase.\n" ..
     "Move to one of the capture zones, destroy the fuel tanks in the capture zone, " ..
     "and occupy each capture zone with a platoon.\n " .. 
     "Your orders are to hold position until all capture zones are taken.\n" ..
     "Use the map (F10) for a clear indication of the location of each capture zone.\n" ..
     "Note that heavy resistance can be expected at the airbase!\n" ..
     "Mission 'Echo Bay' is complete when all five capture zones are taken, and held for at least 5 minutes!"
     , coalition.side.RED )

   US_Mission_EchoBay:Start()

 end

Now the real work starts. We define a CaptureZone object, which is a ZONE object. Within the mission, a trigger zone is created with the name CaptureZone, with the defined radius within the mission editor.

 CaptureZone = ZONE:New( "CaptureZone" )

Next, we define the ZoneCaptureCoalition object, as explained above.

 ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( CaptureZone, coalition.side.RED ) 

Of course, we want to let the ZoneCaptureCoalition object do something when the state transitions. Do accomodate this, it is very simple, as explained above. We use Event Handlers to tailor the logic.

Here we place an Event Handler at the Guarded event. So when the Guarded event is triggered, then this method is called! With the variables From, Event, To. Each of these variables containing a string.

We check if the previous state wasn't Guarded also. If not, we retrieve the owning Coalition of the ZoneCaptureCoalition, using self:GetCoalition(). So Coalition will contain the current owning coalition of the zone.

Depending on the zone ownership, different messages are sent. Note the methods ZoneCaptureCoalition:GetZoneName().

 --- @param Functional.ZoneCaptureCoalition#ZONE_CAPTURE_COALITION self
 function ZoneCaptureCoalition:OnEnterGuarded( From, Event, To )
   if From ~= To then
     local Coalition = self:GetCoalition()
     self:E( { Coalition = Coalition } )
     if Coalition == coalition.side.BLUE then
       ZoneCaptureCoalition:Smoke( SMOKECOLOR.Blue )
       US_CC:MessageTypeToCoalition( string.format( "%s is under protection of the USA", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
       RU_CC:MessageTypeToCoalition( string.format( "%s is under protection of the USA", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     else
       ZoneCaptureCoalition:Smoke( SMOKECOLOR.Red )
       RU_CC:MessageTypeToCoalition( string.format( "%s is under protection of Russia", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
       US_CC:MessageTypeToCoalition( string.format( "%s is under protection of Russia", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     end
   end
 end

As you can see, not a rocket science. Next is the Event Handler when the Empty state transition is triggered. Now we smoke the ZoneCaptureCoalition with a green color, using self:Smoke( SMOKECOLOR.Green ).

 --- @param Functional.Protect#ZONE_CAPTURE_COALITION self
 function ZoneCaptureCoalition:OnEnterEmpty()
   self:Smoke( SMOKECOLOR.Green )
   US_CC:MessageTypeToCoalition( string.format( "%s is unprotected, and can be captured!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
   RU_CC:MessageTypeToCoalition( string.format( "%s is unprotected, and can be captured!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
 end

The next Event Handlers speak for itself. When the zone is Attacked, we smoke the zone white and send some messages to each coalition.

 --- @param Functional.Protect#ZONE_CAPTURE_COALITION self
 function ZoneCaptureCoalition:OnEnterAttacked()
   ZoneCaptureCoalition:Smoke( SMOKECOLOR.White )
   local Coalition = self:GetCoalition()
   self:E({Coalition = Coalition})
   if Coalition == coalition.side.BLUE then
     US_CC:MessageTypeToCoalition( string.format( "%s is under attack by Russia", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     RU_CC:MessageTypeToCoalition( string.format( "We are attacking %s", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
   else
     RU_CC:MessageTypeToCoalition( string.format( "%s is under attack by the USA", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     US_CC:MessageTypeToCoalition( string.format( "We are attacking %s", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
   end
 end

When the zone is Captured, we send some victory or loss messages to the correct coalition. And we add some score.

 --- @param Functional.Protect#ZONE_CAPTURE_COALITION self
 function ZoneCaptureCoalition:OnEnterCaptured()
   local Coalition = self:GetCoalition()
   self:E({Coalition = Coalition})
   if Coalition == coalition.side.BLUE then
     RU_CC:MessageTypeToCoalition( string.format( "%s is captured by the USA, we lost it!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     US_CC:MessageTypeToCoalition( string.format( "We captured %s, Excellent job!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
   else
     US_CC:MessageTypeToCoalition( string.format( "%s is captured by Russia, we lost it!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
     RU_CC:MessageTypeToCoalition( string.format( "We captured %s, Excellent job!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
   end

   self:__Guard( 30 )
 end

And this call is the most important of all! In the context of the mission, we need to start the zone capture monitoring process. Or nothing will be monitored and the zone won't change states. We start the monitoring after 5 seconds, and will repeat every 30 seconds a check.

 ZoneCaptureCoalition:Start( 5, 30 )

Type(s)

Fields and Methods inherited from ZONE_CAPTURE_COALITION Description

ZONE_CAPTURE_COALITION:Attack()

Attack Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:Capture()

Capture Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION.ClassName

Name of the class.

ZONE_CAPTURE_COALITION:Empty()

Empty Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:Guard()

Guard Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION.HitTimeAttackOver

Time interval in seconds before the zone goes from "Attacked" to "Guarded" state after the last hit.

ZONE_CAPTURE_COALITION.HitTimeLast

Time stamp in seconds when the last unit inside the zone was hit.

ZONE_CAPTURE_COALITION.HitsOn

If true, hit events are monitored and trigger the "Attack" event when a defending unit is hit.

ZONE_CAPTURE_COALITION:IsAttacked()

Check if zone is "Attacked", i.e.

ZONE_CAPTURE_COALITION:IsCaptured()

Check if zone is "Captured", i.e.

ZONE_CAPTURE_COALITION:IsEmpty()

Check if zone is "Empty".

ZONE_CAPTURE_COALITION:IsGuarded()

Check if zone is "Guarded", i.e.

ZONE_CAPTURE_COALITION:Mark()

Update Mark on F10 map.

ZONE_CAPTURE_COALITION.MarkBlue

ID of blue F10 mark.

ZONE_CAPTURE_COALITION.MarkOn

If true, create marks of zone status on F10 map.

ZONE_CAPTURE_COALITION.MarkRed

ID of red F10 mark.

ZONE_CAPTURE_COALITION:New(Zone, Coalition, UnitCategories, ObjectCategories)

ZONE_CAPTURE_COALITION Constructor.

ZONE_CAPTURE_COALITION:OnAfterAttack(From, Event, To)

Attack Handler OnAfter for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnAfterCapture(From, Event, To)

Capture Handler OnAfter for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnAfterEmpty(From, Event, To)

Empty Handler OnAfter for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnAfterGuard(From, Event, To)

Guard Handler OnAfter for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnBeforeAttack(From, Event, To)

Attack Handler OnBefore for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnBeforeCapture(From, Event, To)

Capture Handler OnBefore for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnBeforeEmpty(From, Event, To)

Empty Handler OnBefore for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnBeforeGuard(From, Event, To)

Guard Handler OnBefore for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:OnEventHit(EventData)

Monitor hit events.

ZONE_CAPTURE_COALITION.RepeatInterval

Time in seconds after which the zone status is updated.

ZONE_CAPTURE_COALITION.ScheduleStatusZone

ZONE_CAPTURE_COALITION:SetMarkZone(Switch)

Set whether marks on the F10 map are shown, which display the current zone status.

ZONE_CAPTURE_COALITION:SetMonitorHits(Switch, TimeAttackOver)

Set whether hit events of defending units are monitored and trigger "Attack" events.

ZONE_CAPTURE_COALITION.SmokeScheduler

ZONE_CAPTURE_COALITION:Start(StartInterval, RepeatInterval)

Starts the zone capturing monitoring process.

ZONE_CAPTURE_COALITION.StartInterval

Time in seconds after the status monitor is started.

ZONE_CAPTURE_COALITION:StatusZone()

Check status Coalition ownership.

ZONE_CAPTURE_COALITION:Stop()

Stops the zone capturing monitoring process.

ZONE_CAPTURE_COALITION:__Attack(Delay)

Attack Asynchronous Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:__Capture(Delay)

Capture Asynchronous Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:__Empty(Delay)

Empty Asynchronous Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:__Guard(Delay)

Guard Asynchronous Trigger for ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION:onafterGuard()

On after "Guard" event.

ZONE_CAPTURE_COALITION:onenterAttacked()

On enter "Attacked" state.

ZONE_CAPTURE_COALITION:onenterCaptured()

On enter "Captured" state.

ZONE_CAPTURE_COALITION:onenterEmpty()

On enter "Empty" state.

ZONE_CAPTURE_COALITION:onenterGuarded()

On enter "Guarded" state.

Fields and Methods inherited from ZONE_GOAL_COALITION Description

ZONE_CAPTURE_COALITION.ClassName

Name of the Class.

ZONE_CAPTURE_COALITION.Coalition

The current coalition ID of the zone owner.

ZONE_CAPTURE_COALITION:GetCoalition()

Get the owning coalition of the zone.

ZONE_CAPTURE_COALITION:GetCoalitionName()

Get the owning coalition name of the zone.

ZONE_CAPTURE_COALITION:GetPreviousCoalition()

Get the previous coaliton, i.e.

ZONE_CAPTURE_COALITION:New(Zone, Coalition, UnitCategories)

ZONE_GOAL_COALITION Constructor.

ZONE_CAPTURE_COALITION.ObjectCategories

Table of object categories that are able to hold a zone. Default is UNITS and STATICS.

ZONE_CAPTURE_COALITION.PreviousCoalition

The previous owner of the zone.

ZONE_CAPTURE_COALITION:SetCoalition(Coalition)

Set the owning coalition of the zone.

ZONE_CAPTURE_COALITION:SetObjectCategories(ObjectCategories)

Set the owning coalition of the zone.

ZONE_CAPTURE_COALITION:SetUnitCategories(UnitCategories)

Set the owning coalition of the zone.

ZONE_CAPTURE_COALITION.States

ZONE_CAPTURE_COALITION:StatusZone()

Check status Coalition ownership.

ZONE_CAPTURE_COALITION.UnitCategories

Table of unit categories that are able to capture and hold the zone. Default is only GROUND units.

Fields and Methods inherited from ZONE_GOAL Description

ZONE_CAPTURE_COALITION.ClassName

Name of the class.

ZONE_CAPTURE_COALITION:DestroyedUnit()

DestroyedUnit event.

ZONE_CAPTURE_COALITION:Flare(FlareColor)

Flare the zone boundary.

ZONE_CAPTURE_COALITION:GetZone()

Get the Zone.

ZONE_CAPTURE_COALITION:GetZoneName()

Get the name of the Zone.

ZONE_CAPTURE_COALITION.Goal

The goal object.

ZONE_CAPTURE_COALITION:MonitorDestroyedUnits()

Activate the event UnitDestroyed to be fired when a unit is destroyed in the zone.

ZONE_CAPTURE_COALITION:New(Zone)

ZONE_GOAL Constructor.

ZONE_CAPTURE_COALITION:OnAfterDestroyedUnit(From, Event, To, DestroyedUnit, PlayerName)

DestroyedUnit Handler OnAfter for ZONE_GOAL

ZONE_CAPTURE_COALITION:SetSmokeZone(switch)

Activate smoking of zone with the color or the current owner.

ZONE_CAPTURE_COALITION:Smoke(SmokeColor)

Set the smoke color.

ZONE_CAPTURE_COALITION.SmokeColor

Color of the smoke.

ZONE_CAPTURE_COALITION.SmokeScheduler

Scheduler responsible for smoking the zone.

ZONE_CAPTURE_COALITION.SmokeTime

Time stamp in seconds when the last smoke of the zone was triggered.

ZONE_CAPTURE_COALITION.SmokeZone

If true, smoke zone.

ZONE_CAPTURE_COALITION:StatusSmoke()

Check status Smoke.

ZONE_CAPTURE_COALITION:__Destroyed(EventData)

ZONE_CAPTURE_COALITION:__DestroyedUnit(delay)

DestroyedUnit delayed event

ZONE_CAPTURE_COALITION:onafterGuard()

When started, check the Smoke and the Zone status.

Fields and Methods inherited from ZONE_RADIUS Description

ZONE_CAPTURE_COALITION:BoundZone(Points, CountryID, UnBound)

Bounds the zone with tires.

ZONE_CAPTURE_COALITION:CheckScannedCoalition(Coalition)

Check if a certain coalition is inside a scanned zone.

ZONE_CAPTURE_COALITION:CountScannedCoalitions()

Count the number of different coalitions inside the zone.

ZONE_CAPTURE_COALITION:FlareZone(FlareColor, Points, Azimuth, AddHeight)

Flares the zone boundaries in a color.

ZONE_CAPTURE_COALITION:GetRadius()

Returns the radius of the zone.

ZONE_CAPTURE_COALITION:GetRandomCoordinate(inner, outer)

Returns a Core.Point#COORDINATE object reflecting a random 3D location within the zone.

ZONE_CAPTURE_COALITION:GetRandomPointVec2(inner, outer)

Returns a Core.Point#POINT_VEC2 object reflecting a random 2D location within the zone.

ZONE_CAPTURE_COALITION:GetRandomPointVec3(inner, outer)

Returns a Core.Point#POINT_VEC3 object reflecting a random 3D location within the zone.

ZONE_CAPTURE_COALITION:GetRandomVec2(inner, outer)

Returns a random Vec2 location within the zone.

ZONE_CAPTURE_COALITION:GetRandomVec3(inner, outer)

Returns Returns a random Vec3 location within the zone.

ZONE_CAPTURE_COALITION:GetScannedCoalition(Coalition)

Get Coalitions of the units in the Zone, or Check if there are units of the given Coalition in the Zone.

ZONE_CAPTURE_COALITION:GetScannedScenery()

Get scanned scenery table

ZONE_CAPTURE_COALITION:GetScannedSceneryType(SceneryType)

Get scanned scenery type

ZONE_CAPTURE_COALITION:GetScannedSetUnit()

Get a set of scanned units.

ZONE_CAPTURE_COALITION:GetScannedUnits()

Count the number of different coalitions inside the zone.

ZONE_CAPTURE_COALITION:GetVec2()

Returns the DCS#Vec2 of the zone.

ZONE_CAPTURE_COALITION:GetVec3(Height)

Returns the DCS#Vec3 of the ZONE_RADIUS.

ZONE_CAPTURE_COALITION:IsAllInZoneOfCoalition(Coalition)

Is All in Zone of Coalition?

ZONE_CAPTURE_COALITION:IsAllInZoneOfOtherCoalition(Coalition)

Is All in Zone of Other Coalition?

ZONE_CAPTURE_COALITION:IsNoneInZone()

Is None in Zone?

ZONE_CAPTURE_COALITION:IsNoneInZoneOfCoalition(Coalition)

Is None in Zone of Coalition?

ZONE_CAPTURE_COALITION:IsSomeInZoneOfCoalition(Coalition)

Is Some in Zone of Coalition?

ZONE_CAPTURE_COALITION:IsVec2InZone(Vec2)

Returns if a location is within the zone.

ZONE_CAPTURE_COALITION:IsVec3InZone(Vec3)

Returns if a point is within the zone.

ZONE_CAPTURE_COALITION:MarkZone(Points)

Mark the zone with markers on the F10 map.

ZONE_CAPTURE_COALITION:New(ZoneName, Vec2, Radius)

Constructor of #ZONE_RADIUS, taking the zone name, the zone location and a radius.

ZONE_CAPTURE_COALITION.Radius

The radius of the zone.

ZONE_CAPTURE_COALITION:Scan(ObjectCategories, UnitCategories)

Scan the zone for the presence of units of the given ObjectCategories.

ZONE_CAPTURE_COALITION.ScanData

ZONE_CAPTURE_COALITION:SearchZone(ObjectCategories, EvaluateFunction)

Searches the zone

ZONE_CAPTURE_COALITION:SetRadius(Radius)

Sets the radius of the zone.

ZONE_CAPTURE_COALITION:SetVec2(Vec2)

Sets the DCS#Vec2 of the zone.

ZONE_CAPTURE_COALITION:SmokeZone(SmokeColor, Points, AddHeight, AddOffSet, AngleOffset)

Smokes the zone boundaries in a color.

ZONE_CAPTURE_COALITION.Vec2

The current location of the zone.

Field(s)

#string ZONE_CAPTURE_COALITION.ClassName

Name of the class.

#number ZONE_CAPTURE_COALITION.HitTimeAttackOver

Time interval in seconds before the zone goes from "Attacked" to "Guarded" state after the last hit.

#number ZONE_CAPTURE_COALITION.HitTimeLast

Time stamp in seconds when the last unit inside the zone was hit.

#boolean ZONE_CAPTURE_COALITION.HitsOn

If true, hit events are monitored and trigger the "Attack" event when a defending unit is hit.

#number ZONE_CAPTURE_COALITION.MarkBlue

ID of blue F10 mark.

#boolean ZONE_CAPTURE_COALITION.MarkOn

If true, create marks of zone status on F10 map.

#number ZONE_CAPTURE_COALITION.MarkRed

ID of red F10 mark.

#number ZONE_CAPTURE_COALITION.RepeatInterval

Time in seconds after which the zone status is updated.

#number ZONE_CAPTURE_COALITION.StartInterval

Time in seconds after the status monitor is started.

Function(s)

Attack Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Capture Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Empty Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Guard Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Check if zone is "Attacked", i.e.

another coaliton entered the zone.

Defined in:

ZONE_CAPTURE_COALITION

Return value:

#boolean:

self:IsSomeInZoneOfCoalition( self.Coalition )

Check if zone is "Captured", i.e.

another coalition took control over the zone and is the only one present.

Defined in:

ZONE_CAPTURE_COALITION

Return value:

#boolean:

self:IsAllInZoneOfOtherCoalition( self.Coalition )

Check if zone is "Empty".

Defined in:

ZONE_CAPTURE_COALITION

Return value:

#boolean:

self:IsNoneInZone()

Check if zone is "Guarded", i.e.

only one (the defending) coaliton is present inside the zone.

Defined in:

ZONE_CAPTURE_COALITION

Return value:

#boolean:

self:IsAllInZoneOfCoalition( self.Coalition )

Update Mark on F10 map.

Defined in:

ZONE_CAPTURE_COALITION

ZONE_CAPTURE_COALITION Constructor.

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

A Zone object with the goal to be achieved.

The initial coalition owning the zone.

#table UnitCategories

Table of unit categories. See DCS Class Unit. Default {Unit.Category.GROUND_UNIT}.

#table ObjectCategories

Table of unit categories. See DCS Class Object. Default {Object.Category.UNIT, Object.Category.STATIC}, i.e. all UNITS and STATICS.

Return value:

Usage:


 AttackZone = ZONE:New( "AttackZone" )

 ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( AttackZone, coalition.side.RED, {UNITS ) -- Create a new ZONE_CAPTURE_COALITION object of zone AttackZone with ownership RED coalition.
 ZoneCaptureCoalition:__Guard( 1 ) -- Start the Guarding of the AttackZone.
 

Attack Handler OnAfter for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Capture Handler OnAfter for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Empty Handler OnAfter for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Guard Handler OnAfter for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Attack Handler OnBefore for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Return value:

#boolean:

Capture Handler OnBefore for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Return value:

#boolean:

Empty Handler OnBefore for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Return value:

#boolean:

Guard Handler OnBefore for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#string From

#string Event

#string To

Return value:

#boolean:

Monitor hit events.

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

The event data.

Set whether marks on the F10 map are shown, which display the current zone status.

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

#boolean Switch

If true or nil, marks are shown. If false, marks are not displayed.

Return value:

Set whether hit events of defending units are monitored and trigger "Attack" events.

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#boolean Switch

If true, hit events are monitored. If false or nil, hit events are not monitored.

#number TimeAttackOver

(Optional) Time in seconds after an attack is over after the last hit and the zone state goes to "Guarded". Default is 300 sec = 5 min.

Return value:

Starts the zone capturing monitoring process.

This process can be CPU intensive, ensure that you specify reasonable time intervals for the monitoring process. Note that the monitoring process is NOT started automatically during the :New() constructor. It is advised that the zone monitoring process is only started when the monitoring is of relevance in context of the current mission goals. When the zone is of no relevance, it is advised NOT to start the monitoring process, or to stop the monitoring process to save CPU resources. Therefore, the mission designer will need to use the :Start() method within his script to start the monitoring process specifically.

Defined in:

ZONE_CAPTURE_COALITION

Parameters:

#number StartInterval

(optional) Specifies the start time interval in seconds when the zone state will be checked for the first time.

#number RepeatInterval

(optional) Specifies the repeat time interval in seconds when the zone state will be checked repeatedly.

Return value:

Usage:


-- Setup the zone.
CaptureZone = ZONE:New( "CaptureZone" )
ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( CaptureZone, coalition.side.RED )

-- This starts the monitoring process within 15 seconds, repeating every 15 seconds.
ZoneCaptureCoalition:Start() 
     
-- This starts the monitoring process immediately, but repeats every 30 seconds.
ZoneCaptureCoalition:Start( 0, 30 ) 

Check status Coalition ownership.

Defined in:

ZONE_CAPTURE_COALITION

Stops the zone capturing monitoring process.

When the zone capturing monitor process is stopped, there won't be any changes anymore in the state and the owning coalition of the zone. This method becomes really useful when the zone is of no relevance anymore within a long lasting mission. In this case, it is advised to stop the monitoring process, not to consume unnecessary the CPU intensive scanning of units presence within the zone.

Defined in:

ZONE_CAPTURE_COALITION

Usages:

  • 
    -- Setup the zone.
    CaptureZone = ZONE:New( "CaptureZone" )
    ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( CaptureZone, coalition.side.RED )
    
    -- This starts the monitoring process within 15 seconds, repeating every 15 seconds.
    ZoneCaptureCoalition:Start() 
    
    -- When the zone capturing is of no relevance anymore, stop the monitoring!
    ZoneCaptureCoalition:Stop()
    
  • -- For example, one could stop the monitoring when the zone was captured!
    --- @param Functional.Protect#ZONE_CAPTURE_COALITION self
    function ZoneCaptureCoalition:OnEnterCaptured()
      local Coalition = self:GetCoalition()
      self:E({Coalition = Coalition})
      if Coalition == coalition.side.BLUE then
        RU_CC:MessageTypeToCoalition( string.format( "%s is captured by the USA, we lost it!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
        US_CC:MessageTypeToCoalition( string.format( "We captured %s, Excellent job!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
      else
        US_CC:MessageTypeToCoalition( string.format( "%s is captured by Russia, we lost it!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
        RU_CC:MessageTypeToCoalition( string.format( "We captured %s, Excellent job!", ZoneCaptureCoalition:GetZoneName() ), MESSAGE.Type.Information )
      end
     
      self:AddScore( "Captured", "Zone captured: Extra points granted.", 200 )    
     
      self:Stop()
    end
    

Attack Asynchronous Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

#number Delay

Capture Asynchronous Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

#number Delay

Empty Asynchronous Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

#number Delay

Guard Asynchronous Trigger for ZONE_CAPTURE_COALITION

Defined in:

ZONE_CAPTURE_COALITION

Parameter:

#number Delay

On after "Guard" event.

Defined in:

ZONE_CAPTURE_COALITION

On enter "Attacked" state.

Defined in:

ZONE_CAPTURE_COALITION

On enter "Captured" state.

Defined in:

ZONE_CAPTURE_COALITION

On enter "Empty" state.

Defined in:

ZONE_CAPTURE_COALITION

On enter "Guarded" state.

Defined in:

ZONE_CAPTURE_COALITION

Field(s)

#string ZONE_CAPTURE_COALITION.ClassName

Name of the class.

#number ZONE_CAPTURE_COALITION.HitTimeAttackOver

Time interval in seconds before the zone goes from "Attacked" to "Guarded" state after the last hit.

#number ZONE_CAPTURE_COALITION.HitTimeLast

Time stamp in seconds when the last unit inside the zone was hit.

#boolean ZONE_CAPTURE_COALITION.HitsOn

If true, hit events are monitored and trigger the "Attack" event when a defending unit is hit.

#number ZONE_CAPTURE_COALITION.MarkBlue

ID of blue F10 mark.

#boolean ZONE_CAPTURE_COALITION.MarkOn

If true, create marks of zone status on F10 map.

#number ZONE_CAPTURE_COALITION.MarkRed

ID of red F10 mark.

#number ZONE_CAPTURE_COALITION.RepeatInterval

Time in seconds after which the zone status is updated.

#number ZONE_CAPTURE_COALITION.StartInterval

Time in seconds after the status monitor is started.

Function(s)

Get the owning coalition of the zone.

Get the owning coalition name of the zone.

Defined in:

Return value:

#string:

Coalition name.

Get the previous coaliton, i.e.

the one owning the zone before the current one.

ZONE_GOAL_COALITION Constructor.

Defined in:

Parameters:

A Zone object with the goal to be achieved.

The initial coalition owning the zone. Default coalition.side.NEUTRAL.

#table UnitCategories

Table of unit categories. See DCS Class Unit. Default {Unit.Category.GROUND_UNIT}.

Return value:

Set the owning coalition of the zone.

Defined in:

Parameter:

The coalition ID, e.g. coalition.side.RED.

Return value:

Set the owning coalition of the zone.

Defined in:

Parameter:

#table ObjectCategories

Table of unit categories. See DCS Class Object. Default {Object.Category.UNIT, Object.Category.STATIC}, i.e. all UNITS and STATICS.

Return value:

Set the owning coalition of the zone.

Defined in:

Parameter:

#table UnitCategories

Table of unit categories. See DCS Class Unit. Default {Unit.Category.GROUND_UNIT}.

Return value:

Field(s)

#string ZONE_CAPTURE_COALITION.ClassName

Name of the class.

#number ZONE_CAPTURE_COALITION.HitTimeAttackOver

Time interval in seconds before the zone goes from "Attacked" to "Guarded" state after the last hit.

#number ZONE_CAPTURE_COALITION.HitTimeLast

Time stamp in seconds when the last unit inside the zone was hit.

#boolean ZONE_CAPTURE_COALITION.HitsOn

If true, hit events are monitored and trigger the "Attack" event when a defending unit is hit.

#number ZONE_CAPTURE_COALITION.MarkBlue

ID of blue F10 mark.

#boolean ZONE_CAPTURE_COALITION.MarkOn

If true, create marks of zone status on F10 map.

#number ZONE_CAPTURE_COALITION.MarkRed

ID of red F10 mark.

#number ZONE_CAPTURE_COALITION.RepeatInterval

Time in seconds after which the zone status is updated.

#number ZONE_CAPTURE_COALITION.StartInterval

Time in seconds after the status monitor is started.

Function(s)

Flare the zone boundary.

Defined in:

Parameter:

Get the name of the Zone.

Defined in:

Return value:

#string:

Activate the event UnitDestroyed to be fired when a unit is destroyed in the zone.

ZONE_GOAL Constructor.

Defined in:

Parameter:

A Zone object with the goal to be achieved.

Return value:

DestroyedUnit Handler OnAfter for ZONE_GOAL

Defined in:

Parameters:

#string From

#string Event

#string To

Wrapper.Unit#UNIT DestroyedUnit

The destroyed unit.

#string PlayerName

The name of the player.

Activate smoking of zone with the color or the current owner.

Defined in:

Parameter:

#boolean switch

If true or nil activate smoke. If false or nil, no smoke.

Return value:

DestroyedUnit delayed event

Defined in:

Parameter:

#number delay

Delay in seconds.

When started, check the Smoke and the Zone status.

Field(s)

#string ZONE_CAPTURE_COALITION.ClassName

Name of the class.

#number ZONE_CAPTURE_COALITION.HitTimeAttackOver

Time interval in seconds before the zone goes from "Attacked" to "Guarded" state after the last hit.

#number ZONE_CAPTURE_COALITION.HitTimeLast

Time stamp in seconds when the last unit inside the zone was hit.

#boolean ZONE_CAPTURE_COALITION.HitsOn

If true, hit events are monitored and trigger the "Attack" event when a defending unit is hit.

#number ZONE_CAPTURE_COALITION.MarkBlue

ID of blue F10 mark.

#boolean ZONE_CAPTURE_COALITION.MarkOn

If true, create marks of zone status on F10 map.

#number ZONE_CAPTURE_COALITION.MarkRed

ID of red F10 mark.

#number ZONE_CAPTURE_COALITION.RepeatInterval

Time in seconds after which the zone status is updated.

#number ZONE_CAPTURE_COALITION.StartInterval

Time in seconds after the status monitor is started.

Function(s)

Bounds the zone with tires.

Defined in:

Parameters:

#number Points

(optional) The amount of points in the circle. Default 360.

DCS#country.id CountryID

The country id of the tire objects, e.g. country.id.USA for blue or country.id.RUSSIA for red.

#boolean UnBound

(Optional) If true the tyres will be destroyed.

Return value:

self

Check if a certain coalition is inside a scanned zone.

Defined in:

Parameter:

#number Coalition

The coalition id, e.g. coalition.side.BLUE.

Return value:

#boolean:

If true, the coalition is inside the zone.

Count the number of different coalitions inside the zone.

Defined in:

Return value:

#number:

Counted coalitions.

Flares the zone boundaries in a color.

Defined in:

Parameters:

The flare color.

#number Points

(optional) The amount of points in the circle.

DCS#Azimuth Azimuth

(optional) Azimuth The azimuth of the flare.

#number AddHeight

(optional) The height to be added for the smoke.

Return value:

self

Returns the radius of the zone.

Defined in:

Return value:

The radius of the zone.

Returns a Core.Point#COORDINATE object reflecting a random 3D location within the zone.

Defined in:

Parameters:

#number inner

(optional) Minimal distance from the center of the zone. Default is 0.

#number outer

(optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.

Return value:

Returns a Core.Point#POINT_VEC2 object reflecting a random 2D location within the zone.

Defined in:

Parameters:

#number inner

(optional) Minimal distance from the center of the zone. Default is 0.

#number outer

(optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.

Return value:

The Core.Point#POINT_VEC2 object reflecting the random 3D location within the zone.

Returns a Core.Point#POINT_VEC3 object reflecting a random 3D location within the zone.

Defined in:

Parameters:

#number inner

(optional) Minimal distance from the center of the zone. Default is 0.

#number outer

(optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.

Return value:

The Core.Point#POINT_VEC3 object reflecting the random 3D location within the zone.

Returns a random Vec2 location within the zone.

Defined in:

Parameters:

#number inner

(optional) Minimal distance from the center of the zone. Default is 0.

#number outer

(optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.

Return value:

The random location within the zone.

Returns Returns a random Vec3 location within the zone.

Defined in:

Parameters:

#number inner

(optional) Minimal distance from the center of the zone. Default is 0.

#number outer

(optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.

Return value:

The random location within the zone.

Get Coalitions of the units in the Zone, or Check if there are units of the given Coalition in the Zone.

Returns nil if there are none to two Coalitions in the zone! Returns one Coalition if there are only Units of one Coalition in the Zone. Returns the Coalition for the given Coalition if there are units of the Coalition in the Zone.

Defined in:

Parameter:

Coalition

Return value:

#table:

Get scanned scenery table

Defined in:

Return value:

#table:

Table of DCS scenery objects.

Get scanned scenery type

Defined in:

Parameter:

SceneryType

Return value:

#table:

Table of DCS scenery type objects.

Get a set of scanned units.

Defined in:

Return value:

Set of units and statics inside the zone.

Count the number of different coalitions inside the zone.

Defined in:

Return value:

#table:

Table of DCS units and DCS statics inside the zone.

Returns the DCS#Vec2 of the zone.

Defined in:

Return value:

The location of the zone.

Returns the DCS#Vec3 of the ZONE_RADIUS.

Defined in:

Parameter:

DCS#Distance Height

The height to add to the land height where the center of the zone is located.

Return value:

The point of the zone.

Is All in Zone of Coalition?

Check if only the specifed coalition is inside the zone and noone else.

Defined in:

Parameter:

#number Coalition

Coalition ID of the coalition which is checked to be the only one in the zone.

Return value:

#boolean:

True, if only that coalition is inside the zone and no one else.

Usage:

   self.Zone:Scan()
   local IsGuarded = self.Zone:IsAllInZoneOfCoalition( self.Coalition )

Is All in Zone of Other Coalition?

Check if only one coalition is inside the zone and the specified coalition is not the one. You first need to use the ZONE_RADIUS.Scan method to scan the zone before it can be evaluated! Note that once a zone has been scanned, multiple evaluations can be done on the scan result set.

Defined in:

Parameter:

#number Coalition

Coalition ID of the coalition which is not supposed to be in the zone.

Return value:

#boolean:

True, if and only if only one coalition is inside the zone and the specified coalition is not it.

Usage:

   self.Zone:Scan()
   local IsCaptured = self.Zone:IsAllInZoneOfOtherCoalition( self.Coalition )

Is None in Zone?

You first need to use the ZONE_RADIUS.Scan method to scan the zone before it can be evaluated! Note that once a zone has been scanned, multiple evaluations can be done on the scan result set.

Defined in:

Return value:

#boolean:

Usage:

   self.Zone:Scan()
   local IsEmpty = self.Zone:IsNoneInZone()

Is None in Zone of Coalition?

You first need to use the ZONE_RADIUS.Scan method to scan the zone before it can be evaluated! Note that once a zone has been scanned, multiple evaluations can be done on the scan result set.

Defined in:

Parameter:

Coalition

Return value:

#boolean:

Usage:

   self.Zone:Scan()
   local IsOccupied = self.Zone:IsNoneInZoneOfCoalition( self.Coalition )

Is Some in Zone of Coalition?

Check if more than one coaltion is inside the zone and the specifed coalition is one of them. You first need to use the ZONE_RADIUS.Scan method to scan the zone before it can be evaluated! Note that once a zone has been scanned, multiple evaluations can be done on the scan result set.

Defined in:

Parameter:

#number Coalition

ID of the coaliton which is checked to be inside the zone.

Return value:

#boolean:

True if more than one coalition is inside the zone and the specified coalition is one of them.

Usage:

   self.Zone:Scan()
   local IsAttacked = self.Zone:IsSomeInZoneOfCoalition( self.Coalition )

Returns if a location is within the zone.

Defined in:

Parameter:

DCS#Vec2 Vec2

The location to test.

Return value:

#boolean:

true if the location is within the zone.

Returns if a point is within the zone.

Defined in:

Parameter:

DCS#Vec3 Vec3

The point to test.

Return value:

#boolean:

true if the point is within the zone.

Mark the zone with markers on the F10 map.

Defined in:

Parameter:

#number Points

(Optional) The amount of points in the circle. Default 360.

Return value:

self

Constructor of #ZONE_RADIUS, taking the zone name, the zone location and a radius.

Defined in:

Parameters:

#string ZoneName

Name of the zone.

DCS#Vec2 Vec2

The location of the zone.

DCS#Distance Radius

The radius of the zone.

Return value:

self

Scan the zone for the presence of units of the given ObjectCategories.

Note that after a zone has been scanned, the zone can be evaluated by:

Defined in:

Parameters:

ObjectCategories

An array of categories of the objects to find in the zone.

UnitCategories

An array of unit categories of the objects to find in the zone.

Usage:

   self.Zone:Scan()
   local IsAttacked = self.Zone:IsSomeInZoneOfCoalition( self.Coalition )

Searches the zone

Defined in:

Parameters:

ObjectCategories

A list of categories, which are members of Object.Category

EvaluateFunction

Sets the radius of the zone.

Defined in:

Parameter:

DCS#Distance Radius

The radius of the zone.

Return value:

The radius of the zone.

Sets the DCS#Vec2 of the zone.

Defined in:

Parameter:

DCS#Vec2 Vec2

The new location of the zone.

Return value:

The new location of the zone.

Smokes the zone boundaries in a color.

Defined in:

Parameters:

The smoke color.

#number Points

(optional) The amount of points in the circle.

#number AddHeight

(optional) The height to be added for the smoke.

#number AddOffSet

(optional) The angle to be added for the smoking start position.

AngleOffset

Return value:

self