Applied proper documentation

This commit is contained in:
FlightControl
2016-04-30 07:22:48 +02:00
parent 0990e34fef
commit 6a28902305
11 changed files with 1038 additions and 299 deletions

View File

@@ -1,8 +1,61 @@
--- Administers the Initial Sets of the Mission Templates as defined within the Mission Editor.
-- Administers the Spawning of new Groups within the DCSRTE and administers these new Groups within the DATABASE object(s).
-- Mission designers can use the DATABASE class to build sets of units belonging to certain:
--
-- * coalitions
-- * categories
-- * countries
-- * unit types
-- * starting with certain prefix strings.
--
-- Note that this is an initial filter set. More to follow, like zones etc.
--
--
-- DATABASE construction methods:
-- =================================
-- Create a new DATABASE object with the @{#DATABASE.New} method:
--
-- * @{#DATABASE.New}: Creates a new DATABASE object.
--
--
-- DATABASE filter criteria:
-- =========================
-- You can set filter criteria to define the set of units within the database.
-- Filter criteria are defined by:
--
-- * @{#DATABASE.FilterCoalitions}: Builds the DATABASE with the units belonging to the coalition(s).
-- * @{#DATABASE.FilterCategories}: Builds the DATABASE with the units belonging to the category(ies).
-- * @{#DATABASE.FilterTypes}: Builds the DATABASE with the units belonging to the unit type(s).
-- * @{#DATABASE.FilterCountries}: Builds the DATABASE with the units belonging to the country(ies).
-- * @{#DATABASE.FilterUnitPrefixes}: Builds the DATABASE with the units starting with the same prefix string(s).
--
-- Once the filter criteria have been set for the DATABASE, you can start filtering using:
--
-- * @{#DATABASE.FilterStart}: Starts the filtering of the units within the database.
--
-- Planned filter criteria within development are (so these are not yet available):
--
-- * @{#DATABASE.FilterGroupPrefixes}: Builds the DATABASE with the groups of the units starting with the same prefix string(s).
-- * @{#DATABASE.FilterZones}: Builds the DATABASE with the units within a @{Zone#ZONE}.
--
--
-- DATABASE iterators:
-- ===================
-- Once the filters have been defined and the DATABASE has been built, you can iterate the database with the available iterator methods.
-- The iterator methods will walk the DATABASE set, and call for each element within the set a function that you provide.
-- The following iterator methods are currently available within the DATABASE:
--
-- * @{#DATABASE.ForEachAliveUnit}: Calls a function for each alive unit it finds within the DATABASE.
--
-- Planned iterators methods in development are (so these are not yet available):
--
-- * @{#DATABASE.ForEachUnit}: Calls a function for each unit contained within the DATABASE.
-- * @{#DATABASE.ForEachGroup}: Calls a function for each group contained within the DATABASE.
-- * @{#DATABASE.ForEachUnitInZone}: Calls a function for each unit within a certain zone contained within the DATABASE.
--
-- @module Database
-- @author FlightControl
Include.File( "Routines" )
Include.File( "Base" )
Include.File( "Menu" )
@@ -89,7 +142,7 @@ end
-- @param #DATABASE self
-- @param #string Coalitions Can take the following values: "red", "blue", "neutral".
-- @return #DATABASE self
function DATABASE:FilterCoalition( Coalitions )
function DATABASE:FilterCoalitions( Coalitions )
if not self.Filter.Coalitions then
self.Filter.Coalitions = {}
end
@@ -107,7 +160,7 @@ end
-- @param #DATABASE self
-- @param #string Categories Can take the following values: "plane", "helicopter", "ground", "ship".
-- @return #DATABASE self
function DATABASE:FilterCategory( Categories )
function DATABASE:FilterCategories( Categories )
if not self.Filter.Categories then
self.Filter.Categories = {}
end
@@ -125,7 +178,7 @@ end
-- @param #DATABASE self
-- @param #string Types Can take those type strings known within DCS world.
-- @return #DATABASE self
function DATABASE:FilterType( Types )
function DATABASE:FilterTypes( Types )
if not self.Filter.Types then
self.Filter.Types = {}
end
@@ -161,7 +214,7 @@ end
-- @param #DATABASE self
-- @param #string Prefixes The prefix of which the unit name starts with.
-- @return #DATABASE self
function DATABASE:FilterUnitPrefix( Prefixes )
function DATABASE:FilterUnitPrefixes( Prefixes )
if not self.Filter.UnitPrefixes then
self.Filter.UnitPrefixes = {}
end
@@ -179,7 +232,7 @@ end
-- @param #DATABASE self
-- @param #string Prefixes The prefix of which the group name where the unit belongs to starts with.
-- @return #DATABASE self
function DATABASE:FilterGroupPrefix( Prefixes )
function DATABASE:FilterGroupPrefixes( Prefixes )
if not self.Filter.GroupPrefixes then
self.Filter.GroupPrefixes = {}
end
@@ -204,10 +257,10 @@ function DATABASE:FilterStart()
for UnitRegistrationID, UnitRegistration in pairs( _DATABASE.Units ) do
self:T( UnitRegistration )
local DCSUnit = Unit.getByName( UnitRegistration.UnitName )
if self:IsIncludeDCSUnit( DCSUnit ) then
if self:_IsIncludeDCSUnit( DCSUnit ) then
self.DCSUnits[DCSUnit:getName()] = DCSUnit
end
if self:IsAliveDCSUnit( DCSUnit ) then
if self:_IsAliveDCSUnit( DCSUnit ) then
self.DCSUnitsAlive[DCSUnit:getName()] = DCSUnit
end
end
@@ -218,155 +271,6 @@ function DATABASE:FilterStart()
return self
end
---
-- @param #DATABASE self
-- @param DCSUnit#Unit DCSUnit
-- @return #DATABASE self
function DATABASE:IsIncludeDCSUnit( DCSUnit )
self:F( DCSUnit )
local DCSUnitInclude = true
if self.Filter.Coalitions then
local DCSUnitCoalition = false
for CoalitionID, CoalitionName in pairs( self.Filter.Coalitions ) do
self:T( { "Coalition:", DCSUnit:getCoalition(), self.FilterMeta.Coalitions[CoalitionName], CoalitionName } )
if self.FilterMeta.Coalitions[CoalitionName] and self.FilterMeta.Coalitions[CoalitionName] == DCSUnit:getCoalition() then
DCSUnitCoalition = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCoalition
end
if self.Filter.Categories then
local DCSUnitCategory = false
for CategoryID, CategoryName in pairs( self.Filter.Categories ) do
self:T( { "Category:", DCSUnit:getDesc().category, self.FilterMeta.Categories[CategoryName], CategoryName } )
if self.FilterMeta.Categories[CategoryName] and self.FilterMeta.Categories[CategoryName] == DCSUnit:getDesc().category then
DCSUnitCategory = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCategory
end
if self.Filter.Types then
local DCSUnitType = false
for TypeID, TypeName in pairs( self.Filter.Types ) do
self:T( { "Type:", DCSUnit:getTypeName(), TypeName } )
if TypeName == DCSUnit:getTypeName() then
DCSUnitType = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitType
end
if self.Filter.Countries then
local DCSUnitCountry = false
for CountryID, CountryName in pairs( self.Filter.Countries ) do
self:T( { "Country:", DCSUnit:getCountry(), CountryName } )
if country.id[CountryName] == DCSUnit:getCountry() then
DCSUnitCountry = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCountry
end
if self.Filter.UnitPrefixes then
local DCSUnitPrefix = false
for UnitPrefixId, UnitPrefix in pairs( self.Filter.UnitPrefixes ) do
self:T( { "Unit Prefix:", string.find( DCSUnit:getName(), UnitPrefix, 1 ), UnitPrefix } )
if string.find( DCSUnit:getName(), UnitPrefix, 1 ) then
DCSUnitPrefix = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitPrefix
end
self:T( DCSUnitInclude )
return DCSUnitInclude
end
---
-- @param #DATABASE self
-- @param DCSUnit#Unit DCSUnit
-- @return #DATABASE self
function DATABASE:IsAliveDCSUnit( DCSUnit )
self:F( DCSUnit )
local DCSUnitAlive = false
if DCSUnit and DCSUnit:isExist() and DCSUnit:isActive() then
if self.DCSUnits[DCSUnit:getName()] then
DCSUnitAlive = true
end
end
self:T( DCSUnitAlive )
return DCSUnitAlive
end
function DATABASE:ScanEnvironment()
self:F()
self.Navpoints = {}
self.Units = {}
--Build routines.db.units and self.Navpoints
for coa_name, coa_data in pairs(env.mission.coalition) do
if (coa_name == 'red' or coa_name == 'blue') and type(coa_data) == 'table' then
--self.Units[coa_name] = {}
----------------------------------------------
-- build nav points DB
self.Navpoints[coa_name] = {}
if coa_data.nav_points then --navpoints
for nav_ind, nav_data in pairs(coa_data.nav_points) do
if type(nav_data) == 'table' then
self.Navpoints[coa_name][nav_ind] = routines.utils.deepCopy(nav_data)
self.Navpoints[coa_name][nav_ind]['name'] = nav_data.callsignStr -- name is a little bit more self-explanatory.
self.Navpoints[coa_name][nav_ind]['point'] = {} -- point is used by SSE, support it.
self.Navpoints[coa_name][nav_ind]['point']['x'] = nav_data.x
self.Navpoints[coa_name][nav_ind]['point']['y'] = 0
self.Navpoints[coa_name][nav_ind]['point']['z'] = nav_data.y
end
end
end
-------------------------------------------------
if coa_data.country then --there is a country table
for cntry_id, cntry_data in pairs(coa_data.country) do
local countryName = string.lower(cntry_data.name)
--self.Units[coa_name][countryName] = {}
--self.Units[coa_name][countryName]["countryId"] = cntry_data.id
if type(cntry_data) == 'table' then --just making sure
for obj_type_name, obj_type_data in pairs(cntry_data) do
if obj_type_name == "helicopter" or obj_type_name == "ship" or obj_type_name == "plane" or obj_type_name == "vehicle" or obj_type_name == "static" then --should be an unncessary check
local category = obj_type_name
if ((type(obj_type_data) == 'table') and obj_type_data.group and (type(obj_type_data.group) == 'table') and (#obj_type_data.group > 0)) then --there's a group!
--self.Units[coa_name][countryName][category] = {}
for group_num, GroupTemplate in pairs(obj_type_data.group) do
if GroupTemplate and GroupTemplate.units and type(GroupTemplate.units) == 'table' then --making sure again- this is a valid group
self:_RegisterGroup( GroupTemplate )
end --if GroupTemplate and GroupTemplate.units then
end --for group_num, GroupTemplate in pairs(obj_type_data.group) do
end --if ((type(obj_type_data) == 'table') and obj_type_data.group and (type(obj_type_data.group) == 'table') and (#obj_type_data.group > 0)) then
end --if obj_type_name == "helicopter" or obj_type_name == "ship" or obj_type_name == "plane" or obj_type_name == "vehicle" or obj_type_name == "static" then
end --for obj_type_name, obj_type_data in pairs(cntry_data) do
end --if type(cntry_data) == 'table' then
end --for cntry_id, cntry_data in pairs(coa_data.country) do
end --if coa_data.country then --there is a country table
end --if coa_name == 'red' or coa_name == 'blue' and type(coa_data) == 'table' then
end --for coa_name, coa_data in pairs(mission.coalition) do
return self
end
--- Instantiate new Groups within the DCSRTE.
-- This method expects EXACTLY the same structure as a structure within the ME, and needs 2 additional fields defined:
@@ -461,7 +365,7 @@ function DATABASE:_EventOnBirth( Event )
self:F( { Event } )
if Event.IniDCSUnit then
if self:IsIncludeDCSUnit( Event.IniDCSUnit ) then
if self:_IsIncludeDCSUnit( Event.IniDCSUnit ) then
self.DCSUnits[Event.IniDCSUnitName] = Event.IniDCSUnit
self.DCSUnitsAlive[Event.IniDCSUnitName] = Event.IniDCSUnit
end
@@ -490,64 +394,189 @@ function DATABASE:ForEachAliveUnit( IteratorFunction, ... )
self:F( arg )
local function CoRoutine()
local Count = 0
for DCSUnitID, DCSUnit in pairs( self.DCSUnitsAlive ) do
self:T2( DCSUnit )
IteratorFunction( DCSUnit, unpack( arg ) )
coroutine.yield()
Count = Count + 1
if Count % 10 == 0 then
coroutine.yield( false )
end
end
return true
end
local co = coroutine.create( CoRoutine )
while true do
local function Schedule()
local status, res = coroutine.resume( co )
self:T2( { status, res } )
self:T( { status, res } )
if status == false then
error( res )
end
if res == true then
break
if res == false then
timer.scheduleFunction( Schedule, {}, timer.getTime() + 0.001 )
end
end
timer.scheduleFunction( Schedule, {}, timer.getTime() + 1 )
return self
end
--- Interate the DATABASE and call an interator function for each unit, providing the UNIT and optional parameters.
-- @param #DATABASE self
-- @param #function IteratorFunction The function that will be called when there is an alive unit in the database. The function needs to accept a UNIT parameter.
-- @return #DATABASE self
function DATABASE:ForEachAliveUnit( IteratorFunction, ... )
self:F( arg )
local function CoRoutine()
for DCSUnitID, DCSUnit in pairs( self.DCSUnits ) do
self:T2( DCSUnit )
IteratorFunction( DCSUnit, unpack( arg ) )
coroutine.yield()
end
return true
end
local co = coroutine.create( CoRoutine )
while true do
local status, res = coroutine.resume( co )
self:T2( { status, res } )
if status == false then
error( res )
end
if res == true then
break
end
end
function DATABASE:ScanEnvironment()
self:F()
self.Navpoints = {}
self.Units = {}
--Build routines.db.units and self.Navpoints
for coa_name, coa_data in pairs(env.mission.coalition) do
if (coa_name == 'red' or coa_name == 'blue') and type(coa_data) == 'table' then
--self.Units[coa_name] = {}
----------------------------------------------
-- build nav points DB
self.Navpoints[coa_name] = {}
if coa_data.nav_points then --navpoints
for nav_ind, nav_data in pairs(coa_data.nav_points) do
if type(nav_data) == 'table' then
self.Navpoints[coa_name][nav_ind] = routines.utils.deepCopy(nav_data)
self.Navpoints[coa_name][nav_ind]['name'] = nav_data.callsignStr -- name is a little bit more self-explanatory.
self.Navpoints[coa_name][nav_ind]['point'] = {} -- point is used by SSE, support it.
self.Navpoints[coa_name][nav_ind]['point']['x'] = nav_data.x
self.Navpoints[coa_name][nav_ind]['point']['y'] = 0
self.Navpoints[coa_name][nav_ind]['point']['z'] = nav_data.y
end
end
end
-------------------------------------------------
if coa_data.country then --there is a country table
for cntry_id, cntry_data in pairs(coa_data.country) do
local countryName = string.lower(cntry_data.name)
--self.Units[coa_name][countryName] = {}
--self.Units[coa_name][countryName]["countryId"] = cntry_data.id
if type(cntry_data) == 'table' then --just making sure
for obj_type_name, obj_type_data in pairs(cntry_data) do
if obj_type_name == "helicopter" or obj_type_name == "ship" or obj_type_name == "plane" or obj_type_name == "vehicle" or obj_type_name == "static" then --should be an unncessary check
local category = obj_type_name
if ((type(obj_type_data) == 'table') and obj_type_data.group and (type(obj_type_data.group) == 'table') and (#obj_type_data.group > 0)) then --there's a group!
--self.Units[coa_name][countryName][category] = {}
for group_num, GroupTemplate in pairs(obj_type_data.group) do
if GroupTemplate and GroupTemplate.units and type(GroupTemplate.units) == 'table' then --making sure again- this is a valid group
self:_RegisterGroup( GroupTemplate )
end --if GroupTemplate and GroupTemplate.units then
end --for group_num, GroupTemplate in pairs(obj_type_data.group) do
end --if ((type(obj_type_data) == 'table') and obj_type_data.group and (type(obj_type_data.group) == 'table') and (#obj_type_data.group > 0)) then
end --if obj_type_name == "helicopter" or obj_type_name == "ship" or obj_type_name == "plane" or obj_type_name == "vehicle" or obj_type_name == "static" then
end --for obj_type_name, obj_type_data in pairs(cntry_data) do
end --if type(cntry_data) == 'table' then
end --for cntry_id, cntry_data in pairs(coa_data.country) do
end --if coa_data.country then --there is a country table
end --if coa_name == 'red' or coa_name == 'blue' and type(coa_data) == 'table' then
end --for coa_name, coa_data in pairs(mission.coalition) do
return self
end
---
-- @param #DATABASE self
-- @param DCSUnit#Unit DCSUnit
-- @return #DATABASE self
function DATABASE:_IsIncludeDCSUnit( DCSUnit )
self:F( DCSUnit )
local DCSUnitInclude = true
if self.Filter.Coalitions then
local DCSUnitCoalition = false
for CoalitionID, CoalitionName in pairs( self.Filter.Coalitions ) do
self:T( { "Coalition:", DCSUnit:getCoalition(), self.FilterMeta.Coalitions[CoalitionName], CoalitionName } )
if self.FilterMeta.Coalitions[CoalitionName] and self.FilterMeta.Coalitions[CoalitionName] == DCSUnit:getCoalition() then
DCSUnitCoalition = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCoalition
end
if self.Filter.Categories then
local DCSUnitCategory = false
for CategoryID, CategoryName in pairs( self.Filter.Categories ) do
self:T( { "Category:", DCSUnit:getDesc().category, self.FilterMeta.Categories[CategoryName], CategoryName } )
if self.FilterMeta.Categories[CategoryName] and self.FilterMeta.Categories[CategoryName] == DCSUnit:getDesc().category then
DCSUnitCategory = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCategory
end
if self.Filter.Types then
local DCSUnitType = false
for TypeID, TypeName in pairs( self.Filter.Types ) do
self:T( { "Type:", DCSUnit:getTypeName(), TypeName } )
if TypeName == DCSUnit:getTypeName() then
DCSUnitType = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitType
end
if self.Filter.Countries then
local DCSUnitCountry = false
for CountryID, CountryName in pairs( self.Filter.Countries ) do
self:T( { "Country:", DCSUnit:getCountry(), CountryName } )
if country.id[CountryName] == DCSUnit:getCountry() then
DCSUnitCountry = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitCountry
end
if self.Filter.UnitPrefixes then
local DCSUnitPrefix = false
for UnitPrefixId, UnitPrefix in pairs( self.Filter.UnitPrefixes ) do
self:T( { "Unit Prefix:", string.find( DCSUnit:getName(), UnitPrefix, 1 ), UnitPrefix } )
if string.find( DCSUnit:getName(), UnitPrefix, 1 ) then
DCSUnitPrefix = true
end
end
DCSUnitInclude = DCSUnitInclude and DCSUnitPrefix
end
self:T( DCSUnitInclude )
return DCSUnitInclude
end
---
-- @param #DATABASE self
-- @param DCSUnit#Unit DCSUnit
-- @return #DATABASE self
function DATABASE:_IsAliveDCSUnit( DCSUnit )
self:F( DCSUnit )
local DCSUnitAlive = false
if DCSUnit and DCSUnit:isExist() and DCSUnit:isActive() then
if self.DCSUnits[DCSUnit:getName()] then
DCSUnitAlive = true
end
end
self:T( DCSUnitAlive )
return DCSUnitAlive
end
--- Traces the current database contents in the log ... (for debug reasons).
-- @param #DATABASE self
-- @return #DATABASE self