@blamnetwork/blf 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,82 @@
+# @Blam-Network/blf
+
+[![npm](https://img.shields.io/npm/v/@Blam-Network/blf)](https://www.npmjs.com/package/@Blam-Network/blf)
+
+TypeScript library for reading and writing Halo **BLF** (binary layout file) chunks — Reach, Halo 3, and Halo 3: ODST builds.
+
+Built on [@craftycodie/cstruct](https://www.npmjs.com/package/@craftycodie/cstruct) for packed struct layouts and a Halo-style **bitstream** for custom chunk bodies.
+
+## Features
+
+- Chunk discovery with `search_for_chunk` and `find_chunk`
+- Per-game **version bundles** (`haloreach/*`, `halo3/*`, `halo3odst/*`) with chunk classes and blam types for a specific exe build
+- Struct-backed chunks via `CStructBLFChunk` and `@blf.chunk` decorators (compiled away in published `dist/`)
+- Bitstream reader/writer exported from the package root
+- Little- and big-endian BLF headers
+
+## Install
+
+```bash
+npm install @Blam-Network/blf @craftycodie/cstruct
+```
+
+Consumers import from published **`dist/`** exports only. Decorators are lowered at build time — **you do not need `experimentalDecorators`** to use exported chunk classes.
+
+## Usage
+
+### Find and read chunks
+
+```ts
+import { readFileSync } from "node:fs";
+import { search_for_chunk } from "@Blam-Network/blf";
+import {
+  s_blf_chunk_content_header,
+  s_blf_chunk_game_variant,
+} from "@Blam-Network/blf/haloreach/v12065_11_08_24_1738_tu1actual";
+
+const file = new Uint8Array(readFileSync("map.blf"));
+
+const chdr = new s_blf_chunk_content_header();
+search_for_chunk(file, chdr, "big");
+
+const mpvr = new s_blf_chunk_game_variant();
+search_for_chunk(file, mpvr, "big");
+```
+
+### Bitstream (root export only)
+
+```ts
+import { bitstream } from "@Blam-Network/blf";
+
+const reader = new bitstream.BitstreamReader(buffer, "little");
+const mode = reader.read_enum("game-mode", 4, e_game_mode);
+```
+
+### Game build subpaths
+
+Each implementation build is a single module:
+
+| Import | Build |
+|--------|--------|
+| `@Blam-Network/blf/haloreach/v12065_11_08_24_1738_tu1actual` | Reach TU1 |
+| `@Blam-Network/blf/halo3/v12070_08_09_05_2031_halo3_ship` | Halo 3 ship |
+| `@Blam-Network/blf/halo3odst/v13895_09_04_27_2201_atlas_release` | ODST Atlas |
+
+Add a build by creating `src/versions/<game>/<build_id>.ts` and re-exporting its chunks — wildcard `exports` in `package.json` pick it up automatically.
+
+## Development
+
+From `blf-ts/`:
+
+```bash
+npm install
+npm run validate   # lint, test, typecheck
+npm run build
+npm run release    # bump version, tag, push (CI publishes on tag)
+```
+
+Chunk authoring (forking the library) uses Stage 3 decorators (`@blf.chunk`, `@c.struct`) with the same SWC/Vitest setup as the repo. Decorator order: `@blf.chunk` on the class, `@c.struct` below, `@c.field` on properties.
+
+## License
+
+MIT

package/dist/bitstream/enum.d.ts

@@ -0,0 +1,6 @@
+/** TypeScript numeric enum object passed to {@link c_bitstream_reader.read_enum}. */
+export type NumericEnum = Record<string, number | string>;
+export type EnumNumber<E extends NumericEnum> = Extract<E[keyof E], number>;
+export declare function isNumericEnumValue(enumObj: NumericEnum, value: number): boolean;
+export declare function assertFitsInBits(name: string, value: number, size_in_bits: number): void;
+//# sourceMappingURL=enum.d.ts.map

package/dist/bitstream/enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum.d.ts","sourceRoot":"","sources":["../../src/bitstream/enum.ts"],"names":[],"mappings":"AAEA,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE1D,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAE5E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,IAAI,CAON"}

package/dist/bitstream/enum.js

@@ -0,0 +1,15 @@
+import { BitstreamError } from "./errors";
+export function isNumericEnumValue(enumObj, value) {
+    for (const member of Object.values(enumObj)) {
+        if (typeof member === "number" && member === value) {
+            return true;
+        }
+    }
+    return false;
+}
+export function assertFitsInBits(name, value, size_in_bits) {
+    const max = (1 << size_in_bits) - 1;
+    if (value < 0 || value > max) {
+        throw new BitstreamError(`Value ${value} for ${name} does not fit in ${size_in_bits} bits (max ${max})`);
+    }
+}

package/dist/bitstream/enums.d.ts

@@ -0,0 +1,21 @@
+export declare enum e_bitstream_byte_order {
+    _bitstream_byte_order_little_endian = 0,
+    _bitstream_byte_order_big_endian = 1
+}
+export declare namespace e_bitstream_byte_order {
+    function swap(order: e_bitstream_byte_order): e_bitstream_byte_order;
+}
+export declare enum e_bitstream_byte_fill_direction {
+    _bitstream_byte_fill_direction_msb_to_lsb = 0,
+    _bitstream_byte_fill_direction_lsb_to_msb = 1
+}
+export declare enum e_bitstream_state {
+    _bitstream_state_initial = 0,
+    _bitstream_state_writing = 1,
+    _bitstream_state_write_finished = 2,
+    _bitstream_state_reading = 3,
+    _bitstream_state_read_only_for_consistency = 4,
+    _bitstream_state_read_finished = 5,
+    k_bitstream_state_count = 6
+}
+//# sourceMappingURL=enums.d.ts.map

package/dist/bitstream/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/bitstream/enums.ts"],"names":[],"mappings":"AAAA,oBAAY,sBAAsB;IAChC,mCAAmC,IAAI;IACvC,gCAAgC,IAAI;CACrC;AAED,yBAAiB,sBAAsB,CAAC;IACtC,SAAgB,IAAI,CAAC,KAAK,EAAE,sBAAsB,GAAG,sBAAsB,CAO1E;CACF;AAED,oBAAY,+BAA+B;IACzC,yCAAyC,IAAI;IAC7C,yCAAyC,IAAI;CAC9C;AAED,oBAAY,iBAAiB;IAC3B,wBAAwB,IAAI;IAC5B,wBAAwB,IAAI;IAC5B,+BAA+B,IAAI;IACnC,wBAAwB,IAAI;IAC5B,0CAA0C,IAAI;IAC9C,8BAA8B,IAAI;IAElC,uBAAuB,IAAI;CAC5B"}

package/dist/bitstream/enums.js

@@ -0,0 +1,31 @@
+export var e_bitstream_byte_order;
+(function (e_bitstream_byte_order) {
+    e_bitstream_byte_order[e_bitstream_byte_order["_bitstream_byte_order_little_endian"] = 0] = "_bitstream_byte_order_little_endian";
+    e_bitstream_byte_order[e_bitstream_byte_order["_bitstream_byte_order_big_endian"] = 1] = "_bitstream_byte_order_big_endian";
+})(e_bitstream_byte_order || (e_bitstream_byte_order = {}));
+(function (e_bitstream_byte_order) {
+    function swap(order) {
+        switch (order) {
+            case e_bitstream_byte_order._bitstream_byte_order_little_endian:
+                return e_bitstream_byte_order._bitstream_byte_order_big_endian;
+            case e_bitstream_byte_order._bitstream_byte_order_big_endian:
+                return e_bitstream_byte_order._bitstream_byte_order_little_endian;
+        }
+    }
+    e_bitstream_byte_order.swap = swap;
+})(e_bitstream_byte_order || (e_bitstream_byte_order = {}));
+export var e_bitstream_byte_fill_direction;
+(function (e_bitstream_byte_fill_direction) {
+    e_bitstream_byte_fill_direction[e_bitstream_byte_fill_direction["_bitstream_byte_fill_direction_msb_to_lsb"] = 0] = "_bitstream_byte_fill_direction_msb_to_lsb";
+    e_bitstream_byte_fill_direction[e_bitstream_byte_fill_direction["_bitstream_byte_fill_direction_lsb_to_msb"] = 1] = "_bitstream_byte_fill_direction_lsb_to_msb";
+})(e_bitstream_byte_fill_direction || (e_bitstream_byte_fill_direction = {}));
+export var e_bitstream_state;
+(function (e_bitstream_state) {
+    e_bitstream_state[e_bitstream_state["_bitstream_state_initial"] = 0] = "_bitstream_state_initial";
+    e_bitstream_state[e_bitstream_state["_bitstream_state_writing"] = 1] = "_bitstream_state_writing";
+    e_bitstream_state[e_bitstream_state["_bitstream_state_write_finished"] = 2] = "_bitstream_state_write_finished";
+    e_bitstream_state[e_bitstream_state["_bitstream_state_reading"] = 3] = "_bitstream_state_reading";
+    e_bitstream_state[e_bitstream_state["_bitstream_state_read_only_for_consistency"] = 4] = "_bitstream_state_read_only_for_consistency";
+    e_bitstream_state[e_bitstream_state["_bitstream_state_read_finished"] = 5] = "_bitstream_state_read_finished";
+    e_bitstream_state[e_bitstream_state["k_bitstream_state_count"] = 6] = "k_bitstream_state_count";
+})(e_bitstream_state || (e_bitstream_state = {}));

package/dist/bitstream/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class BitstreamError extends Error {
+    constructor(message: string);
+}
+export declare function assert_ok(condition: unknown, message?: string): asserts condition;
+//# sourceMappingURL=errors.d.ts.map

package/dist/bitstream/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/bitstream/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,SAAS,CACvB,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,CAInB"}

package/dist/bitstream/errors.js

@@ -0,0 +1,11 @@
+export class BitstreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BitstreamError";
+    }
+}
+export function assert_ok(condition, message) {
+    if (!condition) {
+        throw new BitstreamError(message ?? "assert_ok failed");
+    }
+}

package/dist/bitstream/index.d.ts

@@ -0,0 +1,7 @@
+export type { EnumNumber, NumericEnum } from "./enum";
+export { e_bitstream_byte_fill_direction, e_bitstream_byte_order, e_bitstream_state, } from "./enums";
+export { assert_ok, BitstreamError } from "./errors";
+export * from "./math";
+export { c_bitstream_reader } from "./reader";
+export { c_bitstream_writer } from "./writer";
+//# sourceMappingURL=index.d.ts.map

package/dist/bitstream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bitstream/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACrD,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

package/dist/bitstream/index.js

@@ -0,0 +1,5 @@
+export { e_bitstream_byte_fill_direction, e_bitstream_byte_order, e_bitstream_state, } from "./enums";
+export { assert_ok, BitstreamError } from "./errors";
+export * from "./math";
+export { c_bitstream_reader } from "./reader";
+export { c_bitstream_writer } from "./writer";

package/dist/bitstream/math.d.ts

@@ -0,0 +1,28 @@
+export type real_vector3d = {
+    i: number;
+    j: number;
+    k: number;
+};
+export declare const k_real_epsilon = 0.000001;
+export declare const k_pi: number;
+export declare const global_forward3d: real_vector3d;
+export declare const global_left3d: real_vector3d;
+export declare const global_up3d: real_vector3d;
+export declare function real_vector3d_default(): real_vector3d;
+export declare function dot_product3d(a: real_vector3d, b: real_vector3d): number;
+export declare function cross_product3d(a: real_vector3d, b: real_vector3d, out: real_vector3d): void;
+export declare function magnitude3d(v: real_vector3d): number;
+/** Matches blf_lib `quantize_real` for Reach bitstreams. */
+export declare function quantize_real(value: number, min_value: number, max_value: number, quantized_value_count: number, exact_midpoint: boolean, exact_endpoints: boolean): number;
+/** Matches blf_lib `dequantize_real` for Reach bitstreams. */
+export declare function dequantize_real(quantized: number, min_value: number, max_value: number, quantized_value_count: number, exact_midpoints: boolean, exact_endpoints: boolean): number;
+export declare function normalize3d(v: real_vector3d): number;
+export declare function arctangent(y: number, x: number): number;
+export declare function assert_valid_real_normal3d(v: real_vector3d): boolean;
+export declare function valid_real_vector3d_axes2(a: real_vector3d, b: real_vector3d): boolean;
+export declare function valid_real_vector3d_axes3(a: real_vector3d, b: real_vector3d, c: real_vector3d): boolean;
+export declare function rotate_vector_about_axis(vector: real_vector3d, axis: real_vector3d, sine: number, cosine: number): void;
+export declare function axes_compute_reference_internal(up: real_vector3d, forward_reference: real_vector3d, left_reference: real_vector3d): void;
+export declare function axes_to_angle_internal(forward: real_vector3d, up: real_vector3d): number;
+export declare function angle_to_axes_internal(up: real_vector3d, angle: number, forward: real_vector3d): void;
+//# sourceMappingURL=math.d.ts.map

package/dist/bitstream/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/bitstream/math.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAEF,eAAO,MAAM,cAAc,WAAO,CAAC;AACnC,eAAO,MAAM,IAAI,QAAU,CAAC;AAE5B,eAAO,MAAM,gBAAgB,EAAE,aAAoC,CAAC;AACpE,eAAO,MAAM,aAAa,EAAE,aAAoC,CAAC;AACjE,eAAO,MAAM,WAAW,EAAE,aAAoC,CAAC;AAE/D,wBAAgB,qBAAqB,IAAI,aAAa,CAErD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAExE;AAED,wBAAgB,eAAe,CAC7B,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,GAAG,EAAE,aAAa,GACjB,IAAI,CAIN;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEpD;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,qBAAqB,EAAE,MAAM,EAC7B,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,MAAM,CA4BR;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,qBAAqB,EAAE,MAAM,EAC7B,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,OAAO,GACvB,MAAM,CAqBR;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAQpD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAGpE;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAET;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAMT;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,IAAI,CAYN;AAED,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,aAAa,EACjB,iBAAiB,EAAE,aAAa,EAChC,cAAc,EAAE,aAAa,GAC5B,IAAI,CAwBN;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,aAAa,GAChB,MAAM,CAQR;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,IAAI,CAwBN"}

package/dist/bitstream/math.js

@@ -0,0 +1,149 @@
+import { assert_ok } from "./errors";
+export const k_real_epsilon = 1e-6;
+export const k_pi = Math.PI;
+export const global_forward3d = { i: 0, j: 0, k: 1 };
+export const global_left3d = { i: 1, j: 0, k: 0 };
+export const global_up3d = { i: 0, j: 1, k: 0 };
+export function real_vector3d_default() {
+    return { i: 0, j: 0, k: 0 };
+}
+export function dot_product3d(a, b) {
+    return a.i * b.i + a.j * b.j + a.k * b.k;
+}
+export function cross_product3d(a, b, out) {
+    out.i = a.j * b.k - a.k * b.j;
+    out.j = a.k * b.i - a.i * b.k;
+    out.k = a.i * b.j - a.j * b.i;
+}
+export function magnitude3d(v) {
+    return Math.sqrt(dot_product3d(v, v));
+}
+/** Matches blf_lib `quantize_real` for Reach bitstreams. */
+export function quantize_real(value, min_value, max_value, quantized_value_count, exact_midpoint, exact_endpoints) {
+    let adjusted_count = quantized_value_count;
+    if (exact_midpoint) {
+        adjusted_count -= 1;
+    }
+    if (exact_endpoints) {
+        if (value === min_value) {
+            return 0;
+        }
+        if (value === max_value) {
+            return adjusted_count - 1;
+        }
+        const divisor = adjusted_count - 2;
+        const step = (max_value - min_value) / divisor;
+        let temp = Math.floor((value - min_value) / step) + 1;
+        if (temp <= 1) {
+            temp = 1;
+        }
+        return temp > adjusted_count - 2 ? adjusted_count - 2 : temp;
+    }
+    const step = (max_value - min_value) / adjusted_count;
+    let result = Math.floor((value - min_value) / step);
+    if (result > adjusted_count - 1) {
+        result = adjusted_count - 1;
+    }
+    return result;
+}
+/** Matches blf_lib `dequantize_real` for Reach bitstreams. */
+export function dequantize_real(quantized, min_value, max_value, quantized_value_count, exact_midpoints, exact_endpoints) {
+    let value_count = quantized_value_count;
+    if (exact_midpoints) {
+        value_count -= 1;
+    }
+    if (exact_endpoints) {
+        if (quantized === 0) {
+            return min_value;
+        }
+        if (quantized === value_count - 1) {
+            return max_value;
+        }
+        const denom = value_count - 2;
+        const step = (max_value - min_value) / denom;
+        const fquant = quantized - 1;
+        return min_value + step * (fquant + 0.5);
+    }
+    const step = (max_value - min_value) / value_count;
+    return min_value + step * (quantized + 0.5);
+}
+export function normalize3d(v) {
+    const mag = magnitude3d(v);
+    if (mag > k_real_epsilon) {
+        v.i /= mag;
+        v.j /= mag;
+        v.k /= mag;
+    }
+    return mag;
+}
+export function arctangent(y, x) {
+    return Math.atan2(y, x);
+}
+export function assert_valid_real_normal3d(v) {
+    const mag = magnitude3d(v);
+    return Math.abs(mag - 1) <= k_real_epsilon;
+}
+export function valid_real_vector3d_axes2(a, b) {
+    return Math.abs(dot_product3d(a, b)) <= k_real_epsilon;
+}
+export function valid_real_vector3d_axes3(a, b, c) {
+    return (valid_real_vector3d_axes2(a, b) &&
+        valid_real_vector3d_axes2(a, c) &&
+        valid_real_vector3d_axes2(b, c));
+}
+export function rotate_vector_about_axis(vector, axis, sine, cosine) {
+    const cross = { i: 0, j: 0, k: 0 };
+    cross_product3d(axis, vector, cross);
+    const dot = dot_product3d(axis, vector);
+    const one_minus_cosine = 1 - cosine;
+    vector.i =
+        vector.i * cosine + cross.i * sine + axis.i * dot * one_minus_cosine;
+    vector.j =
+        vector.j * cosine + cross.j * sine + axis.j * dot * one_minus_cosine;
+    vector.k =
+        vector.k * cosine + cross.k * sine + axis.k * dot * one_minus_cosine;
+}
+export function axes_compute_reference_internal(up, forward_reference, left_reference) {
+    assert_ok(assert_valid_real_normal3d(up));
+    const v10 = Math.abs(dot_product3d(up, global_forward3d));
+    const v9 = Math.abs(dot_product3d(up, global_left3d));
+    if (v10 >= v9) {
+        cross_product3d(global_left3d, up, forward_reference);
+    }
+    else {
+        cross_product3d(up, global_forward3d, forward_reference);
+    }
+    const forward_magnitude = normalize3d(forward_reference);
+    assert_ok(forward_magnitude > k_real_epsilon, "forward_magnitude>k_real_epsilon");
+    cross_product3d(up, forward_reference, left_reference);
+    const left_magnitude = normalize3d(left_reference);
+    assert_ok(left_magnitude > k_real_epsilon, "left_magnitude>k_real_epsilon");
+    assert_ok(valid_real_vector3d_axes3(forward_reference, left_reference, up));
+}
+export function axes_to_angle_internal(forward, up) {
+    const forward_reference = real_vector3d_default();
+    const left_reference = real_vector3d_default();
+    axes_compute_reference_internal(up, forward_reference, left_reference);
+    return arctangent(dot_product3d(left_reference, forward), dot_product3d(forward_reference, forward));
+}
+export function angle_to_axes_internal(up, angle, forward) {
+    const forward_reference = real_vector3d_default();
+    const left_reference = real_vector3d_default();
+    axes_compute_reference_internal(up, forward_reference, left_reference);
+    forward.i = forward_reference.i;
+    forward.j = forward_reference.j;
+    forward.k = forward_reference.k;
+    let u;
+    let v;
+    if (angle === k_pi || angle === -k_pi) {
+        u = 0;
+        v = -1;
+    }
+    else {
+        u = Math.sin(angle);
+        v = Math.cos(angle);
+    }
+    rotate_vector_about_axis(forward, up, u, v);
+    normalize3d(forward);
+    assert_ok(valid_real_vector3d_axes2(forward, up));
+}

package/dist/bitstream/reader.d.ts

@@ -0,0 +1,81 @@
+import { type EnumNumber, type NumericEnum } from "./enum";
+import { e_bitstream_byte_order } from "./enums";
+import { type real_vector3d } from "./math";
+export declare class c_bitstream_reader {
+    private m_data;
+    private m_data_size_bytes;
+    private m_state;
+    private m_byte_order;
+    private m_packed_byte_order;
+    private m_byte_pack_direction;
+    private m_byte_unpack_direction;
+    private current_stream_bit_position;
+    private current_stream_byte_position;
+    static new(data: Uint8Array, byte_order: e_bitstream_byte_order): c_bitstream_reader;
+    /** Use this when dealing with bitstream data from the Halo 3 Beta or prior. */
+    static new_with_legacy_settings(data: Uint8Array, byte_order: e_bitstream_byte_order): c_bitstream_reader;
+    static new_from_instance(data: Uint8Array, instance: c_bitstream_reader): c_bitstream_reader;
+    private constructor();
+    get_byte_order(): e_bitstream_byte_order;
+    seek_relative(bits: number): void;
+    seek(byte: number): void;
+    seek_bit(byte: number, bit: number): void;
+    get_current_offset(): [number, number];
+    read_raw_data(size_in_bits: number): Uint8Array;
+    read_bool(_name: string): boolean;
+    read_bits_internal(output: Uint8Array, size_in_bits: number): void;
+    /**
+     * Read a numeric enum. Pass the enum object; no per-enum parser required.
+     *
+     * - Default: value must be a declared enum member.
+     * - `{ within_bits: true }`: any value that fits in `size_in_bits` (reserved slots).
+     */
+    read_enum<E extends NumericEnum>(name: string, size_in_bits: number, enumObj: E, options?: {
+        within_bits?: boolean;
+    }): EnumNumber<E>;
+    read_enum<T extends number>(name: string, size_in_bits: number, from_u32: (value: number) => T | undefined): T;
+    read_integer(_name: string, size_in_bits: number): number;
+    read_index(name: string, max: number, size_in_bits: number): number;
+    read_quantized_real(min_value: number, max_value: number, size_in_bits: number, exact_midpoint: boolean, exact_endpoints: boolean): number;
+    read_float(_name: string, size_in_bits: number): number;
+    read_i16(size_in_bits: number): number;
+    read_signed_integer(_name: string, size_in_bits: number): number;
+    read_qword(size_in_bits: number): bigint;
+    read_identifier(_identifier: string): void;
+    read_point3d(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, axis_encoding_size_in_bits: number): void;
+    read_point3d_efficient(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, axis_encoding_size_in_bits: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    read_qword_internal(_size_in_bits: number): bigint;
+    read_secure_address(_address: unknown): void;
+    angle_to_axes_internal(up: real_vector3d, angle: number, forward: real_vector3d): void;
+    read_string(_string: {
+        value: string;
+    }, _max_string_size: number): void;
+    read_string_utf8(max_string_size: number): string;
+    read_string_extended_ascii(max_string_size: number): string;
+    read_string_wchar(max_string_size: number): string;
+    read_unit_vector(_unit_vector: unknown, _size_in_bits: number): void;
+    read_vector(_vector: unknown, _min_value: number, _max_value: number, _step_count_size_in_bits: number, _size_in_bits: number): void;
+    begin_reading(): void;
+    reading(): boolean;
+    finish_reading(): void;
+    get_data(): readonly [Uint8Array, number];
+    private reset;
+    private set_data;
+    private skip;
+    private would_overflow;
+    static axes_compute_reference_internal(up: real_vector3d, forward_reference: real_vector3d, left_reference: real_vector3d): void;
+    private static axes_to_angle_internal;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/bitstream/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/bitstream/reader.ts"],"names":[],"mappings":"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"}