@driftengine/drft 3.61.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.

package/README.md

@@ -0,0 +1,9 @@
+# @driftengine/drft
+
+The `.drft` container: read and write a baked scene. Declares no runtime dependency.
+
+**Cost: 5.0 KB gzipped.** 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.
+
+Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)
+for how the packages divide, and why some features are compiled into core on demand instead.

package/dist/animationData.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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/dist/animationData.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export {};

package/dist/coarseFirst.d.ts

@@ -0,0 +1,27 @@
+/** The order splats are written to the container in, so any prefix of the file is the whole place. */
+/**
+ * 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 declare function coarseFirstOrder(positions: Float32Array, count: number): Uint32Array;

package/dist/coarseFirst.js

@@ -0,0 +1,118 @@
+/** 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) {
+    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, count) {
+    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/dist/drftColliders.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `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 declare 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 declare const MAX_COLLIDER_HULLS = 32;
+export declare function buildColliders(hulls: readonly Float32Array[]): Uint8Array;
+/**
+ * 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 declare function readColliders(buffer: ArrayBuffer, offset: number, byteLength: number): readonly Float32Array[];

package/dist/drftColliders.js

@@ -0,0 +1,137 @@
+import { DrftError, align } from './drftFormat.js';
+/**
+ * `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) {
+    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].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, offset, byteLength) {
+    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] !== 0)
+        throw new DrftError('COLL does not start its first hull at zero');
+    if (starts[hullCount] !== 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];
+        const to = starts[i + 1];
+        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 = [];
+    for (let i = 0; i < hullCount; i++) {
+        const from = starts[i] * 3;
+        const to = starts[i + 1] * 3;
+        hulls.push(all.subarray(from, to));
+    }
+    return hulls;
+}