Bug Reporting for Games With Procedural Cities

Procedural cities stack two hard problems on top of each other. First you generate a road network and parcel layout, then you bake a navmesh over it so pedestrians and vehicles can move. Both can fail in ways that only show up in one specific generated block: a road that ends in a wall, a roundabout with no exit, a navmesh island that traps an NPC, a sidewalk that does not connect to the crossing. Players report a stuck taxi or a dead-end alley, and you have no way to reach that block because your city regenerated overnight. The fix is to capture the inputs that rebuild the city deterministically and the location of the failure. This post covers exactly what that means.

Two generation layers, twice the failure surface

A procedural city is generated in stages, and bugs can originate in any of them. The layout stage places districts, roads, and blocks. The parcel stage subdivides blocks into lots and buildings. The navigation stage bakes a navmesh and connects it to roads and doors. A defect in one stage often only becomes visible in a later one: a road generated with a tiny gap looks fine until the navmesh fails to bridge it and a car halts forever. To reproduce that, you need to regenerate all stages identically, which means capturing the seed and parameters that drive every stage, not just the final symptom.

Because the stages interact, the most useful reports identify both the symptom and the location. An NPC frozen at an intersection might be a navmesh hole, a missing link between two mesh patches, or a layout that produced an impossible turn. You cannot tell which from a video. But with the seed and the intersection coordinate you regenerate the city, inspect the navmesh around that node, and see immediately whether the road, the parcel, or the bake is at fault. The generated nature of the world is exactly why precise location plus world identity is non-negotiable.

Capture the seed and the layout parameters

Start with the city seed and the full set of layout parameters: block size distribution, road density, district rules, intersection styles, and any constraints like rivers or terrain that the city was generated to respect. A city is the deterministic output of these inputs, so capturing them lets you rebuild the identical street grid. As with all procedural systems, record the generator version too, because a change to road-merging logic will reshape every block from the same seed and turn a fixed bug into one you can no longer find.

If your city responds to player actions, capture that state as well. Roads that get blocked by events, buildings that unlock or collapse, dynamic traffic density, or time-of-day routing all change the navigation picture. A taxi that gets stuck only during a parade needs the parade state in the report, not just the seed. Treat the city as seed plus parameters plus any runtime mutations, and your regeneration will match what the player actually navigated rather than a pristine starting state that never had the bug.

Navmesh state and stuck agents

Navigation failures are the signature procedural city bug, so capture navigation context specifically. When an agent is stuck, record its position, its current path or the fact that it has none, its destination, and the navmesh polygon it is standing on. A null path means the planner could not connect start to goal, which points at a navmesh island or a missing off-mesh link. A path that exists but the agent will not follow points at a different problem, like a dynamic obstacle or a collision shape blocking a doorway. Distinguishing these up front saves enormous time.

Navmesh islands are common in generated cities because the bake operates on geometry that the layout stage produced without guaranteeing global connectivity. A sidewalk segment that does not quite touch its crossing becomes an isolated patch, and any agent that wanders onto it is trapped. If you can run and log a connectivity check after each bake, you catch many of these before players do. When one slips through, the agent position and seed let you regenerate the city, highlight the disconnected polygon, and fix the bake or the layout rule that left the gap.

Keep city generation deterministic

Reproduction requires that the same seed and parameters always build the same city, including the same navmesh. Cities break determinism in familiar ways: parallel block generation with shared state, iteration over spatial hash maps without a stable order, and navmesh bakes that depend on the order geometry was submitted. Any of these produces a city that differs slightly run to run, so the disconnected road in a player's report simply will not be disconnected when you regenerate. Route randomness through a seeded stream and make every stage's output a pure function of its inputs.

Pay particular attention to the navmesh bake, which is often the least deterministic stage because it may use external libraries with their own tolerances and threading. If the bake is not deterministic, snapshot enough of its result, or the geometry feeding it, to reconstruct the failing patch even if you cannot regenerate it bit for bit. The goal is always the same: given a report, you can return to the exact broken block and study it, rather than accepting that procedural cities are simply mysterious and unfixable.

Setting it up with Bugnet

Bugnet's in-game report button is ideal for capturing this context without bothering the player. The SDK already records device and platform details; you add custom fields for the city seed, layout parameters or version, the player or agent coordinates, and navigation state like current path status and target. Because the button snapshots state at the moment of the report, a player who taps it next to a frozen taxi hands you the taxi's exact position and the seed that built the block around it. That is a runnable reproduction, not a vague description of a stuck car.

Occurrence grouping helps you see which navigation failures are systemic. A bake rule that leaves sidewalk islands will trap agents across many seeds and many blocks, and Bugnet folds those reports into one issue with a count so you prioritize the pattern over the one-off. Filter by generator version to separate fixed from live, filter by district type if a particular rule misbehaves, and keep every seed and coordinate in one dashboard. That turns a flood of stuck-NPC complaints into a single, well-located engineering task you can actually close.

Tools, tests, and durability

Build a developer command that loads a city from a seed and parameter set and teleports to a coordinate, with a navmesh overlay that draws polygons, links, and islands in distinct colors. Most city navigation bugs are obvious the instant you can see the mesh, and invisible until then. When you fix a disconnected road or an island, capture the seed and location in a regression test that regenerates the city and asserts full navmesh connectivity from a sample of nodes, so the defect cannot quietly return after you tune a layout rule.

The recurring theme across procedural systems holds here too. A city is a deterministic function of its inputs across every generation stage, and if you capture those inputs plus the failure location you can rebuild and revisit any block forever. Set up the capture once, lean on the navmesh overlay, and grow a connectivity test corpus over time. The sprawling, ever-changing city stops being a place where bugs evaporate and becomes a map you can drive straight back into, every time a player finds the corner you never could.

Procedural cities fail at the seams between generation stages. Capture the seed, layout, and navigation state and every stuck NPC becomes reproducible.