桌面应用数字人AI 应用【免费下载链接】Mate-EngineA free Desktop Mate alternative with a lightweight interface and custom VRM support, though with more features.项目地址https://gitcode.com/gh_mirrors/ma/Mate-Engine点击查看免费下载导读本文围绕 Mate-Engine 中「Custom Dance Player」自定义舞蹈播放器展开完整讲解如何在 Unity 中制作一个.unity3d舞蹈 AssetBundle由.anim动画、.controller动画控制器与.mp3/.ogg/.wav音频构成并给出获得最佳 MMD 面部表情与运镜效果的文件制作标准。文中同时结合仓库源码说明播放器的实际加载逻辑、.me舞蹈 Mod 的导出流程以及多实例同步机制帮助你制作出可直接放入CustomDances目录或打包为舞蹈 Mod 的合规舞蹈文件。一、舞蹈文件的本质一个 AssetBundle三样资源Mate-Engine 的 Custom Dance Player 将每一支舞蹈封装为一个.unity3dAssetBundle 文件。从播放器源码AvatarDancePlayer.cs可以看到启动时它会扫描两个来源目录凡是扩展名为.unity3d的文件都会被当作一支舞蹈加载Application.streamingAssetsPath/CustomDances即项目的 CustomDances 目录对应代码中streamingSubfolder CustomDancesApplication.persistentDataPath/Mods对应modsFolderName Mods通常指 StreamingAssets/Mods 在持久化数据目录中的拷贝。因此只要把打包好的.unity3d文件放入上述目录重启或触发 Rescan后就会出现在播放器列表中。舞蹈文件结构.unity3d AssetBundle根据 README_dance.md 的规范每支舞蹈的 Bundle 内应包含以下资源推荐三者使用一致的命名资源类型命名约定说明Animator Controller[DanceName].controller简单的单状态控制器新建 Animator Controller 后把[DanceName].anim拖入控制器窗口Unity 会自动生成一个状态Entry无条件过渡到该状态音频文件[DanceName].wav/.mp3/.ogg支持 3 种常见格式时长必须与动画长度匹配否则会导致音画不同步动画[DanceName].anim包含舞蹈动画数据从源码看加载时播放器会从 Bundle 中取出第一个 AnimationClip 与第一个 AudioClip使用见 AvatarDancePlayer.cs所以 Bundle 内通常只需放置这一支舞蹈对应的动画与音频避免多个 Clip 混淆。播放器对资源的实际使用方式播放时SmoothPlayFlow 的执行顺序是冻结 Animatoranimator.speed 0、暂停音频、切换到等待状态通过AssetBundle.LoadFromFile加载 Bundle取出AnimationClip与AudioClip用AnimatorOverrideController把占位动画CUSTOM_DANCE覆盖为舞蹈动画见 EnsureAnimatorReady先启动音频audioSource.Play()再解除 Animator 冻结、播放动画。这个先音频、后动画的顺序正是原文档提到的WaitForAudioThenStartAnimation思路在播放器里通过leadSeconds提前量调度默认 1.5 秒确保音频起播后动画才进入舞蹈状态从而规避音频缓冲导致的音画不同步详见下文多实例同步小节。二、分步制作一只合规的舞蹈文件第 1 步准备动画.anim在 Unity 中制作或导入舞蹈动画 Clip。建议动画只驱动与舞蹈相关的骨骼/曲线命名统一为[DanceName].anim。仓库中播放器自带的占位动画 CUSTOM_DANCE.anim 与结束动画 DANCE_END.anim 位于 Custom Dance Player/Prefab 目录可作为参考样例前者在播放时被替换为舞蹈动画后者在舞蹈结束时触发自动切歌。第 2 步创建单状态控制器.controller按规范创建一个 Animator Controller新建 Animator Controller命名为[DanceName].controller把[DanceName].anim拖入 Animator 窗口Unity 自动生成一个状态Entry无条件过渡到该状态即可。播放器侧使用的控制器是 CustomDanceAvatarController.controller。仓库文档README.md特别说明不直接使用舞蹈文件自带的 controller而是用一个包含全部所需参数的自定义 AnimatorController 覆盖角色原控制器因为直接使用舞蹈 controller 会让 Unity 反复上报缺少参数警告进而引发内存问题。这也是为什么舞蹈 Bundle 里的 controller 只需最简单的单状态结构——真正承载状态机的是播放器自己的控制器。第 3 步准备音频.mp3/.ogg/.wav音频支持.mp3、.ogg、.wav三种常见格式命名与动画一致[DanceName].mp3等。音频时长必须与动画长度匹配否则会出现音画不同步。播放器中进度与时间显示均以AudioClip.length/audioSource.time为准见 AvatarDancePlayer.cs因此音频时长实际上决定了整支舞蹈的播放时长与自动切歌时机。第 4 步打包为 AssetBundle在 Unity 中将三者放入同一个 AssetBundle建议命名为[DanceName].unity3d并执行 Build。最终的.unity3d文件即可放入CustomDances目录。进阶方式仓库还提供了Dance Mod.me导出管线可将动画 音频自动打包成内部含dance.bundle与dance_meta.json的.me文件详情见下文第五节与第七节。三、MMD 面部表情标准让表情曲线真正生效原文档明确指出为了获得最优的 MMD 面部表情支持舞蹈文件中的面部表情应使用标准的日式 MMD BlendShapes如あいうえお并通过模型BodySkinnedMeshRenderer上的动画曲线进行控制。仓库中对这一标准有两层实现佐证1. 面部表情名清单AvatarDancePlayer.cs 内置了一个日式 MMD BlendShape 名称集合包括眼睛类まばたき眨眼、ウィンク、ウィンク、ウィンク右、笑い、なごみ、びっくり、ジト目、瞳小、キリッ、星目、はぁと、はちゅ目、ハイライト消し等口型类あ、い、う、え、お、えーん、ん、▲、ω口、はんっ、にっこり、にやり、べろっ、てへぺろ、口角上げ、口角下げ、口横広げ、真面目、困る、怒り、照れ、涙、すぼめ等。停止舞蹈时ResetMMDBlendShapes 会把这些名字匹配到的 BlendShape 权重全部归零避免表情残留。2. 无 MMD 表情模型的兜底转换如果当前角色本身没有日式 MMD BlendShapes播放器会通过 AvatarDanceShapeConverter.cs 完成兜底候选路径依次为Body、Model/Body、Face见 candidatePaths先调用HasMmdBlendshapes检测模型是否已具备 MMD 表情若已具备则直接跳过转换见 AvatarDanceShapeConverter.cs若不具备则把播放器自带的 DummyBlendshapeMesh.asset内含常见日式 MMD BlendShapes 的网格挂到候选路径上作为代理渲染器并借助PlayableGraph手动求值舞蹈动画逐帧读取代理网格上的 BlendShape 权重GetMax取各候选 SMR 中同名表情的最大值再写入UniversalBlendshapes的通用表情字段AvatarDanceShapeConverter.cs。关键映射关系可在 AvatarDanceShapeConverter.cs 中确认MMD 表情UniversalBlendshapes 字段まばたきBlinkウィンク/ウィンクBlink_L/Blink_RあいうえおAIUEOにこりJoy怒りAngry困るSorrow真面目Neutral笑いFunUniversalBlendshapesUniversalBlendshapes.cs随后在LateUpdate中把通用字段写入角色的实际表情系统同时兼容 VRM 0.xBlendShapePreset见 vrm0Presets与 VRM 1.0ExpressionKey映射见 vrm10KeyMap。这就是即使角色没有 MMD 表情舞蹈表情也能生效的完整链路。四、相机动画标准Camera_root 层级与 180° 初始旋转原文档要求为获得最佳运镜效果舞蹈文件中应包含如下相机层级Camera_root └── Camera_root_1 └── CameraCamera 组件各层级职责节点职责Camera_root控制相机整体位置Camera_root_1控制相机距离z 轴Camera通过 Camera 组件控制FOV视野关键要求创建上述层级后需给Camera_root添加一个y 轴 180° 的初始旋转以保证相机的初始朝向与 MMD 舞蹈惯例一致。仓库中的辅助脚本 DanceCameraDistKeeper 会在播放期间维持舞蹈相机与角色髋部之间的固定 z 轴距离防止模型穿模或相机丢失目标这与上述相机规范配合使用效果最佳。五、舞蹈文件的两种投放方式CustomDances 目录与 .me 舞蹈 Mod方式一直接放入 CustomDances 目录把打包好的.unity3d文件放进 Assets/StreamingAssets/CustomDances构建后位于StreamingAssets根下。播放器启动时会扫描该目录streamingSubfolder CustomDances并递归读取所有.unity3d文件见 AvatarDancePlayer.cs。方式二导出为 .me 舞蹈 Mod仓库的 Mod 导出器支持把舞蹈封装成.me压缩包。TryAddME的加载逻辑AvatarDancePlayer.cs表明.me舞蹈包的结构为[DanceName].me (zip) ├── *.bundle // 内部包含 AnimationClip 与 AudioClip 的 AssetBundle └── dance_meta.json // 元数据或兼容的 dance.jsondance_meta.json的字段定义见 MEDanceModCreator.cs 中的DanceMeta字段含义songName歌曲名songAuthor歌曲作者mmdAuthorMMD 动作作者songLength歌曲时长秒placeholderClipName占位动画名默认CUSTOM_DANCE播放器会优先用songAuthor其次mmdAuthor填充作者显示见 AvatarDancePlayer.cs。此外.me舞蹈包在首次加载时会被解压到Application.temporaryCachePath/ME_Cache下缓存并按源文件修改时间判断是否需要重新解压播放器还会对.bundle计算SHA1 作为稳定标识stableId用于多实例同步时唯一定位同一支舞蹈。.me文件同样受 Mod 开关控制加载前会通过IsModEnabled检查 Mod 是否被停用见 AvatarDancePlayer.cs。六、播放器底层实现加载、播放、队列与多实例同步资源加载与列表LoadAllSources 会合并扫描CustomDances与Mods两个目录按文件名去扩展名作为舞蹈 ID并排序生成列表。BuildListUI 使用对象池构建列表 UI支持 TMP 与回退字体两套文本组件useFallbackFont字段控制。播放流程PlayIndex→SmoothPlayFlow的完整时序已在第二节说明。播放过程中Update会持续检测isCustomDancing参数若动画提前退出舞蹈状态会自动执行StopAndUnload卸载 Bundle 与音频数据AvatarDancePlayer.cs。播放结束音频播完或时间到达时触发TryAutoNext自动切到下一首。队列、收藏、搜索与循环/随机AvatarDancePlayerTools.cs 提供了配套的列表增强搜索过滤ApplyFilter按标题做大小写不敏感匹配可忽略 Unicode 零宽字符收藏收藏列表保存到Application.persistentDataPath/favorite_songs.jsonfavoritesFileName字段见 AvatarDancePlayerTools.cs只显示收藏开启后会把当前可见曲目构建为播放队列SetQueueByIndices上下曲与自动切歌都在该队列内循环循环 / 随机loopOn、shuffleOn由对应 Toggle 写入播放器见 AvatarDancePlayerTools.cs。多实例同步多角色共舞当多个 Mate-Engine 实例例如多个角色同屏共舞同时运行时播放器通过文件总线 领导者选举实现同步配置字段见 AvatarDancePlayer.cs字段默认值作用enableSynctrue是否启用同步syncFileNameavatar_dance_play_bus.json同步总线文件名写入persistentDataPath/Sync/pollInterval0.05秒从总线读取命令的轮询间隔leadSeconds1.5秒命令执行提前量给音频缓冲留时间总线文件内容形如 Sync/dance_sync.json仓库根目录下的同步示例结构含key/time/playing/version/hasStart/startUtc/ev等字段{key:,time:0.0,playing:false,version:0,hasStart:false,startUtc:0.0,ev:0}工作机制实现见 AvatarDancePlayer.cs各实例启动时通过命名 MutexMateEngine.AvatarDanceSync.Leader竞争领导者身份失败时退化为按命令行--instance参数取 0 号实例见 TryAcquireLeader领导者点击播放/上一曲/下一曲/停止时计算atUtc UtcNow() leadSeconds把命令PlayByStableId、StopPlay等连同目标时间原子化写入总线 JSON临时文件 改名写入见SafeWrite所有非领导者实例以pollInterval轮询总线发现v版本号递增后按atUtc精确调度执行从而保证多实例同一时刻切歌领导者在歌曲剩余约 0.18 秒时即开始预调度下一首避免切歌缝隙非领导者会临时静音MuteFollower待播放命令到达再恢复音量。若需关闭同步可在 UI 中切换同步开关AvatarSyncDanceTools.cs 通过文件锁FileShare.None独占总线文件阻止其他实例写入实现主实例独奏。七、制作与导出工具链从动画到 .me 舞蹈 Mod仓库在 Assets/Editor/ModExporterWindow.cs 提供了图形化导出窗口菜单MateEngine/ME Mod Exporter切换为Dance Mod模式即可导出舞蹈在场景中挂载MEDanceModCreator组件MEDanceModCreator.cs填入controllerAnimator Controller可为 AnimatorOverrideControllerdanceClip舞蹈动画 Clip留空时自动从 controller 中按placeholderClipName CUSTOM_DANCE查找song音频 ClipsongName/songAuthor/mmdAuthor元数据留空歌曲名时自动取song.name见OnValidate在导出窗口中选择该组件、填写舞蹈名与作者、选择构建目标默认StandaloneWindows64点击Export Dance Mod。ExportDanceMod的内部流程ModExporterWindow.cs将舞蹈动画复制到Assets/__DanceExportTemp__并设置为dance.bundle的 AssetBundle 名称复制音频并加入同一dance.bundleBuildPipeline.BuildAssetBundles构建 Bundle写入dance_meta.json内容即上文DanceMeta各字段把构建目录压缩为ExportedMods/[DanceModName].me并自动定位到资源管理器。导出产物与播放器TryAddME的解析格式完全对应可直接投放到Mods目录。仓库 ExportedMods 目录 中已有若干.me示例文件可作为 Mod 包结构参考。八、制作规范自查清单与常见问题提交前自查清单动画、控制器、音频三者命名一致[DanceName].anim/.controller/.wav|.mp3|.ogg控制器为单状态结构Entry无条件进入舞蹈状态音频时长与动画长度匹配播放进度以音频为准面部表情使用日式 MMD BlendShape 名称如あいうえお驱动曲线挂在BodySkinnedMeshRenderer上如需运镜模型下建立Camera_root → Camera_root_1 → Camera层级Camera_root初始 y 轴旋转 180°Camera_root_1控制 z 轴距离Camera 组件控制 FOV如需导出.me舞蹈 Mod使用MEDanceModCreator填写元数据经ME Mod Exporter导出。常见问题与应对音画不同步优先检查音频时长是否与动画一致播放器已内置leadSeconds提前量与先音频后动画的播放顺序来缓解缓冲问题仍不同步时可配合手动同步滑块微调。表情不生效确认角色模型是否带日式 MMD BlendShapes若没有确认播放器附带的DummyBlendshapeMesh与AvatarDanceShapeConverter处于启用状态它会把 MMD 表情转换为UniversalBlendshapes通用表情。角色跳舞时部件消失播放器在角色切换后会开启所有SkinnedMeshRenderer的updateWhenOffscreen对应SMRHandle工具舞蹈期间若仍出现部件丢失可在播放器工具中排查代理渲染器遮挡设置。直接使用舞蹈 controller 出现大量参数警告属已知问题播放器设计上使用自定义的CustomDanceAvatarController覆盖原控制器请勿绕过。参考资料仓库内进一步阅读舞蹈文件规范原文Assets/StreamingAssets/CustomDances/README_dance.mdCustom Dance Player 组件说明含脚本职责划分Assets/MATE ENGINE - Custom Dance Player/README.md播放器主逻辑AvatarDancePlayer.cs表情转换AvatarDanceShapeConverter.cs 与 UniversalBlendshapes.cs列表增强工具AvatarDancePlayerTools.cs舞蹈 Mod 导出MEDanceModCreator.cs 与 ModExporterWindow.cs赞分享桌面应用数字人AI 应用【免费下载链接】Mate-EngineA free Desktop Mate alternative with a lightweight interface and custom VRM support, though with more features.项目地址https://gitcode.com/gh_mirrors/ma/Mate-Engine点击查看免费下载相关推荐AtlasOS 驱动优化完整指南按症状下药用 4 个工具解决低帧、推流卡顿与输入延迟AtlasOS 驱动优化完整指南按症状下药用 4 个工具解决低帧、推流卡顿与输入延迟 这是一篇 AtlasOS 驱动优化指南。AtlasOS 是一个开源的桌面应用数字人AI 应用Wormhole-crypto实战指南使用encryptStream和decryptStream处理数据流Wormhole crypto实战指南使用encryptStream和decryptStream处理数据流 Wormhole crypto是基于RFC 818密码学如何用AI舞蹈生成器创作专业级3D舞蹈终极免费教程如何用AI舞蹈生成器创作专业级3D舞蹈终极免费教程 想要创作令人惊艳的3D舞蹈动画吗现在通过AI舞蹈生成器技术任何人都可以轻松生成专业级的舞蹈动作人工智能深度学习媒体生成计算机视觉上一篇完整实战指南如何高效部署开源远程设备管理平台MeshCentral下一篇如何使用TikTokDownload工具高效下载抖音无水印视频完整实用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/16 6:02:04 · 阅读 1.2k Mate-Engine 自定义舞蹈播放器：舞蹈文件（.unity3d）制作、打包与 MMD 标准规范指南
桌面应用数字人AI 应用【免费下载链接】Mate-EngineA free Desktop Mate alternative with a lightweight interface and custom VRM support, though with more features.项目地址https://gitcode.com/gh_mirrors/ma/Mate-Engine点击查看免费下载导读本文围绕 Mate-Engine 中「Custom Dance Player」自定义舞蹈播放器展开完整讲解如何在 Unity 中制作一个.unity3d舞蹈 AssetBundle由.anim动画、.controller动画控制器与.mp3/.ogg/.wav音频构成并给出获得最佳 MMD 面部表情与运镜效果的文件制作标准。文中同时结合仓库源码说明播放器的实际加载逻辑、.me舞蹈 Mod 的导出流程以及多实例同步机制帮助你制作出可直接放入CustomDances目录或打包为舞蹈 Mod 的合规舞蹈文件。一、舞蹈文件的本质一个 AssetBundle三样资源Mate-Engine 的 Custom Dance Player 将每一支舞蹈封装为一个.unity3dAssetBundle 文件。从播放器源码AvatarDancePlayer.cs可以看到启动时它会扫描两个来源目录凡是扩展名为.unity3d的文件都会被当作一支舞蹈加载Application.streamingAssetsPath/CustomDances即项目的 CustomDances 目录对应代码中streamingSubfolder CustomDancesApplication.persistentDataPath/Mods对应modsFolderName Mods通常指 StreamingAssets/Mods 在持久化数据目录中的拷贝。因此只要把打包好的.unity3d文件放入上述目录重启或触发 Rescan后就会出现在播放器列表中。舞蹈文件结构.unity3d AssetBundle根据 README_dance.md 的规范每支舞蹈的 Bundle 内应包含以下资源推荐三者使用一致的命名资源类型命名约定说明Animator Controller[DanceName].controller简单的单状态控制器新建 Animator Controller 后把[DanceName].anim拖入控制器窗口Unity 会自动生成一个状态Entry无条件过渡到该状态音频文件[DanceName].wav/.mp3/.ogg支持 3 种常见格式时长必须与动画长度匹配否则会导致音画不同步动画[DanceName].anim包含舞蹈动画数据从源码看加载时播放器会从 Bundle 中取出第一个 AnimationClip 与第一个 AudioClip使用见 AvatarDancePlayer.cs所以 Bundle 内通常只需放置这一支舞蹈对应的动画与音频避免多个 Clip 混淆。播放器对资源的实际使用方式播放时SmoothPlayFlow 的执行顺序是冻结 Animatoranimator.speed 0、暂停音频、切换到等待状态通过AssetBundle.LoadFromFile加载 Bundle取出AnimationClip与AudioClip用AnimatorOverrideController把占位动画CUSTOM_DANCE覆盖为舞蹈动画见 EnsureAnimatorReady先启动音频audioSource.Play()再解除 Animator 冻结、播放动画。这个先音频、后动画的顺序正是原文档提到的WaitForAudioThenStartAnimation思路在播放器里通过leadSeconds提前量调度默认 1.5 秒确保音频起播后动画才进入舞蹈状态从而规避音频缓冲导致的音画不同步详见下文多实例同步小节。二、分步制作一只合规的舞蹈文件第 1 步准备动画.anim在 Unity 中制作或导入舞蹈动画 Clip。建议动画只驱动与舞蹈相关的骨骼/曲线命名统一为[DanceName].anim。仓库中播放器自带的占位动画 CUSTOM_DANCE.anim 与结束动画 DANCE_END.anim 位于 Custom Dance Player/Prefab 目录可作为参考样例前者在播放时被替换为舞蹈动画后者在舞蹈结束时触发自动切歌。第 2 步创建单状态控制器.controller按规范创建一个 Animator Controller新建 Animator Controller命名为[DanceName].controller把[DanceName].anim拖入 Animator 窗口Unity 自动生成一个状态Entry无条件过渡到该状态即可。播放器侧使用的控制器是 CustomDanceAvatarController.controller。仓库文档README.md特别说明不直接使用舞蹈文件自带的 controller而是用一个包含全部所需参数的自定义 AnimatorController 覆盖角色原控制器因为直接使用舞蹈 controller 会让 Unity 反复上报缺少参数警告进而引发内存问题。这也是为什么舞蹈 Bundle 里的 controller 只需最简单的单状态结构——真正承载状态机的是播放器自己的控制器。第 3 步准备音频.mp3/.ogg/.wav音频支持.mp3、.ogg、.wav三种常见格式命名与动画一致[DanceName].mp3等。音频时长必须与动画长度匹配否则会出现音画不同步。播放器中进度与时间显示均以AudioClip.length/audioSource.time为准见 AvatarDancePlayer.cs因此音频时长实际上决定了整支舞蹈的播放时长与自动切歌时机。第 4 步打包为 AssetBundle在 Unity 中将三者放入同一个 AssetBundle建议命名为[DanceName].unity3d并执行 Build。最终的.unity3d文件即可放入CustomDances目录。进阶方式仓库还提供了Dance Mod.me导出管线可将动画 音频自动打包成内部含dance.bundle与dance_meta.json的.me文件详情见下文第五节与第七节。三、MMD 面部表情标准让表情曲线真正生效原文档明确指出为了获得最优的 MMD 面部表情支持舞蹈文件中的面部表情应使用标准的日式 MMD BlendShapes如あいうえお并通过模型BodySkinnedMeshRenderer上的动画曲线进行控制。仓库中对这一标准有两层实现佐证1. 面部表情名清单AvatarDancePlayer.cs 内置了一个日式 MMD BlendShape 名称集合包括眼睛类まばたき眨眼、ウィンク、ウィンク、ウィンク右、笑い、なごみ、びっくり、ジト目、瞳小、キリッ、星目、はぁと、はちゅ目、ハイライト消し等口型类あ、い、う、え、お、えーん、ん、▲、ω口、はんっ、にっこり、にやり、べろっ、てへぺろ、口角上げ、口角下げ、口横広げ、真面目、困る、怒り、照れ、涙、すぼめ等。停止舞蹈时ResetMMDBlendShapes 会把这些名字匹配到的 BlendShape 权重全部归零避免表情残留。2. 无 MMD 表情模型的兜底转换如果当前角色本身没有日式 MMD BlendShapes播放器会通过 AvatarDanceShapeConverter.cs 完成兜底候选路径依次为Body、Model/Body、Face见 candidatePaths先调用HasMmdBlendshapes检测模型是否已具备 MMD 表情若已具备则直接跳过转换见 AvatarDanceShapeConverter.cs若不具备则把播放器自带的 DummyBlendshapeMesh.asset内含常见日式 MMD BlendShapes 的网格挂到候选路径上作为代理渲染器并借助PlayableGraph手动求值舞蹈动画逐帧读取代理网格上的 BlendShape 权重GetMax取各候选 SMR 中同名表情的最大值再写入UniversalBlendshapes的通用表情字段AvatarDanceShapeConverter.cs。关键映射关系可在 AvatarDanceShapeConverter.cs 中确认MMD 表情UniversalBlendshapes 字段まばたきBlinkウィンク/ウィンクBlink_L/Blink_RあいうえおAIUEOにこりJoy怒りAngry困るSorrow真面目Neutral笑いFunUniversalBlendshapesUniversalBlendshapes.cs随后在LateUpdate中把通用字段写入角色的实际表情系统同时兼容 VRM 0.xBlendShapePreset见 vrm0Presets与 VRM 1.0ExpressionKey映射见 vrm10KeyMap。这就是即使角色没有 MMD 表情舞蹈表情也能生效的完整链路。四、相机动画标准Camera_root 层级与 180° 初始旋转原文档要求为获得最佳运镜效果舞蹈文件中应包含如下相机层级Camera_root └── Camera_root_1 └── CameraCamera 组件各层级职责节点职责Camera_root控制相机整体位置Camera_root_1控制相机距离z 轴Camera通过 Camera 组件控制FOV视野关键要求创建上述层级后需给Camera_root添加一个y 轴 180° 的初始旋转以保证相机的初始朝向与 MMD 舞蹈惯例一致。仓库中的辅助脚本 DanceCameraDistKeeper 会在播放期间维持舞蹈相机与角色髋部之间的固定 z 轴距离防止模型穿模或相机丢失目标这与上述相机规范配合使用效果最佳。五、舞蹈文件的两种投放方式CustomDances 目录与 .me 舞蹈 Mod方式一直接放入 CustomDances 目录把打包好的.unity3d文件放进 Assets/StreamingAssets/CustomDances构建后位于StreamingAssets根下。播放器启动时会扫描该目录streamingSubfolder CustomDances并递归读取所有.unity3d文件见 AvatarDancePlayer.cs。方式二导出为 .me 舞蹈 Mod仓库的 Mod 导出器支持把舞蹈封装成.me压缩包。TryAddME的加载逻辑AvatarDancePlayer.cs表明.me舞蹈包的结构为[DanceName].me (zip) ├── *.bundle // 内部包含 AnimationClip 与 AudioClip 的 AssetBundle └── dance_meta.json // 元数据或兼容的 dance.jsondance_meta.json的字段定义见 MEDanceModCreator.cs 中的DanceMeta字段含义songName歌曲名songAuthor歌曲作者mmdAuthorMMD 动作作者songLength歌曲时长秒placeholderClipName占位动画名默认CUSTOM_DANCE播放器会优先用songAuthor其次mmdAuthor填充作者显示见 AvatarDancePlayer.cs。此外.me舞蹈包在首次加载时会被解压到Application.temporaryCachePath/ME_Cache下缓存并按源文件修改时间判断是否需要重新解压播放器还会对.bundle计算SHA1 作为稳定标识stableId用于多实例同步时唯一定位同一支舞蹈。.me文件同样受 Mod 开关控制加载前会通过IsModEnabled检查 Mod 是否被停用见 AvatarDancePlayer.cs。六、播放器底层实现加载、播放、队列与多实例同步资源加载与列表LoadAllSources 会合并扫描CustomDances与Mods两个目录按文件名去扩展名作为舞蹈 ID并排序生成列表。BuildListUI 使用对象池构建列表 UI支持 TMP 与回退字体两套文本组件useFallbackFont字段控制。播放流程PlayIndex→SmoothPlayFlow的完整时序已在第二节说明。播放过程中Update会持续检测isCustomDancing参数若动画提前退出舞蹈状态会自动执行StopAndUnload卸载 Bundle 与音频数据AvatarDancePlayer.cs。播放结束音频播完或时间到达时触发TryAutoNext自动切到下一首。队列、收藏、搜索与循环/随机AvatarDancePlayerTools.cs 提供了配套的列表增强搜索过滤ApplyFilter按标题做大小写不敏感匹配可忽略 Unicode 零宽字符收藏收藏列表保存到Application.persistentDataPath/favorite_songs.jsonfavoritesFileName字段见 AvatarDancePlayerTools.cs只显示收藏开启后会把当前可见曲目构建为播放队列SetQueueByIndices上下曲与自动切歌都在该队列内循环循环 / 随机loopOn、shuffleOn由对应 Toggle 写入播放器见 AvatarDancePlayerTools.cs。多实例同步多角色共舞当多个 Mate-Engine 实例例如多个角色同屏共舞同时运行时播放器通过文件总线 领导者选举实现同步配置字段见 AvatarDancePlayer.cs字段默认值作用enableSynctrue是否启用同步syncFileNameavatar_dance_play_bus.json同步总线文件名写入persistentDataPath/Sync/pollInterval0.05秒从总线读取命令的轮询间隔leadSeconds1.5秒命令执行提前量给音频缓冲留时间总线文件内容形如 Sync/dance_sync.json仓库根目录下的同步示例结构含key/time/playing/version/hasStart/startUtc/ev等字段{key:,time:0.0,playing:false,version:0,hasStart:false,startUtc:0.0,ev:0}工作机制实现见 AvatarDancePlayer.cs各实例启动时通过命名 MutexMateEngine.AvatarDanceSync.Leader竞争领导者身份失败时退化为按命令行--instance参数取 0 号实例见 TryAcquireLeader领导者点击播放/上一曲/下一曲/停止时计算atUtc UtcNow() leadSeconds把命令PlayByStableId、StopPlay等连同目标时间原子化写入总线 JSON临时文件 改名写入见SafeWrite所有非领导者实例以pollInterval轮询总线发现v版本号递增后按atUtc精确调度执行从而保证多实例同一时刻切歌领导者在歌曲剩余约 0.18 秒时即开始预调度下一首避免切歌缝隙非领导者会临时静音MuteFollower待播放命令到达再恢复音量。若需关闭同步可在 UI 中切换同步开关AvatarSyncDanceTools.cs 通过文件锁FileShare.None独占总线文件阻止其他实例写入实现主实例独奏。七、制作与导出工具链从动画到 .me 舞蹈 Mod仓库在 Assets/Editor/ModExporterWindow.cs 提供了图形化导出窗口菜单MateEngine/ME Mod Exporter切换为Dance Mod模式即可导出舞蹈在场景中挂载MEDanceModCreator组件MEDanceModCreator.cs填入controllerAnimator Controller可为 AnimatorOverrideControllerdanceClip舞蹈动画 Clip留空时自动从 controller 中按placeholderClipName CUSTOM_DANCE查找song音频 ClipsongName/songAuthor/mmdAuthor元数据留空歌曲名时自动取song.name见OnValidate在导出窗口中选择该组件、填写舞蹈名与作者、选择构建目标默认StandaloneWindows64点击Export Dance Mod。ExportDanceMod的内部流程ModExporterWindow.cs将舞蹈动画复制到Assets/__DanceExportTemp__并设置为dance.bundle的 AssetBundle 名称复制音频并加入同一dance.bundleBuildPipeline.BuildAssetBundles构建 Bundle写入dance_meta.json内容即上文DanceMeta各字段把构建目录压缩为ExportedMods/[DanceModName].me并自动定位到资源管理器。导出产物与播放器TryAddME的解析格式完全对应可直接投放到Mods目录。仓库 ExportedMods 目录 中已有若干.me示例文件可作为 Mod 包结构参考。八、制作规范自查清单与常见问题提交前自查清单动画、控制器、音频三者命名一致[DanceName].anim/.controller/.wav|.mp3|.ogg控制器为单状态结构Entry无条件进入舞蹈状态音频时长与动画长度匹配播放进度以音频为准面部表情使用日式 MMD BlendShape 名称如あいうえお驱动曲线挂在BodySkinnedMeshRenderer上如需运镜模型下建立Camera_root → Camera_root_1 → Camera层级Camera_root初始 y 轴旋转 180°Camera_root_1控制 z 轴距离Camera 组件控制 FOV如需导出.me舞蹈 Mod使用MEDanceModCreator填写元数据经ME Mod Exporter导出。常见问题与应对音画不同步优先检查音频时长是否与动画一致播放器已内置leadSeconds提前量与先音频后动画的播放顺序来缓解缓冲问题仍不同步时可配合手动同步滑块微调。表情不生效确认角色模型是否带日式 MMD BlendShapes若没有确认播放器附带的DummyBlendshapeMesh与AvatarDanceShapeConverter处于启用状态它会把 MMD 表情转换为UniversalBlendshapes通用表情。角色跳舞时部件消失播放器在角色切换后会开启所有SkinnedMeshRenderer的updateWhenOffscreen对应SMRHandle工具舞蹈期间若仍出现部件丢失可在播放器工具中排查代理渲染器遮挡设置。直接使用舞蹈 controller 出现大量参数警告属已知问题播放器设计上使用自定义的CustomDanceAvatarController覆盖原控制器请勿绕过。参考资料仓库内进一步阅读舞蹈文件规范原文Assets/StreamingAssets/CustomDances/README_dance.mdCustom Dance Player 组件说明含脚本职责划分Assets/MATE ENGINE - Custom Dance Player/README.md播放器主逻辑AvatarDancePlayer.cs表情转换AvatarDanceShapeConverter.cs 与 UniversalBlendshapes.cs列表增强工具AvatarDancePlayerTools.cs舞蹈 Mod 导出MEDanceModCreator.cs 与 ModExporterWindow.cs赞分享桌面应用数字人AI 应用【免费下载链接】Mate-EngineA free Desktop Mate alternative with a lightweight interface and custom VRM support, though with more features.项目地址https://gitcode.com/gh_mirrors/ma/Mate-Engine点击查看免费下载相关推荐AtlasOS 驱动优化完整指南按症状下药用 4 个工具解决低帧、推流卡顿与输入延迟AtlasOS 驱动优化完整指南按症状下药用 4 个工具解决低帧、推流卡顿与输入延迟 这是一篇 AtlasOS 驱动优化指南。AtlasOS 是一个开源的桌面应用数字人AI 应用Wormhole-crypto实战指南使用encryptStream和decryptStream处理数据流Wormhole crypto实战指南使用encryptStream和decryptStream处理数据流 Wormhole crypto是基于RFC 818密码学如何用AI舞蹈生成器创作专业级3D舞蹈终极免费教程如何用AI舞蹈生成器创作专业级3D舞蹈终极免费教程 想要创作令人惊艳的3D舞蹈动画吗现在通过AI舞蹈生成器技术任何人都可以轻松生成专业级的舞蹈动作人工智能深度学习媒体生成计算机视觉上一篇完整实战指南如何高效部署开源远程设备管理平台MeshCentral下一篇如何使用TikTokDownload工具高效下载抖音无水印视频完整实用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考