Powered by

VRM

本指南将带你完成 SillyTavern 中 VRM 扩展的设置与自定义。该扩展允许你为角色使用 VRM 动画模型，为虚拟角色增添动态与互动的元素。

前置条件

开始之前，请确认你已满足以下前置条件：

  1. 分支选择：确保你使用的是 SillyTavern 的最新版本分支，以便获取最新的功能与更新。

  2. 扩展安装：在扩展面板（以堆叠方块图标表示）的“下载扩展与素材”菜单中安装“VRM”扩展。

  3. 模型文件夹放置：将你的 VRM 模型文件（.vrm）放入 /data/<user-handle>/assets/vrm/model 目录，并将动画文件放入 /data/<user-handle>/assets/vrm/animation 目录。当前支持的动画文件格式为与 VRM 模型兼容的 .fbx 和 .bvh。这包括你从 Mixamo（https://www.mixamo.com/）获取的任何动画，以及从 XR Animator（https://github.com/ButzYung/SystemAnimatorOnline）等工具导出的任何动画。

扩展设置

VRM 扩展提供了多种设置来自定义动画模型的行为。以下是主要设置：

UI 全局设置
UI 全局设置

全局设置

  1. 启用（Enabled）：

    • 勾选此项以激活该扩展，使你的 VRM 模型能在 SillyTavern 中互动。
    • 如果你只想使用普通立绘，可以禁用该扩展。

  2. 看向镜头（Look at camera）：

    • 勾选此项以让 VRM 模型的眼睛看向镜头。

  3. 眨眼（Blink）：

    • 勾选此项以让 VRM 模型的眼睛以随机间隔眨眼。模型表情应正确定义眨眼权重属性，否则模型可能会出现闭着眼睛眨眼的情况。如果发生这种情况，可以：
    • 如果你有 .vroid 文件，则修正模型
    • 不使用那个不正确的面部表情
    • 通过此复选框完全禁用眨眼

  4. TTS 唇形同步（TTS Lip sync）

    • 勾选此项以让 VRM 嘴部动作跟随 TTS 播放时的声音。仅适用于由 SillyTavern 自身播放声音的 TTS（如 XTTS，且非流式模式）。如果禁用，则在收到新的角色消息时，嘴部将根据消息文本长度进行动画。

  5. 自动发送互动（Auto-send Interaction）：

    • 勾选此项以在点击映射了消息的区域时自动触发角色互动（详见触发区部分）。

性能设置

  1. 身体碰撞盒（Body hitboxes）

    • 勾选此项以激活对 VRM 模型多个部位的点击检测。根据模型的不同，可检测以下部位：头部/胸部/手部/裆部/臀部/腿部/脚部。碰撞盒位置会在每一帧计算并跟随身体动画，禁用此选项可提升性能。

  2. 使用模型缓存（Use model cache）

    • 勾选此项以在切换模型时将 VRM 模型保留在内存中，便于更快地切回之前的模型。例如，当你为同一个角色使用不同模型以更换服装或形态时很有用。可能会影响性能。

  3. 使用动画缓存（Use animation cache）

    • 勾选此项以将本次会话中播放过的所有动画保留在内存中。分配给某个模型的所有动画也会在该模型首次出现时一并加载。这会增加首次加载模型的时间，但能让所有动画切换变为瞬时完成。可能会影响性能。

调试设置

  1. 显示网格（Show grid）

    • 勾选此项以可视化 3D 网格、模型拖拽框和身体碰撞盒。

  2. 重新加载按钮（Reload button）

    • 点击此按钮以重新加载 3D 场景，清除缓存及所有 VRM 模型。在出现 bug 或缓存开始影响性能时使用。

场景设置

UI 场景设置
UI 场景设置

  1. 灯光颜色（Light Color）

    • 设置 3D 场景中灯光的颜色。点击重置按钮可将其恢复为默认的白色。根据你使用的浏览器，你可以使用取色器，例如拾取背景图片的颜色以增强沉浸感。

  2. 灯光强度（Light intensity）

    • 使用滑块以百分比形式设置灯光强度。点击重置按钮可将其恢复为默认值 100%。VRM 模型对灯光的反应会因模型内置的着色器而异，多尝试几个数值看看效果。
UI 模型设置
UI 模型设置

角色选择

这些设置允许你管理角色并为其分配 VRM 模型。

  1. 刷新按钮（Refresh Button）：

    • 点击刷新按钮以更新当前对话中的角色列表。

  2. 选择角色（Select Character）：

    • 使用下拉列表选择一个要为其分配 VRM 模型的角色。

  3. 移除按钮（Remove Button）：

    • 点击此按钮以删除角色已分配的模型。

模型选择

  1. 刷新按钮（Refresh Button）：

    • 如果你的 VRM 模型未出现在列表中，点击刷新按钮。

  2. 选择模型（Select Model）：

    • 从列表中选择一个模型以将其分配给所选角色。
    • 模型必须位于 /data/<user-handle>/assets/vrm/model 目录中。

  3. 重置按钮（Reset button）

    • 点击此按钮以将模型设置重置为默认值。如果你有与默认值对应的动画文件，它们将被自动映射。命名映射见本 README 末尾。

模型设置

  1. 模型缩放（Model Scale）：

    • 使用滑块调整模型大小，使其变大或变小。

  2. 模型中心 X/Y 偏移（Model Center X/Y Offset）：

    • 使用这些滑块更改模型相对于窗口中心的水平/垂直位置。

  3. 模型 X/Y 旋转（Model X/Y Rotation）

    • 使用这些滑块更改模型相对于模型髋部的水平/垂直旋转。

说明

- 这些设置按模型保存而非按角色保存，并会跨不同对话保留。
- 如果你想为两个不同角色使用同一个模型但采用不同设置，请复制该 .vrm 文件。
- 你也可以用鼠标拖动模型，这些设置会随之更新并保存。左键按住可在屏幕上拖动模型。鼠标中键按住可旋转模型，或使用 shift+左键。将光标放在模型上并滚动鼠标滚轮可放大或缩小，或使用 ctrl+左键。
- 如果你不小心把模型移出了视野，可使用这些 UI 设置将其移回屏幕。此外，勾选“显示边框（Show frame）”复选框可以清楚地看到哪里可以点击拖动模型。
UI 碰撞盒设置
UI 碰撞盒设置

碰撞盒映射

- 根据模型的骨骼定义，某些碰撞盒区域会被生成，它们会列在此 UI 部分，你可以为每个区域分配一个表情/动画/消息，并在点击该区域时触发。
UI classify 设置
UI classify 设置

分类表情映射

  1. 要求

    • 需要使用 classify 表情扩展；否则将回退到默认动画。

  2. 映射

    • 对于 classify 扩展检测到的每种情绪，你可以分配一个表情/动作/消息。消息可包含命令。

命令

  1. /vrmlightcolor
    • 设置灯光颜色
    • 参数：color
    • 示例："/vrmlightcolor white" 或 "/vrmlightcolor purple"。
  2. /vrmlightintensity
    • 以百分比形式设置灯光强度
    • 参数：intensity
    • 示例："/vrmlightintensity 0" 或 "/vrmlightintensity 100
  3. /vrmmodel
    • 将 vrm 模型分配给角色
    • 参数：character, model
    • 示例：单聊中 "/vrmmodel Seraphina.vrm"，或群聊中 "/vrmmodel character=Seraphina model=Seraphina.vrm"
  4. /vrmexpression
    • 更改模型的表情
    • 参数：character, expression
    • 示例：单聊中 "/vrmexpression happy"，或群聊中 "/vrmexpression character=Seraphina expression=happy"
  5. /vrmmotion
    • 更改模型的动画
    • 参数：character, motion, loop, random
    • "/vrmmotion idle" 或 "/vrmmotion character=Seraphina motion=idle loop=true random=false"

动画默认映射

如果你的动画文件按以下方式命名，在重置模型设置时它们将被自动映射。例如，名为 "assets/vrm/animation/neutral.bvh" 和 "assets/vrm/animation/neutral1.fbx" 的文件会被自动作为一组映射为默认和 neutral 分类的动画。碰撞盒同理。

// Fallback
"default": "assets/vrm/animation/neutral",

// Classify class
"admiration": "assets/vrm/animation/admiration",
"amusement": "assets/vrm/animation/amusement",
"anger": "assets/vrm/animation/anger",
"annoyance": "assets/vrm/animation/annoyance",
"approval": "assets/vrm/animation/approval",
"caring": "assets/vrm/animation/caring",
"confusion": "assets/vrm/animation/confusion",
"curiosity": "assets/vrm/animation/curiosity",
"desire": "assets/vrm/animation/desire",
"disappointment": "assets/vrm/animation/disappointment",
"disapproval": "assets/vrm/animation/disapproval",
"disgust": "assets/vrm/animation/disgust",
"embarrassment": "assets/vrm/animation/embarrassment",
"excitement": "assets/vrm/animation/excitement",
"fear": "assets/vrm/animation/fear",
"gratitude": "assets/vrm/animation/gratitude",
"grief": "assets/vrm/animation/grief",
"joy": "assets/vrm/animation/joy",
"love": "assets/vrm/animation/love",
"nervousness": "assets/vrm/animation/nervousness",
"neutral": "assets/vrm/animation/neutral",
"optimism": "assets/vrm/animation/optimism",
"pride": "assets/vrm/animation/pride",
"realization": "assets/vrm/animation/realization",
"relief": "assets/vrm/animation/relief",
"remorse": "assets/vrm/animation/remorse",
"sadness": "assets/vrm/animation/sadness",
"surprise": "assets/vrm/animation/surprise",

// Hitboxes
"head": "assets/vrm/animation/hitarea_head",
"chest": "assets/vrm/animation/hitarea_chest",
"groin": "assets/vrm/animation/hitarea_groin",
"butt": "assets/vrm/animation/hitarea_butt",
"leftHand": "assets/vrm/animation/hitarea_hands",
"rightHand": "assets/vrm/animation/hitarea_hands",
"leftLeg": "assets/vrm/animation/hitarea_leg",
"rightLeg": "assets/vrm/animation/hitarea_leg",
"rightFoot": "assets/vrm/animation/hitarea_foot",
"leftFoot": "assets/vrm/animation/hitarea_foot"

感谢你跟随本指南！你的 SillyTavern 体验现已增添了动画化且可互动的 3D 模型。

说明

- 该扩展加载的 VRM 模型是 .vrm 文件，而非 .vroid 文件。
- 动画文件应与 VRM 兼容，你可以使用 XR animation（https://github.com/ButzYung/SystemAnimatorOnline）等工具来转换 fbx/bvh 动画文件。
- 你可以通过让同名文件以不同数字结尾来创建动画组，例如："idle1.bvh"、"idle2.bvh"、"idle3.bvh" 将被视为一个名为 "idle" 的组，当在映射中被选中时，触发后会随机播放其中一个，可用于为动画增加多样性。
- 你可以从这个仓库获取精选动画：https://github.com/test157t/VRM-Animations-Pack-For-Silly-Tavern
- Nitral 有一些关于如何使用该扩展和动画仓库的教程视频：https://www.youtube.com/@nitralai

© Copyright 2026. All rights reserved.