vhAssets

Overview

Unity

Unity is available within ICT.  The latest version is available through SVN here:

https://svn.ict.usc.edu/svn_vh/trunk/core/Unity

This location has the latest up-to-date version of Unity, with the documentation pruned for space.

The entire Unity distribution is available here.  

https://svn.ict.usc.edu/svn_vh/vendor/unity/current

Also, all previous versions of Unity are tagged in this vendor branch as well.

Please note that you need a Serial # for Unity Pro.  Please contact Helpdesk for a Serial #.

For projects, it is recommended to use the version of Unity in SVN.  It is virtually the same as installing Unity from the web site*.  But you get the bonus of:

• Knowing that every person on the project is using the exact same version of Unity.
• Upgrading to a newer version is as easy as updating the svn external.  No need to uninstall, distribute the installer, etc.
• Allows different projects to use different versions of Unity, depending on their timetables.  Very useful when working on multiple projects on the same machine.

* The only difference in installing Unity vs using SVN is that certain file associations are not registered (in Windows).  So, double-clicking on a .unitypackage will not open it.  But right-click->Import New Package works fine.

More internal Unity documentation can be found here:  /wiki/spaces/com/pages/16056743

Location

vhAssets is distributed via the Unity packages.  They are built regularly by our build server, so they will always contain the latest code.  It can be found, along with all of our other Unity packages here:

\\vhbuild2\VHToolkit-Builds (sort by Date)
\\roscoemini\fast\build\sbm-Builds 

The source for this package is stored here at https://svn.ict.usc.edu/svn_vh/trunk/lib/vhunity

First Time Installation

1. Bring the .unityPackage file inside of your Unity project Assets folder
2. Double click it
3. Click Import
4. Add all the imported files into svn

Upgrading

Upgrading .unitypackage files is a little more difficult.  This quote from the Unity docs explains it:

"For the cleanest possible upgrade, it should be considered to remove the old package contents first, as some scripts, effects or prefabs might have become deprecated or unneeded and Unity packages don't have a way of deleting (unneeded) files (but make sure to have a security copy of the old version available)."

The easiest way I've found is to use the approach the SVN docs recommend for vendor branch upgrades.

1. remove all files from the folders you are upgrading (leaving the .svn folders)
2. install the .unitypackage as normal
3. bring up the SVN Commit dialog.  Then SVN Add all 'non-versioned' files, and SVN Delete all 'missing' files.

Users

Through the Unity Editor, many variables of vhAssets script components can be customized

DebugConsole

Captures all SmartBody and Unity log ouput and display it to user. Also can be used to send commands. Type '?' for a list of available commands.

FreeMouseLook

Loading Screen

Provides functionality for full screen image

VHWayPointNavigator

VHTimeDemo

Works with VHWayPointNavigator and FpsCounter to track performance along a specified path in the scene and then uploads fps/performance data to a database

SmartBodyManager

Interfaces with SmartBody.dll to provide SmartBody character animation to unity

UnitySmartBodyCharacter

Works with SmartBodyManager to have a SmartBody driven character inside of unity

VHMsgManager

Interfaces with VHMsg that allows communication via strings between processes

Developers

All vhAssets code can be modified directly in the repository https://svn.ict.usc.edu/svn_vh/trunk/lib/vhunity/vhAssets

Here are some examples for common functionality that is modified on a per project basis

DebugConsole

Add a new command callback for an arbitrary command

m_Console.AddCommandCallback("some_command", new DebugConsole.ConsoleCallback(HandleConsoleMessage));

void HandleConsoleMessage(string commandEntered, DebugConsole console)
{
      if (commandEntered.IndexOf("some_command") != -1)
           // Do Something
}

To use the console, at run-time hit the ~ key. Type '?' and hit enter to see a list of commands. If you used the code above in your script, you should see "some_command" in the list. Note, you can pass additional arguments with these commands.

Send arguments with a command while typing in the console

vhmsg someMessage

VHMsgManager

Subscribe to a certain type of message

vhmsg.SubscribeMessage("someMessage");

Subscribe to all vhmsgs

vhmsg.SubscribeMessage("*");

Send a vhmsg

vhmsg.SendVHMsg("someMessage someParam1");

Handle a message

vhmsg.AddMessageEventHandler(new VHMsgBase.MessageEventHandler(VHMsg_MessageEvent));

void VHMsg_MessageEvent(object sender, VHMsgBase.Message message)
{
     string [] splitargs = message.s.Split( " ".ToCharArray() );
     if (splitargs[0] == "someMessage")
          // Do Something
}

Build Process

You can customize the build process by creating and modifying a BuildSettings.xml file.

1. Inside the assets folder in your unity project, create a file called BuildSettings.xml

2. In the same folder as the Assets folder within your Unity project create a .bat file with the following lines

   @setlocal
   set PROJECTPATH=%CD%
   pushd ..\Unity
   call runEditorBatch.bat -projectPath %PROJECTPATH% -batchmode -nographics -quit -executeMethod UnityStartup.PerformWindowsBuild
   popd
   @endlocal

3. Use the following template for custom modification

   <?xml version="1.0" encoding="utf-8"?>
   <BuildSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cpandl.com">
     <ExternalAssetsPaths>
       <string>Assets/SomeDirectory</string>
       <string>Assets/SomeOtherDirectory</string>
     </ExternalAssetsPaths>
     <BuildOutputPath>Builds/YourProject/YourProject.exe</BuildOutputPath>
     <PostBuildScript>somePostBuildScript.bat</PostBuildScript>
     <ConfigFiles>
       <string>Assets/config.ini</string>
     </ConfigFiles>
   </BuildSettings>

BuildSettings.xml Format

Config File Parsing

You can create a config .ini file in your project and read it using the IniParser class

m_ConfigFile = new IniParser(configFileName);
m_ConfigFile.GetSetting("SomeSetting") // returns a string with the value of that setting, if it exists

Known Issues

FAQ

FAQ