EscapistsReintroduced/docs/enemy-loadouts.md

# Enemy infantry loadouts

**Esc → Co10 Escape Reintroduced → HQ** has two percentage settings, each accepting
0–100 or Random:

| Setting | Default | Effect |
| --- | --- | --- |
| Anti-air launchers | 7% | One initially loaded faction MANPADS, with FIM-92 fallback |
| Anti-personnel mines | 60% | Up to two carried PMN-4 mines, subject to inventory space |

These are independent per-soldier grant probabilities, not exact population quotas.
They apply to eligible living, nonplayer military members of mission-owned hostile
groups, including hostile independent factions. Existing authored equipment is
preserved. Specialist loadouts that bypass ordinary fitting remain unchanged.
Changing a value affects soldiers whose initial roll has not happened yet; it does
not reroll existing soldiers. Mines are inventory loot, not automatically planted.

Commands are `/esc hq aa show|set N|set random` and
`/esc hq mines show|set N|set random`. The legacy `/esc hq stinger set N` alias accepts the same percentage or
`/esc hq stinger set random`; its `show` command displays Random instead of the
internal sentinel. Both aliases preserve existing equipment. Server authentication and the existing settings save/validation
path apply. Canonical keys are `antiAirChancePercent` and
`antiPersonnelMineChancePercent`. Old `stingerChanceOneIn` files migrate to the
nearest integer percentage: 0 → 0%, 1 → 100%, 15 → 7%, 37 → 3%.
Very small probabilities can round to zero. The canonical key takes precedence.
Missing settings default to 7% and 60%.

## Faction launchers and modder overrides

An `ERR_ContentOption` can specify `AntiAirLauncher` as a prefab ResourceName.
The lookup matches `NativeFactionKey` in `Configs/ERR/ContentRegistry.conf`.
Otherwise, enabled entries in that faction's native ITEM catalog are checked for
MANPADS prefab names (Stinger/FIM92, Igla, Strela or MANPAD under Launchers).
Catalog inspection is bounded to 4,096 entries. Unrecognized naming requires an
explicit override. USSR/FIA use the installed WCS Igla when no catalog candidate
exists. Other factions, unavailable resources and confirmed insertion failures
fall back to the WCS FIM-92; no additional mod dependency was added.

The runtime verifies that the replacement physically occupies a weapon slot,
is a rocket launcher, and has a chambered round or loaded magazine. A newly
issued unusable replacement is removed only while still in that soldier's
inventory, with confirmed deletion before the FIM request. Authored equipment
is never deleted to make room. This verifies equipment and ammunition, not the
mod's targeting/lock-on behavior in combat.

Inventory operations have finite startup checks. Pending operations are not
repeated or replaced while their result is unknown. Dropping, firing or looting a
granted launcher does not earn a new one; mine allowance is likewise finite.
No loose items are spawned when inventory capacity is unavailable.
`AA PROFILE`, `AA EQUIPMENT`, `AA FALLBACK` and `MINE EQUIPMENT` journal entries
record selection, grants and failure reasons.

## Verification

`test_enemy_loadout.py` executes production grant methods with native API doubles:
all percentage boundaries, preferred success, fallback, exact-item removal,
pending-operation quarantine, missing/looted items, capture, authored mines and
finite mine grants. Existing coordinator, admin/menu and settings migration tests
cover integration. `--project core --smoke enemy-loadout` is a Workbench-only
fixture for physical inventory, loaded weapons and HQ menu capture.

The 2026-09-23 local Workbench fixture completed four assertions with no script
or runtime failures: persisted percentage settings, a physical test group, loaded
WCS Igla and fallback FIM-92 plus two carried AP mines, and HQ navigation.
The native checker still reports installed RHS/WCS localization/resource and
external prefab-field errors; this is not a clean whole-mod engine report.
Multiplayer replication and actual missile targeting/firing were not tested.

Final local fixture logs: `/tmp/erri-loadouts-native2/logs/logs_2026-09-23_15-29-59`. Source and external-addon fingerprints remained unchanged; runner cleanup was confirmed. Native menu navigation passed, but the engine screenshot omitted the overlay and the separate display capture failed, so visual layout acceptance remains unverified.

## Automatic equipment from installed mods

Every eligible non-medic enemy has a **25%** default chance to receive one extra inventory item. The pool is cached per round and rebuilt after item preferences change from enabled standard arsenal entries in the active scenario's general and faction ITEM catalogs. Vanilla and mod items share the pool, regardless of faction. Each distinct resource GUID initially has equal selection probability; entries repeated across factions do not get extra weight. A mod with many distinct variants consequently has a larger total share unless an admin changes the weights.

No Escape connector, extra dependency or soldier prefab edit is needed for equipment that a loaded mod registers in those catalogs. Merely installing a mod is insufficient if its equipment is absent from the active catalogs. This does not enumerate every prefab in Workshop archives or automatically register new factions.

The pool supports rifles, pistols, machine guns, sniper rifles, grenades, medical items and general equipment. Clothing, backpacks, attachments, loose ammunition, mines, launchers, vehicles and mortars are excluded. Existing AA/mine probabilities and authored uniforms, weapons and medical loadouts remain unchanged. Known disabled Escape content entries are excluded; unregistered mods follow the native catalog's enabled state.

Use `/esc hq equipment show` or `/esc hq equipment set 0..100` (`random` is also supported). The saved key is `mission.automaticEquipmentChancePercent` in `$profile:Escapists.json`; zero disables future rolls. Changing it does not reroll existing soldiers.

**Items → Spawn chances** adjusts relative weights for an entire loaded mod and for individual items. Weight **1** is normal, **100** is very high and **0** excludes the item from automatic selection. An item's effective weight is its mod multiplier times its item multiplier. Raising a mod to 100 makes each eligible item from it 100 times as likely to be picked as an otherwise equal weight-1 item; it does **not** mean a 100% spawn chance. The page shows the current calculated lottery share and the separate extra-equipment chance. For Phaseline Marksman Rifles (`BFC890A6F1603EC0`), select that mod and press **Very high (100)**. Disabled or unsupported items remain excluded regardless of weight.

The Items section has four pages: **Extra equipment** sets the overall percentage, **Allowed items** controls inclusion, **Spawn chances** sets relative weights, and **Presets** saves or restores selections and weights. Presets do not alter the overall percentage. Changes keep the same selected mod across the two item pages.

Weights apply to future rolls, persist with the server's item settings and are included in named presets. Existing saved selections load with weight 1. Settings for absent mods remain dormant until those mods are loaded again. Shared resources are entered only once: the highest mod and item multipliers among their loaded contributors apply, while a zero from any contributor excludes them. Because several mods can contribute to one resource, displayed per-mod shares can overlap. No extra entities or duplicate ticket arrays are created; selection uses cumulative integer weights and a binary search.

Each selected item is attempted once after existing startup supplies settle. Guns use a free weapon slot and request at most two magazines of their main muzzle's default ammunition. The AI may use the additional gun through its normal weapon selection; this does not force a main-weapon replacement. Full or incompatible storage can refuse an item or ammunition, so the configured percentage is an **attempt probability**, not a guaranteed count of equipped soldiers. There are no loose fallback drops, retries with different items, or replacements after looting. Medics retain their storage for treatment.

The HQ journal records `AUTO EQUIPMENT CATALOG` (pool size) and `AUTO EQUIPMENT` (issued/refused items and ammunition requests). Catalog limits disable the pool with a diagnostic instead of favoring a truncated subset.

Detailed automatic-equipment diagnostics are in **`$logs:rereintroduced-equipment.log`** beside the server console log, with rotated parts `rereintroduced-equipment-1.log` through `-3.log`. They start automatically after this build is published and loaded; they cannot reconstruct older rounds. Read records by `run` and `seq` across the four files.

- `ROUND` and `ADDON`: configured chance and all loaded addon GUIDs, project names and titles. A configured chance of `-1` means Random; each `ROLL` records the actual resolved chance.
- `CATALOG_SOURCE`, `CATALOG_ITEM`, `CATALOG_ADDON`, `CATALOG_END`: catalogs examined, individual eligibility/filter reasons, per-addon eligible counts (including zero), final pool size, duplicate tickets and safety limits. Resource contributors include addons modifying the same resource, so their counts can overlap. Attribution reuses resources already loaded by equipment selection; rejected resources are identified by prefab/GUID without loading them just for logging. An eligible row is only a candidate if a later safety limit discards the entire pool.
- `ACTOR`, `ROLL`, `PICK`, `REQUEST`, `ITEM_CONFIRMED`, `RESULT`, `STOP`: stable soldier audit ID and prefab/group, medic exclusion, one-time chance roll, selected item/catalog, native insertion requests, confirmed new inventory item, ammunition callback successes, failures and interrupted work. A successful request is not yet a confirmed insertion; ammunition callback success is not a later inventory census. An actor without a roll may still be waiting for startup supplies, incapacitated, or excluded as a medic. The pool is built on the first successful chance roll or an admin item-page snapshot, then cached until selections change.

There are no new entity scans, prefab loads, network messages or per-frame updates for this log. It uses a 4,096-record ring, at most 32 writes per scheduled 500 ms slice, and yields after 3 ms of elapsed flush time (individual filesystem operations can still stall). When idle it schedules nothing. Four rotating files retain approximately 8 MiB per engine log directory; old engine log directories follow the server's existing retention policy. Open failures retry after 30 seconds and warn only once. `LOG_GAP`, sequence gaps, `audit_omitted` or `[truncated]` explicitly mark incomplete details. Buffered tail records may be lost on a crash/world shutdown; this is diagnostic logging, not a durable transaction journal. Logging itself does not change spawn chances, selection weights or loadouts.


## Optional motorbike hunters

Mods → Recommended addons lists WCS Motorbikes (`6503091A7B264FC3`), Cessna 172
and Phaseline Marksman Rifles, using the **server's mounted addons**. Missing
supporting addons are named. This page does not download mods or introduce new
Workshop dependencies. Cessna and weapon buttons open their existing controls.

Motorbike count is 0–6 (default 2, 0 disables), saved for the next round. When WCS
Motorbikes, its Motorbike base (`61B84088181A8FA4`) and WCS Armaments are mounted,
two-person hunter teams join the opening UAZ/truck patrols. Crew use the selected
faction's response soldier and medic profiles (special forces where configured).
Vehicles must expose a driver, one passenger and native AI driving components;
unsupported resources are skipped with a diagnostic. Existing bags/equipment
are retained; a physical handheld radio may be added, with ordinary radio relay
and range constraints. They share hunter movement, dismount and HQ coordination.
The bike allowance is separate from UAZ/trucks and does not replenish losses.

The installed WCS 8.3.0 prefab definitions were inspected: RX100 inherits native
car movement/vehicle usage and defines pilot/passenger seats. No third-party
prefabs/scripts are copied into the mission. Compilation, menu routing and
crew/soft-dependency policy checks passed; actual riding and combat still need
an in-game test after publication.