@driftengine/assets 3.61.0

package/dist/kn5.js

@@ -0,0 +1,557 @@
+/**
+ * Assetto Corsa's `.kn5`. Tier 2: a real attempt, and explicitly not a guarantee.
+ *
+ * The format has no published specification. What is implemented here was verified against three
+ * files from a production car mod, each of which parses to *exact EOF* — a binary walk that
+ * consumes a 44 MB file to its last byte has no field misread anywhere in it, because a single
+ * wrong width desynchronises everything after it. That is the evidence this reader rests on, and
+ * `scripts/kn5-check.mjs` re-establishes it on demand.
+ *
+ * **It needs nothing from its host.** A `.kn5` embeds every texture it uses, so unlike a `.gltf`
+ * naming external buffers or an `.fbx` storing deflated arrays, there is no capability to inject
+ * and no sidecar to resolve. It is the one binary format here that reads from bytes alone.
+ *
+ * It reports what the file says and corrects none of it: the frame comes back as `declaredHand`
+ * and `orient.ts` is what would transform it, for the same reason every other reader here reports
+ * `declaredUp` instead of standing its own models up.
+ */
+import { DrftError } from '@driftengine/drft';
+/** `Kn5Material.blendMode` when the surface belongs in the blended pass. */
+export const KN5_ALPHA_BLEND = 1;
+/**
+ * A position in the file that refuses instead of running off the end.
+ *
+ * Every read goes through here so that a malformed file fails with an offset somebody can look
+ * at, which is the whole difference between a tier 2 refusal and a parser crash.
+ */
+export class Cursor {
+    view;
+    bytes;
+    at = 0;
+    constructor(buffer) {
+        this.view = new DataView(buffer);
+        this.bytes = new Uint8Array(buffer);
+    }
+    /** Refuses when `count` bytes are not there, naming where it ran out. */
+    need(count, what) {
+        if (count < 0 || this.at + count > this.bytes.length) {
+            throw new DrftError(`kn5: ${what} runs past the end of the file at offset ${this.at} ` +
+                `(wanted ${count} bytes, ${this.bytes.length - this.at} remain)`);
+        }
+    }
+    i32(what = 'an integer') {
+        this.need(4, what);
+        const value = this.view.getInt32(this.at, true);
+        this.at += 4;
+        return value;
+    }
+    u32(what = 'an integer') {
+        this.need(4, what);
+        const value = this.view.getUint32(this.at, true);
+        this.at += 4;
+        return value;
+    }
+    f32(what = 'a float') {
+        this.need(4, what);
+        const value = this.view.getFloat32(this.at, true);
+        this.at += 4;
+        return value;
+    }
+    u16(what = 'a short') {
+        this.need(2, what);
+        const value = this.view.getUint16(this.at, true);
+        this.at += 2;
+        return value;
+    }
+    u8(what = 'a byte') {
+        this.need(1, what);
+        return this.bytes[this.at++];
+    }
+    skip(count, what) {
+        this.need(count, what);
+        this.at += count;
+    }
+    take(count, what) {
+        this.need(count, what);
+        const slice = this.bytes.subarray(this.at, this.at + count);
+        this.at += count;
+        return slice;
+    }
+    /** i32 length, then that many UTF-8 bytes. */
+    str(what = 'a name') {
+        const length = this.i32(`the length of ${what}`);
+        return new TextDecoder().decode(this.take(length, what));
+    }
+}
+/** Bytes each material property carries after its value, and does not explain. */
+const PROPERTY_TRAILER = 36;
+/**
+ * The magic, the version, the texture block and the material palette.
+ *
+ * Split from the node walk because it is the half that is pure data: no recursion, no transforms,
+ * and nothing that needs a `MeshData` to exist.
+ */
+export function readKn5Header(buffer) {
+    const cursor = new Cursor(buffer);
+    cursor.need(10, 'the kn5 header');
+    const magic = new TextDecoder().decode(cursor.take(6, 'the magic'));
+    if (magic !== 'sc6969') {
+        throw new DrftError(`kn5: this is not a kn5 file — it begins "${magic}" and not "sc6969"`);
+    }
+    const version = cursor.i32('the version');
+    /*
+     * Version 6 carries one more word here than version 5 did. It reads 0 in every file measured,
+     * and it is skipped by name instead of interpreted: a field whose meaning is unknown is better
+     * passed over deliberately than guessed at.
+     */
+    if (version > 5)
+        cursor.i32('the version 6 extra word');
+    const textures = [];
+    const textureCount = cursor.i32('the texture count');
+    for (let i = 0; i < textureCount; i++) {
+        cursor.i32(`the type of texture ${i}`);
+        const name = cursor.str(`the name of texture ${i}`);
+        const size = cursor.i32(`the size of texture "${name}"`);
+        textures.push({ name, bytes: cursor.take(size, `the bytes of texture "${name}"`) });
+    }
+    const materials = [];
+    const materialCount = cursor.i32('the material count');
+    for (let i = 0; i < materialCount; i++) {
+        const name = cursor.str(`the name of material ${i}`);
+        const shader = cursor.str(`the shader of material "${name}"`);
+        const blendMode = cursor.u8(`the blend mode of material "${name}"`);
+        const alphaTested = cursor.u8(`the alpha test flag of material "${name}"`) !== 0;
+        if (version > 4)
+            cursor.i32(`the depth mode of material "${name}"`);
+        const props = new Map();
+        const propCount = cursor.i32(`the property count of material "${name}"`);
+        for (let p = 0; p < propCount; p++) {
+            const property = cursor.str(`a property name of material "${name}"`);
+            props.set(property, cursor.f32(`the value of "${property}"`));
+            cursor.skip(PROPERTY_TRAILER, `the trailer of property "${property}"`);
+        }
+        const textureSlots = new Map();
+        const slotCount = cursor.i32(`the sampler count of material "${name}"`);
+        for (let s = 0; s < slotCount; s++) {
+            const sampler = cursor.str(`a sampler name of material "${name}"`);
+            cursor.i32(`the slot of sampler "${sampler}"`);
+            textureSlots.set(sampler, cursor.str(`the texture bound to "${sampler}"`));
+        }
+        materials.push({ name, shader, blendMode, alphaTested, props, textures: textureSlots });
+    }
+    return { version, textures, materials, cursor };
+}
+/** Node types the format defines. Anything else is a refusal, not a skip. */
+const NODE_DUMMY = 1;
+const NODE_MESH = 2;
+const NODE_ANIMATED = 3;
+/** pos[3] normal[3] uv[2] tangent[3], all f32. */
+const MESH_VERTEX_BYTES = 44;
+/** The same, plus weights[4] and bone indices[4]. */
+const ANIMATED_VERTEX_BYTES = 76;
+/** layer:u32 lodIn:f32 lodOut:f32 sphere[3]:f32 radius:f32 renderable:u8. */
+const MESH_TRAILER = 29;
+/** An animated mesh states a layer and a lod window and stops there. */
+const ANIMATED_TRAILER = 12;
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+/** Row-vector multiply: `out = a * b`, matching how the format composes a hierarchy. */
+function multiply(a, b) {
+    const out = new Float32Array(16);
+    for (let row = 0; row < 4; row++) {
+        for (let column = 0; column < 4; column++) {
+            let sum = 0;
+            for (let k = 0; k < 4; k++)
+                sum += a[row * 4 + k] * b[k * 4 + column];
+            out[row * 4 + column] = sum;
+        }
+    }
+    return out;
+}
+/** A point through a row-vector matrix, translation included. */
+function transformPoint(m, x, y, z) {
+    return [
+        x * m[0] + y * m[4] + z * m[8] + m[12],
+        x * m[1] + y * m[5] + z * m[9] + m[13],
+        x * m[2] + y * m[6] + z * m[10] + m[14],
+    ];
+}
+/** A direction through the same matrix: no translation, so normals and tangents share it. */
+function transformDirection(m, x, y, z) {
+    return [
+        x * m[0] + y * m[4] + z * m[8],
+        x * m[1] + y * m[5] + z * m[9],
+        x * m[2] + y * m[6] + z * m[10],
+    ];
+}
+/**
+ * Walk the node tree depth first, which is the order the file stores it in.
+ *
+ * **Every node is kept, including the `AC_`-prefixed ones.** The community converter skips them,
+ * correctly for its purpose, since they carry no geometry an OBJ can hold. They are placement
+ * anchors and convention markers, and this reader exists to preserve exactly that.
+ */
+export function readKn5Nodes(header) {
+    const { cursor } = header;
+    const nodes = [];
+    const meshes = [];
+    const worlds = [];
+    const readNode = (parent) => {
+        const startedAt = cursor.at;
+        const type = cursor.i32('a node type');
+        const name = cursor.str('a node name');
+        const childCount = cursor.i32(`the child count of "${name}"`);
+        cursor.u8(`the active flag of "${name}"`);
+        let matrix = IDENTITY;
+        let mesh = -1;
+        let flags = { castShadows: false, isVisible: true, isTransparent: false };
+        if (type === NODE_DUMMY) {
+            const local = new Float32Array(16);
+            for (let i = 0; i < 16; i++)
+                local[i] = cursor.f32(`the transform of "${name}"`);
+            matrix = local;
+        }
+        else if (type === NODE_MESH || type === NODE_ANIMATED) {
+            flags = {
+                castShadows: cursor.u8(`the shadow flag of "${name}"`) !== 0,
+                isVisible: cursor.u8(`the visibility flag of "${name}"`) !== 0,
+                isTransparent: cursor.u8(`the transparency flag of "${name}"`) !== 0,
+            };
+            if (type === NODE_ANIMATED) {
+                /*
+                 * Bones are read past by name and count, not interpreted. No file measured contains one,
+                 * so a skin built from these would be a claim nothing here can support — the geometry is
+                 * imported and the rig is left for a file that can prove it.
+                 */
+                const boneCount = cursor.i32(`the bone count of "${name}"`);
+                for (let b = 0; b < boneCount; b++) {
+                    const bone = cursor.str(`a bone name of "${name}"`);
+                    cursor.skip(64, `the bind matrix of bone "${bone}"`);
+                }
+            }
+            mesh = meshes.length;
+        }
+        else {
+            throw new DrftError(`kn5: node type ${type} is not one this reader understands, at "${name}", ` +
+                `offset ${startedAt}. Known types are 1 (dummy), 2 (mesh) and 3 (animated mesh).`);
+        }
+        const index = nodes.length;
+        const world = parent < 0 ? matrix : multiply(matrix, worlds[parent]);
+        worlds.push(world);
+        nodes.push({ type, name, parent, matrix, mesh, ...flags, lodIn: 0, lodOut: 0 });
+        if (type === NODE_MESH || type === NODE_ANIMATED) {
+            const stride = type === NODE_MESH ? MESH_VERTEX_BYTES : ANIMATED_VERTEX_BYTES;
+            const vertexCount = cursor.i32(`the vertex count of "${name}"`);
+            cursor.need(vertexCount * stride, `the vertices of "${name}"`);
+            const positions = new Float32Array(vertexCount * 3);
+            const normals = new Float32Array(vertexCount * 3);
+            const uvs = new Float32Array(vertexCount * 2);
+            const tangents = new Float32Array(vertexCount * 4);
+            for (let v = 0; v < vertexCount; v++) {
+                const [px, py, pz] = transformPoint(world, cursor.f32(), cursor.f32(), cursor.f32());
+                positions[v * 3] = px;
+                positions[v * 3 + 1] = py;
+                positions[v * 3 + 2] = pz;
+                const [nx, ny, nz] = transformDirection(world, cursor.f32(), cursor.f32(), cursor.f32());
+                normals[v * 3] = nx;
+                normals[v * 3 + 1] = ny;
+                normals[v * 3 + 2] = nz;
+                uvs[v * 2] = cursor.f32();
+                /* kn5 stores v with the opposite origin from every other format here. */
+                uvs[v * 2 + 1] = 1 - cursor.f32();
+                const [tx, ty, tz] = transformDirection(world, cursor.f32(), cursor.f32(), cursor.f32());
+                tangents[v * 4] = tx;
+                tangents[v * 4 + 1] = ty;
+                tangents[v * 4 + 2] = tz;
+                /*
+                 * The file states no bitangent sign. +1 is the convention every exporter in this pipeline
+                 * writes, and `orient.ts` flips it where a mirror makes it wrong.
+                 */
+                tangents[v * 4 + 3] = 1;
+                if (type === NODE_ANIMATED)
+                    cursor.skip(32, `the skin weights of "${name}"`);
+            }
+            const indexCount = cursor.i32(`the index count of "${name}"`);
+            const indices = new Uint32Array(indexCount);
+            for (let i = 0; i < indexCount; i++)
+                indices[i] = cursor.u16(`an index of "${name}"`);
+            const material = cursor.i32(`the material of "${name}"`);
+            let lodIn = 0;
+            let lodOut = 0;
+            if (type === NODE_MESH) {
+                cursor.need(MESH_TRAILER, `the trailer of "${name}"`);
+                cursor.u32();
+                lodIn = cursor.f32();
+                lodOut = cursor.f32();
+                cursor.skip(16, `the bounding sphere of "${name}"`);
+                cursor.u8();
+            }
+            else {
+                cursor.need(ANIMATED_TRAILER, `the trailer of "${name}"`);
+                cursor.u32();
+                lodIn = cursor.f32();
+                lodOut = cursor.f32();
+            }
+            nodes[index] = { ...nodes[index], lodIn, lodOut };
+            meshes.push({ positions, normals, uvs, tangents, indices, material, node: index });
+        }
+        for (let c = 0; c < childCount; c++)
+            readNode(index);
+    };
+    readNode(-1);
+    return { nodes, meshes };
+}
+/**
+ * Shaders this reader maps deliberately. Anything else warns once, by name.
+ *
+ * **A list of names, and it decides nothing.** It used to carry a second list beside it — the
+ * shaders whose surfaces blend — and that list was wrong about a shipped car: all four of its
+ * tyres are `ksTyres`, which the list called transparent, while the file states `alphaBlendMode`
+ * 0 on the material and no transparency on the node. The file is right, it says so in two places,
+ * and a name is a guess where a field is a fact. So blending is read from the material now and
+ * this stays only for the warning, which is the thing a name genuinely can answer: a shader
+ * nobody here has seen is still geometry somebody wants.
+ */
+const KNOWN_SHADERS = new Set([
+    'ksPerPixelAlpha',
+    'ksWindscreen',
+    'ksTyres',
+    'ksTree',
+    'ksGrass',
+    'ksFlags',
+    'ksSkidMark',
+    'ksPerPixel',
+    'ksPerPixelNM',
+    'ksPerPixelNM_UVMult',
+    'ksPerPixelReflection',
+    'ksPerPixelMultiMap',
+    'ksPerPixelMultiMap_NMDetail',
+    'ksPerPixelSimpleRefl',
+    'ksMultilayer',
+    'GL',
+]);
+/**
+ * The opacity a blended surface takes, since `.kn5` states none of its own.
+ *
+ * `MATL` says a surface blends by carrying an opacity below 1, and that is the only channel the
+ * container has for the fact. A `.kn5` material states *whether* it blends and never by how much:
+ * the alpha is per texel, in the diffuse map, and the shader multiplies `uOpacity * coverage` —
+ * so a value just under 1 puts the surface in the blended pass and leaves the picture to the
+ * texture, which is what the file means. It is deliberately not 0.999 arrived at from anything in
+ * the file: the number is a flag, and this constant is where that is admitted.
+ */
+const BLENDED_OPACITY = 0.999;
+/** A Blinn-Phong exponent as a roughness, which is the standard inverse. */
+function roughnessFromExponent(exponent) {
+    if (!(exponent > 0))
+        return 1;
+    return Math.min(1, Math.max(0, Math.sqrt(2 / (exponent + 2))));
+}
+/**
+ * Read a `.kn5` into meshes, materials and the hierarchy that placed them.
+ *
+ * Materials are duplicated per mesh because `MATL` is parallel to `MESH` by ordinal while `.kn5`
+ * addresses a shared palette — 70 entries against 172 meshes in the car this was built against.
+ * The palette entry keeps its name, so nothing is lost by the duplication.
+ */
+export function kn5ToMeshes(buffer) {
+    const head = readKn5Header(buffer);
+    const { nodes, meshes: sources } = readKn5Nodes(head);
+    const warnings = [];
+    const textures = head.textures.map((texture) => ({
+        name: texture.name,
+        bytes: texture.bytes,
+    }));
+    const textureIndex = new Map(head.textures.map((texture, at) => [texture.name, at]));
+    /** A sampler's texture as an ordinal, or -1, warning once for a name the file did not carry. */
+    const bind = (material, sampler) => {
+        const named = material.textures.get(sampler);
+        if (named === undefined)
+            return -1;
+        const at = textureIndex.get(named);
+        if (at === undefined) {
+            warnings.push(`kn5: material "${material.name}" binds ${sampler} to "${named}", which the file does ` +
+                'not carry. That surface loads without the map.');
+            return -1;
+        }
+        return at;
+    };
+    const warned = new Set();
+    const meshes = [];
+    const materials = [];
+    for (const source of sources) {
+        const node = nodes[source.node];
+        const material = head.materials[source.material];
+        if (material === undefined) {
+            throw new DrftError(`kn5: "${node.name}" names material ${source.material}, and the file carries ` +
+                `${head.materials.length}.`);
+        }
+        if (!KNOWN_SHADERS.has(material.shader) && !warned.has(material.shader)) {
+            warned.add(material.shader);
+            warnings.push(`kn5: shader "${material.shader}" is not one this reader maps, so surfaces using it take ` +
+                'a default. Their geometry and textures are unaffected.');
+        }
+        if (material.textures.has('txDetail') && !warned.has('txDetail')) {
+            warned.add('txDetail');
+            warnings.push('kn5: this model uses detail maps, a second UV layer the container carries one of. ' +
+                'Those surfaces lose their close-range texture.');
+        }
+        /*
+         * Said once, because a texture that is read past in silence is the failure this reader keeps
+         * making. `txMaps` is carried by nearly every AC material and none of it reaches the container.
+         */
+        if (material.textures.has('txMaps') && !warned.has('txMaps')) {
+            warned.add('txMaps');
+            warnings.push("kn5: this model's materials carry `txMaps`, which is not read: its channels are specular " +
+                'intensity, reflection sharpness and reflection intensity, and the container has no ' +
+                'packing for those. Each surface keeps the roughness its own `ksSpecularEXP` states.');
+        }
+        const property = (name, fallback) => material.props.get(name) ?? fallback;
+        /*
+         * Both statements are the file's own, so both are honoured: the material's blend mode is the
+         * surface's, the node's flag is this instance's, and they agree on 171 of 172 meshes in the
+         * car measured. Neither of them is `ksAlphaRef`, which is what this used to read.
+         */
+        const blended = material.blendMode === KN5_ALPHA_BLEND || node.isTransparent;
+        const diffuse = property('ksDiffuse', 0.6);
+        meshes.push({
+            positions: source.positions,
+            normals: source.normals,
+            uvs: source.uvs,
+            tangents: source.tangents,
+            indices: source.indices,
+            colors: new Float32Array(source.positions.length).fill(1),
+            emissive: new Float32Array(source.positions.length / 3).fill(property('ksEmissive', 0)),
+        });
+        materials.push({
+            name: material.name,
+            color: [diffuse, diffuse, diffuse],
+            specular: property('ksSpecular', 0.9),
+            roughness: roughnessFromExponent(property('ksSpecularEXP', 1)),
+            emissive: property('ksEmissive', 0),
+            emissiveColor: [-1, -1, -1],
+            opacity: blended ? BLENDED_OPACITY : 1,
+            /*
+             * **`ksAlphaRef` is an alpha test and was being read as an opacity**, so a transparent
+             * material stating the 0 that means "test nothing" came out invisible: nine meshes of a
+             * hundred and two on the car this was reported from, including all four tyres and all four
+             * rims. It is a threshold below which a fragment is discarded, which is what `cutout` is,
+             * and it only applies where the material says it is tested.
+             *
+             * **No file measured here sets that flag**, so this path is carried on the format's word
+             * rather than on evidence — stated plainly for the same reason the bone block is read past
+             * rather than interpreted. What the change fixes is not this line but the one above it.
+             */
+            cutout: material.alphaTested ? property('ksAlphaRef', 0) : 0,
+            albedo: bind(material, 'txDiffuse'),
+            normalMap: bind(material, 'txNormal'),
+            /*
+             * **`txMaps` is deliberately not bound here, and that is the correction of a real defect.**
+             *
+             * It was bound as `ormMap` for as long as this reader has existed, and the cost was measured
+             * from outside: every AC car's paint rendered at roughness 1.0 — the widest probe blur there
+             * is — while the file said 0.180. glTF's ORM is occlusion in R, roughness in G and metallic
+             * in B. Two independent references give AC's `txMaps` as specular intensity in R, reflection
+             * and specular *sharpness* in G, and reflection intensity in B. Sharpness is the inverse of
+             * roughness, so a G pinned at 255 — which is what three bundles' paint maps hold — is a file
+             * asking for the sharpest reflection available and was being read as the bluntest.
+             *
+             * **The half of that which needed no reference** is the line above: `roughness` is derived
+             * from `ksSpecularEXP` and is right, and the shader *replaces* it with the map's G rather
+             * than scaling it. So this reader computed the correct number and then discarded it for a
+             * channel whose meaning `occlusionStrength: 0` already said was not established — about R
+             * alone, while G and B were consumed as if the packing were known.
+             *
+             * Not binding it is not a claim about what `txMaps` means. It is declining to assert a
+             * packing that is not there, which is `recognise.ts`'s principle and this file's own.
+             *
+             * **What would reverse it:** a shader reference for `ksPerPixelMultiMap` settling the curve
+             * between sharpness and roughness, at which point the map's per-texel detail is worth
+             * carrying properly. `docs/IMPROVEMENTS.md` holds the measurements and both routes.
+             */
+            ormMap: -1,
+            emissiveMap: -1,
+            roughnessScale: 1,
+            metallicScale: 1,
+            /* Nothing is bound above, so there is no occlusion to scale either. */
+            occlusionStrength: 0,
+            reflectivity: property('fresnelMaxLevel', property('fresnelC', 0)),
+        });
+    }
+    /*
+     * **Right-handed, and this was measured rather than assumed.** The format is Assetto Corsa's and
+     * the simulator is a DirectX title, which is why this reader first declared the frame left-handed
+     * and mirrored every model it read. A consumer importing a second car found the mirror by eye —
+     * a badge reading backwards — and nothing numeric had caught it, because a mirrored car has the
+     * same bounds, the same triangle count and the same consistent winding as an unmirrored one.
+     *
+     * What settles it: the rear badge of a shipped car, rasterised out of the file with no conversion
+     * at all and viewed from behind, spells the model's name forwards, and spells it backwards
+     * through a negate-X. The rest of the file agrees. Up is `+y`; the front bumper, the headlights and the indicators
+     * are at `+z` and the tail lamps at `−z`; and the steering wheel, the driver's seat, the door
+     * the author named for the left side, the left mirror, and the driver's eye position that the
+     * simulator itself reads out of the car's own configuration are all at `+x`. In a right-handed
+     * frame with that up and that forward, `+x` is the car's left — so the file, read exactly as
+     * stored, is a left-hand-drive car.
+     */
+    return { meshes, materials, textures, nodes, warnings, declaredUp: '+y', declaredHand: 'right' };
+}
+/**
+ * Decompose each node's row-vector 4x4 into the translation, rotation and scale `DrftNode` holds.
+ *
+ * The container stores a hierarchy as TRS and not as a matrix, which is what lets a consumer
+ * animate one channel without disturbing the other two — a wheel spins about its own axis while
+ * its suspension travel writes only the translation.
+ */
+export function toDrftNodes(nodes) {
+    return nodes.map((node) => {
+        const m = node.matrix;
+        const axis = (row) => [
+            m[row * 4],
+            m[row * 4 + 1],
+            m[row * 4 + 2],
+        ];
+        const length = (v) => Math.hypot(v[0], v[1], v[2]);
+        const scale = [length(axis(0)), length(axis(1)), length(axis(2))];
+        /*
+         * The rotation is read out of the scale-normalised basis. A zero-length axis leaves that row
+         * as identity: a degenerate basis has no rotation to recover, and inventing one would be
+         * worse than the identity it collapses to.
+         */
+        const basis = [0, 1, 2].map((row) => {
+            const v = axis(row);
+            const l = scale[row];
+            if (l === 0)
+                return [row === 0 ? 1 : 0, row === 1 ? 1 : 0, row === 2 ? 1 : 0];
+            return [v[0] / l, v[1] / l, v[2] / l];
+        });
+        const [x0, x1, x2] = basis[0];
+        const [y0, y1, y2] = basis[1];
+        const [z0, z1, z2] = basis[2];
+        const trace = x0 + y1 + z2;
+        let rotation;
+        if (trace > 0) {
+            const s = Math.sqrt(trace + 1) * 2;
+            rotation = [(y2 - z1) / s, (z0 - x2) / s, (x1 - y0) / s, s / 4];
+        }
+        else if (x0 > y1 && x0 > z2) {
+            const s = Math.sqrt(1 + x0 - y1 - z2) * 2;
+            rotation = [s / 4, (y0 + x1) / s, (z0 + x2) / s, (y2 - z1) / s];
+        }
+        else if (y1 > z2) {
+            const s = Math.sqrt(1 + y1 - x0 - z2) * 2;
+            rotation = [(y0 + x1) / s, s / 4, (z1 + y2) / s, (z0 - x2) / s];
+        }
+        else {
+            const s = Math.sqrt(1 + z2 - x0 - y1) * 2;
+            rotation = [(z0 + x2) / s, (z1 + y2) / s, s / 4, (x1 - y0) / s];
+        }
+        return {
+            parent: node.parent,
+            translation: [m[12], m[13], m[14]],
+            rotation,
+            scale,
+            mesh: node.mesh,
+            name: node.name,
+        };
+    });
+}

package/dist/loadProgress.d.ts

@@ -0,0 +1,118 @@
+import type { MeshHandle } from '@driftengine/core';
+/**
+ * The vocabulary of a load in flight: which phase it is in, how far it has got, and what a
+ * finished part is.
+ *
+ * Separate from the loader because these three are what a consumer's progress bar is written
+ * against, and reading them should not mean paging through a thousand-line class.
+ */
+/**
+ * Where a load has got to, in the order a file delivers it.
+ *
+ * These are the chunk kinds rather than invented steps, which is the argument docs/FORMAT.md
+ * §4.6 makes for the whole design: the format's own layout is the sequence a viewer sees.
+ */
+export type DrftLoadPhase = 'idle' | 'connecting' | 'manifest'
+/** A coarse whole model has landed: the asset is on screen, at the resolution it arrived at. */
+ | 'outline' | 'materials' | 'geometry' | 'textures' | 'ready' | 'absent' | 'failed';
+/**
+ * How far a load has got, and every field here now answers about the *picture* rather than about
+ * the work.
+ *
+ * **This was not true until it was reported.** `imagesDone` counted an image when its bytes
+ * arrived, and the decode that follows is deliberately not awaited so a slow one never holds up
+ * the stream. So there was a window in which `fraction` was 1, every part was uploaded and
+ * `imagesDone` equalled `imagesTotal`, while the surfaces wearing those images still drew
+ * untextured. Measured by a consumer across a scenario switch: **one and three quarter seconds.**
+ *
+ * It cost more than a harness photographing the wrong frame, which is how it was found. The same
+ * consumer drives a loading bar off these counters, so the bar reached 100% and the model then
+ * visibly changed underneath somebody who had been told it was finished. Their argument for the
+ * trade is the one that decided it: a bar that sits still for a moment is honest about being
+ * busy, and a bar that finishes early and then lets the thing it loaded change is not, and nobody
+ * can tell the second one is happening.
+ *
+ * So an image counts when it is **on the GPU**. `fraction` reaches 1 when the picture is right,
+ * and the cost is that it pauses near the end while the last decodes finish. On a weighted bar
+ * that pause is not at 99%: parts and images carry separate shares, so it climbs to roughly two
+ * thirds on the uploads and waits there, and a bar that stops at two thirds reads as working
+ * where one that stops at 99% reads as stuck.
+ *
+ * `phase === 'ready'` remains the signal to *act* on, and is what anything judging the finished
+ * picture should gate on.
+ */
+export interface DrftLoadProgress {
+    readonly phase: DrftLoadPhase;
+    /** 0 to 1, weighted by what the manifest says the file is actually made of. */
+    readonly fraction: number;
+    readonly partsDone: number;
+    readonly partsTotal: number;
+    /**
+     * Images that are **on the GPU**, not images whose bytes have arrived.
+     *
+     * A decode that fails counts too, because the alternative to counting it is a bar that can
+     * never finish as the price of one image that was never going to draw.
+     */
+    readonly imagesDone: number;
+    readonly imagesTotal: number;
+    readonly totalBytes: number;
+    /** Present only when the phase is `failed` or `absent`. */
+    readonly message: string;
+}
+/** One drawable piece of a loaded model. */
+export interface DrftPart {
+    readonly mesh: MeshHandle;
+    /** Which of the asset's images this surface wears, or -1 for none. */
+    readonly albedo: number;
+    /** Which image carries its occlusion, roughness and metallic, or -1 for none. */
+    readonly orm: number;
+    /**
+     * Which image carries its surface-space normals, or -1 for none.
+     *
+     * **Carried by the container since `MATL` reached stride 72 and dropped here until 2026-08-23**,
+     * which is the whole of why a bought model looked smoother than the one its maker shipped: the
+     * baker wrote the index, the reader read it, the renderer has taken a normal map through
+     * `SurfaceMaterial.normal` since normal maps landed, and this was the one step that did not pass
+     * it on. Panel seams, stitching, tread and every other detail an exporter bakes into a normal
+     * map rather than into geometry was arriving and going nowhere.
+     */
+    readonly normal: number;
+    /**
+     * Which image carries its emission, or -1 for none.
+     *
+     * **The fourth and last index `MATL` carries, passed on from 2026-08-24.** It was written by the
+     * baker, read by the reader and dropped here for the same stretch the normal map was — but for a
+     * stated reason rather than by oversight: no renderer took an emissive map until now, so there
+     * was nowhere to pass it. `SurfaceMaterial.emissive` is that somewhere.
+     */
+    readonly emissive: number;
+    /**
+     * glTF's three factors, in the shape `SurfaceMaterial` takes them.
+     *
+     * Carried on the part rather than looked up from the material, because a caller building a
+     * `setMaterial` call has the part and not the index that produced it.
+     */
+    readonly roughnessScale: number;
+    readonly metallicScale: number;
+    readonly occlusionStrength: number;
+    readonly opacity: number;
+    readonly reflectivity: number;
+    /**
+     * Alpha below which this surface's fragments are discarded, 0 for one that discards nothing.
+     *
+     * The pair to `opacity` and not a weaker version of it: a cutout decides which texels of the
+     * surface exist, an opacity decides how much light passes through the ones that do. It is what
+     * `SurfaceMaterial.cutout` takes, and until `MATL` grew the field there was no way for a source
+     * format to say it — a masked grille arrived as a solid rectangle, and a vehicle format's alpha
+     * *test* was being spent on the opacity, which drew nine surfaces of a hundred and two as
+     * nothing at all.
+     */
+    readonly cutout: number;
+    /**
+     * 0 to 1 as this part arrives, for a caller that would rather it faded in than appeared.
+     *
+     * Advanced by `update`, so it follows the frame's own clock and holds when the frame holds.
+     * A caller that wants parts to pop in can ignore it; one that wants a build fades on it.
+     */
+    reveal: number;
+}

package/dist/loadProgress.js

@@ -0,0 +1 @@
+export {};