TerrainBlock

TerrainBlock is the scene object that represents a heightfield terrain in a level.

It loads terrain height data from a .ter file and connects it with terrain material data, minimap imagery, terrain collision, and terrain rendering.

Most normal outdoor levels have one main terrain object, commonly named:

theTerrain

Basic example

A typical TerrainBlock entry in items.level.json:

{
  "class": "TerrainBlock",
  "name": "theTerrain",
  "__parent": "LevelObjects",
  "position": [-1024, -1024, 0],
  "terrainFile": "/levels/example/theTerrain.ter",
  "materialTextureSet": "exampleTerrainMaterialTextureSet",
  "minimapImage": "levels/example/example_minimap.png",
  "squareSize": 1,
  "maxHeight": 256,
  "baseTexSize": 2048,
  "castShadows": true
}

Important fields

Terrain file

The main field is:

"terrainFile": "/levels/example/theTerrain.ter"

This file stores the terrain heightfield data used by the engine.

The level may also use matching terrain-related images and data:

• Heightmap source images
• Hole maps
• Terrain material layer maps
• Depth maps
• Minimap image
• Terrain material texture set

For .ter, .terrain.json, terrain material, and texture packing details, see the Terrain format documentation.

Position and size

position places the terrain block in world space.

"position": [-1024, -1024, 0]

squareSize controls spacing between height samples:

"squareSize": 1

maxHeight controls the terrain height range:

"maxHeight": 256

Changing these values after authoring can affect roads, object placement, terrain material alignment, and gameplay readability.

Terrain materials

materialTextureSet references the terrain texture setup used by the renderer.

"materialTextureSet": "exampleTerrainMaterialTextureSet"

Terrain materials are different from normal mesh materials. They are painted on the terrain and use base, macro, and detail texture behavior.

Groundmodel behavior is usually connected through terrain material setup rather than the TerrainBlock object itself.

Tool notes

For tools that create or modify terrain data:

• Keep terrainFile paths valid and portable.
• Preserve position, squareSize, and maxHeight unless the tool is intentionally rebuilding terrain scale.
• Keep terrain-related images aligned to the terrain resolution where required.
• Update roads, forest data, ground cover, waypoints, and spawn points when moving or rescaling terrain.
• Do not add a normal scale field to TerrainBlock; it is not the terrain sizing workflow.

Common issues

• Terrain appears in the wrong place because position does not match object and road placement.
• Terrain renders black or incorrectly because materialTextureSet or terrain materials are missing.
• Roads, forests, or ground cover no longer align after changing squareSize, maxHeight, or terrain position.
• Minimap does not match because minimapImage points to an old image.

Validation criteria

• terrainFile exists and loads.
• Terrain material texture set exists.
• Terrain position, size, and height match the intended world scale.
• Ground cover and forest placement still align with the terrain.
• Roads, spawns, waypoints, and major props still sit on the expected surfaces.

See also: Terrain authoring workflow , Terrain files , Groundmodels , GroundCover .