BRG Terrain Registerer
Registers a Unity Terrain's trees and details for GPU-instanced rendering through BRG Instanced Renderer. Trees are extracted once at startup. Details stream dynamically around the camera using C# Jobs and Burst Compiler.
For a step-by-step setup guide, see Getting Started: Terrain.
Settings
| Property | Type | Default | Description |
|---|---|---|---|
| Disable Built-In Rendering | bool | true | Disables the terrain's native drawTreesAndFoliage, so BRG Instanced Renderer takes over all tree and detail rendering. |
| Enable Debug Logging | bool | false | Outputs detailed logging for tree extraction, detail streaming, and patch loading (Development builds only). |
Trees
| Property | Type | Default | Description |
|---|---|---|---|
| Cull Distance | float | — | Read-only. Shows the terrain's Tree Distance setting. Adjust this in Unity's Terrain settings. |
| Create Instance Handles | bool | false | Store per-instance handles for trees, enabling per-instance operations like InstanceLink.SetColor. Increases memory usage. Required for GetTreeInstanceLinks(). |
| Chunk Size | float | 256m | World-space size of each spatial chunk for trees. Smaller values give better culling precision but more overhead. |
| Show Chunk Gizmos | bool | false | Draw wireframe boxes in the Scene View for each tree chunk, color-coded by fill percentage. |
| Show Instance Spheres | bool | false | Draw bounding spheres for each tree instance. Slow with many trees. |
| Skip BRG Upload | bool | false | Debug: skip GPU upload for trees. |
The inspector also shows a status line with tree prototype count, total instance count, and chunk count when registered.
Details
Streaming
| Property | Type | Default | Description |
|---|---|---|---|
| Preserve Prototype Layers | bool | false | When enabled, detail instances keep their prefab's layer. When disabled, details use the terrain GameObject's layer (matches Unity's tree behavior). |
| Cull Distance | float | — | Read-only. Shows the terrain's Detail Object Distance setting. Adjust this in Unity's Terrain settings. |
| Detail Chunk Size | float | 32m | World-space size of detail streaming cells. Determines how finely details are streamed in and out around the camera. Snapped to terrain patch boundaries. |
The inspector shows computed read-only fields for Actual Chunk Size (snapped to patch boundaries) and Patch Size when a terrain is assigned.
| Property | Type | Default | Description |
|---|---|---|---|
| Use Streaming | bool | true | When enabled, patches are loaded and unloaded based on camera distance. When disabled, all patches are loaded at startup. |
| Max Patch Extracts Per Frame | int | 4 | Maximum patches to extract data for per frame. Lower values give smoother loading but slower pop-in. |
| Max Patch Unloads Per Frame | int | 8 | Maximum patches to unload per frame when the camera moves away. |
| Max Concurrent Extraction Jobs | int | 32 | Maximum extraction jobs that can be in flight simultaneously. |
| Complete Jobs Same Frame | bool | false | Force extraction jobs to complete on the same frame they are scheduled. Eliminates pop-in at the cost of a per-patch main thread stall. |
| Skip Extract Throttle On Start | bool | false | Bypass the per-frame extract limit on the first frame so all in-range patches load immediately. Causes a one-time hitch but no pop-in. |
| Update Interval | float | 0.1s | How often to check for patch changes in seconds. 0 = every frame. Editor only. |
| Unload Hysteresis | float | 10m | Extra distance beyond the detail render distance to keep patches loaded, preventing rapid load/unload cycles at the boundary. |
Transform Generation
| Property | Type | Default | Description |
|---|---|---|---|
| Use Unity Transforms | bool | false | Use Unity's ComputeDetailInstanceTransforms API instead of the custom extraction algorithm. Slower and allocates GC, but produces a 1:1 match with Unity's built-in detail rendering. |
Animated Crossfade
| Property | Type | Default | Description |
|---|---|---|---|
| Snap Crossfade On Start | bool | true | Snap animated crossfade to the target LOD for patches already in range when the component initializes. Prevents a mass fade-in on scene load. |
| Snap Crossfade On Load | bool | false | Snap animated crossfade for patches streamed in during gameplay. When off, newly loaded details crossfade in smoothly. When on, they appear at their correct LOD immediately. |
Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Show Chunk Gizmos | bool | false | Draw wireframe boxes in the Scene View for each detail chunk, color-coded by fill percentage. |
| Show Instance Spheres | bool | false | Draw bounding spheres for each detail instance. Very slow — requires refresh to populate. |
| Skip BRG Upload | bool | false | Debug: skip GPU upload for details. |
The inspector also shows a status line with detail prototype count, patch grid size, loaded instance/patch/chunk counts, and pending patches.
Detail Prefab Overrides (Editor Only)
The inspector provides a Detail Prefab Overrides section where you can substitute terrain detail prototypes with LOD Group prefabs. Click Refresh Detail List to populate the list from the terrain's detail settings.
Texture-based details show a warning prompting you to assign an override prefab for BRG rendering.
Inspector Actions
| Button | Description |
|---|---|
| Refresh All | Reloads all tree and detail data from the terrain. Call after modifying terrain data outside the paint tools. |
| Clear Caches | Clears cached extraction data and performs a full reload. |
Public Methods
GetTreeInstanceLinks
public InstanceLink[] GetTreeInstanceLinks()
Returns InstanceLink handles for all registered tree instances. Requires Create Instance Handles to be enabled on the Trees section. Use these handles to modify individual trees at runtime (e.g., set per-tree color).
ClearExtractionCache
public static void ClearExtractionCache(Terrain terrain)
public static void ClearAllExtractionCaches()
Clear cached tree and detail extraction data for a specific terrain or all terrains. The component caches extraction data to avoid redundant work across enable/disable cycles. Call these when terrain data has changed externally and you need a clean re-extraction.
How Trees Work
Tree instances are read from the terrain data when the component initializes. They are:
- Spatially batched into chunks for hierarchical culling
- Uploaded to the GPU as permanent instances
- Matched to the prefab assigned in the terrain's tree prototype settings
In the editor, tree changes made with Unity's terrain paint tools are detected automatically. The registerer performs an incremental update without needing a manual refresh.
How Details Work
Terrain details (grass, flowers, small vegetation) are streamed based on camera proximity:
- The terrain is divided into a grid based on Detail Chunk Size
- Patches near the camera are loaded using Burst-compiled extraction jobs
- Patches are unloaded as the camera moves away
- Extraction runs on worker threads to avoid frame hitches
This allows millions of detail instances without loading the entire terrain upfront. See Terrain Detail Spawning for more on the custom extraction algorithm.
Editor Behavior
- Tree and detail changes from Unity's terrain paint tools are detected and updated automatically
- The component works outside of play mode for editor preview
- Individual terrain trees can be selected and edited directly in the Scene View using the terrain tree selector tool
Notes
- One BRG Terrain Registerer per Terrain GameObject.
- The component caches extraction data per terrain. Cached data survives enable/disable cycles to avoid redundant extraction.
- Per-prefab settings (shadows, density, crossfade) are controlled via BRG Prototype Extra Data on the tree/detail prefabs.
- Use Clear Caches if you modify terrain data through scripts, as the automatic detection only covers the paint tools.