Kivicube Docs

English

简体中文

Appearance

glTF Models ​

Related references:

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 ​

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

Use an ArrayBuffer ​

js
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:

js
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 ​

js
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 ​

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

Play an Animation ​

js
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 ​

js
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 ​

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

Animation Events ​

js
const obj = await api.getObject('rabbit');
  • play - fires when animation starts playing
js
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
js
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
js
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
js
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: