Unreal Engine 5.8, C++ and materials. Updated November 2026. Written by the Algosyntax team.
Quick answer: drawing many similar moving objects as instances of one Instanced Static Mesh component, instead of one actor each, cuts draw calls and per-object overhead. Three things go wrong when you switch:
- The objects turn grey: tick Used with Instanced Static Meshes in each material’s Usage settings.
- Colours or patterns are wrong: the material works in local space, which on an instanced mesh means the whole component’s space. Use Instance & Particle Space instead.
- The render thread is slow: you move instances with
bMarkRenderStateDirtyset to true, which rebuilds the whole component every frame. Pass false.
We switched the falling notes in VR Musician to instances for a standalone VR headset. Here’s what we learned.
When instancing is worth it
Each of our notes was a pooled actor with five components: a root, a visual root, head, tail and a text label. A busy song had around 100 of these moving every frame, plus the label text rebuilding for each eye. With instancing, every visible note’s head and tail became instances in one Instanced Static Mesh component per note colour. For two hands that’s about four draw calls in total.
You give up some things: per-object Blueprint events, per-object components (our note labels), and per-object material parameters. Per-instance data replaces the last one; see below.
Problem 1: everything turns grey
A material can only draw on an instanced mesh if it was compiled for it. Without that, Unreal draws the default grey material, and in a packaged build it stays grey, because the needed shaders were never cooked.
Fix: open each material, find Usage in the Details panel, tick Used with Instanced Static Meshes, then Apply and Save. With many materials, a short editor Python script can set it for you:
import unreal
material = unreal.load_asset("/Game/Notes/M_NoteHead")
material.set_editor_property("used_with_instanced_static_meshes", True)
unreal.MaterialEditingLibrary.recompile_material(material)
unreal.EditorAssetLibrary.save_loaded_asset(material)
Problem 2: partly coloured or black objects
Our note material drew its outline from the pixel’s position in local space (World Position through a Transform Position node set to Local Space). On a normal actor, local means the note itself. On an instanced mesh, local means the whole component, so every note measured itself from the grid’s origin and the outline landed in the wrong place.
Fix: set the Transform Position node’s destination to Instance & Particle Space. For a normal actor that’s the same as local space, so the material keeps working in both modes.
Problem 3: per-object material parameters
You can’t set a material parameter for one instance. Use Per Instance Custom Data:
- Set Num Custom Data Floats on the component, and write the values with
SetCustomDataValueor in a batch. - In the material, read them with a PerInstanceCustomData node (slot 0, 1 and so on).
- Plug your old scalar parameter into the node’s Default Value input, so the material still works on a normal mesh.
For a colour shared by many objects, an instanced mesh component per colour, each with its own material instance, is simpler.
Problem 4: the render thread gets slower, not faster
A profile of our editor VR Preview showed about 6 ms of render thread per frame spent rebuilding cached mesh draw commands, and BatchUpdateInstancesTransforms running every frame. The culprit was our hand-joint display, an instanced mesh that moved its instances like this:
// Rebuilds the whole render proxy every frame.
Joints->BatchUpdateInstancesTransforms(0, Transforms, true, /*bMarkRenderStateDirty*/ true, true);
bMarkRenderStateDirty = true removes the component from the renderer and adds it back. In UE 5.8 instanced meshes already send moved instances to the GPU incrementally, mobile included, so you don’t need it:
// Sends only the changed instance transforms.
Notes->BatchUpdateInstancesTransforms(0, Transforms, /*bWorldSpace*/ false, /*bMarkRenderStateDirty*/ false, /*bTeleport*/ false);
Also turn off what moving instances don’t need: collision, overlap events and shadow casting, unless the objects really need them.
Adding and removing instances
Notes appear and disappear constantly. Adding or removing instances in the middle of the list shifts the indices of every instance after it. We only add or remove at the end of the list and reuse the rest, rewriting all transforms each frame in one batch call. Removing a hit note is just a transform with zero scale until it’s reused.
FAQ
Instanced Static Mesh or Hierarchical Instanced Static Mesh? The hierarchical version culls clusters of instances and suits huge static sets, like foliage. For a few hundred objects that move every frame, the plain one is simpler.
Can instances run Blueprint logic? No. Keep the logic in one manager that owns the data and writes transforms. That’s usually cheaper anyway.
How much faster is it? It depends on how many objects you have and how much each actor did. Measure before and after with stat unit and Unreal Insights. We haven’t benchmarked our note switch on its own, so we won’t give you a number.