EscapistsReintroduced/docs/content-packs.md

Mission content packs and factions

Administrators open Esc → Escapists 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 $profile:EscapistsContent.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.

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 $profile:EscapistsFactions.json, for example:

{"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):

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, with both directions validated before preparation can finish.