-----------------------------------------------------------------------------------------------------------------------
------------------ LUA SCRIPTS FOR MISSION CONTROL AND AI IMPLEMENTATION
---------------------- by lovalmidas
------ 2017.03.23
-----------------------------------------------------------------------------------------------------------------------
-- TO DO LIST
-----------------------------------------------------------------------------------------------------------------------

  - Documentation...
    > Yeah...
  
  - Bugs
    > QueuePerFactory = false is not working
      ~ Need to set IsPrimaryBuildings first
    > Units stuck at factories cause problems with AI Teams
      ~ They cause the team to jam up.
      ~ The only way to clear them as of now is to destroy the factory.
      ~ Stuck factories will likely cause memory leaks as well...

  - Known Performance Issues
    > Per tick, currently 15-20ms Tick and 15-25ms Render in the long run.
  
    > Initial setup (especially BaseNode setup) consumes lots of calculations. High likelihood of exceeding Lua quota with enough nodes!
    > HuntingPath()
    > ForceHunt() (still better than HuntingPath()...)
    > BaseProduction() and UnitProduction() (The selection of new stuff to build)
      ~ PREREQUISITE CHECKS, YOU AGAIN
    > The UI Mission Text display (lags Render process)

  - ActorRegistry
    > Find a way to capture FreeActors into the registry.

  - MasterTables
    > All mod-specific controls should be moved to MasterTables
  
  - SetupBase
    > Reorganize BaseNodes
      ~ Maintain the principal BaseNodes table for initialization
      ~ Use ActiveProductionTables.types or some other subtable to store a local BaseNodes table for a particular actor
      ~ Allow switching of primary production building?
      ~ Expose functions to allow amendments on the local BaseNodes table. ( Get, Add, Delete )
  
  - AIProductionGeneral
    > Base production - building placement should check for actors in the region
      ~ Accompanying change: MasterTables to include structure footprint to determine if building can be placed
      ~ Accompanying change: Some way to determine if, and how, the blockage can be cleared
        - Mobile friendlies: Scatter (or smarter way of moving, why scatter to another spot to block them again??)
        - Enemies: Call Deusfence Vult on thy heads!
        - Immobile friendlies: ???
      ~ Accompanying change: Some way of discovering non-actor blockages (Ore)
      ~ Accompanying change: Some way to give AI the ability to skip failing basenodes.
      ~ Ensuring that basenodes are set on proper terrain is still the scripter's responsbility. Impossible now to use Lua API to query the terrain layer

  - AITeams
    > Resolve aircraft jamming helipads and airfields.
    > Reconsider if DefenceEscort should be implemented (it can already be implemented using custom teams)
    > Set up defence calls to allow customization of defenders (amount and some sort of value? 2 infantry won't push a Mammoth back)
    > Split reserved teams to _Ground, _Navy and _Amphibious (and others if needed)
      ~ Apply this on Pool, Hunt and Defence.
    > Better communication between AIGroups and the Defence team, actors in Defence Team should put a hold on AIGroups until all are returned to the AIGroups they were conscripted from.
    
    
  - AIScriptFunctions
    > Ensure existing scripts are working correctly.
        - Test ScriptFn_AttackActor with aircraft again (See dev response on https://github.com/OpenRA/OpenRA/issues/13017)
    > Implement and test the following scripts
        - ScriptFn_LoadInTransport
        - ScriptFn_UnloadAllTransports
        - ScriptFn_Deploy
        - ScriptFn_Infiltrate
        - ScriptFn_Capture
        - ScriptFn_TransferActorsToTeam
    
  - Wishlist
    > AI smart targeting. (E.g Anti-infantry against infantry, change targets if under attack while performing an action)
    > Use AIScriptFunctions to attach script triggers in a way that can harmonize with script functions (and not interrupt them)
      ~ Can be used to recreate unit repair and unit reload functions.

-----------------------------------------------------------------------------------------------------------------------
-- CHANGELOG
-----------------------------------------------------------------------------------------------------------------------

VERSION 1.001 - 2017.03.25.0

  - Bug Fixes
    > AI teams did not implement prerequisite checks correctly, resulting in jamming of production queues.

  - AITeams
    > Implement conditional switch to determine if a team should start activation. (status: 0 -> -1, start grabbing actors from Pool)
    > AI will use its non-reserved Teams for defense if the team is still acquiring actors from the Pool team. 
    > Refactor the tables used for AI team logic. 
      ~ AITeamClone, AIFunctionClone, AIActorGroups, AIGroupToFillStatus, AIGroupStatus merged into AIGroups
    > Allies can now answer defense calls.
      ~ Global boolean value AllyDefendToProtect controls whether allies should answer a defense call.
    > Fixes applied to ForceHunt(), ForceAttack() and ForceGuard()
    > The Hunt team uses a waypoint-independent Hunt script now.
    > Unit ActiveProductionTables now include a linkage to any AITeam/BaseNode calling for production
      ~ This resolves multiple factories duplicating production leading to redundant actors (and actors that are supposed to be used only once - Tanya, won't be duplicated as well)
      ~ This should also resolve multiple ConYards building on the same BaseNode.
      ~ Said factory should also return PendingType if it is somehow cancelled / destroyed.
    > AI teams now capture produced actors immediately upon production.
    > AI teams will now issue a stop command on its actors when executing a new script. This will clear existing actions that somehow did not conclude (e.g. units stuck trying to clear rally points)
    
  - UI Display
    > Introduced missionDisplayTicks to have the (non-debug) UI display refresh every n ticks instead of every tick. (for performance)
    > Included names of types pending addition to an AI team when on 'Populating' status.
    > Included names for script functions for display (AIFunctions[player.Name][groupname][functionnumber].Name)
    > Included a production 'Queue' to types units that AI teams have called for production.
    


VERSION 1.0
  - Root