jakub
6a667d8deb
Include the current addon, terrain integrations, tools, regression tests and recorded development evidence.
42 lines
8.9 KiB
Markdown
42 lines
8.9 KiB
Markdown
# Town garrisons
|
||
|
||
After the prison opens, approaching within 700 metres horizontally of a native named town, city, village or settlement activates its population attempt. Each settlement rolls **3–10 enemy soldiers once per round**, using the selected enemy faction's infantry roster. Duplicate map descriptors within 50 metres share the same entry.
|
||
|
||
The squad must fit on clear, navigable ground within 200 metres of the settlement's map centre. Every soldier's actual spawn point must be **at least 700 metres from every controlled player**, including unconscious teammates. Placement leaves a small extra margin. If another player is inside the town, the terrain is unsuitable, navigation is still loading, or the mission force budget is full, the town waits. It never relaxes the distance to fill its quota. A rapid approach can therefore leave a town empty until a safe approach becomes possible.
|
||
|
||
The owner first plans the whole formation and loads the faction resources, then creates at most one character in each background work slice. It rechecks player positions and placement clearance immediately before each creation, and player positions again afterwards. The group has no queued native roster slots, so a delayed expansion cannot create additional soldiers beside an approaching player. A native creation/admission failure cancels that attempt rather than repeatedly replenishing part of a squad.
|
||
|
||
All members enter the existing force ledger, intel, equipment and VirtualHQ systems. Each squad requests a physical HQ manpack through the existing equipment service. Initially it guards its assembly area; all members are available for delivered HQ hunting/investigation orders. Town proximity itself does not reveal player positions to HQ: normal AI observations and radio delivery still apply. These squads are distinct from the permanently reserved hospital/camp guards.
|
||
|
||
Town soldiers are not replaced after casualties and are not despawned/recreated as players cross the activation boundary. One shared worker runs every 100 ms, alternating town and object services. Each slice performs one small-cell query, one placement candidate, one resource load, or one soldier creation; completed/exhausted jobs yield to other eligible towns. Failed complete placement searches wait 30 seconds before retrying. Native calls cannot be preempted, so this is a work-count bound rather than a guaranteed frame-time ceiling. The existing finite force budget applies. The owner and its pending work are stopped with HQ at round teardown.
|
||
|
||
The 700-metre rule here applies to these new town formations. Existing mission preparation and other reinforcement systems retain their separate lifecycle rules.
|
||
|
||
## Diagnostics and validation
|
||
|
||
Look for `TOWN GARRISON` in the HQ log. Admission records include the settlement name/identifier, map position, squad size, minimum player distance measured during creation, and HQ role. Deferred attempts explain why they cannot spawn; repeated waiting messages are limited to one per minute per town. The usual `SPAWN GROUP`/`SPAWN MEMBER` events retain individual identities.
|
||
|
||
`tests/test_town_garrisons.py` executes the actual distance/activation policy with exact boundaries, split players, empty/invalid observations and a player crossing the exclusion distance. `tests/test_intel_registration.py` checks the actual HQ registration method's town radio selection and unrestricted order eligibility. The isolated `town-garrisons` Workbench fixture exercises native map descriptors, navigation, three- and ten-member physical squads, blocked placement with a second observer in town, HQ binding and no replacement after elimination. It is not a live dedicated-server playtest.
|
||
|
||
The 24 September 2026 local Workbench test completed with **12 passing assertions and no script/runtime failures**. Minimum player distances at creation were 718 m for the three-man squad and 720 m for the ten-man squad. Repository checks passed. Existing RHS/WCS localization and vanilla resource keyword errors remain in the native log. The runner hit a transient exiting-process classification error during cleanup; a separate read-only follow-up confirmed that its private prefix was idle and addon sources were unchanged. Original runner results are preserved alongside the follow-up in `.local/analysis/town-garrisons-2026-09-24`.
|
||
|
||
## Factory and infrastructure guards
|
||
|
||
The **Forces → Configure guards** page has **Soldiers per guarded site** (`objectGuardCount`, or `/esc mission objectguards set N`). The range is 0–16 soldiers per site, default 8; zero disables these additional guards. All three guard settings are captured when the round's HQ is created and changes apply next round. Existing town populations keep their separate 3–10 soldier / 700 m rules.
|
||
|
||
After the prison opens, the service discovers nearby industrial, military and infrastructure structures from their prefab paths or map descriptor types. It groups structures within 250 m into one site, rather than spawning a squad for each building. Props, vehicles, weapons, characters, building fragments, flags and ruins are excluded. Custom terrain objects need a recognizable structure path or descriptor; unlabelled custom assets are not guaranteed to be discovered.
|
||
|
||
Sites activate within 1,400 m, but every actual guard spawn must remain at least **1,000 m horizontally from every controlled player**. Unsafe or unnavigable sites wait, and rapid approaches or split players may prevent some guards from spawning. There are at most 32 discovered sites, 24 stored structures per site subject to the shared mission force budget. Discovery queues nearby 250 m cells every ten seconds, shares cells between overlapping observers, and processes one cell per discovery slice. Completed static cells are cached for the round (up to 16,384 per service); stale queued cells are discarded and become eligible for discovery on a later visit. Roof searches resume one footprint column at a time and ground searches resume their candidate cursor.
|
||
|
||
**Guard every Nth eligible site** (`objectGuardEvery`, `/esc mission objectevery set N`) accepts 1–4, default **3** for new and older configurations without this key. It selects every first, second, third or fourth compound in discovery order. Skipped compounds are remembered for the round; rescanning or another player approaching does not reroll them. The existing 32-discovered-site cap includes skipped sites. This reduces occupied compounds, not the configured soldiers per occupied compound. Green choice buttons mark saved values; press Apply to save a draft choice.
|
||
|
||
**HQ participation** (`objectGuardHQMode`, `/esc mission objecthq set N`) accepts **0: hold positions**, **1: half to HQ** (default), or **2: all to HQ**. With the default, half the soldiers stay as fixed guards (the extra soldier stays when the count is odd). Each has its own small defend post and is reserved from general HQ retasking. Any responders form a mobile squad that VirtualHQ can order away. With hold positions selected, every guard is reserved from HQ retasking; all-to-HQ leaves no fixed posts. Both use the selected enemy faction and the existing equipment, radio and observation systems; proximity activation does not tell HQ where players are.
|
||
|
||
Fixed guards first try tower and chimney platforms, then other roofs or raised interior floors. Placement traces require solid support under the whole footprint, sufficient standing space and an open outlook. Narrow rims, holes, steep surfaces and enclosed flues are rejected. If no usable post is found within the bounded search, the guard uses the ordinary navigable ground planner. Responders always use navigable ground. These are finite formations with no replacement waves after casualties and no distance-based respawn cycle.
|
||
|
||
`OBJECT GUARDS` logs identify skipped sites, the density factor, HQ mode and planned fixed/response split. `TOWN GARRISON` admission logs include the role, post coordinate and minimum player distance. The setting persistence, boundaries, fixed/response split, support rules and fixed-post HQ admission hook are exercised by the repository tests. Native validation evidence for this addition is recorded separately in `docs/evidence/object-guards-2026-10-06`.
|
||
|
||
The 6 October 2026 isolated Linux engine test spawned eight soldiers at a real Everon industrial compound: four fixed guards on four separate light-tower platforms approximately 15.11 m above ground, and four mobile ground soldiers. All eight survived the 33-second observation after AI release. Each tower guard received a physical HQ manpack, all four fixed groups were reserved, and the response group remained eligible for HQ orders. Geometry probes also tested 80 real structures. This proves the exercised placement/registration path, not every custom terrain, chimney asset or a multiplayer firefight.
|
||
|
||
The 7 October density/HQ controls compile in the isolated Reforger 1.8.0.13 runtime. Focused policy, settings migration/persistence and menu-contract checks pass; the new menu page and density changes still need an in-game playtest.
|