EscapistsReintroduced/docs/living-island/README.md

Living island — plan and agent rules

Goal: Everon should feel occupied — patrols that actually move, manned roadblocks, soldiers doing something other than standing — without raising the active AI count. The target is a constant, bounded agent budget (default 60 enemy agents) regardless of how much "activity" exists on the map.

The core idea: simulate many, spawn few

Most of the island's forces exist as records, not entities. A record has a position, a route, a strength and a duty. A slow tick advances records along their routes with plain arithmetic — no AI, no navmesh, no entity. A record is materialised into a real SCR_AIGroup only when a player is close enough to observe it, or when HQ needs it in contact. When the player leaves, it goes back to being a record, keeping its position and losses.

This is what buys the "living island" feeling cheaply: twelve patrols can be crossing the map at once while only the two near players cost anything.

ERR_ForceLedger        records: id, kind, position, route, strength, duty, importance
   |
   |-- ERR_ForceSimulation   advances dormant records along routes (2 s tick, pure math)
   |-- ERR_PresenceBudget    decides which records are physical right now (3 s tick)
   |        |-- spawns  -> SCR_AIGroup.SpawnMembers()
   |        |-- dormant -> SCR_AIGroup.DespawnMembers()
   |
   +-- consumed by ERR_HQ (ai addon) for tasking, ETA and availability

Hard invariant — fairness: only physical units observe and report contacts. A dormant record never generates a sighting. This protects the HQ design, where enemy knowledge must be earned through line of sight and radio.

Layer 2: presence without population

A site feels occupied because of evidence, not head count. Evidence is free — static props cost no CPU. So roadblocks, barriers, parked vehicles and lit windows are permanent; the soldiers manning them are conditional.

Layer 3: soldiers doing something

Vanilla smart actions (SCR_AISmartActionComponent) let an existing soldier lean on a wall, smoke, or work on a vehicle instead of standing at a waypoint. This costs no extra agents — it changes what the agents you already pay for are doing.

Task order

Do these in order; each builds on the previous one. One agent per task.

Task	File	Depends on
T1	T1-force-ledger.md — records + route simulation	—
T2	T2-presence-budget.md — spawn/dormant arbitration under a cap	T1
T3	T3-checkpoints.md — roadblocks and manned checkpoints	T1, T2
T4	T4-smart-actions.md — idle activity at sites	T2
T5	T5-hq-integration.md — HQ tasks ledger units, gets ETAs	T1, T2
T6	T6-ambient-signals.md — cheap signs of life	T2
T7	T7-performance.md — caps, metrics, thrash prevention	all
T8	T8-hq-memory.md — HQ belief: decaying contacts, searched ground	T5
T9	T9-pursuit.md — alert states, hunting, air search, cordons	T5, T8
T10	T10-ai-migration.md — port the old AI mod's proven behaviour under HQ	T5, T8, T9
O1–O6	OCCUPATION.md — how the island gets occupied after the alarm	T1, T2

T3 and T4 can run in parallel once T2 lands. T6 can run in parallel with T5. T8 and T9 are what make the island hunt rather than merely be occupied; T9 depends on T8, because HQ cannot search for what it does not remember.

---

Rules every agent must follow

Paste this section into each agent along with its task file.

Licensing — non-negotiable

This project is an independent successor. The original Escapists mod and its ScrtCore / ScrtSharedContent dependencies are under SCRT-ND (an APL-ND variant) which forbids derivatives. Therefore:

• Never copy code, config, layouts 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 fails the build on these.
• Only vanilla Arma Reforger resources and resources owned by this repository may be referenced. Every {GUID}path must either be in docs/vanilla-resources.json or be owned by a .meta file in this repo.
• Reimplementing a mechanic from scratch is fine. Copying an implementation is not.

Project constraints

• Five addons only: core, ai, intel, chat, map. Do not add addons or external dependencies.
• Dependency direction: ai, intel, map depend on core; chat depends on all. core must never reference ERR_HQ or anything from another addon. Core defines interfaces (see ERR_CommandService); companions implement them.
• The living-island ledger belongs in core, because the base scenario must work without the AI addon. HQ integration (T5) goes in ai.

Performance rules — the whole point of this work

1. No per-frame work. Every tick in this subsystem is ≥ 1 s. Stagger work by unit id (id % N) so all units never update on the same frame.
2. No allocation inside loops. Reuse member arrays; clear rather than reallocate. Do not allocate an array<AIAgent> per unit per tick.
3. Spatial bucketing for proximity. 500 m cells, as already done in ERR_HQNetwork.Add/Build. Never do an all-pairs distance scan.
4. Hard caps everywhere, with a logged refusal when hit. Never let a count grow unbounded.
5. Prefer vanilla behaviour over custom steering. Issue a waypoint and let the engine drive; do not write per-frame movement code.
6. Hysteresis and dwell time. Spawn and despawn radii must differ, and a unit must stay in its state a minimum time before flipping. Thrash is the main performance risk in this design.

Code style

• Match the surrounding file's indentation (older files use tabs).
• New lines stay under 120 characters. The repo already has 420 lines over 200 characters; do not add more.
• Put decision logic in pure static rule classes (see ERR_DiscoveryMapRules, ERR_MissionRules) so it can be tested without the engine. Entity manipulation stays in the service class.
• Small classes. Do not extend ERR_GameMode or add another 100-field object.

Validation — required before you report done

1. python3 tools/check.py must pass.
2. Add Python tests using tests/policy_harness.py: body(path, signature) extracts a real function body from the .c file and run(code) compiles and executes it as C++. Test the pure rule classes this way. Follow the pattern in tests/test_admin_session.py.
3. Report honestly. This repo separates "compiles and passes scripted fixtures" from "verified in the real game". If you did not run it in Workbench, say so. Do not write evidence files claiming runtime verification you did not perform.

Verified engine APIs you will need

All confirmed present in the installed vanilla scripts (1.6.30):

API	Where	Notes
SCR_AIGroup.SetLifecyclePolicy(policy, spawnDist, despawnDist, veryNearBlockDist)	Entities/SCR_AIGroup.c:2921	Manual (default) or ProximityDriven
SCR_AIGroup.SpawnMembers() / DespawnMembers()	:2783 / :2870	Dormant group keeps its entity and records alive/dead counts, so a later SpawnMembers() re-materialises the right number
ChimeraAIGroup.SetImportance(int) / AIGroup.GetImportance()	generated/AI/ChimeraAIGroup.c:22	Pass SCR_EAISpawnImportance values
SCR_EAISpawnImportance	AI/SCR_EAISpawnImportance.c	LOW 0.50, NORMAL 0.70, HIGH 0.90, CRITICAL 1.00 — fraction of AIWorld's active-AI limit the tier may consume, enforced by AIWorld::CanActivateGroup
SCR_EAIGroupLifecyclePolicy	AI/SCR_EAIGroupLifecyclePolicy.c	Manual = we drive it; ProximityDriven = group self-manages against ObserversSystem
ObserversSystem.GetObservers(out array<vector>)	generated/System/ObserversSystem.c:59	Cheap observer positions; also GetObserversMP
SCR_AIGroup.SetEliminateWhenReached(true) + GetOnEliminatedWhenReached()	used at SCR_AmbientPatrolSpawnPointComponent.c:212	If a player reaches a patrol that could not spawn (budget full), the area counts as cleared and the group retires instead of popping in later
SCR_AISmartActionComponent (ReserveAction, ReleaseAction, GetOnActionEnd, GetOnActionFailed)	AI/Components/SCR_AISmartActionComponent.c	Idle activities
SCR_SmartActionWaypoint.SetSmartActionEntity(IEntity, string tag)	AI/Behavior/SCR_SmartActionWaypoint.c:31	Sends a group to perform a tagged smart action

Reference implementation worth reading (vanilla, not the original mod — safe to read and learn from): Components/Locations/SCR_AmbientPatrolSpawnPointComponent.c and Systems/SCR_AmbientPatrolSystem.c.

Existing repo helpers — use these, do not reinvent

• ERR_Actors.Spawn/DeleteSpawned/Ground/Players/Alive/CanFight/Group — addons/core/Scripts/Game/ERR/ERR_Actors.c
• ERR_Resources.SearchWaypoint/MoveWaypoint/CycleWaypoint/DefendWaypoint — waypoint prefab GUIDs
• ERR_SiteService / ERR_SiteDefinition / ERR_LocationComponent — authored sites and their guards
• ERR_HQNetwork — the 500 m spatial cell pattern to copy
• ERR_Settings.Get("key") — integer settings; add new keys here
• ERR_HQJournal via ERR_HQ.Event(kind, message) — ai addon only; core code logs with PrintFormat("Reintroduced [ledger]: ...")