@driftengine/drft 3.61.0

package/src/animationData.ts

@@ -0,0 +1,58 @@
+/**
+ * What a rig and its clips are, as data.
+ *
+ * **Here for the reason `MeshData` is here**, and stated in that file's header: these are the
+ * boundary objects between the container and everything that uses one. `SKIN` and `ANIM` are
+ * chunks, so what they carry belongs to the format package — which also means the two packages
+ * that meet over a rig, `@driftengine/assets` producing one and `@driftengine/animation` consuming
+ * one, do so without either depending on the other. Both already depend on this.
+ *
+ * Nothing here has behaviour. `Skeleton`, `Pose` and `sampleClip` live in the animation package,
+ * which re-exports these types so a consumer imports from one place.
+ */
+
+/** One joint: where it hangs and what it is called. */
+export interface Joint {
+  /**
+   * Index of this joint's parent, or -1 for a root. **Always less than this joint's own index.**
+   *
+   * Parents-first is a requirement rather than a convention: a palette is resolved in index order
+   * and reads each joint's parent as it goes, so a nearly-sorted rig is wrong in one limb — which
+   * reads as a bad animation rather than as a data error. The importer sorts, because it is also
+   * the layer that can remap every index naming a joint; `Skeleton` refuses an unsorted one.
+   */
+  readonly parent: number;
+  /** The name the source rig gave it, which is what retargeting matches on. */
+  readonly name: string;
+}
+
+/** Which of a joint's three transforms a track drives. */
+export type TrackPath = 'translation' | 'rotation' | 'scale';
+
+/** One joint's keys for one of its three transforms. */
+export interface JointTrack {
+  readonly joint: number;
+  readonly path: TrackPath;
+  /** Ascending, in seconds. One entry per key. */
+  readonly times: Float32Array;
+  /** Three floats a key for translation and scale, four for rotation. */
+  readonly values: Float32Array;
+}
+
+export interface AnimationClip {
+  readonly name: string;
+  readonly durationSec: number;
+  readonly tracks: readonly JointTrack[];
+}
+
+/**
+ * A skin: the joints, their inverse bind matrices, and nothing about how it is played.
+ *
+ * `inverseBind` is sixteen floats a joint, column-major, in the same order as `joints`. An entry
+ * takes a vertex from model space into that joint's bind-pose space, which is what makes a palette
+ * identity at the bind pose whatever the bind pose is.
+ */
+export interface DrftSkin {
+  readonly joints: readonly Joint[];
+  readonly inverseBind: Float32Array;
+}

package/src/coarseFirst.ts

@@ -0,0 +1,113 @@
+/** The order splats are written to the container in, so any prefix of the file is the whole place. */
+
+/**
+ * Bits per axis in the spatial key. Ten, so three of them fit a 30-bit integer sort key.
+ *
+ * A thousand and twenty-four cells an axis over the capture's own extent, which for a room-sized
+ * capture is under a centimetre. What it gives up is that two splats inside one cell are ordered
+ * arbitrarily against each other, which is invisible at any block size a stream uses. What would
+ * make it wrong is a capture whose extent is dominated by one distant outlier, squeezing the rest
+ * into a handful of cells — the same failure any quantisation has.
+ */
+const AXIS_BITS = 10;
+const AXIS_CELLS = (1 << AXIS_BITS) - 1;
+
+/** Spread ten bits out to every third bit, so three of them interleave into one integer. */
+function spread(value: number): number {
+  let bits = value & AXIS_CELLS;
+  bits = (bits | (bits << 16)) & 0x030000ff;
+  bits = (bits | (bits << 8)) & 0x0300f00f;
+  bits = (bits | (bits << 4)) & 0x030c30c3;
+  bits = (bits | (bits << 2)) & 0x09249249;
+  return bits;
+}
+
+/**
+ * The order to write a capture's splats in, so that **every prefix of the file is a complete
+ * sparse capture** rather than a finished corner of one.
+ *
+ * **This is the reason the container is worth having at all.** Everything above it is a splat
+ * viewer; a load that opens on a recognisable place and densifies is what a viewer streaming from
+ * a plain file cannot do by accident. It is the same trick `coarseLevel.ts` plays for meshes,
+ * where a decimated whole body reads as a car and one finished wheel does not.
+ *
+ * Two steps, and both are needed:
+ *
+ * 1. **Sort by Morton code**, so index order becomes spatial order. Without this the sequence
+ *    below decimates whatever order the trainer happened to leave — which is usually fine and is
+ *    a slab of one axis when it is not, and the difference is invisible until somebody opens a
+ *    capture that was written out in scan order. `coarseFirst.test.ts` builds exactly that case.
+ * 2. **Walk that order bit-reversed**, which is the van der Corput sequence and is what makes
+ *    each *block* a sparse capture rather than only the first. Reversing the bits of a counter
+ *    visits 0, half way, quarter, three quarters, and so on, so consecutive slots are maximally
+ *    far apart in the spatial order and every block is an even scattering over the whole thing.
+ *
+ * What it costs is a sort at bake time — `O(n log n)` once, on a machine with a keyboard — and
+ * nothing at all at load. **What would make it wrong** is a capture meant to be read in its
+ * authored order, which this format has no notion of: a `.drft` splat chunk is a set, and a
+ * consumer that needed the original indices would need them stored.
+ */
+export function coarseFirstOrder(positions: Float32Array, count: number): Uint32Array {
+  const order = new Uint32Array(Math.max(0, count));
+  if (count <= 0) return order;
+  if (count === 1) return order;
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (let index = 0; index < count; index++) {
+    const at = index * 3;
+    const x = positions[at] ?? 0;
+    const y = positions[at + 1] ?? 0;
+    const z = positions[at + 2] ?? 0;
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (z < minZ) minZ = z;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+    if (z > maxZ) maxZ = z;
+  }
+  /* A capture with no extent on an axis quantises every splat to cell zero there, which is the
+     right answer: with no range there is no spatial order along it to preserve. */
+  const scaleX = maxX > minX ? AXIS_CELLS / (maxX - minX) : 0;
+  const scaleY = maxY > minY ? AXIS_CELLS / (maxY - minY) : 0;
+  const scaleZ = maxZ > minZ ? AXIS_CELLS / (maxZ - minZ) : 0;
+
+  const spatial = new Uint32Array(count);
+  const keys = new Uint32Array(count);
+  for (let index = 0; index < count; index++) {
+    const at = index * 3;
+    const x = Math.round(((positions[at] ?? 0) - minX) * scaleX);
+    const y = Math.round(((positions[at + 1] ?? 0) - minY) * scaleY);
+    const z = Math.round(((positions[at + 2] ?? 0) - minZ) * scaleZ);
+    keys[index] = (spread(x) | (spread(y) << 1) | (spread(z) << 2)) >>> 0;
+    spatial[index] = index;
+  }
+  /*
+   * A comparison sort, deliberately. This runs once per bake on a workstation, against a counting
+   * sort's 4 MB of buckets for a 30-bit key; the frame-time sort in `@driftengine/splats` is the
+   * one where that trade goes the other way, and it says so.
+   */
+  const sorted = Array.from(spatial).sort((a, b) => (keys[a] ?? 0) - (keys[b] ?? 0));
+
+  /*
+   * Bit-reversal over the spatial order. `width` is the number of bits the count needs, so the
+   * counter covers a power of two at least as large; reversed values landing past the end are
+   * skipped, which keeps the sequence's spread and costs at most one extra pass.
+   */
+  let width = 0;
+  while (1 << width < count) width++;
+  let slot = 0;
+  for (let counter = 0; counter < 1 << width; counter++) {
+    let reversed = 0;
+    for (let bit = 0; bit < width; bit++) {
+      if ((counter & (1 << bit)) !== 0) reversed |= 1 << (width - 1 - bit);
+    }
+    if (reversed >= count) continue;
+    order[slot++] = sorted[reversed] ?? 0;
+  }
+  return order;
+}

package/src/drftColliders.ts

@@ -0,0 +1,153 @@
+import { DrftError, align } from './drftFormat.ts';
+
+/**
+ * `COLL`: the convex hulls an asset collides as.
+ *
+ * **A FourCC that was claimed and undefined for the whole of v1.** `docs/FORMAT.md` §4.3 listed the
+ * row and `KNOWN_CHUNKS` held the code while no writer emitted one and no reader consumed one.
+ * `readModel.ts` said why in as many words when it declined to put a vehicle's collision hull inside
+ * the model's own file: *"a format decision about whether a hull is triangle soup or a set of convex
+ * hulls, and not one an import should make in passing."* This is that decision, made — **a set of
+ * convex hulls**.
+ *
+ * **Points, not shapes, because this package depends on nothing.** `boundaries.test.mjs` asserts
+ * that import graph and `drft-only` measures what it is worth. A serialised `ConvexShape` would mean
+ * the format package knowing what a face plane and a separating axis are, and it would freeze a
+ * representation the physics package is still free to change. A hull here is the points whose hull
+ * it is, which is exactly what `hullShape` takes:
+ *
+ * ```ts
+ * const shapes = asset.colliders.map((points) => hullShape(points));
+ * ```
+ *
+ * **One chunk for the file**, pairing with nothing. An asset's collision is a fact about the whole
+ * asset the way `SUBS` is a fact about all its materials, not a thing that belongs to mesh three.
+ *
+ * ```
+ * u32  hullCount
+ * u32  pointTotal
+ * u32  starts[hullCount + 1]     offsets in points; starts[0] = 0, starts[n] = pointTotal
+ * f32  points[pointTotal * 3]    xyz, in the asset's own space
+ * ```
+ *
+ * The starts table is written whole, with its closing entry, so a reader takes every hull's extent
+ * from one subtraction and never has to special-case the last one. Everything is four-byte aligned,
+ * so the points come back as one `Float32Array` view over the fetched buffer and each hull is a
+ * `subarray` of it — the same property `MESH` exists for.
+ */
+
+/** How many points one hull may carry, which is what `hullShape` accepts. */
+export const MAX_COLLIDER_POINTS = 64;
+
+/**
+ * A cap on hulls per asset, so a malformed length cannot ask a reader for gigabytes.
+ *
+ * Matches `MAX_BODY_PARTS` in `@driftengine/physics` by intent rather than by import — this package
+ * depends on nothing, and the two are checked against each other by a test in the engine instead.
+ */
+export const MAX_COLLIDER_HULLS = 32;
+
+export function buildColliders(hulls: readonly Float32Array[]): Uint8Array {
+  if (hulls.length > MAX_COLLIDER_HULLS) {
+    throw new DrftError(`${hulls.length} collision hulls exceeds ${MAX_COLLIDER_HULLS}`);
+  }
+  let pointTotal = 0;
+  for (const hull of hulls) {
+    if (hull.length % 3 !== 0) {
+      throw new DrftError(`a collision hull has ${hull.length} floats, which is not whole points`);
+    }
+    const points = hull.length / 3;
+    if (points === 0) throw new DrftError('a collision hull has no points');
+    if (points > MAX_COLLIDER_POINTS) {
+      throw new DrftError(
+        `a collision hull has ${points} points, over the ${MAX_COLLIDER_POINTS} cap`,
+      );
+    }
+    pointTotal += points;
+  }
+
+  const startsBytes = (hulls.length + 1) * 4;
+  const size = 8 + startsBytes + pointTotal * 3 * 4;
+  const bytes = new Uint8Array(align(size));
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, hulls.length, true);
+  view.setUint32(4, pointTotal, true);
+
+  let start = 0;
+  for (let i = 0; i < hulls.length; i++) {
+    view.setUint32(8 + i * 4, start, true);
+    start += (hulls[i] as Float32Array).length / 3;
+  }
+  view.setUint32(8 + hulls.length * 4, pointTotal, true);
+
+  const points = new Float32Array(bytes.buffer, 8 + startsBytes, pointTotal * 3);
+  let at = 0;
+  for (const hull of hulls) {
+    points.set(hull, at);
+    at += hull.length;
+  }
+  return bytes;
+}
+
+/**
+ * The hulls a `COLL` chunk carries, as views over the fetched buffer.
+ *
+ * Views rather than copies, exactly like the vertex arrays, so a load allocates nothing beyond the
+ * array holding them. They keep the file alive for as long as they are held, which is the same trade
+ * `DrftTexture.bytes` makes and for the same reason.
+ */
+export function readColliders(
+  buffer: ArrayBuffer,
+  offset: number,
+  byteLength: number,
+): readonly Float32Array[] {
+  if (byteLength < 8) throw new DrftError('COLL is too short to hold its counts');
+  const view = new DataView(buffer, offset, byteLength);
+  const hullCount = view.getUint32(0, true);
+  const pointTotal = view.getUint32(4, true);
+  if (hullCount > MAX_COLLIDER_HULLS) {
+    throw new DrftError(`COLL claims ${hullCount} hulls, over the ${MAX_COLLIDER_HULLS} cap`);
+  }
+
+  const startsBytes = (hullCount + 1) * 4;
+  const needed = 8 + startsBytes + pointTotal * 3 * 4;
+  if (byteLength < needed) {
+    throw new DrftError(
+      `COLL claims ${hullCount} hulls and ${pointTotal} points, which runs past the chunk`,
+    );
+  }
+
+  /*
+   * The starts are read and checked before a single point is handed out. A table that runs backwards
+   * or past the total would otherwise produce a `subarray` of a length nobody wrote, which is a hull
+   * of arbitrary geometry rather than an error.
+   */
+  const starts = new Uint32Array(hullCount + 1);
+  for (let i = 0; i <= hullCount; i++) starts[i] = view.getUint32(8 + i * 4, true);
+  if ((starts[0] as number) !== 0)
+    throw new DrftError('COLL does not start its first hull at zero');
+  if ((starts[hullCount] as number) !== pointTotal) {
+    throw new DrftError('COLL closes its table at a point count it did not declare');
+  }
+  for (let i = 0; i < hullCount; i++) {
+    const from = starts[i] as number;
+    const to = starts[i + 1] as number;
+    if (to < from) throw new DrftError(`COLL hull ${i} runs backwards`);
+    const points = to - from;
+    if (points === 0) throw new DrftError(`COLL hull ${i} has no points`);
+    if (points > MAX_COLLIDER_POINTS) {
+      throw new DrftError(
+        `COLL hull ${i} has ${points} points, over the ${MAX_COLLIDER_POINTS} cap`,
+      );
+    }
+  }
+
+  const all = new Float32Array(buffer, offset + 8 + startsBytes, pointTotal * 3);
+  const hulls: Float32Array[] = [];
+  for (let i = 0; i < hullCount; i++) {
+    const from = (starts[i] as number) * 3;
+    const to = (starts[i + 1] as number) * 3;
+    hulls.push(all.subarray(from, to));
+  }
+  return hulls;
+}