@npcify/web 0.7.2 → 0.7.3

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,7 +122,7 @@ 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 and legs: the upper arm turns at the shoulder by the smallest rotation that is necessary (0.7.1). Loose cloth on spring bones (skirts, coat tails) turns the arm by 10 degrees at most, and a clip without contact stays exactly as authored (0.7.2).
125
+ - Each clip keeps the character's hands out of its own torso, hips and legs: the upper arm turns at the shoulder by the smallest rotation that is necessary (0.7.1). Loose cloth on spring bones (skirts, coat tails) turns the arm by 10 degrees at most, and a clip without contact stays exactly as authored (0.7.2). The clip changes only within about 0.3 s around a contact of a hand with the body; turn it off with the option `handClearance: false` (0.7.3; for `mountNpcify`, `new Npcify` and `createCharacter`/`loadCharacter`).
126
126
  - **Dialogue & Speech State**:
127
127
  - `character.speaking`, `character.thinking`, `character.currentSpeech`, `character.currentText`, `character.revealedText`, `character.options`, `character.cursor`, `character.speech`.
128
128
  - `await character.createConversation()`, `await character.sendMessage(text)`, `await character.endConversation()`.
package/dist/index.d.ts CHANGED
@@ -803,6 +803,8 @@ interface AnimationControllerOptions {
803
803
  * and neck/head orientation face canonical `+Z`.
804
804
  */
805
805
  normalizeIdleOrientation?: boolean;
806
+ /** Keep the hands out of the character's body (default `true`). */
807
+ handClearance?: boolean;
806
808
  }
807
809
  interface CharacterAnimationPlayOptions {
808
810
  fadeDuration?: number;
@@ -841,6 +843,7 @@ declare class AnimationController implements AnimationControllerLike {
841
843
  private readonly normalizedIdleClips;
842
844
  private readonly configs;
843
845
  private readonly normalizeIdleOrientation;
846
+ private readonly handClearance;
844
847
  private previewMixer;
845
848
  private restorePreview;
846
849
  private activeAction;
@@ -1432,6 +1435,13 @@ interface NpcifyOptions {
1432
1435
  * `Character` (`loadCharacter` / `createCharacter` Three.js game mode).
1433
1436
  */
1434
1437
  normalizeIdleOrientation?: boolean;
1438
+ /**
1439
+ * Keep the character's hands out of its own torso, hips and legs in VRMA
1440
+ * clips (the upper arm turns at the shoulder; loose cloth at most 10
1441
+ * degrees; the clip changes only within about 0.3 s around a contact).
1442
+ * Defaults to `true`.
1443
+ */
1444
+ handClearance?: boolean;
1435
1445
  /**
1436
1446
  * Playback of live motion frames (characters with real-time motion). The
1437
1447
  * default `rootMode: 'anchored'` keeps the character where it stands.
@@ -2096,6 +2106,7 @@ declare class Character extends CharacterRuntime {
2096
2106
  private hostedWebChat;
2097
2107
  private memoryIdentifier;
2098
2108
  protected readonly normalizeIdleOrientation: boolean;
2109
+ protected readonly handClearance: boolean;
2099
2110
  private readonly bakedAsset?;
2100
2111
  private animationRefreshId;
2101
2112
  private readonly voice;
@@ -2295,6 +2306,8 @@ interface MountNpcifyOptions {
2295
2306
  serverRendering?: boolean;
2296
2307
  assetProfile?: 'original' | 'web-optimized-v1';
2297
2308
  normalizeIdleOrientation?: boolean;
2309
+ /** Keep the hands out of the character's body in VRMA clips (default `true`). */
2310
+ handClearance?: boolean;
2298
2311
  /** How the player can reply: `'options'`, `'text'`, `'voice'` (docs/voice-input.md). */
2299
2312
  inputModes?: InputMode[];
2300
2313
  /** Player memory identifier for SDK conversations; empty/null uses the character owner's dashboard memory bucket. */
package/dist/index.js CHANGED
@@ -5409,6 +5409,20 @@ var buildRadialMap = function(bone, origin, axis, points) {
5409
5409
  bottom[column] = min;
5410
5410
  }
5411
5411
  }
5412
+ const despiked = radius.slice();
5413
+ const at = (row, column) => radius[row * MAP_ANGLE_BINS + (column + MAP_ANGLE_BINS) % MAP_ANGLE_BINS];
5414
+ for (let row = 0; row < heights; row += 1) {
5415
+ for (let column = 0; column < MAP_ANGLE_BINS; column += 1) {
5416
+ const value = at(row, column);
5417
+ const left = Math.max(at(row, column - 2), at(row, column - 3));
5418
+ const right = Math.max(at(row, column + 2), at(row, column + 3));
5419
+ const support = Math.max(left, right);
5420
+ if (support > 0 && value > support * 1.35 && value - support > 0.05) {
5421
+ despiked[row * MAP_ANGLE_BINS + column] = support;
5422
+ }
5423
+ }
5424
+ }
5425
+ radius.set(despiked);
5412
5426
  const filled = radius.slice();
5413
5427
  for (let row = 0; row < heights; row += 1) {
5414
5428
  for (let column = 0; column < MAP_ANGLE_BINS; column += 1) {
@@ -5577,6 +5591,8 @@ var isHandSkin = function(point, segments) {
5577
5591
 
5578
5592
  // ../vrm-renderer/src/hand-body.ts
5579
5593
  var BUST = /bust|breast|oppai/i;
5594
+ var ARM_BONE = /^(left|right)(UpperArm|LowerArm|Hand|Thumb|Index|Middle|Ring|Little)/;
5595
+ var ARM_WEIGHT_LIMIT = 0.05;
5580
5596
  var SIDES = ["left", "right"];
5581
5597
  var TORSO_PARTS = [
5582
5598
  "hips",
@@ -5780,12 +5796,18 @@ var buildBodyModel = function(vrm) {
5780
5796
  for (let i = 0; i < count; i += 1) {
5781
5797
  let best = 0;
5782
5798
  let bestWeight = -1;
5799
+ let armWeight = 0;
5783
5800
  for (let k = 0; k < 4; k += 1) {
5784
5801
  const weight = skinWeight.getComponent(i, k);
5785
5802
  if (weight > bestWeight) {
5786
5803
  bestWeight = weight;
5787
5804
  best = skinIndex.getComponent(i, k);
5788
5805
  }
5806
+ const part = object.skeleton.bones[skinIndex.getComponent(i, k)];
5807
+ const partAttach = part && weight > 0 ? attachOf(part) : null;
5808
+ if (partAttach && ARM_BONE.test(partAttach)) {
5809
+ armWeight += weight;
5810
+ }
5789
5811
  }
5790
5812
  const bone = object.skeleton.bones[best];
5791
5813
  const attach = bone ? attachOf(bone) : null;
@@ -5800,6 +5822,9 @@ var buildBodyModel = function(vrm) {
5800
5822
  }
5801
5823
  continue;
5802
5824
  }
5825
+ if (armWeight > ARM_WEIGHT_LIMIT) {
5826
+ continue;
5827
+ }
5803
5828
  const body = nameOfRaw.get(bone) === attach || BUST.test(bone.name);
5804
5829
  const key = `${attach}|${body ? "body" : "cloth"}`;
5805
5830
  keys[i] = key;
@@ -6211,6 +6236,14 @@ import {
6211
6236
  var MAX_CORRECTION = 35 * Math.PI / 180;
6212
6237
  var CLOTH_CORRECTION_CAP = 10 * Math.PI / 180;
6213
6238
  var MAX_ITERATIONS = 6;
6239
+ var HOLD_FRAMES = 2;
6240
+ var SMOOTH_SIGMA = 2;
6241
+ var frontOffset = new Vector36();
6242
+ var inFront = function(map, point, forward) {
6243
+ frontOffset.copy(point).sub(map.origin);
6244
+ frontOffset.addScaledVector(map.axis, -frontOffset.dot(map.axis));
6245
+ return frontOffset.dot(forward) > Math.SQRT1_2 * frontOffset.length();
6246
+ };
6214
6247
  var deepestContact = function(model, pose, side, kind) {
6215
6248
  let best = null;
6216
6249
  const perMap = [];
@@ -6239,7 +6272,7 @@ var deepestContact = function(model, pose, side, kind) {
6239
6272
  if (hit.depth <= 0) {
6240
6273
  continue;
6241
6274
  }
6242
- if (torso) {
6275
+ if (torso && inFront(map, local, model.forward)) {
6243
6276
  const front = escapeAlong(map, local, model.forward);
6244
6277
  if (front <= 1.5 * hit.depth + 0.01) {
6245
6278
  hit.depth = front;
@@ -6318,8 +6351,24 @@ var frameCorrections = function(model, frames, side, start, margin, kind, debug)
6318
6351
  };
6319
6352
  apply();
6320
6353
  const added = new Quaternion5();
6354
+ let contact = deepestContact(model, pose, side, kind);
6355
+ const attempt = (step, next) => {
6356
+ const keptCorrection = correction.clone();
6357
+ const keptAdded = added.clone();
6358
+ correction.premultiply(step);
6359
+ added.copy(next);
6360
+ apply();
6361
+ const after = deepestContact(model, pose, side, kind);
6362
+ if (after && contact && after.depth >= contact.depth) {
6363
+ correction.copy(keptCorrection);
6364
+ added.copy(keptAdded);
6365
+ apply();
6366
+ return false;
6367
+ }
6368
+ contact = after;
6369
+ return true;
6370
+ };
6321
6371
  for (let iteration = 0; iteration < MAX_ITERATIONS; iteration += 1) {
6322
- const contact = deepestContact(model, pose, side, kind);
6323
6372
  if (!contact) {
6324
6373
  break;
6325
6374
  }
@@ -6353,9 +6402,7 @@ var frameCorrections = function(model, frames, side, start, margin, kind, debug)
6353
6402
  const cappedStep = capped.clone().multiply(added.clone().invert());
6354
6403
  const total = cappedStep.clone().multiply(correction);
6355
6404
  if (quaternionToRotationVector(total).length() <= MAX_CORRECTION) {
6356
- correction.premultiply(cappedStep);
6357
- added.copy(capped);
6358
- apply();
6405
+ attempt(cappedStep, capped);
6359
6406
  }
6360
6407
  break;
6361
6408
  }
@@ -6363,13 +6410,54 @@ var frameCorrections = function(model, frames, side, start, margin, kind, debug)
6363
6410
  if (quaternionToRotationVector(combined).length() > MAX_CORRECTION) {
6364
6411
  break;
6365
6412
  }
6366
- correction.premultiply(step);
6367
- added.copy(next);
6368
- apply();
6413
+ if (!attempt(step, next)) {
6414
+ break;
6415
+ }
6369
6416
  }
6370
6417
  return quaternionToRotationVector(added);
6371
6418
  });
6372
6419
  };
6420
+ var bodyDepthWith = function(model, frame, side, vector) {
6421
+ const upper = `${side}UpperArm`;
6422
+ const pose = solvePose(model, frame.local, frame.hips);
6423
+ const parentRotation = pose.rotation.get(model.parent.get(upper));
6424
+ const original = frame.local.get(upper) ?? new Quaternion5();
6425
+ const local = new Map(frame.local);
6426
+ local.set(
6427
+ upper,
6428
+ parentRotation.clone().invert().multiply(
6429
+ rotationVectorToQuaternion(vector).multiply(
6430
+ parentRotation.clone().multiply(original)
6431
+ )
6432
+ )
6433
+ );
6434
+ solvePose(model, local, frame.hips, ARM_CHAIN(model, side), pose);
6435
+ return deepestContact(model, pose, side, "body")?.depth ?? 0;
6436
+ };
6437
+ var SCALES = [0.75, 0.5, 0.25, 0];
6438
+ var keepNoDeeper = function(model, frames, side, total) {
6439
+ return total.map((vector, index) => {
6440
+ if (vector.length() < 0.5 * Math.PI / 180) {
6441
+ return vector;
6442
+ }
6443
+ const frame = frames[index];
6444
+ const untouched = bodyDepthWith(model, frame, side, new Vector36());
6445
+ let best = bodyDepthWith(model, frame, side, vector);
6446
+ if (best <= untouched + 2e-3) {
6447
+ return vector;
6448
+ }
6449
+ let result = vector;
6450
+ for (const scale of SCALES) {
6451
+ const scaled = vector.clone().multiplyScalar(scale);
6452
+ const depth = bodyDepthWith(model, frame, side, scaled);
6453
+ if (depth < best - 1e-3) {
6454
+ best = depth;
6455
+ result = scaled;
6456
+ }
6457
+ }
6458
+ return result;
6459
+ });
6460
+ };
6373
6461
  var solveHandClearance = function(model, frames, options = {}) {
6374
6462
  const margin = options.margin ?? 8e-3;
6375
6463
  const result = /* @__PURE__ */ new Map();
@@ -6381,7 +6469,7 @@ var solveHandClearance = function(model, frames, options = {}) {
6381
6469
  let total = frames.map(() => new Vector36());
6382
6470
  let changed = false;
6383
6471
  const compose = (raw) => {
6384
- const smooth = widenAndSmooth(raw, 4, 3);
6472
+ const smooth = widenAndSmooth(raw, HOLD_FRAMES, SMOOTH_SIGMA);
6385
6473
  total = total.map(
6386
6474
  (t, i) => quaternionToRotationVector(
6387
6475
  rotationVectorToQuaternion(smooth[i]).multiply(
@@ -6406,6 +6494,9 @@ var solveHandClearance = function(model, frames, options = {}) {
6406
6494
  changed = true;
6407
6495
  compose(raw);
6408
6496
  }
6497
+ if (changed) {
6498
+ total = keepNoDeeper(model, frames, side, total);
6499
+ }
6409
6500
  if (options.onReport) {
6410
6501
  const left = frameCorrections(model, frames, side, total, margin, "body");
6411
6502
  const degrees = total.map((v) => v.length() * 180 / Math.PI);
@@ -7170,6 +7261,7 @@ var AnimationController = class {
7170
7261
  this.mixer = new AnimationMixer2(this.vrm.scene);
7171
7262
  this.idleAnimationId = idleAnimationId ?? null;
7172
7263
  this.normalizeIdleOrientation = options?.normalizeIdleOrientation ?? false;
7264
+ this.handClearance = options?.handClearance ?? true;
7173
7265
  this.mixer.addEventListener("finished", this.handleActionFinished);
7174
7266
  }
7175
7267
  prepareAnimations;
@@ -7179,6 +7271,7 @@ var AnimationController = class {
7179
7271
  normalizedIdleClips = /* @__PURE__ */ new Map();
7180
7272
  configs = /* @__PURE__ */ new Map();
7181
7273
  normalizeIdleOrientation;
7274
+ handClearance;
7182
7275
  previewMixer = null;
7183
7276
  restorePreview = null;
7184
7277
  activeAction = null;
@@ -7268,7 +7361,9 @@ var AnimationController = class {
7268
7361
  return this.clips.has(id);
7269
7362
  }
7270
7363
  addAnimation(animationId, animation, config) {
7271
- const rawClip = createVRMAnimationClip(animation, this.vrm);
7364
+ const rawClip = createVRMAnimationClip(animation, this.vrm, {
7365
+ handClearance: this.handClearance
7366
+ });
7272
7367
  this.rawClips.set(animationId, rawClip);
7273
7368
  this.normalizedIdleClips.delete(animationId);
7274
7369
  this.clips.set(animationId, this.resolveClipForId(animationId, rawClip));
@@ -7279,7 +7374,9 @@ var AnimationController = class {
7279
7374
  }
7280
7375
  previewAnimation(animation) {
7281
7376
  this.restorePreview?.();
7282
- const clip = createVRMAnimationClip(animation, this.vrm);
7377
+ const clip = createVRMAnimationClip(animation, this.vrm, {
7378
+ handClearance: this.handClearance
7379
+ });
7283
7380
  const previewMixer = new AnimationMixer2(this.vrm.scene);
7284
7381
  previewMixer.clipAction(clip).setLoop(LoopRepeat2, Infinity).reset().play();
7285
7382
  this.previewMixer = previewMixer;
@@ -15041,6 +15138,7 @@ var Character = class extends CharacterRuntime {
15041
15138
  hostedWebChat;
15042
15139
  memoryIdentifier;
15043
15140
  normalizeIdleOrientation;
15141
+ handClearance;
15044
15142
  bakedAsset;
15045
15143
  animationRefreshId = 0;
15046
15144
  voice;
@@ -15069,6 +15167,7 @@ var Character = class extends CharacterRuntime {
15069
15167
  this.hostedWebChat = options.hostedWebChat === true && !resolvedToken;
15070
15168
  this.memoryIdentifier = normalizeMemoryIdentifier(options.memoryIdentifier);
15071
15169
  this.normalizeIdleOrientation = options.normalizeIdleOrientation ?? false;
15170
+ this.handClearance = options.handClearance ?? true;
15072
15171
  this.bakedAsset = options.bakedConversation;
15073
15172
  this.initialAssetInfo = options.initialAssetInfo ?? null;
15074
15173
  this.inputs = new InputModeRules(
@@ -15207,7 +15306,10 @@ var Character = class extends CharacterRuntime {
15207
15306
  const animationController = new AnimationController(
15208
15307
  this.vrm,
15209
15308
  info.idleAnimationId ?? null,
15210
- { normalizeIdleOrientation: this.normalizeIdleOrientation }
15309
+ {
15310
+ normalizeIdleOrientation: this.normalizeIdleOrientation,
15311
+ handClearance: this.handClearance
15312
+ }
15211
15313
  );
15212
15314
  animationController.prepareAnimations = (ids) => this.lazyAnimations.ensureMany(ids);
15213
15315
  this.animationController = animationController;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@npcify/web",
3
- "version": "0.7.2",
3
+ "version": "0.7.3",
4
4
  "description": "Framework-independent Npcify characters, live conversations and baked performances for the web",
5
5
  "type": "module",
6
6
  "license": "UNLICENSED",
@@ -34,9 +34,9 @@
34
34
  "@types/three": "^0.180.0",
35
35
  "tsup": "^8.5.0",
36
36
  "typescript": "^5.9.3",
37
- "@npcify/vrm-renderer": "^0.1.0",
38
37
  "@npcify/shared": "^0.1.0",
39
- "@npcify/web-client": "^0.0.0"
38
+ "@npcify/web-client": "^0.0.0",
39
+ "@npcify/vrm-renderer": "^0.1.0"
40
40
  },
41
41
  "repository": {
42
42
  "type": "git",