Graphs, Machines and Macros
| Note |
|---|
| To use Bolt, which is Unity’s visual scripting solution, you must purchase it on the Unity Asset Store. |
Graphs are visual representations of logic. They’re at the core of Bolt.
There are two kinds of graphs:
Flow Graphs, in which you connect individual actions and values in a specific order. That order of execution is what we call the flow. If you have used Unreal Engine before, you might find they are similar to the Blueprints visual scripting language.
State Graphs, in which you create different states and the transitions between them. Each state acts as a little program. If you have used PlayMaker or other FSM (Finite State Machine) systems before, you’re familiar with state graphs.
Together, these two kinds of graphs allow you to create any game you have in mind.
When to use each kind of graph
- You will most often use Flow Graphs. They let you execute actions at every frame or when an event (like a collision) occurs. Flow graphs have access to all the so-called “low-level” logic, like branching, loops, math, etc. They best answer the question “when this happens, what should I do, and in what order?”.
- You will use State Graphs when you
want to create so-called “high-level” logic, like AI behaviours,
sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary or level structure, or anything that requires the notion of state. For example, an enemy that has a “patrol”, “chase” and “attack” states, or a door that has “locked”, “unlocked”, and “open” states. State Graphs best answer the question “what is my current behaviour, and when should that change?”.
Each kind has its own full dedicated section in the manual, Flow Graphs and State Graphs. You should read them in this order. We will see later that you can combine the two kinds of graphs: for example, each state node in a state graph is actually a flow graph.
For now, let’s just introduce some basic concepts that are shared for both kinds of graphs.
Machines
A Machine is a component that you add on a game object to execute the logic of a graph during play mode. There is one for each kind of graph: a Flow Machine and a State MachineThe set of states in an Animator Controller that a character or animated GameObject can be in, along with a set of transitions between those states and a variable to remember the current state. The states available will depend on the type of gameplay, but typical states include things like idling, walking, running and jumping. More info
See in Glossary. They are both located under the Bolt category.
You can also find them in the top level Unity menu:
Both have the same options in the inspectorA Unity window that displays information about the currently selected GameObject, Asset or Project Settings, alowing you to inspect and edit the values. More info
See in Glossary, so we’ll just create a flow machine for this example:
You can give a title and summary to each graph to help identify them. They have no impact on functionality, but help with organization.
The Edit Graph button opens the graph of this machine in the graph window and the graph inspector. If you only have one machine on the same object, you won’t need to use it, because Bolt automatically matches the graph to your selection.
Embeds vs. Macros
Let’s take a look at the Source. You have two options: Embed or Macro.
| Embed | Macro | |
|---|---|---|
| Relation | The graph is embedded in the machine itself. | The graph is a macro asset that isreferenced by the machine. |
| Re-usability | You cannot re-use the graph for other machines, but it will be shared across prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info See in Glossary instances. |
You can re-use the same macro for multiple machines, even if they’re not on the same prefab. |
| Permanence | If you remove the machine component, the graph will be deleted.The graph will also be deleted if you switch the Source to Macro. | If you remove the machine component, the macro asset will still exist. The graph will not be deleted if you switch the Source to Embed. |
| Scene Reference | The graph can refer to game objects from the current scene in its graph, as long as it’s not saved as a prefab. | The graph cannot refer to game objects from the current scene, because it does not “belong” to any scene. |
| Prefabs | The machine should not be used if you instantiate your prefab while in the editor. | The machine can safely be used on all prefabs. |
Macros
A Macro is a re-usable graph that can be referenced by multiple different machines that have their Source set to Macro.
If you switch the Source option of our machine to Macro, you’ll see that you now have to tell the machine which macro it should use:
As you would expect, a Flow Machine requires a Flow Macro and a State Machine requires a State Macro.
To create a macro, right-click in an empty folder in your Project panel and choose Create > Bolt > (Flow / State) Macro. We recommend putting your macros in a top-level Macros folder, but that organization is entirely up to you and has no impact on functionality.
Then, you can simply drag-and-drop your new graph or use the Unity object picker to assign it to the machine:
Shared Live Update
When you change a graph in a macro, that change will apply to all objects that have that macro attached to it. No need to have a unique macro for every instance of an object, or to ever copy-paste your changes.
When to use which source
As you might have seen from the table above, a macro is generally superior to an embed - it is reusable, not tied to the object, and works safely with prefabs. However, there is a very simple rule of thumb to determine which source to use use:
- Most often, you’ll use a macro. Macros are faster to load and easier to maintain if your graph will be reused across one or more objects or scene.
- For graphs that will only be used once in the current scene, you can use an embed. This will allow you to use scene references, which is very useful for GUI.
Converting the Source
At first, you might find it a bit confusing to choose whether you should use a macro or an embed graph. Don’t worry: Bolt makes it simple to change your mind at any moment. It’s common and normal to convert from one kind of source to the other.
From Macro to Embed
For example, if you were using a shared state macro for AI behaviour, but you then realize that this one enemy has special behaviour, you might want to convert your macro to an embed graph to modify it independently from the others.
To do so, simply click on the Convert button.
From Embed to Macro
For example, you might start working on an embed graph for movement on an enemy game object, but then realize you’d want the same logic to apply to friendly NPC’s. Therefore, you’ll want to convert your embed graph to a macro for re-usability.
To do so, simply click on the Convert button and choose a path and file name for the new macro. Bolt will copy all the items in your embed graph to the macro (except scene references, which are not supported in macros). The machine will then automatically switch to macro mode and reference your new graph.