Working in Unity

This Gaming Guide is a basic guide on how to import Harmony projects and configure them, and includes some tips. It is not meant as a guide on how to program games.

The Unity Interface

Game: Equivalent to Harmony's Camera view which shows you what you see through the game itself.
Scene: Equivalent to Harmony's Perspective view, where you set the scene.
Inspector (right): When you select an element, its properties are displayed.
Hierarchy: This is set up on the lower-left to make it easier to set up the hierarchy of elements in your scene, and set up parent-child relationships for different game objects

Main camera: This is what will show your scene, and you can find this listed in the hierarchy. To show a Harmony object, you must add a special component. With the main camera selected, in the Inspector, select Add Component > Scripts > Harmony Camera.

Game Objects

Basically everything that you create in Unity will be a Game Object. There are two main types of game objects you can use to import Harmony data:

Create Empty: This creates a regular game object in which you can load the exported Harmony data. All the individual body parts on the sprite sheet come in as separate elements, but are treated as one whole object with a dynamically created bounding box. If you were to put a transparency on this object, you would see the overlapping transparencies of all the individual objects. But this in general creates a higher-quality render and should be the default if you’re not animating the transparency of an object. With this option, direct rendering will read the depth information in the scene but not write it. Note that with this option, the rendering cannot be customized.
Create Other > Plane: Renders the entire character to a plane. This renders your character to texture data. With this option, if you animate the transparency of the plane, then it animates the transparency of the rendered output, so you don’t see the transparencies of the overlapping elements. However you will have one static bounding box the size of the plane that you render to. Use this option when you want to animate the transparency of a character in a scene. Also you can write your own custom shaders. Simply set the Render Target to eRenderTarget. You can see an example of this in the sample project DemoRenderTarget.

There is a quick way to import Harmony data:

Create Other > Harmony Object: Lets you browse for the exported Harmony project folder. If you’ve already saved this to your StreamingAssets folder, you can browse to it through there. Then it adds the Harmony scene to your Unity file, and sets up the rendering, audio, and animation scripts you need to get going.

To understand fully how it works, let’s set it up by hand. Everything you do will be based on the Game Object you create to load your Harmony data. So let’s go ahead and create a Game Object.

Using an Empty Game Object

GameObject > Create Empty

You should rename this Game Object to be what you’re working with, so it's more clear in the Hierarchy tab. In our example, we're using the SpaceCat demo file, so we’ll rename the GameObject to SpaceCat. You can do this by clicking twice on the name and renaming it in the Hierarchy tab, or you can select the Game Object and rename it in the Inspector.

At this point, it’s an empty object. Accessing Harmony data is done through scripts. First, select the Game Object. In the Inspector, go to Add Component > Scripts > Harmony Renderer.

When you do this, a new section appears in the Inspector called Harmony Renderer (Script).

This will let you load an animation file. What you want to do is put the path of the asset relative to the HarmonyResources folder. Before this point, you will already have exported from Harmony directly to this folder, or manually copied and pasted the data in here.

You exported a scene called SpaceCat. In the Project Folder, place HarmonyResources/SpaceCat under the Transform information at the top, under Scale. You should set these values to 0.01 for X, Y, and Z because the default Harmony project is for an HD screen.

You won’t see anything until you define a few parameters. First, set the Clip Name Size to 1. A second field will appear, Element 0. Enter the clip name for the animation you want to load.

If you double-check the right Clip Name to put in Element 0, you can check the output that you exported from Harmony. Double-check the stage.xml file, which was exported to the folder you specified when you did the Harmony Export. Our default export path is to StreamingAssets, so that it will load up in the game engine automatically.

Take a look in the Project tab, under Assets > StreamingAssets > HarmonyResources > [ExportName]. You’ll find the data that’s been exported. In this case, we’re looking for SpaceCat. Select the file marked stage to load the data to double-check.

The text data appears in the Inspector.

The name to use for loading the object is the stage name. In this case, SpaceDuck_SpaceCatIdle.

If your Game Object has animation in it, and you want it to load the animation data from the Harmony export, you need to add one more components. With the Game Object selected, in the Inspector select Add Component and select Scripts > Harmony Animation.

If you’d like your animation to loop, then you need to set a game object to define this. Go to GameObject > Create Empty. Then rename this to LoopAll. Click on this game object to show the properties in the Inspector. Click on Add Component > Scripts > Loop All.

Now, when play the animation, you’ll see it on the screen looping as it plays back. The Loop All command simply iterates on all game objects on runtime and asks them to loop, which is useful for when you’re testing your animation. When you are programming the actual game, you should write additional scripts to control the different elements separately.

Using a Plane Game Object

To perform the same process using a plane, do the following:

1. Select GameObject > Create Other > Plane.
2. Select Add Component > Scripts > Harmony Renderer.
3. Set Size to 1 and Element 0 to the clip name as per previous instructions.
4. Set Render Target to eRender Texture.
5. Render Texture Viewport:
X: To reposition the animation correctly; should be -½ the width of your Harmony project.
Y: To reposition the animation correctly; should be -½ the height of your Harmony project.
W: Width of your Harmonyproject
H: Height of your Harmony project.
6. You will also want to use the custom Shader created by Toon Boom to have a transparent background with premultiplied alpha channel. This is what produces nice, antialiased drawings in your output.
7. With the Plane selected in the Inspector, go to Mesh Renderer > Materials. Under Element 0, select UnlitTransparentPremultiplied.
8. If you’re starting with the Toon Boom demo project, this renderer should already be loaded in your list.

You can also write your own custom shaders and use them here.

9. You will need to also add the animation component. Select the Plane. In the Inspector, click Add Component > Scripts > Harmony Animation.