Troubleshooting

The inspector reports missing materials or prefabs

Run Tools > Sorolif > Map Generation > Create Starter Biome Assets for independent settings initialized from Core/Art, or assign production materials and prefabs directly on MapDefinition or through an explicitly assigned BiomeSetting anywhere in the project.

Missing visual assets are warnings unless the related feature cannot operate without them. Use Validate Selected Generator to see all configuration issues before generation.

Generation returns false but a map remains visible

Inspect ProceduralMapGenerationResult.ValidationIssues or the validation section in the inspector. Blocking causes include a null definition, an unsupported map size, an invalid player count, a non-positive cell size, or an unreadable image source.

A failed attempt leaves a 3D preview: terrain and water from the current grid, the previous map if a new preview cannot be built, or a simple terrain with a collider for an invalid initial configuration. The Inspector shows the error and a generation.preview warning. Console messages use warnings so Unity's Error Pause does not interrupt recovery. Unexpected generation exceptions are caught and included as generation.exception with their stack trace.

The generator does not return an earlier successful grid after a failed attempt. Always check Succeeded or the Boolean returned by TryGenerateRuntimeMap. Use PreviewRoot for the visible output; MapRoot, Grid, gameplay score and spawn lists are unavailable on failure. Saving a generation recipe remains disabled until a successful regeneration.

River regions cannot be connected with safe bridges

bridges.connectivity means at least one land region cannot receive a safe crossing with the configured span and landing constraints. Generation continues through the remaining visual stages: mountains, terrain, water, cliff details, biome props, altitude, packing, cleanup and optional screenshots. Plateau-access and player-land-route audit failures also keep their diagnostics without stopping these stages. The finished map remains an unvalidated preview; independently validated path bridges can be shown, but unsafe or missing bridge decks are skipped. A malformed custom bridge prefab is reported as bridges.prefab_invalid and does not stop later visual stages. Increase River Bridge Max Span, reduce River Width, or keep wider, flatter banks clear of cliffs and resources, then regenerate. An error preview does not guarantee that all land regions are playable or reachable.

A river crosses a path or choke corridor

With Has Bridges enabled on a procedural River layout (including a Random layout that resolves to River), a protected choke corridor no longer cuts a continuous river into separate pieces. The generator reopens the river and reserves a bridge perpendicular to the local river course, including when the land regions already connect elsewhere or several paths cross the same river. Water, its bed and naval accessibility remain underneath the deck; land traversal uses the deck height. Assign a usable River Bridge Prefab and regenerate.

A path crossing requires the same river to flow through both lateral sides and dry path continuations on both banks. Oblique paths reconnect to the perpendicular deck over dry terrain. A river that merely touches or follows the path, ends inside it, or meets a path dead end does not request a path bridge. Bases, resources, ramps and plateau reservations keep their existing protection. Lakes, island naval corridors and disabled bridges retain their existing behavior. If the crossing exists but its bridge span, landings or prefab are invalid, the river remains visible in the error preview instead of being filled with land.

A river approaches a base or expansion

Procedural rivers skirt settlement clearings using Player Base Forest Clear Radius and Expansion Forest Clear Radius, including with forests disabled. The same values are exposed in River shape. Existing base, expansion and plateau footprints remain dry. The full channel routes around the clearing, rather than stopping at its boundary and resuming on the other side.

An occupied central clearing takes priority over the primary river's central anchor. A free central passage is retained, and rivers can pass between settlements when their full width fits. If clearings occupy every possible passage, increase map size, reduce River Width or space the settlements farther apart. A river is not carved through a protected clearing to force a crossing.

If a different land region still blocks the global connectivity audit, the error preview can display independently validated path bridges with a usable deck collider. The whole map remains an error preview until a successful regeneration; unsafe or missing decks are not displayed.

A procedural road ends against a plateau wall

Regenerate the map with the current generator. Choke corridors are reserved before the terrain heights are known; their blocked dry segments are now recalculated over the final terrain through legal ramps. The road curves respect plateau edges and cannot cut across a cliff corner. If no legal access exists, the unreachable link is omitted instead of painting a direct road against the wall. River crossing reservations remain unchanged.

Toggling Bridges changes choke roads or hides gizmos

Disable Use Random Seed and keep the same Seed when comparing settings. With a fixed seed, the planned choke points and strategic corridor routes are independent of Has Bridges. The renderer retains their river crossing reservations even if a later bridge or player-route audit fails. On plateaus, blocked dry portions are recalculated through the final ramps; reachable portions remain visible. True river crossings use the bridge deck, and unsafe crossings keep the water and diagnostic. Other player trails can follow different available land connections, so the entire finished map need not be identical.

Bases, expansions and choke gizmos belong to the visible generated map, including an unvalidated preview. Their cached positions survive scene reload and follow the generated root transform, cell size and altitude. Enable Show Gizmos on the root's Generated Map Info component and the global Gizmos switch in the Scene view to display them. Select Map Information on the generator selects that component; see Generated Map Information. An invalid initial fallback has no strategic markers; retaining an earlier map also retains its markers.

Image generation fails

Water, paths or mountains are not visible

Confirm that the corresponding feature is enabled and that its material is assigned. Procedural roads remain curved with Enable Path Smoothing disabled; this switch refines contours rather than choosing another network. Essential town and expansion access is generated first. Increase Path Connection Count for alternative links, Path Branch Count for extra branches, or Wandering Path Count for independent trails. Local streets may deliberately end in pointed dead ends around towns. A road cannot cross an unbridged river or climb a cliff outside a safe ramp.

Mountain formations avoid water, bases, expansions, resources, ramps, choke corridors and reserved strategic routes. A densely occupied or very small map can therefore contain fewer massifs than requested. Reduce Mountain Path Clearance, Mountain Max Area or Mountain Zone Count if the map does not have enough legal space.

River maps have no bridges or disconnected players

Enable Has Bridges and assign a River Bridge Prefab with a non-trigger deck collider. Bridges apply to the resolved River water layout. The planner searches the river banks even if an earlier road hint cannot reach a safe deck. Conflicting road crossings yield to a connected bridge network; final player routes use its walkable crossings. Water remains underneath the bridges.

Generated plateau walls close single-cell ground pinholes completely surrounded by cliff edges. These wall artifacts no longer count as isolated river banks. Real islands, open passages and strategic areas still have to remain reachable.

When bases and expansions already share a dry route, a river layout can have no bridge if no safe shortcut is available. The important check is strategic accessibility, rather than the number of visible decks.

An impossible span or banks blocked by resources, mountains or steep cliffs still produces a validation issue. Increase River Bridge Max Span or leave room for safe landings, then regenerate. A retained 3D preview with a connectivity error is not a validated gameplay map.

Plateau ramps or surfaces are hard to read

Assign a distinct Plateau Material on MapDefinition or the active BiomeSetting; when it is missing, plateau tops intentionally fall back to the grass material. Increase Plateau Relief Scale for a stronger height separation, or lower Plateau Contour Irregularity if the outline is too pronounced for the map size.

Plateau cliff borders are non-walkable by design. Dirt paths may change tier only through planned ramps. If a very dense setup leaves too little room for clean access, reduce the expansion count or choke count, reduce Plateau Footprint Scale, or increase the map size.

Ramp GameObjects use the wrong Unity Layer

Set Walkable Layer (ramps and bridges) on the map and make sure a Unity Layer with exactly that name exists under Project Settings > Tags and Layers. Ramp meshes and colliders are generated under Ramp_* GameObjects on this shared layer. When it is missing, the package falls back to the configured ground layer, then Default, and reports a validation warning. The hidden legacy biome RampLayerName field is ignored.

The ramp surface deliberately reuses Dirt Path Material. The worn areas immediately before and after it are separate DirtPath_RampApproach_* meshes so they remain visible even when curved path smoothing replaces the regular grid path mesh.

Cliff prefabs leave gaps, float or face the wrong direction

Cliff assets should contain at least one Renderer. Their root pivot may be offset: placement uses all child-renderer bounds and aligns the rendered top to the high ground automatically. Set Cliff Prefab Length Axis to the local axis that runs along the wall, or keep Auto when that axis is simply the prefab's largest horizontal extent.

Increase Cliff Segment Overlap slightly if a very irregular rock mesh exposes tiny corner seams. Cliff Vertical Overlap hides the joins above and below the terrain wall. Cliff Height Scale is a coverage multiplier and should stay at one or higher; older serialized values below one are clamped to full coverage.

Generated cliff instances are direct children of the configured Cliffs parent. Straight terrain edges are tiled continuously; cliff sides follow ramps without closing their passages. Mountain outcrops remain inside their massif. Enable Mark Cliff Cells Unbuildable when gameplay construction must respect walls.

Custom project layers are missing

The package can use the optional Ground, Environment and Aerial layers when they exist. Missing layers are safely ignored and do not block generation. Add them to the project only when your gameplay collision or rendering setup needs them.

The top-down screenshot is missing

Enable Generate Screenshot After Generation, verify that the output folder is writable, and make sure Screenshot Layer Mask includes at least one generated renderer. A relative output folder targets the project root in the Editor and Application.persistentDataPath in a build.

Automatic screenshots require a graphics device. Unity sessions launched with -nographics skip the capture and report a warning while map generation remains successful. Use a normal Editor session or a rendered player build when an image is required.

The generator exposes the final absolute path through LastScreenshotPath and ProceduralMapGenerationResult.ScreenshotPath. If the output is inside the project's Assets directory, Unity imports the PNG automatically.

A* Pathfinding is not installed

A* Pathfinding Project is optional and is not bundled. When compatible A* components are present, the package configures them through their public component names; otherwise map generation continues without pathfinding setup.

Regenerating the starter demo

Create Starter Demo Scene is safe to run again. Existing starter materials, prefabs and biome references are preserved rather than reset, so buyer customizations are not overwritten.

Getting useful diagnostics

Configuration errors and important warnings are always logged. Add SOROLIF_MAPGEN_VERBOSE_LOGS to Project Settings > Player > Scripting Define Symbols only when detailed subsystem traces are needed.

If the issue remains reproducible, contact support@sorolif.com with the Unity version, render pipeline, package version, seed, relevant MapDefinition settings and the complete Console error. A minimal project or source image is especially useful for import-related issues.