Working in Unity
The Harmony Gaming Animation Guide is a basic guide on how to import Harmony projects and configure them, design and animate characters, and includes some tips. It is not meant as a guide on how to program games.
The Unity Interface
Here are the main components of the Unity interface and their equivalents in Harmony:
| Unity
|
Harmony
|
Description
|
| Scene view |
Perspective view |
This is where you set the scene–selecting and positioning environments, the player, the camera, enemies, and all other GameObjects. |
| Game view |
Camera view |
The rendered view from the camera(s) in your game. It is representative of your final, published game. |
| Inspector |
Layer Properties |
Displays detailed information about the selected GameObject, including all attached Components and their properties. |
| Hierarchy |
Layers in Timeline view |
Displays the hierarchy of elements in the scene, and lets you set up parent-child relationships for different game objects. |
| Project Browser |
--- |
Lets you access and manage a project's assets. |
The Main camera displays the scene and is located 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.
GameObjects
GameObjects are the fundamental objects in Unity that represent characters, props and scenery. Basically everything you create in Unity will be a GameObject. There are two main types of GameObject you can use to import Harmony data:
|
•
|
Create Empty: This creates a regular GameObject 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 put a transparency on this object, you would see the overlapping transparencies of all the individual objects. This 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. If you animate the transparency of the plane, then the transparency of the rendered output is animated; you won'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:
|
•
|
Harmony > 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. |
|
•
|
Harmony > Harmony Texture Object: Lets you browse for the exported Harmony project folder similarly to Harmony Object, but creates a Unity plane to render your animation on it. |
To understand fully the process, here's are two examples using an empty GameObject and a plane GameObject with the SpaceCat demo file. Everything you do will be based on the GameObject you create to load your Harmony data.
How to use an empty GameObject
|
1.
|
Select GameObject > Create Empty.
|
- Rename the empty GameObject so it's clear in the Hierarchy. Since we're using the SpaceCat demo file, rename the GameObject to SpaceCat by doing one of the following:
|
‣
|
Double-click on the name and rename it in the Hierarchy. |
|
‣
|
Select the GameObject and rename it in the Inspector.
|
- At this point, it’s an empty object. Accessing Harmony data is done through scripts.
|
‣
|
Select the SpaceCat GameObject. |
|
‣
|
In the Inspector, go to Add Component > Scripts > Harmony Renderer. |
A new section appears in the Inspector called Harmony Renderer (Script).
This will let you load an animation file. You must put the path of the asset relative to the HarmonyResources folder. Before this, you must export from Harmony directly to this folder, or manually copy and paste the data here.
- You exported a scene called SpaceCat. In the Project Folder, place HarmonyResources/SpaceCat under the Transform information at the top, under Scale. Set the 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:
|
‣
|
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. |
- Double-check on the right Clip Name to put in Element 0; you can check the output you exported from Harmony.
- Double-check the
stage.xml file, which was exported to the folder you specified when exporting from Harmony. Our default export path is to StreamingAssets, so it will automatically load in the game engine.
- Look in the Project tab, under Assets > StreamingAssets > HarmonyResources > [ExportName].
You’ll find the data that was exported. In this case, we’re looking for SpaceCat. Select the file marked stage to load the data you want 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 GameObject has animation in it, and you want it to load the animation data from the Harmony export, add one more component by doing the following:
|
‣
|
In the Inspector, select Add Component and select Scripts > Harmony Animation.
|
|
2.
|
To loop the animation, you must set a GameObject to define it: |
|
‣
|
Select GameObject > Create Empty and rename it: LoopAll. |
|
‣
|
Click the LoopAll GameObject to display its properties in the Inspector. |
|
‣
|
Click Add Component > Scripts > Loop All.
|
When you play the animation, it will loop as it plays back.
The Loop All command simply iterates on all GameObjects on runtime and asks them to loop, which is useful when testing the animation. When programming the actual game, you should write additional scripts to control the different elements separately.
How to use a plane GameObject
|
1.
|
Select GameObject > Create Other > Plane.
|
|
2.
|
Select Add Component > Scripts > Harmony Renderer.
|
|
3.
|
Set Size to 1 and Element to 0 on the clip name as per previous instructions.
|
|
4.
|
Set Render Target to eRender Texture.
|
|
5.
|
Render Texture Viewport:
|
|
‣
|
X: To reposition the animation correctly; it should be -½ the width of your Harmony project. |
|
‣
|
Y: To reposition the animation correctly; it should be -½ the height of your Harmony project.
|
|
‣
|
W: Width of your Harmony project
|
|
‣
|
H: Height of your Harmony project.
|
|
6.
|
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.
|
- With the Plane selected in the Inspector, go to Mesh Renderer > Materials. Under Element 0, select UnlitTransparentPremultiplied.
|
7.
|
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.
- You must also add the animation component. Select the Plane. In the inspector, click Add Component > Scripts > Harmony Animation.
