Super Units

Super Units are flow graphs that are nested in a parent flow graph as a single unit. They are a powerful feature that allows you to re-use and organize your flow graphs.

For this example, we'll create a Take Damage super unit. Its task will be to substract the input damage from the health object variable, then check if it is below zero, in which case it should play a death animation. Then, it should return control to the parent unit and output a boolean that indicates whether the character was killed.

Creating A Super Unit

To create a blank super unit, right-click an empty space in your graph and choose Nesting > Super Unit. The super unit inspector works exactly like that of a machine; you can switch the source of the graph between embed and macro and convert if you need.

If you want to give a title and summary to your super unit, you can do so from the graph inspector:

For now, click the Edit Graph button or double-click the node to open the nested graph. Now that you're in the sub graph, the breadcrumbs at the top left of the graph window allow you to navigate back up:

Input Output

By default, the embed graphs in super units are created with Input and Output nodes:

These are special nodes allow you to pass flow and values to and from the parent flow graph.

  • The Input node allows you to define flow entry points and parameters of any type that should be passed to your super unit from the parent graph.
  • The Output node allows you to define flow exit points and results of any type that your super unit can return to the parent graph.

Let's start with the input. Click on the input node to open it in the graph inspector. For our Take Damage unit, we will need two inputs:

  • An entry control input, that indicates when the character should take damage
  • An integer value input, that indicates how many health points the character should lose

We will give the damage input a default value of 5 and hide the label for the entry point, because what it does can be deduced from context. For the moment, we won't spend time customizing the label and summary of each port, but keep in mind that you can use those to document your own super units.

As we go, the input node will get updated. When you're done, it should look like this:

Now, let's configure the output. Click on the output node to open it in the graph inspector. For our unit, we will need two outputs:

  • An exit control control output, that indicates when we're done
  • A boolean value output, that indicates whether the character was killed by the damage

When you're done, the output node should look like this:

Here are some very important constraints to keep in mind while defining inputs and outputs:

  • The key cannot be null or empty.
  • The key of each port must be unique across the entire graph. You cannot have an input and an output with the same key, even if they are of a different kind or type.
  • If you change a key, all connections to that port will be removed. Bolt uses keys to identify ports, so if you change them, the connections become obsolete. If you want to change the name of a port without losing all the connections, you can override it with the Label property, which is purely cosmetic and has no impact on functionality.
  • Each value input and output must have a type.

Bolt will warn you from the inspector if you do not meet these criteria.

Now that we have our input and output nodes, we only have the hard part left to do! We'll leave the implementation of this node as a homework and won't go through it step by step, but here's what the final result could look like:

Back in the parent graph, all of this complex logic turns into a simple, single unit with 2 inputs and 2 outputs. Tadah!

Using a Macro

If you have a flow macro that you want to use as a super unit, you can either drag & drop it into your graph, or create it from the Macros category in the fuzzy finder.

Sharing

If you want to share your super unit with others, simply convert it to a macro and upload it. Since macros are just normal asset files, you can share them with your team and your friends!

You can also share the macro in the #library channel on the Bolt Discord server.

Note: Stay tuned! We're currently working on better ways to share your graphs.

  • Copy+Pasting to and from a JSON string
  • Sharing your graphs directly on Imgur and Github Gists
  • In the long term, creating a graph cloud ecosystem