Toon Boom
Harmony22
Gaming Guide

TOON BOOM ANIMATION INC.

+1 514 278 8666

4200 St.Laurent Blvd, Suite 1020
Montreal, Quebec, Canada
H2W 2R2

contact@toonboom.com
toonboom.com

Gaming Guide

Legal Notices
Toon Boom Animation Inc.
4200 Saint-Laurent, Suite 1020
Montreal, Quebec, Canada
H2W 2R2
Tel: +1 514 278 8666
Fax: +1 514 278 2666
toonboom.com

Disclaimer
The content of this document is the property of Toon Boom Animation Inc. and is copyrighted. Any reproductionin whole or in part is strictly prohibited.
The content of this document is covered by a specific limited warranty and exclusions and limit of liability under
the applicable License Agreement as supplemented by the special terms and conditions for Adobe®Flash® File
Format (SWF). For details, refer to the License Agreement and to those special terms and conditions.
Some icons in this document were provided with Font Awesome Free 5.6.1 by Font Awesome. These icons areprovided under the CC BY 4.0 license. For more information on Font Awesome, visit https://fontawesome.com.
For information on the license of Font Awesome Free, see https://fontawesome.com/license/free.
Some icons in this document were provided with the Glyphicons Halflings font by Glyphicons. For more
information on Glyphicons, visit https://www.glyphicons.com/.

Trademarks
Toon Boom® is a registered trademark. Harmony™ and the Toon Boom logo are trademarks of Toon Boom
Animation Inc. All other trademarks of the property of their respective owners.
Toon Boom® is a registered trademark. The Toon Boom logo is a trademark of Toon Boom Animation Inc. Allother trademarks of the property of their respective owners.

Publication Date
02-22-2023
Copyright © 2023 Toon Boom Animation Inc., a Corus Entertainment Inc. company. All rights reserved.

2

Table of Contents

Table of Contents
Table of Contents

3

About Gaming

4

Harmony Gaming SDK 2022 Release Notes

5

Chapter 1: Exporting Harmony Data for Gaming

10

Chapter 2: About Game Asset Creation

13

Game Rigging Guidelines

14

Game Deformation Guidelines

16

About Game Bone Deformations

17

Game Cutter Guidelines

18

Creating Metadata Notes

19

Game Animation Tips

21

About the Orthographic Camera

23

Chapter 3: About Exporting to Unity

24

Setting Anchors

25

Exporting Sprite Sheets

26

Sprite Resolutions

28

Using Bake_Groups

30

Exporting to Easel JS

32

Palette Variations

34

Chapter 4: About the Harmony Unity SDK

36Harmony Previewer

40

Asset Manipulation

42

About the Sample Unity Project48

About the Unity Interface

49

Importing Harmony Files into Unity

51

TBG File Workflow in Unity

52

XML Folder Workflow in Unity

59

Adding a Harmony Renderer to Empty Game Objects

63

Setting Up Collisions in Unity

65

3

Gaming Guide

About Gaming
Harmony allows you to export animations created in Harmony to external game engines. This allows you todesign characters with simple movements that may be used in a game engine.
An example of a game engine that you may incorporate Harmony data with is Unity. Toon Boom has a Harmony
SDK that you may download from the Unity asset store to have control over your character once imported to
Unity.
This guide will demonstrate how to export animations from Harmony. In addition, the Harmony Game SDK for
Harmony integration with Unity will also be detailed.

4Harmony Gaming SDK 2022 Release Notes

Harmony Gaming SDK 2022 Release Notes
Exporting From Harmony
FeatureDescription

To facilitate better support within Game Editors, the Export
to Sprite Sheet interface has been given some additionalfeatures to pack more information into the exported file.

New Exporter Options

New Options
l

l

l

5

Palette selection tab - Exclude certain palettes thatyou don’t want included in your exported file, this will
cover all possible variations of palettes that will resultin different colors showing on the character
Encode to TBG - zips the XML files to the TBG
custom file format so that they may be imported to
Unity with Unity custom importers. When the files areimported, they will be treated like any asset in Unity
and will contain sub-assets for textures, sprites, andanimations. This improves the ergonomics ofcreating and moving character data and checking
changes into source control.
Improved performance on “Save and Export” Exporting process generally takes 1/3 of the timecompared to Harmony 21, for both XML folders and.tbg files

Gaming Guide

FeatureDescription

There are many nodes that are not possible to render in theGame SDK currently. As a means of bringing in the value of
those nodes to your export, there is a new feature to group
drawings and the nodes that affect them into a new groupwith the “bake_” prefix (eg. bake_hips).

“bake_” Groups

Any group named with the “bake_” prefix will be analysed for
unique frames of animation for effects, movements, anddrawing substitutions. When exported to a spritesheet, eachunique frame from this group will export as a sprite. If many
frames of the timeline have nothing changed within thatgroup, it will all be considered the same exported sprite in
the spritesheet

Importing TBG files in Unity
FeatureDescription

Unity will automatically detect changes to TBG files and reimport them using a custom importer. The file can then be
dragged into the scene as a prefab, much like you’d expectfrom an FBX file.
Automatic Importing Process

Textures, sprites, animations and TbgStore assets will be
generated and provided as sub-assets underneath the main
TBG prefab asset. These assets will not have to be
managed separately in source control, and only exist in
Unity’s library cache. An AnimatorController and SpriteSheet
asset are generated beside the character, since these areunable to operate as sub-assets.

The Importing process can be modified from the settings in
the inspector view.
Animation SettingslImporter Settingsll6Discretization Step - The number of columns / rowsthat sprites will get split into if they are being
deformed by bones.
Framerate - The number of frames per second thatthe animation runs at.
Stepped - Disable interpolation between authoredframes.

Harmony Gaming SDK 2022 Release Notes

FeatureDescription

l

l

l

Create Animator Controller - Disable interpolation
between authored frames.
AnimatorController - Provides a workspace totransition animations to one another given certain
conditions. Can be referenced in gameplay scripts totrigger animations during gameplay.
Maintain Curves On Cloned Clips - Curves
duplicated from clip sub-assets inside .tbg file (andreferenced in the AnimatorController) will have theircurves overridden with new data from the updated.tbg file.

Material Settings
l

l

l

l

l

l

Shader - Used to render all sprites in the prefab
SRGBTexture - Map gamma color space fromtextures into Linear color space rendering
FilterMode - How neighboring pixels of the texture
interpolate
MipmapEnabled - Generate lower resolution textures
to render at further distances
CreateSpriteAtlas - If no SpriteAtlas is referenced
below, a new SpriteAtlas asset will be created in the
project beside the .tbg file
SpriteAtlas - All sprites from the .tbg file can be
added to a SpriteAtlas, when done will be able tocombine multiple novel SpriteRenderers into a single
drawcall, improving rendering performance

Rendering TBG files in Unity
FeatureDescription

The structure of the generated prefab in Unity should matchthe hierarchical structure set up in the Timeline in Harmony.
Harmony’s Node view structure of composites feeding into
the output node are excluded during export.

Prefab Hierarchy

New GameObjects can be attached to any of these child peg
transforms. This allows procedural equipment attachment.
Also, any GameObject can be enabled or disabled atruntime, so optional visual additions on characters can be
hidden until they’re needed. The hierarchy could also be
entirely decomposed, restructured, or duplicated at runtime.
This allows the option to explode characters or shoot certain
drawings as projectiles.

7

Gaming Guide

FeatureDescription

TBG Renderer Settings

The resolution, palette, material, color, and skins can beedited from the Inspector as well as the GameObject's
custom scripts. The material and color for SpriteRenderers
can also be set individually per drawing, so you can change
the colors of a character’s accessories or provide special
effects to some drawings through custom shaders.

2D Animation Package Integration

Drawings deformed by GameBones in Harmony will betranslated into SpriteSkin bones in Unity using Unity’s “2D
Animation Package”. This package provides support for
multi-threaded high-performance mesh deformation for
SpriteRenderers as well as UI handles for moving bones in
the Scene view. The bone chain can be procedurally
animated using Unity’s “IK Manager 2D” for blending inaiming, leaning, jiggling, waving effects, etc. after the
animation Update step.

Animations

All animation data is exported from Harmony per peg, so allintermediate rotations and scales are represented in the
Animation window in Unity. Animations can be modified
once their associated AnimationClip asset is duplicated froma TBG sub-asset to a novel asset in the project, allowing
events to be added and additional curves to be provided
within Unity.
AnimationClips are selected through an AnimatorController,
providing a means of transitioning between animations,either immediately or with smooth blending of peg
transforms.

Shader Graph Integration

Compatible shadergraph shaders are provided as part of the
SDK that can be duplicated and modified, allowing for aneasy interface to introduce custom game-specific visual
effects on your characters.

HarmonyRenderer Improvements (XML Folders)FeatureDescription

HarmonyProject Preview

Upon selecting a character in the Unity assets folder, apreview of the character will appear in the preview window.
The preview window plays a preview of the character’s
animations, and you will have the option to change skins
without needing to drag the character into the scene view.

Fixes
The following issues have been fixed in this release of the Harmony Game SDK:

8

Harmony Gaming SDK 2022 Release Notes

HarmonyRendererlAnchors previously would leak memory while updating Anchor transforms. An update to theHarmonyRenderer C++ plugin resolves this issue.

lHarmonyRenderers have improved rendering performance. Will now receive new meshes from theHarmonyRenderer C++ plugin that can be passed directly to Unity’s C++ backend using newer Unity
mesh generation features. This greatly reduces time taken to update animations on HarmonyRenderercharacters, allowing for more characters on-screen at once.

9

Gaming Guide

Chapter 1: Exporting Harmony Data for Gaming
There are two main pipelines for exporting data from Harmony to your game engine:l

Raw Game Data Export on page 11lFrame-by-Frame Export on page 12

Creating Animation in Harmony
When creating character rigs and animation for games, there are a few things to think about before starting.
Artists and programmers should work together to make sure their needs are met.
lWhat platforms will your game be created for? Windows, Mac, Mobile, iOS, PS, XBOX, etc.

lWhat game engine will you be using?

lWhat animation style will be used to create the look of the game? Hand drawn, cut-out, with textures, etc.

These are just a few of the questions to consider before getting started. They all have an impact on how you
design, build, and animate characters.
For example, if you’re planning a mobile game for smartphones, then you will most likely want to keep yourgame under 50 MB, so it can be downloaded without having to be on Wi-Fi. In that case, your most importantconsideration is to create efficient characters with very tight sprite sheets and reuse a lot of the animation tokeep the file sizes small. During the process, you will need to:l

Rig and animate characters in Harmony.

lExtract the Harmony data.

l

Import the Harmony data into the game engine.

Keep in mind, if you’re working with a custom engine, you can also process the Harmony data that’s exported
and use it in a custom game engine. If you need assistance with adapting data for your engine, contact
store.toonboom.com/contact/support.
If you’re making a game for consoles like the PS or Xbox, then you have the freedom to create larger textures.
You may want to animate frame-by-frame, with a cut-out character, or both.
If you're simply going to export on a frame-by-frame sequence, then you can use all the tools in Harmony without
limitations. You can then process an exported image sequence into a sprite sheet.

10Chapter 1: Exporting Harmony Data for Gaming

Raw Game Data Export

Raw game data export is appropriate when you want the file sizes to be as small as possible. Toon Boom lets
you convert data directly from your Harmony scene to incorporate into a game engine. You can extract theskeleton information, drawing information, and keyframe animation data, as well as deformations (bones andarticulations only), cutter, transparency nodes, and timing columns.
lAdvantage: This is the lightest export, and will keep file sizes small which is ideal for mobile applications.

lDisadvantage: You are somewhat limited in the tools you can use in Harmony. You can use tools like
Morphing as well as Curve and Envelope deformers, but you’ll need to bake it out to drawings so they'reinterpreted properly in the game engine. You can use Cutter effects (masking), but you cannot cascadethem, meaning you cannot have more than one in a hierarchy chain. The Game Bone deformers can beused on your rig without having to bake it to drawings.

However, even with these limitations, you can create really great cut-out character animation in Harmony andextract all the compatible data. By moving, rotating, scaling, and skewing the different drawing layers, you cancreate advanced looking animation.
When you extract the data, you'll have sprite sheets that contain only the drawings of the body parts used in yourHarmony scene file. You can also support multiple animations, such as idle, run, and jump while reusing thesame skeleton and drawings.
Toon Boom has fully integrated this solution with the Unity game development rendering engine. If you arecreating your game in Unity, you have a seamless pipeline without the need to re-treat the data in your gameengine.

11

Gaming Guide

Frame-by-Frame Export

You can export from Harmony using an image sequence, which can be recompiled into a sprite sheet.
Advantage: You can use any of the tools in Harmony when you animate!
Disadvantage: These sprite sheets can become quite heavy and end up as large textures to process in thegame. This may be fine for many games, like console games, but when you’re doing game development formobile devices, such as iOS or Android, you need to be very light on your texture space. Also, file sizes should
be kept under 50 MB to facilitate downloading without needing to be connected to Wi-Fi.
There is a script available in Harmony that allows you to export your frame-by-frame animation to the EaselJS
game engine. EaselJS is a javascript web compatible game engine. It uses a json data structure to map eachframe to an entry in the sprite sheet. The data structure is easy to understand and can be adapted or converted
to a different game engine if you need to.
To export to EaselJS, you need to add the script in the Scripting toolbar (TB_ExportToEaselJS). This script isincluded in Harmony. See the Scripting guide for more information on how to add the script to your Scripting
toolbar and the interface parameters.

12

Chapter 2: About Game Asset Creation

Chapter 2: About Game Asset Creation
In this section, you'll find guidelines for rigging, deformation, cutter and many useful animation tips.

13

Gaming Guide

Game Rigging Guidelines
The following is a list of general guidelines to keep in mind when rigging your character. As you're planning thecharacter rig for your game, keep in mind the style of the character, and create your custom colour palette.
However, there are some limitations to consider if you plan to extract the game data:l

Set your Harmony scene to be a square resolution (e.g. 1024 x 1024). You can do this in the Scene
Setting dialog box. See the Reference guidelNudge layers in Z space if you need to reorder layers. However, significant Z offsets are not supported
within a character rig.

lMake every layer in your game engine a separate scene in Harmony. If you have two characters at
different depths, put them in separate scene files.

lDon’t use 3D space. If you want to set things up in 3D space, you can do this when you get to your gameengine.

l

Set your pivot points on Peg layers using the Rotate tool to set the pivot on the entire layer. Peg pivots arerecommended over drawing pivots. You should also set the pivot points on your drawing layers, even if
you don’t animate on them, as this will allow you to retrieve the information later on in the game engine if
you need to put an anchor on a drawing layer.

lDon’t use Morphing. This is not yet supported in game engines.

l

Be mindful of where you put your character before exporting. The master pivot of your exported gameobject will be the center of your Harmony scene (0,0).

l

Be sure to have a Display at the end of your hierarchy.
lWhen rigging, keep in mind that some nodes are not supported by the exporter. As a result, thenode structure would not be interpreted well by game engines. It is therefore recommended thatyou avoid using complex node structures. To do so:lBuild your character out of Drawings attached to Pegs. Pegs can then be connected to otherPegs to form Hierarchies.

l

You should have all Pegs connected to a single Master Peg at the top of your Node viewlDrawings should generally connect to Composites to determine the order of Drawings
shown on-screenl

If Drawings need to change order during animation, you can bump the z-depth to change
which Drawing shows firstl

If you can't get your animations working well with just Drawings and Pegs, there are someother nodes you can use that are possible to export:lCutters - Generally only cut one Drawing against one other Drawing (eg. cutting aface to the bounds of a head). You cannot 'daisy chain' one Cutter's output intoanother Cutter's input.

lGame Bone Deformations - Generally only deform one Drawing. The bone skeleton
can branch. Kinematic Outputs can be used attach Drawings to the ends of bones(eg. foot on the end of a leg)

14

Chapter 2: About Game Asset Creation

NOTE
you are still able to use more complicated node strucures within 'bake_groups'.
See Using Bake_Groups.
Keeping these tips in mind will allow you to create a tight, efficient 2D game character in Harmony while taking
advantage of all the great tools.
Here are some things you should do:lCreate a simple parent-child relationship hierarchy in the Timeline view.

l

Use peg layers to contain keyframe animation data, set to Separate Position.

l

Use drawing layers to draw on, creating new drawings when needed.

l

Use the Rotate tool to set the pivot points on the peg layers.

lName your layers properly so if you need to fetch a specific layer’s pivot point later on in the game engine,
you can easily recognize the layer you need. If you have a top-level Group A, which has a child groupinside it (Group B), and the drawing layer is a child of Group B, then the drawing layer is exported as A_
B_DrawingLayer.

l

Set your anchors where you want to have your pegs show in Unity as transforms.

You can use any of the drawing tools you want: Pencil and Brush tools, textured lines, solid areas, and gradients.
Each individual drawing will be rendered out and assembled into a sprite sheet later.
NOTE
Because the Unity game engine does not support Unicode characters, it is recommended to avoid
using it in scenes intended for games.

15

Gaming Guide

Game Deformation Guidelines
Harmony can export deformations to the game engine XML format. Only hierarchies made of Game Bones canbe successfully exported. In addition, Kinematic Outputs were implemented to complement your game bones.
Deformations in Harmony come with a wide set of features. However, some of these features are not compatible
with the game engine SDK and must not be used for gaming. Hence, Game Bone deformers do not support thefollowing standard Bone deformer features:lZones of influencelCurve and Envelope deformationsl

Having more than a single pose in the deformation hierarchylAnimating drawing pegs underneath deformation groups

The deformation in the game engine SDK does not behave exactly as the Bone deformation in Harmony.
To comply with most game engines and maintain fast calculations, the SDK implements a linear base skinningalgorithm to blend the bones at articulations. You may notice some differences depending on the curvature of
the articulations used. That said, compared to regular Bone deformations, GameBones most closely resemble inHarmony what you will see once imported to Unity.
NOTE* Not currently available in the Cocos2d-x implementation of the game engine SDK.

16

Chapter 2: About Game Asset Creation

About Game Bone Deformations
T-RIG-007-003
The Game Bone deformation is very similar to the Bone deformation. It allows you to create a bone-like structurein which each part is solid, but with articulations that are flexible. This is mostly useful for animating a character's
limbs, such as the arms or legs, or other parts that can be articulated such as torsos or fingers. For example, aGame Bone deformation can be used to articulate an arm that is made of a single drawing, so that the upper arm
and forearm can be moved independently, without having to draw the upper arm and the forearm on different
layers. Harmony will deform the drawing to make it look articulated. The different parts of a Game Bonedeformation can be rotated around their joint, extended and shortened, giving you the same capabilities asanimating articulations on different layers, without having to worry about parts detaching, pivot points, or clipping
outlines.
The Game Bone deformation is different from the Bone deformation in which it is optimized for game engines
such as Unity. Hence, it is usually only used for game development and not in animated productions. The
differences between the Bone and Game Bone deformations are that Game Bone deformations do not have
Bias and Region of Influence properties. The articulation folds also look slightly more rounded.

17

Gaming Guide

Game Cutter Guidelines
The cutter, or mask, operation in Harmony is used for cutting off drawings with custom shapes. The game engine
SDK implements both cutters and inverted cutters with the following limitations:l

For a sprite, only a single cutter drawing can be applied when it is rendered. This also applies to acomposite of multiple matte drawings. The game engine SDK will only use the first matte drawing during
rendering and discard the others.

l

A deformed drawing cannot be cut, but a cut drawing can be deformed.
NOTE
Not currently available in the Cocos2d-x implementation of the game engine SDK.

18

Chapter 2: About Game Asset Creation

Creating Metadata Notes
As you create assets for your game in Harmony, you may want to make notes about the scene or specific partsof the character or props for the programmer. These embedded notes that will be exported with your assets toUnity are known as metadata.

How to access the Metadata Editor viewlIn the top-right corner of a view, click the Add Viewl

In the top menu, select Windows > Metadata Editor.

button and select Metadata Editor.

How to create scene metadata
1. In the Metadata Editor view, in the Scene Metadata section, click on the plus
new metadata entry.

button to create a

The Add Metadata dialog box appears.
2. In the Add Metadata dialog box, enter the name of your new scene entry.

NOTE
For any anchor or prop information created within the Metadata Editor, the naming
convention must always use the prefix "game.". The term "game." is recognizedautomatically by Unity as a metadata information. For example: game.Armor001.
3. Click Add and Close if you only intend to add a single entry. Click Add if you intend to add multiple
entries. Continue adding multiple entries, clicking Add after each one. Click Close when you arethrough.
4. In the Metadata Editor view, double-click on the value field for the first entry to make it editable.
5. Enter the value information for this entry.
6. Continue adding value information for all your entries.
This information will be exported with your Harmony assets. Once in Unity, scene Metadata willappear in Inspector view > Metadata when the asset is selected in the Hierarchy view.

19

Gaming Guide

How to create node metadata
1. In the Timeline view, click on the layer to which you would like to attach metadata.
The name of the layer appears near the top of the Node Metadata section.

2. In the Node Metadata section, click on the plus

button to create a new metadata entry.

The Add Metadata dialog box appears.
3. In the Add Metadata dialog box, enter the name of your new node entry.

NOTE
For any anchor or prop information created within the Metadata Editor, the naming
convention must always use the prefix "game.". The term "game." is recognizedautomatically by Unity as a metadata information. For example: game.Armor001.
4. Click Add and Close if you only intend to add a single entry. Click Add if you intend to add multiple
entries. Continue adding multiple entries, clicking Add after each one. Click Close when you arethrough.
5. In the Metadata Editor view, double-click on the value field for the first entry to make it editable.
6. Enter the value information for this entry.
7. Continue adding value information for all your entries.
This information will be exported with your Harmony assets, more specifically, this information will belinked to the selected layer. Once in Unity, scene Metadata will appear in Inspector view > Metadata
when the asset is selected in the Hierarchy view.

20

Chapter 2: About Game Asset CreationGame Animation Tips
When animating for games, depending on the type of game you’re creating, you may need to limit youranimation. For example, if you’re creating mobile games and you want to keep the file sizes small and playback
fast on all devices, then limit yourself to simple keyframe animation with as few drawing swaps as possible. If
you’re creating console games, you have the freedom to create more drawings and have a higher complexity.
You can explore with your developers the limitations of the platforms you’re exporting to, and what your gameengine supports.
Here are some tips for efficient, lightweight animation:l

Use mainly transformations, such as move, rotate, scale, and skew.

lCreate additional drawing swaps when needed.

l

If you use Curve and Envelope deformers or Morphing, you’ll need to bake out the drawings for export. Be
careful when doing this, as you may want to keep the number of drawings small. Don’t bake out an entire
sequence, just selected drawings. You don't need to bake the Game Bone deformers.

l

The bigger the drawings are in the Drawing view, the more pixels they will occupy in the texture size on
the sprite sheet. When setting up your rig, make sure to not scale individual layers by using a keyframewith the Transform tool. If you want to scale things up or down, use the Select tool. This will keep things
the same relative size on the sprite sheet. When you export the sprite sheets, in the script you can also
set the resolution of the sprite sheet so the drawings can be scaled down for smaller devices.

l

Only drawings which are exposed in the scene will be exported to the sprite sheet. For example, if you
have 10 drawings in your Library view, but only two of them are showing in your scene, only those two will
be exported. This keeps the sprite sheet as tight as possible.

Animating Multiple Sequences
You will most likely have multiple animations for your characters. For example, an idle sequence, a run
sequence, an action sequence, and so on. You need to work in a specific structure so you can export all of theseanimations to a single sprite sheet.
There are two different workflows that you can use:l

Workflow 1: Separate SceneslWorkflow 2: Separating Using Scene Markers

Workflow 1: Separate Scenes
First, create a scene file with the name of the character, such as Space Duck. This is the file where you cancreate or import your game rig. In the top menu, select File > Save As New Version, and give this new version
the name of the animation. For example, Idle.
Every time you need to do a new animation using the same character, perform a Save As New Version. In theend, you may have something like this:Scene: Space Duck
Versions:
l

Idle

l

Run

21

Gaming Guide

l

Jump

l

Shoot

When you run the export script, it will export the drawings from the current scene into the export folder. It will also
let you know if there are any other scene versions that were already exported to that folder.

Workflow 2: Separating Using Scene Markers
You can also create all of your character animations in a single scene, one after the other, such as idle, run, jumpand shoot. Then use scene markers to mark and separate the individual animations.
When you are marking individual animation frame ranges, be sure that they start and end with a keyframe. Do
not create scene markers for a range of frames that starts or ends in the middle of an interpolated movement.

When exporting your sprite sheet, in the Export To Sprite Sheet dialog box, be sure to check the Use Scene
Markers to Export Clips option. This is enabled by default.

The animated clips are divided and listed in the stage.xml in the same way that they would appear if you had
exported each animated sequence from separate scenes to the same file location.

22

Chapter 2: About Game Asset Creation

About the Orthographic Camera
In Harmony, there are two types of cameras available:lPerspectivelOrthographic

The orthographic camera is specific to the gaming pipeline. It changes the camera type from perspective toorthographic. It becomes a camera without vanishing points. This means there is no more perspective in the
Camera view. Objects, when moved on the Z-axis, will not change in size or scale.

The orthographic camera can be set in the Scene Settings dialog box. In order to create scenes with theorthographic camera, by default, you need to create a new custom scene resolution.

23

Gaming Guide

Chapter 3: About Exporting to Unity
If you have a custom game engine, you can take the exported Harmony data and proceed with your usual
process. Or you can modify the export script to fit your convention.

Before exporting a scene:l

Be sure to set your Display as Display and not Display All.

l

Be certain to save your scene. Harmony makes the export based on the tvg files, any unsaved updates
you have added will not be exported.

l

Set your Harmony scene to be a square resolution (ex. 1024 x 1024). Select Scene > Scene Settings.

24Chapter 3: About Exporting to Unity

Setting Anchors
Before exporting to Unity, you should consider what to set as your anchors.
An anchor is a point on the character that you would like to reference in the game engine during the character's
animation.

How to set an anchor
1. Create a new Drawing layer and rename it according to the anchor you are creating.
2. Inside the Layer Properties of your drawing layer, make sure that pivot option is set to Don’t Use
Embedded Pivot or Apply Embedded Pivot on Drawing Layer. The Apply Embedded Pivot on
Parent Peg does not transition well to Unity and you will lose your pivot information.

3. Once this is done, you can use any of the animation tools to reposition the pivot point of your layer,such as the Rotate tool in the Advanced Animation toolbar. You should be able to see the pivot
coordinates from the Layer Properties of your Drawing layer. If the pivot is not repositioned, its default
place will be at the center of your Harmony scene (0,0).
4. Once this is set up, select the Drawing layer and click the Toggle Anchor
button in the Game
toolbar. You can also make a multi-selection to set an anchor on multiple Drawing layers
simultaneously.
The Drawing layer is highlighted in red in the Timeline and Node views. Your anchor can now be
used to attach a prop.

25

Gaming Guide

Exporting Sprite Sheets
The Export to Sprite Sheets window exports to multiple resolutions, generating multiple .xml files and one or
multiple sprites sheets depending how many sprite resolutions you defined.
This saves different animations of the same character into the same name. For example, if there's an idle, run,and jump animation, these should all share the same Asset Name. You can think of it as the overall collection ofanimations. Inside are the different saved scene versions whose drawings you can reuse for all the animations inthat character set. Each scene version will be displayed as an item in the list.
When you export an animation, only the drawings used in that scene are exported. All the drawings are exported
individually first and then atlased together into a sprite sheet.
If you saved multiple animations to the same Asset Name (i.e. SpaceDuck: run, idle), then it will re-atlas the
sprite sheet to include all the drawings from all the animations in that folder, creating a new animation file, but
reusing the same skeleton.
NOTE
Programmers may be interested to note that the XML data exported by Harmony can be converted
afterwards to a more optimized binary data structure. To convert XML to Binary format, use the
Xml2Bin utility. This utility converts the XML data structure generated through the Toon Boom
Harmony software to a compressed binary data structure. This utility is available in the gaming SDK
under /HarmonyGameSDK/Plugins/.
lPlugins/Mac:-Precompiled binary for Mac OSX.

lPlugins/Windows\x86: Precompiled binary for Windows.

lSamples/HarmonyGameSDKSource/Utils/Xml2Bin: Xml2Bin sources.

l

Samples/HarmonyGameSDKSource/Utils/Xml2Bin/proj.mac.Xml2Bin.xcodeproj: XCode projectfor Mac OSX.

l

Samples/HarmonyGameSDKSource/Utils/Xml2Bin/proj.win32/Xml2Bin.sln: Visual Studio 2010
solution for Windows.

The C++ code that handles the data structure can be reused and parsed in your own code if you
want to integrate with other game engines.

How to export sprite sheets
1. Add the Game toolbar, by selectings Windows > Toolbars > Game.

2. Run the script by clicking the Export to Sprite Sheets
The Export to Sprite Sheets window opens.

26

button in the Game toolbar.

Chapter 3: About Exporting to Unity

3. Set the Save Path to the correct folder in your Unity project if you want it to update automatically. If
not, you can save anywhere, then transfer the animation into your Unity project, or any other gameengine you want to use.
4. Set your sprite sheet preferences.
5. Click Export.

27

Gaming Guide

Sprite Resolutions
You can set the number of pixels on a sprite depending on the targeted resolution for your game. Your target
resolution may be based on the hardware you are targeting such as a television or phone screen.

A new sprite sheet will be created for each target resolution specified in the Resolutions tab in the Export to
Sprite Sheet (XML) window. To access this window, you will need to enable the Games toolbar by selecting
Windows > Toolbars > Game.

Please note that the size of the sprite will be the size of the character when it was created in Harmony.

How to setup multiple sprite resolutions
1. Enable the Game toolbar by selecting Windows > Toolbars > Game.
2. Select Export to Sprite Sheets. The Export to Sprite Sheet (XML) window will open.

3. In the Export to Sprite Sheet (XML) dialog, select the Sprite Resolutions tab. This tab will list all of thecurrent target resolutions.
4. Click the Add

icon. This will create a new row for a new target resolution.

28

Chapter 3: About Exporting to Unity

5. Enter the Name, Width, and Height of your new target resolution.
The default target resolutions are HD, FullHD, and QuadHD. The listed screen resolutions represent atarget device the game could be played on.
You are free to manually add or remove resolutions from this list depending on your target resolution andhardware. Once imported into the game engine, it will be possible to select which resolution is being
displayed by changing the rendered sprite sheet.

NOTES
l

The sprite resolutions are affected by the scale of the drawing strokes.

lScaling drawings or their pegs will not affect the output sprite resolution.

l

If you want to increase the sprite resolution, you may scale a drawing's child layers.

29

Gaming Guide

Using Bake_Groups
A Bake_Group is a grouping of drawing and effect nodes that may be exported together as a single unified
drawing in a sprite sheet.

How to create a baked group
1. Group together the layers that you will bake together. It is recommended to group the layers together
from the node view.
NOTE
A bake_group should only have a single input and a single output. This generally meansa Composite node must be contained within the bake_group for the export to work
properly. Consider also what pegs are needed to guide the drawings, as all pegs must
ultimately source from a single peg outside the group.

2. In the timeline, add the “bake_” prefix to the beginning of the group name.
See the example below for how a group node with the "bake_" prefix should look. The "group"labeled "hips" should become "bake_hips" for the bake to apply.

30

Chapter 3: About Exporting to Unity

If the “bake_” prefix is included in the group name, the group will be analyzed for frames containing uniqueeffects, movements and drawing substitutions, and each unique frame will export as a sprite in the sprite
sheet.
New drawing animations for these generated sprites will be created and provided to the game engine. The
game engine will not have access to any of the structure inside this group, instead treating the entire groupas if it were a single Drawing with drawing substitutions.

31

Gaming Guide

Exporting to Easel JS
The Export to Easel JS window lets you flatten an image sequence of your animation. Even if you have a fully
rigged puppet or a single drawing layer with your animation sequence, the outcome will still be a flattened output
of each frame, grouped together in your sprite sheet. This allows for more flexibility and freedom of work as you
have access to any tools or effect modules you want to use. However, this can result in heavier files dependingon the length, complexity and export size of your animation.

How to export to Easel JS
1. Add the Game toolbar, by selectings Windows > Toolbars > Game.

2. Run the script by clicking the Export to Easel JS

button in the Game toolbar.

The Export to Easel JS window opens.

3. Set the Save Path to the correct folder in your Unity project if you want it to update automatically. If
not, you can save anywhere, then transfer the animation into your Unity project, or any other gameengine you want to use.
4. Set your sprite sheet preferences.

32

Chapter 3: About Exporting to Unity

5. Click Export.

33

Gaming Guide

Palette Variations
Creating versions of characters with palette differences is important when you plan to add charactercustomization as a feature of your game. In Harmony, you may create multiple palettes for a character so that it
can have a variety of different looks in your game.
In Harmony, once you create your character and its palettes, you may export the character to sprite sheets foreach palette.
For information on exporting sprite sheets.

How to create palette variations for a game character
1. In the Colour view, select a palette to clone.

2. Do one of the following: From the Colour menu, select Palettes > Clone or right-click and selectClone.
l

Right-click on the palette and select Clone.

lOpen the Colour menu

, then select select Palettes > Clone.

The Clone palette dialog box opens

3. In the New Palette Name field, enter the name for the new palette. By default, the palette's name isbased on the original palette name followed by "-clone". The palette list above this field lists thepalettes that already exist in the selected location. Make sure you enter a name that is not alreadyused by another palette.
4. Click OK.
The cloned palette appears in the palette list.

34

Chapter 3: About Exporting to Unity

All Scene Palettes will appear in the Palettes tab of the Export to Sprite Sheet window.

How to export a sprite sheet for each palette variation
1. Enable Game toolbar by doing one of the following:l

In the top menu, select Windows > Toolbars > Game.

l

Right-click on any existing toolbar and select Game.

2. In the Game toolbar, select Export to Sprite Sheets.

3. Open the Palette tab. You will see all of your project's palettes and their clones.

NOTE
Only Palettes and their clones will appear. Palette duplicates will not appear.
4. Select the names of the palettes you would like to export. Each palette that is checked will export withthe character as its own sprite sheet.
5. Export your Sprite Sheet.
Once the character is imported to Unity, it will be possible to select which palette is being displayed bychanging the rendered sprite sheet.

35

Gaming Guide

Chapter 4: About the Harmony Unity SDK
Toon Boom provides a Unity package in the Unity Assets store that contains all the scripts necessary to import
the data exported from Harmony. Once unpacked to a new Unity project, the following structure is available
inside the Toon Boom Harmony Gaming SDK folder:lDocumentation (Developer-focused information about the Unity integration)lPlugins (SDK libraries)lSamples (demo scenes, exporter scripts, SDK source, and a previewer)lRuntime (Harmony scripts that execute during gameplay)lEditor (Harmony scripts that only run in the Editor and don’t appear in builds)lShaders (Provides shaders that properly render Harmony-specific features)lMaterials (Prebuilt materials that utilize Harmony shaders)

These packages can be managed manually through the Package Manager interface in Unity. Developers can
upgrade and downgrade packages in the event that newer Unity versions have certain package incompatibilities
with the Harmony scripts.

How to create a Unity SDK project
1. Create an empty Unity game project. It is recommended that you create an empty 2D Unity gameproject as it is the most convenient when working on 2D rendering and physics.
NOTE
Ensure you are using Unity 2020.3.36 or later, previous versions of Unity don’t have all
the necessary features to support importing and rendering TBG files.

2. Install the Harmony Game SDK available in the Unity Asset Store. If your SDK was downloaded
manually, you can double-click the .unitypackage file while your Unity project is open.
The Additional Packages Requested pop-up will appear to ensure that you have compatible Unity
packages that facilitate optimized 2D animation at runtime.

36

Chapter 4: About the Harmony Unity SDK

3. Click Download.

Once Unity finishes downloading the required packages and compiling all the scripts, your project is readyto begin importing Harmony characters.

NOTES
When you have installed the Toon Boom Harmony Game SDK, the Harmony SDK package will haveto be imported to every new project created in Harmony.

How to import a package to a project
1. Open the Asset Store by selecting Window > Asset Store. The Asset Store tab will open.
2. In the Asset Store, select Open Package Manager. The Package Manager window will open.

37

Gaming Guide

3. From the Packages dropdown at the top-left of the Package Manager, there will be four options:lPackages: Unity RegistrylPackages: In Projectl

Packages: My AssetslPackages: Built-in

4. Select Packages: My Assets.
A list of your downloaded assets will display in the list below. To the right of the Package Managertab, information about the selected asset will display.
5. When you have selected the Harmony package, select Import at the bottom of the Package Manager.
The Import Unity Package window displaying the asset’s files will appear.

38

Chapter 4: About the Harmony Unity SDK

6. Select Import.

39

Gaming Guide

Harmony Previewer
This section explains how to use the Harmony Previewer to view animations without installing Unity.
You can find a build for Windows or macOS inside the Harmony Game Previewer folder that you can just unzip.
NOTE
Do not unzip the build inside your Unity project, it is advised to unzip it in its own folder.

How to use the Previewer

40

Chapter 4: About the Harmony Unity SDK

1. Run the Harmony Game Previewer.exe or Harmony Game Previewer.app
2. Select which project to load from the loader menu. These projects are loaded from the Harmony
Resources folder in the same directory as the Harmony Game Previewer.exe or Harmony Game
Previewer.app
3. Navigate through the animations using Prev / Next button.
4. Adjust the Frame Rate, Tint, Discretization Step and Skin settings with the controls at the top left.
5. Click Go back button to return to the previous menu and load a different animation.

41

Gaming Guide

Asset Manipulation
In this section, the components Harmony Mesh and Harmony Renderer in Unity will be described.

TBG Workflow
If you are importing sprites to Unity through the TBG workflow, asset manipulation options for TBG files will
display in the inspector view. The asset manipulation options displayed are different from the asset manipulation
options displayed in the XML workflow.

TBG Asset Renderer
Harmony Renderer for the TBG file workflow is used to control the animation and rendering of Harmony assets
for TBG files as well as expose important variables you may want to change during runtime.

How to manipulate TBG Workflow rendering assets
1. Select a character in the scene. The TBG Renderer (Script) section will appear in the Inspector tab tothe right.

2. Control your character's assets by setting the following:lProject: A reference to the TBGStore asset. This asset is generated by the importer and contains the
TBG project data not covered by the generated AnimationClips.

lResolution: The resolution used to display this character. This matches associated sprite sheets
names.

l

Palette: The palette used to display this character. This matches associated sprite sheet names.

lMaterial: The material used to shade this character. Hardware Skinning is the default unlit material
provided with the SDK.

l

Color: Option that multiply the selected color onto the asset.

lSkins: Allows you to change in real-time the skin you’ve exported from Harmony. Each group has its
own drop-down to change the skin, as well as a global dropdown to change the skin of all groups at

42

Chapter 4: About the Harmony Unity SDK

once.

TBG Importer
When TBG files are imported to Unity, the Harmony assets are converted to Unity prefabs, AnimationClips, andother assets. The TBG Importer allows you to specify how the assets and animations are created.

How to control the settings for import of Harmony TBG assets to Unity
1. Select a .tbg character file in your Project view. The inspector tab will open.
2. At the top of the Inspector view, click Select for the Model. The TBG Importer view will open anddisplay the TBG Importer options.

3. Control how animations will import by setting the following:lAnimation SettingslDiscretization Steps: A slider representing the number of columns / rows that sprites will get
split into if they are being deformed by bonesl

Frame Rate: The animation frame rate used by Unity's animation system to playback the
Harmony frames. This should match your frame rate in Harmony.

l

Stepped: If checked, the animations will pass between integer frames and thus not interpolatesmoothly. If unchecked, the animation will be played back between integer frames, for asmooth animation.

lCreate Animator Controller: If checked, this importer will automatically create a new
Animator Controller containing all the generated AnimationClips and place the asset besidethe prefab in the Project view.

43Gaming GuidellAnimator Controller: When changes are made to the .tbg file, the Animator Controller
referenced will be updated with the new AnimationClips.

Material Settingsl

Shader: When the prefab is created, all SpriteRenderers will reference a generated materialusing this shader.

l

SRGB Texture: If checked this will map gamma color space from generated textures into
Linear color space rendering.

lFilter Mode: How neighboring pixels of the texture interpolate.

lMipmap Enabled: Generate lower resolution textures to render at further distances.

lCreate Sprite Atlas: If checked, this importer will automatically create a new Sprite Atlas
containing all the generated Sprites and place the asset beside the prefab in the Project view.

lSprite Atlas: When changes are made to the .tbg file, the Sprite Atlas referenced will be
updated with the new Sprites.

XML Workflow
If you are importing sprites to Unity through the XML workflow, asset manipulation options for XML files will
display in the inspector view. The asset manipulation options displayed are different from the asset manipulation
options displayed in the TBG workflow.

Harmony Mesh
The Harmony Mesh component is used by the Harmony Renderer to create asset meshes based on the
exposed drawings in your animation.

XML Asset Renderer
Harmony Renderer for the XML workflow is used to control the animation and rendering of Harmony assets for
XML files as well as expose important variables you may want to change during runtime.

How to manipulate XML workflow rendering assets
1. Select a character in the scene
2. In the Inspector view, select Add Component at the bottom of the view. The HarmonyRenderer
section will appear.

44

Chapter 4: About the Harmony Unity SDK

3. Control your character's assets by setting the following:lProject: A reference to the Harmony Project Binary asset. This asset is generated by the importerand contains the Harmony project data in an efficient binary format.

lRender Settings: The render settings are used to modify your asset, either by changing theresolution or the Shader used to render or the quality of the deformation.

l

Resolution: The resolution used to display this character. This matches associated sprite sheets
names.

l

Palette: The palette used to display this character. This matches associated sprite sheets names.

lMaterial: The material used to shade this character. Hardware Skinning is the default unlit material
provided with the SDK.

l

Color: Option that multiply the selected color onto the asset.

lDiscretization Steps: Slider that defines the arrangement of all the deformed drawings.

45

Gaming Guidell

Clip Settings: The clips settings are used to see the animations without opening the Animation
window. This only affects the project when in Editor mode, when you play the game, the Animator
overrules the settings inside the Clip Settings.

lCurrent Clip Index: A numerical clip index to display. It can be animated in the Animation
window.

lCurrent Clip: A drop down for selecting which animation to display. It matches the Current
Clip Index.

lCurrent Frame: The frame number currently being displayed.

Animation Settings: These settings are same as importing Asset settings. It is useful while importingor re-importing asset modifications inside Harmony. Once modifications are done click Update
Animator or Update Current Clip in order to save your modifications.

l

Frame Rate: The animation frame rate used by Unity's animation system to playback the
Harmony frames. This should match your frame rate in Harmony.

l

Stepped: If checked, the animations will pass between integer frames and thus not interpolatesmoothly. If unchecked, the animation will be played back between integer frames, for asmooth animation.

lStrip Prefix: This is used to remove a prefix on the animation name. For instance, if we want
"Wishling_Idle" to become "Idle", we set the prefix to "Wishling_". This is useful where theanimation name for games is same for all the characters.

lUpdate Animator: Click this button to update the entire set of animations on this character tomatch what is in the Harmony project. This will update existing animations with the new
settings you entered and add any missing ones.

l

Update Current Clip: This will update only the currently selected clip.

46

Chapter 4: About the Harmony Unity SDKSkin Settings
The Skin Settings allow you to change in real-time the skin you’ve exported from Harmony. To change a skin you
first need to press the + button to add a group. You need to add as many groups as you had in your Harmony
export. If you had no groups, just add one and leave it on all. You can define which group you want to modify,
and then which skin to assign to which group. You can then remove a group by selecting any group and pressing
the - button.

How to change a skin in the XML workflow
1. Clickbutton to add a group/groups.

2. Modify the group, and assign the skin to group.
3. Remove a group by selecting any group and clicking

47

button.

Gaming Guide

About the Sample Unity ProjectToon Boom includes a sample Unity project that contains all the scripts necessary to import the data exported
from Harmony. Inside this project is an Assets folder which contains the following folders:lPluginsl

Scenes (demo scenes and a previewer)l

Scripts (all Harmony scripts)lStreamingAssets (this is where all the Harmony scene files should be exported to)

By configuring the Harmony script, you can automatically export animations into the StreamingAssets folder.
This way, Unity will dynamically load the most up-to-date assets as soon as they appear in the folder. You canalso manually place exported Harmony data into this location.

48

Chapter 4: About the Harmony Unity SDK

About 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 isrepresentative of the final, published game.

Inspector

Layer Properties

Displays detailed information about the selected
GameObject, including all attached Components and theirproperties.

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.

Animation

Cells in Timeline View

Shows keyframes of an animation per transform being
animated.

Displays a graph of states and transitions that lets you set up
how your characters will respond to game events and player
actions

Animator

Project Browser---

Lets you access and manage a project's assets.

49

Gaming Guide

Here are some data types that Unity interacts with, and their equivalents in Harmony:
Unity

Harmony

Description

SpriteDrawing

A single image that can be shown on a SpriteRenderer.

SpriteRenderer

Layer

Displays one sprite at a time. Sprites can be swapped
during an animation to construe motion of a character’s
body part.

Peg

Used to form the hierarchy of a character’s body. It can bescaled, rotated or translated to construe motion of acharacter’s body part. Skew has to be derived from ahierarchy of scales and rotations.

Transform

GameObject

Always paired with a Transform. GameObjects host
Components that can display and simulate gameplay. The
SDK provides custom Behaviors that run on GameObjects
to display Harmony-specific visuals.

Asset

The core data in a Unity project that is used for visuals,
physics, gameplay and sound-effects. Generally these arefiles, but can be hosted as sub-assets inside of larger files.
Textures, AnimationClips, Sprites, AnimatorControllers,
AudioClips and Prefabs are all Assets.

50

Chapter 4: About the Harmony Unity SDK

Importing Harmony Files into Unity
Once you've finished creating your artwork and cyclable animated character movements in Harmony, it's time toimport them into Unity for game integration.

How to import Harmony files directly into Unity
1. Create a Unity 2D project.
2. 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:l

Go to the Unity Asset Store (assetstore.unity3d.com/en/#!/content/31211) and save theHarmony Game SDK file on your computer. Then import it in your project from the following:
Top Menu > Asset > Import Package > Custom Package.

l

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 > AssetStore.
NOTE
For each new Unity project, you must repeat step 2 as it contains the necessary files andfolders to make the Harmony import process work.

3. Add the exported game object to the scene by going to Top Menu > GameObject > HarmonylHarmony Object: Lets you browse for the exported Harmony project folder. If you’ve alreadysaved 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 youneed to get going.

lHarmony Texture Object: Lets you browse for the exported Harmony project folder similarly toHarmony Object, but creates a Unity plane to render your animation on it.

51

Gaming Guide

TBG File Workflow in Unity
In the TBG (Toon Boom Gaming) file workflow, Unity will immediately interpret a TBG file exported from
Harmony as a new asset that it can reference to derive new Textures, Sprites, project data, and a Prefab fromthe file. The resulting Prefab can be dragged into the Unity scene to be immediately viewed and animated. When
the TBG file is overwritten from a new export in Harmony, the TBG Importer can automatically perform the reimport process to update the existing prefab, sprites and textures. This allows artists to rapidly iterate on theircharacters and see their results immediately in-game.

The resulting TBG Renderer prefab contains a full hierarchy of Transforms and SpriteRenderers to display thecharacter in a Unity-friendly rig. Additionally, a TBG Renderer script is included that ensures Sprites areswapped during an animation’s progress and cutters properly apply to relevant SpriteRenderers.
NOTE
The XML format used in TBG files is a newer version, and may not be compatible with the XML
Folder workflow for more complicated characters. It’s a good idea to keep your original Harmony
files and re-export them with different settings later.

How to import a TBG file into Unity
1. In Harmony, find the Export to Sprite Sheetbutton in the Game toolbar.

2. In the Export to Sprite Sheet window, check Encode as TBG .
3. For the Asset Path, enter the file path where you would like to save your character.
4. Select Save and Export. A loading bar will appear that will complete the export process andgenerate a new TBG file.
5. Open your Unity project. Unity should automatically load the TBG as a Prefab.

52

Chapter 4: About the Harmony Unity SDK

NOTE
If your character is not appearing as a Prefab, please ensure:l

You have the HarmonySDK installed for your Unity project. It must be installed forevery new project created.

l

You do not have a scene marker extending beyond the exposure of a character.

In your Unity project, there should be:lSub-assets for Textures, Sprites, TBG Store data, and AnimationClips.

lTwo new assets for the file’s SpriteAtlas and AnimatorController beside the TBG
Prefab.

The TBG Prefab can now be dragged into the Hierarchy, where it will be displayed andinteractable.

53

Gaming Guide

By selecting the Prefab in the Hierarchy, you will be able to view the character’s animations
from the Animation view.

Opening up the Prefab in the Hierarchy view by clicking the small arrow, you will be able toexplore the character’s hierarchy very similarly to what is shown in Harmony’s Timeline.

54Chapter 4: About the Harmony Unity SDK

How to manually inspect the contents of a TBG file
1. Search for the TBG file in your computer's file explorer

2. If you use Windows or Mac, rename the file extension as the .tbg file extension is not recognized byWindows and Mac computers.

Once renamed, Windows and Mac will allow you to explore the contents of the .zip file, so you canensure your SpriteSheets are reasonably sized or that your data files have the contents you expect.

55

Gaming Guide

NOTE
To ensure Unity doesn’t have any trouble, you can change the file extension back to .tbg
before resuming work with Unity. Generally this inspection process need only be done
when you're on a computer that doesn’t have Unity installed.

Adding Inverse Kinematics to a TBG Renderer Prefab
You can utilize Unity’s own 2D Inverse Kinematics feature to add procedural targets to your characters limbs.
You can use SLY_Character from the TBG Workflow example scene for this process.

How to add Inverse Kinematics to a TBG Renderer Prefab
1. Find and drag SLY_Character from the Project view to your Scene view, and press F to frame thecharacter in your view.

NOTE
Ensure the SLY_Character is selected in the hierarchy.
2. In the Inspector view, add an IK Manager 2D component.

56

Chapter 4: About the Harmony Unity SDK

3. In the IK Manager 2D component, click the + button to add a new IK solver, and select Limb.

4. Click the bottom-right bone of Sly’s legs to expose its place in the hierarchy. We will be using its
sibling GameObject that has “..._GameBone_1_end” in the name.

5. With the “New LimbSolver2D” Game Object selected, drag “New LimbSolver2D” into the Target slotof the LimbSolver2D script and drag the “_leg_cuff_GameBone_1_end” GameObject into the
Effector slot.

57

Gaming Guide

Once this is done, you can move around the New LimbSolver2D transform and see the limb bend to matchthe target.

To switch the direction the knee bends, we can click the “Flip” checkbox in the Limb Solver 2D component.

58

Chapter 4: About the Harmony Unity SDK

XML Folder Workflow in Unity
In the XML folder workflow, a unique Harmony Importer asset can be created by a developer to reference an
XML folder exported from Harmony. This importer can then be used to generate a Harmony Project asset and a
new Harmony Renderer prefab.
For each re-exported XML file , developers need to manually set import and export paths and perform the importprocess from the Harmony Importer asset.
This workflow provides flexibility as to where the XML data can live. For example, it can live either inside oroutside the Unity project. However, a disadvantage to this workflow is that more mistakes can be made since
there are more steps involved. For example, the file path for the TBG importer will have to be manually updated
when moving files around.

The resulting Harmony Renderer prefab allows high-performance character rendering by generating a meshwithin a C++ plugin. This is preferable for crowds of characters that don’t require complicated custom renderingfeatures.

How to import an XML folder into Unity
1. Within Harmony, find the Export to Sprite Sheetbutton in the Game toolbar.

2. Select Save and Export. Ensure that the Export as TBG option is unchecked in the Export to Sprite
Sheet dialog.
3. Save the XML to a folder inside of your Unity project's Assets folder.
4. In Unity, create a new Harmony Importer asset by doing one of the following:l

In the Assets drop down in the top menu, select Create > Harmony Project Import.

lRight-Click the Assets folder in the Project view and select Create > Harmony Project Import.

59

Gaming Guide

5. Name the Harmony Importer with an "Importer" suffix to avoid future confusion.
6. Copy relative path of exported folder, paste into new Harmony Importer.

7. Copy relative path of Harmony Importer asset, paste into Harmony Importer, replace “Importer” with
"Project" in the path.

8. Click Import.

60

Chapter 4: About the Harmony Unity SDK

A new HarmonyProject asset will be created as well as a new Prefab with Harmony Renderer thatreferences HarmonyProject.

The Prefab asset can be dragged from the Project view into the Hierarchy view and Scene view toshow your character in your game

Importing Anchors
In Harmony, Anchors provide a way to indicate which pegs and drawings are positions of interest for gameplay
scripts in Unity. Any drawing or peg can be assigned an Anchor.

How to import an anchor to Unity
1. Select a layer in the Timeline view or node in the Node view and select the Toggle Anchor button in
the Game toolbar.

61

Gaming Guide

2. Import the character to Unity.
The next time the XML import process is performed, the new Anchor will appear in Unity under thecharacter’s imported Prefab as a new HarmonyAnchor.

This new GameObject will follow the position, rotation and scale of the current animation playing on thecharacter. This allows you to dynamically attach gameplay objects as children to the anchors to carry, equip
and use.
NOTE
Moving anchor positions will not affect the Harmony Renderer visuals. To view and affect theentire structure of the character in Unity and not just the anchors, you may want to consider
using the TBG workflow

Adding Audio Sources
When you create scene files in Harmony with audio, the audio is exported into the project folder. The Harmony
Importer will automatically create an AudioSource and add it to the generated Prefab. The Harmony Renderer
can then trigger playback of the AudioClip files at points during animation playback, as was authored within
Harmony.

62

Chapter 4: About the Harmony Unity SDK

Adding a Harmony Renderer to Empty Game Objects
If you don’t have the prefab from your Harmony Importer, it’s possible to still create a new Harmony Renderer
component on an empty Game Object to achieve the same end result.

How to use an empty GameObject
1. Select GameObject > Create Empty.
2. Rename the empty GameObject so it's clear in the Hierarchy. Since we're using the PerryPoireau
demo file, rename the GameObject to SpaceCat by doing one of the following:lDouble-click on the name and rename it in the Hierarchy.

lSelect the GameObject and rename it in the Inspector.

3. At this point, it’s an empty object. Accessing Harmony data is done through scripts.
lSelect the PerryPoireau GameObject.

l

In the Inspector, go to Add Component > Scripts > Harmony Renderer.

Four new sections appear in the Inspector called Mesh Renderer, Harmony Mesh (Mesh Filter), andHarmony Renderer.

63

Gaming Guide

From here you need to attach a Harmony Project to this newly created Harmony Renderer. By clicking on
the circle at the right of the empty (Harmony Project) slot, you can select the project you have alreadyimported using the steps to create a Harmony Project using the XML Folder workflow.

64Chapter 4: About the Harmony Unity SDK

Setting Up Collisions in Unity
Extracting the bounding box information is useful when you want to make something collide with your character.
When you put a 2D character into a 3D scene, you may want to use Physics to make the 2D character collidewith the 3D plane.
Colliders were improved to provide several different types of colliders for use in Unity. You can select polygon
colliders and box colliders for a more accurate bounding box.

How to set up collisions
1. Select your imported character.
2. In the inspector, select Add Component > Physics 2D > Box Collider 2D.
3. To enable the Physics on the character, go to Add Component > Physics 2D > Rigid Body 2D.

NOTE
You can also use 3D physics on the imported files.

You can now adjust the variables and see the results.

65