# Shared field-map capture ownership

Current visual asset: the held atlas now uses the authored solid book in
`Assets/Items/ERR_Atlas/ERR_Atlas.xob`, with geometric spiral wire, covers and a
page block. The folded-paper UV corrections and printed binding described in
the historical sections below no longer apply to this item. Page selection keeps
the existing left-hand grip steady. The atlas now has a native right-hand reach,
sweep and return, paired with a separate lightweight turning sheet. See
`source/atlas/README.md` for source, build details and validation limits.

`ERRM_SharedMapComponent` briefly uses the native map renderer to capture the held item's surface, then freezes its own render target. The backpack Shared Field Map stays in hand; it overrides the stock fullscreen transition while retaining native gadget ownership, visibility and focus animations. Ordinary stolen maps remain stock `SCR_MapGadgetComponent` items and still open fullscreen. It uses the existing map singleton; it does not own every later view displayed by that singleton.

While held, the surface refreshes every five seconds on clients within 20 metres of the holder. Each client binds its own off-screen target to the replicated item, so nearby players can render the same map around the holder without sending texture pixels over the network. Native menus and held stock maps take priority. This implementation does not establish multiplayer/JIP visual acceptance by itself.

The folded paper model has two rotated face panels in its texture atlas. The material compensates with a 270-degree turn and panel tiling (U 1.5, V 2, U offset 1). The render-target child has a fixed 744×1024 logical size, and its map canvas and marker overlay fill that child. UI DPI scaling changes pixel resolution but preserves the approximate physical page ratio. Sizing only the root did not work: its full-window child inherited the game viewport dimensions (501×225 in the hidden fixture), stretching the paper and changing the displayed area with the player’s screen. The earlier 90-degree turn also left labels upside down. Opening/closing either type of map never changes global map settings.

The earlier boolean-only ownership check allowed a delayed pan/close callback to act on a replacement fullscreen or auxiliary map. It also restored the local character camera whenever any shared-map item was deleted, even if that spare or remote item had never captured anything. This conflicts with the camera suppression performed by a native fullscreen map.

The component now retains its exact `MapConfiguration` and requires all of the following before panning, closing, or restoring the character camera: its capture flag, the same current map singleton, an open native map, the exact configuration object, and the configuration's original root widget. Both configuration and root identity matter: installed `SCR_MapEntity.SetupMapConfig` reuses its active configuration when the requested mode is unchanged and mutates `RootWidgetRef`. A pointer-only test would still permit one same-mode capture to interfere with another.

Interrupted or completed capture hides and disables only its own render target and clears its ownership before closing the native map. Hiding is essential: `SetEnabled(false)` alone does not prevent the target from repainting a blank canvas after `CloseMap` cleanup. The hidden target retains its last rendered pixels on the mesh. `CloseMap` already restores the character camera; Stop and deletion no longer perform an additional unconditional camera write. A stale Finish callback whose view has been replaced cannot close, pan or focus the replacement. It uses the existing retry path while the item remains in hand, waiting for that view to close before attempting its own capture again. Stop removes this component's capture, centering, completion and priority callbacks, clears holder/map/config references, and freezes its target. Widget destruction remains separate from passing a deleted entity to the renderer.

Installed primary source references (read-only inspection):

- `scripts/Game/Map/SCR_MapEntity.c`: `GetMapConfig` returns `m_ActiveMapCfg`; `OpenMap` closes any prior view and assigns the new config/root, then suppresses the local character camera; `CloseMap` restores it; `SetupMapConfig` can reuse and retarget the same config object.
- `scripts/Game/Components/Gadgets/SCR_MapGadgetComponent.c`: stock `ModeSwitch` limits local focus/camera UI to the local controlled character. Its focus path schedules native map opening and fading, so it must not be triggered immediately by a stale capture callback against a replacement UI.
- `scripts/Game/Components/Gadgets/SCR_GadgetManagerComponent.c`: default gadget-state invokers exist for remote as well as local characters. `RegisterInitialGadgets` reapplies an already replicated gadget mode; this audit therefore does not claim that vanilla's JIP path omits mode initialization.

The meaningful offline regression `tests/test_shared_map_ownership.py` executes the actual ownership, release, finish, camera, stop and deletion methods with explicit native-boundary doubles. It covers distinct replacement configurations, same-object/different-root reuse, another current world/map singleton, never-owned deletion, delayed duplicate callbacks, the deferred-capture path, cancellation of this instance's callbacks while another instance's callback remains, and a missing game context during teardown. The test does not compile Enforce, render a texture or establish multi-client/JIP behavior. Native UI replacement and physical-surface visibility have separate local fixtures; remote streaming still requires multiplayer validation.

The in-hand-only change preserves discovery knowledge, marker lists, setting semantics, network serialization and shared-map resource identity. Core discovery remains a separate owner. Its current production knowledge transitions are monotonic and the current settings catalog has no shared-map enable/disable switch; no hypothetical downgrade or disabled-setting defect was inferred here.

## Physical-map validation — 11 October 2026

The [final hidden Workbench fixture](evidence/held-map-20261011/report.json)
passed all seven checks, including real gadget animations, repeated capture,
remaining in hand and a stock map opening while a background capture was active.
The [held-page screenshot](evidence/held-map-20261011/err-held-map.png) confirms
terrain remains drawn between captures. Earlier attempts exposed a blank page
after closing the renderer; hiding the target before canvas cleanup fixed it.
Multi-client/JIP viewing and readability from all viewing angles remain
playtest items. The fixture and its probe option are Workbench-only.

## Paper orientation and sizing follow-up — 11 October 2026

The user’s full-size screenshot exposed upside-down labels and a blank vertical
band that the earlier cropped fixture missed. Rotation is now 270 degrees.
The fixed dimensions belong on the render-target child, not its workspace root;
the map canvas and marker overlay both fill that child.

The [follow-up native fixture](evidence/held-map-uv-20261011/report.json) passes
eight checks, including a new measurement of the actual texture and canvas
aspect. Its [whole-paper view](evidence/held-map-uv-20261011/err-held-map-whole-paper.png)
shows terrain/water covering the page without the blank band. The fixture is
local Everon at a small editor viewport; Chernarus, legible place names and
remote clients are not independently validated by these screenshots.

## Terrain-edge capture correction — 11 October 2026

The next Chernarus screenshot still showed a blank rectangle. The preceding
Everon evidence established paper coverage at that interior location, not
coverage near a terrain boundary. A native Chernarus reproduction measured a
15360 m map and a captured north edge of 16610.1 m for a holder at Z=14906.5.
Vanilla `FitPanBounds` explicitly permits the centre to reach the map edge,
leaving half a fullscreen viewport outside the mapped region.

`FitPaperView` now fits the entire paper viewport inside the native map’s
`Offset()` and `Size()` rectangle. Interior views retain their requested zoom
and centre. Near an edge, the centre shifts inward; on small terrains, the zoom
increases enough to fit the page. A two-pixel margin accommodates native integer
pan rounding. This does not create cartography beyond a terrain’s map bounds.

Capture centering now waits for `GetOnMapOpenComplete`, then allows the normal
500 ms capture interval. Previously the fixed 100 ms request could be ignored
during native initialization; the reproduction’s first capture retained zoom 1
rather than 0.12. A five-second timeout still releases the renderer if readiness
never arrives. Release/cancellation/deletion remove this instance’s ready-event
listener as well as its scheduled callbacks.

`tests/test_shared_map_viewport.py` executes the actual framing calculation for
the observed failure, all corners, shifted origins, multiple resolutions and a
small terrain. The ownership regression also executes the ready callback and
checks foreign/cancelled readiness and delayed-completion replacement.

The [Chernarus edge run](evidence/held-map-bounds-20261011/report.json) passes
nine native checks with the holder 50 m from the northern edge. The measured
page spans Z=6467.99..15351.3 inside the 0..15360 map, including the first capture
at zoom 0.12. Capture, aspect and ordinary-map menu checks also pass. The GM
carrier retained its external camera in screenshots, so these are coordinate
and lifecycle evidence, not independent confirmation of the final held-page
appearance. No multiplayer/JIP acceptance is claimed.


## Fixed printed sheets and map-key gesture — 11 October 2026

The paper no longer samples the holder's position to choose its view. It starts
at the northwest sheet and uses a fixed print scale of 0.5 logical pixels/metre,
about 1488 x 2048 metres per sheet. Adjacent sheets overlap by at least ten
percent; the grid derives from native terrain bounds, including shifted origins
and rectangular terrains. Chernarus's 15360 m bounds produce 12 columns x 9 rows;
Everon's 12800 m bounds produce 10 columns x 7 rows. Native map zoom limits bound
the requested detail. DPI scaling changes texture resolution, not sheet coverage.

Only the visible sheet is rendered. The existing five-second refresh and shared
renderer arbitration remain. Plain-mode cartography has no GPS module; native
unit descriptors are explicitly hidden for each paper capture. Discovered
mission objective markers retain their separate presentation and knowledge rules.

Arrow input runs in the native gadget manager update, only for the living local
holder, outside menus, dialogs and chat/edit fields. A short native lower/raise movement accompanies a page change;
this is not a new animated folding mesh. Controller-owned, rate-limited server
RPCs validate the actual held item before updating its replicated sheet index.
The index is also included in initial replication serialization. This implements
remote/JIP state transport; actual multi-client viewing still needs a playtest.

A quick double press of the existing bound GadgetMap action (M by default) opens
the native interactive map. From storage the first press equips immediately;
while already holding paper, a single press waits 450 ms before stowing so a
second press can select the interactive view. Ordinary map gadgets retain their
native behavior. All pending input and animation callbacks are cancelled on the
relevant gadget/controller teardown paths.

An atlas overview with numbered rectangles and numpad page selection was
subsequently proposed. That index UI is not part of this fixed-sheet change.


The [final native keyboard run](evidence/held-map-pages-20261011/report.json)
passes 16 checks, including an actual arrow press through the controller RPC,
restored gadget focus, blocked menu input, interactive opening from hand and
storage via double M, preserved sheet selection, single-M stowing and ordinary
map compatibility. The fixture uses only a private headless, muted Workbench
instance. Earlier ActivateAction calls activated actions rather than supplying
keyboard input and did not validate physical key handling; the final run injects
real key events on the test process's own Xwayland display.

Native `MapEscape` also fires on M in this setup, before the `GadgetMap` callback.
The Shared Field Map defers that native escape handler for one tick so the map
key gesture can consume it. A genuine Escape retains native stowing behavior.
Interactive cleanup checks the exact fullscreen root and current map instance;
a stale item cannot close a replacement map UI. Other held-paper captures yield
the native renderer while the local player requests the interactive view.

The page geometry and capture ownership tests pass, and the development source
bundle preview accepts the new script. Native multiplayer/JIP propagation,
final hand-motion appearance and the atlas index remain separate validations.
Input contexts follow the engine's documented priority/overlay model:
[Bohemia Input Manager documentation](https://community.bistudio.com/wiki/Arma_Reforger:Input_Manager).


## OCRAM OLOP runtime atlas (2026-10-11)

The backpack item is now named **OCRAM OLOP Autoatlas**. The earlier fixed-sheet
implementation above is retained underneath an automatically generated jacket
and index. It starts on the red/yellow cover, not the northwest sheet. The active
loaded world supplies the terrain title; native cartography supplies the cover
thumbnail, index map and detail pages. There are no terrain-specific bitmap assets
or Workshop dependencies. The existing folded-paper mesh and native hand motion
remain; this is not a new spiral-bound 3D book model.

The cover shows the terrain extent and detail-sheet count. Page 1 is the overview;
numbered rectangles correspond to detail pages 2 onward, in west-to-east,
north-to-south order. Boundaries lie halfway between sheet centres; detail views
overlap. Each detail page has neighbouring page numbers and a metric scale bar.
A physical print ratio such as 1:100,000 would be misleading for a virtual page,
so none is invented. Overview/jacket place labels are temporarily suppressed to
avoid crowding; their prior visibility is restored before releasing an owned
capture, and never over a replacement map's style.

Controls: Enter (either key) or right from cover opens the index; Enter or right/down from index opens the first
sheet; left/up from index returns to the cover. Detail arrows select neighbouring
sheets without wrapping. Numpad digits followed by either Enter key select a printed
page number; 0 + Enter returns to the index. The local entry buffer expires after
six seconds or clears when UI takes focus. Only the committed, validated selection
replicates. Double-tap M still opens the native interactive map.

Only the selected page's widgets and texture exist. Decorations are rebuilt on
page changes, not every frame or five-second map refresh. Large worlds reduce
print detail when needed to cap the index at 400 cells; impossible extreme aspect
ratios fail layout rather than entering an unbounded loop. No player position is
used for page selection, index content or scale. Objective pins appear only on
detail sheets according to the existing discovery rules.

Validation: `docs/evidence/held-atlas-20261011/` records 18 passing native checks
on Everon, including physical numpad page 37, 0 + Enter, UI gating, held/stored
M gestures, and ordinary-map coexistence. The cover, index and detail screenshots
were visually inspected. The renderer and page geometry checks and development
source bundle preview also pass. Geometry covers Chernarus (108 detail sheets),
shifted origins, rectangular/small terrains, large-world caps and degenerate-layout
termination. Other terrains were not rendered in this run; remote visibility and
join-in-progress still require multiplayer validation. The test process was
hidden, muted and cleaned up with the isolated prefix verified idle.


### Enter and movement binding correction

Both main Enter and numpad Enter confirm typed page numbers. With no number,
Enter opens the index from the cover, or the first detail page from the index.
Atlas input uses the native overlay/exclusive combination (`Flags 0xa`) so its
bound arrows, digits and Enter keys do not also reach lower input contexts.
Unclaimed controls such as WASD remain available; chat and menu guards remain.
The physical-key fixture checks actual displacement: a held right arrow turns a
page with less than 4 cm movement, while W moves the same actor more than 10 cm.
Polling `CharacterForward` late in the gadget update is not a reliable movement
check, because native processing has already consumed that action value.
Long atlas labels now use native bounded font fitting instead of fixed font size.


### Dedicated-server page selection correction

The input-only Workbench tests missed a dedicated-server failure. Native
`MapEntity.Size()` reports zero dimensions on Linux dedicated, even when the
terrain is fully loaded. `PaperLayout` previously returned false, so the server
silently left the replicated page on the cover after every valid request.
Both client and authority now derive the grid from
`WorldEntity.GetTerrain(0, 0).GetTerrainBoundBox`. General world bounds are not
interchangeable: Everon includes outlying objects down to x=-107.382 and z=-100,
which would produce a mismatched grid if treated as terrain dimensions.

`docs/evidence/held-atlas-dedicated-20261011/` preserves the Linux reproduction:
with native map dimensions still zero, before: layout=false and cover unchanged;
after: layout=true, 10x7 sheets, page 37 selected. The dedicated process used a
copied addon and loopback bind, and was reaped. RKS2 logs read over SSH also contain
the native missing-map-size warning; the running server was not changed.
This verifies the authority's native layout/selection path, not a full networked
client-to-server/JIP session. Owner RPC replies now confirm numbered selections
or explain held-item, terrain-layout and page-range rejection. Rejection logging
is limited to one message per controller per ten seconds.

### Atlas legibility and binding update (2026-10-11)

The index uses small, translucent corner page tags and thin grid lines instead
of opaque central labels. Native place names remain visible at a compact size.
The paper capture uses darker forest/contour inks, stronger water colours, and
outlined main/minor roads on the index. Capture cleanup restores configuration
colours, road borders and name sizes only while it still owns the native renderer.
The atlas still has no player-position marker or automatic location selection.

The cover now draws shaded silver wire loops along its left edge, using one
batched canvas in physical pixel coordinates to match UI scaling. These are
printed spiral-binding graphics, not new 3D geometry. Page changes use the native
map lower/raise gesture with a one-second pause and recapture while lowered;
rapid page requests are limited to 1.1 seconds. This does not add a custom hand
animation or a deforming paper/page-curl model.

The isolated hidden/muted native run is recorded under
`docs/evidence/held-atlas-readable-spiral-20261011/`. Native capture/input checks
and the focused geometry, viewport and renderer-ownership checks are used here;
this is not a new dedicated multiplayer/JIP validation.

### Whole-island road visibility correction (2026-10-11)

The native road configuration hides main roads above layer 4, as well as minor
roads, tracks and bridges at their own thresholds. The previous index override
only enabled minor roads, leaving the arterial network missing. The index now
explicitly enables all four road types, with tracks drawn as thin brown lines.
The native road defaults are restored during owned capture cleanup as before.
A hidden native Everon capture visibly restores the road through Saint-Philippe;
20 capture/input checks pass. Evidence: `docs/evidence/held-atlas-roads-20261011/`.
This is a native Everon visual check, not a new Chernarus multiplayer test.

### Binding on every sheet (2026-10-11)

The original spiral was cover-only and too thin. The cover, overview and detail
pages now all draw bright thick loops against a dark left spine. Their map,
headings and navigation occupy a separate area to the right, without a binding
overlay masking terrain. Detail cartography is scaled uniformly at the existing
744:1024 ratio; geographical page coverage and numbering remain unchanged. The
metric scale uses the reduced paper viewport. The index uses the widest clear
area beside the spine, retaining the visible road network in the native preview.
No experimental changes to native layer ceilings or road LOD are included.

Evidence: `docs/evidence/held-atlas-visible-binding-20261011/`. Hidden native
Everon capture/input checks pass (20); index and detail screenshots show binding
and the index retains the Saint-Philippe road. Geometry, viewport, ownership and
source-bundle checks passed. This remains artwork on the existing held-map mesh,
not a new 3D spiral-bound book model. No live server update was performed.

### Native atlas hand turn (2026-10-11)

The atlas attachment now explicitly enters `ERRAtlasControl`, which wraps the
stock map graph with a short right-arm IK action. This preserves the stock
left-hand hold. Only this atlas interprets the generic native item-use command
as a page turn; normal maps and consumables retain their own animation graphs.
A separate non-replicated sheet turns about the spine while the replicated page
selection remains authoritative. Rendering commits partway through the sweep.
Only nearby clients animate that sheet, and its timer/entity are removed on
completion or interruption. No character bone matrices or whole-item transforms
are overwritten by the script.

Evidence: `docs/evidence/held-atlas-hand-turn-20261011/`. The hidden native fixture
passed its 20 existing checks and recorded five successful actions, a moving
right hand and a clean return to idle with the sheet deleted. Multiplayer visual
synchronization and all-stance acceptance remain unverified.

### Regional atlas overviews (2026-10-12)

The island index now links to regional overviews inserted before the detail
maps. Regions group up to three columns by three rows of existing detail sheets;
edge regions are balanced to avoid a thin last strip. Regional extents and
printed grids use the same geographic sheet boundaries. No position marker or
player-based centring is introduced. Cover remains 0, island index remains 1;
regional pages start at 2 and printed detail numbers follow them. Packed detail
state IDs remain stable.

Numbers on the island refer to regional pages; numbers on a region refer to
its detail pages. Enter opens the first detail sheet from a region, and returns
to the parent region from a detail sheet. Numpad selection and 0 + Enter to the
island index remain available. Regions can also be browsed with the arrows.
Page turns retain the existing sideways hand action and bounded repeat count.
Only the selected page is rendered; the region list is computed arithmetically.

Evidence: `docs/evidence/held-atlas-regions-20261012/`. Hidden native rendering
and navigation checks passed, plus the sheet geometry and viewport harnesses.
Live multiplayer visual validation remains outstanding.