Mate Engine - Custom Dance Player
Other Language Versions: English, 中文
a unified clarification here:
- This mod is released at here. Specifically, it can load and play dance .unity3d files compatible with the 7 Days to Die's VRoidMod. All 250+ dance files are available for download from my cloud drive: https://drive.google.com/drive/folders/1YU7-Hz-O8-9B2E58mxQxexJTBTCT42jr?usp=sharing. Detailed instructions on how to create dance files are also provided on the mod’s release page.
- After the release of MateEngine 2.4, through the joint efforts of Shiny and me, this mod has been integrated into the official features. The official dance player will be more comprehensive and polished in the future, and it can still load and use the old dance .unity3d files (even when placed in the original dance folder).
- However, this doesn’t mean the mod is unusable — you can still continue using it, but no additional support or updates will be provided afterward, and it won’t be able to load dance files made with the official mod exporter.
- If you have suggestions or bug reports for the official dance player, you can submit them in the official GitHub Issues section or the corresponding post.
- If you encounter issues with some .unity3d files, since these files were created by my friend and me, you can report them via issue, and please include detailed information.
- I’ve consulted a friend (he was the one who first taught us to make these files and converted most of the dances in the cloud drive; everyone in our community respects him deeply), and he disagrees with uploading the dance files to the Steam Workshop, so I won’t upload them either. However, you can still download them from my Google Drive — please do not upload the old .unity3d files to the Workshop. Additionally, I recommend that every user abide by the rules of the MMD community.
在这里做一个统一澄清：
- 这个 mod 发布于这里。具体来说，它能加载并播放可用于 7 日杀（7dtd）VRoidMod 的舞蹈.unity3d 文件，所有 250 + 个舞蹈文件可从我的谷歌云盘下载：https://drive.google.com/drive/folders/1YU7-Hz-O8-9B2E58mxQxexJTBTCT42jr?usp=sharing 舞蹈文件的制作方法，在 mod 发布页也有详细说明。
- MateEngine 2.4 版本之后，经过 Shiny 和我的共同努力，这个 mod 已整合为官方功能。官方舞蹈播放器未来会更全面、更完善，且仍能加载使用旧的舞蹈.unity3d 文件（甚至可放在原舞蹈文件夹中）。
- 但这并不代表该 mod 无法使用 —— 你依然可以继续使用它，只是后续不会再提供额外支持与更新，也无法加载官方 mod 导出器制作的舞蹈文件。
- 若你对官方舞蹈播放器有建议或 bug 反馈，可在官方 GitHub 的 issue 板块或对应帖子中提交。
- 若发现部分.unity3d 文件存在问题，由于这些文件由我和朋友制作，可通过issue反馈，务必附带详细信息。
- 我已询问过一位朋友（他最早教会我们制作这类文件，还转换了云盘中的大部分舞蹈，社区里每个人都很尊敬他），他不同意将舞蹈文件上传至 Steam 创意工坊，因此我也不会上传。不过你们仍可从我的谷歌云盘下载，请不要将旧的.unity3d 文件上传至创意工坊。此外，建议每位使用者都遵循 MMD 社区的相关规则。
For users in China, please watch this video:
https://www.bilibili.com/video/BV1Yge6zqETU/
If you have any questions, feel free to leave a comment below the video.
You can also post on the Discord page:
https://discord.com/channels/1367667737437929513/1408758200462999583
Previously, I was a player for 7 Days to Die—. There is a mod VRoidMod by author Alter that was well-received by the Chinese community. It allows players to switch character models and perform dances in the game.
Along with friends from the community, we converted over 250+ dance files for use with VRoidMod (mainly from MMDs, and the number is still growing). We also experimented with embedding facial expression curves and camera curves into animations, letting us dance to MMD-style animations whenever we felt bored in 7 Days to Die! You can see the effect in this video
https://www.bilibili.com/video/BV12Cb6zjEfS/
After discovering the MATE-ENGINE project, I found it very interesting and wondered if I could adapt the dance files we created for 7 Days to Die to work with MATE-ENGINE. I also noticed multiple requests for custom dance functionality in MATE-ENGINE’s GitHub Issues, so I decided to develop this mod.
This is a custom mod developed for the Mate Engine desktop pet game. Its core functionality is to add "dance player" capabilities to the desktop pet—supporting custom dance resource loading, playback mode switching, playback control, and an intuitive UI interface. Users can manage the pet’s dance playback just like operating a music player.
You can download the latest release of the mod (does not include dance files) here:
https://github.com/maoxig/MateEngine-CustomDancePlayer/releases
The mod consists of three main parts:
-
.me Mod Package: Contains UI prefabs (e.g., playback control buttons, track dropdown, status text) and basic UI style resources, exported using the MATE-ENGINE SDK.
-
DLL Scripts: Handle core logic, including dance resource loading/unloading, playback state management, and UI event binding. This part involves custom C# scripts and may require modifying game DLL references in dangerous ways (which may not be permitted). By using this DLL, you acknowledge that you trust this repository—you can review the source code to understand its implementation, or fork the repo to modify and compile your own version.
-
Dance Files: Custom dance resources that must follow specific formatting (see Usage Guide). You can also download pre-converted dance files (a subset of the 100+ files my friends in 7 Days to Die community created, mostly converted from MMD motion data):
- https://www.nexusmods.com/7daystodie/mods/3956
- https://www.nexusmods.com/7daystodie/mods/5430
- https://www.7risha.com/rolemodel (may be less user-friendly for non-Chinese users, apologies)
Important for Non-East Asian Users: These .unity3d files may contain Simplified Chinese, Traditional Chinese, Japanese, or Korean (CJK) characters in their filenames. Ensure the files unzip and display correctly (adjust your unzipping software’s name encoding settings, install required fonts, etc.), otherwise the mod may fail to load the dances.
If there is sufficient interest, I may collect all dance files and upload them to a cloud storage service. (Note: These files are converted from MMD .vmd motion data—please comply with relevant laws and copyright regulations when using them.)
Edit: I have uploaded a dance file pack containing 250+ converted dance files. The link is as follows: https://drive.google.com/drive/folders/1YU7-Hz-O8-9B2E58mxQxexJTBTCT42jr?usp=sharing
You must ensure that the filenames are displayed correctly and that you do not rename the files, and also make sure to place them in the correct directory. (See step1.3)
- Mate Engine desktop pet game installed
- Downloaded .me & .dll files from here
- Downloaded dance files (with .unity3d extension)
You can view the mod release page on Discord, there is a tutorial video.
https://discord.com/channels/1367667737437929513/1408758200462999583
The mod requires both the .me Mod Package and DLL Scripts to work.
This step requires caution, as it may cause game crashes or unexpected behavior. Backup the files you intend to modify first. Game updates may also require you to reapply these changes—this is the simplest method I’ve found so far, but better alternatives may exist.
a. Place the CustomDancePlayer.dll file into the game’s MateEngine\MateEngineX_Data\Managed folder.
b. Modify MateEngineX_Data\ScriptingAssemblies.json to reference the new DLL:
- Add "CustomDancePlayer.dll" to the "names" array.
- Add 16 to the "types" array.
If all steps above are completed correctly, you will see the mod’s UI panel. Place your downloaded .unity3d dance files into the MateEngineX_Data\StreamingAssets\CustomDances folder, then click the "Refresh" button in the UI to load the dance resources.
No extra explanation needed—it’s straightforward: load dance files from disk in a specific order and play them like a music player.
Nearly all the .unity3d dance files 7DTD community created support facial expressions (since most are converted from MMD motion data, which typically includes expression data). However, this requires the character model to follow specific conventions:
The Skinned Mesh Renderer on the model’s "Body" object must include MMD-style Japanese-named blend shapes:
If you convert a PMX model to FBX/VRM using Unity’s MMD4Mecanim + uniVRM plugins:
- Before conversion, go to MMD4Mecanim’s advanced settings and uncheck "PrefixMorphNoName" (this option adds numeric prefixes to blend shape names, which breaks compatibility).
- Adjust the model’s hierarchy to match the structure shown above.
For other model types, the most universal solution is to modify and adjust the model in Blender to meet the above conventions.
We implemented MMD-style camera movement in 7 Days to Die, but MATE-ENGINE may not require camera functionality.
The mod works just like a standard music player—controls are intuitive and require no additional explanation.
-
Global Hotkey:
H: Show/Hide UI
-
Playback Modes:
- Single Loop
- Playlist Loop
- Shuffle
-
Settings:
persistent settings are saved in
C:\Users{YOURUSERNAME}\AppData\LocalLow\Shinymoon\MateEngineX\danceSettings.jsonfile. If you run into issues that seem to be caused by the config file, try deleting this danceSettings.json to see if it fixes the problem.- Volume control
- Animation start delay (default: 0.3s)
- UI follows character
- Shadow panel follows character
- Auto-play on startup
- Hide UI on startup
Dance resources must follow these rules to load correctly. I also provide a toolbox to help you quickly convert MMD motions, expressions, and camera data into compatible dance files (takes ~3 minutes per file):
https://github.com/maoxig/UnityMMDConverter/
Each dance corresponds to one .unity3d AssetBundle, which must contain the following resources (filenames must match exactly):
| Resource Type | Filename Specification | Description |
|---|---|---|
| Animator Controller | [DanceName].controller |
A simple single-state controller: Create a new Animator Controller, then drag the corresponding [DanceName].anim file into the controller window. Unity will automatically generate a single animation state, and the controller’s "Entry" (default entry point) will have an unconditional transition to this state. |
| Audio File | [DanceName].wav/.mp3/.ogg |
Supports 3 common audio formats. Duration must match the animation (to avoid audio-visual desync). |
| Animation | [DanceName].anim |
Must include the dance’s animation data. |
Example:
For a dance file named "HappyDance.unity3d", the AssetBundle must contain HappyDance.controller, HappyDance.mp3, and HappyDance.anim.
Place your .unity3d dance files into the StreamingAssets/CustomDances directory. The mod will automatically detect them and add them to the track list.
The overall logic is simple—you can easily understand it by reviewing the source code. To modify the mod:
- Drag the .prefab files into your MATE-ENGINE Unity project, along with the relevant scripts, to edit the UI.
- To modify the DLL scripts: Edit the code in Visual Studio, compile it into a DLL, and import it into Unity.
- Check if the DLL loaded successfully (the UI will show a warning if the DLL is missing).
- Ensure the mouse focus is on the MATE-ENGINE window.
- Verify the file path: Ensure
.unity3dfiles are placed inStreamingAssets/CustomDances. - Check for garbled filenames: Avoid special characters or unrecognized symbols in filenames (these can break controller/audio loading).
- The UI now uses Unity's default text component, which usually prevents garbled characters. If you still see square boxes, check if your system fonts support CJK characters.
- Please check the following:
- Ensure all files are placed in the correct directories and filenames have not been changed (the game and mod depend on specific filenames).
- Try reloading the game or restarting the software.
This mod is open-source under the MIT License and complies with the official Mate Engine License. It is permitted for personal non-commercial use, modification, and distribution, but prohibited for commercial profit. By using this mod, you agree to abide by the official Mate Engine terms. The developer is not liable for any game errors or issues caused by this mod.
- License Details: MIT License, MATE-ENGINE License
- Prohibited Actions: Integrating this mod into commercial software without permission, or redistributing it after removing copyright information.
- Note for Japanese Users: The aforementioned .unity3d dance files may involve copyright issues in Japan (most are converted from MMD motion data, which may not be permitted). Do not upload these files, images, videos, or other related resources to public platforms.
If you encounter issues or have feature requests, please provide feedback via:
- GitHub Issues: Submit an Issue
Last Updated: October 6, 2025
Compatible Mate Engine Version: 2.2.0