@threenative/assets 0.3.5 → 0.3.7

package/dist/blender-gpl/recipes/export_world.py

@@ -388,6 +388,8 @@ def skipped_collections(layer, under_hidden=False):
 
 def terrain_layer_texture(table_dir, textures, layer_id, kind):
     """The source file of one texture set's map, searched in the table's `textures.search` dirs."""
+    if kind not in textures:
+        fail("terrain layers: the table names no '%s' texture for a layer that asks for one" % kind)
     name = textures[kind].replace("{id}", layer_id)
     for relative in textures.get("search", ["."]):
         base = os.path.normpath(os.path.join(table_dir, relative))
@@ -422,7 +424,9 @@ def export_terrain_layers(out, table_path, root=None):
     The table (the game's; its DCC shader can read the same file) names its masks, texture sets and
     blend values. This writes `terrain/layers.json` (the table plus the splat layout),
     `terrain/splat.rgba8` (masks packed into RGBA8 planes, raw so no cook converts them) and
-    `terrain/tex/<id>_diff.jpg` / `<id>_nrm.jpg`, and returns the `terrain.layers` paths.
+    `terrain/tex/<id>_diff.jpg`, `<id>_nrm.jpg` and `<id>_orm.jpg`, and returns the
+    `terrain.layers` paths. A layer's `normal` and `orm` flags say which maps it ships, and its
+    `roughness`/`metalness` say how it answers light when it ships no ORM map.
     Relative paths in the table resolve against `root` when given, else the table's folder.
     """
     import numpy as np
@@ -476,6 +480,19 @@ def export_terrain_layers(out, table_path, root=None):
                 terrain_layer_texture(table_dir, textures, layer["id"], "nrm"),
                 os.path.join(tex, "%s_nrm.jpg" % layer["id"]),
             )
+        if layer.get("orm"):
+            # A material with a roughness input of its own ships that input as occlusion,
+            # roughness and metalness; the table's numbers stand in for one without it.
+            shutil.copyfile(
+                terrain_layer_texture(table_dir, textures, layer["id"], "orm"),
+                os.path.join(tex, "%s_orm.jpg" % layer["id"]),
+            )
+        if layer.get("height"):
+            # The layer's own height, which the game's `layerWeight` reads; fails closed like orm.
+            shutil.copyfile(
+                terrain_layer_texture(table_dir, textures, layer["id"], "h"),
+                os.path.join(tex, "%s_h.jpg" % layer["id"]),
+            )
 
     shipped = {key: table[key] for key in ("base", "breakup", "macro", "layers")}
     shipped["splat"] = {"masks": placed, "planes": len(planes), "size": size}

package/dist/index.d.ts

@@ -1,12 +1,123 @@
 import { Document, Material } from '@gltf-transform/core';
 
+interface IImageQualityFloor {
+    readonly ssim: number;
+    readonly meanDeltaE00: number;
+}
+interface IImageQuality {
+    readonly version: string;
+    readonly width: number;
+    readonly height: number;
+    readonly ssim: number;
+    readonly meanDeltaE00: number | null;
+    readonly slots: readonly string[];
+    readonly floor: IImageQualityFloor;
+    readonly status: "pass" | "below-floor" | "unvalidated-slots";
+    readonly alpha: {
+        readonly ssim: number;
+        readonly meanAbsoluteError: number;
+        readonly coverage: readonly {
+            readonly threshold: number;
+            readonly source: number;
+            readonly decoded: number;
+            readonly changedPixels: number;
+        }[];
+    };
+}
+interface ITextureQuality extends IImageQuality {
+    readonly rung?: string;
+    readonly compressionSkipped?: "block-size" | "not-smaller" | "below-floor";
+    readonly sourceWidth: number;
+    readonly sourceHeight: number;
+    readonly codec: string;
+}
+
+/**
+ * Compresses the images embedded *inside* a `.glb` — the half of a model the geometry passes
+ * never touched. A prop carrying three 2048x2048 JPEGs is a small file and 67 MB of VRAM once
+ * the driver decodes it; meshopt shrinks the other, cheaper half. This stage transcodes each
+ * embedded image to KTX2/Basis and declares `KHR_texture_basisu`, so the GPU stores blocks
+ * instead of RGBA, and caps the resolution so a 4K texture an image model produced cannot
+ * silently eat a phone's whole budget.
+ *
+ * Slot constraints feed one measured ladder: normal/data slots retain UASTC/none, while
+ * colour escalates from ETC1S through RDO and plain UASTC. Alpha coverage is checked separately;
+ * a forced codec must still meet the floor. Colour space comes from the slot too — `getTextureColorSpace`
+ * knows base colour and emissive are sRGB and that metallic-roughness and normals are data —
+ * so a linear map is never encoded through a perceptual metric.
+ *
+ * The encoder is the same in-process Basis WASM the standalone texture pass uses, so no new
+ * dependency and nothing extra to install. Everything fails closed: an image no decoder reads,
+ * an image whose dimensions are not a whole number of 4x4 blocks, and a texture whose binding
+ * did not survive the round trip all throw naming the model and the image.
+ */
+interface IModelTextureOverride {
+    readonly codec: TextureCodec;
+    /** glTF slot the override applies to, e.g. `normalTexture` or `baseColorTexture`. */
+    readonly slot: string;
+}
+type TextureMaxSize = number | Readonly<Record<string, number>>;
+interface IModelTexturesOptions {
+    /** Internal target-selected raw ASTC output. */
+    readonly astc?: boolean;
+    readonly floor?: Partial<IImageQualityFloor>;
+    /** Internal reporting switch; selection still measures and enforces the floor. */
+    readonly measureQuality?: boolean;
+    /**
+     * Resolved by the compiler from the target's runtime capabilities, never by a project: the
+     * target has no KTX2 decoder, so an over-cap embedded image is box-resampled and re-emitted as
+     * a PNG instead of being encoded. Everything else — authored-byte retention under the cap,
+     * per-image deduplication, colour space — is unchanged.
+     */
+    readonly decoderFree?: boolean;
+    /**
+     * Longest edge an embedded image may keep, default 2048. Larger images are box-resampled
+     * down preserving aspect ratio; smaller ones are never upscaled.
+     */
+    readonly maxSize?: TextureMaxSize;
+    readonly overrides?: readonly IModelTextureOverride[];
+    /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
+    readonly quality?: number;
+}
+/** What the stage did, recorded in the manifest and printed by the size report. */
+interface IEmbeddedTextureSummary {
+    readonly quality: Readonly<Record<string, ITextureQuality>>;
+    readonly bytesAfter: number;
+    readonly bytesBefore: number;
+    readonly count: number;
+    /** Chosen codec per embedded image, keyed by texture name. */
+    readonly formats: Readonly<Record<string, string>>;
+    readonly gpuBytesAfter: number;
+    readonly gpuBytesBefore: number;
+    /** How many images the resolution cap actually downsampled. */
+    readonly resized: number;
+    /** Images retained at their authored bytes, by name, with the reason each one was not cooked. */
+    readonly skippedCompression: Readonly<Record<string, TextureSkipReason>>;
+}
+/** One embedded image as the verification compares it, source against re-read output. */
+interface IModelTextureBinding {
+    readonly height: number;
+    readonly key: string;
+    /** KTX2 mip levels; 1 for a still-uncompressed source image. */
+    readonly levels: number;
+    readonly mimeType: string;
+    readonly slots: readonly string[];
+    readonly texCoords: readonly number[];
+    readonly width: number;
+}
+interface IModelTextureBindings {
+    /** `material -> slot=textureIndex@uvN` for the five core glTF slots, in document order. */
+    readonly materials: readonly string[];
+    readonly textures: readonly IModelTextureBinding[];
+}
+
 /**
  * Encodes compiled textures to KTX2/Basis so the GPU stores them compressed instead of as
  * decoded RGBA (a 2048x2048 PNG is 16 MB in VRAM; BC7/ASTC hold it in a quarter of that).
  *
  * Codec choice is a declared property of the asset, never a guess: a config override wins,
- * then the `*_normal.*` / `_nrm.*` filename convention, then alpha presence (UASTC keeps
- * exact alpha and survives normal-map data; ETC1S does not). Mip chains are generated at
+ * then the `*_normal.*` / `_nrm.*` filename convention constrains the shared measured ladder.
+ * Colour escalates through ETC1S/RDO/UASTC/none; unknown alpha cutoffs require exact alpha. Mip chains are generated at
  * encode time — always — because an uploaded compressed texture without mips looks worse
  * than the PNG it replaced.
  *
@@ -18,10 +129,10 @@ type TextureCodec = "etc1s" | "none" | "uastc";
 /**
  * Why a source shipped uncompressed although its pass ran. `not-smaller` means encoding would
  * have grown the download; `block-size` means no block codec can address the source's
- * dimensions. Both keep the authored bytes; neither is a silent decision — the manifest carries
+ * dimensions; `below-floor` means no compressed rung passed. A capped source retains its resized pixels as PNG; none is a silent decision — the manifest carries
  * the reason and the report prints it.
  */
-type TextureSkipReason = "block-size" | "not-smaller";
+type TextureSkipReason = "block-size" | "not-smaller" | "below-floor";
 interface ITextureOverride {
     readonly codec: TextureCodec;
     /** First matching override wins; matched against the logical path, e.g. "ui/x.png". */
@@ -30,8 +141,13 @@ interface ITextureOverride {
     readonly quality?: number;
 }
 interface ITexturePassOptions {
+    /** Compiler-selected mobile output; the quality ladder measures final ASTC bytes. */
+    readonly astc?: boolean;
+    readonly floor?: Partial<IImageQualityFloor>;
+    /** Internal reporting control; selection still measures and enforces the floor. */
+    readonly measureQuality?: boolean;
     /** Longest edge to retain; larger sources are downsampled without upscaling. */
-    readonly maxSize?: number;
+    readonly maxSize?: TextureMaxSize;
     readonly overrides?: readonly ITextureOverride[];
     /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
     readonly quality?: number;
@@ -409,78 +525,6 @@ interface IModelVirtualOptions {
     readonly simplifyRatio?: number;
 }
 
-/**
- * Compresses the images embedded *inside* a `.glb` — the half of a model the geometry passes
- * never touched. A prop carrying three 2048x2048 JPEGs is a small file and 67 MB of VRAM once
- * the driver decodes it; meshopt shrinks the other, cheaper half. This stage transcodes each
- * embedded image to KTX2/Basis and declares `KHR_texture_basisu`, so the GPU stores blocks
- * instead of RGBA, and caps the resolution so a 4K texture an image model produced cannot
- * silently eat a phone's whole budget.
- *
- * Codec choice follows the declared use of the image, never a guess: a config override on the
- * glTF slot wins, then normal-map slots (UASTC survives normal data; ETC1S does not), then
- * alpha in the decoded pixels. Colour space comes from the slot too — `getTextureColorSpace`
- * knows base colour and emissive are sRGB and that metallic-roughness and normals are data —
- * so a linear map is never encoded through a perceptual metric.
- *
- * The encoder is the same in-process Basis WASM the standalone texture pass uses, so no new
- * dependency and nothing extra to install. Everything fails closed: an image no decoder reads,
- * an image whose dimensions are not a whole number of 4x4 blocks, and a texture whose binding
- * did not survive the round trip all throw naming the model and the image.
- */
-interface IModelTextureOverride {
-    readonly codec: TextureCodec;
-    /** glTF slot the override applies to, e.g. `normalTexture` or `baseColorTexture`. */
-    readonly slot: string;
-}
-interface IModelTexturesOptions {
-    /**
-     * Resolved by the compiler from the target's runtime capabilities, never by a project: the
-     * target has no KTX2 decoder, so an over-cap embedded image is box-resampled and re-emitted as
-     * a PNG instead of being encoded. Everything else — authored-byte retention under the cap,
-     * per-image deduplication, colour space — is unchanged.
-     */
-    readonly decoderFree?: boolean;
-    /**
-     * Longest edge an embedded image may keep, default 2048. Larger images are box-resampled
-     * down preserving aspect ratio; smaller ones are never upscaled.
-     */
-    readonly maxSize?: number;
-    readonly overrides?: readonly IModelTextureOverride[];
-    /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
-    readonly quality?: number;
-}
-/** What the stage did, recorded in the manifest and printed by the size report. */
-interface IEmbeddedTextureSummary {
-    readonly bytesAfter: number;
-    readonly bytesBefore: number;
-    readonly count: number;
-    /** Chosen codec per embedded image, keyed by texture name. */
-    readonly formats: Readonly<Record<string, string>>;
-    readonly gpuBytesAfter: number;
-    readonly gpuBytesBefore: number;
-    /** How many images the resolution cap actually downsampled. */
-    readonly resized: number;
-    /** Images retained at their authored bytes, by name, with the reason each one was not cooked. */
-    readonly skippedCompression: Readonly<Record<string, TextureSkipReason>>;
-}
-/** One embedded image as the verification compares it, source against re-read output. */
-interface IModelTextureBinding {
-    readonly height: number;
-    readonly key: string;
-    /** KTX2 mip levels; 1 for a still-uncompressed source image. */
-    readonly levels: number;
-    readonly mimeType: string;
-    readonly slots: readonly string[];
-    readonly texCoords: readonly number[];
-    readonly width: number;
-}
-interface IModelTextureBindings {
-    /** `material -> slot=textureIndex@uvN` for the five core glTF slots, in document order. */
-    readonly materials: readonly string[];
-    readonly textures: readonly IModelTextureBinding[];
-}
-
 /**
  * Images that models share, written once and referenced from every model that carries them.
  *
@@ -495,6 +539,7 @@ interface IModelTextureBindings {
  * bytes resolve to one URL and the browser cache, the bundle and the delete-test all see one file.
  */
 interface ISharedImage {
+    readonly quality?: ITextureQuality;
     readonly buffer: Buffer;
     /** `uastc`, `etc1s` or `none`, spelled into the filename so a cache hit knows what it found. */
     readonly codec: string;
@@ -624,6 +669,7 @@ declare function modelPass(options?: IModelPassOptions): IAssetPass;
  * so tests can pin the exact lines a build prints.
  */
 interface ITextureSizeRow {
+    readonly quality?: ITextureQuality;
     readonly after: number;
     readonly before: number;
     /** Set when the bytes shipped as authored; printed so a flat row is never left unexplained. */
@@ -634,6 +680,7 @@ interface ITextureSizeRow {
 declare function formatTextureSizes(rows: readonly ITextureSizeRow[]): readonly string[];
 /** What the model pass did to the images inside one `.glb`. */
 interface IEmbeddedTextureRow {
+    readonly quality?: Readonly<Record<string, ITextureQuality>>;
     readonly skippedCompression?: Readonly<Record<string, TextureSkipReason>>;
     readonly bytesAfter: number;
     readonly bytesBefore: number;
@@ -648,6 +695,8 @@ interface IEmbeddedTextureRow {
 interface IVirtualRow {
     readonly bakeSeconds: number;
     readonly clusters: number;
+    /** Primitives handed back to the discrete ladder because their DAG reduced nothing. */
+    readonly declined: number;
     readonly levels: number;
     readonly payloadBytes: number;
     readonly primitives: number;
@@ -972,6 +1021,14 @@ interface IAssetSourceConfig {
      * default-on decision is a later phase (PRD-377 §8).
      */
     readonly lod?: boolean | IModelLodOptions | "none";
+    /**
+     * Also writes the native cooked package (`<output>/native/assets.tnpk`, TNPK v1) beside the
+     * existing outputs: one Buffer entry per cooked binary buffer and one Texture entry per cooked
+     * PNG or JPEG (decoded to RGBA8). Mesh, material and scene entries are out of scope until their
+     * native loaders land.
+     * Absent means off, so a web-only project pays nothing.
+     */
+    readonly nativePackage?: boolean;
     readonly output?: string;
     readonly source?: string;
     readonly targets?: IAssetTargets;
@@ -1021,7 +1078,8 @@ interface IAudioConfig {
     readonly seamMaxRatio?: number;
 }
 interface ITexturesConfig {
-    readonly maxSize?: number;
+    readonly floor?: ITexturePassOptions["floor"];
+    readonly maxSize?: TextureMaxSize;
     readonly overrides?: readonly ITextureOverride[];
     readonly quality?: number;
 }
@@ -1046,31 +1104,16 @@ interface IAssetCompileOptions {
      */
     readonly processingOrder?: "reversed" | "sorted";
     /**
-     * The platform this bake is for, which decides whether compression can ship at all.
-     *
-     * Android and iOS run the native host without WebAssembly, so they carry no Basis transcoder
-     * and no Meshopt decoder: a `.ktx2` texture or a meshopt-compressed mesh in a mobile bundle is
-     * a black screen, and `threenative build` refuses one with `TN_NATIVE_KTX2_UNSUPPORTED`. Web
-     * and desktop decode both.
-     *
-     * Absent means web — a direct `compileAssets` call, or a project that compiles once and serves
-     * the result. `threenative build` always names its `--target`, so the passes that a platform
-     * cannot decode drop for that build and stay on for every other one. This is the whole reason
-     * `assets.textures: "none"` used to be pinned in the scaffolded config: the author was asked to
-     * choose one constant for four targets, and every game that wanted Android shipped its web
-     * build uncompressed too. The build knows its target; it decides.
+     * The conservative default decoder policy: web/desktop keep the existing loaders;
+     * Android/iOS stay decoder-free until their packaged loaders are qualified. A V8 engine
+     * alone does not establish a working Basis, Meshopt or Draco path. Absent means web.
+     * Native builds provide runtimeDecoders from their selected artifact instead.
      */
     readonly platform?: "android" | "desktop" | "ios" | "web";
-    /**
-     * What the runtime that will execute this bake can decode, when the caller has probed it.
-     *
-     * `platform` is a proxy: it answers "android and iOS have no WebAssembly" for the targets this
-     * repository ships. A desktop host can also lack WebAssembly — the Linux arm64 lane builds
-     * QuickJS over wgpu-native — and then the same meshopt/KTX2 passes it would keep produce an
-     * asset nothing can decode. `threenative build` reads the engine from the runtime binary it will
-     * package and passes the real capability here; absent, the platform-derived default stands.
-     */
+    /** Which compressed outputs the selected runtime's bundle can decode, independently of WASM. */
     readonly runtimeDecoders?: IAssetRuntimeDecoderCapabilities;
+    /** Exact selected runtime/cohort identity; changing it invalidates cooked output. */
+    readonly runtimeIdentity?: string;
     readonly source?: string;
     /** Overrides resolution of three's Basis transcoder for the copy into the output root. */
     readonly transcoder?: IBasisTranscoder;