InstancedMesh

InstancedMesh renders many copies of a shared mesh in an efficient single draw call via a Vulkan SSBO (Shader Storage Buffer Object). Up to 65,536 instances are supported. Instances can be static, updated each frame, or driven by a physics simulation.

Creating an InstancedMesh

scene.createInstancedMesh(name)

Returns: InstancedMesh — A new instanced mesh registered with the scene.

Parameters:

• name (String) — Identifier for later retrieval via findInstancedMesh.

scene.findInstancedMesh(name)

Returns: InstancedMesh or null — Find an existing instanced mesh by name.

_instanced = _scene.createInstancedMesh("trees")

Mesh source

setMeshFromNode(node)

Set the mesh to instance from a Node (e.g. loaded from a .blend).

Parameters:

• node (Node) — Node whose mesh is used as the prototype.

setMesh(mesh)

Set the mesh to instance from a Mesh object created in code.

_instanced.setMesh(_treeMesh)
// or from a blend node:
_instanced.setMeshFromNode(_treeNode)

Material

setMaterial(r, g, b, a, metallic, roughness)

Set a shared PBR material for all instances.

Parameters: All Num in 0–1 range.

_instanced.setMaterial(0.2, 0.8, 0.3, 1.0, 0.0, 0.7)  // Green matte

Instance management

addInstance(x, y, z)

Returns: Num — Index of the added instance.

Add a new instance at position (x, y, z) with identity rotation and scale 1.

addInstanceWithScale(x, y, z, scale)

Returns: Num — Index of the added instance.

Add a new instance with uniform scale.

setInstancePosition(index, x, y, z)

Update the position of an existing instance (keeps existing rotation and scale).

setInstanceTransform(index, matrix)

Update an instance with a full 4×4 column-major transform matrix (a flat List of 16 Nums).

removeInstance(index)

Remove instance at index. Swaps with the last instance for O(1) removal (indices may change).

clearInstances()

Remove all instances.

setInstanceCount(count)

Resize the instance pool. Growing adds identity transforms; shrinking removes trailing instances.

setInstanceTransforms(matrices, count)

Set all instance transforms from a flat List of count * 16 floats. Used for high-performance bulk updates (e.g. from a physics simulation).

// Static grid of 1000 instances
for (i in 0...1000) {
    var x = (i % 32) * 2.0 - 32
    var z = (i / 32).floor * 2.0 - 16
    _instanced.addInstance(x, 0, z)
}

// Dynamic update per frame (wave animation)
for (i in 0..._instanced.instanceCount) {
    var x = (i % 32) * 2.0 - 32
    var z = (i / 32).floor * 2.0
    var y = Math.sin(_time + x * 0.3) * 0.5
    _instanced.setInstancePosition(i, x, y, z)
}

Properties

Property	Returns	Description
instanceCount	Num	Current number of instances
name / name=(value)	String	Name identifier
isVisible / isVisible=(value)	Bool	Show or hide all instances
useGpuInstancing / useGpuInstancing=(value)	Bool	Enable true GPU instancing via SSBO (recommended for high counts); false falls back to loop-based push-constant instancing

_instanced.useGpuInstancing = true   // Single draw call via SSBO
_instanced.isVisible = false          // Hide the whole group
Logger.info("Instances: %(_instanced.instanceCount)")

---

See Scene for createInstancedMesh and findInstancedMesh. See ParticleEmitter for physics-driven particle rendering (which also uses instanced meshes internally).