#87 · stacks/the-settlers-iii-remake

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/13 Source owner: stacksjs/the-settlers-iii-remake. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Implement visibility-aware minimap modes. Navigate camera and original unit commands. Show truthful contextual alerts and selection.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Shared stx controls read player views and issue commands. Browser/native render adapters consume the same projection, assets, animation state, and input coordinates. Sound follows actual events.

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

Implement visibility-aware minimap modes.
Navigate camera and original unit commands.
Show truthful contextual alerts and selection.
The visible result agrees with the underlying simulation or platform state, including failure paths.
Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

Navigate through minimap and alert history.
Verify hidden entities cannot leak through UI.
Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

Upstream release and adoption

Application behavior belongs here. If a reproduction identifies a framework defect, repair and release its owning source first, update Stacks where affected, then install the verified packages here.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

Implementation commits and relevant upstream issue links.
Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
Published package versions, downstream lockfile identity, and release receipts when affected.
Remaining limitations stated explicitly. Partial work does not close this issue.

Completed in 7de3cb9 and 1cadd3f, following the manual's overview map (in_menu/menu.htm, "The Overview Map", SHA-256 6823c1be…16bb).

Visibility-aware minimap modes: the overview map shows only explored land, with fog over land not currently seen. A white frame marks the playing area on screen.
- Territory display: player colours, land and sea, or terrain.
- Settlers display: all, soldiers only, or none.
- Buildings display: on or off.
It is drawn from the player's observation, so buildings and settlers outside the player's sight cannot leak through it (resources/game/minimap.ts).
Camera and unit commands: a left click on the overview moves the view. A right click orders the marked soldiers or thief there with the same modifiers as on the map: CTRL forced, SHIFT waypoint, ALT patrol or pilfer. Selection, groups and recall come from #54.
Truthful contextual alerts: chronicle entries that refer to an explored place or a currently visible entity carry a Show button that centres the view. Alerts about unexplored places or unseen entities lead nowhere.

Tests (tests/unit/minimap.test.ts):

the overview's coordinate mapping
a hidden enemy tower and soldier absent from the pixels, with no enemy colour anywhere
each display mode
alert targets limited to what the player may know

Verified in the browser: the overview renders the explored hexagon with the view frame, and the toggles redraw it (terrain colours read back from the canvas). The pane was hidden during that check, so screenshots lagged; state was read from the DOM and canvas.

The manual's three small "focus" buttons beside the overview are not recreated yet. They belong with the control-center structure in #85.

[S3-085] Complete minimap, alerts, and original navigation

S3-085: Complete minimap, alerts, and original navigation