Spearhead API updates (#31)

Co-authored-by: dutchie032 <dutchie032>

.github/workflows/static_pages.yml

@@ -103,6 +103,19 @@ jobs:
           find _docs -type f -name "*.html" -exec sed -i "s/#{BETA_VERSION}#/${{ steps.latest_beta.outputs.tag }}/g" {} \;
           find _docs -type f -name "*.html" -exec sed -i "s/#{BETA_VERSION_DATE}#/${{ steps.latest_beta.outputs.date }}/g" {} \;
 
+      - name: Install Python and Pygments
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install pygments
+
+      - name: Highlight API code and update HTML
+        run: |
+          pygmentize -f html -l lua -O noclasses,style=monokai classes/api/SpearheadApiDoc.lua > _docs/pages/temp_api_code.html
+          # Insert the highlighted code into the placeholder in spearheadapi.html
+          sed -i "/#\{API_CODE\}#/r _docs/pages/temp_api_code.html" _docs/pages/spearheadapi.html
+          sed -i "/#\{API_CODE\}#/d" _docs/pages/spearheadapi.html
+          rm _docs/pages/temp_api_code.html
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifact

_docs/pages/spearheadapi.html

@@ -66,24 +66,7 @@
 
                 <h2 id="stages">Stages</h2>
                 <pre>
-<span class="lua-comment">---Changes the active stage of spearhead.
+                    #{API_CODE}#
---- All other stages will change based on the normal logic. (CAP, BLUE etc.)
----@param stageNumber number the stage number you want changed
----@return boolean success indicator of success
----@return string message error message</span>
-<span class="lua-variable">Spearhead.API.Stages</span>.<span class="lua-function">changeStage</span> <span class="lua-operator">=</span> <span class="lua-keyword">function</span>(<span class="lua-variable">stageNumber</span>) <span class="lua-keyword">end</span>
-
-<span class="lua-comment">---Returns the current stange number
----Returns nil when the stagenumber was not set and spearhead is not started.
----@return number | nil</span>
-<span class="lua-variable">Spearhead.API.Stages</span>.<span class="lua-function">getCurrentStage</span> <span class="lua-operator">=</span> <span class="lua-keyword">function</span>() <span class="lua-keyword">end</span>
-
-
-<span class="lua-comment">---returns whether a stage (by index) is complete. 
----@param stageNumber number
----@return boolean | nil
----@return string</span> 
-<span class="lua-variable">Spearhead.API.Stages</span>.<span class="lua-function">isStageComplete</span> <span class="lua-operator">=</span> <span class="lua-keyword">function</span>(<span class="lua-variable">stageNumber</span>) <span class="lua-keyword">end</span>
                 </pre>
             </div>
         </div>

classes/api/SpearheadApi.lua

@@ -1,55 +1,56 @@
+---@type Array<OnMissionCompleteListener>
+local MissionCompleteListeners = {}
 
+---@type SpearheadAPI
+local SpearheadAPI = {
+    Stages = {
+        changeStage = function(stageNumber)
+            if type(stageNumber) ~= "number" then
+                return false, "stageNumber " .. stageNumber .. " is not a valid number"
+            end
 
+            Spearhead.Events.PublishStageNumberChanged(stageNumber)
+            return true, ""
+        end,
+        getCurrentStage = function()
+            return Spearhead.StageNumber or nil
+        end,
+        isStageComplete = function(stageNumber)
+            if type(stageNumber) ~= "number" then
+                return false, "stageNumber " .. stageNumber .. " is not a valid number"
+            end
 
+            local isComplete = Spearhead.internal.GlobalStageManager.isStageComplete(stageNumber)
+            if isComplete == nil then
+                return nil, "no stage found with number " .. stageNumber
+            end
 
-
+            return isComplete, ""
-local SpearheadAPI = {}
-do
-
-    SpearheadAPI.Stages = {}
-
-    --- Changes the active stage of spearhead.
-    --- All other stages will change based on the normal logic. (CAP, BLUE etc.)
-    --- @param stageNumber number the stage number you want changed
-    --- @return boolean success indicator of success
-    --- @return string message error message
-    SpearheadAPI.Stages.changeStage = function(stageNumber) 
-        if type(stageNumber) ~= "number" then
-            return false, "stageNumber " .. stageNumber .. " is not a valid number"
         end
+    },
+    Missions = {
+        addOnMissionCompleteListener = function(listener)
+            if type(listener) ~= "table" or type(listener.onMissionComplete) ~= "function" then
+                error("listener is not a valid OnMissionCompleteListener")
+            end
 
-        Spearhead.Events.PublishStageNumberChanged(stageNumber)
+            table.insert(MissionCompleteListeners, listener)
-        return true, ""
-    end
-
-    ---Returns the current stange number
-    ---Returns nil when the stagenumber was not set before ever, which means Spearhead was not started.
-    ---@return number | nil
-    SpearheadAPI.Stages.getCurrentStage = function()
-        return Spearhead.StageNumber or nil
-    end
-
-    ---returns whether a stage (by index) is complete. 
-    ---@param stageNumber number
-    ---@return boolean | nil
-    ---@return string 
-    SpearheadAPI.isStageComplete = function(stageNumber)
-        if type(stageNumber) ~= "number" then
-            return false, "stageNumber " .. stageNumber .. " is not a valid number"
         end
+    },
 
-        local isComplete = Spearhead.internal.GlobalStageManager.isStageComplete(stageNumber)
+    --- Internal Functions for the API that can be called through the rest of the Framework
-        if isComplete == nil then
+    Internal = {
-            return nil, "no stage found with number " .. stageNumber
+        notifyMissionComplete = function(zone_name)
-        end
+            for _, listener in ipairs(MissionCompleteListeners) do
+                    pcall(function()
+                        listener:onMissionComplete(zone_name)
+                    end)
+            end
+        end,
+    }
 
-        return isComplete, ""
-    end
-
-end
 
+}
 
 if Spearhead == nil then Spearhead = {} end
 Spearhead.API = SpearheadAPI
-
-

classes/api/SpearheadApiDoc.lua

@@ -0,0 +1,17 @@
+---@class SpearheadAPI
+---@field Stages SpearheadStagesAPI
+---@field Missions MissionAPI
+SpearheadAPI = SpearheadAPI
+
+---@class SpearheadStagesAPI
+---@field changeStage fun(stageNumber: number): boolean, string @Changes the active stage of spearhead. <br/> All other stages will change based on the normal logic. (CAP, BLUE etc.)
+---@field getCurrentStage fun(): number | nil @Returns the current stange number <br/> Returns nil when the stagenumber was not set before ever, which means Spearhead was not started.
+---@field isStageComplete fun(stageNumber: number): boolean | nil, string @returns whether a stage (by index) is complete. <br/> @param stageNumber number <br/> @return boolean | nil <br/> @return string
+
+---@class OnMissionCompleteListener
+---@field onMissionComplete fun(self: OnMissionCompleteListener, zone_name: string) @Called when a mission is completed. @return void
+
+---@class MissionAPI 
+---@field addOnMissionCompleteListener fun(listener: OnMissionCompleteListener) @Adds a listener to the mission. <br/> @param listener OnMissionCompleteListener <br/> @return void
+
+

classes/stageClasses/Groups/SpearheadGroup.lua

@@ -3,8 +3,8 @@
 
 ---@class SpearheadGroup : OnUnitLostListener
 ---@field groupName string
----@field private isStatic boolean
+---@field private _isStatic boolean
----@field private isSpawned boolean
+---@field private _isSpawned boolean
 local SpearheadGroup = {}
 
 function SpearheadGroup.New(groupName)
@@ -14,38 +14,38 @@ function SpearheadGroup.New(groupName)
     local o = {}
     local self = setmetatable(o, SpearheadGroup)
 
-    self.isStatic = Spearhead.DcsUtil.IsGroupStatic(groupName) == true
+    self._isStatic = Spearhead.DcsUtil.IsGroupStatic(groupName) == true
     self.groupName = groupName
-    self.isSpawned = false
+    self._isSpawned = false
 
     return self
 end
 
 function SpearheadGroup:SpawnCorpsesOnly()
 
-    if self.isSpawned == true then return end
+    if self._isSpawned == true then return end
 
     local group = Spearhead.DcsUtil.SpawnGroupTemplate(self.groupName)
     if group then
         for _, unit in pairs(group:getUnits()) do
             local deathState = Spearhead.classes.persistence.Persistence.UnitDeadState(unit:getName())
-
+            Spearhead.DcsUtil.DestroyUnit(self.groupName, unit:getName())
             if deathState and deathState.isDead == true then
-                Spearhead.DcsUtil.DestroyUnit(self.groupName, unit:getName())
                 Spearhead.DcsUtil.SpawnCorpse(deathState.country_id, unit:getName(), deathState.type, deathState.pos, deathState.heading)
             end
         end
     end
 
-    self.isSpawned = true
+    self._isSpawned = true
 
 end
 
-function SpearheadGroup:Spawn()
+---@param lateStart boolean?
+function SpearheadGroup:Spawn(lateStart)
 
-    if self.isSpawned == true then return end
+    if self._isSpawned == true then return end
 
-    local spawned, isStatic = Spearhead.DcsUtil.SpawnGroupTemplate(self.groupName)
+    local spawned, isStatic = Spearhead.DcsUtil.SpawnGroupTemplate(self.groupName, nil, nil, lateStart)
     if spawned and isStatic == false then
         for _, unit in pairs(spawned:getUnits()) do
             local deathState = Spearhead.classes.persistence.Persistence.UnitDeadState(unit:getName())
@@ -67,18 +67,36 @@ function SpearheadGroup:Spawn()
         Spearhead.LoggerTemplate.new("SPEARHEADGROUP", "ERROR"):error("Failed to spawn group: " .. self.groupName)
     end
 
-    self.isSpawned = true
+    self._isSpawned = true
+end
+
+function SpearheadGroup:Activate()
+    
+    if self._isStatic == true then return end
+
+    local group = Group.getByName(self.groupName)
+    if group then 
+        group:activate()
+        
+        local controller = group:getController()
+        if controller then
+            controller:setCommand({
+                id = 'Start',
+                params = {}
+            })
+        end
+    end
 end
 
 function SpearheadGroup:Destroy()
-    self.isSpawned = false
+    self._isSpawned = false
     Spearhead.DcsUtil.DestroyGroup(self.groupName)
 end
 
 ---comment
 ---@return integer
 function SpearheadGroup:GetCoalition()
-    if self.isStatic == true then
+    if self._isStatic == true then
         local object = StaticObject.getByName(self.groupName)
         if object == nil then
             return 0
@@ -108,7 +126,7 @@ end
 function SpearheadGroup:GetUnits()
 
     local result = {}
-    if self.isStatic == true then
+    if self._isStatic == true then
         local staticObject = StaticObject.getByName(self.groupName)
         if staticObject then 
             table.insert(result, staticObject)

classes/stageClasses/missions/ZoneMission.lua

@@ -289,7 +289,7 @@ end
 
 function ZoneMission:SpawnPersistedState()
     for _, group in pairs(self._missionGroups.groups) do
-        group:SpawnCorpsesOnly()
+        group:Spawn()
     end
 end
 

classes/stageClasses/missions/baseMissions/Mission.lua

@@ -113,6 +113,11 @@ function Mission:NotifyMissionComplete()
             listener:OnMissionComplete(self)
         end)
     end
+
+    pcall(function()
+        Spearhead.API.Internal.notifyMissionComplete(self.zoneName)
+    end)
+
 end
 
 ---endregion