/** * CharacterHost — entity-generic native character render driver. * * Owns one body (procedural `AgentAvatarMesh` by default; a glTF/VRM→DrawSpec upgrade is a * separate opt-in path), applies a pose each frame (skeleton FK → joint-matrix palette), and * emits a pure-data `CharacterDrawSpec` the native WebGPU renderer consumes (`renderCharacter`). * NO Three.js, NO R3F. * * The SAME host serves all three archetypes (D.094 entity-generic): * - human / avatar → posed by animation/author, * - embodied agent → posed + PLACED by an authoritative world-state driver keyed by * `entityId` (the WebGPU-native analogue of xr-embodiment's AgentAvatarTracker). * * Current scope includes body, skeleton-pose palette, locomotion, deterministic cloth, a bounded * native procedural-head FACS/viseme subset, world-state placement, and the D.102 portable-mind * seam. Production facial topology and activity-driven expressions remain later upgrade lanes. * * @module character-render */ import type { CharacterDrawSpec, MarschnerHairMaterialSpec, WovenClothTextureTile } from '../native-render/draw-spec'; import { type AgentAvatarAnatomyReceipt, type AgentAvatarFacialDetailProfile, type AgentAvatarFacialLandmarkReceipt, type AgentAvatarFaceTopology, type AgentAvatarHandSurfaceReceipt, type AgentAvatarJointDeformationReceipt, type AgentAvatarOrbitalGeometryReceipt, type AgentAvatarOrbitalProfile, type AgentAvatarUpperBodyProfile, type AvatarPose } from './AgentAvatarMesh'; import { type AgentAvatarGroomGeometryReceipt, type AgentAvatarGroomProfile, type AgentAvatarHairMaterialReceipt, type AgentAvatarHairStyle, type AgentAvatarSkinUvReceipt, type AgentAvatarOcularGeometryReceipt, type AgentAvatarOcularProfile } from './AgentAvatarHair'; import { type NativeMorphNormalPolicy, type NativeMorphReceipt, type NativeMorphWeights } from './AgentAvatarMorph'; import type { AgentAvatarGarmentGeometryReceipt, SovereignGarmentStyle, SovereignMantleStyle } from './AgentAvatarGarment'; import { type ClothSimulationConfig, type ClothSimulationReceipt } from './AgentAvatarCloth'; import { type CharacterMicroMotionApplicationReceipt, type CharacterMicroMotionSample } from './AgentAvatarMicroMotion'; import { type Quat } from './skin-math'; import { type GaitMode } from './gait'; import type { CharacterMind, MindIdentity, MindMemoryEntry } from './CharacterMind'; export interface CharacterHostOptions { /** Entity id — drives deterministic accent colour + world-state driver binding (D.094). */ entityId: string; /** 1.0 = 1.75 m reference figure. */ heightScale?: number; /** Limb/torso thickness multiplier. */ buildScale?: number; /** Source-authored facial topology. */ faceTopology?: AgentAvatarFaceTopology; /** Longitude segments for the neutral anatomical face. */ faceRadialSegments?: number; /** Latitude segments for the neutral anatomical face. */ faceVerticalSegments?: number; /** Include native eyelid/tearline rim topology. */ faceTearline?: boolean; /** Native orbital construction profile; legacy tearline rims remain the default. */ orbitalProfile?: AgentAvatarOrbitalProfile; /** Globe recession as a fraction of the procedural eyeball radius (0..0.45). */ eyeRecess?: number; /** Vertical palpebral opening as a fraction of the eyeball radius (0.42..0.78). */ lidOpening?: number; /** Outer-canthus rise as a fraction of the eyeball radius (-0.25..0.25). */ canthalTilt?: number; /** Optional denser facial landmark profile. */ facialDetailProfile?: AgentAvatarFacialDetailProfile; /** Procedural ocular globe scale (0.72..1.08). */ eyeScale?: number; /** Interocular spacing relative to the anatomical-head baseline. */ eyeSpacing?: number; /** Brow rise above the upper lid, in eye-radius units. */ browHeight?: number; /** Brow ribbon thickness, in eye-radius units. */ browThickness?: number; /** Native ear scale. */ earScale?: number; /** Lip-volume depth multiplier. */ mouthDepth?: number; /** Nasal bridge width relative to the portrait facial-volume baseline. */ noseBridgeWidth?: number; /** Nasal vertical length relative to the portrait facial-volume baseline. */ noseLength?: number; /** Nasal forward projection relative to the portrait facial-volume baseline. */ noseProjection?: number; /** Mouth width relative to the anatomical lip baseline. */ mouthWidth?: number; /** Upper-lip soft-tissue fullness relative to the anatomical lip baseline. */ upperLipFullness?: number; /** Lower-lip soft-tissue fullness relative to the anatomical lip baseline. */ lowerLipFullness?: number; /** Portrait-silhouette-v2 cheek-volume multiplier. */ cheekboneScale?: number; /** Portrait-silhouette-v2 forward chin projection. */ chinProjection?: number; /** Portrait-silhouette-v2 temple-width multiplier. */ templeWidth?: number; /** Portrait-facial-planes-v6 brow/malar/jaw plane strength. */ facialPlaneStrength?: number; /** * Expression-time normal handling. The compatibility default preserves authored normals; * H3X can opt into deterministic recomputation around deformed facial vertices. */ expressionNormalPolicy?: NativeMorphNormalPolicy; /** Neutral-head width multiplier (0.84..1.2). */ faceWidth?: number; /** Neutral-head vertical-length multiplier (0.86..1.16). */ faceLength?: number; /** Lower-face width reduction (0.08..0.38). */ jawTaper?: number; /** Bind-space shoulder/arm span multiplier (0.85..1.25). */ shoulderScale?: number; /** Hips/spine thickness multiplier (0.85..1.2). */ torsoScale?: number; /** Source-authored native upper-body construction. */ upperBodyProfile?: AgentAvatarUpperBodyProfile; /** Circumferential topology budget for the connected upper-body loft. */ upperBodyRadialSegments?: number; /** V7 independent left scapular elevation (-1..1). */ leftScapularElevation?: number; /** V7 independent right scapular elevation (-1..1). */ rightScapularElevation?: number; /** V7 independent left scapular forward/back travel (-1..1). */ leftScapularProtraction?: number; /** V7 independent right scapular forward/back travel (-1..1). */ rightScapularProtraction?: number; /** Packed 0xRRGGBB keratin nail-plate colour for coherent-hand-landmarks-v3. */ nailTone?: number; /** Keratin nail-plate microsurface roughness (0.08..0.65). */ nailRoughness?: number; /** Explicit proximal nail-bed colour for fixed-light material calibration. */ nailBedTone?: number; /** Proximal nail-bed microsurface roughness (0.12..0.72). */ nailBedRoughness?: number; /** Opt-in analytic material calibration. Legacy characters retain their original draw schedule. */ materialCalibrationProfile?: AgentAvatarMaterialCalibrationProfile; /** Packed 0xRRGGBB accent/fallback colour; defaults to a deterministic colour from `entityId`. */ color?: number; /** Skin base colour 0xRRGGBB for the SSS material (default warm skin #e8c4a0). */ skinTone?: number; /** * Authored subsurface scatter colour in linear RGB. Omitted characters retain the * human-skin preset; non-human/sovereign bodies can provide their own material response. */ skinScatterColor?: [number, number, number]; /** Provider-independent native skin microdetail profile. */ skinMicrodetailProfile?: AgentAvatarSkinMicrodetailProfile; /** Analytic pore frequency in inverse metres. */ skinMicrodetailScale?: number; /** Bounded analytic roughness-response amplitude. */ skinMicrodetailStrength?: number; /** * Opt-in decoupled skin-surface response. Omission preserves the legacy coupled * albedo/roughness response and its byte-compatible material packing. */ skinSurfaceResponseProfile?: AgentAvatarSkinSurfaceResponseProfile; /** Independent analytic base-colour variation amplitude. */ skinAlbedoVariationStrength?: number; /** Independent analytic microsurface roughness variation amplitude. */ skinRoughnessVariationStrength?: number; /** Tangent-plane analytic fine-normal response amplitude. */ skinNormalMicrodetailStrength?: number; /** Source-authored bind-space facial colour response. */ skinComplexionProfile?: AgentAvatarSkinComplexionProfile; /** Bounded strength of the anatomical complexion response. */ skinComplexionStrength?: number; /** UV-driven portrait texture-space response. */ skinTextureSpaceProfile?: AgentAvatarSkinTextureSpaceProfile; /** Bounded UV-space albedo and microsurface contribution. */ skinTextureSpaceStrength?: number; /** Hair eumelanin 0..1 (0 = white/blond, ~0.9 = black). Default 0.7 (dark brown). */ melanin?: number; /** Hair pheomelanin/redness 0..1. Default 0.2. */ melaninRedness?: number; /** Exact source-authored @hair(color) value. Omission preserves melanin-only hair shading. */ hairTone?: number; /** Source-authored deterministic procedural hair geometry profile. */ hairStyle?: AgentAvatarHairStyle; /** Source-authored scalp guide budget selected by @lod. */ hairGuides?: number; /** Source-authored cards-per-guide budget selected by @lod. */ hairCardsPerGuide?: number; /** Source-authored points-per-guide budget selected by @lod. */ hairSegments?: number; /** Source-authored native groom construction algorithm. */ hairGroomProfile?: AgentAvatarGroomProfile; /** Source-authored card width in metres. */ hairCardWidth?: number; /** Source-authored scalp shell lift in metres. */ hairRootLift?: number; /** Source-authored tip/root card-width ratio. */ hairTipTaper?: number; /** Source-authored front hairline retraction. */ hairlineBias?: number; /** Signed crown-flow rotation around the scalp normal. */ hairCrownWhorl?: number; /** Optional angular groom cluster count. */ hairClusterCount?: number; /** Fraction of each groom cluster sector occupied by roots. */ hairClusterSpread?: number; /** Source-authored analytic hair-card coverage profile. */ hairCoverageProfile?: MarschnerHairMaterialSpec['coverageProfile']; /** Visible normalized card half-width (0.2..1). */ hairStrandCoverage?: number; /** Analytic card edge transition (0.01..0.5). */ hairEdgeSoftness?: number; /** Strand-tangent contribution to the highlight response (0..1). */ hairAnisotropyStrength?: number; /** Longitudinal tangent/normal lobe shift (-0.35..0.35). */ hairLongitudinalShift?: number; /** Layered card density and root-occlusion response. */ hairDensityProfile?: MarschnerHairMaterialSpec['densityProfile']; /** Layered analytic card-opacity contribution. */ hairDensityStrength?: number; /** Analytic root darkening/occlusion contribution. */ hairRootShadowStrength?: number; /** Iris colour 0xRRGGBB (default warm brown #4a3520). */ irisColor?: number; /** Native eye construction profile; legacy composite remains the compatibility default. */ ocularProfile?: AgentAvatarOcularProfile; /** Visible iris radius as a fraction of the eyeball radius (0.34..0.62). */ irisScale?: number; /** Pupil radius as a fraction of the iris radius (0.2..0.72). */ pupilScale?: number; /** Sclera base colour 0xRRGGBB (default warm off-white #eeeae3). */ scleraColor?: number; /** Cornea index of refraction (default 1.376). */ corneaIor?: number; /** Initial world position. */ position?: [number, number, number]; /** Operative native garment preset selected by @clothing. */ garmentStyle?: SovereignGarmentStyle; /** Packed 0xRRGGBB cloth base colour. */ garmentColor?: number; /** Authored radial topology selected by @lod. */ garmentSegments?: number; /** Optional detachable public/story mantle selected by @clothing(mantle_style). */ mantleStyle?: SovereignMantleStyle; /** Packed 0xRRGGBB mantle base colour. */ mantleColor?: number; /** Source-authored deterministic cloth dynamics. Omission keeps the rest-pose garment. */ clothSimulation?: Partial; /** Procedural hair can be suppressed by a closed hood. */ includeHair?: boolean; /** Procedural eyes can be suppressed by a faceless visor. */ includeEyes?: boolean; } export type AgentAvatarSkinMicrodetailProfile = 'none' | 'analytic-pore-v1'; export type AgentAvatarSkinSurfaceResponseProfile = 'calibrated-skin-surface-v1'; export type AgentAvatarSkinComplexionProfile = 'anatomical-complexion-v1'; export type AgentAvatarSkinTextureSpaceProfile = 'portrait-texture-space-v1'; export type AgentAvatarMaterialCalibrationProfile = 'legacy-v1' | 'fixed-light-human-v1'; interface AgentAvatarSkinMaterialReceiptBase { calibrationProfile: AgentAvatarMaterialCalibrationProfile; shadingModel: 'skin-sss'; color: number; scatterColor: [number, number, number]; scatterRadii: [number, number, number]; specularF0: number; thickness: number; transmitStrength: number; ambient: number; microdetailProfile: AgentAvatarSkinMicrodetailProfile; microdetailScale: number; microdetailStrength: number; roughness: number; } export interface AgentAvatarSkinMaterialReceiptV2 extends AgentAvatarSkinMaterialReceiptBase { schemaVersion: 'holoscript.agent-avatar-skin-material.v2'; } export interface AgentAvatarSkinMaterialReceiptV3 extends AgentAvatarSkinMaterialReceiptBase { schemaVersion: 'holoscript.agent-avatar-skin-material.v3'; surfaceResponseProfile: AgentAvatarSkinSurfaceResponseProfile; albedoVariationStrength: number; roughnessVariationStrength: number; normalMicrodetailStrength: number; } export interface AgentAvatarSkinMaterialReceiptV4 extends Omit { schemaVersion: 'holoscript.agent-avatar-skin-material.v4'; complexionProfile: AgentAvatarSkinComplexionProfile; complexionStrength: number; } export interface AgentAvatarSkinMaterialReceiptV5 extends Omit { schemaVersion: 'holoscript.agent-avatar-skin-material.v5'; textureSpaceProfile: AgentAvatarSkinTextureSpaceProfile; textureSpaceStrength: number; uv: AgentAvatarSkinUvReceipt; } export type AgentAvatarSkinMaterialReceipt = AgentAvatarSkinMaterialReceiptV2 | AgentAvatarSkinMaterialReceiptV3 | AgentAvatarSkinMaterialReceiptV4 | AgentAvatarSkinMaterialReceiptV5; /** Authoritative world-state for an embodied agent (subset of xr-embodiment's WorldStateSource). */ export interface CharacterWorldState { position?: { x?: number; y?: number; z?: number; }; /** Facing yaw in radians (rotation about Y). */ rotationY?: number; /** Activity intent (e.g. 'idle' | 'walk' | 'speak') — Phase 1 maps to gait/visemes. */ activity?: string; } export declare class CharacterHost { readonly entityId: string; private readonly built; private readonly faceTopology; private readonly expressionNormalPolicy; private readonly bindWorld; private readonly inverseBind; private readonly material; private readonly materialCalibrationProfile; private readonly skinMaterial; private readonly nailMaterial; private readonly nailBedMaterial; private readonly hairMaterial; private readonly eyeMaterial; private readonly scleraMaterial; private readonly irisMaterial; private readonly pupilMaterial; private readonly corneaMaterial; private readonly garmentMaterial; private readonly mantleMaterial; private readonly visorMaterial; private readonly clothSimulation; private lastClothReceipt; private deformationBasePositions; private readonly deformationBaseNormals; private morphWeights; private microMotionBlinkWeight; private microMotionSample; private lastNativeMicroMotionReceipt; private lastMorphReceipt; private modelMatrix; private pose; private mind; private boundIdentity; private memory; constructor(opts: CharacterHostOptions); /** Replace the whole pose (per-bone local rotations). Absent bones default to bind. */ setPose(pose: AvatarPose): void; /** Set a single bone's local rotation (e.g. raise an arm). */ setBoneRotation(bone: string, rotation: Quat): void; /** * Drive the skeletal pose from a locomotion gait at time `t` (seconds). Replaces the pose * with a walk/run stride cycle or an idle rest (modes track `LocomotionConfig.mode`). */ applyLocomotion(mode: GaitMode, t: number, speed?: number): void; /** Place the figure at a world position (yaw 0). */ setPosition(x: number, y: number, z: number): void; /** * Drive the body from authoritative world-state (embodied-agent path). Sets root * position + facing yaw. Activity→gait/visemes is a Phase-1 seam (currently a no-op on pose). */ applyWorldState(state: CharacterWorldState): void; /** * Deterministically sample authored cloth dynamics at absolute time. Sampling the same time * always restarts from the same bind-space state and emits the same position digest. */ sampleClothSimulation(timeSeconds: number): ClothSimulationReceipt | null; /** Latest deterministic cloth receipt, or null when the source did not author cloth dynamics. */ getClothSimulationReceipt(): ClothSimulationReceipt | null; /** Derived bind-space evidence for the operative native procedural groom. */ getGroomGeometryReceipt(): AgentAvatarGroomGeometryReceipt | null; /** Exact clamped native face and upper-body proportions used by the emitted geometry. */ getAnatomyReceipt(): AgentAvatarAnatomyReceipt; /** Exact operative dual-influence zones emitted by the selected procedural profile. */ getJointDeformationReceipt(): AgentAvatarJointDeformationReceipt | null; /** Exact V5 digit, commissure, nail/cuticle, and wrist-transition topology evidence. */ getHandSurfaceReceipt(): AgentAvatarHandSurfaceReceipt | null; /** Exact native civic facial-landmark topology and authored controls, when selected. */ getFacialLandmarkReceipt(): AgentAvatarFacialLandmarkReceipt | null; /** Exact native orbital construction receipt, including H4K head-shell stitching. */ getOrbitalGeometryReceipt(): AgentAvatarOrbitalGeometryReceipt | null; /** Exact native garment preset and emitted topology, when @clothing is operative. */ getGarmentGeometryReceipt(): AgentAvatarGarmentGeometryReceipt | null; /** Exact native ocular construction receipt, including H3Z tear-meniscus topology. */ getOcularGeometryReceipt(): AgentAvatarOcularGeometryReceipt | null; /** Exact native skin-surface response derived from @subsurface_scattering. */ getSkinMaterialReceipt(): AgentAvatarSkinMaterialReceipt; /** Source-derived native hair response joined to geometry and compiler receipts. */ getHairMaterialReceipt(): AgentAvatarHairMaterialReceipt; /** * Apply the native procedural-head FACS/viseme subset to real mesh vertices. * * Every call starts from the current neutral/cloth deformation base, so weights are absolute * rather than cumulatively drifting. Unsupported names are preserved in the returned receipt. */ applyMorphWeights(weights: NativeMorphWeights): NativeMorphReceipt; /** * Bind one absolute-time sample to native eyelid, ocular-globe, and upper-chest deformation. * * Authored expression weights remain the baseline, and every application restarts from the * current neutral/cloth base so repeated or out-of-order samples cannot accumulate drift. */ applyMicroMotionSample(sample: CharacterMicroMotionSample): CharacterMicroMotionApplicationReceipt; private applyResolvedMorphWeights; /** Latest native facial deformation receipt, or null until morph weights are applied. */ getMorphReceipt(): NativeMorphReceipt | null; /** Apply a source-resolved local UV texture tile to the detachable mantle material. */ setMantleTextureTile(textureTile: WovenClothTextureTile | undefined): void; /** * Emit the current frame's pure-data character draw spec for the native WebGPU renderer. * The compatibility body renders as one SSS-skin material group. V3 keratin nail plates * are excluded from those skin slices and receive their own SSS-derived material groups; * `material` remains the lambert fallback for callers that render without groups. */ getDrawSpec(): CharacterDrawSpec; /** * Bind a portable mind to this body: adopt its wallet identity and load its wallet-scoped * memory (private:) so the SAME agent inhabits the body across substrates (Jetson → * headset). Degrades to body-only on any failure — NEVER throws, and never changes how the * body renders (getDrawSpec is byte-identical with or without a bound mind). */ bindMind(mind: CharacterMind, query?: string, limit?: number): Promise; /** The bound mind's identity (wallet + agent id), or null if no mind is bound. */ getIdentity(): MindIdentity | null; /** A copy of the loaded wallet-scoped memory (empty if no mind / load failed). */ getMemory(): MindMemoryEntry[]; /** True once a mind has been bound (regardless of whether memory loaded). */ hasMind(): boolean; } export {}; //# sourceMappingURL=CharacterHost.d.ts.map