MOOSE/Moose Development/Moose/Functional/ZoneGoalCoalition.lua

--- **Functional (WIP)** -- Base class that models processes to achieve goals involving a Zone for a Coalition.
--
-- ===
-- 
-- ZONE_GOAL_COALITION models processes that have a Goal with a defined achievement involving a Zone for a Coalition.  
-- Derived classes implement the ways how the achievements can be realized.
-- 
-- ===
-- 
-- ### Author: **FlightControl**
-- 
-- ===
-- 
-- @module Functional.ZoneGoalCoalition
-- @image MOOSE.JPG

do -- ZoneGoal

  --- @type ZONE_GOAL_COALITION
  -- @field #string ClassName Name of the Class.
  -- @field #number Coalition The current coalition ID of the zone owner.
  -- @field #table UnitCategories Table of unit categories that are able to capture and hold the zone. Default is only GROUND units.
  -- @field #table ObjectCategories Table of object categories that are able to hold a zone. Default is UNITS and STATICS.
  -- @extends Functional.ZoneGoal#ZONE_GOAL


  --- ZONE_GOAL_COALITION models processes that have a Goal with a defined achievement involving a Zone for a Coalition.  
  -- Derived classes implement the ways how the achievements can be realized.
  -- 
  -- ## 1. ZONE_GOAL_COALITION constructor
  --   
  --   * @{#ZONE_GOAL_COALITION.New}(): Creates a new ZONE_GOAL_COALITION object.
  -- 
  -- ## 2. ZONE_GOAL_COALITION is a finite state machine (FSM).
  -- 
  -- ### 2.1 ZONE_GOAL_COALITION States
  -- 
  -- ### 2.2 ZONE_GOAL_COALITION Events
  -- 
  -- ### 2.3 ZONE_GOAL_COALITION State Machine
  -- 
  -- @field #ZONE_GOAL_COALITION
  ZONE_GOAL_COALITION = {
    ClassName        = "ZONE_GOAL_COALITION",
    Coalition        = nil,
    UnitCategories   = nil,
    ObjectCategories = nil,
  }
  
  --- @field #table ZONE_GOAL_COALITION.States
  ZONE_GOAL_COALITION.States = {}
  
  --- ZONE_GOAL_COALITION Constructor.
  -- @param #ZONE_GOAL_COALITION self
  -- @param Core.Zone#ZONE Zone A @{Zone} object with the goal to be achieved.
  -- @param DCSCoalition.DCSCoalition#coalition Coalition The initial coalition owning the zone. Default coalition.side.NEUTRAL.
  -- @param #table UnitCategories Table of unit categories. See [DCS Class Unit](https://wiki.hoggitworld.com/view/DCS_Class_Unit). Default {Unit.Category.GROUND_UNIT}.
  -- @return #ZONE_GOAL_COALITION
  function ZONE_GOAL_COALITION:New( Zone, Coalition, UnitCategories )
  
    if not Zone then
      BASE:E("ERROR: No Zone specified in ZONE_GOAL_COALITON!")
      return nil
    end
      
    -- Inherit ZONE_GOAL.
    local self = BASE:Inherit( self, ZONE_GOAL:New( Zone ) ) -- #ZONE_GOAL_COALITION
    self:F( { Zone = Zone, Coalition  = Coalition  } )

    -- Set initial owner.
    self:SetCoalition( Coalition or coalition.side.NEUTRAL)
    
    -- Set default unit and object categories for the zone scan.
    self:SetUnitCategories(UnitCategories)
    self:SetObjectCategories()
        
    return self
  end
  

  --- Set the owning coalition of the zone.
  -- @param #ZONE_GOAL_COALITION self
  -- @param DCSCoalition.DCSCoalition#coalition Coalition The coalition ID, e.g. *coalition.side.RED*.
  -- @return #ZONE_GOAL_COALITION
  function ZONE_GOAL_COALITION:SetCoalition( Coalition )
    self.Coalition = Coalition
    return self
  end

  --- Set the owning coalition of the zone.
  -- @param #ZONE_GOAL_COALITION self
  -- @param #table UnitCategories Table of unit categories. See [DCS Class Unit](https://wiki.hoggitworld.com/view/DCS_Class_Unit). Default {Unit.Category.GROUND_UNIT}.
  -- @return #ZONE_GOAL_COALITION
  function ZONE_GOAL_COALITION:SetUnitCategories( UnitCategories )
  
    if UnitCategories and type(UnitCategories)~="table" then
      UnitCategories={UnitCategories}
    end
    
    self.UnitCategories=UnitCategories or {Unit.Category.GROUND_UNIT}
    
    return self
  end
  
  --- Set the owning coalition of the zone.
  -- @param #ZONE_GOAL_COALITION self
  -- @param #table ObjectCategories Table of unit categories. See [DCS Class Object](https://wiki.hoggitworld.com/view/DCS_Class_Object). Default {Object.Category.UNIT, Object.Category.STATIC}, i.e. all UNITS and STATICS.
  -- @return #ZONE_GOAL_COALITION
  function ZONE_GOAL_COALITION:SetObjectCategories( ObjectCategories )
  
    if ObjectCategories and type(ObjectCategories)~="table" then
      ObjectCategories={ObjectCategories}
    end
    
    self.ObjectCategories=ObjectCategories or {Object.Category.UNIT, Object.Category.STATIC}
    
    return self
  end 
  
  --- Get the owning coalition of the zone.
  -- @param #ZONE_GOAL_COALITION self
  -- @return DCSCoalition.DCSCoalition#coalition Coalition.
  function ZONE_GOAL_COALITION:GetCoalition()
    return self.Coalition
  end

  
  --- Get the owning coalition name of the zone.
  -- @param #ZONE_GOAL_COALITION self
  -- @return #string Coalition name.
  function ZONE_GOAL_COALITION:GetCoalitionName()
  
    if self.Coalition == coalition.side.BLUE then
      return "Blue"
    end
    
    if self.Coalition == coalition.side.RED then
      return "Red"
    end
    
    if self.Coalition == coalition.side.NEUTRAL then
      return "Neutral"
    end
    
    return "Unknown"
  end


  --- Check status Coalition ownership.
  -- @param #ZONE_GOAL_COALITION self
  -- @return #ZONE_GOAL_COALITION
  function ZONE_GOAL_COALITION:StatusZone()
  
    local State = self:GetState()
    self:F( { State = self:GetState() } )
  
    -- Debug text.
    local text=string.format("Zone state=%s, Owner=%s, Scanning...", State, self:GetCoalitionName())
    env.info(text)
    
    self:Scan( self.ObjectCategories, self.UnitCategories )
  
    return self
  end
  
end