How to Use Scripts in Toon Boom Harmony

Mark PhilippAll Topics, Animation and Storyboarding, Tutorial

How to Use Scripts in Toon Boom Harmony

Share this Post

One of the seemingly lesser-known features of Toon Boom’s Harmony software is the ability to write scripts within the program. We’ve written many blog posts about Harmony’s features, but in this post, we will discuss what can be accomplished through scripting in Harmony, some of the scripting documentation available, and how to create a simple script and execute it.

Benefits of Writing Harmony Scripts

Toon Boom Harmony provides three different interfaces for scripting:

  • Harmony Scripts: These are written and used directly in the Harmony interface. Useful for automating workflows and functionalities. Also useful for displaying messages within Harmony.
  • Script Module: In a nutshell, this interface is used for creating nodes that have custom behavior. This can be useful for creating custom compositing effects for your node-tree, for instance.
  • DbScript: This is useful for working with data from the Harmony Server database.

Overall, the benefit of writing scripts in Harmony is that you can extend the features of Harmony to suit your needs. In general, writing scripts is something that only advanced users will likely find useful. Perhaps there is a kind of node that you really need but Harmony does not have. You can make that node yourself. Maybe you want to automate a workflow you commonly use in Harmony. You can make a script to do that. Essentially, scripting allows you to extend Harmony and turn it into your own, personalized software with all the features you need.

In this blog, we will only focus on Harmony Scripts. However, it’s important to understand the role of the other two interfaces so you know what tools you have available to you.

What Languages & Frameworks does Harmony Script use?

Harmony’s scripting interface utilizes a popular scripting framework called Qt Script. Qt script utilizes a syntax that is like JavaScript and JScript and it is object-oriented. This means that you will be a more advantageous position if you have any experience with JavaScript or JScript. If are familiar with the syntax, then most of the challenge will come from figuring out how to make use of Harmony’s QT Script library. Additionally, having a basic understanding of common data types in programming languages (int, double, string, bool) will be useful.

Documentation

It’s important to note that there are not a lot of resources available for learning how to write scripts in Harmony. Therefore, writing Harmony scripts will require a lot of trial, error, and research. This means that the available Harmony scripting documentation is an incredibly valuable resource.

The Harmony Script Interface Documentation is going to be the most valuable asset for making Harmony Scripts. The documentation covers modules, namespaces, classes, and header files. When you want to figure out how to implement some feature, your best starting point will likely be this documentation. Additionally, it’s important to know Harmony’s terminology for their nodes, which can be found here.

If you are interested in creating your own custom nodes, then you will want to dive into the Script Module Documentation. This documentation will provide interface details for the different Script Module classes. This will likely be your starting point for writing your Script Module code.

If you are interested in DbScript, you’ll want to refer to the DbScript Documentation. This will be your starting point for writing Db scripts.

How to Write a Script in Harmony

At this point, we’re ready to create a simple, “Hello, world!” script that will run in Harmony. All we will do is create a new script that will pop up a Message Window that says “Hello, world!”

    1. Open Toon Boom Harmony and create a new scene. You can call it whatever you want and save it wherever you want.
    2. When Harmony opens, we need to first make sure that the Script Editor is enabled. Near the top-right of the main viewport, click the + icon and select “Script Editor”
    3. writing a script in Harmony
    4. Once the script editor opens, the viewport will switch views and you will see a “File” pane on the left. The pane on the right is your script editor, which is where you write your code. The first thing to note is that the File pane contains several scripts that come with Harmony by default. Most of these scripts are run by Harmony on startup or during the use of certain features. It can be advantageous to look at some of the scripts to help yourself better understand the syntax and logic of utilizing Harmony Script.
    5. First, let’s make sure the scripting toolbars are enabled. Go to Windows -> Toolbars. Make sure you enable the “Scripting” and “Script Editor” This will place several useful buttons in the script editor for easy access.

EnableToolbars

    1. Now, we want to create a new script. To do this, click the icon near the top-left of the viewport that looks like three horizontal lines stacked on top of each other. Choose File -> New Script.

NewScript

    1. You will be asked to name your script. Go ahead and name it HelloWorld.

NewScriptName

    1. In the File pane, on the left, find the HelloWorld.js file in the list and left-click on it. In the editor pane, on the right, put in the following code:

 

function HelloWorld()

{

MessageBox.information(“Hello, World!”);

}

Code

This code is incredibly simple. We create a function called HelloWorld(). When this function runs, it will call on the MessageBox class’s member function information(). We pass the string                   “Hello, World!” as an argument for the information() function, which will set the text that is displayed in the message box.

      1. Now we want to verify the code and make sure it is valid. To do this, click the “Verify” button near the bottom-right of the viewport.

VerifyButton

A message window should come up saying that the syntax is valid. Click “OK”.

ValidSyntax

      1. Be sure to save the script by clicking the “Save” button next to the verify button.
      2. Now, we want to run this script. First, we need to tell Harmony which function to run. On the toolbar, click the target icon.

SetTarget

      1. On the window that comes up, choose HelloWorld.js from the files pane and select the HelloWorld function from the functions pane. Click Ok.

SetFunctionTarget

      1. Now, we just need to run the script. On the toolbar, click the icon that shows an “f” with a right-facing triangle on it. This will run your script.

RunFunction

      1. You should now see a message box pop up with a message on it saying “Hello, World!” Click OK to close the window.

HelloWorld

      1. Now, you can pin the script to the toolbar for easy access. On the toolbar, click the “Manage Scripts” option.

ManageScripts

      1. In the script manager window that opens, Select HelloWorld.js -> Select HelloWorld in the functions pane -> Click the right-facing arrow. You can then add a custom icon or tooltip using the buttons of the same name near the bottom right of the window. Once you’re done, click “OK”.

ScriptManager

      1. You will now see a new icon on your toolbars window. When you click the icon, it will run your script.

Conclusion

Hopefully, this has given you a basic starting point for writing your own scripts in Harmony. The QT Harmony library is rather extensive and provides a lot of functionality. If you are willing to put in the time and effort, you can make Harmony into your own, personalized animation solution.  Good luck!

Share this Post