Unity Runtimes

Overview

This document describes how to use the Unity runtimes. The language of the runtimes is in C#. We will go through an example of how to load an exported JSON file and play it back in the scene.

Video Tutorial

Click here to watch the Unity Integration Video tutorial.

Click here to watch how to integrate Normal and Ambient Occlusion Maps into a Dragon character in Unity using the Creature Unity Runtimes.

Click here to watch how to playback a character with Animated Region Ordering exported from Creature.

Click here to watch how to create 2D Side-Scrolling Platformer Game Mechanics using the Creature Plugin for Unity. The sample project for the platformer demo can be downloaded here.

Click here to watch a tutorial on how to Author Frame Callback Triggers using the new Event Authoring Editor in the Creature Tool itself. The exported event triggers can be loaded in from Unity.

Click here to watch a tutorial on how to use the Live Sync functionality to sync up animation changes live between Unity and Creature Pro for Windows.

Click here to watch a tutorial on how to instantiate Live Bend Physics Motors from within Unity. This allows real-time dangling bone chains to interact with user input/environment/gameplay.

Click here to watch a tutorial on how to use Skin Swap in your gameplay characters for Unity. Skin Swap is a feature that is useful for swapping of in-game items like clothing, hairstyles, weapons, items etc. in your custom gameplay.

A Tutorial teaching you how to activate Morph Targets it in Unity can be found here here.

Grabbing the runtimes

You can either download the runtimes directly from the Creature Game Runtimes window or grab them from the repository here.

Full Runtime vs CreaturePack ( Need higher performance playback for crowds? )

There is a alternative, lightweight plugin called the CreaturePack runtime designed for high performance playback of lots of characters. If this is what you are looking for, please head over here.

Adding Unity Objects

After you have added in the provided runtime scripts, an extra Creature menu appears under the GameObject menu:

The components available are:

• CreatureAsset: This object does the loading and management of the JSON animation data.

• CreatureRenderer: This object does the actual rendering of the character. It has a slot that you will point to an available CreatureAsset object.

• CreatureGameController: This object is added as a child of the CreatureRender object. It manages and creates rigid collider objects for each bone in the character. It will also move the collider objects with the bones under animation.

You will need all 3 objects to accomplish character animation playback in Unity.

Step 1: Add CreatureAsset

Click on the main menu Creature->CreatureAsset to add a new CreatureAsset object. This object has the following properties:

In this example, we have an animation JSON file containing some ninja animation. It is called ninjaTest. We set this object to load and manage the JSON file by pointing the Creature JSON input slot to our ninjaTest asset file. As you can see once the file is loaded, the available animation clips will be shown in the inspector automatically. In this case, there are 3 animations available in the file: default, running and attack.

Step 2: Add CreatureRenderer

Click on the main menu Creature->CreatureRenderer to add a new CreatureRenderer object. This object has the following properties:

You will set the Creature_asset input slot to reference the CreatureAsset object you just created. Once that is done, a couple more attributes will show up:

• Local_time_scale: This is a multiplier on the playback speed.

• Region offsets z: This is a value that defines how much of a z offset each underlying mesh region has. Use this to "push" your various mesh regions of your character out if you are experiencing z fighting rendering artifacts.

• Counter clockwise: This sets the winding order of the rendered triangles of the mesh. If your mesh is not showing up due to backface culling, you can check this option to change the winding order and make it appear.

• Animation: This sets the currently active animation for playback.

• Loop: Decides if the animation is looping or not.

Please also remember that this object does not yet draw anything on screen. You will need to add in your Material component typically pointing to your character's texture atlas PNG image to make the character rendering appear. One Material you can start out with easily is to use the Sprites/Default Material.

Step 3: Add CreatureGameController

Select your previously created CreatureRenderer object, then click on Creature->CreatureGameController and create a new CreatureGameController object as the child of the current CreatureRenderer object. You should get something like this in the Hierarchy view:

The CreatureGameController has the following properties in the inspector:

• Creature_renderer: Set this to reference your CreatureRenderer object.

• Collider Height: This defines the height of the each bone collider. Bone colliders are kinematic so they are not driven by physics but rather animation.

• Sim Collider Width and Sim Collider Height: These define the dimensions of the main character collider. This collider is created for the entire character and is the one that is driven by physics.

To start off using this object, click on Build Skeleton Objects. The object will automatically traverse your character's bone hierarchy and create kinematic colliders for every bone in the character. In addition to that, it will also create an overall Sim Collider representing the character itself. You should get something like this in the Hierarchy view:

The purpose of each bone collider being kinematic is so that they follow the animation of the character. The main Sim Collider is not kinematic and will be driven by physics. Hence, you can apply forces like gravity/player actions onto it to drive the Sim Collider. The Sim Collider motion will move the entire CreatureRenderer object with it allowing you to move your character around in the game. The individual kinematic bone colliders can be used for collision detecion with other objects(incoming bullets, damage etc.)

When the game is not running, you should be able to get a pre-vis of how the colliders are laid out in the character. The colliders will sync up with the bones when the game is actually running. When not running, the bones will be set in the rest pose and hence might not sync up with the character's current animated pose:

Speeding up Load Times with Creature Flat Binary Data

You can speed up load times of large character assets by converting your Creature JSON files over into the Creature Flat Binary Data format.

First, go onto the Creature Tools Github Page:

1. Go into the FlatData directory.

2. You can either compile the CreatureFlatData converter program or just grab the binaries for your system (Mac or Windows) from the Bin directories.

Running the CreatureFlatData Converter

This is a command line program that will take your input exported Creature Character JSON file and convert it into a binary Creature Flat Data file. We recommend you use for the final converted output binary file to have an extension of .bytes so that Unity can recognize it as a binary asset.

To run the CreatureFlatData Converter, load up the terminal/command prompt:

CreatureFlatData <Input JSON File> <Output .bytes File>

Using the Creature Flat Binary in Unity

In the CreatureAsset object:

1. First put your new Creature Flat Binary file into your project's assets folder

2. Drag the binary file into the Flat Creature Data slot of your CreatureAsset

3. Toggle the Use Flat Data Asset box to True

After completing all the steps above, the Creature Unity Runtimes should load your new Creature binary file.

Speeding up Playback with Point Caches

If you are experiencing frame rate issues in your game or want to put a lot of characters on screen, you can enable Point Caching in your animations.

Check the Point Cache toggle on each animation in the CreatureAsset object to enable it for that particular animation. When the game loads, a small amount of time will be spent generating the cache. Playback of a cached animation bypasses the posing engine completely so is on average 2x to 3x the speed of regular playback.

Animated Region Ordering

If you authored your character from Creature with Animated Region Ordering, there will be a extra file generated. This file has the extension of type .mdata. Drag this file into Unity and then rename it into JSON since it has to be seen by Unity as a Text Asset. Drag this new asset into the Creature Meta JSON slot of your Creature Asset object to activate Region Ordering.

Custom Animation Frame Callback Events/Triggers using the Creature Editor

You can now author events directly in the Creature Editor itself and export them out into the engine.

1. First, open up the Event Triggers edit window in Creature:

2. Now Add in your custom events. Events are added at the current time/frame you are on in the animation:

3. Export your character and import in the .mdata into the scene. This is covered in the Animated Region Ordering section of this document.

In order to process the event callbacks, you will need to setup a GameController. In the GameController itself, there is an event and delegate:

public delegate void eventTrigger(string event_name);
public static event eventTrigger OnEventTrigger;

If you are unfamiliar with events/delegates, please read up on how to setup something like this from the official Unity documentation page.

By connecting up your custom eventTrigger method with the OnEventTrigger event, you can listen and react to your custom authored events for your character.

Reducing JSON File size with Compressed Export & Loading

The CreatureAsset object also allows you to export and load compressed JSON assets if size is an issue. Here are the steps needed to use Compressed JSON assets:

1. Select the CreatureAsset object and click on Export as Compressed File. Pick the filename to export the compressed file to. Make sure the file ends with the .bytes extension.

2. Create a new CreatureAsset object, check the Use Compressed Asset toggle.

3. Drag the new compressed asset from step 1) into the Compressed Creature JSON slot of the new CreatureAsset object.

File compression sizes through this method are huge, a 10.5mb file can compress down to only 0.8mb ( over a 10x ratio ). Use this option if you have large Creature JSON assets or are disk space limited during deployment.

Customizing GameController for Gameplay, Method #1

The point of adding the CreatureGameController object is to allow you to customize the character in your game. Once it is all setup, you can begin to modify the actual code in the CreatureGameController object to suit your needs.

Let us say you wanted to make the ninja character respond to user keyboard input for movement. The first thing you want to do is to open up the scripting code for your CreatureGameController. In there, pay attention to the FixedUpdate() method:

// Put your gameplay code here
void FixedUpdate() {
	// Call this to make the bone colliders follow the animation in a kinematic fashion
	UpdateGameColliders();
	
	...

You will notice that there is a call to UpdateGameColliders() at the beginning. You shoudl always call this to sync up the bone and sim colliders with the character animation. Next, you can begin to add your own character gameplay code:

	// The following code is an example of how you could handle the 
	// control/behaviour of a character using this runtime
	bool left_down = Input.GetKeyDown (KeyCode.A);
	bool right_down = Input.GetKeyDown (KeyCode.D);
	bool left_up = Input.GetKeyUp (KeyCode.A);
	bool right_up = Input.GetKeyUp (KeyCode.D);
	bool attack_down = Input.GetKeyDown (KeyCode.R);
	bool attack_up = Input.GetKeyUp (KeyCode.R);
	var parent_obj = creature_renderer.gameObject;
	Rigidbody2D parent_rbd = parent_obj.GetComponent<Rigidbody2D> ();

	if (is_moving) {
		if(is_moving)
		{
			float move_vel_x = 0;
			if(is_facing_left)
			{
				move_vel_x = -50;
			}
			else {
				move_vel_x = 50;
			}
			parent_rbd.velocity = new UnityEngine.Vector2(move_vel_x, 0);
			creature_renderer.SetActiveAnimation ("running", true);
		}

		if(left_up || right_up) {
			is_moving = false;
			var cur_vel = parent_rbd.velocity;
			cur_vel.x = 0;
			parent_rbd.velocity = cur_vel;
			creature_renderer.SetActiveAnimation ("default");
		}
	} 
	else {
		if (left_down) {
			is_moving = true;
			is_facing_left = true;
		} 
		else if (right_down) {
			is_moving = true;
			is_facing_left = false;
		}

		float facing_angle = 0;
		if(is_facing_left) {
			facing_angle = 180;
		}

		parent_obj.transform.rotation = UnityEngine.Quaternion.AngleAxis(facing_angle, new UnityEngine.Vector3(0, 1, 0));
	}


	if (!is_moving) {
		if(attack_down)
		{
			creature_renderer.SetActiveAnimation ("attack");
		}
		else if(attack_up)
		{
			creature_renderer.SetActiveAnimation ("default");
		}
	} 

Read through the above code sample carefully. You will see that you can change the currently active animation by calling SetActiveAnimation() on the creature_renderer object. You can also flip the character by setting the rotation attribute on the parent_obj object. The above example will result in a character controllable by the keyboard. The overall Sim Collider is retrieved from:

	var parent_obj = creature_renderer.gameObject;
	Rigidbody2D parent_rbd = parent_obj.GetComponent<Rigidbody2D> ();
	

since the Sim Collider lives as a component on the parent CreatureRenderer object.

The character can run left when A is pressed, run right when D is pressed and attack when R is pressed. In addition to that, when no keys are held down, the character will play its default animation.

Customizing GameController for Gameplay, Method #2

There is another, much cleaner way to add gameplay logic into your characters. This still requires the existence of the CreatureGameController object.

With the CreatureGameController object added, you will also have to derive a new class inherited from CreatureGameAgent. Say you had some AI that drove your characters called Merfolk Game, you would do something like this:

using System;
using CreatureModule;
using UnityEngine;
using UnityEditor;

public class MerfolkGame : CreatureGameAgent
{
	public MerfolkGame ()
		: base()
	{
	}
	
	public override void updateStep()
	{
		// Shows you how to grab the renderer and relevant parent 
		// objects.
		var creature_renderer = game_controller.creature_renderer;
		var parent_obj = creature_renderer.gameObject;
		Rigidbody2D parent_rbd = parent_obj.GetComponent<Rigidbody2D> ();
	

		base.updateStep ();
		
		// My gameplay code here, do whatever you need to do
		// to control the character
	}
}

After that is done, create a new empty GameObject and assign it to the MerfolkGame script. Select your CreatureGameController object and under the connection Custom Agent, assign it to the MerfolkGame object. With this done, the GameController will use the MerfolkGame object during execution by calling its updateState() method.

Transitioning to new Animation Clip

There are 2 ways to transition to a new animation. First, you need to grab a reference to the base render object like this:

var creature_renderer = game_controller.creature_renderer;

For a hard transition(instant transition) to a new animation clip, call:

creature_renderer.SetActiveAnimation ("NewAnimationName", true);

For a blended gradual transition to the new clip, call:

creature_renderer.BlendToAnimation("default");

Customizing Frame Range of an Animation Clip

You can set your own custom start and end times for an animation clip. Grab an instance of the CreatureManager from the CreatureRenderer:

var creature_renderer = game_controller.creature_renderer;
var manager = creature_renderer.creature_manager;
var myAnimation = manager.GetAllAnimations()["MyAnimationName"];

// Set my own start and end times
myAnimation.start_time = myCustomStartTime;
myAnimation.end_time = myCustomEndTime;

MecAnim support in Unity 5

The Unity runtimes now support Unity State machines (MecAnim) in Unity 5. To start using it, select on your Creature Asset:

Click on Build State Machine. This will automatically generate a new state machine asset. Open it up and you will see states have been created for you representing the different animation states in the asset:

This is a regular Unity State Machine asset so you can connect up and set state transition conditions just like how you would do it regularly.

Once you are done with setting up your state transitions, go back into your Creature Game Controller and drag in the State Machine Asset:

Your animation state transitions should be active and good to go.

Overriding/Modifying Bone Positions

Sometimes you need to modify the bone positions of the character directly. For example, you might want the positions of the bones to follow a number of rigid bodies connected with springs/joints for ragdoll physics. In the cases where you need to set bone positions for your own custom requirements, you should do the following. First, write your custom bone override method. Here is an example that displaces the bones in y by some amount:

// This demonstrates the ability to override/modify bone positions 

void UpdateBonesToCustomPositions(Dictionary<string, MeshBoneUtil.MeshBone> bones_map)
{
	foreach(KeyValuePair<string, MeshBoneUtil.MeshBone> entry in bones_map)
	{
		var cur_bone = entry.Value;
		// displace each bone upwards by y as an example
		var cur_world_start_pos = cur_bone.getWorldStartPt();
		var cur_world_end_pos = cur_bone.getWorldEndPt();

		float displace_y = -20.0f;
		cur_world_start_pos.Y += displace_y;
		cur_world_end_pos.Y += displace_y;

		cur_bone.setWorldStartPt(cur_world_start_pos);
		cur_bone.setWorldEndPt(cur_world_end_pos);
	}

}

Then in the FixedUpdate() call, tell the CreatureManager to use your custom bone modify callback like this:

	// The following code sets an optional bone override callback for modifying bone positions
	CreatureManager cur_manager = creature_renderer.creature_manager;
	cur_manager.bones_override_callback = UpdateBonesToCustomPositions;
	

In Game Real-time IK

You can activate in game IK with up to 2 bones using the IK Packet framework. To use:

1. Create a GameObject->Creature->CreatureIKPacket from the menu
2. Fill in the bone names: ik_bone1 and ik_bone2 ( the 2 bones for IK posing )
3. Set the IK angle ( ik_pos_angle ) to be True or False ( this affects how the 2 bones are posed )
4. Create a generic Unity Transform object and drag it into the ik_target slot to serve as the ik positional target

Now go into your CreatureGameController, activate ik by setting ik_on to True. Set the size of the ik_packets list to 1 ( or the number of ik packets you have ). Drag the ik packet you created into the list.

Now when you play the game, your 2 bones should run ik real-time in the game and target your Unity Transform IK Target.

In Game Real-time Morph Targets

Make sure you have read the Morph Targets authoring for Game Engines documentation so that the required data has been setup in your MetaData file. Check that you have connected up the MetaData slot in your CreatureAsset. Also make sure you have a CreatureGameController available for your character. Setup the following in your CreatureGameController:

• Morph_targets_active Check this ON/OFF to enable or disable Morph Targets
• Morph_target_xform A target transform where you want to morph target to point to
• Morph_base_xform A base/source transform where the morph target is situated at, typically this can be a transform that follows your character
• Morph_radius How large a radius value affects the overall size of the blending polygon, this can be the average size of your character

Switching/Swapping out Items & Regions in Game

You can switch/swap out specific mesh regions of your character using the runtimes. This is useful if you want to perform switching of character items like hats, shoes and weapons.

Steps to setup in game item/region switching:

1. Make sure Enable Image Swap is enabled for the region you want to swap in the Creature Editor

2. Also make sure you have A Single Image Swap Knot set from the Sprite Frame Manager for the region of interest

3. For the other sprites that you want to swap in for the region, open up the Sprite Frame Manager and take note of the Tag value:

The tag value is always Negative. This value is the number you will put into the runtime later on for in game item swapping.

How to activate item switching

With item switching setup in the previous paragraph, we are now ready to trigger region/item switching in the game. This code is assuming you are modifying the CreatureGameController and overriding the FixedUpdate() callback. First, grab a reference to the CreatureManager object in your C# code:

CreatureManager cur_manager = creature_renderer.creature_manager;

With that done, you can now swap out the target region with a new image:

	cur_manager.target_creature.SetActiveItemSwap(region_name, tagID);

The region_name is the name of the region of your interest, the tagID is the tag you retrieved from the previous section.

Skin Swapping ( Costume and Item swapping )

A more efficient way of allowing character costume and weapon/item changes is to use the Skin Swap functionality. Please read up on how to setup the Skin Swap sets in the Creature Editor before continuing. When you export out your character, the Skin Swap information will be contained in the MetaData JSON. Make sure that json has been properly imported into Unity and also connected into your CreatureAsset in order to activate Skin Swap.

Once that is all setup, you simply start a Skin Swap in your CreatureAgent by calling:

EnableSkinSwap( swap_name_in )

from your CreatureRenderer object. The swap_name_in is the name of the Skin Swap set you want to switch to for your current character.

You can disable Skin Swap by calling:

DisableSkinSwap()

again from the CreatureRenderer object.

You can also author your own Skin Swap sets dynamically in-game by calling:

**AddSkinSwap( swap_name, swap_set )

swap_name is the new name of your custom set while swap_set is a hash_set of strings containing the names of the items in this set.

Anchor Points

Often times when you are animating your character, you might not have centered them at the same origin. Anchor Points allow you to specify the character's relative origin for a specific Animation Clip. This allows you to center different character animations if so desired.

1. In the Creature Editor, run Animate -> Set Anchor Point

2. Set the Anchor Point by dragging the Red Spinning Box around the character:

3. In Unity:

   CreatureManager cur_manager = creature_renderer.creature_manager; cur_manager.target_creature.anchor_points_active = true;

The second line activates the Anchor Points and makes your character animations centered on your specified anchor points.

Vertex Attachments

Vertex Attachments are exported out into the MetaData file, make sure to include and connect them up properly in Unity. The following APIs are available for Vertex Attachments:

GetVertexAttachmentPoint(string name_in) - Returns the vertex attachment point transformed into world space

Retrieving Bone Positions Easily ( For attachments etc. )

You can easily retrieve bone positions of your character via the following methods in the GameController:

• GetBoneStartPt(string bone_name) Returns the bone's start position in world space
• GetBoneEndPt(string bone_name) Returns the bone's end position in world space

Live Bend Physics

Bend Physics Motors authored from within Creature can be exported out and instantiated live within Unity itself. This means you can run Bend Physics bones that flop/react to the underlying motion of the character's gameplay movements. In order for this to happen, the Bend Physics Motors must satisfy the following criteria:

1. The chain of bones with Bend Physics must not have any children; this means it is normally a set of bones dangling at the end of the character.

2. It is recommended you do not exceed more than a chain of 3 or 4 bones, this is because the actual physics will be run with the engine's physics solver which might not be as stable as Creature's own internal editor solver.

3. There should be no gaps between the bones in the chain, this is due to the limitation of the engine's physics solver.

Bend Physics Motors that satisfy the above 3 conditions get automatically exported out into the Meta Data file of the exported character directory. Please note that you should rename the Meta Data to a .json extension in order for it to be imported into Unity. ( This is a Unity requirement )

Once you have done that, import the Meta Data json into Unity and connect it up to the Meta Data slot of the CreatureAsset object. When the slot is correctly connected, you will automatically see the Bend Physics Motors populate and show up in the CreatureAsset panel:

The attributes to understand/tweak:

• Motor Name The motor name, same as the name in the editor.

• Anim Clip Name The animation clip this motor resides in. When you instantiate the motors live, only motors matching the specified animation clip will be created.

• Active You can toggle this to Enable/Disable the motor when you instruct the plugin to create the live physics motors.

• Stiffness How stiff the live physics chain is, this value is different from the one you set in the editor since you are using the engine's default physics solver.

• Damping How damped the live physics chain is, this value is different from the one you set in the editor since you are using the engine's default physics solver.

Set the appropriate Stiffness and Damping attributes for the motors you care about. Also remember to toggle on the Active flag on the motors you want to enable.

The next step is to actually instantiate the Bend Physics Motors in your gameplay. To do that, create a CreatureGameAgent and connect it up to your CreatureGameController:

using System;
using CreatureModule;
using UnityEngine;


public class PhysicsTestAgent : CreatureGameAgent
{
    PhysicsTestAgent()
        : base()
    {

    }

    public override void updateStep()
    {
    }

    public override void initState()
    {
        game_controller.CreateBendPhysics("run");
    }
}

The actual function to call is CreateBendPhysics() with the specified anim clip to instantiate the motors from. One important note to remember is that if your character flips/changes direction ( moves left to right ), you should call CreatureBendPhysics() after the flip. This is to ensure a new set of motors are created to reflect the new orientation of the character.

Canvas Renderer

There is a Canvas Renderer as well available to render your character into a Unity Canvas environment. To use:

1. Create a new Unity Canvas object
2. Add the regular Creature Asset ( Game Object -> CreatureAsset )
3. Add a CreatureCanvasRenderer object
4. Assign your JSON/Flatbuffer data as per usual to 2.
5. Connect up the Creature_asset slot in the CreatureCanvasRenderer with the CreatureAsset you created in 2.

The following functions are available for animation control:

• SetActiveAnimation: Sets the animation to the specified animation clip name
• BlendToAnimation: Smoothly blends to a target animation
• EnableSkinSwap: Switch to a SkinSwap set if available

Additional Usage Tips

• You can have multiple CreatureRenderer objects referencing a single CreatureAsset object. This helps you save memory and is useful when you want to instance multiple copies of the same type of character.

• You should use the individual bone colliders for collision detecion. However the collision response can be applied to the main Sim Collider. That way you can get fine grained collision detection on individual body parts but an overall stable collision response on the overall character body.