Develop (#16)

* Initial Methods for SpearheadAPI * Added Spearhead API * Added Spearhead API * fixed compile for api * Added notes for API in beta * Added notes for API in beta * Added Menu to all doc pages * Added Menu to all doc pages * added it for real * added it for real * fixed develop * fixed develop * fixed develop * wip * wip * updated * work in progress * work in progress * added empty docs page * wip * removed SAR files from persistence branch * Added Blue Sams as seperate class * added initial persistance * added initial persistance * added initial persistance * added initial persistance * added initial persistance * added menu to persistence markdown * added menu to persistence markdown * added menu to persistence markdown * docs update * wip * wip * Refactor of Stage classes. * wip * wip * wip * reworked bluesam and stagebase * Added waiting stage functionality * updated docs * wip * wip * wip * updated * wip * wip * wip * refactored without issues, needs testing --------- Co-authored-by: Dutchie <54616262+dutchie032@users.noreply.github.com> Co-authored-by: dutchie032 <dutchie032> Co-authored-by: ex61wi <tim.rorije@ing.com>
2025-04-22 14:39:22 +02:00
parent 9c6a5ed217
commit ff392e0e7e
37 changed files with 4494 additions and 1732 deletions
@@ -0,0 +1,77 @@
+# Spearhead Persistence
+
+> **_NOTE:_** Persistence is only released in the Beta branch at the moment.
+
+Spearhead comes with a custom Persistence option. <br/>
+It will even save burned out vehicles to give players a consistent battlefield even after the restart. <br/>
+
+Most is pretty straight forward, however, some zones are somewhat special. <br/>
+Underneath you'll see all special zones listed.
+
+## Settings
+
+To see the full config check: [Reference](./Reference.html#Configuration)
+
+## Feedback
+
+Since this feature is still very much in development, please let any issues know as soon as possible and as consice as possible so a fix can be made quickly. 
+
+Currently implemented is local file storage. <br/>
+If enough interest is expressed cloud based persistence would be possible. <br/>
+
+
+```lua
+... Rest of config
+   Persistence = {
+        --- io and lfs cannot be sanitized in the MissionScripting.lua
+        
+        --- enables or disables the persistence logic in spearhead
+        enabled = false,
+
+        --- sets the directory where the persistence file is stored
+        --- if nil then lfs.writedir() will be used. 
+        --- which will 
+        directory = nil ,
+
+        --- the filename of the persistence file. Should end with .json for convention, but any text extension should do.
+        fileName = "Spearhead_Persistence.json"
+    }
+... Rest of config
+
+```
+
+
+
+## Basic behavior
+
+While playing the mission Spearhead is keeping track of all units killed. <br/>
+These units are stored in memory internally and written to file. <br/>
+This happens every 2 minutes AND during "onMissionStop" event to make sure the mission is as up to date as possible without having to call IO methods on each event.<br/>
+
+## Misc units
+
+Miscelaneous units will follow basic behaviour. <br/>
+These are units that are part of a stage, but are not in a mission or airbase. <br/>
+These units will be replaced by a static "DEAD" unit after a mission restart at the location it was killed. <br/>
+Due to blue units spawning afterwards it's generally best to not have these units move through or over areas where BLUESAMS and Airbase units will spawn after a stage completion.
+
+## Missions
+
+Missions follow the same logic as Misc Units. <br/>
+
+## Blue SAMs
+
+For Blue SAMs, due to placements easily overlapping between red and blue units within a BLUESAM trigger zone red units that overlap with blue units will be deleted. 
+<br/>
+This will ensure that the blue units are placed as needed. <br/>
+
+
+## Airbases
+
+Airbase units will also be checked for overlap. As the blue units will be spawned after the RED unit. <br/>
+Units that were alive when the stage was completed will be removed. Units that died will have corpses spawned. <br/>
+
+## Warehouses
+
+Currently warehouses are not implemented and therefore warehouses are not persisted. <br/>
+When supply missions and logistics get implemented warehouses will be persisted as well. <br/>
@@ -19,51 +19,6 @@ If you however want to go right to the Get Started guide click here: [here](./Ge
 You can always come back later here. <br/>
 The Get Started guide will not show all details and reasoning. <br/>

-## Release Notes
-
-<details>
-<summary>01-10-2024 Initial Version </summary> 
-The initial version with basic functionality
-</details>
-
-## Feature / TODO list
-
- [ ] CAP Manager
-    - [x] RTB flow. Flying out before primary flies back. 
-    - [ ] Out of Missile flow 
- [ ] Stage
-    - [ ] Pre Activate
-      - [x] All SAM Sites
-      - [x] All Red airbase units
-      - [ ] OCA Missions
-    - [ ] Activate
-      - [ ] Activate all DEAD sites. (No surprise pop ups)
-      - [ ] Activate other random mission till 10 max
-    - [ ] Completion Logic
-      - [ ] ?? Custom Conditions ??
-      - [ ] ?? Airbases as final mission ??
-      - [ ] Required Mission types
- [ ] Missions
-  - [x] BAI
-  - [x] DEAD
-  - [x] STRIKE
-  - [ ] INTERCEPT
-  - [ ] LOGISTIC
-  - [ ] EXTRACTION | MEDEVAC
-  - [ ] More?
-
- [ ] Warehouses
-  - [ ] Logistics [OPTIONAL]
-  - [ ] 
-
- [ ] Team creation
- [ ] Airbases
- [ ] Farps 
- [ ] Carrier/Fleet routes
-    - [ ] Fleet tracks
- [ ] Persistance
-
-
 ## Configuration

 Spearhead will always try to be as configurable as possible. <br/>
@@ -77,6 +32,14 @@ Overwrite the values in your own script (before spearhead runs) or <a download="
  ##!config!##
 ```

+## The Spearhead API
+
+> **_NOTE:_** The Spearhead.API space is only release in the Beta branch at the moment.
+
+You can not only use Spearhead, but you can also interact with it via your own scripts.  
+
+See all the reference, explanation here: [SpearheadAPI](./SpearheadApi.html)
+
 ## All Trigger zone name options: 

 <details> 
@@ -84,6 +47,21 @@ Overwrite the values in your own script (before spearhead runs) or <a download="
  A mission stage that encapsulates multiple missions, airbases and other objects.
 </details> 

+<details> 
+  <summary>WAITINGSTAGE_</summary>
+  A stage that functions as a logic delay or timer. <br/>
+  With this you can add a wait before or in between stages. 
+
+  Naming Convention: `WAITINGSTAGE_<order>_<amount of seconds>`
+  Example: `WAITINGSTAGE_2_180`
+
+  A waiting stage can be part of the same stage order as other stages. <br/>
+  This will first activate the DELAYSTAGE and only when the DELAYSTAGE is completed will the other stages be activated. <br/>
+  This is so you can easily add delays later in your mission development, without havint to rename all subsequent stages. 
+
+</details> 
+
+
 <details> 
  <summary>MISSION_</summary>
 </details> 
@@ -106,8 +84,6 @@ Overwrite the values in your own script (before spearhead runs) or <a download="
 A stage is a logical part of a mission. It's isn't anything special per se, but everything revolves around stages in Spearhead. <br/>
 Everything is tied to at a stage. <br/>

-
-
 ## Mission

 A mission is a completable objective with a state and a continuous check to see if itself is completed. <br/>
@@ -0,0 +1,37 @@
+
+# Spearhead.API
+
+> **_NOTE:_** The Spearhead.API space is only release in the Beta branch at the moment.
+
+the `Spearhead.API` space is specifically created to make sure mission makers can interact with the framework. 
+
+Simply alter logic, get the current state in Spearhead, and give the whole ME more control. 
+
+eg. Late activate the entire framework by calling `Spearhead.API.Stages.changeStage(1)` later or on demand and setting the starting config stage to -1 in the Spearhead configuration file
+
+
+## Stages
+
+```lua
+
+---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
+Spearhead.API.Stages.changeStage = function(stageNumber) 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
+Spearhead.API.Stages.getCurrentStage = function() end
+
+
+---returns whether a stage (by index) is complete. 
+---@param stageNumber number
+---@return boolean | nil
+---@return string 
+Spearhead.API.Stages.isStageComplete = function(stageNumber) end
+
+```
+
@@ -0,0 +1,38 @@
+
+<div id="menu">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">
+    <div style="position:fixed; 
+        left:80%; 
+        top:80%;
+        height:15%;
+        width:15%;
+        padding:10px;
+        background-color: #00053B;
+        border-radius: 8px;">
+        <div style="margin-bottom: 8px;">
+            <a href="/Spearhead/Reference.html" style="color: white; font-size: 18px; ">
+                <i class="bi bi-file-earmark-richtext"></i>
+                &ensp;Reference
+            </a>
+        </div>
+        <div style="margin-bottom: 8px;">
+            <a href="/Spearhead/GetStarted.html" style="color: white; font-size: 18px;">
+                <i class="bi bi-rocket-takeoff"></i>
+                &ensp;Get Started 
+            </a>
+        </div>
+        <div style="margin-bottom: 8px;">
+            <a href="/Spearhead/Persistence.html" style="color: white; font-size: 18px;">
+                <i class="bi bi-database-check"></i>
+                &ensp;Persistence 
+            </a>
+        </div>
+        <div style="margin-bottom: 8px;">
+            <a href="/Spearhead/SpearheadApi.html" style="color: white; font-size: 18px;">
+                <i class="bi bi-gear"></i>
+                &ensp;API 
+            </a>
+        </div>
+    </div>
+</div>
+