OpenRA/OpenRA · error · MapGenerationException

TerrainSmoothing must be between 0 and {MatrixUtils.MaxBinom

Error message

TerrainSmoothing must be between 0 and {MatrixUtils.MaxBinomialKernelRadius} inclusive

What it means

Validate() checks that TerrainSmoothing is between 0 and MatrixUtils.MaxBinomialKernelRadius (constant value 10) inclusive. TerrainSmoothing controls the radius of a binomial blur kernel applied to the elevation noise. Values outside [0,10] exceed the precomputed kernel table in MatrixUtils, which would cause an ArgumentException downstream in BinomialBlur. The field defaults to 0 and is [FieldLoader.Require].

Source

Thrown at OpenRA.Mods.Common/Traits/World/ClassicMapGenerator.cs:311

						else
							throw new YamlException($"Invalid resource spawn weight `{subMy.Value}`");
					});
			}

			public void Validate(ITemplatedTerrainInfo terrainInfo)
			{
				if (Rotations < 1)
					throw new MapGenerationException("Rotations must be >= 1");
				if (TerrainFeatureSize < 1)
					throw new MapGenerationException("TerrainFeatureSize must be >= 1");
				if (ForestFeatureSize < 1)
					throw new MapGenerationException("ForestFeatureSize must be >= 1");
				if (ResourceFeatureSize < 1)
					throw new MapGenerationException("ResourceFeatureSize must be >= 1");
				if (CivilianBuildingsFeatureSize < 1)
					throw new MapGenerationException("CivilianBuildingsFeatureSize must be >= 1");
				if (TerrainSmoothing < 0 || TerrainSmoothing > MatrixUtils.MaxBinomialKernelRadius)
					throw new MapGenerationException($"TerrainSmoothing must be between 0 and {MatrixUtils.MaxBinomialKernelRadius} inclusive");
				if (WaterRoughness > 0 && MinimumCoastStraight < 0)
					throw new MapGenerationException("MinimumCoastStraight must be >= 0");
				if (SmoothingThreshold < (FractionMax + 1) / 2 || SmoothingThreshold > FractionMax)
					throw new MapGenerationException($"SmoothingThreshold must be between {(FractionMax + 1) / 2} and {FractionMax} inclusive");
				if (MinimumLandSeaThickness < 1)
					throw new MapGenerationException("MinimumLandSeaThickness must be >= 1");
				if (MinimumMountainThickness < 1)
					throw new MapGenerationException("MinimumMountainThickness must be >= 1");
				if (Water < 0 || Water > FractionMax)
					throw new MapGenerationException($"Water must be between 0 and {FractionMax} inclusive");
				if (Forests < 0 || Forests > FractionMax)
					throw new MapGenerationException($"Forest must be between 0 and {FractionMax} inclusive");
				if (ForestCutout < 0)
					throw new MapGenerationException("ForestCutout must be >= 0");
				if (MaximumCutoutSpacing < 0)
					throw new MapGenerationException("TopologyAugmentationThreshold must be >= 0");
				if (ForestClumpiness < 0)
					throw new MapGenerationException("ForestClumpiness must be >= 0");

View on GitHub (pinned to a520984d91)

Solutions

1. Set TerrainSmoothing to an integer in the range 0–10
2. Use 0 for no smoothing, 10 for maximum available smoothing
3. Check MatrixUtils.MaxBinomialKernelRadius in your OpenRA version to confirm the upper bound

Example fix

# before
TerrainSmoothing: 20
# after
TerrainSmoothing: 10

// Pre-flight check: TerrainSmoothing must be in [0, MaxBinomialKernelRadius]
static void ValidateTerrainSmoothing(int smoothing)
{
    if (smoothing < 0 || smoothing > MatrixUtils.MaxBinomialKernelRadius)
        throw new ArgumentOutOfRangeException(nameof(smoothing),
            $"ClassicMapGenerator TerrainSmoothing must be between 0 and {MatrixUtils.MaxBinomialKernelRadius} inclusive");
}

static bool IsValidTerrainSmoothing(int value) =>
    value >= 0 && value <= MatrixUtils.MaxBinomialKernelRadius;

try
{
    var param = new Parameters(map, yaml);
}
catch (MapGenerationException ex) when (ex.Message.Contains("TerrainSmoothing must be between"))
{
    Console.Error.WriteLine($"Invalid TerrainSmoothing: {ex.Message}");
    // clamp to valid range or abort
}

When it happens

Trigger: The TerrainSmoothing key is set to a negative number or a value greater than 10 in the generator YAML.

Common situations: Mod developer sets a large smoothing value (e.g. 20) expecting more blur, not knowing the kernel table is capped at radius 10. Negative value entered accidentally. Version upgrade where MaxBinomialKernelRadius was reduced.

Related errors

• SmoothingThreshold must be between {(FractionMax + 1) / 2} a
• TerrainFeatureSize must be >= 1
• MinimumLandSeaThickness must be >= 1
• MinimumMountainThickness must be >= 1
• Roughness must be between 0 and {FractionMax}

AI-assisted analysis of OpenRA/OpenRA@a520984d91 (2026-08-13). Data as JSON: /api/errors/a7b26920c03c1750. Report an issue: GitHub.