GltfInstance

fun FilamentSceneScope.GltfInstance(asset: GltfAsset?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), fitToSize: Float? = null, animationState: AnimationState? = null, morphWeights: FloatArray? = null, visible: Boolean = true, castShadows: Boolean? = null, receiveShadows: Boolean? = null, materialVariant: String? = null, onCreate: GltfInstanceScope.() -> Unit = {}, onUpdate: GltfInstanceScope.() -> Unit = {}, onTap: (Position) -> Unit? = null)

Places one copy of a GltfAsset in the scene.

Each call creates its own FilamentInstance with independent transform, animation state, and material overrides. GPU resources (geometry, textures) are shared from the asset.

Accepts a nullable asset so it composes naturally with rememberGltfAsset's suspend-lambda overload, which returns null while loading. When asset is null this composable is a no-op.

Typical usage:

// single static model — loading handled internally
GltfInstance(
asset = rememberGltfAsset { Res.readBytes("files/models/Duck.glb") },
position = Position(0f, 0f, 0f),
)

// multiple copies from a shared asset
val tree = rememberGltfAsset { Res.readBytes("files/models/Tree.glb") }
GltfInstance(tree, position = Position(0f, 0f, 0f))
GltfInstance(tree, position = Position(5f, 0f, 0f))

Emitting from a list

Wrap each call in key() when the collection can change:

enemies.forEach { enemy -> key(enemy.id) { GltfInstance(enemyAsset, enemy.position) } }

Without it, identity follows the slot rather than the item, so inserting or reordering makes every later entry destroy its instance and build a new one — restarting animation playback and re-running onCreate. Appending to the end is the only safe unkeyed case.

Lifecycle Note

Filament's gltfio does not have a destroyInstance API; instances are automatically destroyed when the parent GltfAsset is destroyed. To avoid memory pressure, avoid creating hundreds of dynamic instances from a single long-lived asset.

Parameters

asset

A loaded asset from rememberGltfAsset, or null while still loading.

position

World-space translation.

rotation

World-space rotation. Build one with Rotation.axisAngle/Rotation.euler.

scale

Per-axis scale.

pivot

The point in mesh space that rotation and scale revolve around, and that ends up at position in world space. Defaults to (0,0,0) — the glTF's own root origin. Use this to e.g. rotate a model around its centre when the glTF was authored with the origin at one corner. With fitToSize, it is in the fitted space, where the model is centred on the origin.

fitToSize

Scales the model so its largest side is this many units and centres it on position, before rotation and scale apply — for showing a model whose size and origin you don't know. Null (the default) keeps the model as authored.

animationState

Optional hoisted, auto-advancing playback state from rememberAnimationState. When non-null it drives the animator every frame (with cross-fade blending); pause it and call AnimationState.seek to hold a pose. Instances sharing one state play in step. Null leaves the animator alone, for onUpdate to drive by hand.

morphWeights

Optional vertex morph-target weights applied to every renderable in the instance that has morph targets. Pass null to leave morph weights untouched.

visible

Whether the instance's entities are in the scene. False removes them (cheaply, keeping the instance and its state alive) — a show/hide toggle.

castShadows

Overrides shadow casting for every renderable in the instance; null (the default) keeps what the asset authored — matching the primitives' castShadows toggle.

receiveShadows

Overrides shadow receiving for every renderable in the instance; null (the default) keeps what the asset authored.

materialVariant

The KHR_materials_variants variant to draw with, by name (see GltfAsset.materialVariants); null (the default) keeps the authored materials. A name the asset lacks is ignored with a warning.

onCreate

Called once when the instance is first added to the scene. Use for one-time setup such as swapping materials or finding entities by name.

onUpdate

Called on every recomposition (not every frame — a static scene never recomposes). Use it to react to Compose state changes with low-level calls; for genuinely per-frame work use OnFrame or rememberFilamentScene's FilamentEffect.

onTap

Called when a tap on a io.github.erkko68.filament.compose.FilamentView hits any part of this instance, with the world point it hit. Null answers with the enclosing Group's onTap, if any.