@driftengine/assets 3.61.0

package/dist/index.js

@@ -0,0 +1,132 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Reading a model, and getting it onto the GPU.
+ *
+ * Separate from `@driftengine/drft` because these need a renderer: the loader uploads, and
+ * the readers exist to produce something the loader can upload. A procedurally generated
+ * world imports none of this and pays for none of it.
+ */
+/*
+ * And the whole load as one object: streamed, uploaded within a per-frame budget, faded in, and
+ * merged down to one draw per material at the end. What it reports is *phases as data* — a
+ * consumer writes the words, because what to call a stage is a decision about an audience.
+ */
+export { DrftLoader } from './drftLoader.js';
+/*
+ * The loader's own draw-call grouping, exported because a consumer counting draws needs it and was
+ * keeping a copy that could not be kept in step. See `drawKey.ts`.
+ */
+export { drawKeyOf, resolveDrawGrouping } from './drawKey.js';
+/* Addressing a texture by name, so a consumer never holds an ordinal. */
+export { TextureSet, textureColorSpaces } from './drftTextures.js';
+export { assetCandidates, basenameOf } from './assetPath.js';
+/* An image identified from its own header, because a declared mime type is optional in glTF
+   and wrong often enough that reading the bytes is the only reliable answer. */
+export { describeImage } from './imageInfo.js';
+export { readGlb, gltfToMeshes } from './gltf.js';
+export { parseObj, parseMtl } from './obj.js';
+export { parseStl } from './stl.js';
+/*
+ * Radiance RGBE, for an environment a scene did not photograph.
+ *
+ * Opt-in on exactly the terms SDF text is: a consumer that never loads an environment never
+ * imports this, ships none of it, and the engine still carries no image of its own. That is what
+ * keeps the zero-texture-files rule met on its own terms rather than waived.
+ */
+export { readRadianceHdr } from './radianceHdr.js';
+/* IESNA LM-63, on the same opt-in terms: a consumer that loads no profile ships no parser. */
+export { readIesProfile } from './iesPhotometry.js';
+/*
+ * The zip-container formats and the recognise-only tier, exported for the same reason as
+ * the readers above: every one of them is pure, takes its decompressor as a parameter and
+ * touches no filesystem, so a consumer that wants to open a dropped file in a worker can.
+ * See docs/FORMAT.md §3.3 for what that costs and why it is not the default.
+ */
+export { parseUsda, usdzToMeshes } from './usd.js';
+export { parseThreeMfModel, threeMfToMeshes } from './threemf.js';
+export { readZip, findEntry } from './zip.js';
+export { recognise, describeRecognised } from './recognise.js';
+export { fbxToMeshes } from './fbx.js';
+/*
+ * One dispatcher from a file to meshes, so a browser and the baker cannot disagree about which
+ * reader a `.glb` needs. Every capability it may want is a parameter: the filesystem, the two
+ * decompressors and the resolution of a name a file states are all the caller's to supply.
+ */
+export { readModel, readerFor, extensionOf, MODEL_FORMATS } from './readModel.js';
+/*
+ * The browser's decompressor, and the two-pass trick that makes an async one usable by a
+ * synchronous parser. `DecompressionStream` is all a page has and it only works as a stream, so
+ * every compressed span is recorded on one walk, expanded concurrently, and looked up on the
+ * next. See `fbxInflate.ts` for why neither making the reader async nor shipping a DEFLATE
+ * implementation was the answer.
+ */
+export { browserInflate, browserInflateRaw, prepareFbxInflate, prepareZipInflate, } from './fbxInflate.js';
+/*
+ * Turning what a reader produced into what the GPU wants: one vertex per distinct corner, and
+ * no array holding one repeated number. An importer emits a vertex per triangle corner, which
+ * on a real asset is roughly six times more than the model has.
+ */
+export { weldMesh, dropDefaultAttributes } from './weld.js';
+/*
+ * The frame is derived after the weld and not inside a reader, for the reason `tangentOrder.ts`
+ * measures: a soup carrying a frame per corner has nothing left to merge.
+ */
+export { deriveTangentsFor } from './tangentOrder.js';
+/*
+ * One coarse mesh standing in for a whole asset, so a load can open on an outline rather than on
+ * nothing. Baked, because a coarse model has to exist as geometry before it can be drawn, and
+ * built for the whole subject at once: a decimated body reads as a car, 187 coarse parts do not.
+ */
+export { buildCoarseLevel, isOutlineWorthWriting, DEFAULT_COARSE_CELLS } from './coarseLevel.js';
+/*
+ * Which way is up, applied as one format-agnostic turn on the shared intermediate. Told rather
+ * than guessed: every rule for measuring it from the geometry is wrong on something ordinary,
+ * and guessing is what put a car upside down and reported it as verified.
+ */
+export { orientMeshes, parseUpAxis, describeUpAxis } from './orient.js';
+/* Skins and clips out of a glTF document. See the module for why it is not part of `gltf.ts`. */
+export { readGltfSkins } from './gltfSkin.js';
+/*
+ * The tier 2 vehicle-container reader is deliberately **not** re-exported here.
+ *
+ * The barrel is the documented public surface, and `readModel` is how every format in this
+ * directory is meant to be reached: it dispatches by content, applies the orientation and
+ * handedness the file declared, and returns one shape whichever reader answered. Exporting a
+ * single format's entry point would document a second way in that no consumer needs, and this
+ * one has a further reason to stay behind the dispatcher. `scripts/kn5-check.mjs` imports the
+ * module directly, which is what an in-repo probe is for.
+ */
+/*
+ * The mirror an up-axis rotation deliberately cannot express, kept beside the rotations so the
+ * next left-handed format gets the same conversion instead of writing its own.
+ */
+export { convertHandedness } from './orient.js';
+/*
+ * The hierarchy's half of the up-axis turn. Kept beside `orientMeshes` because calling one
+ * without the other leaves a file whose graph and geometry disagree about where every part is.
+ */
+export { orientNodes } from './orient.js';
+/*
+ * And the hierarchy's half of a mirror, which is the same pairing one step further out: a format
+ * that declares itself left-handed gets `convertHandedness` over its meshes and this over its
+ * graph, or the two desynchronise while each stays individually well formed.
+ */
+export { mirrorNodes } from './orient.js';
+/*
+ * **World-space meshes into parts a consumer can turn, and `docs/HANDBOOK.md` §10.1 has told
+ * people to import it from here since it was written.** It was not exported, so the one consumer
+ * that followed the handbook reached the module by sub-path — the exception this repository
+ * reserves for the chemistry library — and `scripts/docs.test.mjs` now checks every import the
+ * documentation prints against the barrel it names.
+ */
+export { localiseNodes } from './localise.js';
+/*
+ * The collision hull a vehicle folder ships beside its model, found by convention so a consumer
+ * does not have to know the convention.
+ */
+export { colliderBeside, levelsBeside } from './readModel.js';
+/*
+ * DDS block decoding, for the block-compressed textures a vehicle model carries. Baker work: RGBA
+ * is larger than the source and nothing ships a block decoder into a frame.
+ */
+export { ddsToRgba, isDds } from './dds.js';

package/dist/kn5.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Assetto Corsa's `.kn5`. Tier 2: a real attempt, and explicitly not a guarantee.
+ *
+ * The format has no published specification. What is implemented here was verified against three
+ * files from a production car mod, each of which parses to *exact EOF* — a binary walk that
+ * consumes a 44 MB file to its last byte has no field misread anywhere in it, because a single
+ * wrong width desynchronises everything after it. That is the evidence this reader rests on, and
+ * `scripts/kn5-check.mjs` re-establishes it on demand.
+ *
+ * **It needs nothing from its host.** A `.kn5` embeds every texture it uses, so unlike a `.gltf`
+ * naming external buffers or an `.fbx` storing deflated arrays, there is no capability to inject
+ * and no sidecar to resolve. It is the one binary format here that reads from bytes alone.
+ *
+ * It reports what the file says and corrects none of it: the frame comes back as `declaredHand`
+ * and `orient.ts` is what would transform it, for the same reason every other reader here reports
+ * `declaredUp` instead of standing its own models up.
+ */
+import type { DrftMaterial, DrftNode, MeshData } from '@driftengine/drft';
+import type { AssetReference } from './assetPath.ts';
+import type { Handedness, UpAxis } from './orient.ts';
+/** A texture the file carried inline. Every `.kn5` texture is inline; none are named only. */
+export interface Kn5Texture {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+/** One entry of the shared material palette, as the file states it. */
+export interface Kn5Material {
+    readonly name: string;
+    readonly shader: string;
+    /**
+     * 0 opaque, 1 alpha blended, 2 alpha to coverage. **The file's own statement about the pass.**
+     *
+     * Read where the walk previously skipped two bytes it called "the flags". Measured across a
+     * shipped car and its three levels of detail plus its collider, it takes only the values the
+     * format defines — 61 and 9 in the full model, 33/6, 26/3, 16/2, and one opaque collider — and
+     * it agrees with the *node's* transparency flag on 171 of 172 meshes, which is the cross-check
+     * that says the field is being read and not merely decoded.
+     */
+    readonly blendMode: number;
+    /** Whether `ksAlphaRef` is a live alpha test. Zero in every file measured here. */
+    readonly alphaTested: boolean;
+    /** `ksDiffuse`, `ksSpecularEXP`, `ksAlphaRef` and the rest, unmapped. */
+    readonly props: ReadonlyMap<string, number>;
+    /** Sampler name to texture name: `txDiffuse`, `txNormal`, `txMaps`, `txDetail`. */
+    readonly textures: ReadonlyMap<string, string>;
+}
+/** `Kn5Material.blendMode` when the surface belongs in the blended pass. */
+export declare const KN5_ALPHA_BLEND = 1;
+/**
+ * A position in the file that refuses instead of running off the end.
+ *
+ * Every read goes through here so that a malformed file fails with an offset somebody can look
+ * at, which is the whole difference between a tier 2 refusal and a parser crash.
+ */
+export declare class Cursor {
+    readonly view: DataView;
+    readonly bytes: Uint8Array;
+    at: number;
+    constructor(buffer: ArrayBuffer);
+    /** Refuses when `count` bytes are not there, naming where it ran out. */
+    need(count: number, what: string): void;
+    i32(what?: string): number;
+    u32(what?: string): number;
+    f32(what?: string): number;
+    u16(what?: string): number;
+    u8(what?: string): number;
+    skip(count: number, what: string): void;
+    take(count: number, what: string): Uint8Array;
+    /** i32 length, then that many UTF-8 bytes. */
+    str(what?: string): string;
+}
+/** What the file says before its node tree begins. */
+export interface Kn5Header {
+    readonly version: number;
+    readonly textures: Kn5Texture[];
+    readonly materials: Kn5Material[];
+    /** Where the node tree starts, so the caller carries on from here. */
+    readonly cursor: Cursor;
+}
+/**
+ * The magic, the version, the texture block and the material palette.
+ *
+ * Split from the node walk because it is the half that is pure data: no recursion, no transforms,
+ * and nothing that needs a `MeshData` to exist.
+ */
+export declare function readKn5Header(buffer: ArrayBuffer): Kn5Header;
+/**
+ * One node of the file's own graph.
+ *
+ * `matrix` is the node's **local** transform, row-major with the translation in row 3, which is
+ * the row-vector convention the format inherits from DirectX. The world matrix is not stored
+ * here: it is accumulated during the walk and applied to the geometry, because `MESH` is
+ * world-space by the rule in the design's §5.1.
+ */
+export interface Kn5Node {
+    readonly type: number;
+    readonly name: string;
+    readonly parent: number;
+    readonly matrix: Float32Array;
+    /** Index into the returned meshes, or -1 for a node that draws nothing. */
+    readonly mesh: number;
+    readonly castShadows: boolean;
+    readonly isVisible: boolean;
+    /** The author's own statement that this surface belongs in the blended pass. */
+    readonly isTransparent: boolean;
+    /** Zero in every car measured; non-zero in track models. Carried, never relied upon. */
+    readonly lodIn: number;
+    readonly lodOut: number;
+}
+/** Geometry as the file stores it, already carried into world space. */
+export interface Kn5Mesh {
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly uvs: Float32Array;
+    readonly tangents: Float32Array;
+    readonly indices: Uint32Array;
+    /** Index into the material palette from `readKn5Header`. */
+    readonly material: number;
+    /** Index into the returned nodes, so a mesh can name the node that placed it. */
+    readonly node: number;
+}
+/**
+ * Walk the node tree depth first, which is the order the file stores it in.
+ *
+ * **Every node is kept, including the `AC_`-prefixed ones.** The community converter skips them,
+ * correctly for its purpose, since they carry no geometry an OBJ can hold. They are placement
+ * anchors and convention markers, and this reader exists to preserve exactly that.
+ */
+export declare function readKn5Nodes(header: Kn5Header): {
+    nodes: Kn5Node[];
+    meshes: Kn5Mesh[];
+};
+/** What a `.kn5` yields, in the shape every other reader in this directory returns. */
+export interface Kn5Import {
+    meshes: MeshData[];
+    materials: DrftMaterial[];
+    textures: AssetReference[];
+    nodes: Kn5Node[];
+    warnings: string[];
+    declaredUp: UpAxis;
+    declaredHand: Handedness;
+}
+/**
+ * Read a `.kn5` into meshes, materials and the hierarchy that placed them.
+ *
+ * Materials are duplicated per mesh because `MATL` is parallel to `MESH` by ordinal while `.kn5`
+ * addresses a shared palette — 70 entries against 172 meshes in the car this was built against.
+ * The palette entry keeps its name, so nothing is lost by the duplication.
+ */
+export declare function kn5ToMeshes(buffer: ArrayBuffer): Kn5Import;
+/**
+ * Decompose each node's row-vector 4x4 into the translation, rotation and scale `DrftNode` holds.
+ *
+ * The container stores a hierarchy as TRS and not as a matrix, which is what lets a consumer
+ * animate one channel without disturbing the other two — a wheel spins about its own axis while
+ * its suspension travel writes only the translation.
+ */
+export declare function toDrftNodes(nodes: readonly Kn5Node[]): DrftNode[];