@driftengine/assets 3.61.0

package/dist/drftTextures.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A loaded asset's textures, addressed by name. One responsibility: which image is which.
+ *
+ * **A caller must never hold a texture index.** An index is a position in whatever order a
+ * reader met its records, which is an accident of parsing rather than anything the asset
+ * promised, and code holding one is coupled to a decision nobody meant to publish. Reorder
+ * the source, re-export it, or regroup the meshes for drawing, and the index still resolves
+ * — to the wrong surface, with no error anywhere. That is the failure this exists to remove.
+ *
+ * So a consumer says `set('Tire_05_DM.jpg', bitmap)` and an unknown name **throws at the
+ * call**, naming what it has. Failing loudly at the moment of the mistake is the whole
+ * difference from an index, which fails silently at some later frame.
+ *
+ * Names come from `TEXS`, which stores what the source called each image. Matching is on the
+ * basename as well as the full declared path, because a material may name
+ * `textures\Tire_05_DM.jpg` while a person reasonably says `Tire_05_DM.jpg`, and requiring
+ * the exact original spelling would put the ordinal problem back with extra steps.
+ */
+import type { DrftTexture } from '@driftengine/drft';
+/**
+ * Whatever a consumer creates from a decoded texture, kept as it was handed over.
+ *
+ * Generic because this module must not know what a GPU texture is: `src/asset/` describes
+ * files and `src/render/` owns the context. A caller parameterises this with its own handle
+ * and gets its own type back.
+ */
+/**
+ * How each of an asset's images should be sampled, decided from what its materials call them.
+ *
+ * **A colour map and a data map need opposite treatment and the container does not say which is
+ * which** — it says only that material *n* names image *k* as its albedo, or its ORM, or its
+ * normal. So the roles are read off the materials, and an image nothing names falls to `linear`,
+ * which is the harmless answer for an image nothing samples.
+ *
+ * `srgb` for a base colour and an emissive map: glTF specifies both as sRGB-encoded, and handing
+ * those bytes to a shader undecoded treats display values as light — mid-tones arrive far brighter
+ * than the author's, and it stays invisible until an output transform washes the surface out.
+ *
+ * `linear` for a normal or ORM map, whose numbers *are* the data. Decoding a direction or a
+ * roughness as though it were a colour bends every one of them toward its floor.
+ *
+ * **A conflict resolves to `linear`.** An image named as a colour map by one material and as a
+ * data map by another is a file nobody meant to write, and of the two ways to be wrong this is the
+ * milder: an sRGB-decoded ORM map bends roughness and metallic toward zero and turns the surface
+ * to polished chrome, where an undecoded colour map is merely pale.
+ */
+export declare function textureColorSpaces(materials: readonly {
+    readonly albedo: number;
+    readonly normalMap: number;
+    readonly ormMap: number;
+    readonly emissiveMap: number;
+}[], count: number): ('srgb' | 'linear')[];
+export declare class TextureSet<T> {
+    private readonly byName;
+    /**
+     * By the texture's index **in the file**, with a gap where one did not decode.
+     *
+     * Sparse on purpose. A material stores the index the file gave its map, so packing the
+     * successes together would shift every texture after a failed one and repaint the model
+     * with its neighbours' images. That is the ordinal hazard this class exists to remove,
+     * reappearing inside the thing removing it, which is exactly where it would be missed.
+     */
+    private readonly byIndex;
+    /**
+     * Build the lookup as the textures are created, in file order.
+     *
+     * `create` returning null means that image could not be decoded, which is survivable: the
+     * surface draws untextured and the slot stays addressable, so a later `replace` can still
+     * put something there. Dropping the entry instead would renumber everything after it.
+     */
+    static from<T>(textures: readonly DrftTexture[], create: (texture: DrftTexture, at: number) => T | null): TextureSet<T>;
+    /** How many textures were created, which is not the number the file carried. */
+    get size(): number;
+    /** Every created texture, for disposal rather than for addressing. */
+    all(): readonly T[];
+    /** The texture a material named, by its index in the file, or null. */
+    at(index: number): T | null;
+    /** Whether a name resolves, for a caller that wants to ask rather than to handle a throw. */
+    has(name: string): boolean;
+    /**
+     * The texture called this, or a refusal naming every texture the asset does have.
+     *
+     * Throwing beats returning null. A caller asking by name has a specific image in mind, and
+     * a null it forgets to check is the silent-wrong-surface failure that indices already had.
+     */
+    get(name: string): T;
+}

package/dist/drftTextures.js

@@ -0,0 +1,138 @@
+/**
+ * A loaded asset's textures, addressed by name. One responsibility: which image is which.
+ *
+ * **A caller must never hold a texture index.** An index is a position in whatever order a
+ * reader met its records, which is an accident of parsing rather than anything the asset
+ * promised, and code holding one is coupled to a decision nobody meant to publish. Reorder
+ * the source, re-export it, or regroup the meshes for drawing, and the index still resolves
+ * — to the wrong surface, with no error anywhere. That is the failure this exists to remove.
+ *
+ * So a consumer says `set('Tire_05_DM.jpg', bitmap)` and an unknown name **throws at the
+ * call**, naming what it has. Failing loudly at the moment of the mistake is the whole
+ * difference from an index, which fails silently at some later frame.
+ *
+ * Names come from `TEXS`, which stores what the source called each image. Matching is on the
+ * basename as well as the full declared path, because a material may name
+ * `textures\Tire_05_DM.jpg` while a person reasonably says `Tire_05_DM.jpg`, and requiring
+ * the exact original spelling would put the ordinal problem back with extra steps.
+ */
+import { basenameOf } from './assetPath.js';
+import { DrftError } from '@driftengine/drft';
+/**
+ * Whatever a consumer creates from a decoded texture, kept as it was handed over.
+ *
+ * Generic because this module must not know what a GPU texture is: `src/asset/` describes
+ * files and `src/render/` owns the context. A caller parameterises this with its own handle
+ * and gets its own type back.
+ */
+/**
+ * How each of an asset's images should be sampled, decided from what its materials call them.
+ *
+ * **A colour map and a data map need opposite treatment and the container does not say which is
+ * which** — it says only that material *n* names image *k* as its albedo, or its ORM, or its
+ * normal. So the roles are read off the materials, and an image nothing names falls to `linear`,
+ * which is the harmless answer for an image nothing samples.
+ *
+ * `srgb` for a base colour and an emissive map: glTF specifies both as sRGB-encoded, and handing
+ * those bytes to a shader undecoded treats display values as light — mid-tones arrive far brighter
+ * than the author's, and it stays invisible until an output transform washes the surface out.
+ *
+ * `linear` for a normal or ORM map, whose numbers *are* the data. Decoding a direction or a
+ * roughness as though it were a colour bends every one of them toward its floor.
+ *
+ * **A conflict resolves to `linear`.** An image named as a colour map by one material and as a
+ * data map by another is a file nobody meant to write, and of the two ways to be wrong this is the
+ * milder: an sRGB-decoded ORM map bends roughness and metallic toward zero and turns the surface
+ * to polished chrome, where an undecoded colour map is merely pale.
+ */
+export function textureColorSpaces(materials, count) {
+    const colour = new Set();
+    const data = new Set();
+    for (const material of materials) {
+        if (material.albedo >= 0)
+            colour.add(material.albedo);
+        if (material.emissiveMap >= 0)
+            colour.add(material.emissiveMap);
+        if (material.normalMap >= 0)
+            data.add(material.normalMap);
+        if (material.ormMap >= 0)
+            data.add(material.ormMap);
+    }
+    const out = [];
+    for (let at = 0; at < count; at++) {
+        out.push(colour.has(at) && !data.has(at) ? 'srgb' : 'linear');
+    }
+    return out;
+}
+export class TextureSet {
+    byName = new Map();
+    /**
+     * By the texture's index **in the file**, with a gap where one did not decode.
+     *
+     * Sparse on purpose. A material stores the index the file gave its map, so packing the
+     * successes together would shift every texture after a failed one and repaint the model
+     * with its neighbours' images. That is the ordinal hazard this class exists to remove,
+     * reappearing inside the thing removing it, which is exactly where it would be missed.
+     */
+    byIndex = [];
+    /**
+     * Build the lookup as the textures are created, in file order.
+     *
+     * `create` returning null means that image could not be decoded, which is survivable: the
+     * surface draws untextured and the slot stays addressable, so a later `replace` can still
+     * put something there. Dropping the entry instead would renumber everything after it.
+     */
+    static from(textures, create) {
+        const set = new TextureSet();
+        for (let at = 0; at < textures.length; at++) {
+            const texture = textures[at];
+            if (texture === undefined)
+                continue;
+            const made = create(texture, at);
+            /* The slot is kept either way, so the indices materials carry stay true. */
+            set.byIndex[at] = made;
+            if (made === null)
+                continue;
+            /*
+             * Both spellings, so a caller may use either. The full path wins a collision because
+             * it is what the file actually said; a basename is a convenience over it.
+             */
+            const base = basenameOf(texture.name);
+            if (base !== '' && !set.byName.has(base))
+                set.byName.set(base, made);
+            if (texture.name !== '')
+                set.byName.set(texture.name, made);
+        }
+        return set;
+    }
+    /** How many textures were created, which is not the number the file carried. */
+    get size() {
+        return this.byIndex.filter((t) => t !== null).length;
+    }
+    /** Every created texture, for disposal rather than for addressing. */
+    all() {
+        return this.byIndex.filter((t) => t !== null);
+    }
+    /** The texture a material named, by its index in the file, or null. */
+    at(index) {
+        return index >= 0 ? (this.byIndex[index] ?? null) : null;
+    }
+    /** Whether a name resolves, for a caller that wants to ask rather than to handle a throw. */
+    has(name) {
+        return this.byName.has(name) || this.byName.has(basenameOf(name));
+    }
+    /**
+     * The texture called this, or a refusal naming every texture the asset does have.
+     *
+     * Throwing beats returning null. A caller asking by name has a specific image in mind, and
+     * a null it forgets to check is the silent-wrong-surface failure that indices already had.
+     */
+    get(name) {
+        const found = this.byName.get(name) ?? this.byName.get(basenameOf(name));
+        if (found === undefined) {
+            const known = [...this.byName.keys()].join(', ');
+            throw new DrftError(`no texture called "${name}" in this asset. It carries: ${known === '' ? 'none' : known}`);
+        }
+        return found;
+    }
+}

package/dist/fbx.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Binary FBX → `MeshData`. Tier 2: a real attempt, and explicitly not a guarantee.
+ *
+ * FBX is what an asset store hands you as the source, so reading it removes a round trip
+ * through an export dialog for the common case. The obstacle was never the format — it is
+ * Autodesk's *SDK licence*, and nothing here uses or ships any of it. The binary container
+ * is a self-describing tree of typed records, which is why a reader can be written against
+ * it at all.
+ *
+ * **Inflate is injected.** Array properties are usually deflate-compressed, and the only
+ * decompressor available without a dependency is Node's `zlib` — which must not be
+ * imported here, because this file is part of an engine that runs in a browser. So the
+ * caller supplies one. The baker passes `zlib.inflateSync`; a browser could pass
+ * `DecompressionStream`. Neither is this module's business.
+ *
+ * What it reads: geometry, its normals and UVs, and per-model transforms. What it refuses:
+ * anything it cannot understand, by name. It never returns the part of a scene it managed
+ * — a model with holes in it is a worse outcome than an error, because the error says what
+ * to do next.
+ *
+ * **It reports orientation and does not apply it.** The file's declared up axis comes back
+ * as `declaredUp`, and standing the asset up is `orient.ts`, one implementation shared by
+ * every format. That split is deliberate: a reader that quietly corrected its own files
+ * would make this format's habits into the engine's defaults, and the next reader would be
+ * written to match those rather than its own specification.
+ */
+import type { MeshData } from '@driftengine/drft';
+import type { UpAxis } from './orient.ts';
+import type { DrftMaterial } from '@driftengine/drft';
+import type { AssetReference } from './assetPath.ts';
+import type { AnimationClip, DrftSkin } from '@driftengine/drft';
+/** Turn a deflate stream into bytes. Supplied by the caller; see the note above. */
+export type Inflate = (compressed: Uint8Array, expectedBytes: number) => Uint8Array;
+/** A node in the FBX record tree. */
+export interface FbxNode {
+    name: string;
+    properties: unknown[];
+    children: FbxNode[];
+}
+/** Parse the record tree. Structure only — nothing here knows what a mesh is. */
+export declare function parseFbxTree(buffer: ArrayBuffer, inflate: Inflate): {
+    root: FbxNode;
+    version: number;
+};
+/**
+ * Geometry out of a parsed tree, one `MeshData` per `Geometry` record.
+ *
+ * FBX stores polygons of any size as a flat index list where a **negative index marks the
+ * last corner of a polygon**, encoded as its bitwise complement. Triangulating as a fan is
+ * correct for the convex polygons these files contain and is what every other reader does.
+ *
+ * Normals and UVs arrive as layer elements with their own mapping and reference modes, and
+ * the combination decides how to look a value up. Getting that wrong does not fail — it
+ * shades the model wrongly — so each supported combination is handled explicitly and an
+ * unsupported one is named rather than approximated.
+ */
+export declare function fbxToMeshes(buffer: ArrayBuffer, inflate: Inflate): {
+    meshes: MeshData[];
+    warnings: string[];
+    version: number;
+    declaredUp: UpAxis;
+    /**
+     * Parallel to `meshes`: the surface each one wears, including which texture colours it.
+     *
+     * A parallel array rather than a field on `MeshData`, because `MeshData` is the engine's
+     * own vertex data and a texture *reference* is a fact about a file that has not been
+     * resolved yet. Folding an unresolved path into the thing the renderer uploads would put a
+     * bake-time concern inside a runtime type.
+     */
+    materials: DrftMaterial[];
+    /** Textures the file names, with bytes where it embedded them itself. */
+    textures: AssetReference[];
+    /**
+     * The rig, where the file carries one. Empty for the static meshes this reader began with.
+     *
+     * **A skinned geometry keeps its vertices in the space its own file put them in**, and does not
+     * take the model's world transform the way a static one does. That is not an omission: a
+     * cluster's bind matrices already carry where the mesh was, so applying the transform as well
+     * places the character twice — which throws the rig across the scene rather than shifting it,
+     * and is the same rule the glTF reader states for a skinned primitive.
+     */
+    skins: DrftSkin[];
+    clips: AnimationClip[];
+    /** Metres per source unit, which this format states. See `unitScaleOf`. */
+    unitScale: number;
+};