Expand trigger support in Evac

.github/workflows/gremlin.yaml

@@ -1,4 +1,4 @@
-name: 'Gremlin Script Tools'
+name: 'Gremlin'
 
 on:
   push:

README.md

@@ -6,15 +6,15 @@ This is the Gremlin Scripts repo! Everything you need to succeed with DCS missio
 
 Simply copy the contents of the `src` directory to your `Missions` folder in `Saved Games`. If you like, you can also grab MiST from this project's `lib` folder, though it's usually best to grab the latest version [directly from GitHub](https://github.com/mrSkortch/MissionScriptingTools). **NOTE THAT MiST WILL BE REMOVED FROM THIS REPO SOON, AS WE ARE MOVING AWAY FROM IT!**
 
-Once you have the files in place, add a trigger to load MiST (follow its documentation for the best ways to do this), a second to load Gremlin Script Tools, and then a third to load the exact script you wish to use, such as Gremlin Evac. Once all three are loaded, the final step is to fully set up the script(s) to do their thing - see the relevant Configuration section in the docs for more on this.
+Once you have the files in place, add a trigger to load MiST (follow its documentation for the best ways to do this), a second to load Gremlin, and then a third to load the exact script you wish to use, such as Gremlin Evac. Once all three are loaded, the final step is to fully set up the script(s) to do their thing - see the relevant Configuration section in the docs for more on this.
 
 And that's it! The scripts are installed and working from this point on.
 
 ## Components
 
 ### gremlin.lua
 
-The Gremlin Script Tools file provides common features that all Gremlin Scripts use to do their thing. It must be loaded after MiST, and before any other Gremlin Scripts components. [Full documentation is here](https://ilsystems.github.io/GremlinScripts/gremlin.html).
+The Gremlin file provides common features that all Gremlin Scripts use to do their thing. It must be loaded after MiST, and before any other Gremlin Scripts components. [Full documentation is here](https://ilsystems.github.io/GremlinScripts/gremlin.html).
 
 ### evac.lua
 

docs/SUMMARY.md

@@ -3,7 +3,7 @@
 
 [Introduction](./intro.md)
 
-# Gremlin Script Tools
+# Gremlin (Core)
 
 - [About](./gremlin.md)
   - [Setup](./gremlin/setup.md)

docs/api/gremlin.ldoc

@@ -1,8 +1,8 @@
 file = '../../src/gremlin.lua'
-project = 'Gremlin Script Tools'
-title = 'Gremlin Script Tools'
+project = 'Gremlin'
+title = 'Gremlin'
 package = '../../src'
-description = 'Documenting Gremlin Script Tools'
+description = 'Documenting Gremlin'
 template = true
 template_escape = '>'
 dir = '.'

docs/evac.md

@@ -8,4 +8,5 @@ The Gremlin Evac script sets up your missions to include evacuation scenarios. S
 - Loading and unloading via in-game menus
 - Manual overrides via config and function calls
 - Automatic loss for any side that loses too many evacuees
+- Automatic win for any side that rescues enough evacuees
 - More coming soon!

docs/evac/setup.md

@@ -5,57 +5,78 @@
 
 ```lua,editable
 Evac:setup({
-    beaconBatteryLife = 2,
-    beaconSound = "test.ogg",
+    adminPilotNames = { 'Walter White' },
+    beaconBatteryLife = 30,
+    beaconSound = 'beacon.ogg',
     carryLimits = {
-        ["SH60B"] = 15,
+        ['C-130'] = 90,
+        ['CH-43E'] = 55,
+        ['CH-47D'] = 44,
+        ['Hercules'] = 90,
+        ['Mi-8MT'] = 24,
+        ['Mi-24P'] = 5,
+        ['Mi-24V'] = 5,
+        ['Mi-26'] = 70,
+        ['SH-60B'] = 5,
+        ['SH60B'] = 5,
+        ['UH-1H'] = 8,
+        ['UH-60L'] = 11,
     },
-    idStart = 5,
-    loadUnloadPerIndividual = 2,
-    lossFlags = { 1, 2 }
-    lossThresholds = { 0, 25 },
+    idStart = 50000,
+    loadUnloadPerIndividual = 30,
+    lossFlags = { 'GremlinEvacRedLoss', 'GremlinEvacBlueLoss' },
+    lossThresholds = { 25, 25 },
     maxExtractable = {
-        {
-            ['Carrier Seaman'] = 12,
-            Infantry = 12,
-            M249 = 12,
-            RPG = 12,
-            StingerIgla = 12,
-            ["2B11"] = 12,
-            JTAC = 3,
-        },
-        {
-            ['Carrier Seaman'] = 12,
-            Infantry = 12,
-            M249 = 12,
-            RPG = 12,
-            StingerIgla = 12,
-            ["2B11"] = 12,
-            JTAC = 3,
+        _global = {
+            Generic = { 0, 0, [0] = 0 },
+            Infantry = { 0, 0, [0] = 0 },
+            M249 = { 0, 0, [0] = 0 },
+            RPG = { 0, 0, [0] = 0 },
+            StingerIgla = { 0, 0, [0] = 0 },
+            ['2B11'] = { 0, 0, [0] = 0 },
+            JTAC = { 0, 0, [0] = 0 },
         },
     },
-    spawnWeight = 50,
     spawnRates = {
-        ["Test 1"] = {
-            nil,
+        _global = {
+            {
+                side = coalition.side.NEUTRAL,
+                units = 0,
+                startTrigger = { type = 'time', value = 0 },
+                spawnTrigger = { type = 'time', value = 0 },
+                endTrigger = { type = 'limits', value = 100 },
+            },
             {
-                units = 12,
-                per = 5,
-                period = Gremlin.Periods.Minute,
+                side = coalition.side.RED,
+                units = 0,
+                startTrigger = { type = 'time', value = 0 },
+                spawnTrigger = { type = 'time', value = 0 },
+                endTrigger = { type = 'limits', value = 100 },
+            },
+            {
+                side = coalition.side.BLUE,
+                units = 0,
+                startTrigger = { type = 'time', value = 0 },
+                spawnTrigger = { type = 'time', value = 0 },
+                endTrigger = { type = 'limits', value = 100 },
             },
         },
     },
+    spawnWeight = 100,
     startingUnits = { 'helicargo1', 'helicargo2', 'MedEvac1', 'MedEvac2', 'MedEvac3' },
     startingZones = {
-        { mode = Evac.modes.EVAC, name = "Test 1", smoke = trigger.smokeColor.Green, side = coalition.side.BLUE, active = true },
+        { mode = Evac.modes.EVAC,  name = "Test 1", smoke = trigger.smokeColor.Green,  side = coalition.side.BLUE, active = true },
         { mode = Evac.modes.RELAY, name = "Test 2", smoke = trigger.smokeColor.Orange, side = coalition.side.BLUE, active = true },
-        { mode = Evac.modes.SAFE, name = "Test 3", smoke = trigger.smokeColor.White, side = coalition.side.BLUE },
+        { mode = Evac.modes.SAFE,  name = "Test 3", smoke = trigger.smokeColor.White,  side = coalition.side.BLUE },
     },
-    winFlags = { 3, 4 }
-    winThresholds = { 0, 75 },
+    winFlags = { 'GremlinEvacRedWin', 'GremlinEvacBlueWin' },
+    winThresholds = { 75, 75 },
 })
 ```
 
+- `adminPilotNames`: Pilots to consider admins, with bonus menu items available.
+  - Default: `{}`
+
 - `beaconBatteryLife`: How long beacons should broadcast once spawned, in minutes
   - Default: `30`
 
@@ -77,25 +98,33 @@ Evac:setup({
 - `lossThresholds`: The maximum percentage of evacuees that can be lost from any side
   - Default: `{ 25, 25 }`
 
-- `maxExtractable`: Provides a cap for automatically generated evacuees, by type; the script won't create more than allowed here
+- `maxExtractable`: Provides a cap for automatically generated evacuees, by zone/type/side; the script won't create more than allowed here
   - Default: `0` for everything
 
-- `spawnWeight`: The average weight of an evacuee - the exact weight used will vary between 90% and 120% of this value
-  - Default: `100`
-
 - `spawnRates`: Describes how and when to spawn evacuee units/groups
   - Default: `{ _global = { units = 0, per = 0, period = Gremlin.Periods.Second } }` (everything at mission start)
   - Spec
     - key: Zone name
     - value: table
-      - key: Side ID
+      - key: index
       - value: table
+        - `side`: The side ID for spawning
         - `units`: Number or composition of units to spawn
-        - `per`: Number of periods to wait between spawns
-          - `0`: At setup time, no repeat
-          - `< 0`: After `math.abs(per)` periods, no repeat
-          - `> 0`: Every `per` periods, until `maxExtractable` is reached
-        - `period`: One of the `Gremlin.Periods` constants indicating how long a single period lasts
+        - `startTrigger`: Trigger to start spawning
+        - `spawnTrigger`: Trigger to actually spawn units
+        - `endTrigger`: Trigger to stop spawning
+  - Notes:
+    - Triggers:
+      - `{ type = 'time', value = 900 }`: seconds since mission start
+      - `{ type = 'time', value = { after = 15, period = Gremlin.Periods.Minute } }`: another way to say time since mission start
+      - `{ type = 'repeat', value = { per = 5, period = Gremlin.Periods.Minute } }`: every `per` `period`s
+      - `{ type = 'flag', value = 7 }`: flag goes truthy
+      - `{ type = 'event', value = { id = 'Evac:Spawn', filter = function(event) return true end } }`: event triggered
+      - `{ type = 'menu', value = 'Spawn Bonus Evacuees' }`: menu item selected
+      - `{ type = 'limits', value = 50 }`: `value`% of allowed evacuees spawned
+
+- `spawnWeight`: The average weight of an evacuee - the exact weight used will vary between 90% and 120% of this value
+  - Default: `100`
 
 - `startingUnits`: Registers units for evacuation purposes during setup
   - Default: `{}`

docs/evac/usage.md

@@ -36,33 +36,27 @@ Evac:setup({
     lossFlags = { 1, 2 },
     lossThresholds = { 0, 25 },
     maxExtractable = {
-        {
-            ['Carrier Seaman'] = 12,
-            Infantry = 12,
-            M249 = 12,
-            RPG = 12,
-            StingerIgla = 12,
-            ["2B11"] = 12,
-            JTAC = 3,
-        },
-        {
-            ['Carrier Seaman'] = 12,
-            Infantry = 12,
-            M249 = 12,
-            RPG = 12,
-            StingerIgla = 12,
-            ["2B11"] = 12,
-            JTAC = 3,
+        _global = {
+            {
+                Generic = { 12, 12, [0] = 0 },
+                Infantry = { 12, 12, [0] = 0 },
+                M249 = { 12, 12, [0] = 0 },
+                RPG = { 12, 12, [0] = 0 },
+                StingerIgla = { 12, 12, [0] = 0 },
+                ["2B11"] = { 12, 12, [0] = 0 },
+                JTAC = { 3, 3, [0] = 0 },
+            },
         },
     },
     spawnWeight = 50,
     spawnRates = {
         ["Test 1"] = {
-            nil,
             {
+                side = coalition.side.BLUE,
                 units = 12,
-                per = 5,
-                period = Gremlin.Periods.Minute,
+                startTrigger = { type = 'time', value = 0 },
+                spawnTrigger = { type = 'repeat', value = { per = 5, period = Gremlin.Periods.Minute } },
+                endTrigger = { type = 'limits', value = 100 },
             },
         },
     },
@@ -82,7 +76,7 @@ Initializes Gremlin Evac, overriding all the defaults:
 - any beacons are killed after 2 minutes (default is 30)
 - the beacon sound file is changed to something mission specific
 - the list of craft that can perform evac ops is reset to just the `SH60B` Unit type at a max loadout of 15 evacuees
-- the starting ID is dropped from 500 to 5
+- the starting ID is dropped from 50000 to 5
 - the time it takes to load or unload evacuees is set to 2 seconds per evacuee (down from 30 seconds)
 - the flags used to indicate evacuation mission failure are set to 1 and 2, respectively (default is `GremlinEvacRedLoss` and `GremlinEvacBlueLoss`)
 - the percentage of evacuees that can be lost is set to 0 for red, and 25 for blue (default is 25 for both)

docs/gremlin.md

@@ -1,5 +1,5 @@
-# Gremlin Script Tools
+# Gremlin (Core)
 
-Welcome to the Gremlin Script Tools documentation! We're still building most of this out, so there will be some rough edges, but hopefully you'll be up and running in no time with whichever Gremlin Scripts you end up using in your own missions!
+Welcome to the Gremlin documentation! We're still building most of this out, so there will be some rough edges, but hopefully you'll be up and running in no time with whichever Gremlin Scripts you end up using in your own missions!
 
-Gremlin Script Tools is a framework for building these scripts around, so it doesn't do much on its own. Still, in case it proves useful for your own scripts, we've documented it anyway. Enjoy!
+Gremlin is a framework for building these scripts around, so it doesn't do much on its own. Still, in case it proves useful for your own scripts, we've documented it anyway. Enjoy!

docs/gremlin/functions.md

@@ -3,4 +3,4 @@
 
 ### `Gremlin:setup(config)`
 
-Sets up Gremlin Scripting Tools. Docs for this are in [the setup section](./setup.md).
+Sets up Gremlin. Docs for this are in [the setup section](./setup.md).

docs/gremlin/functions/utils.md

@@ -1,6 +1,12 @@
 <!-- markdownlint-disable MD041 -->
 ### Utils
 
+#### `Gremlin.utils.checkTrigger(_trigger, _type, _extra)`
+
+Checks a trigger definition against a type and optional extra data - returns true when any conditions are met
+
+---
+
 #### `Gremlin.utils.countTableEntries(_tbl)`
 
 Counts the number of entries in a table, regardless of type
@@ -13,6 +19,36 @@ Looks up a list of all the zones a unit is currently in
 
 ---
 
+#### `Gremlin.utils.innerSquash(_tbl, _idx)`
+
+Flatten a table by one level, by removing the second level:
+
+```lua
+Gremlin.utils.innerSquash({
+    walnut = { 'redWalnut', 'blueWalnut', [0] = 'noWalnut' },
+    pecan = { 'redPecan', 'bluePecan', [0] = 'noPecan' },
+    almond = { 'redAlmond', 'blueAlmond', [0] = 'noAlmond' },
+}, coalition.side.BLUE)
+```
+
+would become
+
+```lua
+{
+    walnut = 'blueWalnut',
+    pecan = 'bluePecan',
+    almond = 'blueAlmond',
+}
+```
+
+---
+
+#### `Gremlin.utils.inspect(_value, _depth)`
+
+Converts a Lua value to a string for display or logging. It tries to make the string valid Lua, but there are a few types we can't reconstruct. Leave the second argument off if calling this directly!
+
+---
+
 #### `Gremlin.utils.isInTable(_tbl, _needle)`
 
 Checks whether `_needle` is in the haystack `_tbl`

docs/gremlin/setup.md

@@ -5,7 +5,7 @@ First, you need to add MiST to your mission. Follow [its instructions](https://g
 
 Next, copy the contents of Gremlin Scripts' `src/` directory to your missions folder. Include `gremlin.lua` as a DoScriptFile action, immediately followed by the specific Gremlin Scripts you wish to use in your mission.
 
-Finally, run a single line of code to set everything up. Note that the Gremlin Scripts will set up Gremlin Script Tools automatically, so unless you're building your own scripts on this framework, **you don't need to do this step in your own missions.**
+Finally, run a single line of code to set everything up. Note that the Gremlin Scripts will set up Gremlin automatically, so unless you're building your own scripts on this framework, **you don't need to do this step in your own missions.**
 
 ```lua,editable
 Gremlin:setup()

docs/gremlin/usage.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD041 -->
 ## Usage
 
-Gremlin Script Tools is an abstraction framework built on MiST. It doesn't do much on its own, yet, but we're working on adding more! Here's how to use what's already working:
+Gremlin is an abstraction framework that makes working with DCS in scripts much simpler. It doesn't do much on its own, yet, but we're working on adding more! Here's how to use some of what's already working:
 
 ```lua,editable
 Gremlin:setup()

mocks/DCS.lua

@@ -1886,5 +1886,6 @@ trigger.action.outTextForGroup = Mock()
 trigger.action.outTextForUnit = Mock()
 trigger.action.radioTransmission = Mock()
 trigger.action.setUnitInternalCargo = Mock()
+trigger.action.getUserFlag = Mock()
 trigger.action.setUserFlag = Mock()
 trigger.action.stopRadioTransmission = Mock()