@driftengine/assets 4.6.1 → 4.7.1

package/README.md

@@ -1,6 +1,6 @@
 # @driftengine/assets
 
-Model readers for seven formats, and the streaming loader that uploads them.
+Model readers for nine formats — `.blend` among them, read from the file's own DNA — and the streaming loader that uploads them.
 
 **Cost: 22.5 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.

package/dist/blend.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reading a `.blend` directly: Blender's own file, with no Blender installed.
+ *
+ * The route is container → catalogue → scene → glTF document → the glTF reader, each step in its
+ * own module, and this one only chains them and decides what a refusal looks like. See
+ * `blendGltf.ts` for why the document in the middle is glTF.
+ *
+ * **A refusal is an error with its reasons attached**, `BlendNeedsBlender`, because the caller
+ * that can act on it — the baker, with Blender on the machine — needs the list rather than a
+ * sentence to parse: it hands the file to Blender and says why. A browser has no Blender, and shows
+ * the message.
+ */
+import { DrftError } from '@driftengine/drft';
+import { BlendData } from './blendData.ts';
+import type { BlendGltf } from './blendGltf.ts';
+import type { BlendDecompress } from './blendPacked.ts';
+/** Thrown when a `.blend` holds something only Blender can evaluate, with each thing named. */
+export declare class BlendNeedsBlender extends DrftError {
+    readonly reasons: readonly string[];
+    constructor(reasons: readonly string[]);
+}
+/** Open a `.blend`'s bytes, decompressing them first where the file was saved compressed. */
+export declare function openBlend(bytes: Uint8Array, decompress?: BlendDecompress): Promise<BlendData>;
+/** A `.blend` as a glTF document, refusing it whole when any part of it needs evaluating. */
+export declare function readBlend(bytes: Uint8Array, decompress?: BlendDecompress): Promise<BlendGltf>;

package/dist/blend.js

@@ -0,0 +1,43 @@
+/**
+ * Reading a `.blend` directly: Blender's own file, with no Blender installed.
+ *
+ * The route is container → catalogue → scene → glTF document → the glTF reader, each step in its
+ * own module, and this one only chains them and decides what a refusal looks like. See
+ * `blendGltf.ts` for why the document in the middle is glTF.
+ *
+ * **A refusal is an error with its reasons attached**, `BlendNeedsBlender`, because the caller
+ * that can act on it — the baker, with Blender on the machine — needs the list rather than a
+ * sentence to parse: it hands the file to Blender and says why. A browser has no Blender, and shows
+ * the message.
+ */
+import { DrftError } from '@driftengine/drft';
+import { BlendData } from './blendData.js';
+import { blendToGltf } from './blendGltf.js';
+import { unpackBlend } from './blendPacked.js';
+/** Thrown when a `.blend` holds something only Blender can evaluate, with each thing named. */
+export class BlendNeedsBlender extends DrftError {
+    reasons;
+    constructor(reasons) {
+        const shown = reasons
+            .slice(0, 6)
+            .map((reason) => `  ${reason}`)
+            .join('\n');
+        const more = reasons.length > 6 ? `\n  …and ${reasons.length - 6} more` : '';
+        super(`blend: this file needs Blender to evaluate it, and the direct reader draws nothing rather than ` +
+            `the wrong shape:\n${shown}${more}\nBake it with \`npm run bake\` on a machine with Blender ` +
+            'installed, which hands it to Blender, or apply these in Blender and save again.');
+        this.name = 'BlendNeedsBlender';
+        this.reasons = reasons;
+    }
+}
+/** Open a `.blend`'s bytes, decompressing them first where the file was saved compressed. */
+export async function openBlend(bytes, decompress) {
+    return new BlendData(await unpackBlend(bytes, decompress));
+}
+/** A `.blend` as a glTF document, refusing it whole when any part of it needs evaluating. */
+export async function readBlend(bytes, decompress) {
+    const result = blendToGltf(await openBlend(bytes, decompress));
+    if (result.refusals.length > 0)
+        throw new BlendNeedsBlender(result.refusals);
+    return result;
+}

package/dist/blendAnimation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What an object's animation says at a frame: its F-curves read from its action or its NLA strips,
+ * and evaluated as Blender evaluates them.
+ *
+ * **Two ways an action stores its curves.** Before 4.4 an action was a list of F-curves; from 4.4 it
+ * is layered — layers of strips, each strip's keyframes in channel bags, one bag a slot — so one
+ * action can animate several objects, each reading the bag its slot names. Both are read here into
+ * the same `Curve`, and nothing above this module knows which a file used.
+ *
+ * **What is evaluated, Blender's way**: constant, linear and Bézier keys, the Bézier handles
+ * corrected so a segment cannot loop back in time (as Blender corrects them before it draws one),
+ * constant or linear extrapolation past the ends, and the Cycles modifier, which is how a looping
+ * action is made. **NLA strips** map scene time into each strip's action time by its start, scale
+ * and repeats, and hold their ends as their extend mode says.
+ *
+ * What it gives up, and says through `unread`: the easing modes past Bézier (back, bounce, elastic
+ * and the rest, drawn as Bézier), every F-curve modifier but Cycles, drivers, blending between NLA
+ * strips other than replacing, and the influence of a strip below one. A file using them animates
+ * here as the nearest of what is read, which a bake should check against Blender's own export.
+ */
+import type { BlendStruct } from './blendData.ts';
+/** One keyframed property of one animated datablock. */
+export interface Curve {
+    /** Blender's data path: `location`, `rotation_euler`, `pose.bones["Spine"].rotation_quaternion`. */
+    readonly path: string;
+    readonly index: number;
+    evaluate(frame: number): number;
+    /** The first and last keyed frames. */
+    readonly range: readonly [number, number];
+}
+/** One F-curve, ready to evaluate. */
+export declare function readCurve(curve: BlendStruct, unread: Set<string>): Curve | null;
+/** The F-curves an action holds for `slot`: its channel bag in a layered action, every curve otherwise. */
+export declare function actionCurves(action: BlendStruct, slot: number, unread: Set<string>): Curve[];
+/** Everything that animates a datablock: its active action, then its NLA tracks bottom to top. */
+export declare class Animation {
+    private readonly sources;
+    readonly unread: Set<string>;
+    constructor(id: BlendStruct);
+    get animated(): boolean;
+    /** The scene frames anything here animates over. */
+    get range(): [number, number];
+    /** Every animated value at `frame`, by `path[index]`; the last source to speak wins. */
+    values(frame: number, out: Map<string, number>): Map<string, number>;
+}

package/dist/blendAnimation.js

@@ -0,0 +1,294 @@
+/**
+ * What an object's animation says at a frame: its F-curves read from its action or its NLA strips,
+ * and evaluated as Blender evaluates them.
+ *
+ * **Two ways an action stores its curves.** Before 4.4 an action was a list of F-curves; from 4.4 it
+ * is layered — layers of strips, each strip's keyframes in channel bags, one bag a slot — so one
+ * action can animate several objects, each reading the bag its slot names. Both are read here into
+ * the same `Curve`, and nothing above this module knows which a file used.
+ *
+ * **What is evaluated, Blender's way**: constant, linear and Bézier keys, the Bézier handles
+ * corrected so a segment cannot loop back in time (as Blender corrects them before it draws one),
+ * constant or linear extrapolation past the ends, and the Cycles modifier, which is how a looping
+ * action is made. **NLA strips** map scene time into each strip's action time by its start, scale
+ * and repeats, and hold their ends as their extend mode says.
+ *
+ * What it gives up, and says through `unread`: the easing modes past Bézier (back, bounce, elastic
+ * and the rest, drawn as Bézier), every F-curve modifier but Cycles, drivers, blending between NLA
+ * strips other than replacing, and the influence of a strip below one. A file using them animates
+ * here as the nearest of what is read, which a bake should check against Blender's own export.
+ */
+const BEZT_IPO_CONST = 0;
+const BEZT_IPO_LIN = 1;
+const FCURVE_EXTRAPOLATE_LINEAR = 1;
+/* F-curve modifier types: generator 1, function 2, envelope 3, cycles 4, noise 5. */
+const FMODIFIER_TYPE_CYCLES = 4;
+const FCM_EXTRAPOLATE_NONE = 0;
+const FCM_EXTRAPOLATE_CYCLIC_OFFSET = 2;
+const FCM_EXTRAPOLATE_MIRROR = 3;
+const NLASTRIP_EXTEND_HOLD = 0;
+const NLASTRIP_EXTEND_HOLD_FORWARD = 1;
+const NLASTRIP_FLAG_MUTED = 1 << 12;
+const NLATRACK_MUTED = 1 << 4;
+/** The parameter where a cubic's x is `x`, by bisection then Newton: the curve is monotonic. */
+function solveBezier(x0, x1, x2, x3, x) {
+    let lo = 0;
+    let hi = 1;
+    let t = (x - x0) / (x3 - x0 || 1);
+    for (let i = 0; i < 24; i++) {
+        const u = 1 - t;
+        const at = u * u * u * x0 + 3 * u * u * t * x1 + 3 * u * t * t * x2 + t * t * t * x3;
+        if (Math.abs(at - x) < 1e-7)
+            return t;
+        if (at < x)
+            lo = t;
+        else
+            hi = t;
+        const slope = 3 * u * u * (x1 - x0) + 6 * u * t * (x2 - x1) + 3 * t * t * (x3 - x2);
+        const next = slope !== 0 ? t - (at - x) / slope : (lo + hi) / 2;
+        t = next > lo && next < hi ? next : (lo + hi) / 2;
+    }
+    return t;
+}
+/** Blender's correction of a Bézier segment's handles, so its x never runs backwards. */
+function correct(k0, k1) {
+    let h1x = k0.rx - k0.x;
+    let h1y = k0.ry - k0.y;
+    let h2x = k1.x - k1.lx;
+    let h2y = k1.y - k1.ly;
+    const span = k1.x - k0.x;
+    const total = h1x + h2x;
+    if (total > span && total > 0) {
+        const f = span / total;
+        h1x *= f;
+        h1y *= f;
+        h2x *= f;
+        h2y *= f;
+    }
+    return [k0.x + h1x, k0.y + h1y, k1.x - h2x, k1.y - h2y];
+}
+function readKeys(curve) {
+    const count = curve.int('totvert');
+    if (count === 0 || curve.ptr('bezt') === 0n)
+        return [];
+    return curve.array('bezt', 'BezTriple', count).map((b) => {
+        const v = b.floats('vec');
+        return {
+            lx: v[0],
+            ly: v[1],
+            x: v[3],
+            y: v[4],
+            rx: v[6],
+            ry: v[7],
+            ipo: b.int('ipo'),
+        };
+    });
+}
+/** One F-curve, ready to evaluate. */
+export function readCurve(curve, unread) {
+    const keys = readKeys(curve);
+    if (keys.length === 0)
+        return null;
+    const extend = curve.int('extend');
+    let cycles = null;
+    for (const modifier of curve.list('modifiers')) {
+        if (modifier.int('type') === FMODIFIER_TYPE_CYCLES) {
+            const data = modifier.deref('data', 'FMod_Cycles');
+            cycles = { before: data?.int('before_mode') ?? 1, after: data?.int('after_mode') ?? 1 };
+        }
+        else
+            unread.add(`F-curve modifier ${modifier.int('type')}`);
+    }
+    for (const key of keys)
+        if (key.ipo > 2)
+            unread.add('easing past Bézier');
+    const first = keys[0];
+    const last = keys[keys.length - 1];
+    const span = last.x - first.x;
+    const plain = (frame) => {
+        if (frame <= first.x || keys.length === 1) {
+            if (extend !== FCURVE_EXTRAPOLATE_LINEAR || keys.length === 1)
+                return first.y;
+            const next = keys[1];
+            const slope = first.ipo === BEZT_IPO_BEZ_SLOPE
+                ? (first.y - first.ly) / (first.x - first.lx || 1)
+                : (next.y - first.y) / (next.x - first.x || 1);
+            return first.y + (frame - first.x) * slope;
+        }
+        if (frame >= last.x) {
+            if (extend !== FCURVE_EXTRAPOLATE_LINEAR)
+                return last.y;
+            const prev = keys[keys.length - 2];
+            const slope = last.ipo === BEZT_IPO_BEZ_SLOPE
+                ? (last.ry - last.y) / (last.rx - last.x || 1)
+                : (last.y - prev.y) / (last.x - prev.x || 1);
+            return last.y + (frame - last.x) * slope;
+        }
+        let lo = 0;
+        let hi = keys.length - 1;
+        while (hi - lo > 1) {
+            const mid = (lo + hi) >> 1;
+            if (keys[mid].x <= frame)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        const a = keys[lo];
+        const b = keys[hi];
+        if (a.ipo === BEZT_IPO_CONST)
+            return a.y;
+        if (a.ipo === BEZT_IPO_LIN)
+            return a.y + ((frame - a.x) / (b.x - a.x || 1)) * (b.y - a.y);
+        const [x1, y1, x2, y2] = correct(a, b);
+        const t = solveBezier(a.x, x1, x2, b.x, frame);
+        const u = 1 - t;
+        return u * u * u * a.y + 3 * u * u * t * y1 + 3 * u * t * t * y2 + t * t * t * b.y;
+    };
+    const evaluate = cycles === null || span <= 0
+        ? plain
+        : (frame) => {
+            const before = frame < first.x;
+            const mode = before ? cycles.before : cycles.after;
+            if ((frame >= first.x && frame <= last.x) || mode === FCM_EXTRAPOLATE_NONE)
+                return plain(frame);
+            const offset = frame - first.x;
+            const cycle = Math.floor(offset / span);
+            let local = offset - cycle * span;
+            if (mode === FCM_EXTRAPOLATE_MIRROR && cycle % 2 !== 0)
+                local = span - local;
+            const value = plain(first.x + local);
+            return mode === FCM_EXTRAPOLATE_CYCLIC_OFFSET
+                ? value + cycle * (last.y - first.y)
+                : value;
+        };
+    return {
+        path: curve.text('rna_path'),
+        index: curve.int('array_index'),
+        evaluate,
+        range: [first.x, last.x],
+    };
+}
+/** Bézier keys whose handles give the slope at an end. */
+const BEZT_IPO_BEZ_SLOPE = 2;
+/** The F-curves an action holds for `slot`: its channel bag in a layered action, every curve otherwise. */
+export function actionCurves(action, slot, unread) {
+    const out = [];
+    const legacy = action.has('curves') ? action.list('curves') : [];
+    for (const curve of legacy) {
+        const read = readCurve(curve, unread);
+        if (read !== null)
+            out.push(read);
+    }
+    if (!action.has('strip_keyframe_data_array') || action.int('strip_keyframe_data_array_num') === 0)
+        return out;
+    const scope = action.scope;
+    const file = action.file;
+    const data = action.pointers('strip_keyframe_data_array', action.int('strip_keyframe_data_array_num'));
+    for (const address of data) {
+        const keyframes = file.at(address, scope, 'ActionStripKeyframeData');
+        if (keyframes === null)
+            continue;
+        for (const bagAddress of keyframes.pointers('channelbag_array', keyframes.int('channelbag_array_num'))) {
+            const bag = file.at(bagAddress, scope, 'ActionChannelBag');
+            if (bag === null || bag.int('slot_handle') !== slot)
+                continue;
+            for (const curveAddress of bag.pointers('fcurve_array', bag.int('fcurve_array_num'))) {
+                const curve = file.at(curveAddress, scope, 'FCurve');
+                const read = curve === null ? null : readCurve(curve, unread);
+                if (read !== null)
+                    out.push(read);
+            }
+        }
+    }
+    return out;
+}
+function stripSource(strip, unread) {
+    const action = strip.deref('act');
+    if (action === null)
+        return null;
+    const curves = actionCurves(action, strip.has('action_slot_handle') ? strip.int('action_slot_handle') : 0, unread);
+    if (curves.length === 0)
+        return null;
+    const start = strip.float('start');
+    const end = strip.float('end');
+    const actStart = strip.float('actstart');
+    const actEnd = strip.float('actend');
+    const scale = Math.abs(strip.float('scale')) || 1;
+    const repeat = strip.float('repeat') || 1;
+    const length = actEnd - actStart || 1;
+    const extend = strip.int('extendmode');
+    const time = (frame) => {
+        if (frame < start)
+            return extend === NLASTRIP_EXTEND_HOLD ? actStart : null;
+        if (frame > end)
+            return extend === NLASTRIP_EXTEND_HOLD || extend === NLASTRIP_EXTEND_HOLD_FORWARD
+                ? actStart + (repeat % 1 === 0 ? length : ((end - start) / scale) % length)
+                : null;
+        /* At the very end of a whole number of repeats, the end of the action rather than its start. */
+        if (frame === end && repeat === Math.floor(repeat))
+            return actStart + length;
+        return (actStart +
+            ((((frame - start) % (length * scale)) + length * scale) % (length * scale)) / scale);
+    };
+    return { curves, time, range: [start, end] };
+}
+/** Everything that animates a datablock: its active action, then its NLA tracks bottom to top. */
+export class Animation {
+    sources = [];
+    unread = new Set();
+    constructor(id) {
+        const adt = id.has('adt') ? id.deref('adt') : null;
+        if (adt === null)
+            return;
+        for (const track of adt.list('nla_tracks')) {
+            if ((track.int('flag') & NLATRACK_MUTED) !== 0)
+                continue;
+            for (const strip of track.list('strips')) {
+                if ((strip.int('flag') & NLASTRIP_FLAG_MUTED) !== 0)
+                    continue;
+                const source = stripSource(strip, this.unread);
+                if (source !== null)
+                    this.sources.push(source);
+            }
+        }
+        const action = adt.deref('action');
+        if (action !== null) {
+            const curves = actionCurves(action, adt.has('slot_handle') ? adt.int('slot_handle') : 0, this.unread);
+            let lo = Infinity;
+            let hi = -Infinity;
+            for (const c of curves) {
+                lo = Math.min(lo, c.range[0]);
+                hi = Math.max(hi, c.range[1]);
+            }
+            if (curves.length > 0)
+                this.sources.push({ curves, time: (frame) => frame, range: [lo, hi] });
+        }
+        if (adt.list('drivers').length > 0)
+            this.unread.add('drivers');
+    }
+    get animated() {
+        return this.sources.length > 0;
+    }
+    /** The scene frames anything here animates over. */
+    get range() {
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (const s of this.sources) {
+            lo = Math.min(lo, s.range[0]);
+            hi = Math.max(hi, s.range[1]);
+        }
+        return [lo, hi];
+    }
+    /** Every animated value at `frame`, by `path[index]`; the last source to speak wins. */
+    values(frame, out) {
+        out.clear();
+        for (const source of this.sources) {
+            const t = source.time(frame);
+            if (t === null)
+                continue;
+            for (const curve of source.curves)
+                out.set(`${curve.path}[${curve.index}]`, curve.evaluate(t));
+        }
+        return out;
+    }
+}

package/dist/blendData.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Reading a `.blend`'s structs by field name, and following its pointers between blocks.
+ *
+ * `blendFile.ts` says where every block is and what every struct looks like; this is what turns
+ * those two tables into `mesh.int('totvert')` and `object.deref('data')`. Every accessor names a
+ * field rather than an offset, so a field that moved between Blender releases is found where the
+ * file says it is, and a field that does not exist in this file answers `has` false rather than
+ * reading whatever sits at an offset some other release used.
+ *
+ * **A missing field is a question, not an error.** Most of the reading above this module is
+ * "the new name if this file has it, the old one otherwise", so `has` is cheap and every typed
+ * accessor throws only when asked for a field the struct does not carry — which is a reader bug,
+ * and is said with the struct's name and the Blender version beside it.
+ */
+import type { BlendBlock, BlendHeader, DnaField, DnaStruct } from './blendFile.ts';
+/** A parsed file: its blocks, its catalogue, and the maps from an address to a block. */
+export declare class BlendData {
+    readonly header: BlendHeader;
+    readonly bytes: Uint8Array;
+    readonly view: DataView;
+    readonly blocks: readonly BlendBlock[];
+    readonly structs: readonly DnaStruct[];
+    private readonly byType;
+    /**
+     * Which datablock each block's data belongs to: the most recent block that is not `DATA`.
+     *
+     * **Addresses are only unique inside one datablock, and 5.0 relies on it.** Blender's own reader
+     * keeps one map for datablocks and a second, per datablock, for the data blocks that follow it,
+     * and 5.0 writes placeholder addresses that repeat between datablocks: measured on a 5.0 file,
+     * one address named eight different meshes' attribute arrays. A file-wide map answered every
+     * mesh with the last mesh's positions.
+     */
+    private readonly owner;
+    private readonly ids;
+    private readonly scoped;
+    private readonly sorted;
+    /** Before 5.0 every address was a real one, so a data pointer may be resolved file-wide. */
+    private readonly fileWide;
+    constructor(bytes: Uint8Array);
+    /** The catalogue entry for a struct type, or undefined where this file's Blender had none. */
+    struct(type: string): DnaStruct | undefined;
+    /** The datablock a block's data belongs to, which is what scopes every pointer inside it. */
+    scopeOf(block: number): number;
+    /**
+     * The block an address falls in, and how far into it, as seen from inside datablock `scope`.
+     *
+     * The datablock's own data first, then the datablocks themselves, which is the order Blender's
+     * reader resolves in. Null for an address nothing holds.
+     */
+    find(address: bigint, scope: number): {
+        block: number;
+        offset: number;
+    } | null;
+    /** Every datablock of a two-letter code — `OB`, `ME`, `MA` — as views of their own struct. */
+    idsOf(code: string): BlendStruct[];
+    /** A view of the struct at an address, typed by the block that holds it or by `type`. */
+    at(address: bigint, scope: number, type?: string): BlendStruct | null;
+    /**
+     * The structs of an array a pointer names, indexed *inside* its block.
+     *
+     * **Never by adding to the address.** From 5.0 an address is a placeholder rather than a
+     * location, so `base + 24` is not the second element and can be exactly the address of some
+     * unrelated block.
+     */
+    array(address: bigint, scope: number, type: string, count?: number): BlendStruct[];
+    /** The raw bytes a pointer names, through the end of its block. */
+    raw(address: bigint, scope: number): Uint8Array | null;
+    /** A zero-terminated string a `char *` names. */
+    text(address: bigint, scope: number): string;
+    /** The block a pointer names, for its count and its catalogue type. */
+    blockOf(address: bigint, scope: number): BlendBlock | null;
+    pointer(at: number): bigint;
+}
+/** One struct in the file, read by field name. */
+export declare class BlendStruct {
+    readonly file: BlendData;
+    readonly struct: DnaStruct;
+    readonly offset: number;
+    /** The datablock this struct's data belongs to, which every pointer in it is resolved inside. */
+    readonly scope: number;
+    constructor(file: BlendData, struct: DnaStruct, offset: number, 
+    /** The datablock this struct's data belongs to, which every pointer in it is resolved inside. */
+    scope: number);
+    get type(): string;
+    has(name: string): boolean;
+    field(name: string): DnaField;
+    /** An integer field of any width, signed as its type is. */
+    int(name: string, index?: number): number;
+    float(name: string, index?: number): number;
+    /** Every element of a float array field, flattened: `co[3]` is three, `mat[4][4]` sixteen. */
+    floats(name: string): number[];
+    ints(name: string): number[];
+    /** A `char[]` field as text, up to its first zero. */
+    string(name: string): string;
+    /** An ID's name without its two-letter code: `OBCube` is `Cube`. */
+    idName(): string;
+    ptr(name: string, index?: number): bigint;
+    /** Follow a pointer field, typed by the block it lands in or by `type` where that is known. */
+    deref(name: string, type?: string): BlendStruct | null;
+    /** An array a pointer field names, `count` long or as long as its block. */
+    array(name: string, type: string, count?: number): BlendStruct[];
+    /** The bytes a pointer field names, through the end of their block. */
+    raw(name: string): Uint8Array | null;
+    /** The block a pointer field names. */
+    blockOf(name: string): BlendBlock | null;
+    /** A `char *` field's text. */
+    text(name: string): string;
+    /** An embedded struct field, viewed in place. */
+    sub(name: string): BlendStruct;
+    /** The links of a `ListBase` field, following `next` until it runs out. */
+    list(name: string, type?: string): BlendStruct[];
+    /** An array of pointers that a pointer-to-pointer field names: `Mesh.mat`, `Object.mat`. */
+    pointers(name: string, count: number): bigint[];
+}