@npcify/web 0.5.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -122,13 +122,16 @@ animate()
122
122
  - `character.animation.activeAction`: Active `THREE.AnimationAction | null`.
123
123
  - `await character.animation.play(animationId, { fadeDuration, loop })`: Automatically fetches lazy animations if needed and cross-fades.
124
124
  - `character.animation.playIdle(fadeDuration)` / `character.animation.stop(fadeDuration)`.
125
+ - Each clip keeps the character's hands out of its own torso, hips, skirt and legs: the upper arm turns at the shoulder by the smallest rotation that is necessary (0.7.1). Clips made on a slimmer body otherwise put the hands inside a fuller character.
125
126
  - **Dialogue & Speech State**:
126
127
  - `character.speaking`, `character.thinking`, `character.currentSpeech`, `character.currentText`, `character.revealedText`, `character.options`, `character.cursor`, `character.speech`.
127
128
  - `await character.createConversation()`, `await character.sendMessage(text)`, `await character.endConversation()`.
129
+ - `character.setMemoryIdentifier(id)` / `character.getMemoryIdentifier()`: Set or read the SDK player memory identifier (`string | null | undefined`, up to 128 characters). When **SDK Player Memory** is enabled in **Export → Web SDK**, passing a non-empty identifier isolates memories per player; passing an empty string, `null`, or omitting `memoryIdentifier` stores memories in the character owner's dashboard bucket (**Dashboard → Memory**).
128
130
  - `character.onConnectionClosed(callback)`: The server closed the conversation connection ([lifecycle](#runtime-and-lifecycle)).
129
131
  - **Voice Input** ([details](#voice-input-and-input-modes)):
130
132
  - `character.bindPushToTalk(options)`, `character.startListening(options)`, `character.stopListening()`, `character.cancelListening()`.
131
133
  - `character.listeningState`, `character.onListeningState(callback)`, `character.onTranscript(callback)`, `character.inputModes`.
134
+ - `character.notifyUserTyping(active)`, `character.playerActivity`, `character.onPlayerActivity(callback)`: listening reflexes ([details](#voice-input-and-input-modes)).
132
135
  - `await character.dispose()`: Ends conversation, detaches from the scene, removes the audio element, and disposes VRM GPU resources.
133
136
  - **Sight** ([details](#sight)):
134
137
  - `character.startSight(options)`, `character.stopSight()`, `character.sightState`, `character.onSightState(callback)`, `character.onSight(callback)`.
@@ -239,6 +242,13 @@ character.onListeningState((state) => {
239
242
  text when the server's speech model gives it.
240
243
  - The first press or `startListening()` asks for the microphone permission.
241
244
  An empty result sends nothing.
245
+ - Listening reflexes: while the player holds to talk, the character looks at
246
+ the player, shows a subtle attentive face and nods lightly at pauses. Call
247
+ `notifyUserTyping(true)` from the text field's `input` event (and `false`
248
+ after a send) for the same gaze and face while the player types; typing
249
+ ends 1.5 s after the last input. A reply takes over at once. This is local:
250
+ no request and no cost. `playerActivity` is `'idle'`, `'typing'` or
251
+ `'speaking'`.
242
252
  - `language` is an optional BCP 47 hint (`'zh'`, `'ja'`, `'en'`). Without it,
243
253
  the server detects the language.
244
254
  - `inputModes` (an option of `mountNpcify`, `loadCharacter` and `Npcify`) is
package/dist/index.d.ts CHANGED
@@ -49,6 +49,39 @@ type SightObservationEvent = {
49
49
  type TtsProviderId = string;
50
50
  type NullableTtsProviderId = TtsProviderId | null;
51
51
 
52
+ declare const DEFAULT_VARIANT_KEY: "default";
53
+ declare const NUDE_VARIANT_KEY: "nude";
54
+ interface AvatarVariantSummary {
55
+ key: string;
56
+ label: string;
57
+ description: string;
58
+ r18: boolean;
59
+ portraitUrl: string | null;
60
+ creditText?: string | null;
61
+ }
62
+ declare const STAGING_TOOL_NAMES: readonly ["switch_variant"];
63
+ type StagingToolName = (typeof STAGING_TOOL_NAMES)[number];
64
+ declare const STAGING_TOOL_RESULT_STATUSES: readonly ["applied", "noop", "rejected"];
65
+ type StagingToolResultStatus = (typeof STAGING_TOOL_RESULT_STATUSES)[number];
66
+ interface StagingSwitchVariantArguments {
67
+ variant: string;
68
+ }
69
+ interface StagingToolCallResult {
70
+ ok: boolean;
71
+ status: StagingToolResultStatus;
72
+ previousVariant: string;
73
+ activeVariant: string;
74
+ error?: string;
75
+ }
76
+ interface StagingToolCall {
77
+ id: string;
78
+ name: StagingToolName;
79
+ /** Seconds from the start of the staging. */
80
+ timestamp: number;
81
+ arguments: StagingSwitchVariantArguments;
82
+ result: StagingToolCallResult;
83
+ }
84
+
52
85
  declare const EXPRESSION_CALL_RANGES: readonly ["linear", "bool"];
53
86
  type ExpressionCallRange = (typeof EXPRESSION_CALL_RANGES)[number];
54
87
  type ExpressionCallRangeMap = Record<string, ExpressionCallRange>;
@@ -90,6 +123,7 @@ interface AvatarPublicInfo {
90
123
  freeFirstNMessages?: number | null;
91
124
  hostedCharacterEnabled?: boolean;
92
125
  listedPublicly?: boolean;
126
+ allowFork?: boolean;
93
127
  r18?: boolean;
94
128
  bakedConversationEnabled?: boolean;
95
129
  bakedConversationRevision?: number;
@@ -105,7 +139,17 @@ interface AvatarPublicInfo {
105
139
  serverRenderingEnabled: boolean;
106
140
  /** The character's body motion is generated live in each turn (missing on older servers). */
107
141
  realtimeMotionEnabled?: boolean;
142
+ /** After the free messages, the player pays live motion and speech recognition (missing on older servers: off). */
143
+ playerPaysAiCosts?: boolean;
144
+ /** On the hosted web page, the character reads and saves memories about signed-in players (missing on older servers: off). */
145
+ memoryEnabled?: boolean;
146
+ /** In SDK chats, the character reads and saves memories keyed by memoryIdentifier or the owner when empty (missing on older servers: off). */
147
+ sdkMemoryEnabled?: boolean;
148
+ /** On live turns, the character gets the player's local message time (missing on older servers: off). */
149
+ messageTimeEnabled?: boolean;
108
150
  cameraSqt?: Sqt | null;
151
+ /** Allowed appearance variants (`default` first) when the character has variants. */
152
+ variants?: AvatarVariantSummary[];
109
153
  }
110
154
 
111
155
  interface UsageChargeSummary {
@@ -131,6 +175,9 @@ interface ConversationWorldlineStaging {
131
175
  text: string;
132
176
  options: ConversationOption[];
133
177
  createdAt: string;
178
+ initialVariant?: string;
179
+ activeVariant?: string;
180
+ toolCalls?: StagingToolCall[];
134
181
  }
135
182
  interface ConversationWorldline {
136
183
  conversationId: string;
@@ -286,6 +333,12 @@ interface StagingTimeline {
286
333
  motions?: StagingMotionClip[];
287
334
  /** Stored live motion frames, on reads of a completed staging (NPCP 1.1). */
288
335
  motion?: StagingMotionTrack;
336
+ /** Variant active at the start of the staging (NPCP 1.2; default is `default`). */
337
+ initialVariant?: string;
338
+ /** Variant active at the end of the staging (NPCP 1.2; default is `default`). */
339
+ activeVariant?: string;
340
+ /** Recorded agent tool calls and results on the staging clock (NPCP 1.2). */
341
+ toolCalls?: StagingToolCall[];
289
342
  }
290
343
  declare const STAGING_PROTOCOL_VERSION: 1;
291
344
  interface StagingResultPayload {
@@ -455,7 +508,31 @@ interface ConversationTurnOptions {
455
508
  requestId?: string;
456
509
  }
457
510
 
458
- type NpcifyAssetInfo = Pick<AvatarPublicInfo, 'animations' | 'idleAnimationId' | 'bakedConversationEnabled' | 'bakedConversationRevision'> & Partial<Pick<AvatarPublicInfo, 'allowCustomReply' | 'speechInputEnabled' | 'sight'>>;
511
+ type NpcifyAssetInfo = Pick<AvatarPublicInfo, 'animations' | 'idleAnimationId' | 'bakedConversationEnabled' | 'bakedConversationRevision'> & Partial<Pick<AvatarPublicInfo, 'allowCustomReply' | 'speechInputEnabled' | 'sight' | 'sdkMemoryEnabled' | 'variants'>>;
512
+ interface FetchVrmDownloadUrlOptions {
513
+ apiToken?: string;
514
+ assetProfile?: 'original' | 'web-optimized-v1';
515
+ signal?: AbortSignal;
516
+ }
517
+ type ResourceProgressCallback = (resourceId: string, loaded: number, total: number) => void;
518
+ declare const fetchVrmDownloadUrl: (baseUrl: string, characterId: string, options?: FetchVrmDownloadUrlOptions) => Promise<string>;
519
+ declare const fetchVariantVrmDownloadUrl: (baseUrl: string, characterId: string, variantKey: string, options?: FetchVrmDownloadUrlOptions) => Promise<string>;
520
+ declare const loadVrm: ({ baseUrl, characterId, variantKey, apiToken, onProgress, assetProfile, }: {
521
+ baseUrl: string;
522
+ characterId: string;
523
+ variantKey?: string;
524
+ apiToken?: string;
525
+ assetProfile?: "original" | "web-optimized-v1";
526
+ onProgress?: ResourceProgressCallback;
527
+ }) => Promise<VRM>;
528
+ declare const loadVariantVrm: ({ baseUrl, characterId, variantKey, apiToken, onProgress, assetProfile, }: {
529
+ baseUrl: string;
530
+ characterId: string;
531
+ variantKey: string;
532
+ apiToken?: string;
533
+ assetProfile?: "original" | "web-optimized-v1";
534
+ onProgress?: ResourceProgressCallback;
535
+ }) => Promise<VRM>;
459
536
 
460
537
  interface LlmThinkingPayload {
461
538
  taskId?: string | null;
@@ -736,6 +813,7 @@ interface AnimationControllerLike {
736
813
  previewAnimation?: (animation: VRMAnimation) => () => void;
737
814
  hasAnimation?: (id: string) => boolean;
738
815
  addAnimation?: (animationId: string, animation: VRMAnimation, config?: AnimationConfig) => void;
816
+ setVrm?: (nextVrm: VRM, rawAnimations: ReadonlyMap<string, VRMAnimation>) => void;
739
817
  clearAnimations?: () => void;
740
818
  setIdleAnimation?: (animationId: string | null) => void;
741
819
  getAnimationMixer?: () => AnimationMixer;
@@ -755,9 +833,9 @@ declare class RemoteAnimationController implements AnimationControllerLike {
755
833
  update(_delta: number): void;
756
834
  }
757
835
  declare class AnimationController implements AnimationControllerLike {
758
- private readonly vrm;
836
+ private vrm;
759
837
  prepareAnimations?: (ids: string[]) => Promise<void>;
760
- private readonly mixer;
838
+ private mixer;
761
839
  private readonly clips;
762
840
  private readonly rawClips;
763
841
  private readonly normalizedIdleClips;
@@ -770,6 +848,7 @@ declare class AnimationController implements AnimationControllerLike {
770
848
  private idleAnimationId;
771
849
  private pendingReturnToIdleAction;
772
850
  constructor(vrm: VRM, idleAnimationId?: string | null, options?: AnimationControllerOptions);
851
+ setVrm(nextVrm: VRM, rawAnimations: ReadonlyMap<string, VRMAnimation>): void;
773
852
  getAnimationMixer(): AnimationMixer;
774
853
  getActiveAction(): AnimationAction | null;
775
854
  getActiveAnimationId(): string | null;
@@ -929,8 +1008,11 @@ declare class FacialPerformanceMixer {
929
1008
  private restoreMouthAfterVisemeRelease;
930
1009
  private idleFace;
931
1010
  private gazeTarget;
1011
+ private readonly listeningFace;
932
1012
  constructor(recorder?: PerformanceRecorder | undefined, options?: FacialPerformanceMixerOptions);
933
- setVrm(vrm: VRM | null): void;
1013
+ setVrm(vrm: VRM | null, options?: {
1014
+ preserveState?: boolean;
1015
+ }): void;
934
1016
  getChannelNames(): string[];
935
1017
  getEmotionChannelNames(): string[];
936
1018
  getVisemeChannelNames(): string[];
@@ -948,6 +1030,17 @@ declare class FacialPerformanceMixer {
948
1030
  /** Blend temporary emotions without changing timeline targets or mouth ownership. */
949
1031
  setOverlay(weights: Readonly<Record<string, number>>): void;
950
1032
  clearOverlay(): void;
1033
+ /**
1034
+ * The attentive face of the listening reflexes (`relaxed`, else `happy`)
1035
+ * at `weight`. It eases in and out on its own layer, gives way to any
1036
+ * emotion and leaves the mouth layers alone. `immediate` with weight 0
1037
+ * removes it in this frame.
1038
+ */
1039
+ setListeningFace(weight: number, options?: {
1040
+ immediate?: boolean;
1041
+ }): void;
1042
+ /** The preset of the attentive face, or null when the model has none. */
1043
+ get listeningFaceChannel(): string | null;
951
1044
  releaseVisemeMouthMode(): void;
952
1045
  /**
953
1046
  * Ends the speech source without disturbing any other performance layer.
@@ -1087,6 +1180,8 @@ type StagingPlaybackOptions = {
1087
1180
  onCharacter?: (speech: StagingSpeechBlock, characterIndex: number, character: string) => void;
1088
1181
  onSpeechStart?: (speech: StagingSpeechBlock) => void;
1089
1182
  onTimelineStart?: (timeline: StagingTimeline) => void;
1183
+ onToolCall?: (toolCall: StagingToolCall) => void;
1184
+ onVariantCue?: (variantKey: string, toolCall: StagingToolCall | null) => Promise<void> | void;
1090
1185
  onPhonemePlayback?: (speech: StagingSpeechBlock, stats: {
1091
1186
  phonemeCount: number;
1092
1187
  latePhonemeCount: number;
@@ -1109,6 +1204,9 @@ declare class StagingPlayer {
1109
1204
  private activeExpressionMouthMode;
1110
1205
  private activeAnimation;
1111
1206
  private currentTrackTime;
1207
+ private playbackElapsed;
1208
+ private readonly appliedToolCallIds;
1209
+ private activeOptions?;
1112
1210
  constructor(audioPlayer: AudioPlayer, facialMixer: FacialPerformanceMixer, animationController: AnimationControllerLike);
1113
1211
  get paused(): boolean;
1114
1212
  /**
@@ -1132,6 +1230,7 @@ declare class StagingPlayer {
1132
1230
  private playSpeechAttempt;
1133
1231
  private playSilentSpeech;
1134
1232
  private playTimedRange;
1233
+ private applyToolCalls;
1135
1234
  private applyTracks;
1136
1235
  private clearPerformance;
1137
1236
  }
@@ -1213,7 +1312,7 @@ declare class CharacterSceneRig {
1213
1312
  /** The target that setVrmLookAtTarget set on the current model. */
1214
1313
  private vrmLookAtTarget;
1215
1314
  get vrm(): VRM | null;
1216
- setVrm(vrm: VRM | null): void;
1315
+ setVrm(vrm: VRM | null, fallbackParent?: Object3D | null): void;
1217
1316
  /**
1218
1317
  * The `Object3D` of a `lookAt()` argument: an `Object3D` as it is, a point
1219
1318
  * or three coordinates as a world position that this rig keeps, or null.
@@ -1262,6 +1361,7 @@ declare class CharacterSceneRig {
1262
1361
  /** Re-index meshes, materials, and skeletons after custom scene graph edits. */
1263
1362
  refreshMeshes(): void;
1264
1363
  disposeVrm(): void;
1364
+ disposeAllVrms(vrms: Iterable<VRM>): void;
1265
1365
  private applyShadows;
1266
1366
  private applyTransform;
1267
1367
  }
@@ -1294,7 +1394,19 @@ interface NpcifyOptions {
1294
1394
  };
1295
1395
  /** Editing uses live generation even when the character is published as baked. */
1296
1396
  authoring?: boolean;
1397
+ /** Marks conversations started on `/npcs/:id` on the website; ignored when an API key is used. */
1398
+ hostedWebChat?: boolean;
1399
+ /**
1400
+ * Developer-supplied player identifier for SDK memory. Leave empty or omit
1401
+ * to share and manage SDK memories in Dashboard -> Memory.
1402
+ */
1403
+ memoryIdentifier?: string | null;
1297
1404
  bakedConversation?: BakedConversationAsset | string | ArrayBuffer | Uint8Array;
1405
+ /**
1406
+ * Optional loader of a variant's VRM. Without it the client asks the API for
1407
+ * the variant's download URL with `apiToken`.
1408
+ */
1409
+ loadVariant?: (variantKey: string) => Promise<VRM>;
1298
1410
  /** Optional Three.js `Scene` or `Object3D` to attach `character.scene` to once loaded. */
1299
1411
  parent?: Object3D | null;
1300
1412
  /** Optional Three.js `Camera` or `Object3D` for template-face eye tracking. */
@@ -1366,6 +1478,8 @@ interface StreamPlaybackDependencies {
1366
1478
  onMotionFrames?: (event: StagingStreamMotionFramesEvent) => void;
1367
1479
  /** The stored live motion of a staging that starts to play (a replay). */
1368
1480
  onMotionTrack?: (stagingId: string, track: StagingMotionTrack) => void;
1481
+ onToolCall?: (toolCall: StagingToolCall) => void;
1482
+ onVariantCue?: (variantKey: string, toolCall: StagingToolCall | null) => Promise<void> | void;
1369
1483
  }
1370
1484
  declare class StreamPlaybackController {
1371
1485
  private readonly dependencies;
@@ -1394,6 +1508,12 @@ declare class StreamPlaybackController {
1394
1508
  get cursor(): CharacterPlaybackCursor | null;
1395
1509
  /** The staging that plays or waits to play, or null. */
1396
1510
  get activeStagingId(): string | null;
1511
+ /**
1512
+ * A staging plays or waits to play (its audio or the rest of its stream).
1513
+ * False after it completed or when autoplay blocked it; the last staging
1514
+ * stays the active staging after that.
1515
+ */
1516
+ get playing(): boolean;
1397
1517
  onStreamEvent(callback: (event: StagingStreamEvent) => Promise<void> | void): () => void;
1398
1518
  onSpeechPlaybackStart(callback: (speech: StagingSpeechPlaybackEvent) => Promise<void> | void): () => void;
1399
1519
  onCharacterReveal(callback: (speech: StagingSpeechPlaybackEvent, characterIndex: number, character: string) => void): () => void;
@@ -1419,6 +1539,53 @@ declare class StreamPlaybackController {
1419
1539
  private safeInvoke;
1420
1540
  }
1421
1541
 
1542
+ interface CharacterVariantChangeEvent {
1543
+ previousVariant: string;
1544
+ activeVariant: string;
1545
+ toolCall: StagingToolCall | null;
1546
+ }
1547
+ type VariantChangeEvent = CharacterVariantChangeEvent;
1548
+ interface NpcifyEventMap {
1549
+ variantChange: CharacterVariantChangeEvent;
1550
+ toolCall: StagingToolCall;
1551
+ vrmChange: VRM;
1552
+ }
1553
+ type NpcifyEventName = keyof NpcifyEventMap;
1554
+ interface CharacterVariantControllerOptions {
1555
+ loadVariant: (variantKey: string) => Promise<VRM>;
1556
+ applyVrmSwap: (nextVrm: VRM) => void;
1557
+ getCurrentVrm: () => VRM | null;
1558
+ handleCallbackError: (context: string, error: unknown) => void;
1559
+ }
1560
+ declare class CharacterVariantController {
1561
+ private readonly options;
1562
+ readonly variantVrms: Map<string, VRM>;
1563
+ private variantsList;
1564
+ private activeVariantKey;
1565
+ private remoteMode;
1566
+ private loadEpoch;
1567
+ private switchRevision;
1568
+ private readonly pendingLoads;
1569
+ private readonly listeners;
1570
+ constructor(options: CharacterVariantControllerOptions);
1571
+ get variants(): AvatarVariantSummary[];
1572
+ get activeVariant(): string;
1573
+ get isRemote(): boolean;
1574
+ on<K extends NpcifyEventName>(event: K, listener: (payload: NpcifyEventMap[K]) => void): () => void;
1575
+ off<K extends NpcifyEventName>(event: K, listener: (payload: NpcifyEventMap[K]) => void): void;
1576
+ emit<K extends NpcifyEventName>(event: K, payload: NpcifyEventMap[K]): void;
1577
+ configureVariants(variants: readonly AvatarVariantSummary[] | undefined, options?: {
1578
+ remote?: boolean;
1579
+ }): void;
1580
+ registerDefaultVrm(vrm: VRM): void;
1581
+ syncDirectVrm(vrm: VRM | null, previousVrm: VRM | null): void;
1582
+ preloadVariants(eager: boolean): Promise<void>;
1583
+ ensureVariant(variantKey: string): Promise<VRM>;
1584
+ switchVariant(variantKey: string, toolCall?: StagingToolCall | null): Promise<void>;
1585
+ reset(): VRM[];
1586
+ private applyActiveVariant;
1587
+ }
1588
+
1422
1589
  declare class CharacterExpressions {
1423
1590
  readonly mixer: FacialPerformanceMixer;
1424
1591
  constructor(mixer: FacialPerformanceMixer);
@@ -1456,12 +1623,147 @@ declare class CharacterExpressions {
1456
1623
  reset(): void;
1457
1624
  }
1458
1625
 
1626
+ /**
1627
+ * The scene graph access of a character: its root group, meshes, materials,
1628
+ * skeletons, bones and transform. `CharacterRuntime` adds the performance.
1629
+ */
1630
+ declare class CharacterSceneAccess {
1631
+ protected readonly sceneRig: CharacterSceneRig;
1632
+ protected defaultParent: Object3D | null;
1633
+ /** True once the character VRM model is loaded. */
1634
+ get ready(): boolean;
1635
+ /** Root Three.js `Group` (`vrm.scene`) to add to a `THREE.Scene`. */
1636
+ get scene(): Group | null;
1637
+ /** Alias for `scene` for Three.js `Object3D` workflows. */
1638
+ get object3d(): Group | null;
1639
+ /** Alias for `scene`. */
1640
+ get root(): Group | null;
1641
+ /** Primary character mesh (`SkinnedMesh` preferred, otherwise first `Mesh`). */
1642
+ get mesh(): SkinnedMesh | Mesh | null;
1643
+ /** All Three.js `Mesh` instances in the character hierarchy. */
1644
+ get meshes(): readonly Mesh[];
1645
+ /** All Three.js `SkinnedMesh` instances in the character hierarchy. */
1646
+ get skinnedMeshes(): readonly SkinnedMesh[];
1647
+ /** Deduplicated Three.js `Material` instances across all character meshes. */
1648
+ get materials(): readonly Material[];
1649
+ /** Deduplicated Three.js `Skeleton` instances across all character skinned meshes. */
1650
+ get skeletons(): readonly Skeleton[];
1651
+ /** Three-VRM humanoid rig when loaded. */
1652
+ get humanoid(): VRMHumanoid | null;
1653
+ /** Look up a raw humanoid bone `Object3D` by VRM bone name (for example `'head'` or `'rightHand'`). */
1654
+ getBone(name: VRMHumanBoneName): Object3D | null;
1655
+ /** Look up a normalized humanoid bone `Object3D` by VRM bone name. */
1656
+ getNormalizedBone(name: VRMHumanBoneName): Object3D | null;
1657
+ /** Attach the character root `Group` to a Three.js `Scene` or parent `Object3D`. */
1658
+ attachTo(parent: Object3D): Group;
1659
+ /** Detach the character root `Group` from its current parent `Object3D`. */
1660
+ detach(): void;
1661
+ /** Configure `castShadow` and `receiveShadow` on all character meshes. */
1662
+ setShadows(options?: CharacterShadowOptions): void;
1663
+ /** Configure `position`, `rotation`, and `scale` on the character root `Group`. */
1664
+ setTransform(options: CharacterTransformOptions): void;
1665
+ /** Re-index cached meshes, materials, and skeletons after custom scene graph edits. */
1666
+ refreshMeshes(): void;
1667
+ }
1668
+
1669
+ interface SpeechNod {
1670
+ /** The largest pitch of the head and neck together, in degrees. */
1671
+ amplitudeDegrees: number;
1672
+ durationMs: number;
1673
+ }
1674
+
1675
+ /** What the player does now, as the listening reflexes see it. */
1676
+ type PlayerActivity = 'idle' | 'typing' | 'speaking';
1677
+ interface PlayerActivityTrackerOptions {
1678
+ /** The random numbers of the nods (tests: a fixed stream). */
1679
+ random?: () => number;
1680
+ }
1681
+ /**
1682
+ * The state machine of the player's activity (docs/voice-input.md,
1683
+ * "Listening reflexes"). Speaking is a listening session in state
1684
+ * `listening`; typing is input in a text field during the last 1.5 s.
1685
+ * Speaking wins over typing. Only typed input and microphone levels go in:
1686
+ * nothing is sent to a server here.
1687
+ */
1688
+ declare class PlayerActivityTracker {
1689
+ private listening;
1690
+ private typing;
1691
+ private typingTimer;
1692
+ private current;
1693
+ private readonly trigger;
1694
+ private readonly changeListeners;
1695
+ private readonly nodListeners;
1696
+ constructor(options?: PlayerActivityTrackerOptions);
1697
+ get state(): PlayerActivity;
1698
+ /** The listening session is (or is no longer) in state `listening`. */
1699
+ setListening(active: boolean): void;
1700
+ /**
1701
+ * Input in a text field: `true` at each input event, `false` when the
1702
+ * player sends or leaves the field. Without input, typing ends after 1.5 s.
1703
+ */
1704
+ notifyTyping(active: boolean): void;
1705
+ /** One microphone frame of the listening session; returns a nod when one is due. */
1706
+ pushVoiceLevel(level: number, frameMs?: number): SpeechNod | null;
1707
+ onChange(listener: (state: PlayerActivity) => void): () => void;
1708
+ onNod(listener: (nod: SpeechNod) => void): () => void;
1709
+ /** Ends all activity, for example when the conversation ends. */
1710
+ reset(): void;
1711
+ private resolve;
1712
+ private clearTypingTimer;
1713
+ }
1714
+
1715
+ interface ListeningReflexHost {
1716
+ vrm(): VRM | null;
1717
+ /** The gaze target of `setGazeTarget` or `lookAt`, or null. */
1718
+ gazeTarget(): Object3D | null;
1719
+ /** The host application set the gaze target with `lookAt()`. */
1720
+ lookAtActive(): boolean;
1721
+ /** Looks at `target` until the returned function restores the prior gaze. */
1722
+ lookAtTemporarily(target: Object3D): () => void;
1723
+ facialMixer: FacialPerformanceMixer;
1724
+ }
1725
+ interface ListeningReflexFrame {
1726
+ /** A reply (staging) plays or waits to play. */
1727
+ stagingActive: boolean;
1728
+ /** The weight of live motion frames, 0 when idle. */
1729
+ liveMotionWeight: number;
1730
+ }
1731
+ /**
1732
+ * The listening reflexes of the Web client (docs/voice-input.md): while the
1733
+ * player speaks or types, the character looks at the player, shows a subtle
1734
+ * attentive face, and nods lightly at pauses in the speech. A staging takes
1735
+ * over at once: the face, the gaze and a nod stop in the same frame, and
1736
+ * nothing changes while it plays. A `lookAt()` target of the host stays; the
1737
+ * prior gaze comes back when the reflexes end. Live motion stops a nod.
1738
+ */
1739
+ declare class ListeningReflex {
1740
+ private readonly host;
1741
+ private readonly activity;
1742
+ private readonly nod;
1743
+ private pendingNod;
1744
+ private releaseGaze;
1745
+ private readonly front;
1746
+ private readonly origin;
1747
+ private readonly forward;
1748
+ private yielded;
1749
+ constructor(host: ListeningReflexHost, activity: PlayerActivityTracker);
1750
+ /** Call after the animation mixer and live motion, before the facial mixer and `vrm.update()`. */
1751
+ update(delta: number, frame: ListeningReflexFrame): void;
1752
+ /** A new model or the end of the conversation: no gaze, face or nod remains. */
1753
+ reset(): void;
1754
+ private beginGaze;
1755
+ private endGaze;
1756
+ /** The point in front of the head, along the character's forward axis. */
1757
+ private placeFront;
1758
+ }
1759
+
1459
1760
  interface CharacterRuntimeInitOptions extends Omit<NpcifyOptions, 'apiToken' | 'assetProfile' | 'apiKey'> {
1460
1761
  apiToken: string;
1461
1762
  assetProfile: 'original' | 'web-optimized-v1';
1462
1763
  loadAnimation?: (animationId: string) => Promise<VRMAnimation>;
1764
+ loadVariant?: (variantKey: string) => Promise<VRM>;
1463
1765
  }
1464
- declare class CharacterRuntime {
1766
+ declare class CharacterRuntime extends CharacterSceneAccess {
1465
1767
  readonly baseUrl: string;
1466
1768
  readonly characterId: string;
1467
1769
  readonly apiToken: string;
@@ -1471,8 +1773,8 @@ declare class CharacterRuntime {
1471
1773
  readonly animation: CharacterAnimation;
1472
1774
  animations: Map<string, VRMAnimation>;
1473
1775
  animationController?: AnimationControllerLike;
1474
- protected readonly sceneRig: CharacterSceneRig;
1475
1776
  protected readonly lazyAnimations: LazyAnimations;
1777
+ protected readonly variantController: CharacterVariantController;
1476
1778
  protected audioPlayer: AudioPlayer | null;
1477
1779
  protected stagingPlayer: StagingPlayer | null;
1478
1780
  protected readonly facialMixer: FacialPerformanceMixer;
@@ -1481,7 +1783,8 @@ declare class CharacterRuntime {
1481
1783
  protected readonly telemetry: ClientTelemetry;
1482
1784
  protected readonly streamPlayback: StreamPlaybackController;
1483
1785
  protected readonly liveMotion: LiveMotionPlayer;
1484
- protected defaultParent: Object3D | null;
1786
+ protected readonly playerActivityTracker: PlayerActivityTracker;
1787
+ protected readonly listeningReflex: ListeningReflex;
1485
1788
  protected currentGazeTarget: Object3D | null;
1486
1789
  /** The current gaze target came from `lookAt()`. */
1487
1790
  protected lookAtActive: boolean;
@@ -1493,26 +1796,14 @@ declare class CharacterRuntime {
1493
1796
  /** Loaded Three-VRM instance, or `null` before `loadAssets()`. */
1494
1797
  get vrm(): VRM | null;
1495
1798
  set vrm(value: VRM | null);
1496
- /** True once the character VRM model is loaded. */
1497
- get ready(): boolean;
1498
- /** Root Three.js `Group` (`vrm.scene`) to add to a `THREE.Scene`. */
1499
- get scene(): Group | null;
1500
- /** Alias for `scene` for Three.js `Object3D` workflows. */
1501
- get object3d(): Group | null;
1502
- /** Alias for `scene`. */
1503
- get root(): Group | null;
1504
- /** Primary character mesh (`SkinnedMesh` preferred, otherwise first `Mesh`). */
1505
- get mesh(): SkinnedMesh | Mesh | null;
1506
- /** All Three.js `Mesh` instances in the character hierarchy. */
1507
- get meshes(): readonly Mesh[];
1508
- /** All Three.js `SkinnedMesh` instances in the character hierarchy. */
1509
- get skinnedMeshes(): readonly SkinnedMesh[];
1510
- /** Deduplicated Three.js `Material` instances across all character meshes. */
1511
- get materials(): readonly Material[];
1512
- /** Deduplicated Three.js `Skeleton` instances across all character skinned meshes. */
1513
- get skeletons(): readonly Skeleton[];
1514
- /** Three-VRM humanoid rig when loaded. */
1515
- get humanoid(): VRMHumanoid | null;
1799
+ /** Allowed appearance variants configured for this character (`default` first). */
1800
+ get variants(): AvatarVariantSummary[];
1801
+ /** Currently active appearance variant key (defaults to `'default'`). */
1802
+ get activeVariant(): string;
1803
+ /** Cached Three-VRM instances keyed by variant key. */
1804
+ get variantVrms(): Map<string, VRM>;
1805
+ /** Switch the character's active appearance variant, loading on-demand if needed. */
1806
+ switchVariant(variantKey: string): Promise<void>;
1516
1807
  /** Underlying Three.js `AnimationMixer` driving skeletal animations. */
1517
1808
  get mixer(): AnimationMixer | null;
1518
1809
  /** The `Object3D` (such as a `THREE.Camera`) the character's eyes track. */
@@ -1534,20 +1825,6 @@ declare class CharacterRuntime {
1534
1825
  get cursor(): CharacterPlaybackCursor | null;
1535
1826
  /** Combined snapshot of real-time speech and dialogue state. */
1536
1827
  get speech(): CharacterSpeechState;
1537
- /** Look up a raw humanoid bone `Object3D` by VRM bone name (for example `'head'` or `'rightHand'`). */
1538
- getBone(name: VRMHumanBoneName): Object3D | null;
1539
- /** Look up a normalized humanoid bone `Object3D` by VRM bone name. */
1540
- getNormalizedBone(name: VRMHumanBoneName): Object3D | null;
1541
- /** Attach the character root `Group` to a Three.js `Scene` or parent `Object3D`. */
1542
- attachTo(parent: Object3D): Group;
1543
- /** Detach the character root `Group` from its current parent `Object3D`. */
1544
- detach(): void;
1545
- /** Configure `castShadow` and `receiveShadow` on all character meshes. */
1546
- setShadows(options?: CharacterShadowOptions): void;
1547
- /** Configure `position`, `rotation`, and `scale` on the character root `Group`. */
1548
- setTransform(options: CharacterTransformOptions): void;
1549
- /** Re-index cached meshes, materials, and skeletons after custom scene graph edits. */
1550
- refreshMeshes(): void;
1551
1828
  ensureAnimation(animationId: string): Promise<void>;
1552
1829
  /** Play a character animation by ID, automatically loading it if lazy. */
1553
1830
  playAnimation(animationId: string, options?: CharacterAnimationPlayOptions): Promise<void>;
@@ -1588,6 +1865,16 @@ declare class CharacterRuntime {
1588
1865
  clearLookAt(): void;
1589
1866
  /** Briefly look at an object; release restores the prior target and gaze mode. */
1590
1867
  lookAtTemporarily(target: Object3D): () => void;
1868
+ /**
1869
+ * Tells the character that the player types (`true` at each input event
1870
+ * of the text field) or stopped (`false`, for example after sending). The
1871
+ * character looks at the player and shows a subtle attentive face; typing
1872
+ * ends by itself after 1.5 s without input. Local only: no request.
1873
+ */
1874
+ notifyUserTyping(active: boolean): void;
1875
+ /** `'speaking'` while listening, `'typing'` after typed input, else `'idle'`. */
1876
+ get playerActivity(): PlayerActivity;
1877
+ onPlayerActivity(callback: (state: PlayerActivity) => void): () => void;
1591
1878
  startPerformanceRecording(options?: PerformanceRecordingStartOptions): void;
1592
1879
  stopPerformanceRecording(): PerformanceRecording | null;
1593
1880
  getPerformanceRecording(): PerformanceRecording | null;
@@ -1600,6 +1887,11 @@ declare class CharacterRuntime {
1600
1887
  onOptionsReady(callback: (payload: StagingOptionsReadyPayload) => void): () => void;
1601
1888
  onPlaybackCursor(callback: Parameters<StreamPlaybackController['onPlaybackCursor']>[0]): () => void;
1602
1889
  onTimelineStart(callback: (timeline: StagingTimeline, playback: StagingPlaybackStart) => Promise<void> | void): () => void;
1890
+ on<K extends NpcifyEventName>(event: K, listener: (payload: NpcifyEventMap[K]) => void): () => void;
1891
+ off<K extends NpcifyEventName>(event: K, listener: (payload: NpcifyEventMap[K]) => void): void;
1892
+ onVrmChange(callback: (vrm: VRM) => void): () => void;
1893
+ onVariantChange(callback: (event: CharacterVariantChangeEvent) => void): () => void;
1894
+ onToolCall(callback: (toolCall: StagingToolCall) => void): () => void;
1603
1895
  /** Advance skeletal animations, lip-sync visemes, facial expressions, and VRM physics by `delta` seconds. */
1604
1896
  update(delta: number): void;
1605
1897
  protected readonly getAudioPlayer: () => AudioPlayer;
@@ -1611,7 +1903,9 @@ declare class CharacterRuntime {
1611
1903
  * IdleFace (its gaze cone, idle eye moves and look cues).
1612
1904
  */
1613
1905
  protected applyGaze(): void;
1614
- protected resetRuntimeAssets(): void;
1906
+ protected resetRuntimeAssets(options?: {
1907
+ disposeVrms?: boolean;
1908
+ }): void;
1615
1909
  protected disposeRuntimeAssets(): void;
1616
1910
  protected readonly handleCallbackError: (context: string, error: unknown) => void;
1617
1911
  protected readonly reportError: (error: Error, context?: string) => void;
@@ -1799,6 +2093,8 @@ declare class Character extends CharacterRuntime {
1799
2093
  /** The conversation whose live motion was warmed up. */
1800
2094
  private liveMotionPrepared;
1801
2095
  private readonly authoring;
2096
+ private hostedWebChat;
2097
+ private memoryIdentifier;
1802
2098
  protected readonly normalizeIdleOrientation: boolean;
1803
2099
  private readonly bakedAsset?;
1804
2100
  private animationRefreshId;
@@ -1896,6 +2192,9 @@ declare class Character extends CharacterRuntime {
1896
2192
  */
1897
2193
  playStreamEvent(event: StagingStreamEvent): Promise<boolean> | undefined;
1898
2194
  setRenderSessionId(renderSessionId: string | null): void;
2195
+ setHostedWebChat(enabled: boolean): void;
2196
+ setMemoryIdentifier(memoryIdentifier: string | null | undefined): void;
2197
+ getMemoryIdentifier(): string | null;
1899
2198
  onStagingResult(callback: (payload: StagingResultPayload) => Promise<void> | void): () => void;
1900
2199
  onThinking(callback: (payload: LlmThinkingPayload) => Promise<void> | void): () => void;
1901
2200
  private resetAssets;
@@ -1998,6 +2297,8 @@ interface MountNpcifyOptions {
1998
2297
  normalizeIdleOrientation?: boolean;
1999
2298
  /** How the player can reply: `'options'`, `'text'`, `'voice'` (docs/voice-input.md). */
2000
2299
  inputModes?: InputMode[];
2300
+ /** Player memory identifier for SDK conversations; empty/null uses the character owner's dashboard memory bucket. */
2301
+ memoryIdentifier?: string | null;
2001
2302
  onError?: (error: Error) => void;
2002
2303
  }
2003
2304
  interface NpcifyView {
@@ -2007,9 +2308,10 @@ interface NpcifyView {
2007
2308
  camera?: PerspectiveCamera | null;
2008
2309
  renderer?: WebGLRenderer | null;
2009
2310
  controls?: OrbitControls | null;
2311
+ setMemoryIdentifier(memoryIdentifier: string | null | undefined): void;
2010
2312
  dispose(): Promise<void>;
2011
2313
  }
2012
2314
  /** Mount into an existing canvas. Its CSS must give it a nonzero width and height. */
2013
2315
  declare const mountNpcify: (options: MountNpcifyOptions) => Promise<NpcifyView>;
2014
2316
 
2015
- export { AnimationController, type AnimationControllerLike, type AnimationControllerOptions, type AssetLoadProgress, type AudioCapture, type AudioPerformanceFrameSnapshot, AudioPlayer, BakedConversation, type BakedConversationAsset, type CaptureFrame, Character, CharacterAnimation, type CharacterAnimationPlayOptions, CharacterAudio, type CharacterDisposeOptions, CharacterExpressions, type CharacterLookAtTarget, type CharacterOptions, type CharacterPlaybackCursor, CharacterRuntime, type CharacterRuntimeInitOptions, CharacterSceneRig, type CharacterShadowOptions, type CharacterSpeechState, type CharacterTransformOptions, type ConversationConnectionClosedEvent, ConversationConnectionError, type ConversationConnectionErrorCode, type ConversationJoinFailure, type ConversationTurnOptions, type FacialChannelName, type FacialCueOptions, type FacialMouthMode, type FacialPerformanceFrameSnapshot, FacialPerformanceLayer, type FacialPerformanceLayerId, FacialPerformanceMixer, type FacialPerformanceModelSnapshot, INPUT_MODES, type InputMode, InputModeError, type ListeningOptions, type ListeningState, type LiveMotionOptions, LiveMotionPlayer, type LiveMotionRootMode, type LlmThinkingPayload, type LoadCharacterOptions, MicrophoneError, type MountNpcifyOptions, Npcify, type NpcifyAssetInfo, Character as NpcifyCharacter, type NpcifyOptions, type NpcifyView, PERFORMANCE_FILE_EXTENSION, PERFORMANCE_MEDIA_TYPE, type PerformanceAnalysis, type PerformanceAnalysisOptions, type PerformanceEvent, type PerformanceFrame, type PerformanceIssue, type PerformanceKind, type PerformanceRecording, PerformanceRecordingSchemaVersion, type PerformanceRecordingStartOptions, type PerformanceTimelineSnapshot, type PlayStagingOptions, type PushToTalkOptions, type PushToTalkTarget, RemoteAnimationController, type RepeatedVisemeTransitionAnalysis, SightError, type SightFailureCode, type SightObservation, type SightObservationEvent, type SightOptions, type SightPerson, type SightState, SpeechInputError, type SpeechInputResult, type StagingOptionsReadyPayload, type StagingPlaybackStart, type StagingSpeechPlaybackEvent, type TranscriptEvent, type Vector3Like, type Vector3Tuple, type VisemePerformanceFrameSnapshot, analyzePerformanceRecording, bindPushToTalk, createCharacter, decodePerformance, encodePerformance, loadBakedConversation, loadCharacter, mountNpcify };
2317
+ export { AnimationController, type AnimationControllerLike, type AnimationControllerOptions, type AssetLoadProgress, type AudioCapture, type AudioPerformanceFrameSnapshot, AudioPlayer, type AvatarVariantSummary, BakedConversation, type BakedConversationAsset, type CaptureFrame, Character, CharacterAnimation, type CharacterAnimationPlayOptions, CharacterAudio, type CharacterDisposeOptions, CharacterExpressions, type CharacterLookAtTarget, type CharacterOptions, type CharacterPlaybackCursor, CharacterRuntime, type CharacterRuntimeInitOptions, CharacterSceneRig, type CharacterShadowOptions, type CharacterSpeechState, type CharacterTransformOptions, type CharacterVariantChangeEvent, type ConversationConnectionClosedEvent, ConversationConnectionError, type ConversationConnectionErrorCode, type ConversationJoinFailure, type ConversationTurnOptions, DEFAULT_VARIANT_KEY, type FacialChannelName, type FacialCueOptions, type FacialMouthMode, type FacialPerformanceFrameSnapshot, FacialPerformanceLayer, type FacialPerformanceLayerId, FacialPerformanceMixer, type FacialPerformanceModelSnapshot, type FetchVrmDownloadUrlOptions, INPUT_MODES, type InputMode, InputModeError, type ListeningOptions, type ListeningState, type LiveMotionOptions, LiveMotionPlayer, type LiveMotionRootMode, type LlmThinkingPayload, type LoadCharacterOptions, MicrophoneError, type MountNpcifyOptions, NUDE_VARIANT_KEY, Npcify, type NpcifyAssetInfo, Character as NpcifyCharacter, type NpcifyEventMap, type NpcifyEventName, type NpcifyOptions, type NpcifyView, PERFORMANCE_FILE_EXTENSION, PERFORMANCE_MEDIA_TYPE, type PerformanceAnalysis, type PerformanceAnalysisOptions, type PerformanceEvent, type PerformanceFrame, type PerformanceIssue, type PerformanceKind, type PerformanceRecording, PerformanceRecordingSchemaVersion, type PerformanceRecordingStartOptions, type PerformanceTimelineSnapshot, type PlayStagingOptions, type PlayerActivity, type PushToTalkOptions, type PushToTalkTarget, RemoteAnimationController, type RepeatedVisemeTransitionAnalysis, SightError, type SightFailureCode, type SightObservation, type SightObservationEvent, type SightOptions, type SightPerson, type SightState, SpeechInputError, type SpeechInputResult, type StagingOptionsReadyPayload, type StagingPlaybackStart, type StagingSpeechPlaybackEvent, type StagingSwitchVariantArguments, type StagingToolCall, type StagingToolCallResult, type StagingToolName, type StagingToolResultStatus, type TranscriptEvent, type VariantChangeEvent, type Vector3Like, type Vector3Tuple, type VisemePerformanceFrameSnapshot, analyzePerformanceRecording, bindPushToTalk, createCharacter, decodePerformance, encodePerformance, fetchVariantVrmDownloadUrl, fetchVrmDownloadUrl, loadBakedConversation, loadCharacter, loadVariantVrm, loadVrm, mountNpcify };