From 9e2c66dae4d0d2051894dea575ef4a608da83dc6 Mon Sep 17 00:00:00 2001 From: FlightControl Date: Sat, 8 Apr 2017 08:06:29 +0200 Subject: [PATCH] SPAWN Delay implementation -- New methods SPAWN:InitDelayOnOff(), SPAWN:InitDelayOn(), SPAWN:InitDelayOff() -- Default is delay is on, but only for :SpawnScheduled() -- Did a large review of the SPAWN documentation (for dummies). -- Moved the SPAWN class documentation to the SPAWN object, so that it becomes visible in intellisense. -- Added Demo Mission links -- Added Youtube channel links --- Moose Development/Moose/Functional/Spawn.lua | 360 +++++++++------ docs/Documentation/AI_Patrol.html | 3 - docs/Documentation/Cargo.html | 1 - docs/Documentation/Detection.html | 3 +- docs/Documentation/Fsm.html | 3 +- docs/Documentation/MOVEMENT.html | 4 - docs/Documentation/Spawn.html | 451 +++++++++++++------ docs/Documentation/Zone.html | 220 ++++----- docs/Documentation/index.html | 11 +- 9 files changed, 627 insertions(+), 429 deletions(-) diff --git a/Moose Development/Moose/Functional/Spawn.lua b/Moose Development/Moose/Functional/Spawn.lua index 55cdcbbdd..02f757fed 100644 --- a/Moose Development/Moose/Functional/Spawn.lua +++ b/Moose Development/Moose/Functional/Spawn.lua @@ -1,112 +1,22 @@ ---- Single-Player:**Yes** / Multi-Player:**Yes** / AI:**Yes** / Human:**No** / Types:**All** -- --- **Spawn groups of units dynamically in your missions.** +--- **Functional** -- Spawn dynamically new @{Group}s in your missions. -- -- ![Banner Image](..\Presentations\SPAWN\SPAWN.JPG) -- --- === +-- ==== -- --- # 1) @{#SPAWN} class, extends @{Base#BASE} +-- # Demo Missions -- --- The @{#SPAWN} class allows to spawn dynamically new groups, based on pre-defined initialization settings, modifying the behaviour when groups are spawned. --- For each group to be spawned, within the mission editor, a group has to be created with the "late activation flag" set. We call this group the *"Spawn Template"* of the SPAWN object. --- A reference to this Spawn Template needs to be provided when constructing the SPAWN object, by indicating the name of the group within the mission editor in the constructor methods. +-- ### [SPAWN Demo Missions source code](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master-release/SPA%20-%20Spawning) -- --- Within the SPAWN object, there is an internal index that keeps track of which group from the internal group list was spawned. --- When new groups get spawned by using the SPAWN methods (see below), it will be validated whether the Limits (@{#SPAWN.Limit}) of the SPAWN object are not reached. --- When all is valid, a new group will be created by the spawning methods, and the internal index will be increased with 1. --- --- Regarding the name of new spawned groups, a _SpawnPrefix_ will be assigned for each new group created. --- If you want to have the Spawn Template name to be used as the _SpawnPrefix_ name, use the @{#SPAWN.New} constructor. --- However, when the @{#SPAWN.NewWithAlias} constructor was used, the Alias name will define the _SpawnPrefix_ name. --- Groups will follow the following naming structure when spawned at run-time: --- --- 1. Spawned groups will have the name _SpawnPrefix_#ggg, where ggg is a counter from 0 to 999. --- 2. Spawned units will have the name _SpawnPrefix_#ggg-uu, where uu is a counter from 0 to 99 for each new spawned unit belonging to the group. --- --- Some additional notes that need to be remembered: --- --- * Templates are actually groups defined within the mission editor, with the flag "Late Activation" set. As such, these groups are never used within the mission, but are used by the @{#SPAWN} module. --- * It is important to defined BEFORE you spawn new groups, a proper initialization of the SPAWN instance is done with the options you want to use. --- * When designing a mission, NEVER name groups using a "#" within the name of the group Spawn Template(s), or the SPAWN module logic won't work anymore. --- --- ## 1.1) SPAWN construction methods --- --- Create a new SPAWN object with the @{#SPAWN.New}() or the @{#SPAWN.NewWithAlias}() methods: --- --- * @{#SPAWN.New}(): Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition). --- * @{#SPAWN.NewWithAlias}(): Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition), and gives each spawned @{Group} an different name. +-- ### [SPAWN Demo Missions, only for beta testers](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/SPA%20-%20Spawning) -- --- It is important to understand how the SPAWN class works internally. The SPAWN object created will contain internally a list of groups that will be spawned and that are already spawned. --- The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons. --- So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient. --- --- ## 1.2) SPAWN initialization methods +-- ### [ALL Demo Missions pack of the last release](https://github.com/FlightControl-Master/MOOSE_MISSIONS/releases) -- --- A spawn object will behave differently based on the usage of **initialization** methods, which all start with the **Init** prefix: +-- ==== -- --- * @{#SPAWN.InitKeepUnitNames}(): Keeps the unit names as defined within the mission editor, but note that anything after a # mark is ignored, and any spaces before and after the resulting name are removed. IMPORTANT! This method MUST be the first used after :New !!! --- * @{#SPAWN.InitLimit}(): Limits the amount of groups that can be alive at the same time and that can be dynamically spawned. --- * @{#SPAWN.InitRandomizeRoute}(): Randomize the routes of spawned groups, and for air groups also optionally the height. --- * @{#SPAWN.InitRandomizeTemplate}(): Randomize the group templates so that when a new group is spawned, a random group template is selected from one of the templates defined. --- * @{#SPAWN.InitUnControlled}(): Spawn plane groups uncontrolled. --- * @{#SPAWN.InitArray}(): Make groups visible before they are actually activated, and order these groups like a batallion in an array. --- * @{#SPAWN.InitRepeat}(): Re-spawn groups when they land at the home base. Similar methods are @{#SPAWN.InitRepeatOnLanding} and @{#SPAWN.InitRepeatOnEngineShutDown}. --- * @{#SPAWN.InitRandomizePosition}(): Randomizes the position of @{Group}s that are spawned within a **radius band**, given an Outer and Inner radius, from the point that the spawn happens. --- * @{#SPAWN.InitRandomizeUnits}(): Randomizes the @{Unit}s in the @{Group} that is spawned within a **radius band**, given an Outer and Inner radius. --- * @{#SPAWN.InitRandomizeZones}(): Randomizes the spawning between a predefined list of @{Zone}s that are declared using this function. Each zone can be given a probability factor. --- * @{#SPAWN.InitAIOn}(): Turns the AI On when spawning the new @{Group} object. --- * @{#SPAWN.InitAIOff}(): Turns the AI Off when spawning the new @{Group} object. --- * @{#SPAWN.InitAIOnOff}(): Turns the AI On or Off when spawning the new @{Group} object. +-- # YouTube Channel -- --- ## 1.3) SPAWN spawning methods --- --- Groups can be spawned at different times and methods: --- --- * @{#SPAWN.Spawn}(): Spawn one new group based on the last spawned index. --- * @{#SPAWN.ReSpawn}(): Re-spawn a group based on a given index. --- * @{#SPAWN.SpawnScheduled}(): Spawn groups at scheduled but randomized intervals. You can use @{#SPAWN.SpawnScheduleStart}() and @{#SPAWN.SpawnScheduleStop}() to start and stop the schedule respectively. --- * @{#SPAWN.SpawnFromVec3}(): Spawn a new group from a Vec3 coordinate. (The group will can be spawned at a point in the air). --- * @{#SPAWN.SpawnFromVec2}(): Spawn a new group from a Vec2 coordinate. (The group will be spawned at land height ). --- * @{#SPAWN.SpawnFromStatic}(): Spawn a new group from a structure, taking the position of a @{Static}. --- * @{#SPAWN.SpawnFromUnit}(): Spawn a new group taking the position of a @{Unit}. --- * @{#SPAWN.SpawnInZone}(): Spawn a new group in a @{Zone}. --- --- Note that @{#SPAWN.Spawn} and @{#SPAWN.ReSpawn} return a @{GROUP#GROUP.New} object, that contains a reference to the DCSGroup object. --- You can use the @{GROUP} object to do further actions with the DCSGroup. --- --- ## 1.4) Retrieve alive GROUPs spawned by the SPAWN object --- --- The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution. --- Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS. --- SPAWN provides methods to iterate through that internal GROUP object reference table: --- --- * @{#SPAWN.GetFirstAliveGroup}(): Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found. --- * @{#SPAWN.GetNextAliveGroup}(): Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found. --- * @{#SPAWN.GetLastAliveGroup}(): Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found. --- --- You can use the methods @{#SPAWN.GetFirstAliveGroup}() and sequently @{#SPAWN.GetNextAliveGroup}() to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example. --- The method @{#SPAWN.GetGroupFromIndex}() will return the GROUP object reference from the given Index, dead or alive... --- --- ## 1.5) SPAWN object cleaning --- --- Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive. --- In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, --- and it may occur that no new groups are or can be spawned as limits are reached. --- To prevent this, a @{#SPAWN.InitCleanUp}() initialization method has been defined that will silently monitor the status of each spawned group. --- Once a group has a velocity = 0, and has been waiting for a defined interval, that group will be cleaned or removed from run-time. --- There is a catch however :-) If a damaged group has returned to an airbase within the coalition, that group will not be considered as "lost"... --- In such a case, when the inactive group is cleaned, a new group will Re-spawned automatically. --- This models AI that has succesfully returned to their airbase, to restart their combat activities. --- Check the @{#SPAWN.InitCleanUp}() for further info. --- --- ## 1.6) Catch the @{Group} spawn event in a callback function! --- --- When using the SpawnScheduled method, new @{Group}s are created following the schedule timing parameters. --- When a new @{Group} is spawned, you maybe want to execute actions with that group spawned at the spawn event. --- To SPAWN class supports this functionality through the @{#SPAWN.OnSpawnGroup}( **function( SpawnedGroup ) end ** ) method, which takes a function as a parameter that you can define locally. --- Whenever a new @{Group} is spawned, the given function is called, and the @{Group} that was just spawned, is given as a parameter. --- As a result, your spawn event handling function requires one parameter to be declared, which will contain the spawned @{Group} object. --- A coding example is provided at the description of the @{#SPAWN.OnSpawnGroup}( **function( SpawnedGroup ) end ** ) method. +-- ### [SPAWN YouTube Channel](https://www.youtube.com/playlist?list=PL7ZUrU4zZUl1jirWIo4t4YxqN-HxjqRkL) -- -- ==== -- @@ -119,44 +29,34 @@ -- -- Hereby the change log: -- +-- 2017-04-08: SPAWN:**InitDelayOnOff( DelayOnOff )** added. +-- 2017-04-08: SPAWN:**InitDelayOn()** added. +-- 2017-04-08: SPAWN:**InitDelayOff()** added. +-- -- 2017-03-14: SPAWN:**InitKeepUnitNames()** added. --- 2017-03-14: SPAWN:**InitRandomizePosition( RandomizePosition, OuterRadious, InnerRadius )** added. +-- 2017-03-14: SPAWN:**InitRandomizePosition( RandomizePosition, OuterRadious, InnerRadius )** added. -- --- 2017-02-04: SPAWN:InitUnControlled( **UnControlled** ) replaces SPAWN:InitUnControlled(). +-- 2017-02-04: SPAWN:InitUnControlled( **UnControlled** ) replaces SPAWN:InitUnControlled(). -- --- 2017-01-24: SPAWN:**InitAIOnOff( AIOnOff )** added. --- --- 2017-01-24: SPAWN:**InitAIOn()** added. --- --- 2017-01-24: SPAWN:**InitAIOff()** added. --- --- 2016-08-15: SPAWN:**InitCleanUp**( SpawnCleanUpInterval ) replaces SPAWN:_CleanUp_( SpawnCleanUpInterval ). +-- 2017-01-24: SPAWN:**InitAIOnOff( AIOnOff )** added. +-- 2017-01-24: SPAWN:**InitAIOn()** added. +-- 2017-01-24: SPAWN:**InitAIOff()** added. -- +-- 2016-08-15: SPAWN:**InitCleanUp**( SpawnCleanUpInterval ) replaces SPAWN:_CleanUp_( SpawnCleanUpInterval ). -- 2016-08-15: SPAWN:**InitRandomizeZones( SpawnZones )** added. -- --- 2016-08-14: SPAWN:**OnSpawnGroup**( SpawnCallBackFunction, ... ) replaces SPAWN:_SpawnFunction_( SpawnCallBackFunction, ... ). --- --- 2016-08-14: SPAWN.SpawnInZone( Zone, __RandomizeGroup__, SpawnIndex ) replaces SpawnInZone( Zone, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). --- --- 2016-08-14: SPAWN.SpawnFromVec3( Vec3, SpawnIndex ) replaces SpawnFromVec3( Vec3, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ): --- --- 2016-08-14: SPAWN.SpawnFromVec2( Vec2, SpawnIndex ) replaces SpawnFromVec2( Vec2, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ): --- --- 2016-08-14: SPAWN.SpawnFromUnit( SpawnUnit, SpawnIndex ) replaces SpawnFromUnit( SpawnUnit, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ): --- --- 2016-08-14: SPAWN.SpawnFromUnit( SpawnUnit, SpawnIndex ) replaces SpawnFromStatic( SpawnStatic, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ): --- --- 2016-08-14: SPAWN.**InitRandomizeUnits( RandomizeUnits, OuterRadius, InnerRadius )** added: --- --- 2016-08-14: SPAWN.**Init**Limit( SpawnMaxUnitsAlive, SpawnMaxGroups ) replaces SPAWN._Limit_( SpawnMaxUnitsAlive, SpawnMaxGroups ): --- --- 2016-08-14: SPAWN.**Init**Array( SpawnAngle, SpawnWidth, SpawnDeltaX, SpawnDeltaY ) replaces SPAWN._Array_( SpawnAngle, SpawnWidth, SpawnDeltaX, SpawnDeltaY ). --- --- 2016-08-14: SPAWN.**Init**RandomizeRoute( SpawnStartPoint, SpawnEndPoint, SpawnRadius, SpawnHeight ) replaces SPAWN._RandomizeRoute_( SpawnStartPoint, SpawnEndPoint, SpawnRadius, SpawnHeight ). --- --- 2016-08-14: SPAWN.**Init**RandomizeTemplate( SpawnTemplatePrefixTable ) replaces SPAWN._RandomizeTemplate_( SpawnTemplatePrefixTable ). --- --- 2016-08-14: SPAWN.**Init**UnControlled() replaces SPAWN._UnControlled_(). +-- 2016-08-14: SPAWN:**OnSpawnGroup**( SpawnCallBackFunction, ... ) replaces SPAWN:_SpawnFunction_( SpawnCallBackFunction, ... ). +-- 2016-08-14: SPAWN.SpawnInZone( Zone, __RandomizeGroup__, SpawnIndex ) replaces SpawnInZone( Zone, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). +-- 2016-08-14: SPAWN.SpawnFromVec3( Vec3, SpawnIndex ) replaces SpawnFromVec3( Vec3, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). +-- 2016-08-14: SPAWN.SpawnFromVec2( Vec2, SpawnIndex ) replaces SpawnFromVec2( Vec2, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). +-- 2016-08-14: SPAWN.SpawnFromUnit( SpawnUnit, SpawnIndex ) replaces SpawnFromUnit( SpawnUnit, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). +-- 2016-08-14: SPAWN.SpawnFromUnit( SpawnUnit, SpawnIndex ) replaces SpawnFromStatic( SpawnStatic, _RandomizeUnits, OuterRadius, InnerRadius,_ SpawnIndex ). +-- 2016-08-14: SPAWN.**InitRandomizeUnits( RandomizeUnits, OuterRadius, InnerRadius )** added. +-- 2016-08-14: SPAWN.**Init**Limit( SpawnMaxUnitsAlive, SpawnMaxGroups ) replaces SPAWN._Limit_( SpawnMaxUnitsAlive, SpawnMaxGroups ). +-- 2016-08-14: SPAWN.**Init**Array( SpawnAngle, SpawnWidth, SpawnDeltaX, SpawnDeltaY ) replaces SPAWN._Array_( SpawnAngle, SpawnWidth, SpawnDeltaX, SpawnDeltaY ). +-- 2016-08-14: SPAWN.**Init**RandomizeRoute( SpawnStartPoint, SpawnEndPoint, SpawnRadius, SpawnHeight ) replaces SPAWN._RandomizeRoute_( SpawnStartPoint, SpawnEndPoint, SpawnRadius, SpawnHeight ). +-- 2016-08-14: SPAWN.**Init**RandomizeTemplate( SpawnTemplatePrefixTable ) replaces SPAWN._RandomizeTemplate_( SpawnTemplatePrefixTable ). +-- 2016-08-14: SPAWN.**Init**UnControlled() replaces SPAWN._UnControlled_(). -- -- === -- @@ -177,7 +77,6 @@ --- SPAWN Class -- @type SPAWN --- @extends Core.Base#BASE -- @field ClassName -- @field #string SpawnTemplatePrefix -- @field #string SpawnAliasPrefix @@ -186,6 +85,165 @@ -- @field #number SpawnIndex -- @field #number MaxAliveGroups -- @field #SPAWN.SpawnZoneTable SpawnZoneTable +-- @extends Core.Base#BASE + + +--- # SPAWN class, extends @{Base#BASE} +-- +-- The SPAWN class allows to spawn dynamically new groups. +-- Each SPAWN object needs to be have a related **template group** setup in the Mission Editor (ME), +-- which is a normal group with the **Late Activation** flag set. +-- This template group will never be activated in your mission. +-- SPAWN uses that **template group** to reference to all the characteristics +-- (air, ground, livery, unit composition, formation, skill level etc) of each new group to be spawned. +-- +-- Therefore, when creating a SPAWN object, the @{#SPAWN.New} and @{#SPAWN.NewWithAlias} require +-- **the name of the template group** to be given as a string to those constructor methods. +-- +-- Initialization settings can be applied on the SPAWN object, +-- which modify the behaviour or the way groups are spawned. +-- These initialization methods have the prefix **Init**. +-- There are also spawn methods with the prefix **Spawn** and will spawn new groups in various ways. +-- +-- ### IMPORTANT! The methods with prefix **Init** must be used before any methods with prefix **Spawn** method are used, or unexpected results may appear!!! +-- +-- Because SPAWN can spawn multiple groups of a template group, +-- SPAWN has an **internal index** that keeps track +-- which was the latest group that was spawned. +-- +-- **Limits** can be set on how many groups can be spawn in each SPAWN object, +-- using the method @{#SPAWN.InitLimit}. SPAWN has 2 kind of limits: +-- +-- * The maximum amount of @{Unit}s that can be **alive** at the same time... +-- * The maximum amount of @{Group}s that can be **spawned**... This is more of a **resource**-type of limit. +-- +-- When new groups get spawned using the **Spawn** methods, +-- it will be evaluated whether any limits have been reached. +-- When no spawn limit is reached, a new group will be created by the spawning methods, +-- and the internal index will be increased with 1. +-- +-- These limits ensure that your mission does not accidentally get flooded with spawned groups. +-- Additionally, it also guarantees that independent of the group composition, +-- at any time, the most optimal amount of groups are alive in your mission. +-- For example, if your template group has a group composition of 10 units, and you specify a limit of 100 units alive at the same time, +-- with unlimited resources = :InitLimit( 100, 0 ) and 10 groups are alive, but two groups have only one unit alive in the group, +-- then a sequent Spawn(Scheduled) will allow a new group to be spawned!!! +-- +-- ### IMPORTANT!! If a limit has been reached, it is possible that a **Spawn** method returns **nil**, meaning, no @{Group} had been spawned!!! +-- +-- Spawned groups get **the same name** as the name of the template group. +-- Spawned units in those groups keep _by default_ **the same name** as the name of the template group. +-- However, because multiple groups and units are created from the template group, +-- a suffix is added to each spawned group and unit. +-- +-- Newly spawned groups will get the following naming structure at run-time: +-- +-- 1. Spawned groups will have the name _GroupName_#_nnn_, where _GroupName_ is the name of the **template group**, +-- and _nnn_ is a **counter from 0 to 999**. +-- 2. Spawned units will have the name _GroupName_#_nnn_-_uu_, +-- where _uu_ is a **counter from 0 to 99** for each new spawned unit belonging to the group. +-- +-- That being said, there is a way to keep the same unit names! +-- The method @{#SPAWN.InitKeepUnitNames}() will keep the same unit names as defined within the template group, thus: +-- +-- 3. Spawned units will have the name _UnitName_#_nnn_-_uu_, +-- where _UnitName_ is the **unit name as defined in the template group*, +-- and _uu_ is a **counter from 0 to 99** for each new spawned unit belonging to the group. +-- +-- Some **additional notes that need to be considered!!**: +-- +-- * templates are actually groups defined within the mission editor, with the flag "Late Activation" set. +-- As such, these groups are never used within the mission, but are used by the @{#SPAWN} module. +-- * It is important to defined BEFORE you spawn new groups, +-- a proper initialization of the SPAWN instance is done with the options you want to use. +-- * When designing a mission, NEVER name groups using a "#" within the name of the group Spawn template(s), +-- or the SPAWN module logic won't work anymore. +-- +-- ## SPAWN construction methods +-- +-- Create a new SPAWN object with the @{#SPAWN.New}() or the @{#SPAWN.NewWithAlias}() methods: +-- +-- * @{#SPAWN.New}(): Creates a new SPAWN object taking the name of the group that represents the GROUP template (definition). +-- * @{#SPAWN.NewWithAlias}(): Creates a new SPAWN object taking the name of the group that represents the GROUP template (definition), and gives each spawned @{Group} an different name. +-- +-- It is important to understand how the SPAWN class works internally. The SPAWN object created will contain internally a list of groups that will be spawned and that are already spawned. +-- The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons. +-- So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient. +-- +-- ## SPAWN **Init**ialization methods +-- +-- A spawn object will behave differently based on the usage of **initialization** methods, which all start with the **Init** prefix: +-- +-- * @{#SPAWN.InitKeepUnitNames}(): Keeps the unit names as defined within the mission editor, but note that anything after a # mark is ignored, and any spaces before and after the resulting name are removed. IMPORTANT! This method MUST be the first used after :New !!! +-- * @{#SPAWN.InitLimit}(): Limits the amount of groups that can be alive at the same time and that can be dynamically spawned. +-- * @{#SPAWN.InitRandomizeRoute}(): Randomize the routes of spawned groups, and for air groups also optionally the height. +-- * @{#SPAWN.InitRandomizeTemplate}(): Randomize the group templates so that when a new group is spawned, a random group template is selected from one of the templates defined. +-- * @{#SPAWN.InitUnControlled}(): Spawn plane groups uncontrolled. +-- * @{#SPAWN.InitArray}(): Make groups visible before they are actually activated, and order these groups like a batallion in an array. +-- * @{#SPAWN.InitRepeat}(): Re-spawn groups when they land at the home base. Similar methods are @{#SPAWN.InitRepeatOnLanding} and @{#SPAWN.InitRepeatOnEngineShutDown}. +-- * @{#SPAWN.InitRandomizePosition}(): Randomizes the position of @{Group}s that are spawned within a **radius band**, given an Outer and Inner radius, from the point that the spawn happens. +-- * @{#SPAWN.InitRandomizeUnits}(): Randomizes the @{Unit}s in the @{Group} that is spawned within a **radius band**, given an Outer and Inner radius. +-- * @{#SPAWN.InitRandomizeZones}(): Randomizes the spawning between a predefined list of @{Zone}s that are declared using this function. Each zone can be given a probability factor. +-- * @{#SPAWN.InitAIOn}(): Turns the AI On when spawning the new @{Group} object. +-- * @{#SPAWN.InitAIOff}(): Turns the AI Off when spawning the new @{Group} object. +-- * @{#SPAWN.InitAIOnOff}(): Turns the AI On or Off when spawning the new @{Group} object. +-- * @{#SPAWN.InitDelayOnOff}(): Turns the inital delay On/Off when spawning the first @{Group} object. +-- * @{#SPAWN.InitDelayOn}(): Turns the inital delay On when spawning the first @{Group} object. +-- * @{#SPAWN.InitDelayOff}(): Turns the inital delay On when spawning the first @{Group} object. +-- +-- ## SPAWN **Spawn** methods +-- +-- Groups can be spawned at different times and methods: +-- +-- * @{#SPAWN.Spawn}(): Spawn one new group based on the last spawned index. +-- * @{#SPAWN.ReSpawn}(): Re-spawn a group based on a given index. +-- * @{#SPAWN.SpawnScheduled}(): Spawn groups at scheduled but randomized intervals. You can use @{#SPAWN.SpawnScheduleStart}() and @{#SPAWN.SpawnScheduleStop}() to start and stop the schedule respectively. +-- * @{#SPAWN.SpawnFromVec3}(): Spawn a new group from a Vec3 coordinate. (The group will can be spawned at a point in the air). +-- * @{#SPAWN.SpawnFromVec2}(): Spawn a new group from a Vec2 coordinate. (The group will be spawned at land height ). +-- * @{#SPAWN.SpawnFromStatic}(): Spawn a new group from a structure, taking the position of a @{Static}. +-- * @{#SPAWN.SpawnFromUnit}(): Spawn a new group taking the position of a @{Unit}. +-- * @{#SPAWN.SpawnInZone}(): Spawn a new group in a @{Zone}. +-- +-- Note that @{#SPAWN.Spawn} and @{#SPAWN.ReSpawn} return a @{GROUP#GROUP.New} object, that contains a reference to the DCSGroup object. +-- You can use the @{GROUP} object to do further actions with the DCSGroup. +-- +-- ## Retrieve alive GROUPs spawned by the SPAWN object +-- +-- The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution. +-- Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS. +-- SPAWN provides methods to iterate through that internal GROUP object reference table: +-- +-- * @{#SPAWN.GetFirstAliveGroup}(): Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found. +-- * @{#SPAWN.GetNextAliveGroup}(): Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found. +-- * @{#SPAWN.GetLastAliveGroup}(): Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found. +-- +-- You can use the methods @{#SPAWN.GetFirstAliveGroup}() and sequently @{#SPAWN.GetNextAliveGroup}() to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example. +-- The method @{#SPAWN.GetGroupFromIndex}() will return the GROUP object reference from the given Index, dead or alive... +-- +-- ## Spawned cleaning of inactive groups +-- +-- Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive. +-- In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, +-- and it may occur that no new groups are or can be spawned as limits are reached. +-- To prevent this, a @{#SPAWN.InitCleanUp}() initialization method has been defined that will silently monitor the status of each spawned group. +-- Once a group has a velocity = 0, and has been waiting for a defined interval, that group will be cleaned or removed from run-time. +-- There is a catch however :-) If a damaged group has returned to an airbase within the coalition, that group will not be considered as "lost"... +-- In such a case, when the inactive group is cleaned, a new group will Re-spawned automatically. +-- This models AI that has succesfully returned to their airbase, to restart their combat activities. +-- Check the @{#SPAWN.InitCleanUp}() for further info. +-- +-- ## Catch the @{Group} Spawn Event in a callback function! +-- +-- When using the @{#SPAWN.SpawnScheduled)() method, new @{Group}s are created following the spawn time interval parameters. +-- When a new @{Group} is spawned, you maybe want to execute actions with that group spawned at the spawn event. +-- The SPAWN class supports this functionality through the method @{#SPAWN.OnSpawnGroup}( **function( SpawnedGroup ) end ** ), +-- which takes a function as a parameter that you can define locally. +-- Whenever a new @{Group} is spawned, the given function is called, and the @{Group} that was just spawned, is given as a parameter. +-- As a result, your spawn event handling function requires one parameter to be declared, which will contain the spawned @{Group} object. +-- A coding example is provided at the description of the @{#SPAWN.OnSpawnGroup}( **function( SpawnedGroup ) end ** ) method. +-- +-- @field #SPAWN SPAWN +-- SPAWN = { ClassName = "SPAWN", SpawnTemplatePrefix = nil, @@ -227,6 +285,7 @@ function SPAWN:New( SpawnTemplatePrefix ) self.AIOnOff = true -- The AI is on by default when spawning a group. self.SpawnUnControlled = false self.SpawnInitKeepUnitNames = false -- Overwrite unit names by default with group name. + self.DelayOnOff = true -- An intial delay when spawning the first group. self.SpawnGroups = {} -- Array containing the descriptions of each Group to be Spawned. else @@ -270,6 +329,7 @@ function SPAWN:NewWithAlias( SpawnTemplatePrefix, SpawnAliasPrefix ) self.AIOnOff = true -- The AI is on by default when spawning a group. self.SpawnUnControlled = false self.SpawnInitKeepUnitNames = false -- Overwrite unit names by default with group name. + self.DelayOnOff = true -- An intial delay when spawning the first group. self.SpawnGroups = {} -- Array containing the descriptions of each Group to be Spawned. else @@ -626,6 +686,36 @@ do -- AI methods end -- AI methods +do -- Delay methods + --- Turns the Delay On or Off for the first @{Group} scheduled spawning. + -- The default value is that for scheduled spawning, there is an initial delay when spawning the first @{Group}. + -- @param #SPAWN self + -- @param #boolean DelayOnOff A value of true sets the Delay On, a value of false sets the Delay Off. + -- @return #SPAWN The SPAWN object + function SPAWN:InitDelayOnOff( DelayOnOff ) + + self.DelayOnOff = DelayOnOff + return self + end + + --- Turns the Delay On for the @{Group} when spawning. + -- @param #SPAWN self + -- @return #SPAWN The SPAWN object + function SPAWN:InitDelayOn() + + return self:InitDelayOnOff( true ) + end + + --- Turns the Delay Off for the @{Group} when spawning. + -- @param #SPAWN self + -- @return #SPAWN The SPAWN object + function SPAWN:InitDelayOff() + + return self:InitDelayOnOff( false ) + end + +end -- Delay methods + --- Will spawn a group based on the internal index. -- Note: Uses @{DATABASE} module defined in MOOSE. -- @param #SPAWN self @@ -787,7 +877,11 @@ function SPAWN:SpawnScheduled( SpawnTime, SpawnTimeVariation ) self:F( { SpawnTime, SpawnTimeVariation } ) if SpawnTime ~= nil and SpawnTimeVariation ~= nil then - self.SpawnScheduler = SCHEDULER:New( self, self._Scheduler, {}, 1, SpawnTime, SpawnTimeVariation ) + local InitialDelay = 0 + if self.DelayOnOff == true then + InitialDelay = math.random( SpawnTime - SpawnTime * SpawnTimeVariation, SpawnTime + SpawnTime * SpawnTimeVariation ) + end + self.SpawnScheduler = SCHEDULER:New( self, self._Scheduler, {}, InitialDelay, SpawnTime, SpawnTimeVariation ) end return self diff --git a/docs/Documentation/AI_Patrol.html b/docs/Documentation/AI_Patrol.html index 5cbf8109a..ac871d530 100644 --- a/docs/Documentation/AI_Patrol.html +++ b/docs/Documentation/AI_Patrol.html @@ -931,9 +931,6 @@ Use the method AIPATROLZONE.M - -

This table contains the targets detected during patrol.

-
diff --git a/docs/Documentation/Cargo.html b/docs/Documentation/Cargo.html index 4486dc17a..6ec4d6173 100644 --- a/docs/Documentation/Cargo.html +++ b/docs/Documentation/Cargo.html @@ -2444,7 +2444,6 @@ The UNIT carrying the package.

- AI_CARGO_UNIT.CargoCarrier diff --git a/docs/Documentation/Detection.html b/docs/Documentation/Detection.html index 837979858..e405ef044 100644 --- a/docs/Documentation/Detection.html +++ b/docs/Documentation/Detection.html @@ -2130,7 +2130,6 @@ self

- #number DETECTION_BASE.DetectedItemCount @@ -2258,7 +2257,7 @@ self

- #number + DETECTION_BASE.DetectionInterval diff --git a/docs/Documentation/Fsm.html b/docs/Documentation/Fsm.html index 1b595793d..1096eb06c 100644 --- a/docs/Documentation/Fsm.html +++ b/docs/Documentation/Fsm.html @@ -1580,7 +1580,7 @@ A string defining the start state.

- #string + FSM._StartState @@ -1879,6 +1879,7 @@ A string defining the start state.

+ FSM.current diff --git a/docs/Documentation/MOVEMENT.html b/docs/Documentation/MOVEMENT.html index 0ae0b53f6..ccaa648dc 100644 --- a/docs/Documentation/MOVEMENT.html +++ b/docs/Documentation/MOVEMENT.html @@ -209,7 +209,6 @@ on defined intervals (currently every minute).

- #number MOVEMENT.AliveUnits @@ -218,9 +217,6 @@ on defined intervals (currently every minute).

- -

Contains the counter how many units are currently alive

-
diff --git a/docs/Documentation/Spawn.html b/docs/Documentation/Spawn.html index 31aaa95d3..4eb0349df 100644 --- a/docs/Documentation/Spawn.html +++ b/docs/Documentation/Spawn.html @@ -91,129 +91,27 @@

Module Spawn

-

Single-Player:Yes / Multi-Player:Yes / AI:Yes / Human:No / Types:All --
-Spawn groups of units dynamically in your missions.

+

Functional -- Spawn dynamically new Groups in your missions.

-

Banner Image

+ +

+Banner Image

-

1) #SPAWN class, extends Base#BASE

+

Demo Missions

-

The #SPAWN class allows to spawn dynamically new groups, based on pre-defined initialization settings, modifying the behaviour when groups are spawned.

+

SPAWN Demo Missions source code

- -

For each group to be spawned, within the mission editor, a group has to be created with the "late activation flag" set. We call this group the "Spawn Template" of the SPAWN object. -A reference to this Spawn Template needs to be provided when constructing the SPAWN object, by indicating the name of the group within the mission editor in the constructor methods.

+

SPAWN Demo Missions, only for beta testers

-

Within the SPAWN object, there is an internal index that keeps track of which group from the internal group list was spawned. -When new groups get spawned by using the SPAWN methods (see below), it will be validated whether the Limits (SPAWN.Limit) of the SPAWN object are not reached. -When all is valid, a new group will be created by the spawning methods, and the internal index will be increased with 1.

+

ALL Demo Missions pack of the last release

-

Regarding the name of new spawned groups, a SpawnPrefix will be assigned for each new group created. -If you want to have the Spawn Template name to be used as the SpawnPrefix name, use the SPAWN.New constructor. -However, when the SPAWN.NewWithAlias constructor was used, the Alias name will define the SpawnPrefix name. -Groups will follow the following naming structure when spawned at run-time:

+
-
    -
  1. Spawned groups will have the name SpawnPrefix#ggg, where ggg is a counter from 0 to 999.
    2. -
  2. Spawned units will have the name SpawnPrefix#ggg-uu, where uu is a counter from 0 to 99 for each new spawned unit belonging to the group.
    3. -
+

YouTube Channel

-

Some additional notes that need to be remembered:

- -
    -
  • Templates are actually groups defined within the mission editor, with the flag "Late Activation" set. As such, these groups are never used within the mission, but are used by the #SPAWN module.
    • -
  • It is important to defined BEFORE you spawn new groups, a proper initialization of the SPAWN instance is done with the options you want to use.
    • -
  • When designing a mission, NEVER name groups using a "#" within the name of the group Spawn Template(s), or the SPAWN module logic won't work anymore.
    • -
- -

1.1) SPAWN construction methods

- -

Create a new SPAWN object with the SPAWN.New() or the SPAWN.NewWithAlias() methods:

- -
    -
  • SPAWN.New(): Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition).
    • -
  • SPAWN.NewWithAlias(): Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition), and gives each spawned Group an different name.
    • -
- -

It is important to understand how the SPAWN class works internally. The SPAWN object created will contain internally a list of groups that will be spawned and that are already spawned. -The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons. -So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient.

- -

1.2) SPAWN initialization methods

- -

A spawn object will behave differently based on the usage of initialization methods, which all start with the Init prefix:

- - - -

1.3) SPAWN spawning methods

- -

Groups can be spawned at different times and methods:

- - - -

Note that SPAWN.Spawn and SPAWN.ReSpawn return a GROUP#GROUP.New object, that contains a reference to the DCSGroup object. -You can use the GROUP object to do further actions with the DCSGroup.

- -

1.4) Retrieve alive GROUPs spawned by the SPAWN object

- -

The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution. -Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS. -SPAWN provides methods to iterate through that internal GROUP object reference table:

- -
    -
  • SPAWN.GetFirstAliveGroup(): Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found.
    • -
  • SPAWN.GetNextAliveGroup(): Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found.
    • -
  • SPAWN.GetLastAliveGroup(): Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found.
    • -
- -

You can use the methods SPAWN.GetFirstAliveGroup() and sequently SPAWN.GetNextAliveGroup() to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example. -The method SPAWN.GetGroupFromIndex() will return the GROUP object reference from the given Index, dead or alive...

- -

1.5) SPAWN object cleaning

- -

Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive. -In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, -and it may occur that no new groups are or can be spawned as limits are reached. -To prevent this, a SPAWN.InitCleanUp() initialization method has been defined that will silently monitor the status of each spawned group. -Once a group has a velocity = 0, and has been waiting for a defined interval, that group will be cleaned or removed from run-time. -There is a catch however :-) If a damaged group has returned to an airbase within the coalition, that group will not be considered as "lost"... -In such a case, when the inactive group is cleaned, a new group will Re-spawned automatically. -This models AI that has succesfully returned to their airbase, to restart their combat activities. -Check the SPAWN.InitCleanUp() for further info.

- -

1.6) Catch the Group spawn event in a callback function!

- -

When using the SpawnScheduled method, new Groups are created following the schedule timing parameters. -When a new Group is spawned, you maybe want to execute actions with that group spawned at the spawn event. -To SPAWN class supports this functionality through the SPAWN.OnSpawnGroup( *function( SpawnedGroup ) end * ) method, which takes a function as a parameter that you can define locally. -Whenever a new Group is spawned, the given function is called, and the Group that was just spawned, is given as a parameter. -As a result, your spawn event handling function requires one parameter to be declared, which will contain the spawned Group object. -A coding example is provided at the description of the SPAWN.OnSpawnGroup( *function( SpawnedGroup ) end * ) method.

+

SPAWN YouTube Channel

@@ -228,44 +126,34 @@ A coding example is provided at the description of the SPAWN +

SPAWN class, extends Base#BASE

+

The SPAWN class allows to spawn dynamically new groups.

@@ -318,6 +208,12 @@ A coding example is provided at the description of the SPAWN.CleanUpScheduler + + + + SPAWN.DelayOnOff + + @@ -378,6 +274,24 @@ A coding example is provided at the description of the SPAWN:InitCleanUp(SpawnCleanUpInterval)

CleanUp groups when they are still alive, but inactive.

+ + + + SPAWN:InitDelayOff() + +

Turns the Delay Off for the Group when spawning.

+ + + + SPAWN:InitDelayOn() + +

Turns the Delay On for the Group when spawning.

+ + + + SPAWN:InitDelayOnOff(DelayOnOff) + + @@ -905,6 +819,177 @@ and any spaces before and after the resulting name are removed.

+

SPAWN class, extends Base#BASE

+ +

The SPAWN class allows to spawn dynamically new groups.

+ + +

Each SPAWN object needs to be have a related template group setup in the Mission Editor (ME), +which is a normal group with the Late Activation flag set. +This template group will never be activated in your mission.
+SPAWN uses that template group to reference to all the characteristics +(air, ground, livery, unit composition, formation, skill level etc) of each new group to be spawned.

+ +

Therefore, when creating a SPAWN object, the SPAWN.New and SPAWN.NewWithAlias require +the name of the template group to be given as a string to those constructor methods.

+ +

Initialization settings can be applied on the SPAWN object, +which modify the behaviour or the way groups are spawned. +These initialization methods have the prefix Init. +There are also spawn methods with the prefix Spawn and will spawn new groups in various ways.

+ +

IMPORTANT! The methods with prefix Init must be used before any methods with prefix Spawn method are used, or unexpected results may appear!!!

+ +

Because SPAWN can spawn multiple groups of a template group, +SPAWN has an internal index that keeps track +which was the latest group that was spawned.

+ +

Limits can be set on how many groups can be spawn in each SPAWN object, +using the method SPAWN.InitLimit. SPAWN has 2 kind of limits:

+ +
    +
  • The maximum amount of Units that can be alive at the same time...
    • +
  • The maximum amount of Groups that can be spawned... This is more of a resource-type of limit.
    • +
+ +

When new groups get spawned using the Spawn methods, +it will be evaluated whether any limits have been reached. +When no spawn limit is reached, a new group will be created by the spawning methods, +and the internal index will be increased with 1.

+ +

These limits ensure that your mission does not accidentally get flooded with spawned groups.
+Additionally, it also guarantees that independent of the group composition, +at any time, the most optimal amount of groups are alive in your mission. +For example, if your template group has a group composition of 10 units, and you specify a limit of 100 units alive at the same time, +with unlimited resources = :InitLimit( 100, 0 ) and 10 groups are alive, but two groups have only one unit alive in the group, +then a sequent Spawn(Scheduled) will allow a new group to be spawned!!!

+ +

IMPORTANT!! If a limit has been reached, it is possible that a Spawn method returns nil, meaning, no Group had been spawned!!!

+ +

Spawned groups get the same name as the name of the template group.
+Spawned units in those groups keep by default the same name as the name of the template group.
+However, because multiple groups and units are created from the template group, +a suffix is added to each spawned group and unit.

+ +

Newly spawned groups will get the following naming structure at run-time:

+ +
    +
  1. Spawned groups will have the name _GroupName#nnn_, where GroupName is the name of the template group, + and nnn is a counter from 0 to 999.
    2. +
  2. Spawned units will have the name _GroupName#nnn-uu_, + where uu is a counter from 0 to 99 for each new spawned unit belonging to the group.
    3. +
+ +

That being said, there is a way to keep the same unit names!
+The method SPAWN.InitKeepUnitNames() will keep the same unit names as defined within the template group, thus:

+ +
    +
  1. Spawned units will have the name _UnitName#nnn-uu_, + where UnitName is the unit name as defined in the template group*, + and uu is a **counter from 0 to 99 for each new spawned unit belonging to the group.
    2. +
+ +

Some additional notes that need to be considered!!:

+ +
    +
  • templates are actually groups defined within the mission editor, with the flag "Late Activation" set. + As such, these groups are never used within the mission, but are used by the #SPAWN module.
    • +
  • It is important to defined BEFORE you spawn new groups, + a proper initialization of the SPAWN instance is done with the options you want to use.
    • +
  • When designing a mission, NEVER name groups using a "#" within the name of the group Spawn template(s), + or the SPAWN module logic won't work anymore.
    • +
+ +

SPAWN construction methods

+ +

Create a new SPAWN object with the SPAWN.New() or the SPAWN.NewWithAlias() methods:

+ +
    +
  • SPAWN.New(): Creates a new SPAWN object taking the name of the group that represents the GROUP template (definition).
    • +
  • SPAWN.NewWithAlias(): Creates a new SPAWN object taking the name of the group that represents the GROUP template (definition), and gives each spawned Group an different name.
    • +
+ +

It is important to understand how the SPAWN class works internally. The SPAWN object created will contain internally a list of groups that will be spawned and that are already spawned. +The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons. +So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient.

+ +

SPAWN Initialization methods

+ +

A spawn object will behave differently based on the usage of initialization methods, which all start with the Init prefix:

+ + + +

SPAWN Spawn methods

+ +

Groups can be spawned at different times and methods:

+ + + +

Note that SPAWN.Spawn and SPAWN.ReSpawn return a GROUP#GROUP.New object, that contains a reference to the DCSGroup object. +You can use the GROUP object to do further actions with the DCSGroup.

+ +

Retrieve alive GROUPs spawned by the SPAWN object

+ +

The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution. +Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS. +SPAWN provides methods to iterate through that internal GROUP object reference table:

+ +
    +
  • SPAWN.GetFirstAliveGroup(): Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found.
    • +
  • SPAWN.GetNextAliveGroup(): Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found.
    • +
  • SPAWN.GetLastAliveGroup(): Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found.
    • +
+ +

You can use the methods SPAWN.GetFirstAliveGroup() and sequently SPAWN.GetNextAliveGroup() to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example. +The method SPAWN.GetGroupFromIndex() will return the GROUP object reference from the given Index, dead or alive...

+ +

Spawned cleaning of inactive groups

+ +

Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive. +In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, +and it may occur that no new groups are or can be spawned as limits are reached. +To prevent this, a SPAWN.InitCleanUp() initialization method has been defined that will silently monitor the status of each spawned group. +Once a group has a velocity = 0, and has been waiting for a defined interval, that group will be cleaned or removed from run-time. +There is a catch however :-) If a damaged group has returned to an airbase within the coalition, that group will not be considered as "lost"... +In such a case, when the inactive group is cleaned, a new group will Re-spawned automatically. +This models AI that has succesfully returned to their airbase, to restart their combat activities. +Check the SPAWN.InitCleanUp() for further info.

+ +

Catch the Group Spawn Event in a callback function!

+ +

When using the SPAWN.SpawnScheduleds are created following the spawn time interval parameters. +When a new Group is spawned, you maybe want to execute actions with that group spawned at the spawn event. +The SPAWN class supports this functionality through the method SPAWN.OnSpawnGroup( *function( SpawnedGroup ) end * ), +which takes a function as a parameter that you can define locally. +Whenever a new Group is spawned, the given function is called, and the Group that was just spawned, is given as a parameter. +As a result, your spawn event handling function requires one parameter to be declared, which will contain the spawned Group object. +A coding example is provided at the description of the SPAWN.OnSpawnGroup( *function( SpawnedGroup ) end * ) method.

@@ -975,6 +1060,23 @@ and any spaces before and after the resulting name are removed.

self.CleanUpFunction = routines.scheduleFunction( self._SpawnCleanUpScheduler, { self }, timer.getTime() + 1, SpawnCleanUpInterval )

+ +
+
+
+ + #boolean + +SPAWN.DelayOnOff + +
+
+ + + + +

An intial delay when spawning the first group.

+
@@ -1297,6 +1399,63 @@ self

+ +SPAWN:InitDelayOff() + +
+
+ +

Turns the Delay Off for the Group when spawning.

+ +

Return value

+ +

#SPAWN: +The SPAWN object

+ +
+
+
+
+ + +SPAWN:InitDelayOn() + +
+
+ +

Turns the Delay On for the Group when spawning.

+ +

Return value

+ +

#SPAWN: +The SPAWN object

+ +
+
+
+
+ + +SPAWN:InitDelayOnOff(DelayOnOff) + +
+
+ + + +

Parameter

+
    +
  • + +

    DelayOnOff :

    + +
    • +
+
+
+
+
+ SPAWN:InitKeepUnitNames() diff --git a/docs/Documentation/Zone.html b/docs/Documentation/Zone.html index 10ad3ea38..15c96b3fe 100644 --- a/docs/Documentation/Zone.html +++ b/docs/Documentation/Zone.html @@ -180,7 +180,9 @@ ZONE_BASE +

1) ZONE_BASE class, extends Base#BASE

+

This class is an abstract BASE class for derived classes, and is not meant to be instantiated.

@@ -210,7 +212,9 @@ ZONE_RADIUS +

2) Zone#ZONE_RADIUS class, extends Zone#ZONE_BASE

+

The ZONE_RADIUS class defined by a zone name, a location and a radius.

@@ -238,12 +242,6 @@ ZONE_BASE:BoundZone()

Bound the zone boundaries with a tires.

- - - - ZONE_BASE.ClassName - - @@ -492,12 +490,6 @@ ZONE_RADIUS:BoundZone(Points, UnBound, CountryID)

Bounds the zone with tires.

- - - - ZONE_RADIUS.ClassName - - @@ -665,7 +657,54 @@
+

1) ZONE_BASE class, extends Base#BASE

+

This class is an abstract BASE class for derived classes, and is not meant to be instantiated.

+ + + +

1.1) Each zone has a name:

+ + + +

1.2) Each zone implements two polymorphic functions defined in Zone#ZONE_BASE:

+ + + +

1.3) A zone has a probability factor that can be set to randomize a selection between zones:

+ +
    +
  • ZONE_BASE.SetRandomizeProbability(): Set the randomization probability of a zone to be selected, taking a value between 0 and 1 ( 0 = 0%, 1 = 100% )
    • +
  • ZONE_BASE.GetRandomizeProbability(): Get the randomization probability of a zone to be selected, passing a value between 0 and 1 ( 0 = 0%, 1 = 100% )
    • +
  • ZONE_BASE.GetZoneMaybe(): Get the zone taking into account the randomization probability. nil is returned if this zone is not a candidate.
    • +
+ +

1.4) A zone manages Vectors:

+ + + +

1.5) A zone has a bounding square:

+ + + +

1.6) A zone can be marked:

+ + + +
@@ -757,6 +796,45 @@ This class is an abstract BASE class for derived classes, and is not meant to be
+

2) Zone#ZONE_RADIUS class, extends Zone#ZONE_BASE

+ +

The ZONE_RADIUS class defined by a zone name, a location and a radius.

+ + +

This class implements the inherited functions from Core.Zone#ZONE_BASE taking into account the own zone format and properties.

+ +

2.1) Zone#ZONE_RADIUS constructor

+ + + +

2.2) Manage the radius of the zone

+ + + +

2.3) Manage the location of the zone

+ + + +

2.4) Zone point randomization

+ +

Various functions exist to find random points within the zone.

+ + + +
@@ -817,55 +895,7 @@ The name of the zone as defined within the mission editor.

Type ZONE_BASE

-

1) ZONE_BASE class, extends Base#BASE

- -

This class is an abstract BASE class for derived classes, and is not meant to be instantiated.

- - - -

1.1) Each zone has a name:

- - - -

1.2) Each zone implements two polymorphic functions defined in Zone#ZONE_BASE:

- - - -

1.3) A zone has a probability factor that can be set to randomize a selection between zones:

- -
    -
  • ZONE_BASE.SetRandomizeProbability(): Set the randomization probability of a zone to be selected, taking a value between 0 and 1 ( 0 = 0%, 1 = 100% )
    • -
  • ZONE_BASE.GetRandomizeProbability(): Get the randomization probability of a zone to be selected, passing a value between 0 and 1 ( 0 = 0%, 1 = 100% )
    • -
  • ZONE_BASE.GetZoneMaybe(): Get the zone taking into account the randomization probability. nil is returned if this zone is not a candidate.
    • -
- -

1.4) A zone manages Vectors:

- - - -

1.5) A zone has a bounding square:

- - - -

1.6) A zone can be marked:

- - - -
- +

The ZONE_BASE class

Field(s)

@@ -879,20 +909,6 @@ The name of the zone as defined within the mission editor.

Bound the zone boundaries with a tires.

- -
-
-
- - #string - -ZONE_BASE.ClassName - -
-
- - -
@@ -1713,46 +1729,6 @@ self

Type ZONE_RADIUS

-

2) Zone#ZONE_RADIUS class, extends Zone#ZONE_BASE

- -

The ZONE_RADIUS class defined by a zone name, a location and a radius.

- - -

This class implements the inherited functions from Core.Zone#ZONE_BASE taking into account the own zone format and properties.

- -

2.1) Zone#ZONE_RADIUS constructor

- - - -

2.2) Manage the radius of the zone

- - - -

2.3) Manage the location of the zone

- - - -

2.4) Zone point randomization

- -

Various functions exist to find random points within the zone.

- - - -
-

The ZONE_RADIUS class, defined by a zone name, a location and a radius.

Field(s)

@@ -1792,20 +1768,6 @@ If true the tyres will be destroyed.

#ZONE_RADIUS: self

- -
-
-
- - #string - -ZONE_RADIUS.ClassName - -
-
- - -
diff --git a/docs/Documentation/index.html b/docs/Documentation/index.html index 2badd74ed..5459603f9 100644 --- a/docs/Documentation/index.html +++ b/docs/Documentation/index.html @@ -479,16 +479,7 @@ and creates a CSV file logging the scoring events and results for use at team or Spawn -

Single-Player:Yes / Multi-Player:Yes / AI:Yes / Human:No / Types:All --
-Spawn groups of units dynamically in your missions.

- -

Banner Image

- -
- -

1) #SPAWN class, extends Base#BASE

- -

The #SPAWN class allows to spawn dynamically new groups, based on pre-defined initialization settings, modifying the behaviour when groups are spawned.

+

Functional -- Spawn dynamically new Groups in your missions.