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 the 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.
Importing Harmony Files Directly into Unity
How to import Harmony files directly into Unity
- Create a Unity 2D project.
-
The SDK Harmony project needs to be imported to your project in order for the assets to be brought in. Do one of the following:
‣ Go to the Unity Asset Store (assetstore.unity3d.com/en/#!/content/31211) and save the Harmony Game SDK file on your computer. Then import it in your project from the following: Top Menu > Asset > Import Package > Custom Package. ‣ Search for the Harmony Game SDK in the Unity Asset Store, then download and import the package. You can access the Asset Store from the following: Top Menu > Window > Asset Store. NOTE: For each new Unity project, you must repeat step 2 as it contains the necessary files and folders to make the Harmony import process work. - Add the exported game object to the scene by going to Top Menu > GameObject > 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 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. |
Importing your Hamony files from an empty GameObject
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.
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.
- 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:
‣ | Select the GameObject. |
‣ | In the Inspector, select Add Component and select Scripts > Harmony Animation. |
- 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.
- Select GameObject > Create Other > Plane.
- Select Add Component > Scripts > Harmony Renderer.
- Set Size to 1 and Element to 0 on the clip name as per previous instructions.
- Set Render Target to eRender Texture.
- 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. |
- 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.
- 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.
Attaching Props to Anchors in Unity
Once your Harmony GameObject is imported, you should be able to see your character both in the Scene and the Hierarchy views. From here you can attach one or several props to an anchor.
- Open up your character in the Hierarchy view to have access to both the props and the anchors.
- Click on the prop you wish to attach, and drag it onto the appropriate anchor.
- Repeat these steps for each prop and anchor in your project.
- In the Inspector view, under Frame, you can select which frame you wish to show. If you only had one drawing in your prop, then you will not have multiple options.
- If part of your character is cut off by the plane of the character, now that the props are showing, you will need to regenerate the mesh. To do so, select your GameObject. After this is done, go to Inspector View > Render > Generate Mesh.