Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🔁How to instance repeated meshes

A Model Mesh Node is one draw. Ten copies of the same .glb are ten draws. They still share one file. That is normal kitbash. See How to kitbash a level from mesh models.

Instancing is one node that draws many copies of the same geometry in one pass. Use it when you need dozens or hundreds of the same small prop (grass, rocks, coins), not for a handful of unique kit pieces.

Registered editor names (Mesh category):

Node
Class
Use

Instanced Model Mesh Node

ENGINE.InstancedModelMeshNode

Repeat a .glb (modelUrl)

Instanced Mesh Node

ENGINE.InstancedMeshNode

Repeat built-in geometry (default is a box)

Measure FPS first: Performance & optimization.

NOTE: The list of instance transforms (instances) is hidden in the Inspector. You do not type each copy by hand there. Ask the agent to fill instances (position, rotation, scale) up to maxInstances. Do not stamp copies in a .genesys-scene file.

1

Add an Instanced Model Mesh Node

Select the plus button in the Outliner, choose Component, then Instanced Model Mesh Node.

For a box or other primitive instead of a .glb, choose Instanced Mesh Node.

2

Point it at the mesh

On Instanced Model Mesh Node, set modelUrl to a fully qualified path such as @project/assets/models/prop.glb.

Leave Model Material empty to keep packed kit materials. Override only when every instance should share a different .material.json. Same rule as a Model Mesh Node: How to set up materials.

3

Set capacity

maxInstances is the buffer size (default 1000). Raise it only if you need more copies. Extra unused capacity still costs memory.

Ask the agent to add instance transforms. The count cannot exceed maxInstances.

4

Cull distant copies

cullDistance is world-space distance from the camera. 0 (default) turns distance culling off. Set a positive value so far copies are skipped.

perInstanceFrustumCulling defaults on. Copies outside the camera frustum are skipped in that pass.

5

Add LOD only if you have extra meshes

LOD is optional. LOD0 is the node’s main mesh (modelUrl or the primitive geometry).

On Instanced Model Mesh Node, extra lods entries each need a modelUrl and a camera distance greater than 0. Farther distances use simpler .glb files. Tiers with distance at 0 or below are ignored.

On Instanced Mesh Node, extra lods entries use geometry plus distance.

Compaction (cull / LOD) also runs when more than one LOD tier exists.

6

Test in Play

Enter Play mode. Watch FPS in the same view that was slow with separate Model Mesh Nodes. Capture a profiler JSON if it is still slow: How to use the profiler.

When not to instance

Situation
Use

A few unique kit pieces

Separate Model Mesh Nodes, one .glb

Mesh plus light, trigger, or gameplay children

A prefab, then instances of that prefab

Player or NPC character

Character pawn / NPC prefab, not an instanced node

updatePhysicsOnInstanceTransform defaults off. Leave it off unless instance motion must push physics that frame.

Common mistakes

What went wrong
What to do

Expected to type every copy in the Inspector

instances is hidden. Ask the agent.

Named it Instant Mesh

The Mesh category labels are Instanced Model Mesh Node and Instanced Mesh Node.

Instanced a unique building

Keep unique architecture as Model Mesh Nodes.

Raised maxInstances “to be safe”

Match the real count. Default is 1000.

Set cullDistance and everything vanished

Distance is world units from the camera. 0 disables. Lower the value only after you see FPS.

What You've Done

You can add an Instanced Model Mesh Node (or Instanced Mesh Node), set modelUrl or primitive geometry, let the agent fill copies, and turn on distance cull or extra LOD. Next: Performance & optimization, or How to kitbash a level from mesh models if most of the level should stay as ordinary nodes.

Last updated

Was this helpful?