Brainevents

Brainevents activate gameplay features and logic in a sequential order that is determined by the object or player action. See more at the Brainevents documentation page.

addBrainEventCallback(name, function)

Adds a callback function to trigger when the Brainevent is triggered. An event can only have one callback attached to it at a time. If addBrainEventCallback() is used on an event that already has a callback, it will replace the existing one with the new one.

Parameters

string name – the name of the event function the callback function to execute when the event is triggered

if (this.entity().hasEvent('MyEvent')) {
    this.entity().addBrainEventCallback('MyEvent', function() {
        log('In MyEvent Callback!');
        return true;
    });
}

↑ Back to top

currentEvent()

Returns the name of the current or most recent event. If there is no such event, returns an empty string.

Returns

string – the name of the current event

↑ Back to top

hasEvent(name)

Returns true if the entity has an event of the given name, or false if not.

Parameters

string name – the name of the event

Returns

boolean – true if the entity has the event, false if not

↑ Back to top

removeBrainEventCallback(name)

Removes the callback attached to the given Brainevent. Remember, each event can only have one callback associated with it.

Parameters

string name – the name of the event

↑ Back to top

setEvent(name)

Triggers the event passed as a parameter, also setting it as the entity’s current event. If no data is passed, the event will pass a boolean true value.

Parameters

string name – the name of the event
data (optional) value passed to the event of data type boolean, number, or string

this.entity().setEvent('AttackEventName');

↑ Back to top

Background Music

The BackgroundMusic class can be used to control the Background Music of a UI Screen Node.

play(sound, looped)

Sets the audio track of the Background Music and plays it.

Parameters

Sound sound – The new audio to play as Background Music. Sound is a Script node attribute.
boolean looped – Optional. Set the Background Music to loop if true, or stop after one play if false.

function start(){
     let track2 = this.attribute('track2');
     BackgroundMusic.play(track2);
}

A screenshot showing the Sound attribute used in the code example.

↑ Back to top

stop()

Stops the Background Music.

↑ Back to top

setVolume(volume)

Sets the volume of the Background Music, range 0 (muted) to 1 (max).

Parameters

number – the new volume of the Background Music

↑ Back to top

volume()

Returns the volume of the Background Music, range 0 (muted) to 1 (max).

Returns

number – the volume of the Background Music

↑ Back to top

Custom Nodes

A node is a piece of functionality that exists within a Node Map. If you have an idea for a custom node, you can make one yourself and share it online as a .bbnode file with JSON formatting.

To create a custom node, you need a basic understanding of JSON formatting and a text editor of your choice. To modify a pre-existing node, see Customizing Nodes.

Writing your own Custom Node

Let’s look at a simple example – the “Set Color” node. Here’s the full .bbnode file:

{
	"name" : "Set Color",
	"attributes": [
		{
			"name" : "Set",
			"type" : "Boolean",
			"connection" : "Input",
			"editable" : false		
		},
		{
			"name" : "Done",
			"type" : "Boolean",
			"connection" : "Output",
			"editable" : false		
		},
		{
			"name" : "Color",
                        "type" : "Color",
			"connection" : "None",
			"editable" : true
		}

	],
	"script":"
        function init(){
        }


        function update(dt){
        }


        function signal(name, value) {
            //Check the incoming signals
            if (name == 'Set' && value) {
                //get the node attributes
                let col = this.attribute('Color');
                
                //set the entity color
                this.entity().setColor(col.r, col.g, col.b, col.a);
                
                //Emit signal to indicate the node finished
                this.emitSignal('Done', true);
            }
        }
    "

}

This results in the following node and attributes:

Now let’s look at it line by line.

name

"name" : "Set Color",

This defines what name this node will have.

attributes

"attributes": []

This array defines what attributes the node will have in the attributes sidebar. It also details any input or output connections the node will have. Please note that the Fields and Possible Values here are all cAsE sEnSiTiVe!

"value": {
    "default": "kReplace",
    "options": {
        "Replace": "kReplace",
        "Add": "kAdd",
        "Multiply": "kMultiply"
    }
}

{
    "name": "My Slider",
    "type": "Slider",
    "connection": "None",
    "editable": true,
    "sliderMin": 0,
    "sliderMax": 10,
    "sliderStepSize": 2,
    "sliderDefaultValue": 2
}

script

"script":"

Anything you put in this string will be inserted into the Script section of the Node. Since it’s all defined within a string, make sure to use single quotes (‘) instead of double quotes (“) to avoid terminating the string early.

If you save your .bbnode file as a .json file and use a program that has syntax highlighting (such as Visual Studio Code), this section will highlight with errors. This is because normal JSON doesn’t allow multiline strings; this is an area where the .bbnode format differs from JSON.

Here’s another script example, this time from the Jump node. This code snippet is entirely contained within the “script”: ” … ” section of the Jump.bbnode file.

    //Input Signal variables
    let _enabled = true;

    //Node attribute variables
    let _jumpLimit;
    let _jumpForce;

    //working variables
    let _physics;
    let _jumpCount = 0;

    function init(){
        //get the node attributes
        _jumpForce = this.attribute('Jump Force');
        _jumpLimit = this.attribute('Jump Limit');
    
        //Get and check the Physics status of this entity
        _physics = this.entity().physics();
        if(_physics && _physics.type() != 'kDynamic'){
            warning('Jump Node only works with [Dynamic] bodies. Enabling by default');

            _physics.setType('kDynamic');
        }
    }

    function start(){

    }

    function update(dt){

    }

    function signal(name, value){
        //Check the incoming signals
        if(name == 'Jump' && value){
            //check we have dynamic physics on the entity
            if(_physics){
                //check here if the signal to jump again is valid
                //we need to check we are with the jump limit
                if(_jumpLimit == 0 || _jumpCount < _jumpLimit){
                    //calculate the jump force to be applied
                    let vel = _physics.linearVelocity();
                    if(_jumpForce.x != null){
                        vel.x = _jumpForce.x;
                    }
                    if(_jumpForce.y != null){
                        vel.y = _jumpForce.y;
                    }
                    if(_jumpForce.z != null){
                        vel.z = _jumpForce.z;
                    }
                    
                    //apply the jump velocity
                    _physics.setLinearVelocity( vel.x, vel.y, vel.z );

                    //track the jump count
                    _jumpCount++;
                }
            }
        }
        else if(name == 'Reset' && value){
            //Signal to reset the jump so we just reset the 
            //jumpcount variable
            _jumpCount = 0;
        }
    }

Import a Node

To import a node into BuildBox, drag it from your file explorer into the mind map of the Entity you’d like to add it to. Voilà!

Troubleshooting

If you drag your .bbnode into the mind map and nothing happens, that probably means there’s a typo somewhere.

– Make sure that each attribute includes all the required fields.
– Make sure that you have no trailing commas.
– A JSON Validator will give you errors based on the Script section, because as noted above, JSON doesn’t normally allow multiline strings. You can try pasting your .bbnode contents into a JSON Validator and then deleting the script section to look for errors elsewhere.

Label Node

globalDepth()

Returns the global depth of the Label node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.

Returns

number value – The global depth of the Label

↑ Back to top

isRemoved()

Returns true if the Label is removed, false if not.

Returns

boolean true if Label is removed, false if not

↑ Back to top

opacity()

Returns the opacity of the label. Ranges from 0 (invisible) to 255 (fully opaque)

Returns

number the opacity of the label

↑ Back to top

position()

Returns the position of the label.

Returns

Vec2 the {x, y} position of the label.

↑ Back to top

setGlobalDepth(value)

Sets the global depth of the Label node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.

Parameters

number value – The global depth of the Label

↑ Back to top

setOpacity(value)

Sets the opacity of the label. Ranges from 0 (invisible) to 255 (fully opaque)

Parameters

number value – The opacity of the label

↑ Back to top

setPosition(x, y)

Sets the position of the label.

Parameters

number x – the x coordinate position
number y – the y coordinate position
number z – the z coordinate position (optional)

↑ Back to top

setText(value)

Sets the text for the label.

Parameters

string value – The string that will be displayed by the label.

↑ Back to top