React Ready Flag Bug in Last Thaw Map Replays

Summary

Pixel shares a debugging story from Last Thaw, a browser strategy game where a React ready flag stayed true for the wrong map. The bug caused Pangaea replays to crash on cold loads, while Earth matches and live Pangaea games worked. The announcement explains how lazy-loaded map data and stale state combined to create the issue.

DEV Community

A React "ready" flag that was true for the wrong map

I make Last Thaw, a free browser strategy game. Up to a hundred players start with five settlers on a real map of Earth, cut into 408 regions, and have 30 real days to build an empire while an ice age advances from both poles. It's in early access and I'm looking for people to test it. Most matches are played on Earth, but a match can also be played on Pangaea, the supercontinent of 250 million years ago (the about page has the details). Last week the replay of a finished Pangaea match crashed with this on the error screen: map pangaea is not loaded
Live Pangaea matches worked. Replays of Earth matches worked. Only the replay of a Pangaea match fell over, and only on a cold load. The cause was four lines of React I'd have sworn were fine: a piece of state that answered a question about one prop value and kept answering it after the prop changed. How maps get loaded Earth ships in the main bundle because the home page and the lobby draw it. Pangaea doesn't. Its regions, coast points and sea lanes are a few hundred kilobytes of JSON that most visitors never need, so the web app fetches them the first time a match on that map opens. The shared package keeps a small registry of the maps that have arrived: const registry = new Map();

/* Earth is registered at load; other maps when their JSON arrives. /
export function registerWorld(id: MapId, w: WorldMap): void {
registry.set(id, { id, world: w, byId: new Map(w.regions.map((r) => [r.id, r] as const)) });
}
registerWorld("earth", earthJson as WorldMap);

export function isMapLoaded(id: MapId): boolean {
return registry.has(id);
}
Every helper that needs geography (neighbors, distances, which regions the ice has reached) reads the map through one function, and that function is strict on purpose: function data(): MapData {
const id = resolver(); // which map is in play right now
const d = registry.get(id);
if (!d) throw new Error(map ${id} is not loaded);
return d;
}
I'd rather it throw than quietly fall back to Earth. A Pangaea match drawn with Earth's regions would be a much stranger bug to chase than an error with the map's name in it. On the web side, a component called MapScope puts a map in scope for everything inside it and holds the children back until the map is there: Loading the map...\

}>


That ?? "earth" is the replay page being reasonable. It doesn't know which map the match used until the replay data arrives, so it starts on Earth. The bug Here's MapScope as it was: export function MapScope({ map, children, fallback = null }) {
// true straight away if the map is already loaded
const [ready, setReady] = useState(isMapLoaded(map) && !!assets[map]);

useEffect(() => {
let live = true;
if (isMapLoaded(map) && assets[map]) setReady(true);
else {
setReady(false);
void ensureMap(map).then(() => live && setReady(true));
}
return () => { live = false; };
}, [map]);

if (!ready) return <>{fallback};
current = map; // everything below now reads this map
return <>{children};
}
Read it top to bottom and it looks right. If the map is loaded, ready. If not, not ready, fetch it, then ready. The effect reruns when map changes. Now walk through the replay page on a cold load: The page mounts. The replay hasn't arrived, so map is "earth". Earth is in the bundle, so ready starts out true. The replay arrives. The match was on Pangaea, so the page renders again with map="pangaea". During that render, ready is still true. It was computed for Earth. useState only uses its initial value once, and the effect that would set it to false hasn't run yet, because effects run after the render. So MapScope sets the current map to Pangaea and renders the children. The map component asks for the active world, the registry has no Pangaea, and data() throws. The effect would have fixed everything a moment...
React Ready Flag Bug in Last Thaw Map Replays
Powered by Readybot.io

The latest from Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …