Production > Animation > Gaming Guidelines > Troubleshooting

Chapter 38: Troubleshooting

Unity Questions

Q. My Harmony asset does not appear in the Unity Editor.

A. There are several possible reasons for this. Check the following:

Has the HarmonyRenderer plugin been copied to the Assets/Plugins directory? The plugin is named HarmonyRenderer.bundle on Mac OS X and HarmonyRenderer.dll on Windows.
Is the clip name valid ? Make sure the clip name exists in the stage.xml file.
Are the binary files up to date? If you updated the Toon Boom Game Engine SDK to a newer version, make sure to regenerate the binary files if you use them so they’re compatible with the SDK.

Q. My Harmony asset does not appear in iOS or Android when exported from Unity.

A. There are several possible reasons for this. Check the following:

Make sure the Harmony assets are copied in the StreamingAssets directory. Since the HarmonyRenderer plugin cannot use Unity’s asset database, the Harmony assets were packaged as plain files so they are accessible to the plugin.
Is the plugin for iOS the same version as the one used for the editor? The plugin for iOS is in the Assets/Plugins/iOS directory.
Is the clip name spelled correctly? Windows and Mac OS X aren’t usually case sensitive file systems, but iOS and Android are. This implies that an asset that is visible on the editor will not appear on the mobile platform because it cannot be found.
Make sure the size of your sprite sheets does not exceed the hardware limit of the device you're working on. Otherwise, the texture might not appear at all.
Is the path to the project folder an absolute path? If it is, it might not work on the mobile device as that path will not exist on the platform. Make sure to use relative paths to the StreamingAssets directory.

Q. My Harmony asset does not composite properly with other 2D sprites in Unity. The 2D sprites always appear behind the Harmony assets even if I change the order index in the GameObjects.

A. The 2D sprites from Unity and the Harmony assets cannot currently composite together. There are, however, several solutions for working around this problem:

Use 2D textures instead of 2D sprites. The 2D textures, when attached to a geometry in Unity, will composite like the other 3D elements in the scene and you can change the compositing order by incrementing or decrementing the Z value of the transform.

Use multiple cameras to render your scene in parts. Here’s how:

Harmony Camera

  1. Create a new camera.
  1. Make sure you set the Harmony GameObjects to a specific layer (top-right of the game object inspector).
  1. In the camera, set the culling mask to this layer (and the other layers you want rendered in the background).
  1. Add the HarmonyCamera component to this camera so the Harmony GameObjects render properly.

Sprite Camera

  1. Create a new camera.
  1. Make sure to set the 2D sprite objects to a specific layer.
  1. In the camera, set the culling mask to this layer (and the other layers you want rendered in front of the 2D sprites).
  1. Make sure to set the clear flags to Depth Only or Don't Clear.
  1. Set the depth to be higher than the Harmony camera.
  1. Afterwards, if you move the camera, make sure to move both cameras simultaneously if you want to keep Game Ojects in sync.

Q. How can you specify the frame rate of the animation? My animation does not play at the same frame rate in Harmony and in the Game Previewer in the Unity Editor.

A. The Game Previewer previews the animation at a default of 24 frames per second. In your game, using the HarmonyAnimation component, you can schedule animations at the speed you want.


HarmonyAnimation animation = GetComponent<HarmonyAnimation>();

if (animation != null)


animation.PlayAnimation( frameRate, clipName );


Q. I cannot see my character in the Scene view in Unity. Is there any way to preview the Harmony asset?

A. Since the rendering of Harmony assets is implemented in a plugin, it does not update any Renderer component in the GameObject, and so cannot be shown directly in the Scene view.

However, you should still be able to preview your assets in the Game view (even when not playing). To help find and position assets, we also added bounding box shapes rendered in the editor and the Game view.

Q. How is memory management handled in Unity for Harmony assets?

A. Most of the memory extensive algorithms are executed in the C++ plugin. The data structure is maintained alive as long as a GameObject refers to it. This means you can instantiate as many clones of a character without reloading the data. Upon destruction, the GameObject will issue a clean-up call to the plugin and delete its associated rendering object. The sprite sheet and animation data are kept alive as long as a single GameObject uses them and a cleanup call is issued once they are destroyed.

Q. The Harmony assets memory does not appear in the Unity profiler. Can we profile the assets memory?

A. The Unity profiler does not pick up Harmony assets in its traces. Since the Harmony GameObject refers to a C++ plugin for its asset management and rendering, its memory cannot be recorded in the profiler. Profilers such as the one provided with XCode or Visual Studio should allow you to track your application’s memory including the Harmony assets and should also provide a more accurate result.

General Questions

Q. How can you specify the resolution used for the drawings in the sprite sheet?

A. The drawing resolution is not fixed in Harmony. Since you're exporting the scene to multiple sprite sheets in multiple resolutions, every drawing will have a different resolution in the end. You can use the Drawing view to see the resolution of a drawing compared to the rest of the scene. By enabling the light table in the Drawing view, you will see all of the scene’s drawings untransformed in the same proportion as they will appear in the sprite sheet. More specifically, the resolution used in the sprite sheet for a drawing is the size it appears untransformed in the Camera view, scaled to the sprite sheet resolution ("Sprite Resolutions" in the Export Sprite Sheet dialog box).

Once you know that, you can easily adjust the size of a single drawing. Use the Select tool to scale down a drawing and use the Transform tool to scale it back up so it does not change visually in the Camera view. This should allow you to alter the size of drawings in the sprite sheet.

Q. The assets take time to load on mobile devices. Is there any way to speed up the process?

A. Harmony exports an interchange XML format that is intended to be compatible with multiple game engines. However, reading data from the XML files is slow and this is mostly intended to test the assets in your project. At some point, they should be converted to a binary compact data structure that can be read into memory a lot faster than the XML.

You can use the Xml2Bin tool provided with the game engine SDK to convert your XML files to binary. This tool is in the Utils/Xml2Bin folder and a precompiled version for Mac OS X is available in the Utils/macosx folder.

Q. There are problems with the character I exported in the game engine. Pieces are not exported or are not showing in the proper order. What can I do ?

A. To integrate with the game engine SDK, all animations in Harmony must follow certain guidelines. Here are some of the key points for building a character that is compatible with the rendering in the game engine SDK:

Build your rig in the Timeline view. The game engine SDK data structure is similar to what is displayed in the Timeline view and an advanced node system might not always export properly.
Because every top level node in your scene will render separately in the game engine SDK, they may not intersect. A top level node is also isolated in its separate sprite sheet to allow the artist better memory segmentation of the character. If you created a character with top level nodes and this was not the intended result, create a top level group or peg to group them all together.
Use micro-Z ordering if necessary. With no Z ordering, a child layer will appear behind its parent (as it does in Harmony). To change the ordering, add some Z offset to the child layer.
The export script does not handle plain bitmap images. Toon Boom vector drawings and Toon Boom bitmap drawings are supported though.
The export script does not handle symbols.