b7f7ae3a01
- Document Eden object, garage, and task setup for playable missions - Add the new getting-started page and update navigation links - Rename store actor variable to `isStore` in the docs
403 lines
15 KiB
Markdown
403 lines
15 KiB
Markdown
# Mission Designer Guide
|
|
|
|
Build playable Forge missions in Eden with the required interaction objects,
|
|
garage markers, and CAD-compatible task modules.
|
|
|
|
This guide focuses on editor placement and mission validation. Framework
|
|
internals, extension commands, and persistence details are covered in the
|
|
developer-oriented module guides.
|
|
|
|
## Core Rule
|
|
|
|
Most Forge systems become available to players through nearby Eden objects.
|
|
Place the object, give it the correct variable name in Eden, and the server
|
|
initializer marks it with the runtime variable the actor menu scans for.
|
|
|
|
Players must be within 5 meters of the object for the actor menu to offer the
|
|
action.
|
|
|
|
## Interaction Objects
|
|
|
|
Use the object's Eden variable name, not its display name. The matching is
|
|
case-sensitive in some initializers, so use lower-case names.
|
|
|
|
|
|
|
|
| System | Eden Object Variable Name | Runtime Variable | Player Action | Notes |
|
|
| --- | --- | --- | --- | --- |
|
|
| Bank | name contains `bank` | `isBank = true` | Full bank UI | Allows full banking workflows, including PIN changes. |
|
|
| ATM | name contains `atm` | `isAtm = true` | ATM bank UI | ATM mode requires PIN authorization and does not allow PIN changes. |
|
|
| Store | name contains `store` | `isStore = true` | Store UI | Store catalog and checkout behavior are configured server-side. |
|
|
| Garage | name contains `garage` | `isGarage = true` | Garage UI and virtual garage | Include a garage category in the name or set `garageType` manually. |
|
|
| Locker | name contains `locker` | local `isLocker = true` | Virtual arsenal action | The server hides the editor object; each client creates a local locker at the same position. |
|
|
|
|
Recommended object names:
|
|
|
|
```text
|
|
atm
|
|
bank
|
|
store
|
|
locker
|
|
garage_hq
|
|
garage_hq_2
|
|
```
|
|
|
|
The example mission uses short lower-case names. Keep single-use objects simple,
|
|
add an index when there may be multiple copies, and include a site label for
|
|
garage objects so related spawn markers can share the same prefix.
|
|
|
|
Avoid using `forge_locker_box` as an editor-placed locker variable name. That
|
|
name is reserved by the client-side virtual arsenal box.
|
|
|
|
## Manual Object Variables
|
|
|
|
The automatic initializers are the normal path. If a mission script creates
|
|
interaction objects dynamically, set the same variables manually:
|
|
|
|
```sqf
|
|
_bankLaptop setVariable ["isBank", true, true];
|
|
_atmTerminal setVariable ["isAtm", true, true];
|
|
_storeCounter setVariable ["isStore", true, true];
|
|
_garageTerminal setVariable ["isGarage", true, true];
|
|
_garageTerminal setVariable ["garageType", "cars", true];
|
|
```
|
|
|
|
Supported garage types are:
|
|
|
|
- `cars`
|
|
- `armor`
|
|
- `helis`
|
|
- `planes`
|
|
- `naval`
|
|
- `other`
|
|
|
|
## Garage Markers
|
|
|
|
Garage interaction objects open the garage UI. Vehicle spawn positions come
|
|
from Eden markers.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Additional garage sites use the same pattern: place another garage interaction
|
|
object, give it a `garage` variable name that identifies the site, then place
|
|
matching category spawn markers near that garage.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Create empty markers near each garage site. Marker names must contain `garage`
|
|
and one supported garage category:
|
|
|
|
```text
|
|
garage_hq_cars
|
|
garage_hq_armor
|
|
garage_hq_helis
|
|
garage_hq_helis_1
|
|
garage_hq_planes
|
|
garage_hq_naval
|
|
garage_hq_other
|
|
```
|
|
|
|
This convention keeps the site and category visible in the marker name:
|
|
`garage_hq_planes` is the planes spawn marker for `garage_hq`, while
|
|
`garage_hq_2` can use another nearby set of `garage_hq_*` category markers for
|
|
the second HQ garage area. If two garage objects of the same category are close
|
|
to each other, include the full object name in the marker prefix, such as
|
|
`garage_hq_2_planes`.
|
|
|
|
Use these rules:
|
|
|
|
1. Put the marker where the vehicle should spawn.
|
|
2. Rotate the marker to control spawn heading.
|
|
3. Keep the marker close to the matching garage object.
|
|
4. Include the garage object's variable name when multiple garages exist at
|
|
different sites.
|
|
5. Do not allow parked vehicles to block the marker. If a vehicle is within 5
|
|
meters of the spawn position, the virtual garage blocks the session.
|
|
|
|
Vehicle spawning is strict by category. A garage without a matching category
|
|
marker cannot spawn that vehicle category.
|
|
|
|
## Store Setup
|
|
|
|
Store objects only unlock the store UI. The actual item catalog, prices,
|
|
payment source handling, locker grants, and garage unlocks are server-owned.
|
|
|
|
|
|
|
|
|
|
|
|
Minimum Eden setup:
|
|
|
|
1. Place a terminal, table, NPC, or other object players can stand near.
|
|
2. Set its Eden variable name to something containing `store`.
|
|
3. Test that the actor menu shows the store action within 5 meters.
|
|
|
|
## Bank and ATM Setup
|
|
|
|
Bank and ATM objects intentionally expose different workflows.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use a `bank` object for the full bank interface:
|
|
|
|
- account view
|
|
- transfers
|
|
- earnings deposit
|
|
- PIN change
|
|
|
|
Use an `atm` object for ATM access:
|
|
|
|
- PIN-gated account access
|
|
- ATM-mode banking actions
|
|
- no PIN change
|
|
|
|
Minimum Eden setup:
|
|
|
|
1. Place one or more bank laptops or terminals with variable names containing
|
|
`bank`.
|
|
2. Place one or more ATM objects with variable names containing `atm`.
|
|
3. Keep the object accessible so players can stand within 5 meters.
|
|
|
|
## Locker Setup
|
|
|
|
Locker objects are slightly different from other interaction objects. The
|
|
server finds editor-placed objects whose variable names contain `locker`, hides
|
|
those global objects, and each client creates a local locker object at the same
|
|
position.
|
|
|
|
|
|
|
|
|
|
|
|
Minimum Eden setup:
|
|
|
|
1. Place a container object where the locker should appear.
|
|
2. Set its Eden variable name to something containing `locker`.
|
|
3. Do not use `forge_locker_box`.
|
|
4. Test that the local locker appears and opens the virtual arsenal action.
|
|
|
|
## Medical Spawn Setup
|
|
|
|
The medical economy store discovers up to eleven medical spawn objects by exact
|
|
mission namespace variable name:
|
|
|
|
- `med_spawn`
|
|
- `med_spawn_1`
|
|
- `med_spawn_2`
|
|
- continuing through `med_spawn_10`
|
|
|
|
These objects are used for medical respawn placement and occupancy checks.
|
|
|
|
|
|
|
|
|
|
|
|
Minimum Eden setup:
|
|
|
|
1. Place an object at each medical respawn position.
|
|
2. Set the first object's Eden variable name to `med_spawn`.
|
|
3. Set additional medical spawns to `med_spawn_1`, `med_spawn_2`, and so on.
|
|
4. Keep each spawn position clear enough for a revived player to occupy.
|
|
|
|
## CAD Access
|
|
|
|
The CAD UI is currently opened from the actor menu action path, but there is no
|
|
server initializer that marks Eden objects as dedicated CAD terminals. If a
|
|
mission needs a CAD terminal object, wire it through mission script or a custom
|
|
interaction that calls:
|
|
|
|
```sqf
|
|
[] spawn forge_client_cad_fnc_openUI;
|
|
```
|
|
|
|
Tasks show in CAD only when they are created through a CAD-compatible task
|
|
creation path.
|
|
|
|
## CEO and Dispatch Slots
|
|
|
|
Forge grants dispatch-board permissions from the player's Eden unit variable
|
|
name when that player belongs to the default organization.
|
|
|
|
Use these exact lower-case variable names:
|
|
|
|
| Slot | Eden Unit Variable Name | Permissions |
|
|
| --- | --- | --- |
|
|
| CEO | `ceo` | Can administer the default organization, use default organization funds where supported, and use the CAD dispatch board. |
|
|
| Dispatch | `dispatch` | Can use the CAD dispatch board. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CEO slot is intentionally broader than the dispatch slot. Use it for the
|
|
player who should administrate the default organization. Use the dispatch slot
|
|
for players who need dispatcher tools without default organization
|
|
administration rights.
|
|
|
|
## Task and CAD Setup
|
|
|
|
Mission designers should use Forge Eden task modules for CAD-visible work.
|
|
Those modules delegate to `forge_server_task_fnc_startTask`, which creates the
|
|
BIS task, registers the Forge task catalog entry, sets active task state, and
|
|
dispatches the task handler.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CAD-compatible task creation paths:
|
|
|
|
| Path | CAD Compatible | Use When |
|
|
| --- | --- | --- |
|
|
| Forge Eden task modules | Yes | Normal mission-designer workflow. |
|
|
| `forge_server_task_fnc_startTask` | Yes | Scripted or generated mission content. |
|
|
| Dynamic mission manager attack tasks | Yes | Server-generated attack missions. |
|
|
| `forge_server_task_fnc_handler` directly | Only if catalog and BIS task already exist | Advanced scripted flows. |
|
|
| Direct task function calls | No by default | Custom server-owned flows that do not need CAD assignment. |
|
|
|
|
General task rules:
|
|
|
|
1. Give every task a unique `TaskID`.
|
|
2. Set success and fail limits explicitly.
|
|
3. Use area markers for zone fields.
|
|
4. Use Forge grouping modules where required.
|
|
5. Sync task modules to real world objects, units, vehicles, or grouping
|
|
modules.
|
|
6. Test that the task appears in CAD before relying on dispatch assignment.
|
|
|
|
Zone fields that must reference area markers:
|
|
|
|
|
|
|
|
| Field | Used By | Marker Requirement |
|
|
| --- | --- | --- |
|
|
| `DefenseZone` | Defend Task | Rectangle or ellipse area marker. |
|
|
| `DeliveryZone` | Delivery Task | Rectangle or ellipse area marker. |
|
|
| `ExtZone` | Hostage and HVT capture tasks | Rectangle or ellipse area marker. |
|
|
| `CBRNZone` | Hostage CBRN variant | Rectangle or ellipse area marker. |
|
|
|
|
## Task Module Quick Reference
|
|
|
|
| Task Module | Sync Target | Required Marker |
|
|
| --- | --- | --- |
|
|
| `FORGE_Module_Attack` | Target units or vehicles | None |
|
|
| `FORGE_Module_Destroy` | Target objects, vehicles, or units | None |
|
|
| `FORGE_Module_Defuse` | `FORGE_Module_Explosives`, optionally `FORGE_Module_Protected` | None |
|
|
| `FORGE_Module_Delivery` | `FORGE_Module_Cargo` | `DeliveryZone` |
|
|
| `FORGE_Module_Hostage` | `FORGE_Module_Hostages` and `FORGE_Module_Shooters` | `ExtZone`, optional `CBRNZone` |
|
|
| `FORGE_Module_HVT` | HVT units | `ExtZone` when capture mode is enabled |
|
|
| `FORGE_Module_Defend` | Optional enemy units as wave templates | `DefenseZone` |
|
|
|
|
## Mission Manager Blacklist Markers
|
|
|
|
The dynamic mission generator avoids rectangle and ellipse area markers whose
|
|
marker name or marker text starts with `blklist`.
|
|
|
|
Use blacklist area markers to keep generated missions out of bases, spawn
|
|
areas, training zones, or protected set pieces.
|
|
|
|
|
|
|
|
|
|
|
|
Setup:
|
|
|
|
1. Create a rectangle or ellipse area marker over the area to exclude.
|
|
2. Set the marker variable name or marker text to start with `blklist`.
|
|
3. Give the marker real size so the generator can test candidate positions
|
|
against the area.
|
|
|
|
## Task Setup Checklist
|
|
|
|
Before publishing a mission, verify:
|
|
|
|
- Every task has a unique `TaskID`.
|
|
- Every configured marker name exists in Eden.
|
|
- Zone markers are area markers, not icon-only markers.
|
|
- Grouping modules are synced in the correct direction.
|
|
- Success and fail limits match the number of required entities.
|
|
- Reward funds and rating changes are intentional.
|
|
- The task appears in CAD when created.
|
|
- Assigned CAD tasks can be acknowledged, declined, and completed.
|
|
|
|
## Mission Validation Checklist
|
|
|
|
Run this checklist in a local multiplayer test:
|
|
|
|
- Stand within 5 meters of each bank object and verify the full bank action.
|
|
- Stand within 5 meters of each ATM and verify ATM mode.
|
|
- Confirm PIN changes are only available from the full bank interface.
|
|
- Stand near each store object and complete a test checkout.
|
|
- Stand near each locker and verify the local locker/arsenal opens.
|
|
- Open each garage and retrieve/store a vehicle.
|
|
- Open each virtual garage category and confirm the correct spawn marker is
|
|
used.
|
|
- Block a garage spawn marker with a vehicle and confirm the warning appears.
|
|
- Create each mission task and confirm CAD visibility.
|
|
- Assign a task in CAD and verify the player flow through completion or failure.
|
|
|
|
## Eden Screenshot Set
|
|
|
|
The live docs should include real Eden screenshots for mission designers. When
|
|
capturing them, save the images under `docus/public/images/eden/` and use these
|
|
filenames so the docs can reference stable assets:
|
|
|
|
| File | Capture |
|
|
| --- | --- |
|
|
| `bank_obj.jpg`, `bank_obj_var.jpg` | Bank object placement and variable name. |
|
|
| `atm_obj.jpg`, `atm_obj_var.jpg` | ATM object placement and variable name. |
|
|
| `store_obj.jpg`, `store_obj_var.jpg` | Store object placement and variable name. |
|
|
| `locker_obj.jpg`, `locker_obj_var.jpg` | Locker container placement and variable name. |
|
|
| `garage_obj.jpg`, `garage_obj_var.jpg` | Garage interaction object placement and variable name. |
|
|
| `garage_spawn_mrkrs.jpg`, `garage_spawn_1_mrkr_var.jpg` | Garage category spawn markers and marker variable naming. |
|
|
| `garage_obj_2.jpg`, `garage_obj_2_var.jpg`, `garage_spawn_2_mrkrs.jpg` | Additional garage site placement, variable name, and spawn markers. |
|
|
| `med_spawn_obj.jpg`, `med_spawn_obj_var.jpg` | Medical spawn object placement and variable name. |
|
|
| `ceo_unit.jpg`, `ceo_unit_var.jpg` | CEO playable unit placement and variable name. |
|
|
| `dispatch_unit.jpg`, `dispatch_unit_var.jpg` | Dispatch playable unit placement and variable name. |
|
|
| `blacklist_mrkr.jpg`, `blacklist_mrkr_var.jpg` | Mission-manager blacklist marker placement and marker variable naming. |
|
|
| `create_task_mod.jpg`, `create_task_mod_params.jpg` | Generic Forge task module placement and parameters. |
|
|
| `attack_task_mod.jpg`, `attack_task_mod_params.jpg`, `attack_task_tgts.jpg` | Attack task module placement, parameters, and target sync. |
|
|
| `cad-visible-task.jpg` | In-game CAD showing a task created from the Eden module. |
|
|
|
|
Use screenshots that show the Eden left-side entity list, the selected object's
|
|
attributes panel, and the map placement where possible. Crop only enough to
|
|
remove unrelated mission content.
|
|
|
|
## Related Guides
|
|
|
|
- [Task Usage Guide](./TASK_USAGE_GUIDE.md)
|
|
- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md)
|
|
- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md)
|
|
- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md)
|
|
- [Store Usage Guide](./STORE_USAGE_GUIDE.md)
|
|
- [Bank Usage Guide](./BANK_USAGE_GUIDE.md)
|
|
- [Client CAD Usage Guide](./CLIENT_CAD_USAGE_GUIDE.md)
|