- {resources ?
: null}
+ {resources ?
: null}
setSurface('closed')}
onCollect={() => void collect()}
onExplore={() => closeThen(() => onRequestExplore?.())}
@@ -556,6 +626,32 @@ export function RealmHud({
onRecenter={() => closeThen(onRecenterKeep)}
onRequestReturn={() => closeThen(onRequestReturn)}
onSettings={() => setSurface('settings')}
+ onWorkers={genericWorkersActive ? () => setSurface('workers') : undefined}
+ />
+ ) : null}
+
+ {genericWorkersActive && workerRoster && surface === 'workers' ? (
+ setSurface('menu')}
+ onRecallAllWorkers={onRecallAllWorkers}
+ onRecallWorker={onRecallWorker}
+ onSelectWorker={(worker) => {
+ setSelectedWorkerId(worker.workerId);
+ setSurface('worker-inspection');
+ }}
+ roster={workerRoster}
+ workers={ownedWorkersForUi}
+ />
+ ) : null}
+ {genericWorkersActive && selectedWorker && surface === 'worker-inspection' ? (
+ setSurface('workers')}
+ worker={selectedWorker}
/>
) : null}
diff --git a/src/components/realm/RealmMapScreen.css b/src/components/realm/RealmMapScreen.css
index 1071cb6c..f48b09ea 100644
--- a/src/components/realm/RealmMapScreen.css
+++ b/src/components/realm/RealmMapScreen.css
@@ -196,6 +196,9 @@
z-index: 2;
right: max(0.8rem, env(safe-area-inset-right));
bottom: max(4.55rem, calc(env(safe-area-inset-bottom) + 4rem));
+ display: grid;
+ justify-items: end;
+ gap: 0.5rem;
width: min(28rem, calc(100vw - 1.6rem));
margin: 0;
color: #f8f0d6;
@@ -205,6 +208,24 @@
text-shadow: 0 1px 8px #293018;
}
+.realm-map-screen__fallback-copy button {
+ min-height: 2.5rem;
+ padding: 0 0.85rem;
+ border: 1px solid rgb(255 241 184 / 62%);
+ border-radius: 0.4rem;
+ background: rgb(20 27 17 / 72%);
+ color: #fff1b8;
+ font: 700 0.75rem/1 Inter, ui-sans-serif, system-ui, sans-serif;
+ cursor: pointer;
+}
+
+.realm-map-screen__fallback-copy button:hover,
+.realm-map-screen__fallback-copy button:focus-visible {
+ border-color: #fff1b8;
+ outline: 2px solid #fff1b8;
+ outline-offset: 2px;
+}
+
.realm-hud {
position: absolute;
z-index: 5;
@@ -499,6 +520,39 @@
font-weight: 800;
}
+.realm-cell-navigator__water {
+ display: grid;
+ gap: 0.35rem;
+ margin-top: 0.8rem;
+}
+
+.realm-cell-navigator__water > span {
+ color: var(--realm-muted);
+ font-size: 0.6875rem;
+ font-weight: 800;
+ letter-spacing: 0.12em;
+}
+
+.realm-cell-navigator__water-row {
+ display: grid;
+ gap: 0.28rem;
+ padding: 0.58rem 0.65rem;
+ border: 1px solid rgb(145 217 216 / 22%);
+ border-radius: 0.35rem;
+ background: rgb(19 59 70 / 24%);
+}
+
+.realm-cell-navigator__water-row > div {
+ display: flex;
+ gap: 0.35rem;
+}
+
+.realm-cell-navigator__water-row > div button {
+ width: auto;
+ padding: 0.28rem 0.45rem;
+ font-size: 0.625rem;
+}
+
.realm-cell-navigator__community {
display: grid;
gap: 0.22rem;
diff --git a/src/components/realm/RealmMapScreen.tsx b/src/components/realm/RealmMapScreen.tsx
index 4ad09e52..4ac9a304 100644
--- a/src/components/realm/RealmMapScreen.tsx
+++ b/src/components/realm/RealmMapScreen.tsx
@@ -32,12 +32,16 @@ import type {
} from '../../settings/graphicsPreference';
import type { CanonicalWarpkeepRealmSnapshot } from '../../spacetime/warpkeepBackendTypes';
import { isCanonicalGenesisSnapshot } from '../../spacetime/canonicalGenesisSnapshot';
-import type { ReadyRealmResourcePresentation } from './realmResourcePresentation';
+import type {
+ ReadyRealmResourcePresentation,
+ RealmEconomicResourceKey
+} from './realmResourcePresentation';
import { CastleInspectionPanel } from './CastleInspectionPanel';
import { FoodFarmInspectionPanel } from './FoodFarmInspectionPanel';
import { GoldMineInspectionPanel } from './GoldMineInspectionPanel';
import { LoggingCampInspectionPanel } from './LoggingCampInspectionPanel';
import { StoneQuarryInspectionPanel } from './StoneQuarryInspectionPanel';
+import { WaterInspectionPanel } from './WaterInspectionPanel';
import { RealmAccessibilityControls } from './RealmAccessibilityControls';
import {
RealmCastleLabels,
@@ -54,6 +58,11 @@ import {
} from './createRealmScene';
import { resolveCanonicalWaterProjection } from './realmWaterProjection';
import { projectRealmWaterRevisionTerrainMetadata } from './realmWaterTerrainProjection';
+import {
+ realmWaterNavigatorBodies,
+ resolveRealmWaterInspectionRecords,
+ type RealmWaterInspectionRecord
+} from './realmWaterInspectionPresentation';
import {
resolveRealmGoldNodePresentations,
type RealmGoldNodePresentation
@@ -110,6 +119,7 @@ import type { RealmCastleProjectionFrame } from './realmTypes';
import {
CASTLE_LABEL_LAYOUT_MAX_CASTLES,
castleProfileLabel,
+ fallbackCastleIsInViewBox,
fallbackCastleProjection,
publicProfileForCastle,
resolvePersistentCastleLabels,
@@ -143,8 +153,23 @@ import {
resolveRealmEscape,
type RealmCameraTarget
} from './realmInteractionState';
+import {
+ classifyRealmRendererFailure,
+ initialRealmRendererLifecycle,
+ REALM_RENDERER_CONTEXT_RESTORE_TIMEOUT_MS,
+ shouldRetryRealmRenderer,
+ transitionRealmRendererLifecycle,
+ type RealmRendererFailure,
+ type RealmRendererLifecycle
+} from './realmRendererRecovery';
import './RealmMapScreen.css';
import './RealmCastlePresentation.css';
+import type {
+ ReadyWorkerProjection,
+ ReadyWorkerResourceState,
+ RealmWorkerDestinationPresentation,
+ WorkerRosterPresentation
+} from './realmWorkerPresentation';
export {
BLOCKED_SHARED_FOREST_PROJECTION_SIGNATURE,
@@ -183,6 +208,16 @@ type RealmMapScreenProps = Readonly<{
onDispatchStoneExpedition?: (siteId: string) => Promise;
/** Guarded owner-only Stone settlement reducer; never supplied to observers. */
onClaimStoneExpedition?: () => Promise;
+ workerProjection?: ReadyWorkerProjection;
+ workerRoster?: WorkerRosterPresentation;
+ workerResourceState?: ReadyWorkerResourceState;
+ onDispatchWorker?: (
+ workerId: string,
+ resourceKind: RealmEconomicResourceKey,
+ siteId: string
+ ) => Promise;
+ onRecallWorker?: (workerId: string) => Promise;
+ onRecallAllWorkers?: () => Promise;
graphicsPreference?: GraphicsPreference;
resolvedGraphicsQuality?: GraphicsQualityTier;
audioMuted?: boolean;
@@ -273,6 +308,12 @@ function CanonicalRealmMapScreen({
stoneExpedition,
onDispatchStoneExpedition,
onClaimStoneExpedition,
+ workerProjection,
+ workerRoster,
+ workerResourceState,
+ onDispatchWorker,
+ onRecallWorker,
+ onRecallAllWorkers,
graphicsPreference,
resolvedGraphicsQuality,
audioMuted,
@@ -322,6 +363,20 @@ function CanonicalRealmMapScreen({
() => projectRealmWaterRevisionTerrainMetadata(sharedTileMetadata, waterCells),
[sharedTileMetadata, waterCells]
);
+ const waterRecords = useMemo(
+ () => resolveRealmWaterInspectionRecords(waterCells, projectedTileMetadata),
+ [projectedTileMetadata, waterCells]
+ );
+ const waterRecordsByKey = useMemo(
+ () => new Map(waterRecords.map((record) => [record.cellKey, record] as const)),
+ [waterRecords]
+ );
+ const waterRecordsByKeyRef = useRef>(waterRecordsByKey);
+ waterRecordsByKeyRef.current = waterRecordsByKey;
+ const navigatorWaterBodies = useMemo(
+ () => realmWaterNavigatorBodies(waterRecords),
+ [waterRecords]
+ );
const otherCastles = snapshot.castles;
const surface = useMemo(
() => createAuthoritativeRealmTerrainSurface(
@@ -456,6 +511,32 @@ function CanonicalRealmMapScreen({
const stoneNodesBySiteId = useMemo(() => new Map(
stoneNodes.map((node) => [node.siteId, node] as const)
), [stoneNodes]);
+ const workerDestinations = useMemo(() => {
+ if (workerProjection?.mode !== 'active') return Object.freeze([]);
+ const occupied = new Set(workerProjection.occupations.map((occupation) => occupation.nodeKey));
+ const destinations: RealmWorkerDestinationPresentation[] = [];
+ const append = (
+ resourceKind: RealmEconomicResourceKey,
+ resourceLabel: string,
+ nodes: readonly GatheringNodePresentation[]
+ ) => {
+ for (const node of nodes) {
+ if (node.availability !== 'available' || occupied.has(`${resourceKind}:${node.siteId}`)) {
+ continue;
+ }
+ destinations.push(Object.freeze({
+ resourceKind,
+ siteId: node.siteId,
+ label: `${resourceLabel} · Tier ${node.tier} · cell ${node.coord.q}, ${node.coord.r}`
+ }));
+ }
+ };
+ append('food', 'Wheat Farm', foodNodes);
+ append('wood', 'Logging Camp', woodNodes);
+ append('stone', 'Stone Quarry', stoneNodes);
+ append('gold', 'Gold Mine', goldNodes);
+ return Object.freeze(destinations);
+ }, [foodNodes, goldNodes, stoneNodes, woodNodes, workerProjection]);
const activeWagons = useMemo(() => {
if (observerMode) return Object.freeze([]);
const items: RealmActiveWagonMenuItem[] = [];
@@ -593,9 +674,25 @@ function CanonicalRealmMapScreen({
}), [surface, terrainPlacements, tileMetadataByKey]);
const quality = useMemo(() => initialQuality(qualityOverride), [qualityOverride]);
const qualitySpec = REALM_QUALITY_SPECS[quality];
- const [rendererMode, setRendererMode] = useState('loading');
+ const [rendererLifecycle, setRendererLifecycle] = useState(
+ initialRealmRendererLifecycle
+ );
+ const rendererMode: RendererMode = rendererLifecycle.state === 'static-unsupported'
+ ? 'fallback'
+ : rendererLifecycle.state === 'ready' ? 'webgl' : 'loading';
const rendererModeRef = useRef('loading');
rendererModeRef.current = rendererMode;
+ const rendererLifecycleRef = useRef(rendererLifecycle);
+ rendererLifecycleRef.current = rendererLifecycle;
+ // Scene callbacks can arrive after React has already retired their effect.
+ // Keep the active generation in a synchronous ref so stale scenes cannot
+ // publish ready/failure state into a newer renderer.
+ const activeRendererGenerationRef = useRef(0);
+ const lastSuccessfulRendererGenerationRef = useRef(0);
+ const rendererRecoveryTimerRef = useRef(null);
+ const rendererRecoveryNonceRef = useRef(0);
+ const [rendererRecoveryNonce, setRendererRecoveryNonce] = useState(0);
+ const rendererAttestationRef = useRef | null>(null);
const [cameraMode, setCameraMode] = useState('realm');
const [interaction, dispatchInteraction] = useReducer(
realmInteractionReducer,
@@ -623,10 +720,21 @@ function CanonicalRealmMapScreen({
const handledKeyboardIntentSequenceRef = useRef(-1);
const reducedMotion = useReducedMotionPreference();
const fallbackSurface = useMemo(
- () => fallbackSurfacePresentation(surface),
- [surface]
+ () => fallbackSurfacePresentation(surface, { focusCoord: keepCoord, radius: 16 }),
+ [keepCoord, surface]
);
const viewBox = fallbackSurface.viewBox;
+ const fallbackVisibleCastleIds = useMemo(() => new Set(
+ allCastles
+ .filter((castle) => fallbackCastleIsInViewBox(castle, viewBox))
+ .map((castle) => castle.castleId)
+ ), [allCastles, viewBox]);
+ const visibleFallbackFoundations = useMemo(() => fallbackFoundations.filter((foundation) => {
+ const castleId = foundation.id === 'own-keep'
+ ? ownCastle.castleId
+ : Number(foundation.id.replace(/^peer-castle-/, ''));
+ return fallbackVisibleCastleIds.has(castleId);
+ }), [fallbackFoundations, fallbackVisibleCastleIds, ownCastle.castleId]);
const selectedCell = selectedCellFor(surface, selectedCoord, keepCoord);
const selectedTerrainKindCandidate = tileMetadataByKey.get(hexKey(selectedCoord))?.terrainKind;
const selectedTerrainKind = isRealmTerrainKind(selectedTerrainKindCandidate)
@@ -657,10 +765,15 @@ function CanonicalRealmMapScreen({
&& 'stoneSiteId' in selectedInspectorTarget
? stoneNodesBySiteId.get(selectedInspectorTarget.stoneSiteId)
: undefined;
+ const inspectorWater = selectedInspectorTarget !== null
+ && 'cellKey' in selectedInspectorTarget
+ ? waterRecordsByKey.get(selectedInspectorTarget.cellKey)
+ : undefined;
const goldNodeAtSelectedCell = goldNodes.find((node) => sameCoord(node.coord, selectedCoord));
const foodNodeAtSelectedCell = foodNodes.find((node) => sameCoord(node.coord, selectedCoord));
const woodNodeAtSelectedCell = woodNodes.find((node) => sameCoord(node.coord, selectedCoord));
const stoneNodeAtSelectedCell = stoneNodes.find((node) => sameCoord(node.coord, selectedCoord));
+ const waterAtSelectedCell = waterRecords.find((record) => sameCoord(record.coord, selectedCoord));
const ownProfile = profileRecords.get(ownCastle.castleId)?.profile;
const focusedCastleId = interaction.cameraTarget.kind === 'castle'
? interaction.cameraTarget.castleId
@@ -731,6 +844,8 @@ function CanonicalRealmMapScreen({
inspectorFocusRef.current?.focus({ preventScroll: true });
} else if (target.kind === 'stone-quarry-inspector') {
inspectorFocusRef.current?.focus({ preventScroll: true });
+ } else if (target.kind === 'water-inspector') {
+ inspectorFocusRef.current?.focus({ preventScroll: true });
} else if (target.kind === 'castle-label') {
const label = rootRef.current
?.querySelector(`.realm-castle-label[data-castle-id="${target.castleId}"]`)
@@ -833,6 +948,19 @@ function CanonicalRealmMapScreen({
if (focusSite) sceneRef.current?.focusCell(node.coord);
}, []);
+ const selectWaterCell = useCallback((record: RealmWaterInspectionRecord, focusWater = true) => {
+ selectedCoordRef.current = { ...record.coord };
+ dispatchInteraction({
+ type: 'activate-water-cell',
+ cellKey: record.cellKey,
+ bodyId: record.bodyId,
+ regime: record.regime,
+ coord: record.coord,
+ cameraIntent: focusWater ? 'focus-water' : 'preserve'
+ });
+ if (focusWater) sceneRef.current?.focusWaterCell?.(record.cellKey);
+ }, []);
+
const openActiveWagon = useCallback((wagon: RealmActiveWagonMenuItem) => {
if (!activeWagons.some((candidate) => (
candidate.resource === wagon.resource && candidate.siteId === wagon.siteId
@@ -866,9 +994,78 @@ function CanonicalRealmMapScreen({
woodNodesBySiteId
]);
- const markRendererUnavailable = useCallback(() => {
- rendererModeRef.current = 'fallback';
- setRendererMode('fallback');
+ const markRendererFailure = useCallback((failureInput?: RealmRendererFailure | unknown) => {
+ const current = rendererLifecycleRef.current;
+ const failure = failureInput && typeof failureInput === 'object' && 'code' in failureInput
+ ? failureInput as RealmRendererFailure
+ : classifyRealmRendererFailure(failureInput, current.state);
+ if (failure.code === 'webgl-unavailable') {
+ rendererModeRef.current = current.everReady ? 'loading' : 'fallback';
+ const nextLifecycle = transitionRealmRendererLifecycle(current, {
+ type: 'webgl-unsupported',
+ failure
+ });
+ rendererLifecycleRef.current = nextLifecycle;
+ setRendererLifecycle(nextLifecycle);
+ return;
+ }
+ // Stop accepting pointer/camera mutations synchronously, before React has
+ // committed the loading/recovering state to the DOM. The scene itself
+ // applies the same guard while a WebGL context is lost.
+ rendererModeRef.current = 'loading';
+ if (shouldRetryRealmRenderer(current, failure)) {
+ const nextAttempt = current.attempt + 1;
+ const nextLifecycle = transitionRealmRendererLifecycle(current, {
+ type: 'recover',
+ failure,
+ attempt: nextAttempt
+ });
+ rendererLifecycleRef.current = nextLifecycle;
+ setRendererLifecycle(nextLifecycle);
+ if (failure.code !== 'context-lost') {
+ rendererRecoveryNonceRef.current += 1;
+ setRendererRecoveryNonce(rendererRecoveryNonceRef.current);
+ }
+ if (failure.code === 'context-lost') {
+ if (rendererRecoveryTimerRef.current !== null) window.clearTimeout(rendererRecoveryTimerRef.current);
+ rendererRecoveryTimerRef.current = window.setTimeout(() => {
+ rendererRecoveryTimerRef.current = null;
+ const latest = rendererLifecycleRef.current;
+ const timeoutFailure: RealmRendererFailure = {
+ code: 'context-restore-timeout',
+ retryable: true,
+ phase: latest.state,
+ message: 'The browser did not restore the Realm graphics context in time.'
+ };
+ const failedLifecycle = transitionRealmRendererLifecycle(latest, {
+ type: 'failed',
+ failure: timeoutFailure
+ });
+ rendererLifecycleRef.current = failedLifecycle;
+ setRendererLifecycle(failedLifecycle);
+ }, REALM_RENDERER_CONTEXT_RESTORE_TIMEOUT_MS);
+ }
+ return;
+ }
+ const failedLifecycle = transitionRealmRendererLifecycle(current, { type: 'failed', failure });
+ rendererLifecycleRef.current = failedLifecycle;
+ setRendererLifecycle(failedLifecycle);
+ }, []);
+
+ const retryRenderer = useCallback(() => {
+ if (rendererRecoveryTimerRef.current !== null) {
+ window.clearTimeout(rendererRecoveryTimerRef.current);
+ rendererRecoveryTimerRef.current = null;
+ }
+ const loadingLifecycle = transitionRealmRendererLifecycle(rendererLifecycleRef.current, {
+ type: 'load-start',
+ attempt: 0
+ });
+ rendererLifecycleRef.current = loadingLifecycle;
+ setRendererLifecycle(loadingLifecycle);
+ rendererModeRef.current = 'loading';
+ rendererRecoveryNonceRef.current += 1;
+ setRendererRecoveryNonce(rendererRecoveryNonceRef.current);
}, []);
const isSceneCoordPassable = useCallback((coord: HexCoord) => (
@@ -889,6 +1086,14 @@ function CanonicalRealmMapScreen({
// The scene reserves its restrained ground outline for unoccupied terrain;
// castle identity and raycasting provide the occupied-cell cue without a
// depth-tested line cutting through the wider authored landscape base.
+ if (target?.kind === 'water-cell') {
+ updateHoveredCastleId(undefined);
+ hoveredCoordRef.current = null;
+ sceneRef.current?.setHoveredWaterCellKey?.(target.cellKey);
+ sceneRef.current?.setHovered(null);
+ return;
+ }
+ sceneRef.current?.setHoveredWaterCellKey?.(null);
updateHoveredCoord(target?.coord ?? null);
updateHoveredCastleId(target?.kind === 'castle' ? target.castleId : undefined);
}, [updateHoveredCastleId, updateHoveredCoord]);
@@ -920,8 +1125,13 @@ function CanonicalRealmMapScreen({
if (node) selectStoneNode(node, target.source !== 'wagon');
return;
}
+ if (target.kind === 'water-cell') {
+ const record = waterRecordsByKeyRef.current.get(target.cellKey);
+ if (record) selectWaterCell(record);
+ return;
+ }
selectCoord(target.coord);
- }, [selectCastle, selectCoord, selectFoodNode, selectGoldNode, selectStoneNode, selectWoodNode]);
+ }, [selectCastle, selectCoord, selectFoodNode, selectGoldNode, selectStoneNode, selectWaterCell, selectWoodNode]);
const updateCastleProjection = useCallback((frame: RealmCastleProjectionFrame) => {
latestProjectionRef.current = frame;
@@ -1077,6 +1287,7 @@ function CanonicalRealmMapScreen({
root.dataset.semanticTerrainKindCount = String(telemetry.semanticKindCount);
root.dataset.semanticTerrainFeatureCount = String(telemetry.semanticFeatureCount);
root.dataset.semanticTerrainFeatureDrawCalls = String(telemetry.semanticFeatureDrawCalls);
+ root.dataset.semanticTerrainFeatureCounts = JSON.stringify(telemetry.semanticFeatureCounts);
root.dataset.totalTerrainDetailInstanceCount = String(telemetry.totalDetailInstanceCount);
root.dataset.totalTerrainDetailDrawCalls = String(telemetry.totalDetailDrawCalls);
root.dataset.forestPlacementSource = telemetry.forestPlacementSource;
@@ -1089,7 +1300,18 @@ function CanonicalRealmMapScreen({
root.dataset.grassCacheEntries = String(telemetry.grassCacheEntries);
root.dataset.grassAnimated = String(telemetry.grassAnimated);
root.dataset.grassTargetAnimationCadence = String(telemetry.grassTargetAnimationCadence);
+ root.dataset.grassCandidateCellsByTerrain = JSON.stringify(
+ telemetry.grassCandidateCellsByTerrain
+ );
+ root.dataset.grassActiveCellsByTerrain = JSON.stringify(telemetry.grassActiveCellsByTerrain);
root.dataset.grassCountsByTerrain = JSON.stringify(telemetry.grassCountsByTerrain);
+ root.dataset.grassAverageRetainedPatchesByTerrain = JSON.stringify(
+ telemetry.grassAverageRetainedPatchesByTerrain
+ );
+ root.dataset.grassPaletteLuminanceMin = String(telemetry.grassPaletteLuminanceMin);
+ root.dataset.grassPaletteLuminanceMax = String(telemetry.grassPaletteLuminanceMax);
+ root.dataset.grassPaletteGreenMin = String(telemetry.grassPaletteGreenMin);
+ root.dataset.grassPaletteGreenMax = String(telemetry.grassPaletteGreenMax);
root.dataset.grassCompletelyBareActiveCells = String(telemetry.grassCompletelyBareActiveCells);
root.dataset.grassRejectedByStructureClearance = String(
telemetry.grassRejectedByStructureClearance
@@ -1130,7 +1352,7 @@ function CanonicalRealmMapScreen({
root.querySelectorAll(
'.realm-hud, .realm-hud__actions, .realm-profile-trigger, .realm-resource-rail, '
+ '.castle-inspection, .gold-mine-inspection, .food-farm-inspection, .logging-camp-inspection, '
- + '.stone-quarry-inspection, .realm-cell-navigator'
+ + '.stone-quarry-inspection, .realm-cell-navigator, .water-inspection'
).forEach((element) => observer?.observe(element));
}
window.addEventListener('resize', updateSceneComposition, { passive: true });
@@ -1189,14 +1411,26 @@ function CanonicalRealmMapScreen({
useEffect(() => {
const canvas = canvasRef.current;
if (!canvas || !canUseWebGL()) {
- markRendererUnavailable();
+ markRendererFailure({
+ code: 'webgl-unavailable',
+ retryable: true,
+ phase: 'probing',
+ message: 'WebGL is unavailable on this device.'
+ });
return undefined;
}
let scene: RealmSceneHandle | null = null;
+ const rendererGeneration = rendererLifecycleRef.current.generation + 1;
+ const loadingLifecycle = transitionRealmRendererLifecycle(rendererLifecycleRef.current, {
+ type: 'load-start',
+ attempt: rendererLifecycleRef.current.attempt,
+ generation: rendererGeneration
+ });
+ activeRendererGenerationRef.current = rendererGeneration;
+ rendererLifecycleRef.current = loadingLifecycle;
try {
- rendererModeRef.current = 'loading';
- setRendererMode('loading');
+ setRendererLifecycle(loadingLifecycle);
latestProjectionRef.current = { width: 0, height: 0, castles: [] };
labelMembershipSignatureRef.current = '';
latestVisibleCastleLabelsRef.current = [];
@@ -1209,6 +1443,7 @@ function CanonicalRealmMapScreen({
rootRef.current.dataset.semanticTerrainKindCount = '0';
rootRef.current.dataset.semanticTerrainFeatureCount = '0';
rootRef.current.dataset.semanticTerrainFeatureDrawCalls = '0';
+ rootRef.current.dataset.semanticTerrainFeatureCounts = '{}';
rootRef.current.dataset.waterPresentation = waterCells ? 'pending' : 'unavailable';
rootRef.current.dataset.waterLayoutVersion = '0';
rootRef.current.dataset.waterTriangleCount = '0';
@@ -1225,7 +1460,14 @@ function CanonicalRealmMapScreen({
rootRef.current.dataset.grassCacheEntries = '0';
rootRef.current.dataset.grassAnimated = 'false';
rootRef.current.dataset.grassTargetAnimationCadence = '0';
+ rootRef.current.dataset.grassCandidateCellsByTerrain = '{}';
+ rootRef.current.dataset.grassActiveCellsByTerrain = '{}';
rootRef.current.dataset.grassCountsByTerrain = '{}';
+ rootRef.current.dataset.grassAverageRetainedPatchesByTerrain = '{}';
+ rootRef.current.dataset.grassPaletteLuminanceMin = '0';
+ rootRef.current.dataset.grassPaletteLuminanceMax = '0';
+ rootRef.current.dataset.grassPaletteGreenMin = '0';
+ rootRef.current.dataset.grassPaletteGreenMax = '0';
rootRef.current.dataset.grassCompletelyBareActiveCells = '0';
rootRef.current.dataset.grassRejectedByStructureClearance = '0';
rootRef.current.dataset.grassRejectedBySlope = '0';
@@ -1257,7 +1499,6 @@ function CanonicalRealmMapScreen({
rootRef.current.dataset.stoneMarkerOnlySiteCount = String(stoneNodeCatalog.length);
}
setVisibleCastleLabels([]);
- setCameraMode('realm');
scene = createRealmScene({
canvas,
surface,
@@ -1271,7 +1512,10 @@ function CanonicalRealmMapScreen({
sharedForestLayout: sharedForestProjection.layout,
sharedForestTrees: sharedForestProjection.trees,
waterCells,
+ waterBodies: snapshot.waterBodies,
+ waterEnvironment: snapshot.realmEnvironment,
realmId: snapshot.realm.realmId,
+ rendererGeneration,
// The retired local planner is exposed only to the synthetic dev
// observer. Player scenes wait for the paired shared public tables.
allowLegacyForestFallback: observerMode,
@@ -1285,14 +1529,46 @@ function CanonicalRealmMapScreen({
onTargetHover: handleSceneTargetHover,
onKeepStatusChange: () => undefined,
onCastlesReady: (castleCount) => {
+ if (activeRendererGenerationRef.current !== rendererGeneration) return;
if (castleCount !== expectedCastleCountRef.current) {
- markRendererUnavailable();
+ markRendererFailure({
+ code: 'castle-count-mismatch',
+ retryable: true,
+ phase: 'loading',
+ message: `Expected ${expectedCastleCountRef.current} castles, received ${castleCount}.`
+ });
return;
}
rendererModeRef.current = 'webgl';
- setRendererMode('webgl');
+ const activeLod = canvas.dataset.realmCastleActiveLod;
+ lastSuccessfulRendererGenerationRef.current = rendererGeneration;
+ const readyLifecycle = transitionRealmRendererLifecycle(rendererLifecycleRef.current, {
+ type: 'ready',
+ generation: rendererGeneration,
+ degradedQuality: activeLod === 'compact' || activeLod === 'balanced'
+ ? activeLod
+ : undefined
+ });
+ rendererLifecycleRef.current = readyLifecycle;
+ setRendererLifecycle(readyLifecycle);
updateSceneComposition();
},
+ onCastleLodChange: (activeLod) => {
+ if (activeRendererGenerationRef.current !== rendererGeneration) return;
+ const currentLifecycle = rendererLifecycleRef.current;
+ // An optional model can settle while a WebGL context is lost. Its
+ // presentation upgrade must not clear the recovering/failed state.
+ if (currentLifecycle.state !== 'ready') return;
+ const readyLifecycle = transitionRealmRendererLifecycle(currentLifecycle, {
+ type: 'ready',
+ generation: rendererGeneration,
+ degradedQuality: activeLod === 'compact' || activeLod === 'balanced'
+ ? activeLod
+ : undefined
+ });
+ rendererLifecycleRef.current = readyLifecycle;
+ setRendererLifecycle(readyLifecycle);
+ },
onCastlePresentationTelemetry: updateCastlePresentationTelemetry,
onGoldNodePresentationTelemetry: updateGoldNodePresentationTelemetry,
onFoodNodePresentationTelemetry: updateFoodNodePresentationTelemetry,
@@ -1300,7 +1576,21 @@ function CanonicalRealmMapScreen({
onStoneNodePresentationTelemetry: updateStoneNodePresentationTelemetry,
onTerrainPresentationTelemetry: updateTerrainPresentationTelemetry,
onCastleProjection: updateCastleProjection,
- onRendererUnavailable: markRendererUnavailable,
+ onRendererFailure: (failure) => {
+ if (activeRendererGenerationRef.current === rendererGeneration) {
+ markRendererFailure(failure);
+ }
+ },
+ onRendererContextRestored: () => {
+ if (activeRendererGenerationRef.current !== rendererGeneration) return;
+ if (rendererRecoveryTimerRef.current !== null) {
+ window.clearTimeout(rendererRecoveryTimerRef.current);
+ rendererRecoveryTimerRef.current = null;
+ }
+ rendererRecoveryNonceRef.current += 1;
+ setRendererRecoveryNonce(rendererRecoveryNonceRef.current);
+ },
+ onRendererUnavailable: () => undefined,
onSelect: () => undefined,
onTargetSelect: handleSceneTargetSelect
});
@@ -1336,22 +1626,50 @@ function CanonicalRealmMapScreen({
? interactionRef.current.inspectorTarget.stoneSiteId
: null
);
+ scene.setSelectedWaterCellKey?.(
+ interactionRef.current.inspectorOpen
+ && interactionRef.current.inspectorTarget !== null
+ && 'cellKey' in interactionRef.current.inspectorTarget
+ ? interactionRef.current.inspectorTarget.cellKey
+ : null
+ );
scene.setHovered(hoveredCoordRef.current);
const cameraTarget: RealmCameraTarget = interactionRef.current.cameraTarget;
if (cameraTarget.kind === 'castle') scene.focusCastle(cameraTarget.castleId);
else if (cameraTarget.kind === 'cell') scene.focusCell(cameraTarget.coord);
+ else if (cameraTarget.kind === 'water') scene.focusWaterCell?.(cameraTarget.cellKey);
else if (cameraTarget.kind === 'keep') scene.recenterKeep();
else if (cameraTarget.kind === 'founding-district') scene.frameFoundingDistrict();
else scene.showRealm();
- } catch {
- markRendererUnavailable();
+ const attestation = rendererAttestationRef.current;
+ if (attestation && attestation.canvasId === canvas.dataset.realmCanvasIdentity) {
+ scene.restoreCameraAttestation?.(attestation);
+ }
+ } catch (error) {
+ if (activeRendererGenerationRef.current === rendererGeneration) {
+ markRendererFailure(classifyRealmRendererFailure(error, 'loading'));
+ }
}
return () => {
+ if (scene) {
+ try {
+ rendererAttestationRef.current = scene.getCameraAttestation();
+ } catch {
+ rendererAttestationRef.current = null;
+ }
+ }
scene?.dispose();
if (sceneRef.current === scene) sceneRef.current = null;
+ if (activeRendererGenerationRef.current === rendererGeneration) {
+ activeRendererGenerationRef.current = 0;
+ }
+ if (rendererRecoveryTimerRef.current !== null) {
+ window.clearTimeout(rendererRecoveryTimerRef.current);
+ rendererRecoveryTimerRef.current = null;
+ }
};
- }, [foodNodeCatalog, goldNodeCatalog, handleSceneTargetHover, handleSceneTargetSelect, hasNearbyFoundingKeeps, isSceneCoordPassable, keepCoord, markRendererUnavailable, observerMode, ownCastle.castleId, peerCastles, projectedTileMetadata, qualitySpec, reducedMotion, sharedForestProjection, snapshot.realm.realmId, stoneNodeCatalog, surface, updateCastlePresentationTelemetry, updateCastleProjection, updateFoodNodePresentationTelemetry, updateGoldNodePresentationTelemetry, updateSceneComposition, updateStoneNodePresentationTelemetry, updateTerrainPresentationTelemetry, updateWoodNodePresentationTelemetry, waterCells, woodNodeCatalog]);
+ }, [foodNodeCatalog, goldNodeCatalog, handleSceneTargetHover, handleSceneTargetSelect, hasNearbyFoundingKeeps, isSceneCoordPassable, keepCoord, markRendererFailure, observerMode, ownCastle.castleId, peerCastles, projectedTileMetadata, qualitySpec, reducedMotion, rendererRecoveryNonce, sharedForestProjection, snapshot.realm.realmId, snapshot.realmEnvironment, snapshot.waterBodies, stoneNodeCatalog, surface, updateCastlePresentationTelemetry, updateCastleProjection, updateFoodNodePresentationTelemetry, updateGoldNodePresentationTelemetry, updateSceneComposition, updateStoneNodePresentationTelemetry, updateTerrainPresentationTelemetry, updateWoodNodePresentationTelemetry, waterCells, woodNodeCatalog]);
useEffect(() => {
sceneRef.current?.reconcileLiveGatheringState?.(liveGatheringState);
@@ -1381,6 +1699,10 @@ function CanonicalRealmMapScreen({
sceneRef.current?.setSelectedStoneSiteId?.(inspectorStoneNode?.siteId ?? null);
}, [inspectorStoneNode?.siteId]);
+ useEffect(() => {
+ sceneRef.current?.setSelectedWaterCellKey?.(inspectorWater?.cellKey ?? null);
+ }, [inspectorWater?.cellKey]);
+
useEffect(() => {
const handleEscape = (event: KeyboardEvent) => {
// Treat one physical Escape press as one hierarchy step. Ignoring the
@@ -1463,6 +1785,8 @@ function CanonicalRealmMapScreen({
selectWoodNode(woodNodeAtSelectedCell);
} else if (stoneNodeAtSelectedCell) {
selectStoneNode(stoneNodeAtSelectedCell);
+ } else if (waterAtSelectedCell) {
+ selectWaterCell(waterAtSelectedCell);
} else {
sceneRef.current?.focusCell(selectedCoord);
dispatchInteraction({
@@ -1479,16 +1803,31 @@ function CanonicalRealmMapScreen({
if (isPlayableRealmCoord(surface, next)) selectCoord(next);
};
+ // The scene mirrors these counters onto the canvas so a context event can
+ // be diagnosed without exposing implementation details in user copy.
+ const canvasTelemetry = canvasRef.current?.dataset;
return (
@@ -1513,7 +1852,7 @@ function CanonicalRealmMapScreen({
? 'Hegemony lowlands with public frontier castles'
: 'Hegemony lowlands with your authoritative frontier keep'}
- {fallbackFoundations.map((foundation) => (
+ {visibleFallbackFoundations.map((foundation) => (
- {fallbackFoundations.map((foundation) => (
+ {visibleFallbackFoundations.map((foundation) => (
))}
- {!observerMode ? (
+ {!observerMode && fallbackVisibleCastleIds.has(ownCastle.castleId) ? (
) : null}
- {peerCastles.map((castle) => {
+ {peerCastles.filter((castle) => (
+ fallbackVisibleCastleIds.has(castle.castleId)
+ )).map((castle) => {
const world = axialToWorld({ q: castle.q, r: castle.r }, HEX_SIZE);
return (
-
- Detailed terrain is unavailable. Showing the canonical Genesis 001 realm map.
-
+
+
+ WebGL is unavailable on this device. Showing a bounded, accessible view of the
+ canonical Genesis 001 region around your keep.
+
+
+
) : null}
- {rendererMode === 'loading' ? (
+ {rendererLifecycle.state !== 'ready' && rendererLifecycle.state !== 'static-unsupported' ? (