🏃Behavior Nodes

A powerful feature of Bonfire is its Node system. Nodes are individual pieces of functionality that, when chained together, allow creators to build unique and customizable experiences. Bonfire supports a variety of Behavior Nodes that are grouped into Causes, Effects, and Modifiers.

Nodes are made up of sockets, transitions, and properties. Sockets are the white circles positioned at the top and bottom of a Node. The number of sockets a Node has depends on its purpose and function

Transitions are formed by connecting sockets of different Nodes. These transitions direct the execution flow and are represented by solid white lines between Nodes. Nodes can be executed in sequence, one after another, in parallel, at the same time, or both.

Nodes have a unique set of configurable properties. When adding a Node to the tree in the Behaviors Panel, Bonfire assigns default modifiable values to each property.

Nodes are tied to a Spark. Before adding a Behavior Node, creators must select a Spark from the Map Editor, Map Explorer, Entities Panel, Symbols Panel, or the Spark dropdown in the Behaviors panel. Once a Spark is selected, a list of available Causes and Effects will appear in a dropdown.

Although Bonfire comes with a set of prebuilt Behavior Nodes, creators could use the SparkSDK to create custom Causes and Effects unique to a project.

Causes

A Cause is an input to a Spark that represents a condition or action within a Chapter. Examples of Causes include the starting ‘condition’ of a Chapter upon start or a player's triggering ‘action’ on a given Spark. When these conditions or actions are met, all Effects and Modifiers connected to the Cause will be triggered.

Approached

The ‘Approached’ Cause is triggered by movement into a defined circumference around a given Spark. The following are modifiable Approached characteristics:

Distance	Distance from the Spark associated with the ‘Approached’ Cause, measured in meters. If the player or specified Spark is within this distance, the ‘Approached’ Cause will trigger.
Player	If enabled, the player will trigger the ‘Approached’ Cause.
Spark	If enabled, the selected Spark will trigger the ‘Approached’ Cause.
One Shot	If enabled, the ‘Approached’ Cause will only trigger once.

Attacked

The ‘Attacked’ Cause is assigned to a Spark that receives the impact of actions taken by a player. To see a visual response, the Cause needs to be connected to an Effect, which might be a modification of the Health value–a measure of physical capacity–or an Animation (i.e., death, attack). The user in the experience initiates actions based on keyboard or VR controller actions. The keyboard key to initiate an attack is the letter Q.

Collided

The ‘Collided’ Cause triggers when a Spark or player either begins or stops touching the Spark associated with the ‘Collided’ Cause.

One Shot	If enabled, the ‘Collided’ Cause will only trigger once.
On Enter	Triggers when a Spark or player touches the Spark associated with the ‘Collided’ Cause.
On Exit	Triggers when a Spark or player has stopped touching the Spark associated with the ‘Collided’ Cause.
With Spark	On Enter/On Exit is triggered by the selected Spark.
With Player	On Enter/On Exit is triggered by the player.
Left Hand	The player’s left hand triggers On Enter/On Exit events, particularly when publishing to VR devices.
Right Hand	The player’s right hand triggers On Enter/On Exit events, particularly when publishing to VR devices.
Threshold	The threshold defines the delay, in seconds, required before a new detection is registered after an initial detection. Setting this value helps prevent unintended duplicate detections caused by sensitivity issues. The default threshold is 0.1 seconds.

Note about Threshold:

In the first GIF below, the Threshold is set to 0. When the player crosses a Trigger Spark, the “Collided Cause” is triggered twice.

Double event triggers caused by 0 threshold value

In the second GIF, the Threshold is set to 0.1 seconds. Here, when the player crosses a Trigger Spark, the “Collided Cause” is triggered only once.

Single event trigger caused by 0.1 threshold value

Adjust the threshold value as needed. If unintended double triggers occur on a “Collided Cause,” increasing the threshold may help resolve the issue.

The following instructions describe using the ‘Collided’ Cause and configuring its settings.

Prerequisites

Please ensure creators have downloaded Bonfire’s Low-Poly Animals asset pack to follow this tutorial.

1. In the Spark Browser, navigate to the Low-Poly → Animals directory.

2. Drag and drop the Buffalo Spark into the Map Editor panel from the Animals directory.

Figure 1

1. After dropping the Buffalo Spark, it will be highlighted in the Map Editor panel and selected in the Behavior and Traits panels.

Figure 2

1. For the Buffalo Spark to collide, ensure that the 'Is Collidable' option is selected in the Traits panel of the Buffalo Spark. If this option is not selected, the ‘Collided’ Cause will have no effect.

Figure 3

1. Next, add the ‘Collided’ Cause. In the Behaviors panel, ensure that the Buffalo Spark is selected from the Sparks dropdown, and select the 'Collided' Cause from the Causes dropdown.

Figure 4

1. After selecting the ‘Collided’ Cause, click the icon next to the Causes dropdown to add the Collided Node to the Behaviors panel.

Figure 5

Now that the ‘Collided’ Cause has been added, let's log a message to the Console when the player collides with the Buffalo.

1. First, ensure that the 'On Enter' and 'With Player' are the only options selected from the ‘Collided’ Cause.

1. Next, go to the Modifiers Dropdown in the Behaviors panel and select 'Debug' Modifier.

Figure 6

1. Once selected, click on the icon next to the Modifiers dropdown to add it to the Behavior panel.

Figure 7

1. To trigger the ‘Debug’ Modifier after the Buffalo’s 'Collided' Cause is triggered, a connection has to be made between the output socket of the Buffalo’s Cause Collider and the input socket of the ‘Debug’ Modifier. Input sockets are the white circles at the top of a node, and output sockets are the white circles at the bottom of a node.

Figure 8

1. In the 'Message' field of the ‘Debug’ Modifier, enter 'Player has collided with me.' This message will appear in the Console panel when the ‘Debug’ Modifier triggers (i.e. when the player collides with the Buffalo).

2. To test the collision, clear all messages from the Console panel and enter the Map Explorer panel.

3. Use the arrow keys to move the player towards the Buffalo. As soon as the player touches the Buffalo, 'Player has collided with me' will appear in the Console panel. Creators will note that Bonfire outputs other messages relating to the 'Collided' Cause to the Console panel for debugging purposes.

Figure 9

Grabbed

The ‘Grabbed’ Cause is set on a Spark as the input that allows a user to interact (hold, move) with a given Spark.

Interacted

The ‘Interacted’ Cause is triggered when the player interacts with the Spark associated with the ‘Interacted’ Cause.

Effects

Audio

The Audio Effect is accessible for Sparks and includes audio files as part of their supplemental data.

Clip	Audio clip selection. The selection comprises all audio files added as supplemental data during the Spark creation.
State	Changes the state of the audio clip when the Effect triggers: Play - Plays the audio clip. Pause - Pauses the audio clip. Stop - Stop the audio clip.
Volume	Sets the volume of the audio clip. The volume is normalized, meaning the range can only be set from 0 (mute) to 1 (maximum volume).
Solo	Only the selected audio clip will play when enabled, stopping other audio clips. When disabled, the audio clip will play regardless of different audio clips.

Modify

The ‘Modify’ Effect modifies Traits on the Spark it is attached to.

Is Visible	If enabled, the ‘Is Visible’ Trait will be enabled when the Modify Effect is triggered; otherwise, the Trait will be disabled.
Use Physics	If enabled, the ‘Use Physics’ Trait will be enabled when the Modify Effect is triggered; otherwise, the Trait will be disabled.
Is Collidable	If enabled, the ‘Is Collidable’ Trait will be enabled when the Modify Effect is triggered; otherwise, the Trait will be disabled.
Is Grabbable	If enabled, the ‘Is Grabbable’ Trait will be enabled when the Modify Effect is triggered; otherwise, the Trait will be disabled.
Is Interactable	If enabled, the ‘Is Interactable’ Trait will be enabled when the Modify Effect is triggered; otherwise, the Trait will be disabled.
Do Animation	If enabled, the Spark’s Animation will be enabled when the Modify Effect is triggered; otherwise, it will be disabled.
Altitude	If a decimal value is entered, the Spark’s Altitude Trait updates to match the value in the input box when the Modify Effect is triggered.
Position	If a decimal value is entered, the Spark’s X and Y Position Traits update to match the values in the input boxes when the Modify Effect is triggered.
Rotation	If a decimal value is entered, the Spark’s X, Y, and Z Rotation Traits update to match the values in the input boxes when the Modify Effect is triggered.
Scale	If a decimal value is entered, the Spark’s Scale Trait updates to match the value in the input box when the Modify Effect is triggered.
Color	If a decimal value is entered, the Spark’s R, G, B, and Alpha color Traits update to match the values in the input boxes when the Modify Effect is triggered.

Animation Play

The ‘Animation Play’ Effect changes the animation on a Spark. The animation will only play if the Spark has animations attached to it and the 'Do Animation' Trait is enabled on the Spark.

Do Loop	If enabled, the selected clip will loop.
Clip	This is the animation that will play when the Animation Effect triggers.

Animation Stop

The ‘Animation Stop’ Effect stops the animation on a Spark. The animation will only stop if the Spark has animations attached to it and the 'Do Animation' Trait is enabled on the Spark. Highlight

The ‘Highlight’ Effect emphasizes the Spark attached to it, with a fade-in and a fade-out effect.

Enabled	If enabled, the Spark will be emphasized.

Move

The ‘Move’ Effect changes the ‘Position’ Trait and the ‘Altitude’ Trait of the Spark attached.

Altitude	Raises or lowers the Spark to the entered altitude.
Position	Moves the Spark to the entered x and y positions.

Rotate

The ‘Rotate’ Effect modifies the ‘Rotation’ Trait of the Spark attached to it.

x	Sets the Spark’s rotation along the x-axis.
y	Sets the Spark’s rotation along the y-axis.
z	Sets the Spark’s rotation along the z-axis.

Converse

The ‘Converse’ Effect represents conversation text that appears above the Spark.

Time	The duration of the text conversation displayed on the screen is represented in seconds. When this time duration is reached, the text conversation disappears.
Message	The conversation text will be displayed above the Spark.

Force Grab

The `Force Grab` effect enables a Spark to automatically move into the player's hand when triggered. This ensures that the Spark is immediately loaded into the player hand without requiring manual grabbing.

For example, as demonstrated in the GIF below, when a button is clicked, the Spark moves directly into the player’s hand and transitions to on grabbed state, making it ready for immediate use.

Force Drop

The ‘Force Drop’ Effect makes the player release any Spark they are currently holding.

Attach On

The ‘Attach On’ Effect attaches the Spark to another Spark or onto a player.

Type	Attachment Options: Spark - Attach to another Spark. A new ‘Parent’ dropdown will appear to specify which Spark to attach it to. Player_Head - Attaches the Spark to the player’s head. Player_Hand_L - Attaches the Spark to the player’s left hand. Player_Hand_R - Attaches the Spark to the player’s right hand.
Parent	This field appears only if ‘Spark’ is selected in the Type dropdown. It specifies which Spark the currently selected Spark should be attached to.
Offset Position	Specifies the X, Y, and Z offset positions from the center of the attachment point.
Offset Rotation	Specifies the X, Y, and Z offset rotations from the center of the attachment point.

Attach Off

The ‘Attach Off’ Effect detaches the Spark from its current attachment.

Submesh

The ‘Submesh’ Effect allows the player to toggle the visibility of specific parts of a Spark’s body, provided the Spark's 3D object has multiple submeshes.

SubMesh	Provides options to select specific parts of a Spark’s body to toggle visibility.
Visible	Indicates whether to toggle the visibility of the part selected in the SubMesh dropdown when this Effect is triggered.

Modifiers

Change Book

The ‘Change Book Modifier' will load the Book linked to a given share code. The state of the current Book is saved and unloaded before loading the new Book.

Share Code	The share code of the Book to load.

Blackout

The ‘Change Book Modifier' will load the Book linked to a given share code. The state of the current Book is saved and unloaded before loading the new Book.

Type	FadeOut: Applies a fade-out effect to the player’s screen when this Modifier is triggered. FadeIn: Applies a fade-in effect to the player’s screen when this Modifier is triggered. FadeOutThenIn: Applies a fade-out effect followed by a fade-in effect after a specified duration in seconds.

Change Chapter

When triggered, the ‘Change Chapter’ Modifier loads the selected Chapter. The state of the current Chapter is saved and unloaded before loading the new Chapter.

Chapter	The Chapter to load. The selection includes the current Chapter and the next linked Chapter, as defined in the Chapter tree.

Comment

The Comment Modifier is a basic text box for creator notes, which can be placed anywhere in the Behavior Tab panel. The text box automatically expands based on the length of the comment.

Debug

When triggered, the ‘Debug’ Modifier logs a message to the Console panel.

Message	The message logged to the Console panel.
Trigger button	The Trigger button allows creators to trigger the ‘Debug’ Modifier manually. If a node is connected to one of the output sockets of the ‘Debug’ Modifier, it will execute after the Trigger button is pressed.

Delay

The ‘Delay’ Modifier delays triggering the node connected to its output socket.

Seconds	Number of seconds to wait before the node connected to the output socket is triggered.

Spawn Spark

The ‘Spawn Spark’ Modifier creates a clone of an existing Spark within the current Chapter when it is triggered.

Template	A dropdown list to select an existing Spark in the Chapter to clone.
Position	The X, Y, and Z position to where the cloned Spark will spawn.
Rotation	The X, Y, Z rotation of the cloned Spawn when it spawns

Exit Book

The 'Exit Book' Modifier terminates the game session and exits the player from the game when activated.

Random

The ‘Random’ Modifier will randomly trigger a Node connected to one of its two output sockets.

Chapter Started

The 'Chapter Started' Modifier is automatically triggered, activating the connected Nodes upon the start of a Chapter. This occurs when the player begins the scene or Chapter, or when Play Mode is enabled in the builder. It is useful for executing Nodes that need to be triggered at the beginning of a Chapter.

Toggle

The ‘Toggle’ Modifier alternates, triggering the Nodes connected to each of its two output sockets. This could be used for on/off, open/close, visible/hidden behaviors.

Stop Audio Channel

The 'Stop Audio Channel' Modifier forcibly stops playback of a specified Audio Spark when triggered.

Channel Name	Specifies the audio channel that the creator wants to stop playing.

Ember

The 'Ember' Modifier activates the custom ember script specified in the input box.

Instance ID	Specifies the name or ID of the Ember script to be triggered when the 'Ember' Modifier is activated.
Open	Button to open or view the Ember script.