EscapistsReintroduced/docs/living-island/OCCUPATION.md

# Island occupation — agent brief

**Hand this file to a coding agent as-is.** It is self-contained: concept, rules,
verified engine APIs, work breakdown, acceptance criteria and tests.

Companion files (same directory) hold the supporting infrastructure this design
sits on: `README.md` (plan and rules), `T1-force-ledger.md`,
`T2-presence-budget.md`, `T3-checkpoints.md`, `T4-smart-actions.md`,
`T5-hq-integration.md`, `T6-ambient-signals.md`, `T7-performance.md`.
If the ledger (T1) and presence budget (T2) are not yet implemented, build those
first — this design assumes them.

---

## 1. The concept

The island does **not** start occupied. At mission start only the prison and its
immediate surroundings hold troops. Everything else — the radio station, the
helipad, the junctions, the depots — is empty ground with buildings on it.

Then the alarm goes off, and the enemy *moves in while the player watches*.
Helicopters lift sections out to guard the objectives. Trucks drive to junctions
and the soldiers get out and **build roadblocks over several minutes**. Patrols
fan out along the roads. Over the next twenty to forty minutes the island closes
around the player.

This gives three things at once:

1. **Atmosphere.** Watching a transport helicopter flare and unload eight
   soldiers onto the hill you were about to cross is worth more than finding
   those eight soldiers already standing there.
2. **CPU.** Almost nothing exists at T+0. Deployments travel as ledger records
   and only become real AI near players. Start cost is near zero, and the
   steady-state cost is the same agent budget as before.
3. **Counterplay and pressure.** Every deployment is interruptible, every loss
   is permanent, and an island left alone gets steadily harder to cross. Hiding
   is punished; moving fast is rewarded.

**The player must be able to change the outcome.** Shoot down the transport and
those eight soldiers never arrive — that junction stays open for the rest of the
round. That is the whole point of the design; protect it in every decision.

---

## 2. Non-negotiable rules

### Licensing

This project is an independent successor. The original Escapists mod and its
`ScrtCore` / `ScrtSharedContent` dependencies are SCRT-ND licensed (an APL-ND
variant) which **forbids derivative works**.

- Never copy code, configs, layouts, compositions or assets from the original
  Escapists mod, from ScrtCore/ScrtSharedContent, or from `/home/jakub/devel/escapists`.
- Never introduce identifiers matching `ESCT*`, `SCRTC_*`, `SCRT_*`, `EAI_*`.
  `tools/check.py:39` fails the build on these.
- Only vanilla Arma Reforger resources and resources owned by this repo may be
  referenced. Reimplementing a mechanic from scratch is fine; copying an
  implementation is not.

### Addon boundaries

Five addons only: `core`, `ai`, `intel`, `chat`, `map`. `ai`/`intel`/`map`
depend on `core`; `chat` depends on all. **`core` must never reference `ERR_HQ`,
`ERR_AircraftService`, or anything else from another addon.**

Occupation logic lives in **`core`**, so the base scenario occupies the island
without the AI addon installed. Where it needs a companion capability it defines
an interface in core and lets `ai` register an implementation — the existing
`ERR_CommandService` and `ERR_AdminProvider` show the pattern. Without the AI
addon, occupation still happens by road and on foot; only air lift is missing.

### Performance

1. No per-frame work. Every tick here is ≥ 1 s, staggered by id (`id % N`).
2. No allocation inside loops. Reuse member arrays.
3. Spatial bucketing (500 m cells) for proximity — copy `ERR_HQNetwork.Add/Build`.
4. Hard caps everywhere, with a logged refusal when hit.
5. Issue waypoints and let the engine drive. No custom per-frame steering.
6. Hysteresis and dwell before any spawn/dormant flip.

### Style and validation

- Match surrounding indentation (older files use tabs). New lines under 120 chars.
- Decision logic goes in **pure static rule classes** (see `ERR_MissionRules`,
  `ERR_DiscoveryMapRules`) so it is testable without the engine. Entity work
  stays in the service.
- `python3 tools/check.py` must pass before you report done.
- Add tests with `tests/policy_harness.py`: `body(path, signature)` extracts a
  real function body from the `.c` file and `run(code)` compiles and runs it as
  C++. Follow `tests/test_admin_session.py`.
- Report honestly. Separate "compiles and passes scripted fixtures" from
  "verified in the real game". Do not write evidence claiming runtime
  verification you did not perform.

---

## 3. The occupation timeline

### T+0 — Dormant island

| Location | State at start |
| --- | --- |
| Prison | Full garrison, physical (players are there) |
| Within 2 km of prison | 2 patrol records, dormant |
| Staging areas (1–2 authored) | The entire remaining force pool, as records |
| Everything else | Buildings and props only. **No troops.** |

Authored staging areas are the military sites the occupation flows out of — pick
the existing barracks/airfield areas on Everon. They hold the pool and are where
transport originates. A staging area is itself a site that can be attacked.

### T+alarm — Detection

The occupation plan starts when HQ learns something is wrong, through the
existing systems, not a timer: an escape is witnessed, a body or breach is found,
or a guard check-in is missed. If nothing is detected, occupation still begins
on a long fallback (default 15 min, setting `occupationFallbackSeconds`) — a
missing prisoner count is noticed eventually.

### T+alarm onward — Deployment

HQ walks a priority list and issues deployment orders while the pool lasts:

| Priority | Objective | Why |
| --- | --- | --- |
| 1 | Radio station(s) | Denies the player's first objective |
| 2 | Helipad / extraction site | Denies the escape |
| 3 | Road junctions and bridges on the ring road | Roadblocks, cordon |
| 4 | Medical and depot sites | Denies resupply |
| 5 | Overwatch positions near likely routes | Observation, HQ eyes |

Cadence: one order every 90–180 s early, slowing as the pool depletes
(`occupationOrderSeconds`). At most **5 deployments in transit at once**.

### T+20 to T+40 — Entrenchment

Arrived sections build. Roadblocks go up over 6–10 minutes each. Checkpoints
become manned (T3). Patrol routes establish between occupied sites. The island
that was empty is now a network.

### Continuous — Adaptation

As HQ gains contacts (T5), it re-prioritises: the sector where players were seen
gets the next deployments and a cordon on its exits; quiet sectors are thinned,
not reinforced. With no contacts, occupation proceeds methodically down the
priority list — so hiding tightens the noose.

---

## 4. Data model

Add to `core`, next to the ledger:

```
class ERR_ForcePool          // finite, permanent losses
{
  int Sections;              // remaining uncommitted sections
  int SectionStrength;       // soldiers per section, default 4
  int TransportAircraft;     // remaining flyable transports
  int TransportVehicles;     // remaining trucks
}

enum ERR_OccupationPriority { RADIO, EXTRACTION, JUNCTION, SUPPLY, OVERWATCH }

class ERR_OccupationObjective
{
  string SiteId;  ERR_OccupationPriority Priority;
  int RequiredSections;  int AssignedSections;
  bool Held;  bool Contested;  bool Abandoned;
}

enum ERR_DeployMethod { FOOT, CONVOY, AIRLIFT }
enum ERR_DeployState  { QUEUED, LOADING, IN_TRANSIT, UNLOADING, ARRIVED, LOST }

class ERR_DeploymentOrder
{
  int Id;  string ObjectiveId;  ERR_DeployMethod Method;  ERR_DeployState State;
  int LedgerRecordId;          // the travelling force (T1 record)
  int TransportRecordId;       // the aircraft/vehicle, -1 for foot
  vector Origin;  vector LandingZone;  float StartedAt;  float EtaSeconds;
}
```

`ERR_OccupationPlan` owns the pool, the objective list and the live orders, and
ticks every 5 s (staggered). It is created and ticked by `ERR_GameMode` on the
existing tick path — **do not add a timer**.

---

## 5. Deployment methods

Method selection is a pure rule (`ERR_DeployRules.Select`): urgency, distance,
and what transport remains. Roughly — under 1.5 km on foot, 1.5–6 km by convoy,
over 6 km or urgent by air, falling back down the list when transport is gone or
the AI addon is absent.

### Foot

The record's duty becomes `MOVE_TO`; it walks its route virtually and
materialises near players like anything else. No transport consumed.

### Convoy

Consumes a truck. A `CONVOY` record carries the section along an authored road
route. Slow (8–15 min) and ambushable — when physical, it is a real truck with
real soldiers in it. If destroyed, the section and the truck are **permanently**
lost from the pool.

### Air lift

Consumes an aircraft. Three rules make this affordable — read them before
implementing, because the naive version blows the whole agent budget at T+0.

**Cargo is virtual in transit.** Passengers inside a fuselage are invisible.
Never spawn them for the flight. A physical lift is **1 vehicle + 1 pilot**; the
section spawns at the moment of unload. This takes a lift from ~10 agents to ~2
with no visual difference, and it is the single most important optimisation in
this document.

**Two aircraft in the air at once, not ten.** Queue as many lifts as the plan
needs — the island-wide occupation is real — but execute at most
`occupationConcurrentLifts` (default 2) physically. The rest fly as records with
real routes and real timings, and materialise if a player comes near. The player
is only ever in one place; ten simultaneous flights pay full price for drama
nobody witnesses. The existing `ERR_AircraftService.MAX_AIRCRAFT` is 4, and the
controller's demonstrated envelope is vertical flight plus a bounded 20 m route —
ten concurrent cross-map flights with landings is far outside what is proven.
Treat the concurrency as a dial: start at 2, measure with the T7 metrics, raise
it only if the numbers allow.

**Aircraft get a far larger materialisation band than infantry.** A helicopter is
visible and audible at 2–3 km, so lifts materialise at `presenceAirMetres`
(default 2500 m) instead of the 600 m used for foot patrols. This is what
actually delivers "helicopters moving around the island" — they are seen
crossing the valley, not only overhead.

A fleet of ten airframes in the pool is fine; ten in the air simultaneously is
not. Note also that ten AI helicopters converging on one staging area is where
collisions, failed landings and wrecks blocking your own LZs come from.

Core cannot call the aircraft service directly, so:

```
// core
class ERR_TransportProvider          // interface
{
  bool CanLift(vector from, vector to);
  int  Lift(int recordId, vector from, vector landingZone, float deadline);
  int  LiftState(int orderId);       // queued / flying / landed / unloaded / lost
  void CancelLift(int orderId);
}
```

`core` calls the registered provider; `ai` registers an implementation backed by
the existing `ERR_AircraftService` (`addons/ai/Scripts/Game/ERR/ERR_AircraftService.c`),
which already supports route flight, field flight, vertical flight, cancellation
and a `MAX_AIRCRAFT` cap of 4. **Reuse it — do not write a second flight
controller.** `{859B2A6A7DFA9EFB}` style GUIDs must come from
`docs/vanilla-resources.json`; the transport helicopter
`Prefabs/Vehicles/Helicopters/Mi8MT/Mi8MT_unarmed_transport.et` is already
registered there.

Lift sequence — each stage is a state, none of it is per-frame:

1. `LOADING` — section boards at the staging area (virtual unless observed).
2. `IN_TRANSIT` — aircraft flies the route. Physical when near observers; this
   is the moment the design exists for, so let it be seen and heard.
3. `UNLOADING` — lands at the LZ, section disembarks, order is marked `ARRIVED`.
4. Aircraft returns to staging and is returned to the pool.

**LZ selection:** flat ground within 150 m of the objective, not inside a
building footprint, not on the road. Choose from authored LZ points per site
rather than searching terrain at runtime — authoring is cheaper and more
reliable than a runtime flatness search.

**Interruption:** if the aircraft is destroyed in any state before `ARRIVED`,
the section and the aircraft are permanently removed from the pool, the
objective returns to unassigned with a logged reason, and HQ must re-plan.
Same for a convoy. This must be tested, not assumed.

---

## 6. Roadblock construction

A roadblock is built, not spawned. State machine, advancing on the 5 s plan tick:

| State | What exists | Duration |
| --- | --- | --- |
| `SURVEYED` | Nothing. Site reserved by an incoming order | — |
| `MATERIEL` | Flat-packed props: stacked barriers, crates, a parked truck | on arrival |
| `BUILDING` | Props appear in 3 stages as progress crosses 33/66/100% | 6–10 min |
| `MANNED` | Complete; becomes a T3 checkpoint with its garrison | — |
| `DAMAGED` | Partial props, reduced garrison | on attack |
| `ABANDONED` | Props remain, no garrison, never repopulated | garrison wiped |

Rules:

- Progress advances **whether or not anyone is watching**, and props spawn on
  stage transitions regardless of observers. A player who leaves and returns
  finds a finished roadblock. Props are static and cost nothing.
- Soldiers under construction use T4 smart actions so they look like they are
  working. Never all of them — keep a sentry.
- Destroying props during `BUILDING` drops progress and can return the site to
  `MATERIEL`. Destroying it repeatedly must not loop forever: after two resets
  HQ abandons that junction and spends the section elsewhere.
- Leave a drivable gap. A roadblock that fully seals a road can soft-lock a
  route; it should slow and expose the player, not wall them in.
- At most **4 construction sites at once** (`occupationBuildSites`).

---

## 7. Interaction with HQ and fairness

- Dormant records **never observe and never report**. Only physical units
  generate contacts. Enforce in code.
- Deployment orders are HQ traffic: they travel the existing radio model
  (`ERR_HQNetwork`) with its latency and failure rules. Severing HQ's radio chain
  delays or loses deployment orders — killing radio operators slows the
  occupation, which is exactly the intended counterplay.
- HQ's contact-driven re-prioritisation reuses the scored tasking from T5. The
  occupation plan proposes; HQ's priorities re-order the queue.

---

## 8. Caps (all settings, all enforced, all logged on refusal)

| Setting | Default | Meaning |
| --- | --- | --- |
| `activeAgentBudget` | 60 | Global active enemy agents (T2 owns enforcement) |
| `occupationSections` | 16 | Total sections in the pool |
| `occupationTransportAir` | 2 | Transport aircraft |
| `occupationTransportRoad` | 3 | Trucks |
| `occupationConcurrentOrders` | 5 | Deployments in transit at once |
| `occupationConcurrentLifts` | 2 | Air lifts flown **physically** at once; others fly as records |
| `presenceAirMetres` | 2500 | Materialisation band for aircraft (infantry use 600) |
| `occupationBuildSites` | 4 | Simultaneous construction sites |
| `occupationOrderSeconds` | 120 | Cadence between new orders |
| `occupationFallbackSeconds` | 900 | Alarm fallback if nothing is detected |

---

## 9. Work breakdown

Implement in order. One agent per step is fine; steps O3 and O4 can run in
parallel after O2.

- **O1 — Pool, objectives and plan skeleton.** `ERR_ForcePool`,
  `ERR_OccupationObjective`, `ERR_OccupationPlan` with the priority queue and the
  5 s tick. Authored staging areas and objective list in `EveronSites.conf`.
  Start state: prison garrison only, everything else empty.
- **O2 — Deployment orders and transit.** `ERR_DeploymentOrder`,
  `ERR_DeployRules.Select`, foot and virtual transit, arrival handover to the
  objective. Permanent pool loss on destruction.
- **O3 — Air lift.** The `ERR_TransportProvider` interface in core, the `ai`
  implementation over `ERR_AircraftService`, authored LZ points, load/fly/unload
  states, loss handling.
- **O4 — Convoy.** Road routes, truck + section as a `CONVOY` record, ambush and
  loss handling, blocked-route fallback to foot.
- **O5 — Roadblock construction.** The state machine, staged props, progress,
  damage and abandonment, handover to T3 checkpoints.
- **O6 — Adaptation and proof.** Contact-driven re-prioritisation, cordon
  formation, plus the metrics and the measured comparison run from T7.

---

## 10. Acceptance criteria

1. At T+0 the island holds troops only at the prison and its two nearby patrols;
   measured active agents at mission start are under 20.
2. Within 10 minutes of the alarm, the radio station and the helipad have
   garrisons that **arrived**, and the journal shows how each got there.
3. A player positioned along a lift route sees a real helicopter fly, land,
   unload soldiers and depart.
4. Destroying that helicopter before it unloads permanently removes those
   soldiers and that aircraft from the pool; the objective is logged as
   unassigned and is still empty ten minutes later.
5. A player watching a junction sees a roadblock built in stages over minutes,
   not appear at once. Leaving and returning shows progress continued.
6. Active agents never exceed `activeAgentBudget` at any sample during a
   20-minute occupation, and never exceed 20 in the first minute after the alarm
   despite the full deployment queue being issued.
7. A lift in transit costs 2 agents, not 10 — verified in the metrics output.
7. With the AI addon absent, occupation still completes by road and foot.
8. Restarting the mission leaves no deployment, aircraft, convoy or prop behind.
9. `python3 tools/check.py` passes.

## 11. Tests

`tests/test_occupation_plan.py`

- Priority order is respected while the pool lasts, and objectives are refused
  once the pool is empty rather than spawning free sections.
- Pool accounting: a lost deployment permanently decrements sections and
  transport; totals never go negative and never regenerate.
- Cadence and concurrency caps hold under a burst of eligible objectives.

`tests/test_deployment_rules.py`

- `Select` picks foot under 1.5 km, convoy in the middle band, air over 6 km, and
  falls back correctly when transport is exhausted or no provider is registered.
- ETA scales with method speed and distance.
- A destroyed transport moves the order to `LOST` and releases the objective.
- A lift in transit reports zero passenger agents; the section's agents appear
  only on unload, and the count matches the section strength.
- The physical-lift cap holds: with 6 queued lifts and a cap of 2, exactly 2 are
  flown physically and the other 4 remain records with valid ETAs.

`tests/test_roadblock_build.py`

- Progress crosses the three prop stages exactly once each, in order.
- Progress advances with no observers present.
- Two resets lead to abandonment, not an infinite rebuild loop.
- The drivable gap is preserved in every completed variant.

---

## 12. Do not

- Do not spawn the island's garrisons at mission start "for now" — the staged
  arrival is the feature, not an optimisation to add later.
- Do not write a second flight controller; use `ERR_AircraftService` through the
  provider interface.
- Do not launch a fleet of helicopters at once. Ten physical lifts is ~90 agents
  before a single garrison exists, front-loads the whole occupation into five
  minutes, and stages nine flights where no player can see or stop them.
- Do not spawn passengers for a flight. Cargo is virtual until unload.
- Do not let core reference `ai` classes.
- Do not make deployments invulnerable or teleport them on failure. If the player
  breaks a deployment, it stays broken.
- Do not exceed the caps to make a demo look better.