@driftengine/assets 4.2.1 → 4.4.0

package/src/gltf.ts

@@ -17,7 +17,7 @@
  * world matrix on the way through, and the graph does not survive into the engine.
  */
 
-import type { DrftNode, MeshData } from '@driftengine/drft';
+import type { DrftLight, DrftNode, MeshData } from '@driftengine/drft';
 import { DrftError } from '@driftengine/drft';
 import type { DrftMaterial } from '@driftengine/drft';
 import { generateTangents } from '@driftengine/core';
@@ -93,6 +93,7 @@ interface GltfMaterial {
   emissiveFactor?: number[];
   /** `OPAQUE`, `MASK` or `BLEND`. Absent means opaque, which the specification states. */
   alphaMode?: string;
+  doubleSided?: boolean;
   alphaCutoff?: number;
   name?: string;
   /**
@@ -118,6 +119,16 @@ interface GltfImage {
 interface GltfTexture {
   source?: number;
   sampler?: number;
+  /**
+   * Where an image in a newer codec is named. glTF's own `source` is the fallback, and a file that
+   * *requires* the extension usually carries none, so the extension's index is the only route to
+   * the picture.
+   */
+  extensions?: {
+    EXT_texture_webp?: { source?: number };
+    EXT_texture_avif?: { source?: number };
+    KHR_texture_basisu?: { source?: number };
+  };
 }
 interface GltfNode {
   mesh?: number;
@@ -129,6 +140,17 @@ interface GltfNode {
   rotation?: number[];
   scale?: number[];
   name?: string;
+  /** Which of the document's punctual lights hangs on this node. */
+  extensions?: { KHR_lights_punctual?: { light?: number } };
+}
+/** One `KHR_lights_punctual` light, as the extension states it. */
+interface GltfPunctualLight {
+  type?: string;
+  name?: string;
+  color?: number[];
+  intensity?: number;
+  range?: number;
+  spot?: { innerConeAngle?: number; outerConeAngle?: number };
 }
 export interface GltfDocument {
   asset?: { version?: string; generator?: string };
@@ -142,9 +164,14 @@ export interface GltfDocument {
   materials?: GltfMaterial[];
   images?: GltfImage[];
   textures?: GltfTexture[];
+  /** Extensions the file states it cannot be read correctly without. */
+  extensionsRequired?: string[];
+  extensionsUsed?: string[];
   /* Read by `gltfSkin.ts`; ignored entirely by the mesh path, which flattens. */
   skins?: GltfSkinDef[];
   animations?: GltfAnimationDef[];
+  /** The document's own lights, which nodes name by index. */
+  extensions?: { KHR_lights_punctual?: { lights?: GltfPunctualLight[] } };
 }
 
 /** A skin, as glTF declares one. `skeleton` is a hint this reader does not need and ignores. */
@@ -323,6 +350,34 @@ function normalMatrix(m: readonly number[]): number[] {
  * textures may share one image with different samplers. Following the indirection here keeps
  * the material's index meaning what the file said it meant.
  */
+/**
+ * Which image a texture shows: glTF's `source` when there is one, otherwise an image-codec
+ * extension's.
+ *
+ * **The fallback wins when both exist**, because every reader can decode it and the baker
+ * identifies whatever bytes it gets. What that gives up is nothing a bake can use today: a WebP
+ * extension's image is smaller, but nothing here knows the two are the same picture. What would
+ * make it wrong is a baker that decodes AVIF, where the extension's image may be the better source.
+ *
+ * Basis is refused by name: it is a GPU transcoding format, and this engine uploads decoded images.
+ */
+function textureSource(
+  texture: GltfTexture | undefined,
+  index: number,
+  warnings: string[],
+): number | undefined {
+  if (texture?.source !== undefined) return texture.source;
+  const ext = texture?.extensions;
+  if (ext?.KHR_texture_basisu !== undefined) {
+    warnings.push(
+      `texture ${index} is KHR_texture_basisu, which this reader does not transcode; export ` +
+        'the model with PNG, JPEG or WebP images',
+    );
+    return undefined;
+  }
+  return ext?.EXT_texture_webp?.source ?? ext?.EXT_texture_avif?.source;
+}
+
 function readImages(
   doc: GltfDocument,
   buffers: readonly Uint8Array[],
@@ -330,7 +385,7 @@ function readImages(
 ): AssetReference[] {
   const out: AssetReference[] = [];
   for (let i = 0; i < (doc.textures ?? []).length; i++) {
-    const source = doc.textures?.[i]?.source;
+    const source = textureSource(doc.textures?.[i], i, warnings);
     const image = source === undefined ? undefined : doc.images?.[source];
     if (image === undefined) {
       warnings.push(`texture ${i} names no image this reader can find; it will draw untextured`);
@@ -563,6 +618,17 @@ function materialOf(material: GltfMaterial | undefined): DrftMaterial {
   const modulated = ormMap >= 0;
   const metallic = modulated ? 0 : (pbr?.metallicFactor ?? 1);
   const roughness = modulated ? DEFAULT_ROUGHNESS : (pbr?.roughnessFactor ?? 1);
+  /*
+   * **The same trap reached by the other door: a metal whose colour is an image.** `specular` is
+   * this engine's dielectric highlight and it is white, which is a metal's highlight only where the
+   * metal is white. Where the base colour is a texture that colour is per texel, the lane cannot
+   * say it, and the factor alone blew a dirt decal to white: its file names no metallic and no
+   * roughness, so the specification reads a rough metal of dark grime, and every wall it covered
+   * drew white under a low sun with the grime dark between. So the lane keeps the dielectric's
+   * zero there. What it gives up is the sun's glint on a textured metal with no map, which then
+   * shades as the grime or the paint its image says; what would change it is a metallic lane.
+   */
+  const highlight = pbr?.baseColorTexture === undefined ? metallic : 0;
 
   /*
    * **glTF leaves `metallicRoughnessTexture`'s R channel undefined.** The specification assigns G
@@ -583,7 +649,7 @@ function materialOf(material: GltfMaterial | undefined): DrftMaterial {
   return {
     name: material?.name ?? '',
     color: [base[0] ?? 1, base[1] ?? 1, base[2] ?? 1],
-    specular: metallic,
+    specular: highlight,
     roughness,
     emissive,
     emissiveColor:
@@ -591,6 +657,14 @@ function materialOf(material: GltfMaterial | undefined): DrftMaterial {
         ? [emissiveFactor[0] ?? 0, emissiveFactor[1] ?? 0, emissiveFactor[2] ?? 0]
         : [-1, -1, -1],
     opacity: blends ? Math.min(1, Math.max(0, base[3] ?? 1)) : 1,
+    /*
+     * glTF's `BLEND` says alpha is the factor *times the texture*. With a factor of 1 `opacity` alone
+     * cannot say the material blends, and a leaf whose shape is all in its texture's alpha drew as a
+     * solid card. So it is said.
+     */
+    blend: blends,
+    /* Seen from both faces: a curtain, a leaf card. The specification's default is one face. */
+    doubleSided: material?.doubleSided === true,
     /* Only in MASK mode: the specification says `alphaCutoff` has no meaning in the other two. */
     cutout: masked ? Math.min(1, Math.max(0, material?.alphaCutoff ?? 0.5)) : 0,
     /* Metalness is glTF's statement about reflection: a metal mirrors its surroundings and
@@ -627,6 +701,14 @@ export interface GltfReadOptions {
   readonly deriveTangents?: boolean;
 }
 
+/** The required extensions this reader implements, or follows far enough to fail loudly. */
+const KNOWN_REQUIRED = new Set([
+  'KHR_materials_pbrSpecularGlossiness',
+  'EXT_texture_webp',
+  'EXT_texture_avif',
+  'KHR_lights_punctual',
+]);
+
 /**
  * Turn a document into meshes in world space, one per primitive.
  *
@@ -644,6 +726,7 @@ export function gltfToMeshes(
   materials: DrftMaterial[];
   textures: AssetReference[];
   nodes: DrftNode[];
+  lights: DrftLight[];
 } {
   const version = doc.asset?.version ?? '';
   if (!version.startsWith('2')) {
@@ -655,6 +738,15 @@ export function gltfToMeshes(
   /* One per labelled material, by the ordinal `materials` is about to give it. */
   const substances: { material: number; substance: string }[] = [];
   const warnings: string[] = [];
+  /*
+   * A required extension is the file saying it cannot be read correctly without it. One this
+   * reader does not know is said by name, rather than drawing whatever falls out.
+   */
+  for (const name of doc.extensionsRequired ?? []) {
+    if (!KNOWN_REQUIRED.has(name)) {
+      warnings.push(`the file requires ${name}, which this reader does not implement`);
+    }
+  }
   const textures = readImages(doc, buffers, warnings);
   /*
    * Said once per material rather than once per primitive that uses it.
@@ -696,6 +788,9 @@ export function gltfToMeshes(
    * traversal.
    */
   const nodes: DrftNode[] = [];
+  /* The lights, placed by the same world matrix the walk computes for the geometry. */
+  const lights: DrftLight[] = [];
+  const punctual = doc.extensions?.KHR_lights_punctual?.lights ?? [];
 
   const walk = (nodeIndex: number, parent: readonly number[], parentNode: number): void => {
     if (seen.has(nodeIndex)) {
@@ -708,6 +803,18 @@ export function gltfToMeshes(
     if (node === undefined)
       throw new DrftError(`gltf: a scene names node ${nodeIndex}, which is absent`);
     const world = multiply(parent, localMatrix(node));
+    const hung = node.extensions?.KHR_lights_punctual?.light;
+    if (hung !== undefined) {
+      const light = punctual[hung];
+      if (light === undefined) {
+        warnings.push(`node ${nodeIndex} names light ${hung}, and the file has ${punctual.length}`);
+      } else {
+        const placed = placeLight(light, world, node.name ?? light.name ?? '');
+        if (placed === null)
+          warnings.push(`light ${hung}: a type "${light.type}" is not a punctual light`);
+        else lights.push(placed);
+      }
+    }
 
     const entry = nodes.length;
     nodes.push({
@@ -795,10 +902,39 @@ export function gltfToMeshes(
     materials,
     textures,
     nodes,
+    lights,
     ...(substances.length === 0 ? {} : { substances }),
   };
 }
 
+/**
+ * One punctual light where its node puts it: the node's origin, and its local −z for the way it
+ * points, both through the world matrix. The extension's defaults stand where the file is silent.
+ */
+function placeLight(
+  light: GltfPunctualLight,
+  world: readonly number[],
+  name: string,
+): DrftLight | null {
+  const kind = light.type;
+  if (kind !== 'point' && kind !== 'spot' && kind !== 'directional') return null;
+  const dx = -(world[8] ?? 0);
+  const dy = -(world[9] ?? 0);
+  const dz = -(world[10] ?? 1);
+  const length = Math.hypot(dx, dy, dz) || 1;
+  return {
+    kind,
+    name,
+    position: [world[12] ?? 0, world[13] ?? 0, world[14] ?? 0],
+    direction: [dx / length, dy / length, dz / length],
+    color: [light.color?.[0] ?? 1, light.color?.[1] ?? 1, light.color?.[2] ?? 1],
+    intensity: light.intensity ?? 1,
+    range: light.range ?? 0,
+    innerConeRad: light.spot?.innerConeAngle ?? 0,
+    outerConeRad: light.spot?.outerConeAngle ?? Math.PI / 4,
+  };
+}
+
 function buildPrimitive(
   doc: GltfDocument,
   buffers: readonly Uint8Array[],

package/src/index.ts

@@ -13,6 +13,11 @@
  * consumer writes the words, because what to call a stage is a decision about an audience.
  */
 export { DrftLoader } from './drftLoader.ts';
+/*
+ * A part's whole material in the renderer's shape, so a consumer drawing parts cannot copy half of
+ * it: a copy that left out the occlusion strength drew a bought model black.
+ */
+export { writePartMaterial } from './partMaterial.ts';
 /*
  * **A `DTEX` chunk's tile table as the grid residency asks about.** The other constructor of a
  * `MaterialTileGrid` — `latentTileGrid` cuts one from a latent a baker holds, and this reads one a
@@ -28,6 +33,7 @@ export type { DrftFit, DrftLoaderOptions } from './drftLoader.ts';
 export { drawKeyOf, resolveDrawGrouping } from './drawKey.ts';
 export type { DrawGrouping, DrawSurfaceOverride } from './drawKey.ts';
 export type { DrftLoadPhase, DrftLoadProgress, DrftPart } from './loadProgress.ts';
+export type { DrftFieldPlacement } from './fieldPlacement.ts';
 /* Addressing a texture by name, so a consumer never holds an ordinal. */
 export { TextureSet, textureColorSpaces } from './drftTextures.ts';
 export { assetCandidates, basenameOf } from './assetPath.ts';
@@ -105,11 +111,21 @@ export type { AsyncInflate } from './fbxInflate.ts';
  * on a real asset is roughly six times more than the model has.
  */
 export { weldMesh, dropDefaultAttributes } from './weld.ts';
+export { simplifyMesh } from './bake/simplify.ts';
+export type { SimplifyOptions } from './bake/simplify.ts';
+/*
+ * Copies an export merged into one mesh, found again as a prototype and a placement each. The
+ * baker writes them as `INST`; see `repeats.ts` for how strict a copy has to be to count.
+ */
+export { componentCount, findRepeats } from './repeats.ts';
+export type { Repeats } from './repeats.ts';
 /*
  * 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.ts';
+/* A decoded image shrunk to a texture cap, which is what the baker's `--max-texture` runs. */
+export { cappedSize, downscaleRgba } from './downscale.ts';
 /*
  * 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
@@ -122,7 +138,13 @@ export type { CoarseLevelOptions } from './coarseLevel.ts';
  * 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.ts';
+export {
+  orientMeshes,
+  orientTransforms,
+  orientLights,
+  parseUpAxis,
+  describeUpAxis,
+} from './orient.ts';
 export type { UpAxis } from './orient.ts';
 
 /* Skins and clips out of a glTF document. See the module for why it is not part of `gltf.ts`. */
@@ -199,6 +221,7 @@ export type { ClusterDag, ClusterLevel } from './bake/clusterLod.ts';
  * carries, and a field a consumer cannot bake is a pipeline with no input.
  */
 export { bakeObjectSdf } from './bake/sdf.ts';
+export { bakeSceneField } from './bake/sceneField.ts';
 /*
  * **The third time, and the one that got furthest before anybody noticed.** `bake/hlod.ts` builds
  * the proxies and impostors `docs/CAPABILITIES.md` lists as shipping, it is tested, it is sized and

package/src/loadProgress.ts

@@ -1,4 +1,4 @@
-import type { MeshHandle } from '@driftengine/core';
+import type { MeshHandle, InstancedHandle, MeshInstances } from '@driftengine/core';
 
 /**
  * The vocabulary of a load in flight: which phase it is in, how far it has got, and what a
@@ -73,6 +73,12 @@ export interface DrftLoadProgress {
 }
 
 /** One drawable piece of a loaded model. */
+/** A part's copies: the instanced batch over its mesh, and the placements already uploaded to it. */
+export interface DrftPartInstances {
+  readonly batch: InstancedHandle;
+  readonly data: MeshInstances;
+}
+
 export interface DrftPart {
   readonly mesh: MeshHandle;
   /** Which of the asset's images this surface wears, or -1 for none. */
@@ -121,6 +127,22 @@ export interface DrftPart {
    * nothing at all.
    */
   readonly cutout: number;
+  /**
+   * Whether the part blends: its texture's alpha is coverage, so it is drawn translucent whatever its
+   * `opacity` says. glTF's `BLEND` with a factor of 1 is the case: a leaf's shape is in its alpha.
+   */
+  readonly blend: boolean;
+  /** Whether both faces are seen: glTF's `doubleSided`. Drawn without culling, each face lit as the front. */
+  readonly doubleSided: boolean;
+  /**
+   * The copies this part is drawn as, or null for a part drawn once.
+   *
+   * A mesh the file places many times (`INST`, 1.18) is uploaded once and drawn through the
+   * engine's instanced path: `drawInstanced(batch, data)`, and `sink.instanced` for a shadow. The
+   * placements are uploaded when the part is made and carry the fit, so a caller passes them as
+   * they are. Null for every part of a file with no instances, which is every file before 1.18.
+   */
+  readonly instances: DrftPartInstances | null;
   /**
    * 0 to 1 as this part arrives, for a caller that would rather it faded in than appeared.
    *

package/src/orient.ts

@@ -26,7 +26,7 @@
  * untouched.
  */
 
-import type { DrftNode, MeshData } from '@driftengine/drft';
+import type { DrftLight, DrftNode, MeshData } from '@driftengine/drft';
 import { DrftError } from '@driftengine/drft';
 
 /** Which way is up in the asset, as a signed axis of the engine's own frame. */
@@ -71,7 +71,11 @@ export function describeUpAxis(up: UpAxis): string {
   return (TURNS[up] as { says: string }).says;
 }
 
-function turnTriples(source: Float32Array, m: readonly number[]): Float32Array {
+/**
+ * Turn the first three of every `stride` values, and copy the rest. Three for a position or a
+ * normal; four for a tangent, whose fourth is the bitangent's handedness and is not a direction.
+ */
+function turnTriples(source: Float32Array, m: readonly number[], stride = 3): Float32Array {
   const out = new Float32Array(source.length);
   const m0 = m[0] as number;
   const m1 = m[1] as number;
@@ -82,13 +86,14 @@ function turnTriples(source: Float32Array, m: readonly number[]): Float32Array {
   const m6 = m[6] as number;
   const m7 = m[7] as number;
   const m8 = m[8] as number;
-  for (let i = 0; i + 2 < source.length; i += 3) {
+  for (let i = 0; i + 2 < source.length; i += stride) {
     const x = source[i] as number;
     const y = source[i + 1] as number;
     const z = source[i + 2] as number;
     out[i] = m0 * x + m1 * y + m2 * z;
     out[i + 1] = m3 * x + m4 * y + m5 * z;
     out[i + 2] = m6 * x + m7 * y + m8 * z;
+    for (let k = 3; k < stride; k++) out[i + k] = source[i + k] as number;
   }
   return out;
 }
@@ -106,6 +111,60 @@ export function orientMeshes(meshes: readonly MeshData[], assetUp: UpAxis): Mesh
     ...mesh,
     positions: turnTriples(mesh.positions, m),
     normals: turnTriples(mesh.normals, m),
+    /*
+     * **The tangent frame turns with the normals**, and it did not until 2026-09-25: the baker
+     * derives tangents before it orients, so a normal-mapped model baked with `--up` kept its
+     * tangents in the file's axes and lit its normal maps from the wrong side.
+     */
+    ...(mesh.tangents === undefined ? {} : { tangents: turnTriples(mesh.tangents, m, 4) }),
+  }));
+}
+
+/**
+ * Column-major 4×4 placements, turned into the engine's frame: `O · M · Oᵀ` for each, with `O` the
+ * same turn `orientMeshes` gives the geometry. A copy the file moved along its own +z is then moved
+ * along the engine's +y, and a placement that was a rotation stays one of the same angle.
+ */
+export function orientTransforms(transforms: Float32Array, assetUp: UpAxis): Float32Array {
+  const o = TURNS[assetUp].m;
+  const out = new Float32Array(transforms.length);
+  for (let at = 0; at + 15 < transforms.length; at += 16) {
+    /* Row-major 3×3 of the placement, read out of its column-major block. */
+    for (let r = 0; r < 3; r++) {
+      for (let c = 0; c < 3; c++) {
+        let sum = 0;
+        for (let i = 0; i < 3; i++) {
+          for (let j = 0; j < 3; j++) {
+            /* (O M Oᵀ)[r][c] = Σ O[r][i] M[i][j] O[c][j] */
+            sum +=
+              (o[r * 3 + i] as number) *
+              (transforms[at + j * 4 + i] as number) *
+              (o[c * 3 + j] as number);
+          }
+        }
+        out[at + c * 4 + r] = sum;
+      }
+      let t = 0;
+      for (let i = 0; i < 3; i++)
+        t += (o[r * 3 + i] as number) * (transforms[at + 12 + i] as number);
+      out[at + 12 + r] = t;
+    }
+    out[at + 15] = 1;
+  }
+  return out;
+}
+
+/** Authored lights, turned into the engine's frame by the turn `orientMeshes` gives the geometry. */
+export function orientLights(lights: readonly DrftLight[], assetUp: UpAxis): DrftLight[] {
+  const { m } = TURNS[assetUp];
+  const turn = (v: readonly [number, number, number]): [number, number, number] => {
+    const t = turnTriples(new Float32Array(v), m);
+    return [t[0] as number, t[1] as number, t[2] as number];
+  };
+  return lights.map((light) => ({
+    ...light,
+    position: turn(light.position),
+    direction: turn(light.direction),
   }));
 }
 

package/src/partMaterial.ts

@@ -0,0 +1,42 @@
+/**
+ * A loaded part's material, written into the shape the renderer's `setMaterial` takes.
+ *
+ * **Every field or none**, because a partial copy fails in the one way nobody notices: silently and
+ * dark. `SurfaceMaterial` defaults `occlusionStrength` to 1, which is right for a caller who binds
+ * an ORM map and says nothing. A glTF material with no occlusion texture is carried as 0, and glTF
+ * lets its ORM map's red channel be anything — zero, in a bought scene measured here. A consumer
+ * who copied the maps and not the strength drew every surface multiplied by that zero. This is the
+ * one place the correspondence is written, so a field added to one side has one place to arrive.
+ *
+ * Writes into a caller-owned object and allocates nothing, so a scene rewrites one material per
+ * part in its frame loop. Opacity and reflectivity are not written: the first is a choice of draw
+ * call and the second a separate setter, and both stay the caller's to apply.
+ */
+import type { SurfaceMaterial, SurfaceTextureHandle } from '@driftengine/core';
+import type { TextureSet } from './drftTextures.ts';
+import type { DrftPart } from './loadProgress.ts';
+
+function at(
+  textures: TextureSet<SurfaceTextureHandle> | null,
+  index: number,
+): SurfaceTextureHandle | null {
+  return index >= 0 ? (textures?.at(index) ?? null) : null;
+}
+
+/** `part`'s maps and factors into `out`, resolving each map through `textures`. */
+export function writePartMaterial(
+  part: DrftPart,
+  textures: TextureSet<SurfaceTextureHandle> | null,
+  out: SurfaceMaterial<SurfaceTextureHandle>,
+): SurfaceMaterial<SurfaceTextureHandle> {
+  out.albedo = at(textures, part.albedo);
+  out.orm = at(textures, part.orm);
+  out.normal = at(textures, part.normal);
+  out.emissive = at(textures, part.emissive);
+  out.roughnessScale = part.roughnessScale;
+  out.metallicScale = part.metallicScale;
+  out.occlusionStrength = part.occlusionStrength;
+  out.cutout = part.cutout;
+  out.doubleSided = part.doubleSided;
+  return out;
+}

package/src/readModel.ts

@@ -22,7 +22,7 @@
  */
 
 import type { MeshData } from '@driftengine/drft';
-import type { AnimationClip, DrftMaterial, DrftNode, DrftSkin } from '@driftengine/drft';
+import type { AnimationClip, DrftLight, DrftMaterial, DrftNode, DrftSkin } from '@driftengine/drft';
 import { DrftError } from '@driftengine/drft';
 import type { AssetReference } from './assetPath.ts';
 import { assetCandidates } from './assetPath.ts';
@@ -150,6 +150,8 @@ export interface ModelImport {
    * reads it calls `localiseNodes` to get parts it can turn.
    */
   nodes?: readonly DrftNode[];
+  /** The lights the file was authored with, in world space. glTF carries them; nothing else here. */
+  lights?: readonly DrftLight[];
   /** Which way round the source's coordinate system was. `orient.ts` is what acts on it. */
   declaredHand?: Handedness;
 }