glTF Models

Related references:

• Scene API / Dynamic Content Creation
• Scene API / Animation

Support for glTF / GLB models in the Web plugin mainly focuses on two areas: dynamically creating models and controlling model animation.

Create a Model

Use a URL

const model = await api.createGltfModel('https://your.domain.com/model/rabbit.glb');
await api.add(model);

Use an ArrayBuffer

const response = await fetch('/my-assets/model/rabbit.glb');
const buffer = await response.arrayBuffer();

const model = await api.createGltfModel(buffer);
await api.add(model);

If you use a URL, make sure the asset server allows CORS access from https://www.kivicube.com.

Models Are the Most Common Composite Objects

A glTF model is usually not a single object but an object tree. So a common pattern is:

const model = await api.getObject('rabbit');
const children = await api.getChildren(model);

If you need to control a node inside the model, use getChildByProperty() to find it.

Basic Operations

await api.setPosition(model, 0, 0, 0);
await api.setRotation(model, 0, Math.PI / 2, 0);
await api.setScale(model, 1.5, 1.5, 1.5);

Animation Control

Read Animation Names

const names = await api.getAnimationNames(model);
console.log(names);

Play an Animation

await api.playAnimation(model, {
  name: 'Idle',
  loop: true,
  repeat: Infinity,
});

Animation options also support:

• loop - whether playback loops
• repeat - how many times to repeat
• repeatMode - loop mode. 0: normal, 1: ping-pong
• timeScale - playback speed multiplier. 1 is original speed. Default is 1
• weight - blend weight when multiple animations play together. Default is 1
• clampWhenFinished - whether to stay on the last frame after playback finishes
• resetLoopCount - reset the internal loop counter to 0

Pause, Stop, and Replay

await api.pauseAnimation(model, 'Idle');
await api.stopAnimation(model, 'Idle');
// Supported options are the same as playAnimation.
await api.playbackAnimation(model, { name: 'Idle', loop: true });

Read Playback State

const running = await api.animationIsRunning(model, 'Idle');
const loop = await api.isAnimationLoop(model, 'Idle');
const runningNames = await api.getAnimationIsRunningNames(model);

Animation Events

const obj = await api.getObject('rabbit');

• play - fires when animation starts playing

function onPlay(event) {
  // animationName - the name of the animation currently playing
  const { type, target, animationName } = event;
}

await api.on('play', onPlay, obj);

• pause - fires when animation pauses

function onPause(event) {
  // animationName - the name of the animation currently paused
  const { type, target, animationName } = event;
}

await api.on('pause', onPause, obj);

• ended - fires when animation finishes naturally

function onEnded(event) {
  // animationName - the name of the animation that just finished
  const { type, target, animationName } = event;
}

await api.on('ended', onEnded, obj);

• replay - fires when animation replays

function onReplay(event) {
  // animationName - the name of the animation currently replaying
  const { type, target, animationName } = event;
}

await api.on('replay', onReplay, obj);

Custom animations and built-in model animations share the same event and control model.

Lighting and Environment Maps

Models are often the object type that most benefits from lighting and environment maps. A common workflow is:

1. create the model
2. add it to the scene
3. set its position and scale
4. adjust environment mapping and tone mapping
5. fine-tune the default lights

Related capabilities:

• Lighting
• Environment Maps
• Tone Mapping
• Anisotropy