Skip to content

Game.Rendering.TerrainRenderSystem

Assembly: Game
Namespace: Game.Rendering

Type: class

Base: GameSystemBase

Summary:
TerrainRenderSystem is a game system responsible for preparing and updating terrain rendering state each frame. It coordinates terrain-related systems (TerrainSystem, TerrainMaterialSystem, OverlayInfomodeSystem, SnowSystem), manages a cached Material instance used for terrain rendering, updates global shader parameters for cascaded heightmaps and virtual texturing, and applies overlay/snow textures and keywords. It also exposes helper APIs to query cascade regions, viewports and culling areas used by other rendering or culling code. The nested ShaderID class centralizes shader property IDs used by the system.

Fields

  • private TerrainSystem m_TerrainSystem
    Holds a reference to the TerrainSystem (terrain data, heightmaps, cascade info). Used to query cascade matrices, heightmap textures, height scale/offset, and to request cascade rendering.

  • private TerrainMaterialSystem m_TerrainMaterialSystem
    Reference to the TerrainMaterialSystem responsible for terrain material-specific updates (splat maps, material properties). Used to obtain and update textures/material parameters.

  • private OverlayInfomodeSystem m_OverlayInfomodeSystem
    Reference to the OverlayInfomodeSystem. Present for overlay-related coordination (info modes), although this class primarily uses overlay textures it exposes.

  • private SnowSystem m_SnowSystem
    Reference to the SnowSystem. Provides snow depth texture used by terrain materials.

  • private Material m_CachedMaterial
    A cached copy of the terrain material owned by this system. The system creates a copy of the source material (from assets or valid surface) to safely set keywords and parameters per-world. The cached material is destroyed on change or on system destroy.

  • public Texture overrideOverlaymap { get; set; }
    A public property allowing external code to override the terrain overlay/base color map. When set, the system will bind this texture to the material as the base color/overlay texture.

  • public Texture overlayExtramap { get; set; }
    A public property for an extra overlay texture. When set, the system enables the relevant shader keyword and binds this texture as _OverlayExtra.

  • public float4 overlayArrowMask { get; set; }
    A public property holding overlay arrow mask parameters (uses Unity.Mathematics.float4). This vector is passed to the material as _OverlayArrowMask.

  • private Material material { get; set; }
    Private property wrapping m_CachedMaterial. The setter safely destroys any previous cached material (using Object.DestroyImmediate) and clones a new Material from the provided value. The setter also initializes the decal layer mask shader property on the cloned material.

  • public class ShaderID (nested)
    Contains static readonly int fields created by Shader.PropertyToID for all shader property names the system needs (e.g., _HeightMap, _SplatMap, _COTerrainTextureArrayLODArea, _LODArea, _TerrainScaleOffset, etc.). Using the ShaderID constants avoids repeated string lookups and centralizes IDs.

Properties

  • public Texture overrideOverlaymap { get; set; }
    Used to override the default overlay/base-color texture applied to terrain. If overlayExtramap is set but overrideOverlaymap is null, the system provides a white texture so the extra overlay can be sampled.

  • public Texture overlayExtramap { get; set; }
    If set, triggers the system to enable the OVERRIDE_OVERLAY_EXTRA shader keyword and bind the extra overlay texture to the terrain material.

  • public float4 overlayArrowMask { get; set; }
    A 4-component vector passed to the material for overlay arrow masking (parameter name _OverlayArrowMask).

  • private Material material { get; private set }
    A private property that exposes/updates the internally cached Material instance. Setting this property clones a provided material into m_CachedMaterial and sets an initial decal layer mask via _CODecalLayerMask.

Constructors

  • public TerrainRenderSystem()
    Default parameterless constructor. The class relies on OnCreate to perform initialization and acquire references to dependent systems.

Methods

  • protected override void OnCreate()
    Initializes the system. Calls base.OnCreate(), requires TerrainPropertiesData for update scheduling, creates the cached terrain material from the global asset (AssetDatabase.global.resources.terrain.renderMaterial), and obtains references to TerrainSystem, TerrainMaterialSystem, OverlayInfomodeSystem and SnowSystem from the World. The method is annotated with [Preserve] to prevent code stripping.

  • protected override void OnDestroy()
    Cleans up the cached material when the system is destroyed. Calls CoreUtils.Destroy on m_CachedMaterial and base.OnDestroy(). Annotated with [Preserve].

  • private void UpdateMaterial()
    Core logic that gathers cascade info from TerrainSystem and configures global and per-material shader parameters. It:

  • Gets cascade matrices, LOD ranges and base LOD and sets global shader variables (_COTerrainTextureArrayLODArea, _COTerrainTextureArrayLODRange, _COTerrainTextureArrayBaseLod, _COTerrainHeightScaleOffset).
  • Chooses a Material to update: either the system's cached material or the valid surface's material (TerrainSurface.GetValidSurface()).
  • Calls SetKeywords to enable/disable overlay and playable-world keywords based on state.
  • Binds textures: heightmap, splatmap, cascade texture (heightmap array), override overlay map, overlay extra map, snow depth.
  • Passes LOD area/range and terrain scale/VT scale offsets into the material.
  • Invokes m_TerrainMaterialSystem.UpdateMaterial(material) to let the material system apply further updates.

  • Assigns the material back to the valid surface so the renderer uses the updated material.

  • protected override void OnUpdate()
    Called each frame. Updates the material state via UpdateMaterial(). If the TerrainSystem indicates a height map render is required (heightMapRenderRequired), it calls m_TerrainSystem.RenderCascades() to render/update the cascaded heightmap textures.

  • private void SetKeywords(Material materialToUpdate)
    Enables or disables shader keywords on the provided material based on overlay textures and the TerrainSystem.baseLod:

  • If overlayExtramap is set, ensures overrideOverlaymap is at least a white texture, enables OVERRIDE_OVERLAY_EXTRA, disables OVERRIDE_OVERLAY_SIMPLE.
  • Else if overrideOverlaymap is set, enables OVERRIDE_OVERLAY_SIMPLE, disables OVERRIDE_OVERLAY_EXTRA.
  • Otherwise disables both overlay override keywords.

  • Enables or disables _PLAYABLEWORLDSELECT depending on whether TerrainSystem.baseLod is zero.

  • public Bounds GetCascadeRegion(int index)
    Returns an axis-aligned bounding box (UnityEngine.Bounds) representing the world region covered by a particular cascade index (derived from m_TerrainSystem.heightMapSliceArea). If index is out of range, returns an empty/default Bounds.

  • public Bounds GetCascadeViewport(int index)
    Computes and returns a Bounds representing the viewport area within the cascade slice that was last updated (based on heightMapViewportUpdated and heightMapSliceArea). Useful for partial updates and culling of dynamic regions. Returns default Bounds if index out of range.

  • public Bounds GetCascadeCullArea(int index)
    Returns the culling area for a given cascade index (constructed from m_TerrainSystem.heightMapCullArea). If index is out of range, returns default Bounds.

  • public Bounds GetLastCullArea()
    Returns a Bounds built from TerrainSystem.lastCullArea representing the last computed culling rectangle used for terrain.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Acquire or override overlay textures before runtime rendering
    this.overrideOverlaymap = myCustomOverlayTexture;
    this.overlayExtramap = myOverlayExtraTexture; // optional
    // The system will clone the default terrain material and apply properties each frame.
}

Notes and tips: - To change the terrain appearance per-world or per-mod, assign overrideOverlaymap and/or overlayExtramap; UpdateMaterial will bind them and enable the correct keywords. - If replacing the material entirely, assign a Material to the private material property via reflection or by changing the system's initialization to use a custom Material source (the property clones the provided Material). - The nested ShaderID class contains the string-to-ID mappings used by this system; refer to those IDs when writing shaders or setting global/material properties to ensure compatibility.