@driftengine/assets 4.6.1 → 4.7.1

package/src/blendAnimation.ts

@@ -0,0 +1,328 @@
+/**
+ * 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];
+}
+
+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;
+
+interface Key {
+  x: number;
+  y: number;
+  /** Left handle, then right. */
+  lx: number;
+  ly: number;
+  rx: number;
+  ry: number;
+  ipo: number;
+}
+
+/** The parameter where a cubic's x is `x`, by bisection then Newton: the curve is monotonic. */
+function solveBezier(x0: number, x1: number, x2: number, x3: number, x: number): number {
+  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: Key, k1: Key): [number, number, number, number] {
+  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: BlendStruct): Key[] {
+  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] as number,
+      ly: v[1] as number,
+      x: v[3] as number,
+      y: v[4] as number,
+      rx: v[6] as number,
+      ry: v[7] as number,
+      ipo: b.int('ipo'),
+    };
+  });
+}
+
+/** One F-curve, ready to evaluate. */
+export function readCurve(curve: BlendStruct, unread: Set<string>): Curve | null {
+  const keys = readKeys(curve);
+  if (keys.length === 0) return null;
+  const extend = curve.int('extend');
+  let cycles: { before: number; after: number } | null = 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] as Key;
+  const last = keys[keys.length - 1] as Key;
+  const span = last.x - first.x;
+
+  const plain = (frame: number): number => {
+    if (frame <= first.x || keys.length === 1) {
+      if (extend !== FCURVE_EXTRAPOLATE_LINEAR || keys.length === 1) return first.y;
+      const next = keys[1] as Key;
+      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] as Key;
+      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] as Key).x <= frame) lo = mid;
+      else hi = mid;
+    }
+    const a = keys[lo] as Key;
+    const b = keys[hi] as Key;
+    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: number): number => {
+          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: BlendStruct, slot: number, unread: Set<string>): Curve[] {
+  const out: Curve[] = [];
+  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;
+}
+
+/** An NLA strip's or the active action's curves, and how scene time maps into them. */
+interface Source {
+  readonly curves: readonly Curve[];
+  /** Action time at a scene frame, or null where the strip says nothing then. */
+  readonly time: (frame: number) => number | null;
+  readonly range: readonly [number, number];
+}
+
+function stripSource(strip: BlendStruct, unread: Set<string>): Source | null {
+  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: number): number | null => {
+    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 {
+  private readonly sources: Source[] = [];
+  readonly unread = new Set<string>();
+
+  constructor(id: BlendStruct) {
+    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(): boolean {
+    return this.sources.length > 0;
+  }
+
+  /** The scene frames anything here animates over. */
+  get range(): [number, number] {
+    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: number, out: Map<string, number>): Map<string, number> {
+    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/src/blendData.ts

@@ -0,0 +1,375 @@
+/**
+ * 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 { DrftError } from '@driftengine/drft';
+import type { BlendBlock, BlendHeader, DnaField, DnaStruct } from './blendFile.ts';
+import { readBlendBlocks, readBlendHeader, readDna } from './blendFile.ts';
+
+/** A parsed file: its blocks, its catalogue, and the maps from an address to a block. */
+export class BlendData {
+  readonly header: BlendHeader;
+  readonly bytes: Uint8Array;
+  readonly view: DataView;
+  readonly blocks: readonly BlendBlock[];
+  readonly structs: readonly DnaStruct[];
+  private readonly byType = new Map<string, DnaStruct>();
+  /**
+   * 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: Int32Array;
+  private readonly ids = new Map<bigint, number>();
+  private readonly scoped = new Map<number, Map<bigint, number>>();
+  private readonly sorted = new Map<number, number[]>();
+  /** Before 5.0 every address was a real one, so a data pointer may be resolved file-wide. */
+  private readonly fileWide: Map<bigint, number> | null;
+
+  constructor(bytes: Uint8Array) {
+    this.bytes = bytes;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.header = readBlendHeader(bytes);
+    this.blocks = readBlendBlocks(bytes, this.header);
+    const dna = this.blocks.find((block) => block.code === 'DNA1');
+    if (dna === undefined) throw new DrftError('blend: the file carries no DNA1 catalogue');
+    this.structs = readDna(bytes, dna, this.header);
+    for (const struct of this.structs) this.byType.set(struct.type, struct);
+
+    this.owner = new Int32Array(this.blocks.length);
+    this.fileWide = this.header.version < 500 ? new Map() : null;
+    let scope = -1;
+    this.blocks.forEach((block, i) => {
+      if (block.code !== 'DATA') {
+        scope = i;
+        if (block.address !== 0n) this.ids.set(block.address, i);
+      } else if (block.address !== 0n) {
+        let map = this.scoped.get(scope);
+        if (map === undefined) this.scoped.set(scope, (map = new Map()));
+        map.set(block.address, i);
+        let list = this.sorted.get(scope);
+        if (list === undefined) this.sorted.set(scope, (list = []));
+        list.push(i);
+      }
+      this.owner[i] = block.code === 'DATA' ? scope : i;
+      if (this.fileWide !== null && block.address !== 0n) this.fileWide.set(block.address, i);
+    });
+    for (const list of this.sorted.values()) {
+      list.sort((a, b) => {
+        const x = (this.blocks[a] as BlendBlock).address;
+        const y = (this.blocks[b] as BlendBlock).address;
+        return x < y ? -1 : x > y ? 1 : 0;
+      });
+    }
+  }
+
+  /** The catalogue entry for a struct type, or undefined where this file's Blender had none. */
+  struct(type: string): DnaStruct | undefined {
+    return this.byType.get(type);
+  }
+
+  /** The datablock a block's data belongs to, which is what scopes every pointer inside it. */
+  scopeOf(block: number): number {
+    return this.owner[block] ?? -1;
+  }
+
+  /**
+   * 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 {
+    if (address === 0n) return null;
+    const own = this.scoped.get(scope)?.get(address) ?? this.ids.get(address);
+    if (own !== undefined) return { block: own, offset: 0 };
+    const list = this.sorted.get(scope);
+    if (list !== undefined) {
+      let lo = 0;
+      let hi = list.length - 1;
+      while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const index = list[mid] as number;
+        const block = this.blocks[index] as BlendBlock;
+        if (block.address > address) hi = mid - 1;
+        else if (block.address + BigInt(block.length) <= address) lo = mid + 1;
+        else return { block: index, offset: Number(address - block.address) };
+      }
+    }
+    const anywhere = this.fileWide?.get(address);
+    return anywhere === undefined ? null : { block: anywhere, offset: 0 };
+  }
+
+  /** Every datablock of a two-letter code — `OB`, `ME`, `MA` — as views of their own struct. */
+  idsOf(code: string): BlendStruct[] {
+    const out: BlendStruct[] = [];
+    this.blocks.forEach((block, i) => {
+      if (block.code !== code) return;
+      const struct = this.structs[block.sdna];
+      if (struct !== undefined) out.push(new BlendStruct(this, struct, block.offset, i));
+    });
+    return out;
+  }
+
+  /** 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 {
+    const found = this.find(address, scope);
+    if (found === null) return null;
+    const block = this.blocks[found.block] as BlendBlock;
+    const struct = type === undefined ? this.structs[block.sdna] : this.byType.get(type);
+    if (struct === undefined) return null;
+    return new BlendStruct(this, struct, block.offset + found.offset, this.scopeOf(found.block));
+  }
+
+  /**
+   * 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[] {
+    const found = this.find(address, scope);
+    const struct = this.byType.get(type);
+    if (found === null || struct === undefined) return [];
+    const block = this.blocks[found.block] as BlendBlock;
+    const start = block.offset + found.offset;
+    const room = Math.floor((block.offset + block.length - start) / struct.size);
+    const n = Math.min(count ?? room, room);
+    const owner = this.scopeOf(found.block);
+    const out: BlendStruct[] = [];
+    for (let i = 0; i < n; i++)
+      out.push(new BlendStruct(this, struct, start + i * struct.size, owner));
+    return out;
+  }
+
+  /** The raw bytes a pointer names, through the end of its block. */
+  raw(address: bigint, scope: number): Uint8Array | null {
+    const found = this.find(address, scope);
+    if (found === null) return null;
+    const block = this.blocks[found.block] as BlendBlock;
+    return this.bytes.subarray(block.offset + found.offset, block.offset + block.length);
+  }
+
+  /** A zero-terminated string a `char *` names. */
+  text(address: bigint, scope: number): string {
+    const raw = this.raw(address, scope);
+    if (raw === null) return '';
+    const stop = raw.indexOf(0);
+    return new TextDecoder().decode(stop < 0 ? raw : raw.subarray(0, stop));
+  }
+
+  /** The block a pointer names, for its count and its catalogue type. */
+  blockOf(address: bigint, scope: number): BlendBlock | null {
+    const found = this.find(address, scope);
+    return found === null ? null : (this.blocks[found.block] ?? null);
+  }
+
+  pointer(at: number): bigint {
+    const le = this.header.littleEndian;
+    return this.header.pointerSize === 8
+      ? this.view.getBigUint64(at, le)
+      : BigInt(this.view.getUint32(at, le));
+  }
+}
+
+/** One struct in the file, read by field name. */
+export class BlendStruct {
+  constructor(
+    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,
+  ) {}
+
+  get type(): string {
+    return this.struct.type;
+  }
+
+  has(name: string): boolean {
+    return this.struct.fields.has(name);
+  }
+
+  field(name: string): DnaField {
+    const field = this.struct.fields.get(name);
+    if (field === undefined) {
+      throw new DrftError(
+        `blend: ${this.struct.type} has no field "${name}" in a file from Blender ` +
+          `${this.file.header.version}, which is a reader bug rather than a bad file`,
+      );
+    }
+    return field;
+  }
+
+  /** An integer field of any width, signed as its type is. */
+  int(name: string, index = 0): number {
+    const field = this.field(name);
+    return readInt(this.file, field.type, this.offset + field.offset + index * elementSize(field));
+  }
+
+  float(name: string, index = 0): number {
+    const field = this.field(name);
+    const at = this.offset + field.offset + index * elementSize(field);
+    const le = this.file.header.littleEndian;
+    return field.type === 'double'
+      ? this.file.view.getFloat64(at, le)
+      : this.file.view.getFloat32(at, le);
+  }
+
+  /** Every element of a float array field, flattened: `co[3]` is three, `mat[4][4]` sixteen. */
+  floats(name: string): number[] {
+    const field = this.field(name);
+    const count = field.dims.reduce((n, d) => n * d, 1);
+    const out: number[] = [];
+    for (let i = 0; i < count; i++) out.push(this.float(name, i));
+    return out;
+  }
+
+  ints(name: string): number[] {
+    const field = this.field(name);
+    const count = field.dims.reduce((n, d) => n * d, 1);
+    const out: number[] = [];
+    for (let i = 0; i < count; i++) out.push(this.int(name, i));
+    return out;
+  }
+
+  /** A `char[]` field as text, up to its first zero. */
+  string(name: string): string {
+    const field = this.field(name);
+    const start = this.offset + field.offset;
+    const bytes = this.file.bytes.subarray(start, start + field.size);
+    const stop = bytes.indexOf(0);
+    return new TextDecoder().decode(stop < 0 ? bytes : bytes.subarray(0, stop));
+  }
+
+  /** An ID's name without its two-letter code: `OBCube` is `Cube`. */
+  idName(): string {
+    return this.sub('id').string('name').slice(2);
+  }
+
+  ptr(name: string, index = 0): bigint {
+    const field = this.field(name);
+    if (!field.pointer) throw new DrftError(`blend: ${this.struct.type}.${name} is not a pointer`);
+    return this.file.pointer(this.offset + field.offset + index * this.file.header.pointerSize);
+  }
+
+  /** 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 {
+    return this.file.at(this.ptr(name), this.scope, type);
+  }
+
+  /** An array a pointer field names, `count` long or as long as its block. */
+  array(name: string, type: string, count?: number): BlendStruct[] {
+    return this.file.array(this.ptr(name), this.scope, type, count);
+  }
+
+  /** The bytes a pointer field names, through the end of their block. */
+  raw(name: string): Uint8Array | null {
+    return this.file.raw(this.ptr(name), this.scope);
+  }
+
+  /** The block a pointer field names. */
+  blockOf(name: string): BlendBlock | null {
+    return this.file.blockOf(this.ptr(name), this.scope);
+  }
+
+  /** A `char *` field's text. */
+  text(name: string): string {
+    return this.file.text(this.ptr(name), this.scope);
+  }
+
+  /** An embedded struct field, viewed in place. */
+  sub(name: string): BlendStruct {
+    const field = this.field(name);
+    const struct = this.file.struct(field.type);
+    if (struct === undefined)
+      throw new DrftError(`blend: no struct ${field.type} in the catalogue`);
+    return new BlendStruct(this.file, struct, this.offset + field.offset, this.scope);
+  }
+
+  /** The links of a `ListBase` field, following `next` until it runs out. */
+  list(name: string, type?: string): BlendStruct[] {
+    const base = this.sub(name);
+    const out: BlendStruct[] = [];
+    const seen = new Set<bigint>();
+    let address = base.ptr('first');
+    while (address !== 0n && !seen.has(address)) {
+      seen.add(address);
+      const link = this.file.at(address, this.scope, type);
+      if (link === null) break;
+      out.push(link);
+      /* `next` is the first pointer of every link, including those that embed it in a header
+         struct of their own, as every modifier and constraint does. */
+      address = this.file.pointer(link.offset);
+    }
+    return out;
+  }
+
+  /** An array of pointers that a pointer-to-pointer field names: `Mesh.mat`, `Object.mat`. */
+  pointers(name: string, count: number): bigint[] {
+    const raw = this.file.find(this.ptr(name), this.scope);
+    if (raw === null) return [];
+    const out: bigint[] = [];
+    const base = (this.file.blocks[raw.block] as BlendBlock).offset + raw.offset;
+    for (let i = 0; i < count; i++)
+      out.push(this.file.pointer(base + i * this.file.header.pointerSize));
+    return out;
+  }
+}
+
+function elementSize(field: DnaField): number {
+  const count = field.dims.reduce((n, d) => n * d, 1);
+  return field.size / count;
+}
+
+function readInt(file: BlendData, type: string, at: number): number {
+  const le = file.header.littleEndian;
+  const view = file.view;
+  switch (type) {
+    case 'char':
+    case 'uchar':
+    case 'uint8_t':
+    case 'bool':
+      return view.getUint8(at);
+    case 'int8_t':
+      return view.getInt8(at);
+    case 'short':
+    case 'int16_t':
+      return view.getInt16(at, le);
+    case 'ushort':
+    case 'uint16_t':
+      return view.getUint16(at, le);
+    case 'int':
+    case 'int32_t':
+      return view.getInt32(at, le);
+    case 'uint':
+    case 'uint32_t':
+      return view.getUint32(at, le);
+    case 'int64_t':
+    case 'long':
+      return Number(view.getBigInt64(at, le));
+    case 'uint64_t':
+    case 'ulong':
+      return Number(view.getBigUint64(at, le));
+    case 'float':
+      return view.getFloat32(at, le);
+    default:
+      throw new DrftError(`blend: no integer reading for a field of type ${type}`);
+  }
+}