@threenative/assets 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -54,6 +54,15 @@ interface IAssetRuntimeDecoderCapabilities {
     readonly meshopt: boolean;
 }
 
+interface IModelDedupeSummary {
+    /** Distinct cooked outputs among the model sources that took part. */
+    readonly cooked: number;
+    /** Cooked bytes the duplicates would have written on their own. */
+    readonly savedBytes: number;
+    /** Model sources that took part, canonicals and duplicates alike. */
+    readonly sources: number;
+}
+
 type AssetFindingGrade = "fail" | "ok" | "warn";
 interface IAssetFinding {
     readonly asset: string;
@@ -164,6 +173,7 @@ interface IModelLodRuntimeOptions {
 }
 /** A partial override for one asset; nested objects overlay, they never replace. */
 interface IModelLodOverride {
+    readonly cutout?: boolean;
     readonly enabled?: boolean;
     readonly generation?: IModelLodGenerationOptions;
     readonly preset?: LodPreset;
@@ -175,6 +185,12 @@ interface IModelLodOverride {
  * re-enable. Resolution is per asset and happens where the asset is known (PRD-377 §3.2, §5).
  */
 interface IModelLodOptions {
+    /**
+     * Convert eligible `BLEND` foliage to alpha-tested in the cook (PRD-458 §4). Default `true`,
+     * because a needle card exported as `BLEND` is refused a chain by rule and the tree then draws
+     * LOD0 forever. `false` keeps the authored blending; per asset, `cutout` in an override entry.
+     */
+    readonly cutout?: boolean;
     readonly enabled?: boolean;
     readonly generation?: IModelLodGenerationOptions;
     readonly overrides?: Readonly<Record<string, boolean | IModelLodOverride>>;
@@ -275,6 +291,74 @@ interface IAudioPassOptions {
 /** `"none"` drops the pass; an object configures it; absent means the defaults run. */
 declare function parseAudioConfig(raw: unknown): IAudioPassOptions | undefined;
 
+interface IModelCompactInstanceOptions {
+    /**
+     * Minimum number of nodes that must share one mesh before it is instanced, default 2.
+     * gltf-transform's own default is 5; the lower floor is what lets a paired prop instance.
+     */
+    readonly min?: number;
+}
+interface IModelCompactOptions {
+    readonly flatten?: boolean;
+    readonly instance?: boolean | IModelCompactInstanceOptions;
+    readonly join?: boolean;
+    /** Extra exact node names to protect, on top of the regex and the structural rules. */
+    readonly protectedNames?: readonly string[];
+    /**
+     * Case-insensitive node-name regex source for nodes the game looks up or moves. Defaults to
+     * {@link DEFAULT_PROTECTED_PATTERN}; an invalid source throws rather than silently protecting nothing.
+     */
+    readonly protectedPattern?: string;
+}
+/** Why a node was kept out of join/instance. */
+type TModelProtectedRule = "allow-list" | "animation-ancestor" | "animation-target" | "regex" | "skin-joint";
+interface IModelProtectedNode {
+    readonly name: string;
+    readonly rule: TModelProtectedRule;
+}
+interface IModelCompactSummary {
+    /** Whether each pass ran and how many primitives/nodes it removed. */
+    readonly flatten: {
+        readonly enabled: boolean;
+        /** Nodes reparented toward the scene root; a node left in place is not counted. */
+        readonly reparented: number;
+    };
+    readonly instance: {
+        readonly batches: number;
+        readonly enabled: boolean;
+        readonly instances: number;
+        /** Why no batch was created, when none was. */
+        readonly reason?: string;
+    };
+    readonly join: {
+        readonly enabled: boolean;
+        readonly primitivesAfter: number;
+        readonly primitivesBefore: number;
+    };
+    readonly nodesAfter: number;
+    readonly nodesBefore: number;
+    readonly primitivesAfter: number;
+    readonly primitivesBefore: number;
+    /**
+     * Named scene nodes that existed before compaction and are gone after it. Empty is the
+     * expected result of a run whose protected set covered every name the game addresses; a
+     * non-empty list is the report's warning that a `getObjectByName` can now return undefined.
+     */
+    readonly removed: readonly string[];
+    /** Every node kept out of compaction, with the rule that protected it, sorted by name. */
+    readonly protected: readonly IModelProtectedNode[];
+}
+/** The compaction policy with every default resolved, so it is a stable cache key. */
+interface IResolvedCompactOptions {
+    readonly flatten: boolean;
+    readonly instance: false | IModelCompactInstanceOptions;
+    readonly join: boolean;
+    readonly protectedNames: readonly string[];
+    readonly protectedPattern: string;
+    /** Algorithm identity, so an upgraded pass never re-serves a cache from an older build. */
+    readonly version: number;
+}
+
 /**
  * Atlas integration follows the mesh → xatlas → remapped-attribute split documented by
  * xatlas-three 0.2.1 (MIT, copyright 2022 Palash Bansal). This implementation uses xatlasjs's
@@ -350,6 +434,13 @@ interface IModelTextureOverride {
     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.
@@ -470,6 +561,12 @@ interface IModelSimplifyOptions {
 }
 interface IModelPassOptions {
     readonly passes?: IModelPassesOptions;
+    /**
+     * Lossless scene-graph compaction (flatten → instance → join) against one protected-node set.
+     * Absent means on with defaults; `false` is the kill switch; an object configures the
+     * sub-passes, the protected-name allow-list and the name regex. It never decimates geometry.
+     */
+    readonly compact?: boolean | IModelCompactOptions;
     /** Native WebGPU rejects interleaved vertex attributes; mobile output uses separate buffers. */
     readonly vertexLayout?: "interleaved" | "separate";
     /** Preserve generated TEXCOORD_1 data that is consumed by a runtime-attached lightmap. */
@@ -583,6 +680,17 @@ interface ILodJoinedRow {
 interface ILodRow {
     /** Bytes the derived index buffers add, before compression. */
     readonly byteOverhead: number;
+    /**
+     * The foliage cutout conversion the cook ran before generating (PRD-458 §4): the `BLEND`
+     * materials that became alpha-tested, and the ones that kept blending and why.
+     */
+    readonly cutout?: {
+        readonly converted: readonly string[];
+        readonly kept: readonly {
+            readonly name: string;
+            readonly reason: string;
+        }[];
+    };
     /** Migration/legacy notes the resolver raised, by code. */
     readonly diagnostics: readonly string[];
     /** The resolved increasing geometric-error targets, as the bake consumed them. */
@@ -717,6 +825,19 @@ interface IAudioRow {
  */
 declare function formatAudioSizes(rows: readonly IAudioRow[]): readonly string[];
 /** One compiled model plus a total, before against after the optimization pass. */
+/** The cook's material merge (PRD-458 §5): what collapsed, and the counts either side of it. */
+interface IMaterialsRow {
+    /** Distinct signatures — the count a draw call is bound by. */
+    readonly distinct: {
+        readonly after: number;
+        readonly before: number;
+    };
+    readonly materials: {
+        readonly after: number;
+        readonly before: number;
+    };
+    readonly merged: readonly string[];
+}
 interface IModelSizeRow {
     readonly after: number;
     readonly before: number;
@@ -739,8 +860,12 @@ interface IModelSizeRow {
     readonly simplify?: ISimplifyRow;
     /** Automatic discrete LOD generation (PRD-377), when the effective policy ran. */
     readonly lod?: ILodRow;
+    /** Lossless scene-graph compaction (PRD-443), when it ran. */
+    readonly compact?: IModelCompactSummary;
     /** The cluster-DAG bake, when it was configured for this model. */
     readonly virtual?: IVirtualRow;
+    /** The material merge the cook ran unconditionally, before any other geometry stage. */
+    readonly materials?: IMaterialsRow;
     /** Triangle count of the compiled output, recorded in the manifest. */
     readonly triangles?: number;
 }
@@ -804,6 +929,13 @@ interface IAssetPass {
     /** True when this pass's emitted output requires a runtime decoder unavailable on mobile. */
     readonly needsRuntimeDecoder?: boolean;
     readonly name: string;
+    /**
+     * Input kinds whose bytes this pass can change. The compile hashes only the passes that can
+     * change an asset into that asset's digest, so a model-only option edit does not rename every
+     * texture. `undefined` (the default for a caller-supplied pass) means any kind, which stays
+     * conservative: an unknown pass can change every asset.
+     */
+    readonly appliesTo?: readonly AssetKind[];
     /**
      * JSON-serializable snapshot of every option that changes this pass's output. Part of the
      * compile cache key: without it, editing a config value (texture quality, quantize bits, an
@@ -825,7 +957,7 @@ interface IAssetSourceConfig {
     readonly audio?: IAudioConfig | "none";
     /**
      * The bound on how many workers a bake may use. A direct `concurrency` option overrides it;
-     * absent means the driver's default (`min(4, cores - 1)`). CI boxes and laptops differ, and
+     * absent means the driver's default (cores - 1, bounded by ~2 GB of memory a worker, at most 12). CI boxes and laptops differ, and
      * a 6.8 GB pack does not get to decide the machine's fate.
      */
     readonly concurrency?: number;
@@ -850,6 +982,11 @@ interface IAssetSourceConfig {
     readonly textures?: ITexturesConfig | "none";
 }
 interface IModelsConfig {
+    /**
+     * Lossless scene-graph compaction (flatten → instance → join) against one protected-node set.
+     * Default true ({@link IModelCompactOptions}); `false` ships the scene graph as authored.
+     */
+    readonly compact?: boolean | IModelCompactOptions;
     /** Generate standard TEXCOORD_1 lightmap UVs. Absent means no lightmap pass. */
     readonly lightmap?: ILightmapPassOptions;
     readonly passes?: IModelPassesOptions;
@@ -955,6 +1092,11 @@ interface IAssetCompileResult {
     readonly skippedCompression: readonly ISkippedReportRow[];
     readonly receipt?: IBakeReceipt;
     readonly report?: IAssetHealthReport;
+    /**
+     * What the model cook saved by cooking content-identical sources once, when this project has
+     * any model source. `cooked` is the number of distinct outputs those sources produced.
+     */
+    readonly dedupe?: IModelDedupeSummary;
     readonly skipped: number;
     readonly written: number;
 }
@@ -1317,4 +1459,4 @@ declare function censusDocument(model: string, document: Document, pageSize?: nu
 /** Totals across a set of models, so a scene's census is one line rather than twenty-nine. */
 declare function totalCensus(entries: readonly IContentCensus[]): Omit<IContentCensus, "model">;
 
-export { type AssetFindingGrade, type AssetKind, type AtlasExclusionReason, type AudioBand, type AudioConditioning, type AudioNormalisation, type IAssetCompileOptions, type IAssetCompileResult, type IAssetFinding, type IAssetHealthEntry, type IAssetHealthInput, type IAssetHealthReport, type IAssetPass, type IAssetPassOutput, type IAssetSourceConfig, type IAssetTargets, type IAssetWatchHandle, type IAssetWatchOptions, type IAssetWatchSummary, type IAtlasExclusion, type IAtlasOptions, type IAtlasPage, type IAtlasPlacement, type IAtlasResult, type IAtlasSource, type IAudioConfig, type IAudioLoopOptions, type IAudioOverride, type IAudioPassOptions, type IAudioRow, type IAudioSpectrumExpectation, type IBakeReceipt, type IBakeReceiptOutput, type IBasisTranscoder, type IContentCensus, type IDedupeCensus, type IEmbeddedTextureRow, type IEmbeddedTextureSummary, type ILightmapPassOptions, type IMaterialBucket, type IMaterialState, type IModelPassOptions, type IModelPassesOptions, type IModelQuantizeOptions, type IModelSimplifyOptions, type IModelSimplifySummary, type IModelSizeRow, type IModelStats, type IModelTextureBinding, type IModelTextureBindings, type IModelTextureOverride, type IModelTexturesOptions, type IModelsConfig, type IPassCostAssetRow, type IPassCostRow, type IPngInfo, type ISimplifyRow, type ITextureOverride, type ITexturePassOptions, type ITextureSizeRow, type ITextureStats, type ITexturesConfig, type PassCostStatus, type TextureCodec, WRAP_CLAMP_TO_EDGE, WRAP_MIRRORED_REPEAT, WRAP_REPEAT, atlasManifest, audioPass, censusDocument, compileAssets, dedupeMaterials, formatAudioSizes, formatHealthReport, formatModelSizes, formatPassCosts, formatTextureSizes, lightmapPass, materialSignature, materialStateOf, modelPass, packAtlas, parseAudioConfig, parsePng, resolveBasisTranscoder, resolveSourceTexel, rewriteUvs, runHealthReport, texturePass, totalCensus, uvsTile, watchAssets, withAtlasTextures, wrapTiles };
+export { type AssetFindingGrade, type AssetKind, type AtlasExclusionReason, type AudioBand, type AudioConditioning, type AudioNormalisation, type IAssetCompileOptions, type IAssetCompileResult, type IAssetFinding, type IAssetHealthEntry, type IAssetHealthInput, type IAssetHealthReport, type IAssetPass, type IAssetPassOutput, type IAssetSourceConfig, type IAssetTargets, type IAssetWatchHandle, type IAssetWatchOptions, type IAssetWatchSummary, type IAtlasExclusion, type IAtlasOptions, type IAtlasPage, type IAtlasPlacement, type IAtlasResult, type IAtlasSource, type IAudioConfig, type IAudioLoopOptions, type IAudioOverride, type IAudioPassOptions, type IAudioRow, type IAudioSpectrumExpectation, type IBakeReceipt, type IBakeReceiptOutput, type IBasisTranscoder, type IContentCensus, type IDedupeCensus, type IEmbeddedTextureRow, type IEmbeddedTextureSummary, type ILightmapPassOptions, type IMaterialBucket, type IMaterialState, type IModelCompactInstanceOptions, type IModelCompactOptions, type IModelCompactSummary, type IModelPassOptions, type IModelPassesOptions, type IModelProtectedNode, type IModelQuantizeOptions, type IModelSimplifyOptions, type IModelSimplifySummary, type IModelSizeRow, type IModelStats, type IModelTextureBinding, type IModelTextureBindings, type IModelTextureOverride, type IModelTexturesOptions, type IModelsConfig, type IPassCostAssetRow, type IPassCostRow, type IPngInfo, type IResolvedCompactOptions, type ISimplifyRow, type ITextureOverride, type ITexturePassOptions, type ITextureSizeRow, type ITextureStats, type ITexturesConfig, type PassCostStatus, type TModelProtectedRule, type TextureCodec, WRAP_CLAMP_TO_EDGE, WRAP_MIRRORED_REPEAT, WRAP_REPEAT, atlasManifest, audioPass, censusDocument, compileAssets, dedupeMaterials, formatAudioSizes, formatHealthReport, formatModelSizes, formatPassCosts, formatTextureSizes, lightmapPass, materialSignature, materialStateOf, modelPass, packAtlas, parseAudioConfig, parsePng, resolveBasisTranscoder, resolveSourceTexel, rewriteUvs, runHealthReport, texturePass, totalCensus, uvsTile, watchAssets, withAtlasTextures, wrapTiles };