diff --git a/arma/server/addons/task/README.md b/arma/server/addons/task/README.md index be4e43a..be57885 100644 --- a/arma/server/addons/task/README.md +++ b/arma/server/addons/task/README.md @@ -128,6 +128,10 @@ Eden task modules are the normal designer-facing path. Place the module, configure its attributes, and sync it to the relevant entities or grouping modules. +For a mission-designer-focused step-by-step setup guide, see: + +- `docs/TASK_USAGE_GUIDE.md` + Available task modules: - `FORGE_Module_Attack`: sync directly to target units or vehicles - `FORGE_Module_Destroy`: sync directly to objects, vehicles, or units diff --git a/docs/TASK_USAGE_GUIDE.md b/docs/TASK_USAGE_GUIDE.md index 0639dbb..ccff4f0 100644 --- a/docs/TASK_USAGE_GUIDE.md +++ b/docs/TASK_USAGE_GUIDE.md @@ -203,6 +203,245 @@ Available task modules: These modules delegate to `forge_server_task_fnc_startTask`. +## Mission Designer Guide + +This section is the practical Eden setup guide for mission designers. + +### General Rules + +Use these rules for every Forge task: + +1. Give every task a unique `TaskID`. +2. Use area markers for zone-style fields such as: + - `DefenseZone` + - `DeliveryZone` + - `ExtZone` + - `CBRNZone` +3. Prefer `RECTANGLE` or `ELLIPSE` markers with real size. +4. Set success and fail limits explicitly instead of relying on defaults. +5. If a task uses a timer, the countdown now waits until the task is assigned. +6. Grouping modules such as `Explosive Entities`, `Protected Entities`, + `Cargo`, `Hostages`, and `Shooters` should be synced to real world objects, + not other logic modules. + +### Attack Task + +Use `FORGE_Module_Attack` when players need to eliminate hostile units or +vehicles. + +Setup: + +1. Place the enemy units or vehicles. +2. Place `FORGE_Module_Attack`. +3. Set `TaskID`. +4. Set `LimitSuccess` to the number of targets that must be killed. +5. Set `LimitFail` if you want a fail threshold. +6. Set rewards, rating, and optional `TimeLimit`. +7. Sync the attack module directly to the target units or vehicles. + +Notes: + +- This module reads its synced entities directly. +- `TimeLimit` uses seconds. `0` means no limit. + +### Destroy Task + +Use `FORGE_Module_Destroy` when players must destroy objects, vehicles, or +units. + +Setup: + +1. Place the objects, vehicles, or units that must be destroyed. +2. Place `FORGE_Module_Destroy`. +3. Set `TaskID`. +4. Set `LimitSuccess` to the number of targets that must be destroyed. +5. Set `LimitFail` if the mission should fail after too many losses. +6. Set rewards, rating, and optional `TimeLimit`. +7. Sync the destroy module directly to the targets. + +Notes: + +- This module reads its synced entities directly. +- `TimeLimit` uses seconds. `0` means no limit. + +### Defuse Task + +Use `FORGE_Module_Defuse` when players must defuse one or more explosives while +protecting other entities. + +Required module layout: + +```text +[Defuse Task] --> [Explosive Entities] --> explosive objects +[Defuse Task] --> [Protected Entities] --> protected objects/vehicles/units +``` + +Setup: + +1. Place the explosive objects that players must defuse. +2. Place `FORGE_Module_Explosives`. +3. Sync each explosive object to `FORGE_Module_Explosives`. +4. Place the objects, vehicles, or units that must survive. +5. Place `FORGE_Module_Protected`. +6. Sync each protected entity to `FORGE_Module_Protected`. +7. Place `FORGE_Module_Defuse`. +8. Set `TaskID`. +9. Set `LimitSuccess` to the number of explosives that must be defused. +10. Set `LimitFail` to the number of protected entities that can be lost before failure. +11. Set `TimeLimit` to the IED countdown in seconds. This is per-IED countdown behavior, not a global mission timer. +12. Set rewards, rating, and end-state options. +13. Sync `FORGE_Module_Defuse` to `FORGE_Module_Explosives`. +14. Sync `FORGE_Module_Defuse` to `FORGE_Module_Protected`. + +Notes: + +- The module reads grouped objects from the `Explosive Entities` and + `Protected Entities` modules, not from direct object syncs. +- Logic objects are filtered out already, so only real explosives and protected + entities are counted. +- The ACE defuse event is wired to the task system and resolves IEDs back to + the correct task. + +### Delivery Task + +Use `FORGE_Module_Delivery` when players must move cargo into a delivery zone. + +Required module layout: + +```text +[Delivery Task] --> [Cargo] --> cargo objects +``` + +Setup: + +1. Place the cargo objects. +2. Create an area marker for the delivery zone. +3. Place `FORGE_Module_Cargo`. +4. Sync each cargo object to `FORGE_Module_Cargo`. +5. Place `FORGE_Module_Delivery`. +6. Set `TaskID`. +7. Set `DeliveryZone` to the marker name. +8. Set `LimitSuccess` to the number of cargo objects that must arrive. +9. Set `LimitFail` to the number of cargo objects that can be damaged past the fail threshold. +10. Set rewards, rating, and optional `TimeLimit`. +11. Sync `FORGE_Module_Delivery` to `FORGE_Module_Cargo`. + +Notes: + +- The runtime checks `inArea DeliveryZone`, so the zone must be an area marker. + +### Hostage Task + +Use `FORGE_Module_Hostage` when players must rescue hostages and move them to +an extraction zone. + +Required module layout: + +```text +[Hostage Task] --> [Hostage Entities] --> hostage units +[Hostage Task] --> [Shooter Entities] --> hostile shooter units +``` + +Setup: + +1. Place the hostage AI units. +2. Place the hostile shooter AI units. +3. Create an area marker for the extraction zone. +4. If using the CBRN variant, create an area marker for the `CBRNZone`. +5. Place `FORGE_Module_Hostages`. +6. Sync the hostage units to `FORGE_Module_Hostages`. +7. Place `FORGE_Module_Shooters`. +8. Sync the shooter units to `FORGE_Module_Shooters`. +9. Place `FORGE_Module_Hostage`. +10. Set `TaskID`. +11. Set `ExtZone` to the extraction marker name. +12. Set `LimitSuccess` to the number of hostages that must be rescued. +13. Set `LimitFail` to the number of hostages that can be lost before failure. +14. Set `Execution` or `CBRN` as needed for the mission variant. +15. If `CBRN` is enabled, set `CBRNZone`. +16. Set rewards, rating, and optional `TimeLimit`. +17. Sync `FORGE_Module_Hostage` to `FORGE_Module_Hostages`. +18. Sync `FORGE_Module_Hostage` to `FORGE_Module_Shooters`. + +Notes: + +- Hostages and shooters are filtered to real units only. +- Hostages are protected immediately on task registration to avoid startup race conditions. +- The hostage timer now waits until the task is assigned before counting down. +- `ExtZone` is checked with `inArea`, so it must be an area marker. + +### HVT Task + +Use `FORGE_Module_HVT` when players must capture or eliminate a high-value +target. + +Setup: + +1. Place the HVT unit or units. +2. If using capture mode, create an area marker for the extraction zone. +3. Place `FORGE_Module_HVT`. +4. Set `TaskID`. +5. Set `CaptureHVT` as needed: + - enabled for capture/extract + - disabled for kill/eliminate +6. If using capture mode, set `ExtZone` to the extraction marker name. +7. Set `LimitSuccess` to the number of HVTs that must be captured or eliminated. +8. Set `LimitFail` if the mission should fail after too many HVT deaths in capture mode. +9. Set rewards, rating, and optional `TimeLimit`. +10. Sync the HVT module directly to the HVT unit or units. + +Notes: + +- Capture mode uses `ExtZone` with `inArea`, so use an area marker. +- Elimination mode does not require an extraction zone. +- The HVT timer now waits until the task is assigned before counting down. + +### Defend Task + +Use `FORGE_Module_Defend` when players must hold an area against spawned enemy +waves. + +Setup: + +1. Create an area marker for the defense zone. +2. Place `FORGE_Module_Defend`. +3. Set `TaskID`. +4. Set `DefenseZone` to the defense marker name. +5. Set `DefendTime` to how long the area must be held. +6. Set `WaveCount`. +7. Set `WaveCooldown`. +8. Set `MinBlufor` to the minimum number of friendlies required in the zone. +9. Set rewards, rating, and end-state options. + +Notes: + +- No enemy groups need to be pre-placed or synced. The defend task spawns its + own enemy waves. +- The defend task waits for the required number of BLUFOR to enter the zone + before the timer, waves, and empty-zone failure checks begin. +- `DefenseZone` must be an area marker. + +### Quick Reference + +Use direct syncs: + +- `Attack Task` -> target units/vehicles +- `Destroy Task` -> target objects/vehicles/units +- `HVT Task` -> HVT units + +Use grouping modules: + +- `Defuse Task` -> `Explosive Entities`, `Protected Entities` +- `Delivery Task` -> `Cargo` +- `Hostage Task` -> `Hostage Entities`, `Shooter Entities` + +Use area markers: + +- `DefenseZone` +- `DeliveryZone` +- `ExtZone` +- `CBRNZone` + ## Scripted Start Task Use `forge_server_task_fnc_startTask` when creating tasks from modules,