docs: add mission designer setup guide to TASK_USAGE_GUIDE.md
This commit is contained in:
Jacob Schmidt
parent
07d5422091
commit
3535484079
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user