LittleJS 1.30.1

GLTF

LittleJS glTF Plugin

  • Loads glTF 2.0 models: a .gltf with its .bin and images beside it, or a .glb with everything in one file
  • A model comes back as parts, one Mesh per primitive of every node placed by the node tree, each with its material's color and base color texture, plus everything combined into one Mesh
  • Geometry: positions, normals, uvs, vertex colors and indices, and skins, the four strongest joints of a vertex of up to eight; morph targets are not read
  • Animations play through the GLTFObject that createObject makes: parts that move, turn and scale, like doors, wheels and propellers, and skinned characters, their meshes bent by their joints each frame; play takes a blend time to cross-fade from one animation to the next
  • Materials give a base color and texture and whether they blend; glass made with KHR_materials_transmission blends too, and a KHR_materials_unlit material comes in emissive, its own color with no shading
  • A material's normal map and emissive map load too, with its normal scale and emissive factor, read at the base color texture's uvs; roughness, metalness and occlusion maps are not loaded
  • The base color texture reads the uv set its texCoord names, moved by KHR_texture_transform as gltfpack and Blender write it
  • An OPAQUE material, the default, ignores its texture's alpha as the format says: its texture loads with alpha set to 1, so the 3D pass cuts no holes in it, as a copy when a MASK or BLEND material uses the texture too; MASK always cuts at half by the texture's alpha alone: alphaCutoff, the material's alpha and the vertex alpha are not read, so a mask goes in the texture, as exporters write it
  • Material and vertex colors are linear in glTF and are converted to sRGB at load, the space textures are in
  • glTF and LittleJS agree on the axes, y up and -z forward, on counter clockwise triangles and on uvs running down
  • Requires the Render3D plugin

Classes

Functions

Typedefs

Functions

loadGLTF(url) → Promise<GLTFModel>asyncgltf.js:486

Load a glTF or GLB model, the .bin and images of a .gltf from beside it

  • A texture only OPAQUE materials use loads with its alpha set to 1, so the 3D pass cuts no holes in it
url string
parseGLTF(data, baseUrl, files) → Promise<GLTFModel>asyncgltf.js:525

Parse a model from GLB bytes or glTF JSON, fetching the buffers and images it refers to

  • A .gltf names its .bin and image files, which are fetched from baseUrl, or found among files: what a game has in hand, like the files dropped on the page, by their paths in the drop; with files, baseUrl is the .gltf's own folder among them ('' or 'models/house/'), its names are read from there, and a name found nowhere there is taken by its file name alone only when one file of the drop has it; only an http, https or blob uri is fetched then
  • A file the model needs that is not found is named in the error, and an image that can not be read is named in a warning and left out
data ArrayBuffer|ArrayBufferView|Object<string, any>|string

GLB bytes, or the glTF JSON as bytes, text or an object

baseUrl string optional

Where the .bin and image files are, with its trailing slash; loadGLTF passes the file's folder

files Map<string, Blob> optional

The files it refers to, by their paths, in place of fetching them

// the files of a drop, a .gltf with its .bin and textures, by their names
const files = new Map([...dataTransfer.files].map((file)=> [file.name, file]));
const gltf = [...files.values()].find((file)=> file.name.endsWith('.gltf'));
const model = await parseGLTF(await gltf.text(), '', files);

Typedefs

GLTFChannel : Objectgltf.js:119

What one channel of an animation moves, as the loader reads it

node number

The index of the node it moves

path 'translation'|'rotation'|'scale'

Which of the node's transform

interpolation 'LINEAR'|'STEP'|'CUBICSPLINE'

How to go between keys

times ArrayLike<number>

The key times in seconds

values ArrayLike<number>

The key values, components numbers each, and an in and out tangent around each with CUBICSPLINE

components number

4 for a rotation, 3 otherwise

GLTFNodeTree : Objectgltf.js:110

A model's nodes as an animation needs them: each as the file has it, its parent, and where it rests

parents Array<(number|undefined)>

Each node's parent, undefined for a root

restInverse Array<Matrix4>

The inverse of where each node is baked in the model

restPose Array<(Matrix4|undefined)>

From where a node is baked to where it rests, when they differ

GLTFNodeTRS : Objectgltf.js:103

A node's place as an animation sets it: its translation, rotation as a quaternion x y z w, and scale

translation Array<number>
rotation Array<number>
scale Array<number>
GLTFSkin : Objectgltf.js:90

What bends a skinned part: its joints, the nodes that move it, their inverse bind matrices, and for each vertex of its mesh four joints and four weights, with the place and normal each pose bends from

joints Array<number>

The joints, as node numbers

inverseBind Array<Matrix4>

Each joint's inverse bind matrix

vertexJoints Uint16Array

Four joints a vertex, as places in joints

vertexWeights Float32Array

Four weights a vertex, summing to 1

bindPoints Float32Array

Each vertex's place as stored, x y z

bindNormals Float32Array

Each vertex's normal as stored, x y z