Initial Documentation

.github/workflows/evac.yaml

@@ -12,7 +12,7 @@ jobs:
     name: Test
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ilammy/msvc-dev-cmd@v1
       - uses: leafo/gh-actions-lua@v10
         with:

.github/workflows/mdbook.yaml

@@ -0,0 +1,48 @@
+name: Deploy mdBook site to Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.37
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+      - name: Build with mdBook
+        run: mdbook build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,4 @@
 DCS_header_extracted.lua
 CTLD_*.lua
 CSAR_*.lua
+book

README.md

@@ -18,86 +18,7 @@ The Gremlin Script Tools file provides common features that all Gremlin Scripts
 
 ### evac.lua
 
-The Gremlin Evac script sets up your missions to include evacuation scenarios. Simply call `Evac:setup({})` to get sane defualts, or customize everything by filling out the available options you wish to override.
-
-#### Configuration
-
-```lua
-Evac:setup({
-    beaconBatteryLife = 2,
-    beaconSound = "test.ogg",
-    carryLimits = {
-        ["Test"] = 15,
-    },
-    idStart = 5,
-    loadUnloadPerIndividual = 2,
-    maxExtractable = {
-        Refugees = 12,
-        Infantry = 12,
-        M249 = 12,
-        RPG = 12,
-        StingerIgla = 12,
-        ["2B11"] = 12,
-        JTAC = 3,
-    },
-    spawnWeight = 50,
-    spawnRates = {
-        test = {
-            units = 12,
-            per = 5,
-            period = Gremlin.Periods.Minute,
-        },
-    },
-    startingZones = {
-        { mode = Evac.modes.EVAC, name = "Test 1", smoke = trigger.smokeColors.Green, side = coalition.side.BLUE },
-        { mode = Evac.modes.RELAY, name = "Test 2", smoke = trigger.smokeColors.Orange, side = coalition.side.BLUE },
-        { mode = Evac.modes.SAFE, name = "Test 3", smoke = trigger.smokeColors.White, side = coalition.side.BLUE },
-    },
-})
-```
-
-- `beaconBatteryLife`: How long beacons should broadcast once spawned, in minutes
-  - Default: `30`
-
-- `beaconSound`: The audio file name to play for radio beacons
-  - Default: `beacon.ogg`
-
-- `carryLimits`: Specifies the maximum capacity loadout per aircraft designator
-  - Default: `{ ["C-130"] = 90, ["CH-47D"] = 44, ["CH-43E"] = 55, ["Mi-8MT"] = 24, ["Mi-24P"] = 5, ["Mi-24V"] = 5, ["Mi-26"] = 70, ["SH-60B"] = 5, ["UH-1H"] = 8, ["UH-60A"] = 11 }`
-
-- `idStart`: The lowest ID number that Gremlin Evac will use to create units and groups
-  - Default: `500`
-
-- `loadUnloadPerIndividual`: The amount of time it takes to load/unload a single evacuee onto/from an aircraft, in seconds
-  - Default: `30`
-
-- `maxExtractable`: Provides a cap for automatically generated evacuees, by type; 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
-      - `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
-
-- `startingZones`: Registers zones for evacuation purposes during setup
-  - Default: `{}`
-  - Spec
-    - key: ignored
-    - value: table
-      - `mode`: One of the `Evac.modes` constants, indicating what evacuation mode the zone should be registered using
-      - `name`: Zone name - MUST MATCH THE MISSION EDITOR'S NAME FOR THE ZONE EXACTLY!
-      - `smoke`: Smoke color, taken from `trigger.smokeColors`
-      - `side`: Coalition, taken from `coalition.side`
+The Gremlin Evac script sets up your missions to include evacuation scenarios. Simply call `Evac:setup()` to get sane defualts, or customize everything by filling out the available options you wish to override. [Full documentation is here](https://ilsystems.github.io/GremlinScripts/evac/).
 
 ## Development and Testing
 

book.toml

@@ -0,0 +1,7 @@
+[book]
+authors = ["Hennik Hunsaker"]
+language = "en"
+multilingual = false
+src = "docs"
+title = "Gremlin Scripts (The Docs)"
+description = "Details the usage of the Gremlin Scripts collection in DCS World!"

docs/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+- [Gremlin Script Tools!](./gremlin.md)
+- [Gremlin Evac](./evac.md)
+  - [Setup](./evac/setup.md)
+  - [Usage](./evac/usage.md)
+  - [Functions](./evac/functions.md)
+    - [Zones](./evac/functions/zones.md)
+    - [Units](./evac/functions/units.md)
+    - [Groups](./evac/functions/groups.md)

docs/evac.md

@@ -0,0 +1,10 @@
+# Gremlin Evac
+
+The Gremlin Evac script sets up your missions to include evacuation scenarios. Simply call `Evac:setup()` to get sane defualts, or customize everything by filling out the available options you wish to override.
+
+## Features
+
+- Automatic spawn of evacuees
+- Loading and unloading via in-game menus
+- Manual overrides via config and function calls
+- More coming soon!

docs/evac/functions.md

@@ -0,0 +1,4 @@
+<!-- markdownlint-disable MD041 -->
+## Functions
+
+Gremlin Evac has its functions nested into various tables, rather than living directly under Evac (or worse, the global namespace). These tables include `zones`, `units`, and `groups`. Keep reading to learn more!

docs/evac/functions/groups.md

@@ -0,0 +1,14 @@
+<!-- markdownlint-disable MD041 -->
+### Functions » Groups
+
+#### `Evac.groups.spawn(_side, _numberOrComposition, _country, _zone, _scatterRadius)`
+
+Spawns evacuees manually. `_side` is the Group's `coalition.side`, `_numberOrComposition` follows the same rules as [`Evac.zones.evac.setRemaining()`](./zones.md#sample-composition), `_country` is the `country` for the Group, `_zone` is the Zone name to spawn the evacuees into, and `_scatterRadius` is the distance between spawned Units on the map.
+
+#### `Evac.groups.list(_zone)`
+
+Returns a list of all Groups in a Zone. `_zone` is the name of the Zone to search.
+
+#### `Evac.groups.count(_zone)`
+
+Returns a count of all Groups in a Zone. `_zone` is the name of the Zone to search.

docs/evac/functions/units.md

@@ -0,0 +1,22 @@
+<!-- markdownlint-disable MD041 -->
+### Functions » Units
+
+#### `Evac.units.findEvacuees(_unit)`
+
+Lists the currently-active beacons broadcasting for the Unit's side. `_unit` is the name of the Unit doing the search.
+
+#### `Evac.units.loadEvacuees(_unit)`
+
+Starts the evacuee loading process for a Unit. `_unit` is the name of the Unit to load evacuees onto.
+
+#### `Evac.units.unloadEvacuees(_unit)`
+
+Starts the evacuee unloading process for a Unit. `_unit` is the name of the Unit to unload evacuees from.
+
+#### `Evac.units.countEvacuees(_unit)`
+
+Count the number of evacuees aboard a given Unit. `_unit` is the name of the Unit to count evacuees aboard.
+
+#### `Evac.units.count(_zone)`
+
+Count the number of Units in a given Zone. `_zone` is the name of the Zone to check.

docs/evac/functions/zones.md

@@ -0,0 +1,121 @@
+<!-- markdownlint-disable MD041 -->
+### Functions » Zones
+
+#### `Evac.zones.evac.register(_zone, _smoke, _side)`
+
+Registers an evacuation zone with Gremlin Evac so that it can spawn and track evacuees there.
+
+#### `Evac.zones.relay.register(_zone, _smoke, _side)`
+
+Registers a relay/staging zone with Gremlin Evac so that it can track evacuees there.
+
+#### `Evac.zones.safe.register(_zone, _smoke, _side)`
+
+Registers a safe zone with Gremlin Evac so that it can track evacuees there.
+
+For all three of the above, `_zone` is the name of the zone to register, `_smoke` is the smoke color from `trigger.smokeColor`, and `_side` is taken from `coalition.side`.
+
+---
+
+#### `Evac.zones.evac.activate(_zone)`
+
+Turns on evacuation automations for a given zone.
+
+#### `Evac.zones.relay.activate(_zone)`
+
+Turns on relay/staging automations for a given zone.
+
+#### `Evac.zones.safe.activate(_zone)`
+
+Turns on safe zone automations for a given zone.
+
+For all three of the above, `_zone` is the zone name to activate.
+
+---
+
+#### `Evac.zones.evac.setRemaining(_zone, _side, _country, _numberOrComposition)`
+
+Sets the number of waiting evacuees in the zone.
+
+#### `Evac.zones.relay.setRemaining(_zone, _side, _country, _numberOrComposition)`
+
+Sets the number of waiting evacuees in the zone.
+
+For both of the above, `_zone` is the zone name to activate, `_side` is taken from `coalition.side`, `_country` is taken from the `country` table, and `_numberOrComposition` is (as its name suggests) either a number of evacuees to generate (these will all be of type `"Refugee"`), or a table listing off the composition of the units to spawn (as its name also suggests).
+
+##### Sample Composition
+
+```lua
+Evac.zones.evac.setRemaining('test', coalition.side.BLUE, country.USA, {
+    { type = 'Refugee', unitName = 'Karl Marx', unitId = 42, weight = 75 },
+    { type = 'Infantry' },
+    { type = 'JTAC' },
+    {},
+})
+```
+
+This will add a refugee named Karl Marx, with associated ID and weight values, an infantry unit, a JTAC unit, and a second refugee whose name is automatically generated. Note how none of the parameters are required if you just want a rufugee, though a unit composed entirely of refugees is simpler to build with a number instead of a composition table.
+
+---
+
+#### `Evac.zones.evac.count(_zone)`
+
+Gets an evacuee count for a given evacuation zone.
+
+#### `Evac.zones.relay.count(_zone)`
+
+Gets an evacuee count for a given relay/staging zone.
+
+#### `Evac.zones.safe.count(_zone)`
+
+Gets an evacuee count for a given safe zone.
+
+For all three of the above, `_zone` is the zone name to count evacuees within.
+
+---
+
+#### `Evac.zones.evac.isIn(_unit)`
+
+Gets a flag indicating whether an evacuee is in a given evacuation zone.
+
+#### `Evac.zones.relay.isIn(_unit)`
+
+Gets a flag indicating whether an evacuee is in a given relay/staging zone.
+
+#### `Evac.zones.safe.isIn(_unit)`
+
+Gets a flag indicating whether an evacuee is in a given safe zone.
+
+For all three of the above, `_unit` is the unit name to search for.
+
+---
+
+#### `Evac.zones.evac.deactivate(_zone)`
+
+Turns off evacuation automations for a given zone.
+
+#### `Evac.zones.relay.deactivate(_zone)`
+
+Turns off relay/staging automations for a given zone.
+
+#### `Evac.zones.safe.deactivate(_zone)`
+
+Turns off safe zone automations for a given zone.
+
+For all three of the above, `_zone` is the zone name to deactivate.
+
+---
+
+#### `Evac.zones.evac.unregister(_zone)`
+
+Removes an evacuation zone from Evac's control.
+
+#### `Evac.zones.relay.unregister(_zone)`
+
+Removes a relay/staging zone from Evac's control.
+
+#### `Evac.zones.safe.unregister(_zone)`
+
+Removes a safe zone from Evac's control.
+
+For all three of the above, `_zone` is the zone name to remove.