littlejsengine 1.24.3 → 1.26.0

package/plugins/gltf.js

@@ -3,9 +3,11 @@
  * - 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; skins and morph targets are not read
- * - Node animations play: parts that move, turn and scale, like doors, wheels and propellers, through the
- *   GLTFObject that createObject makes; a skinned character's walk is not read
+ * - 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
@@ -23,6 +25,7 @@
  * const model = await loadGLTF('ship.glb');   // in an async gameInit
  * const ship = model.createObject(vec3(0, 1, 0)); // an object with a child per part, textures and all
  * ship.play('fly');                            // and its animation, by name or number
+ * ship.play('land', false, 1, .3);             // then another, cross-faded over .3 seconds
  * new EngineObject3D(vec3(), model.mesh);      // or the whole thing as one mesh, still
  */
 
@@ -35,7 +38,8 @@
  */
 class GLTFPart
 {
-    /** @param {string} name @param {Mesh} mesh @param {Color} color @param {TextureInfo|undefined} textureInfo @param {boolean} transparent */
+    /** Make a part, as the loader does for each primitive
+     *  @param {string} name @param {Mesh} mesh @param {Color} color @param {TextureInfo|undefined} textureInfo @param {boolean} transparent */
     constructor(name, mesh, color, textureInfo, transparent)
     {
         /** @property {string} - The node's name, or its mesh's */
@@ -69,9 +73,32 @@ class GLTFPart
         this.emissiveMap = undefined;
         /** @property {Color} - The emissiveFactor, which multiplies the emissive map */
         this.emissiveMapColor = WHITE;
+        /** @property {number} - The material's roughnessFactor, 0 a mirror to 1 matte, 1 when it has none as the
+         *  format says; the object createObject makes takes it as its roughness, which sets its shininess */
+        this.roughness = 1;
+        /** @property {GLTFSkin|undefined} - For a skinned mesh, what bends it: mesh is its resting pose, and the
+         *  object createObject makes bends a copy of its own to each pose
+         *  @type {GLTFSkin|undefined} */
+        this.skin = undefined;
+        // which of the file's vertices each of the mesh's is, when flat normals split them, for a skin
+        /** @type {Array<number>|undefined} */
+        this.vertexSource = undefined;
     }
 }
 
+/**
+ * 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
+ * @typedef {Object} GLTFSkin
+ * @property {Array<number>} joints - The joints, as node numbers
+ * @property {Array<Matrix4>} inverseBind - Each joint's inverse bind matrix
+ * @property {Uint16Array} vertexJoints - Four joints a vertex, as places in joints
+ * @property {Float32Array} vertexWeights - Four weights a vertex, summing to 1
+ * @property {Float32Array} bindPoints - Each vertex's place as stored, x y z
+ * @property {Float32Array} bindNormals - Each vertex's normal as stored, x y z
+ * @memberof GLTF
+ */
+
 /**
  * GLTFAnimation - One animation of a model: keys that move, turn and scale its nodes over time
  * - Play it through the GLTFObject that model.createObject makes
@@ -79,7 +106,8 @@ class GLTFPart
  */
 class GLTFAnimation
 {
-    /** @param {string} name @param {Array<Object>} channels */
+    /** Make an animation from its channels, as the loader does
+     *  @param {string} name @param {Array<Object>} channels */
     constructor(name, channels)
     {
         /** @property {string} - Its name in the file, or 'animation' and its number when it has none */
@@ -100,7 +128,8 @@ class GLTFAnimation
  */
 class GLTFModel
 {
-    /** @param {Array<GLTFPart>} parts @param {Array<GLTFAnimation>} [animations] @param {Object} [nodeTree] */
+    /** Make a model from its parts, as the loader does
+     *  @param {Array<GLTFPart>} parts @param {Array<GLTFAnimation>} [animations] @param {Object} [nodeTree] */
     constructor(parts, animations=[], nodeTree)
     {
         /** @property {Array<GLTFPart>} - One per primitive of every node that has a mesh */
@@ -108,13 +137,15 @@ class GLTFModel
         /** @property {Array<GLTFAnimation>} - The animations, play one through createObject's GLTFObject
          *  @type {Array<GLTFAnimation>} */
         this.animations = animations;
+        /** @type {{nodes: Array<Object>, parents: Array<number|undefined>, restInverse: Array<Matrix4>,
+         *  restPose: Array<Matrix4|undefined>}|undefined} */
         this.nodeTree = nodeTree;             // each node's parent and resting place, for animation
         this.modelMatrix = new Matrix4;       // what center, fit and transform did to the parts, animation works through it
         /** @property {Mesh} - Every part combined, each tinted with its material color; the texture is textureInfo,
          *  and blending and unlit stay with the parts, which createObject draws */
         this.mesh = new Mesh;
         for (const part of parts) // a part baked at scale 1 from a node resting at 0 goes in as it rests
-            this.mesh.combine(part.mesh, nodeTree?.restPose?.[part.node] || RENDER3D_IDENTITY, part.color);
+            this.mesh.combine(part.mesh, !part.skin && nodeTree?.restPose?.[part.node] || RENDER3D_IDENTITY, part.color);
         // the one texture every part uses, when they all do; a part without one has no uvs into it, so a model
         // that mixes plain and textured parts, or uses several textures, is drawn through createObject instead
         const textures = new Set(parts.map(p=> p.textureInfo));
@@ -180,29 +211,18 @@ class GLTFModel
      *  @return {Array<Matrix4>} */
     getPose(animation, time)
     {
-        const tree = this.nodeTree;
-        if (!tree) return this.parts.map(()=> new Matrix4);
-
-        // the nodes the animation moves get its values at this time, every other node keeps its own
-        const moved = new Map;
-        for (const channel of animation.channels)
-        {
-            let node = moved.get(channel.node);
-            node || moved.set(channel.node, node = gltfNodeTRS(tree.nodes[channel.node]));
-            gltfSample(channel, time, node[channel.path]);
-        }
+        if (!this.nodeTree) return this.parts.map(()=> new Matrix4);
+        return this.partPoses(gltfNodeWorlds(this.nodeTree, gltfPoseNodes(this.nodeTree, animation, time)));
+    }
 
-        // then each node's place in the model through its parents, and each part's move from where it rests,
-        // through what center and fit did: modelMatrix * now * rest inverse * modelMatrix inverse
-        const world = [];
-        const worldOf = (i)=>
-        {
-            if (world[i]) return world[i];
-            const local = gltfNodeMatrix(moved.get(i) || tree.nodes[i]), parent = tree.parents[i];
-            return world[i] = parent === undefined ? local : worldOf(parent).copy().multiply(local);
-        };
-        const model = this.modelMatrix, modelInverse = model.copy().invert();
-        return this.parts.map(part=> model.copy().multiply(worldOf(part.node)).multiply(tree.restInverse[part.node]).multiply(modelInverse));
+    // each part's move from where it rests, with each node's place in the model from worldOf, through what center
+    // and fit did: modelMatrix * now * rest inverse * modelMatrix inverse; a skinned part is posed by its joints
+    // and stays where it is
+    partPoses(worldOf)
+    {
+        const tree = this.nodeTree, model = this.modelMatrix, modelInverse = model.copy().invert();
+        return this.parts.map(part=> part.skin ? new Matrix4 :
+            model.copy().multiply(worldOf(part.node)).multiply(tree.restInverse[part.node]).multiply(modelInverse));
     }
 
     /** Free the GPU buffers of every part's mesh and of the combined mesh, and the textures, for a model that is
@@ -263,19 +283,33 @@ class GLTFObject extends EngineObject3D
         this.animationLoop = true;
         /** @property {boolean} - Whether it is moving through the animation now */
         this.animationPlaying = false;
+        // what a cross-fade comes from: an animation going on as it was, or a pose held, and how far it is
+        /** @type {{animation?: GLTFAnimation, time?: number, speed?: number, loop?: boolean, nodes?: Map<number, Object>}|undefined} */
+        this.blendFrom = undefined;
+        this.blendTime = 0;
+        this.blendElapsed = 0;
+        // each node's values and place in the model as last posed, for a fade from here and for getJointMatrix, and
+        // whether that pose was a mix, as a fade stopped part way holds it
+        /** @type {Map<number, Object>|undefined} */
+        this.poseNodes = undefined;
+        this.poseMixed = false;
+        /** @type {(function(number): Matrix4)|undefined} */
+        this.poseWorldOf = undefined;
         /** @property {Array<EngineObject3D>} - The child that draws each of the model's parts, in the order of
          *  model.parts, which an animation poses; one destroyed or taken off the object is left alone
          *  @type {Array<EngineObject3D>} */
         this.parts = [];
         for (const part of model.parts)
         {
-            const o = new EngineObject3D(vec3(), part.mesh, part.textureInfo, part.color);
+            // a skinned part bends a mesh of its own, so objects of one model each hold their own pose
+            const o = new EngineObject3D(vec3(), part.skin ? gltfSkinMeshCopy(part.mesh) : part.mesh, part.textureInfo, part.color);
             o.transparent = part.transparent;
             o.pixelated = part.pixelated;
             o.emissive = part.unlit ? 1 : 0;
             o.normalMap = part.normalMap, o.normalScale = part.normalScale;
             o.emissiveMap = part.emissiveMap, o.emissiveMapColor = part.emissiveMapColor.copy(); // its own, as color is
-            const rest = model.nodeTree?.restPose?.[part.node];
+            o.roughness = part.roughness;
+            const rest = !part.skin && model.nodeTree?.restPose?.[part.node];
             if (rest)
             {
                 // baked at scale 1 from a node resting at 0, it starts as it rests, where a pose would put it
@@ -285,20 +319,50 @@ class GLTFObject extends EngineObject3D
                 o.rotation3D = m.getRotation();
                 o.scale3D = m.getScale();
             }
+            render3DShareSettings(o, this); // what is set on the model, the part's own material otherwise
             this.addChild(o);
             this.parts.push(o);
         }
     }
 
-    /** Play an animation from its start
+    /** Destroy the object and its parts, and free the meshes its skinned parts bend, which are its own
+     *  @param {boolean} [immediate] */
+    destroy(immediate)
+    {
+        if (this.destroyed) return;
+        this.parts.forEach((o, i)=> this.model.parts[i]?.skin && o.mesh?.dispose());
+        super.destroy(immediate);
+    }
+
+    /** Play an animation from its start, at once or cross-faded from the pose it is in
+     *  - A play with a blend of the animation already playing goes on with it, so state code may call it each
+     *    frame; without a blend it starts the animation again
      *  @param {string|number|GLTFAnimation} [animation] - Its name, its number in model.animations, or itself
      *  @param {boolean} [loop] - Start again at the end, or stop there
-     *  @param {number} [speed] - 1 is as made, negative plays it backward from its end */
-    play(animation=0, loop=true, speed=1)
+     *  @param {number} [speed] - 1 is as made, negative plays it backward from its end
+     *  @param {number} [blend] - Seconds to cross-fade from the pose it is in, 0 to switch at once; the animation
+     *    it comes from goes on through the fade, and a fade started during another fades from the mix there */
+    play(animation=0, loop=true, speed=1, blend=0)
     {
         const found = this.model.getAnimation(animation);
         ASSERT(found, 'the model has no animation ' + animation, this.model.animations.map(a=> a.name));
         if (!found) return;
+        if (blend > 0 && found === this.animation && this.animationPlaying)
+        {
+            this.animationLoop = loop, this.animationSpeed = speed;
+            return;
+        }
+        const fading = this.blendFrom;
+        this.blendFrom = undefined;
+        if (blend > 0)
+        {
+            // from the animation playing, going on as it was, or from the pose held, a fade's mix included
+            const from = this.animation && !fading && !this.poseMixed ? {animation: this.animation, time: this.animationTime,
+                speed: this.animationPlaying ? this.animationSpeed : 0, loop: this.animationLoop} : undefined;
+            this.blendFrom = from || {nodes: this.poseNodes || new Map};
+            this.blendTime = blend;
+            this.blendElapsed = 0;
+        }
         this.animation = found;
         this.animationLoop = loop;
         this.animationSpeed = speed;
@@ -306,21 +370,39 @@ class GLTFObject extends EngineObject3D
         this.setAnimationTime(speed < 0 ? found.duration : 0);
     }
 
-    /** Stop the animation where it is, the parts hold that pose */
-    stop() { this.animationPlaying = false; }
+    /** Stop the animation where it is, the parts hold that pose; a cross-fade going on stops too, holding the mix */
+    stop() { this.animationPlaying = false; this.blendFrom = undefined; }
 
     /** Put the parts where the animation has them at a time, playing or not
      *  @param {number} time - Seconds into the animation */
     setAnimationTime(time)
     {
         this.animationTime = time;
-        if (!this.animation) return;
+        const model = this.model, tree = model.nodeTree;
+        if (!this.animation || !tree) return;
+
+        // each node's values now, mixed with what a fade comes from by how far it is, eased in and out
+        let nodes = gltfPoseNodes(tree, this.animation, time);
+        const from = this.blendFrom;
+        if (from)
+        {
+            const fromNodes = from.nodes || gltfPoseNodes(tree, from.animation, from.time);
+            nodes = gltfPoseBlend(tree, fromNodes, nodes, smoothStep(clamp(this.blendElapsed / this.blendTime)));
+        }
+        const worldOf = gltfNodeWorlds(tree, nodes);
+        this.poseNodes = nodes, this.poseWorldOf = worldOf, this.poseMixed = !!from;
+
         // its own list of the part objects, so a child removed or added does not hand a part another's pose
-        const pose = this.model.getPose(this.animation, time), parts = this.parts;
+        const pose = model.partPoses(worldOf), parts = this.parts;
         for (let i = 0; i < pose.length && i < parts.length; ++i)
         {
-            const o = parts[i], m = pose[i];
+            const o = parts[i], m = pose[i], skin = model.parts[i].skin;
             if (o.destroyed || o.parent !== this) continue;
+            if (skin)
+            {
+                gltfSkinApply(skin, worldOf, model.modelMatrix, o.mesh); // bent by its joints, where it is
+                continue;
+            }
             // drawn with the whole pose, which a parent's uneven scale can shear, the parts kept for what reads them
             o.localMatrix = m;
             o.pos3D = m.getTranslation();
@@ -329,23 +411,40 @@ class GLTFObject extends EngineObject3D
         }
     }
 
-    /** Move through the animation, called automatically each frame */
+    /** Move through the animation, and a cross-fade into it, called automatically each frame */
     update()
     {
         super.update();
-        const animation = this.animation;
-        if (!this.animationPlaying || !animation) return;
-        const duration = animation.duration;
-        let t = this.animationTime + timeDelta * this.animationSpeed;
-        if (this.animationLoop)
-            t = duration ? mod(t, duration) : 0;
-        else if (t >= duration || t <= 0)
+        const animation = this.animation, from = this.blendFrom;
+        if (!animation || !this.animationPlaying && !from) return;
+        let t = this.animationTime;
+        if (this.animationPlaying)
         {
-            // the end, or the start when playing backward: hold the last pose there
-            t = clamp(t, 0, duration);
-            this.animationPlaying = false;
+            t = gltfAnimationStep(animation, t, this.animationSpeed, this.animationLoop);
+            if (!this.animationLoop && (t >= animation.duration || t <= 0))
+                this.animationPlaying = false; // the end, or the start when playing backward: hold the last pose there
+        }
+        if (from)
+        {
+            this.blendElapsed += timeDelta;
+            if (from.animation) // what it fades from goes on as it was
+                from.time = gltfAnimationStep(from.animation, from.time, from.speed, from.loop);
         }
         this.setAnimationTime(t);
+        if (from && this.blendElapsed >= this.blendTime)
+            this.blendFrom = undefined; // faded all the way, the pose just set is the animation's own
+    }
+
+    /** A node's matrix in the world as the model is posed now, by its name in the file, to hang something on a
+     *  joint, a sword on a hand or a hat on a head; undefined when the model has no node of that name
+     *  @param {string} name
+     *  @return {Matrix4|undefined} */
+    getJointMatrix(name)
+    {
+        const tree = this.model.nodeTree, index = tree?.nodes?.findIndex(node=> node.name === name) ?? -1;
+        if (index < 0) return;
+        const worldOf = this.poseWorldOf || gltfNodeWorlds(tree, new Map);
+        return this.getMatrix().multiply(this.model.modelMatrix).multiply(worldOf(index));
     }
 }
 
@@ -358,16 +457,23 @@ class GLTFObject extends EngineObject3D
  *  @memberof GLTF */
 async function loadGLTF(url)
 {
-    const response = await fetch(url);
+    const response = await loadFetch(url, 'loadGLTF');
     if (!response.ok)
-        throw new Error('loadGLTF failed: ' + url);
+        throw new Error(`loadGLTF: could not load ${url}, ${response.status} ${response.statusText}`);
     // the files beside it are beside where it came from, after any redirect; a blob or data url has nothing
     // beside it, and a model in one is whole, or parsed with parseGLTF and a base of its own
     const from = response.url || url;
     let base = '';
     if (!/^(blob|data):/i.test(from))
         base = response.url ? new URL('.', from).href : from.slice(0, from.lastIndexOf('/') + 1);
-    return parseGLTF(await response.arrayBuffer(), base);
+    const data = await response.arrayBuffer();
+    try { return await parseGLTF(data, base); }
+    catch (e)
+    {
+        // which file, and a web page, as a dev server sends for a mistyped path, said as one
+        const page = loadIsWebPage(String.fromCharCode(...new Uint8Array(data, 0, min(data.byteLength, 64))));
+        throw new Error('loadGLTF ' + url + (page ? ' is a web page, so the path may be wrong' : ': ' + e.message));
+    }
 }
 
 /** Parse a model from GLB bytes or glTF JSON, fetching the buffers and images it refers to
@@ -378,7 +484,7 @@ async function loadGLTF(url)
  *    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
- *  @param {ArrayBuffer|Object|string} data - GLB bytes, or the glTF JSON as bytes, text or an object
+ *  @param {ArrayBuffer|ArrayBufferView|Object<string, any>|string} data - GLB bytes, or the glTF JSON as bytes, text or an object
  *  @param {string} [baseUrl] - Where the .bin and image files are, with its trailing slash; loadGLTF passes the file's folder
  *  @param {Map<string, Blob>} [files] - The files it refers to, by their paths, in place of fetching them
  *  @return {Promise<GLTFModel>}
@@ -390,7 +496,10 @@ async function loadGLTF(url)
  *  @memberof GLTF */
 async function parseGLTF(data, baseUrl='', files)
 {
-    let json = data, glbBuffer;
+    // bytes as a typed array, a Node Buffer or a view into a bigger buffer, read as an ArrayBuffer of just them
+    if (ArrayBuffer.isView(data))
+        data = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    let json = /** @type {any} */ (data), glbBuffer; // bytes, text or the parsed glTF, an object once parsed
     if (data instanceof ArrayBuffer)
     {
         const view = new DataView(data);
@@ -474,6 +583,9 @@ async function parseGLTF(data, baseUrl='', files)
     // the parts: the scene's nodes walked with their transforms, every primitive of a node's mesh placed by it;
     // each node's parent and resting place are kept, so an animation can move a part from where it rests
     const parts = [], parents = [], restInverse = [], restPose = [], visited = new Set;
+    // every node's parent from the children lists, so a joint outside the scene's nodes keeps its own; the walk
+    // below sets them again for the nodes it reaches
+    (json.nodes || []).forEach((node, i)=> (node.children || []).forEach((child)=> parents[child] ??= i));
     const visit = (index, parentMatrix, parentIndex, parentRest)=>
     {
         // nodes are trees, so one reached again is a cycle or a node with two parents, a file problem
@@ -499,11 +611,18 @@ async function parseGLTF(data, baseUrl='', files)
         if (node.mesh !== undefined)
         {
             const mesh = json.meshes[node.mesh];
+            // a skinned mesh is placed by its joints and not by its node, as the format says, so it is read as stored
+            const skin = node.skin !== undefined ? json.skins?.[node.skin] : undefined;
             for (const primitive of mesh.primitives)
             {
-                const part = gltfPart(json, buffers, textures, primitive, matrix, node.name || mesh.name || 'part ' + parts.length);
+                const skinned = skin?.joints?.length && primitive.attributes.JOINTS_0 !== undefined &&
+                    primitive.attributes.WEIGHTS_0 !== undefined;
+                const part = gltfPart(json, buffers, textures, primitive, skinned ? new Matrix4 : matrix,
+                    node.name || mesh.name || 'part ' + parts.length);
                 if (!part) continue;
                 part.node = index;
+                if (skinned)
+                    part.skin = gltfSkin(json, buffers, skin, primitive, part);
                 parts.push(part);
             }
         }
@@ -548,8 +667,194 @@ async function parseGLTF(data, baseUrl='', files)
     const used = new Set(parts.flatMap(p=> [p.textureInfo, p.normalMap, p.emissiveMap]));
     for (const texture of textures)
         texture && !used.has(texture) && texture.destroyWebGLTexture();
-    return new GLTFModel(parts, animations, {nodes: json.nodes, parents, restInverse, restPose});
+    // a skinned part rests as its joints place it, with nothing moved
+    const nodeTree = {nodes: json.nodes, parents, restInverse, restPose}, restWorlds = gltfNodeWorlds(nodeTree, new Map);
+    for (const part of parts)
+        part.skin && gltfSkinApply(part.skin, restWorlds, RENDER3D_IDENTITY, part.mesh);
+    return new GLTFModel(parts, animations, nodeTree);
+}
+
+// the values of each node an animation moves at a time, a Map of node to its translation, rotation and scale;
+// every other node keeps its own
+function gltfPoseNodes(tree, animation, time)
+{
+    const moved = new Map;
+    for (const channel of animation.channels)
+    {
+        let node = moved.get(channel.node);
+        node || moved.set(channel.node, node = gltfNodeTRS(tree.nodes[channel.node]));
+        gltfSample(channel, time, node[channel.path]);
+    }
+    return moved;
+}
+
+// two such sets of node values mixed by a weight, 0 all a, 1 all b: places and scales in a line, turns the short
+// way round; a node only one moves has its own values in the other
+function gltfPoseBlend(tree, a, b, weight)
+{
+    const mixed = new Map, lerp3 = (p, q)=> p.map((v, i)=> v + (q[i] - v) * weight);
+    for (const node of new Set([...a.keys(), ...b.keys()]))
+    {
+        const p = a.get(node) || gltfNodeTRS(tree.nodes[node]), q = b.get(node) || gltfNodeTRS(tree.nodes[node]);
+        mixed.set(node, {translation: lerp3(p.translation, q.translation), scale: lerp3(p.scale, q.scale),
+            rotation: gltfSlerp(p.rotation, q.rotation, weight)});
+    }
+    return mixed;
+}
+
+// the turn between two quaternions, x y z w, a part of the way along the short way round
+function gltfSlerp(a, b, t)
+{
+    let dot = a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3], sign = 1;
+    if (dot < 0)
+        dot = -dot, sign = -1; // the same turn the other way round is shorter
+    let wa = 1 - t, wb = t * sign;
+    if (dot < .9995)
+    {
+        // along the arc; nearly the same turn is done in a line, where the arc's sine goes to nothing
+        const angle = Math.acos(dot), s = sin(angle);
+        wa = sin(wa * angle) / s, wb = sin(t * angle) / s * sign;
+    }
+    const out = a.map((v, i)=> v * wa + b[i] * wb), l = hypot(...out) || 1;
+    return out.map(v=> v / l);
+}
+
+// each node's place in the model through its parents, with the values in moved for the nodes there, kept as found
+function gltfNodeWorlds(tree, moved)
+{
+    const world = [];
+    const worldOf = (i)=>
+    {
+        if (world[i]) return world[i];
+        const local = gltfNodeMatrix(moved.get(i) || tree.nodes[i]), parent = tree.parents[i];
+        return world[i] = parent === undefined ? local : worldOf(parent).copy().multiply(local);
+    };
+    return worldOf;
+}
+
+// an animation's time a frame on, at a speed, around again when it loops, held at its ends when it does not
+function gltfAnimationStep(animation, time, speed, loop)
+{
+    const duration = animation.duration, t = time + timeDelta * speed;
+    return loop ? duration ? mod(t, duration) : 0 : clamp(t, 0, duration);
+}
+
+// a skinned primitive's skin: its joints, the nodes that bend it, their inverse bind matrices, and for each vertex
+// of the part's mesh four joints, as places in that list, and four weights made to sum to 1, with its place and
+// normal as stored, which each pose bends from; a mesh split for flat normals maps its corners to the file's
+function gltfSkin(json, buffers, skin, primitive, part)
+{
+    const joints = skin.joints, mesh = part.mesh, count = mesh.points.length;
+    const bind = skin.inverseBindMatrices !== undefined ? gltfAccessor(json, buffers, skin.inverseBindMatrices).data : undefined;
+    const inverseBind = joints.map((_, j)=> bind ? new Matrix4(bind.subarray(j * 16, j * 16 + 16)) : new Matrix4);
+    // a second set of four, as rigs from many tools have, is read too, and each vertex keeps its four strongest
+    const attributes = primitive.attributes, read = (name)=> gltfAccessor(json, buffers, attributes[name]).data;
+    const sets = [[read('JOINTS_0'), read('WEIGHTS_0')]];
+    attributes.JOINTS_1 !== undefined && attributes.WEIGHTS_1 !== undefined && sets.push([read('JOINTS_1'), read('WEIGHTS_1')]);
+    const vertexJoints = new Uint16Array(count * 4), vertexWeights = new Float32Array(count * 4);
+    const bindPoints = new Float32Array(count * 3), bindNormals = new Float32Array(count * 3);
+    for (let v = 0; v < count; ++v)
+    {
+        const from = part.vertexSource ? part.vertexSource[v] : v, influences = [];
+        for (const [fileJoints, fileWeights] of sets)
+            for (let k = 0; k < 4; ++k)
+                influences.push([fileJoints[from * 4 + k], fileWeights[from * 4 + k]]);
+        sets.length > 1 && influences.sort((a, b)=> b[1] - a[1]); // the strongest four first
+        let total = 0;
+        for (let k = 0; k < 4; ++k)
+            total += influences[k][1];
+        for (let k = 0; k < 4; ++k)
+        {
+            const [joint, weight] = influences[k];
+            vertexJoints[v * 4 + k] = joint < joints.length ? joint : 0;
+            vertexWeights[v * 4 + k] = total ? weight / total : k ? 0 : 1;
+        }
+        const p = mesh.points[v], n = mesh.normals[v];
+        bindPoints.set([p.x, p.y, p.z], v * 3);
+        bindNormals.set([n.x, n.y, n.z], v * 3);
+        // vectors of its own, as each pose writes into them, where a flat normal is shared by a face's corners
+        mesh.points[v] = p.copy(), mesh.normals[v] = n.copy();
+    }
+    return {joints, inverseBind, vertexJoints, vertexWeights, bindPoints, bindNormals};
+}
+
+// a skinned part's mesh copied with vectors of its own for an object to bend, its upload rewriting only the values
+function gltfSkinMeshCopy(mesh)
+{
+    const copy = new Mesh;
+    copy.points = mesh.points.map(p=> p.copy());
+    copy.normals = mesh.normals.map(n=> n.copy());
+    copy.uvs = mesh.uvs.slice();
+    copy.colors = mesh.colors.slice();
+    copy.indices = mesh.indices && mesh.indices.slice();
+    copy.doubleSided = mesh.doubleSided;
+    copy.dynamicDraw = true;
+    return copy;
+}
+
+// bend a skinned mesh to a pose: each vertex its stored place moved by its four joints, weighted, and its normal by
+// their normal matrices, each joint's matrix modelMatrix * its place now * its inverse bind; written into the
+// mesh's own vectors, so a pose makes nothing for each vertex, and once an upload has laid the mesh out for the GPU
+// into that data too, with the radius and box the upload would measure, so it sends the data as it is
+function gltfSkinApply(skin, worldOf, modelMatrix, mesh)
+{
+    // each joint's point matrix, 12 numbers, then its normal matrix, 9, in one array the skin keeps
+    const jointCount = skin.joints.length, M = skin.jointMatrices ||= new Float32Array(jointCount * 21);
+    const m = gltfSkinScratch[0], n = gltfSkinScratch[1];
+    for (let j = 0; j < jointCount; ++j)
+    {
+        m.m.set(modelMatrix.m);
+        m.multiply(worldOf(skin.joints[j])).multiply(skin.inverseBind[j]);
+        n.m.set(m.m);
+        n.invert().transpose();
+        const a = m.m, b = n.m, o = j * 21;
+        M[o]    = a[0], M[o+1]  = a[1], M[o+2]  = a[2],  M[o+3]  = a[4], M[o+4]  = a[5], M[o+5]  = a[6];
+        M[o+6]  = a[8], M[o+7]  = a[9], M[o+8]  = a[10], M[o+9]  = a[12], M[o+10] = a[13], M[o+11] = a[14];
+        M[o+12] = b[0], M[o+13] = b[1], M[o+14] = b[2],  M[o+15] = b[4], M[o+16] = b[5], M[o+17] = b[6];
+        M[o+18] = b[8], M[o+19] = b[9], M[o+20] = b[10];
+    }
+    const {vertexJoints, vertexWeights, bindPoints, bindNormals} = skin, points = mesh.points, normals = mesh.normals;
+    // an indexed mesh's GPU vertex j is its point j, as upload lays it out
+    const layout = mesh.vertexLayout, count = points.length;
+    const floats = layout && mesh.indices && layout.pointCount === count ? new Float32Array(layout.data) : undefined;
+    let r = 0, x0 = Infinity, y0 = Infinity, z0 = Infinity, x1 = -Infinity, y1 = -Infinity, z1 = -Infinity;
+    for (let v = 0; v < count; ++v)
+    {
+        const v3 = v*3, v4 = v*4, px = bindPoints[v3], py = bindPoints[v3+1], pz = bindPoints[v3+2];
+        const qx = bindNormals[v3], qy = bindNormals[v3+1], qz = bindNormals[v3+2];
+        let x = 0, y = 0, z = 0, nx = 0, ny = 0, nz = 0;
+        for (let k = 0; k < 4; ++k)
+        {
+            const w = vertexWeights[v4+k];
+            if (!w) continue;
+            const o = vertexJoints[v4+k] * 21;
+            x += w * (M[o]*px + M[o+3]*py + M[o+6]*pz + M[o+9]);
+            y += w * (M[o+1]*px + M[o+4]*py + M[o+7]*pz + M[o+10]);
+            z += w * (M[o+2]*px + M[o+5]*py + M[o+8]*pz + M[o+11]);
+            nx += w * (M[o+12]*qx + M[o+15]*qy + M[o+18]*qz);
+            ny += w * (M[o+13]*qx + M[o+16]*qy + M[o+19]*qz);
+            nz += w * (M[o+14]*qx + M[o+17]*qy + M[o+20]*qz);
+        }
+        const p = points[v], normal = normals[v], l = (nx*nx + ny*ny + nz*nz) ** .5 || 1;
+        p.x = x, p.y = y, p.z = z;
+        normal.x = nx / l, normal.y = ny / l, normal.z = nz / l;
+        if (!floats) continue;
+        const at = v * RENDER3D_VERTEX_FLOATS;
+        floats[at]   = x,        floats[at+1] = y,        floats[at+2] = z;
+        floats[at+3] = normal.x, floats[at+4] = normal.y, floats[at+5] = normal.z;
+        r = max(r, x*x + y*y + z*z);
+        x0 = min(x0, x), y0 = min(y0, y), z0 = min(z0, z);
+        x1 = max(x1, x), y1 = max(y1, y), z1 = max(z1, z);
+    }
+    if (floats)
+    {
+        mesh.radius = r ** .5;
+        mesh.bounds = count ? {min: vec3(x0, y0, z0), max: vec3(x1, y1, z1)} : {min: vec3(), max: vec3()};
+        mesh.vertexDataPacked = true;
+    }
+    mesh.dirty = true;
 }
+const gltfSkinScratch = [new Matrix4, new Matrix4]; // a joint's matrix and its normal matrix, as it is worked out
 
 // a node's translation, rotation and scale as arrays to animate, copies so the file's stay as they rest
 function gltfNodeTRS(node)
@@ -710,7 +1015,7 @@ function gltfFetch(uri, baseUrl, files)
     const page = typeof location !== 'undefined' && location.href;
     const base = page ? new URL(baseUrl, page) : /^[a-z][a-z0-9+.-]*:/i.test(baseUrl) ? baseUrl : undefined;
     const url = base ? new URL(uri, base).href : baseUrl + uri;
-    return fetch(url).then(r=>
+    return loadFetch(url, 'glTF').then(r=>
     {
         if (!r.ok) throw new Error('glTF needs ' + uri + ', not found at ' + url);
         return r;
@@ -755,6 +1060,9 @@ function gltfAccessor(json, buffers, index)
     if (view)
     {
         const buffer = buffers[view.buffer], offset = (view.byteOffset || 0) + (a.byteOffset || 0);
+        // the format keeps values on their size, a typed array can not read them off it
+        if (offset % size || stride % size)
+            throw new Error('glTF accessor ' + index + ' is not aligned to its ' + size + ' byte values');
         if (stride === components * size)
             out.set(new Type(buffer, offset, a.count * components)); // packed, one view over all of it
         else
@@ -769,6 +1077,13 @@ function gltfAccessor(json, buffers, index)
         const indexView = json.bufferViews?.[indices.bufferView], valueView = json.bufferViews?.[values.bufferView];
         if (!IndexType || !indexView || !valueView)
             throw new Error('glTF sparse accessor is missing its indices or values');
+        // its indices and values in their buffers and on their sizes, before typed arrays are made over them
+        const indexAt = (indexView.byteOffset || 0) + (indices.byteOffset || 0);
+        const valueAt = (valueView.byteOffset || 0) + (values.byteOffset || 0);
+        if (indexAt % IndexType.BYTES_PER_ELEMENT || valueAt % size ||
+            !(indexAt + sparse.count * IndexType.BYTES_PER_ELEMENT <= (buffers[indexView.buffer]?.byteLength ?? 0)) ||
+            !(valueAt + sparse.count * components * size <= (buffers[valueView.buffer]?.byteLength ?? 0)))
+            throw new Error('glTF sparse accessor ' + index + ' is not aligned or reaches past its buffer');
         const at = new IndexType(buffers[indexView.buffer], (indexView.byteOffset || 0) + (indices.byteOffset || 0), sparse.count);
         const data = new Type(buffers[valueView.buffer], (valueView.byteOffset || 0) + (values.byteOffset || 0), sparse.count * components);
         for (let i = 0; i < sparse.count; ++i)
@@ -800,7 +1115,10 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
     };
     const points = read(attributes.POSITION, (d, k)=> vec3(d[k], d[k+1], d[k+2]));
     const normals = attributes.NORMAL !== undefined ? read(attributes.NORMAL, (d, k)=> vec3(d[k], d[k+1], d[k+2])) : undefined;
-    // the uv set the base color texture names, moved by its KHR_texture_transform once here, offset + rotation * scale
+    // the uv set the base color texture names, moved by its KHR_texture_transform once here, offset + rotation * scale,
+    // the rotation turning (u, v) to (cos u + sin v, cos v - sin u), counter-clockwise in glTF's uv space with v down,
+    // as the extension's text says and as Khronos's sample renderer and three.js turn it, which models are made to
+    // look right in; the GLSL sample in the extension's readme, read column major, turns the other way
     const material = json.materials?.[primitive.material] || {}, pbr = material.pbrMetallicRoughness || {};
     const textureRef = pbr.baseColorTexture, uvTransform = textureRef?.extensions?.KHR_texture_transform;
     const uvAccessor = attributes['TEXCOORD_' + (uvTransform?.texCoord ?? textureRef?.texCoord ?? 0)];
@@ -816,7 +1134,10 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
     else if (mode === 6) // a fan around the first entry
         indices = indices.flatMap((_, i, s)=> i < 2 ? [] : [s[0], s[i-1], s[i]]);
     const mesh = new Mesh().addTriangles(points, indices, normals, uvs, colors);
-    normals || mesh.computeNormals(false); // flat when the file gives none, as the format says
+    // flat when the file gives none, as the format says, which gives each corner a vertex of its own: which of the
+    // file's each one is, kept for a skin
+    const vertexSource = normals ? undefined : mesh.indices.slice();
+    normals || mesh.computeNormals(false);
     mesh.transform(matrix);
     const factor = pbr.baseColorFactor || [1, 1, 1, 1];
     mesh.doubleSided = !!material.doubleSided;
@@ -829,6 +1150,7 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
     const part = new GLTFPart(name, mesh, rgb(gltfSRGB(factor[0]), gltfSRGB(factor[1]), gltfSRGB(factor[2]), alpha),
         textureRef ? textures[textureRef.index] : undefined, blend || transmission > 0);
     part.pixelated = json.samplers?.[texture?.sampler]?.magFilter === 9728; // NEAREST
+    part.vertexSource = vertexSource;
     part.unlit = !!material.extensions?.KHR_materials_unlit;
 
     // the normal and emissive maps, read at the base color texture's uvs; the emissive texture is multiplied by the
@@ -837,6 +1159,7 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
     const normalRef = material.normalTexture, emissiveRef = material.emissiveTexture;
     part.normalMap = normalRef && textures[normalRef.index];
     part.normalScale = normalRef?.scale ?? 1;
+    part.roughness = pbr.roughnessFactor ?? 1; // a roughness map is not read
     const [er, eg, eb] = material.emissiveFactor || [0, 0, 0];
     if (er || eg || eb)
     {