@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/importCharacter.d.ts

@@ -1,11 +1,35 @@
+import { type Document } from '@gltf-transform/core';
+import { type BoneMap } from './stages/retarget';
 import { type ConformResult } from './stages/conform';
+import { type PushOutOptions, type PushOutReport } from './addonPushOut';
+import { type PoseAwareFitOptions, type PoseAwareFitReport } from './stages/poseAwareFit';
+import { type LimbBridgeOptions, type LimbBridgeReport } from './stages/limbBridge';
 import { type Ktx2Mode, type Ktx2Result } from './stages/ktx2';
+import { type UnrealMaterialSidecarApplyResult } from './unrealMaterialSidecar';
+import { type CharacterSourcePreflight } from './untrustedSource';
+import { type CharacterSourceProvenance } from './importTrust';
+import { type AvatarFaceManifestV1 } from './faceManifest';
+import { type HelixPaletteApplyResult, type HelixPaletteSelection } from './helixPalette';
 export declare const CANONICAL_BODY_FILENAME = "body-m-default.web.glb";
+export type CharacterRigScope = 'character' | 'addon';
+export interface SourceLodSelection {
+    retained: string[];
+    removed: string[];
+}
+/** Unreal exports often contain authored LOD0..N meshes in one scene. HELIX generates its own
+ * three deterministic LODs, so retaining every authored level duplicates the character in each
+ * output scene and makes modular composition ambiguous. Keep authored LOD0 for each explicitly
+ * numbered mesh family and leave unnumbered meshes untouched. A family without LOD0 is untouched
+ * as well, avoiding guesses about incomplete or nonstandard sources. */
+export declare function retainHighestDetailSourceLods(document: Document): Promise<SourceLodSelection>;
 export interface ImportCharacterOptions {
-    /** Source biped character GLB (skinned body, Meshy/Mixamo-style rig). */
+    /** Source biped character GLB or FBX (skinned body, Meshy/Mixamo/MetaHuman-style rig). */
     body: string;
-    /** Bone map JSON path ({ map: { src: helix }, drop: [...] }). Default: the bundled Meshy->helix map. */
+    /** Bone map JSON path ({ map: { src: helix }, drop: [...] }). Default: auto-detected MetaHuman, Meshy, or Mixamo map. */
     map?: string;
+    /** Rig coverage contract. Full characters require the complete humanoid anchors; Bridge add-ons may
+     * use a safely resolvable partial subset. Defaults to 'character'. */
+    rigScope?: CharacterRigScope;
     /** Canonical helix body GLB. Default: body-m-default.web.glb from the world's installed humanoid-character
      * pack when present, else the embedded helix-humanoid@1 skeleton snapshot (fully standalone). */
     canonical?: string;
@@ -17,8 +41,17 @@ export interface ImportCharacterOptions {
     output?: string;
     /** Output basename (default: derived from the body file name) -> <name>.web.glb. */
     name?: string;
-    /** Triangle target per LOD level, high->low (default [10000, 5000, 1500]). */
+    /** Triangle target per LOD level, high->low. Default: the slot-aware ladder for `slotType` (an add-on
+     *  with a known slot — see `slotBudgets.ts`), else [10000, 5000, 1500]. An explicit value is honoured
+     *  exactly (Bridge profile `lodTris`, #218) but is still held to the slot's combined ceiling. */
     lodTris?: number[];
+    /**
+     * The add-on's published slot type (`character.top@1`, …), `rigScope: 'addon'` only. Makes packaging
+     * aim at — and verify against — the ceiling the server applies to that slot at publish (combined
+     * triangles across every LOD, materials, texture edge), read from the server's own source via
+     * `slotBudgets.generated.ts`. Undefined: no slot budget (the generic ladder, no combined check).
+     */
+    slotType?: string;
     /** Texture longest-edge cap (default 1024); the bake route halves it per LOD level like a mip chain. */
     texSize?: number;
     /** KTX2 codec per LOD level (a shorter list repeats its last entry; a single value = all levels).
@@ -26,21 +59,82 @@ export interface ImportCharacterOptions {
      * levels where its block artifacts are invisible. */
     ktxModes?: Ktx2Mode[];
     ktxQuality?: number;
+    /** Encode textures to KTX2/Basis (default true). Disable to keep the source PNG/JPEG textures —
+     * for pipelines that must scan or re-encode the images downstream (e.g. a moderation gate that
+     * can only decode png/jpeg, followed by a server-side KTX2 optimize pass). */
+    ktx2?: boolean;
     /** Meshopt error budget (default 0.02 — imports resist collapse). */
     simplifyError?: number;
     /** Preserve UV-seam/material-boundary verts during decimation (default false for imports). */
     lockBorder?: boolean;
     /** Force (true) or disable (false) the weld+unwrap+rebake path; undefined = auto-detect micro-chart atlases. */
     bake?: boolean;
+    /** 'source' fits a canonical rig to source joints; 'canonical' reposes geometry to the pinned
+     * rest; 'host-aligned' preserves geometry already authored in the host's mesh coordinates while
+     * rebinding to its exact skeleton. The last mode validates mapped anatomical anchors. */
+    fit?: 'source' | 'canonical' | 'host-aligned';
     /** Seam-weld fallback for floored far LODs on the non-bake path (default true; LOD0 never welds there). */
     weld?: boolean;
     /** Slice head-weighted triangles into a separate 'FaceMesh' node per LOD (default true), so the
      * runtime's first-person mode can hide the head like the stock character's face part. */
     splitFace?: boolean;
+    /**
+     * Face detail on the rebake route (micro-chart imports — Meshy/Dreamer avatars): the forward-facing head region
+     * (see stages/faceRegion.ts) keeps `triShare` of every LOD's triangle target instead of its ~3% uniform share, and
+     * its UV charts are scaled `texelBoost`x in the unwrap (capped at `maxAtlasShare` of the atlas) so eyes, brows and
+     * mouth keep the source's texel density. Default ON for full characters, OFF for add-ons (a garment has no face);
+     * `false` restores the area-blind decimate + unwrap.
+     */
+    faceDetail?: false | FaceDetailOptions;
     /** Directory whose installed packs are searched for the canonical body (default process.cwd()). */
     cwd?: string;
     /** Progress sink (default console.log). */
     onProgress?: (message: string) => void;
+    /** Optional source/license record. When present it is validated and embedded in the import receipt. */
+    provenance?: CharacterSourceProvenance;
+    /** Optional explicit helix/avatar-face@1 mapping JSON. Without it, safe known morph names are detected. */
+    faceMap?: string;
+    /** Reviewed HELIX Palette family selection. The palette JSON is an immutable Bridge input; authored
+     * textures and UVs are preserved while portable PBR defaults and the standard binding are applied. */
+    palette?: {
+        path: string;
+        selection: HelixPaletteSelection;
+    };
+    /**
+     * Conform-time poke-through push-out (`rigScope: 'addon'` only, and only when `canonical` names a real
+     * host body GLB — for a plain character import there is no worn-against body to push away from). Moves
+     * garment vertices that sit too close to the host body's surface out along the body's own normal by a
+     * small amount; see `addonPushOut.ts` for the algorithm and defaults. Pass `false` to disable it outright
+     * (e.g. a garment already proven poke-through-free, where the small extra pass is not worth the cost).
+     */
+    /**
+       * Full characters only: cut arm<->leg bridge geometry (a hand fused to the thigh by an A-pose mesher) and
+       * re-weight each side to its own limb, gated on a walk-stride stretch measure (see stages/limbBridge.ts).
+       * Default `{ mode: 'repair' }`; `{ mode: 'report' }` measures without changing anything; `false` skips it.
+       */
+    limbBridges?: LimbBridgeOptions | false;
+    pushOut?: PushOutOptions | false;
+    /**
+     * Pose-aware poke-through fit on the PACKAGED add-on (every LOD level), against the host body in the
+     * canonical pose set — see `stages/poseAwareFit.ts`. `rigScope: 'addon'` with a real host `canonical` only.
+     * Opt-in because the region scope is the SLOT's grant, which only the caller knows: pass
+     * `{ hiddenRegions: defaultHideRegionsForSlotType(slotType) }` (the Bridge add-on route does). Gated inside
+     * the stage: the packaged geometry changes only if the poke-through measurement is strictly better.
+     */
+    poseFit?: (PoseAwareFitOptions & {
+        hiddenRegions: readonly string[];
+    }) | false;
+    /**
+     * Hard ceiling on materials in the packaged (post-LOD-merge) document. Each LOD level bakes or
+     * resizes its own textures independently, so the SAME named material can legitimately carry
+     * different texture bytes per LOD — fine for most add-on slots, but a low-cap slot (mask/footwear)
+     * can trip its real publish ceiling this way even though no single LOD is out of budget on its own.
+     * When set and the merged document exceeds it, rebinds every primitive onto the document's
+     * dominant-by-triangle-count material (see `unifyDominantMaterial`) and joins same-material
+     * primitives within each LOD's own mesh (see `joinPrimitivesPerMesh`) to also cut the resulting
+     * draw-call count. Undefined (default): off — every LOD keeps its own materials untouched.
+     */
+    maxMaterials?: number;
 }
 export interface ImportCharacterClipResult {
     name: string;
@@ -50,6 +144,24 @@ export interface ImportCharacterClipResult {
     duration: number;
     animatedBones: string[];
 }
+export interface FaceDetailOptions {
+    /** Fraction of each LOD's triangle target reserved for the face (default 0.2). */
+    triShare?: number;
+    /** Linear texel-density multiplier for the face's charts (default 2.25 — ~the 2048px source density at 1024). */
+    texelBoost?: number;
+    /** Ceiling on the face's share of the packed atlas area (default 0.25). */
+    maxAtlasShare?: number;
+    /**
+     * Smallest LOD triangle target that still reserves `triShare` for the face (default 4000). Below it the level
+     * decimates area-blind: at 1500 tris a 20% face reserve starved the body to ~1200 and meshopt bridged arms to legs
+     * and hoodie to trousers with sheets (live job c92a1d22's LOD2: the "cloth panel" and "washed-out" walk-away frames).
+     * A far LOD is never seen up close, so the face buys nothing there. The texel boost still applies to every level.
+     */
+    minLevelTris?: number;
+}
+export declare const DEFAULT_FACE_DETAIL: Required<FaceDetailOptions>;
+/** The face's triangle reserve for one LOD level (0 = area-blind), given the resolved face-detail options. */
+export declare function faceTriShareForLevel(targetTris: number, faceDetail: Required<FaceDetailOptions> | null): number;
 export interface ImportCharacterResult {
     /** The packaged multi-LOD body: <out>/<name>.web.glb. */
     bodyPath: string;
@@ -62,15 +174,41 @@ export interface ImportCharacterResult {
         unmapped: string[];
         dropped: string[];
     };
-    conform: Pick<ConformResult, 'mode' | 'verticesProcessed' | 'jointsRebuilt'>;
-    /** Aggregated over the per-level encodes (each LOD may use a different codec). */
+    conform: Pick<ConformResult, 'mode' | 'unitScale' | 'restAimed' | 'verticesProcessed' | 'jointsRebuilt'>;
+    /** Aggregated over the per-level encodes (each LOD may use a different codec).
+     * With `ktx2: false` the encoder is 'skipped', modes is empty and before/after are 0. */
     ktx2: {
-        encoder: Ktx2Result['encoder'];
+        encoder: Ktx2Result['encoder'] | 'skipped';
         modes: Ktx2Mode[];
         before: number;
         after: number;
     };
     clip: ImportCharacterClipResult | null;
+    /** Machine-readable source, transform and output receipt written beside the packaged GLB. */
+    receiptPath: string;
+    face: {
+        capability: 'viseme15' | 'vowel5' | 'jaw' | 'none';
+        manifest: AvatarFaceManifestV1;
+    };
+    palette: HelixPaletteApplyResult | null;
+    /** Poke-through push-out report, or null when it did not run (not an addon, no host body, or disabled). */
+    limbBridges: LimbBridgeReport | null;
+    pushOut: PushOutReport | null;
+    /** Pose-aware fit report, or null when it did not run (not an addon, no host body, or not requested). */
+    poseFit: PoseAwareFitReport | null;
+}
+export interface RetargetAnimationOptions {
+    /** Raw Mixamo/Meshy animation FBX or GLB. */
+    animation: string;
+    map?: string;
+    canonical?: string;
+    clipName?: string;
+    /** Whether consumers should loop the clip. Defaults false for one-shot imports. */
+    loop?: boolean;
+    /** Output GLB path. Default: ./character-out/anims/<clipName>.glb. */
+    output?: string;
+    cwd?: string;
+    onProgress?: (message: string) => void;
 }
 /**
  * Finds the canonical helix body GLB inside the world's installed packs. First-party installs copy
@@ -79,10 +217,50 @@ export interface ImportCharacterResult {
  * the humanoid-character pack can satisfy the default — otherwise the caller must pass --canonical.
  */
 export declare function findCanonicalBody(cwd: string): string | null;
+export declare function selectDefaultBoneMap(source: Document, scope?: CharacterRigScope): BoneMap;
+export interface PreparedCharacterSource {
+    glb: CharacterSourcePreflight;
+    original: {
+        sha256: string;
+        sizeBytes: number;
+    };
+    convertedFromFbx: boolean;
+    materialSidecar: UnrealMaterialSidecarApplyResult | null;
+}
+export declare function prepareCharacterSource(sourcePath: string, outputDir: string, convertFbx?: (path: string) => Promise<Uint8Array>, 
+/**
+ * Downscale target for any embedded texture that exceeds the per-image 32MB ceiling, applied
+ * before that ceiling is enforced (see `downscaleOversizedTexturesAndRegate`). Defaults to 1024px,
+ * matching this module's own default publish resolution (`ImportCharacterOptions.texSize`) — the
+ * caller-visible slot-type distinction (1024 for most add-on slots, 2048 for a genuine
+ * `character.outfit@1` full-outfit slot) is NOT threaded down to this function: `importCharacter`
+ * already forwards its own resolved `texSize`/`texCap` here, so a caller that wants the 2048 cap for
+ * an outfit slot gets it automatically by passing `texSize: 2048`; the Bridge add-on entry point
+ * (`executeCharacterAddon`) does not do that today and so gets this 1024 default. That is a
+ * genuinely tighter cap than the platform's own 2048px wearable/add-on publish ceiling for a
+ * `character.outfit@1` item, but a correct and safe default for every slot type: it matches the
+ * pipeline's own existing default final-publish resolution (`ImportCharacterOptions.texSize`), so
+ * this pre-pass never produces a texture larger than what an unblocked item would already ship at
+ * today.
+ */
+textureEdgeCap?: number): Promise<PreparedCharacterSource>;
+/**
+ * Retargets one raw FBX/GLB directly to the platform clip format without
+ * requiring a separate body-conversion run.
+ */
+export declare function retargetAnimation(opts: RetargetAnimationOptions): Promise<ImportCharacterClipResult>;
+export interface CharacterGeometryBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+    size: [number, number, number];
+}
 /**
- * Converts an external biped character GLB into a helix-humanoid@1 drop-in, chaining the engine
- * pipeline's stages: rename the rig (retargetSkeleton) -> embed the canonical skeleton at the source's
- * proportions (conformToHelixRest) -> LODs (rebake route for micro-chart atlases) -> merge -> resize ->
- * KTX2 -> <out>/<name>.web.glb. With `anim`, also retargets the clip -> <out>/anims/<clipName>.glb.
+ * World-space geometry postcondition for runtime character packages.
+ *
+ * Measures what a glTF renderer draws at rest: each vertex skinned by its joints
+ * (`Σ weight · jointWorld · IBM · position`). The skinned mesh node's own transform is ignored by
+ * glTF skinning, so measuring `nodeWorld · position` instead can report a correct character at the
+ * wrong scale — or pass one that renders at the wrong scale.
  */
+export declare function assertCanonicalCharacterGeometry(doc: Document, scope: CharacterRigScope): CharacterGeometryBounds;
 export declare function importCharacter(opts: ImportCharacterOptions): Promise<ImportCharacterResult>;