egametang/ET · warning · Exception

rcBuildHeightfieldLayers: Region ID overflow.

Error message

rcBuildHeightfieldLayers: Region ID overflow.

What it means

Thrown in rcBuildHeightfieldLayers when the region ID counter (regId) reaches 255 during the sweep-based region assignment. Layer region IDs are stored in a byte, so at most 255 distinct regions are supported per tile. More than that means the compact heightfield is too complex for the layer partitioning step.

Source

Thrown at Packages/cn.etetet.recast/Scripts/Core/Share/Recast/RecastLayers.cs:157

                    }
                }

                // Create unique ID.
                for (int i = 0; i < sweepId; ++i)
                {
                    // If the neighbour is set and there is only one continuous
                    // connection to it,
                    // the sweep will be merged with the previous one, else new
                    // region is created.
                    if (sweeps[i].nei != 0xff && prevCount[sweeps[i].nei] == sweeps[i].ns)
                    {
                        sweeps[i].id = sweeps[i].nei;
                    }
                    else
                    {
                        if (regId == 255)
                        {
                            throw new Exception("rcBuildHeightfieldLayers: Region ID overflow.");
                        }

                        sweeps[i].id = regId++;
                    }
                }

                // Remap local sweep ids to region ids.
                for (int x = borderSize; x < w - borderSize; ++x)
                {
                    RcCompactCell c = chf.cells[x + y * w];
                    for (int i = c.index, ni = c.index + c.count; i < ni; ++i)
                    {
                        if (srcReg[i] != 0xff)
                            srcReg[i] = sweeps[srcReg[i]].id;
                    }
                }
            }

View on GitHub (pinned to 5cab01f7a8)

Solutions

1. Reduce tile size so each tile contains fewer regions.
2. Raise minRegionArea to merge tiny regions and reduce the total count.
3. Smooth/erode walkable area (filterSmallRegion, region merging) before layer build.
4. Simplify source geometry; switch to a partitioning method with a lower region count.

Example fix

// before
cfg.minRegionArea = 4;
cfg.tileSize = 1024;

// after
cfg.minRegionArea = 64;
cfg.tileSize = 256;

if (cfg.tileSize > 512) Debug.LogWarning("Large tiles can exceed 255 layer regions; consider smaller tiles");
if (cfg.minRegionArea < 32) Debug.LogWarning("Tiny minRegionArea raises region count toward the 255 cap");

try { RecastLayers.BuildHeightfieldLayers(ctx, chf, borderSize, cfg.tileSize, lset); }
catch (Exception e) when (e.Message.Contains("Region ID overflow"))
{ /* reduce tile size, raise minRegionArea, retry */ }

When it happens

Trigger: A tile with extremely fragmented walkable area producing > 255 distinct layer regions; very small minRegionArea retaining slivers; high-detail scenes in a single large tile.

Common situations: Large tiles covering complex geometry; tiny minRegionArea; layer partitioning on scenes better suited to watershed/monotile.

Related errors

• rcBuildContours: Multiple outlines for region {cont.reg}.
• rcBuildContours: Bad outline for region {i}, contour simplif
• removeVertex: Too many polygons {mesh.npolys} (max:{maxTris}
• invalid capacity: {capacity}
• rcBuildCompactHeightfield: Heightfield has too many layers {

AI-assisted analysis of egametang/ET@5cab01f7a8 (2026-08-13). Data as JSON: /api/errors/cdd1d6883d47f23a. Report an issue: GitHub.