jakub
6a667d8deb
Include the current addon, terrain integrations, tools, regression tests and recorded development evidence.
152 lines
8.7 KiB
Markdown
152 lines
8.7 KiB
Markdown
# Mission content packs and factions
|
|
|
|
Administrators open **Esc → Co10 Escape Reintroduced → Mods** (also available in `/esc menu`). RHS
|
|
and its US Marines, Russian Armed Forces and ION factions default to enabled.
|
|
Each faction can be disabled independently. Disabling the parent pack excludes
|
|
all its factions and the mission's optional RHS optics, while retaining child
|
|
preferences. Enable/disable controls are authenticated on the server; saved
|
|
preferences and current effective selections are shown separately.
|
|
|
|
Changes apply on mission restart. Preferences live in
|
|
the `mods` section of `$profile:Escapists.json` on the server; use numeric `0`/`1` values for
|
|
`rhs`, `rhs_usmc`, `rhs_afrf`, and `rhs_ion`. Invalid existing files are preserved;
|
|
validated backup recovery and verified writes follow the mission settings
|
|
pattern. New registry entries use their authored default when absent from an
|
|
older file. Workshop dependencies stay installed and loaded. This controls what
|
|
the mission selects, not third-party scripts or a player's downloaded mods.
|
|
|
|
When **REAPER_CORE and RHS: Status Quo are both loaded**, Escape repairs their
|
|
conflicting base-character slot managers before character creation. It moves
|
|
Reaper's existing spectator-camera slot into the RHS thermal manager, preserving
|
|
the thermal body as the first slot, and removes only the redundant camera-only
|
|
manager. The repair changes the combined resource in memory; it does not edit
|
|
either addon, add a prefab override, or require Reaper as a dependency. It is
|
|
inactive when either mod is absent, independently of the mission's item/faction
|
|
selection. An unfamiliar slot layout is left unchanged and logged for review.
|
|
|
|
Native validation with Reaper 1.1.3 and RHS 0.16.5208 covers mission readiness,
|
|
Soviet/US/RHS character creation, attached thermal/camera entities and repeated
|
|
application. The absent-mod cases use the same compatibility script, with a
|
|
minimal test addon where necessary because Escape itself already depends on RHS.
|
|
See [compatibility evidence](evidence/reaper-rhs-compat-2026-10-03/review.json).
|
|
|
|
Open **Mission settings → Factions** to select the **Escapists**, **Enemy**, and
|
|
**Independent / FIA** roles. Each dropdown offers Random plus enabled registered
|
|
factions (US Army, Soviet Army, FIA, and enabled RHS factions). **Random all**
|
|
sets all three drafts to Random; **Apply factions** saves them together.
|
|
Explicit choices must differ. Random reserves explicit choices first and fills
|
|
the remaining roles without duplicates. A previously selected faction that is
|
|
now disabled falls back to another eligible faction at round start.
|
|
|
|
Role preferences are separate from pack enablement and live in
|
|
the `factions` section of the same `$profile:Escapists.json`. Its section value
|
|
is, for example:
|
|
|
|
```json
|
|
{"escapists":"us","enemy":"ussr","independent":"fia"}
|
|
```
|
|
|
|
Each value can instead be `"random"`; RHS IDs are `rhs_usmc`, `rhs_afrf`, and
|
|
`rhs_ion`. The equivalent authenticated command is
|
|
`/esc factions set us ussr fia`. Saved choices and the current resolved factions
|
|
are displayed separately. Changes require mission restart and never reassign
|
|
live players or AI mid-round.
|
|
|
|
The three selected sides are mutually hostile and friendly within their own
|
|
faction. Prisoners join the selected Escapists faction. Ordinary enemy guards
|
|
use the selected enemy group's native infantry. Sites with `AllowFactionPool`
|
|
alternate independent and main-enemy groups. The strategic HQ, radio network,
|
|
convoys and mortar logistics follow the main enemy; independent groups execute
|
|
native guard/patrol orders. Convoy infantry use the selected enemy profile.
|
|
Existing convoy vehicles, specialist mortar kits and the unarmed prisoner outfit
|
|
are retained; faction selection does not replace every vehicle or item asset.
|
|
All mission hostiles stay frozen until the prison is unlocked.
|
|
|
|
The prison starter container is the original Kolobok backpack, stocked once with
|
|
five PM pistols, eight spare magazines and one map. Existing readiness checks
|
|
wait for actual inventory insertion and client storage ownership.
|
|
|
|
## Adding a pack or faction
|
|
|
|
No menu code, command code or fixed settings schema edits are needed.
|
|
|
|
1. Add the Workshop dependency to `addons/core/addon.gproj` and install it in
|
|
Workbench. Update the test tooling allowlist in `tools/external_addons.py` and
|
|
extend `docs/external-addons.json` with the reviewed dependency
|
|
closure and exact resource GUID/path records used by this repository's tools.
|
|
2. Add a pack `ERR_ContentOption` to
|
|
`addons/core/Configs/ERR/Content/Registry.conf`: unique lowercase `Id`, readable
|
|
`Label`, `DefaultEnabled` (0 or 1), and optional `EquipmentGuids`.
|
|
3. Add one child option per combat faction with `Parent` set to the pack ID,
|
|
the exact `NativeFactionKey`, and `GuardGroup` resource. The group must spawn
|
|
its physical members immediately, with every member in that native faction.
|
|
Use distinct native keys for factions that should fight each other.
|
|
4. Add its `SCR_Faction` config to `Prefabs/ERR/FactionManager.et`, with
|
|
`m_bIsPlayable 0` and an empty `m_aFriendlyFactionsIds` list. The startup
|
|
validator checks the enabled factions and establishes mutual hostility.
|
|
5. Set `AllowFactionPool 1` on scenario sites eligible for faction variation.
|
|
These sites alternate the selected independent and main-enemy groups.
|
|
Other guarded sites use the main enemy profile. Specialist units retain
|
|
their mission equipment while following the selected enemy faction.
|
|
6. For new optional equipment selection code, call
|
|
`mode.Content().Allows(prefab)` before granting it, and register its GUID in
|
|
the owning option. Existing inherited equipment on faction characters stays
|
|
part of their prefab. Arbitrary native resource spawns are not intercepted.
|
|
|
|
Example child entry (substitute real faction key/resource):
|
|
|
|
```text
|
|
ERR_ContentOption {
|
|
Id "my_pack_infantry"
|
|
Label "My pack / Infantry"
|
|
Parent "my_pack"
|
|
DefaultEnabled 1
|
|
NativeFactionKey "MY_INFANTRY"
|
|
GuardGroup "{REAL_RESOURCE_GUID}Prefabs/Groups/MyInfantry.et"
|
|
}
|
|
```
|
|
|
|
IDs are persistent preference keys: keep them stable across releases. The
|
|
registry rejects duplicate IDs, faction keys, resource ownership, missing
|
|
parents and nested parent chains. It supports up to 64 entries and the UI
|
|
scrolls automatically. Registered factions also populate the role dropdowns;
|
|
no separate menu registration is needed. Use keys distinct from US, USSR and FIA.
|
|
The server must load the faction and its group resource. This registry does not
|
|
automatically discover arbitrary unregistered Workshop factions.
|
|
|
|
Commands: `/esc mods show`, `/esc mods rhs disable`,
|
|
`/esc mods rhs_usmc enable`, `/esc mods help`.
|
|
|
|
## Verification — 21 September 2026
|
|
|
|
Production-policy tests cover role resolution, explicit-choice reservation,
|
|
unique Random-all selection, disabled-choice fallback, invalid choices, pack
|
|
and child gating, guard eligibility, and selected non-USSR convoy dispatch.
|
|
|
|
The isolated native `core / prisoner-kit` run at
|
|
`/tmp/erri-factions-native3/logs/logs_2026-09-21_17-49-09` completed **341 assertions**
|
|
with USSR prisoners, RHS AFRF enemies and US independent guards. It compiled the
|
|
scripts and exercised actual player affiliation, physical guard groups,
|
|
hostility, authenticated role-menu save/restore, Random-all drafts, unchanged
|
|
active roles after save, unauthorized-command rejection, persistence reload,
|
|
backpack storage/readiness and the existing prisoner-kit checks. Sources and
|
|
dependencies stayed unchanged during the run; private runtime cleanup completed.
|
|
The faction page was rendered and inspected at `/tmp/erri-factions-menu.png`.
|
|
A second run (`/tmp/erri-factions-native4`) also completed 341 assertions
|
|
with RHS ION prisoners, US enemies and FIA independent guards, confirming
|
|
RHS player eligibility and FIA physical squads. Repository checks passed with
|
|
`python3 tools/check.py`.
|
|
|
|
Native validation still reports four external RHS/WCS localization errors and
|
|
five unknown-keyword errors while preloading inherited RHS vehicle catalogs
|
|
(`SlidingTrackMaterial` and BTR70 `Parent` entries). There were no mission script
|
|
or smoke failures in the completed run. These are local scripted Workbench
|
|
checks, not dedicated-server, ordinary mouse/gamepad-input, or multiplayer
|
|
replication acceptance. No Workshop publishing was performed.
|
|
|
|
Faction hostility follows the native
|
|
[SCR_FactionManager API](https://community.bistudio.com/wikidata/external-data/arma-reforger/ArmaReforgerScriptAPIPublic/interfaceSCR__FactionManager.html),
|
|
with both directions validated before preparation can finish.
|
|
|
|
Faction entries may optionally specify `AntiAirLauncher` for a loaded MANPADS prefab. The HQ anti-air percentage uses that override, otherwise searches the native faction item catalog and falls back to FIM-92 when necessary. See [enemy loadouts](enemy-loadouts.md) for supported naming, compatibility checks and finite grants.
|