Registerer Example

BRGRegistererExample is a working example of a Custom Registerer included in the Examples folder. It demonstrates prototype registration, chunk allocation, per-instance mutation, and the inspector-driven workflow for testing BRG features.

For per-frame animated updates and a side-by-side comparison of all three submission paths (Stage*, *Unsafe, and batched), see Instance Link Example.

Setup

Property	Type	Default	Description
Prefab	GameObject	—	Prefab to render. Must have a MeshFilter + MeshRenderer (or LODGroup).

Chunk Settings

Property	Type	Default	Description
Chunk Size	int	25	Physical size of the chunk in world units.
Chunk Padding	float	1	Extra padding added to chunk bounds.
Initial Instance Count	int	256	Number of instances to spawn per grid chunk.
Cull Distance	float	0	Max render distance for the chunk. 0 = unlimited.

Lifecycle

Property	Type	Default	Description
Auto Register	bool	true	Automatically initialize on enable and shutdown on disable. When off, use the Initialize / Shutdown buttons in the inspector.

When Auto Register is disabled, the inspector shows a Manual Lifecycle section with Initialize and Shutdown buttons, along with the current registration status.

Inspector Controls

Once registered, the inspector provides runtime controls:

Global

Button	Description
Create Grid Chunk	Allocate a new chunk and fill it with instances arranged in a grid pattern. Each new chunk is offset so they don't overlap.
Create Empty Chunk	Allocate an empty chunk with no instances. Use Add Instance to populate it one at a time.

Per Chunk

Each chunk shows its ID, instance count, and a set of action buttons:

Button	Description
Add Instance	Add a single instance at a random position within the chunk bounds, with a random color.
Remove Random	Remove a random instance from the chunk.
Randomize Colors	Set all instances to random colors (requires Enable Per-Instance Color on the Config).
Randomize Scales	Set all instances to random scales between 0.3 and 2.0.
Scatter Positions	Move all instances to random positions within the chunk bounds.
Delete Chunk	Free the chunk and all its instances.

The per-instance buttons use InstanceLink handles obtained via GetInstanceLink(chunk, localIndex) or returned from AddInstance().

How It Works

The example demonstrates the key steps of a custom registerer:

OnInitialize

Registers the assigned prefab via RegisterRenderSignatureFromPrefab()
Creates an initial grid chunk via CreateGridChunk()

OnShutdown

Clears local chunk state. The base class handles freeing chunks and unregistering prototypes.

OnChunkWritten

When a chunk is written, the GPU writes may be deferred (e.g. for a buffer resize). The base class calls OnChunkWritten(chunkId) once the primary chunk and all of its overflow sub-chunks have completed their writes. The example uses this to refresh its cached instance count after async writes complete.

Instance Mutation

Per-instance buttons use the staged Stage* API to modify instances. Multiple updates to the same slot in one frame collapse into a single GPU write:

// add an instance
var link = AddInstance(chunkState.link, new InstanceData
{
    position = randomPosition,
    rotation = quaternion.identity,
    scale = new float3(1f),
    signatureIndex = _protoIndex,
    color = new Color32(255, 128, 64, 255)
});

// modify it later (staged - merged into one GPU write per slot per frame)
StageColor(link, new Color32(0, 255, 0, 255));
StagePosition(link, newPosition);
StageScale(link, new float3(1.5f));

// remove it
StageRemove(link);

Debug

Property	Type	Default	Description
Show Chunk Gizmos	bool	true	Draw wireframe boxes in the Scene View showing chunk bounds. Each chunk gets a unique color.

Table of Contents