MMU Generator
The MMU Generator is a Unity package, which helps to easily develop and deploy MMUs without needing to take care about the complexity of handling Unity and C# development files. The current version of the MMU Generator is tested in Unity 2018.4.1f1. We cannot guarantee it will work with other Unity Versions.
There are two options for installing the MMU Generator. One is to clone the tools repository and load the Unity project, the other approach is by importing the released Unity package in an existing project. Both approaches require Unity version 2018.4.1f1 to be already installed on the system. We recommend using the Unity Hub for easier installation.
Use a git client to clone the repository or download it from the Github page. Open the Unity Hub and add the Unity Project (aka the folder "MMUGenerator") from the repository.
Create or open a new Unity project with version 2018.4.1f1. Download the released Unity Package. Once the Unity project was loaded, open the import dialog from the menu in "Assets" - "Import Package" - "Custom Package". Afterwards, select the downloaded package and import all Assets.
´
Ensure, that the "API Compatibility Level" is set to ".Net 4.x" in the player settings. To open the player settings, select "File" - "Build Settings" from the Unity menu and click on "Player Settings" in the build settings dialog.
Once the installation is complete, there should be a menu item "MMI" in the Unity menu and no new error messages should appear.
In order to compile and deploy the MMU, you need to copy the UnityEngine.dll to the dependencies folder. We are not allowed to publish UnityEngine.dlls in Github, hence, they have to be copied on the local machine. You will be able to find the UnityEngine.dll in your Unity installation folder in Editor\Data\Managed\UnityEngine.dll. In Windows using the Unity Hub, for example, the full path is C:\Program Files\Unity\Hub\Editor\2018.4.1f1\Editor\Data\Managed\UnityEngine.dll. Please copy the UnityEngine.dll to your MMUGenerator folder in Assets\MMUGenerator\Dependencies and rename the file there to UnityEngine.dllx.
There are two pipelines to create MMUs with the MMU Generator. The first pipeline is considered for the pure replay of motion capture data and requires no knowledge of C#, Animators, or the MOSIM Framework. It is a good starting point but will only result in rudimentary animation replay that will not generalize.
The second pipeline assists Unity developers in integrating existing animations and animators to the MOSIM Framework. It sets up the rudimentary MMU class, which has to be extended further. This approach requires prior knowledge in C#, Unity Animators, and ideally the MOSIM Framework.
In order for a simple MMU replaying a motion capture take, we assume that the motion capture data was preprocessed (e.g. denoised, cut, and cleaned) and is available in a *.fbx file format.
Inside the Unity project which includes the MMU Generator, the MMU creation process can be started from the MMI - Menu ("MMI" -> "MMU Creator", see above). If the default scene was not yet opened, the dialogue will first ask to open it. Click on "Open default scene", if required.
Please enter the MMU information in the Setup MMU dialog. The name is used to generate class files, hence only use valid class names (e.g. no white-spaces, no special characters, no leading number) to ensure an error-free experience. To create an MMU replaying motion capture recordings select the "Should the MMU play MoCap recordings?" toggle and choose a FBX file. Afterwards, press the "Setup" button.
After the animation was imported, it will be displayed on the reference character. A new folder with the MMU content will be created. In addition, a simple Animator graph will be created to replay the motion-capture animations. If the FBX file contained more than a single animation, the specific animation can be replaced in the Animator. The source code required to run the MMU will be included in the Scrips folder and can be adapted before exporting, as well. For more information about MMU development in Unity, please consider the respective Wiki article on MMU Development in Unity.
It is possible to use the MMU Generator in order to integrate a more complex animator into the MOSIM Framework. In this example, we assume that the Unity animator was already set up and the blend trees can be controlled in a meaningful manner, for example blending different wave animations together to wave in a particular direction.
For more information on Unity Animation Controllers, please consult our Introduction to Unity Animators.
Inside the Unity project which includes the MMU Generator, the MMU creation process can be started from the MMI - Menu ("MMI" -> "MMU Creator", see above). If the default scene was not yet opened, the dialogue will first ask to open it. Click on "Open default scene", if required.
Please enter the MMU information in the Setup MMU dialog. The name is used to generate class files, hence only use valid class names (e.g. no white-spaces, no special characters, no leading number) to ensure an error-free experience. To create an MMU replaying motion capture recordings do not select the "Should the MMU play MoCap recordings?" toggle. Afterwards, press the "Setup" button.
After pressing the Setup button, a new folder for the MMU (in this example named ComplexWave) will be created. The folder contains the reference character, a description file and a script in the name of the MMU (in this example named ComplexWave.cs). The reference avatar will be added to the scene and should contain the MMU script as a component.
The MMU Script will not be complete and must be finished, before testing and/or exporting the MMU, as it is not functional as is. For more information about MMU development in Unity, please consider the respective Wiki article on MMU Development in Unity.
In order to test a MMU, three components are required:
- there has to be a running version of the MMI Environment installed and started (see Core Documentation).
- there has to be a target engine running that is using the MMU / motion type (see Core Documentation).
- there has to be an executable implementation of the MMU linked to an Adapter
To link your implementation to an adapter inside the MMU Generator, simply add the MMU Adapter component to the avatar. Inside the component, the system specifics for the MMI Framework can be adapted (e.g. port and IP address, if required).
In order to export the MMU, click on the "Export as zip file" button in the Setup MMU Dialog in the MMU Generator project. Do not forget to remove the MMU Adapter component before starting to export. The exported MMU can be integrated into the MMI Framework to be automatically loaded and utilized after exporting. Please be aware, that the source code is not exported and hence should be backed up separately.
Next to the export option in the Setup MMU dialogue of the MMU Creator, there is a button for creating a new MMU (see above).
Once clicked on the "Create a new MMU" Button, it will permanently delete your current status of the MMU development. Please consider to backup your state to a separate folder, before (e.g. copying it to a "Sandbox" folder).
The following issues are known:
Please check the Unity Version of your current project (it should be 2018.4.1f1) and check the API compatibility level (it should be .Net 4x, see above).
Please check, whether the MMU name qualifies for a class name, or whether it contains wrong characters (e.g. white space).
After restarting the target engine, the MMUs are not loading anymore and the MMU Adapter throws the error
ArgumentException: An item with the same key has already been added. Key: 1
This is a known bug, which can be solved by restarting the MMU Generator.