Thursday, October 17, 2013

Unity and version control

Here's some info of version control in Unity for this fall's game project course. Summary: it's ok to use git, svn etc. if you know a few tips, and Aalto doesn't have licenses for Unity's own version control system (the Asset Server). Only add the Assets and ProjectSettings folders to version control. Don't add the automatically generated Library folder or the monodevelop and visual studio solution files.

Also: DON'T SWITCH BACK TO UNITY WHILE YOU'RE GETTING/UPDATING FILES FROM VERSION CONTROL. This will cause major errors, as Unity starts importing and reimporting the files right away, and in the process it may create new .meta files if the correct .meta file was not yet updated.

Basic info about setting up external version control: 

Some additional points:
  • If you are using Unity Pro or Academic (e.g., school computers) go to project settings/editor and set asset serialization to "force text", which enables svn, git etc. to merge the files. 
  • However, the merging doesn't always work, and to minimize conflicts, you should avoid modifying your scene files. The way to do this is to have everything as prefabs and edit the prefabs instead of modifying the scene. This way, it's less likely that several people modify the same file.
  • Enabling external version control as explained in the document above creates a .meta file for each file. Always remember to add the metafiles to your repository. The metafile contains the unique identifier (GUID) that Unity uses, e.g., when you link a prefab to a script's public GameObject property. If you don't commit a metafile to the repository, it will be regenerated on each person's machine with different GUIDs, which breaks the object linking and you get null reference errors.
  • Be careful when moving and deleting assets. If you delete or move assets inside the Unity editor, svn etc. will of course bring them back when you update before committing your changes. However, once the metafiles are in use, you can safely move and delete files outside Unity as long as you move and delete the metafiles too. Unity will recognize the moved assets as the same ones based on the metafiles.
  • When googling to check if there's a good tutorial or if I missed something above, I noticed there's quite a lot of "free version of Unity doesn't support version control". However, things have changed and as of version 3.5., metafiles are no longer a pro-only feature.
  • The "force text" option is apparently a pro-only feature, but there are workarounds: &

Unity and FMOD Studio integration

Edit 12 June 2014: This post was based on the very first FMOD Unity integration from fall 2013. There's been changes and the project file should probably be updated. Please (also) check some more recent tutorials.

There's finally an official FMOD Studio integration for Unity, available from It has just been released and contains no Unity examples, so I prepared a bare bones Unity project and an example FMOD Studio project that you can download from here

The main reason to use this is that it enables your sound designers to edit, mix and master your game audio using the FMOD Studio interface while the game is running. Using FMOD studio, you can also create, e.g., a footstep sound event that will randomize the pitch and selected sound sample without the game having to know anything else than the name of the event. Using FMOD is free for non-commercial purposes and the license prices are also pretty reasonable for commercial work.

Most commercial games with decent sound design use such live mixing and centralized sound management approach, either using FMOD, WWise or some custom tools. Unity does use fmod for its own sound, but it does not provide any mixing tools and a sound designer will go insane if he/she has to manage hundreds of sound objects in the Unity editor. The main limitation of the FMOD Studio integration is that it only supports iOS, Android, Windows, Mac but no web player. If you want your sounds to work in the web player, I suggest you check out the Clockstone Audio Toolkit that provides mixing and management on top of Unity's internal sound system.

Here are the steps you need to add FMOD Studio support to your Unity project. These instructions can also be found in the readme.txt of the .zip above.

  1. Import the fmodstudio10203.unitypackage from this folder. You can also check for a later version from To import in Unity editor, select Assets/Import Package/Custom package.
  2. build your FMOD banks (File/Build)
  3. In Unity, select FMOD/Refresh Event List and select the GUIDs.txt from your FMOD project's Build folder. Note: you need to do this whenever you rebuild the FMOD project. This will create FMODAssets and StreamingAssets folders in the Unity project and copy the FMOD banks to the StreamingAssets folder.
  4. When your scene starts, load a bank (see the Start() method in main.cs)
  5. Use the FMOD_StudioSystem helpers such as PlayOneShot() to play sound. See the OnGUI() method of main.cs. You might also have to use the lower level API (fmod.cs, fmodstudio.cs), as the unity integration package has been released very recently. The integration package doesn't contain any examples, and for example code, you should consult the c++ examples in the FMOD Studio API install, which you  can download from
  6. To enable live mixing using FMOD Studio, uncomment the first line of FMOD_StudioSystem.cs, found in the plugins/FMOD folder. Also check the "Run in background" checkbox in Unity Editor. You'll find that by selecting Edit/project settings/player and then selecting the Resolution and Presentation panel in the Inspector. Now press play in unity, select File/Connect to game in FMOD Studio and click ok. You can now adjust audio event properties on the fly while the game is running. 

Thursday, October 10, 2013

Unity Mecanim and ragdolls

Update 17 May 2014: If you're interested in physics simulation and character animation, check also our latest research. Also, please note that Mecanim has had some changes since the original post, and now the script could be implemented more elegantly. I also haven't tested the script with different characters - the comments suggest that some characters with different bone structure might not work out of the box.

Sharing a Unity project with a RagdollHelper.cs script that can be used to turn a Mecanim character into a ragdoll and then back. Using the script is simple: there's just one public property called "ragdolled", which can be set to true or false. When the property is changed from true to false, the script blends from the ragdolled pose to a get up animation. This is illustrated in the video below.

Transitioning from Mecanim animation to a ragdoll is as easy as disabling the Animator component of the character and setting all ragdoll rigid bodies to non-kinematic. The reverse is more complex, and my solution is not without kludges, as Mecanim doesn't allow as low level control of the animation as Unity's older animation system. The main problems are that one can't use scripting to enforce an immediate state transition without a blend, and apparently one can't also add states programmatically into an animation controller.

In the old animation system, one could create a new animation clip from the ragdoll's current pose, turn of ragdolling and blend the animation from the created clip to a recovery animation. In Mecanim this is not possible, and after turning Mecanim back on, we have to manually lerp the hip position and slerp all body part rotations back towards the last ragdolled pose in LateUpdate() to achieve a smooth blending. Additionally, we have to wait some frames for Mecanim to transition to the get up animation while using LateUpdate() to move the pose back to the ragdolled one, and then read back the get up animation start body orientation and position, and update Mecanim character's root so that the animated orientation and position match the ragdolled one as well as possible. In the old system we could just update the character transforms with a single script command according to a specific frame of a given animation, and then read whatever info we need. Actually we could possibly use the legacy animation system for that, but then the script would need additional handles to the animation etc., so it seems there's no really simple and beautiful way. One could also perhaps use an editor script to precompute the info.

Here's the Unity project as a zip file in case someone finds it useful:

Open the test scene, click with mouse on a body part to add an impact to the character, press space to make it get back up.

Update 5 Dec 2013: Today I noticed that Unity 4.3 has added the Animator.Update() which could be used to implement the ragdoll to animation blend more elegantly without the LateUpdate() trickery. I'll have to update this example when I have time.