Script Node

With BuildBox you can make games without any coding expertise. However, it’s also possible to add code to your game by using JavaScript. Most standard JavaScript will work within BuildBox. This API will help you control many aspects of your game with BuildBox-specific functionality.

Script Nodes (also called Script Components) consist of four functions by default: init(), start(), update(dt), signal(name, value, sender), and requested(name, value, sender).

Function Description
animation(name)

Given the string name of an Animation node, this method returns the matching Animation node object. Returns null if no node is found with that name.

attribute(name)

Returns the value of an attribute of this script node. Attributes are useful for containing local information that only this script node will use. They are listed in the window on the right side of the BuildBox screen when a script node is open. New attributes are added with the “Add Attribute” button at the bottom right of the screen. Attributes can be various data types such as number, Vector3D, boolean, etc., so this method will return the data in that format.

emitSignal(name, value)

Sends a signal via an output connection.
Output connections are added to a script node by clicking the “+” button on the right side of the node.

enableTouch(swallow, priority)

Enables touch events. The entity will start receiving events for three functions: touchBegin(point), touchMove(point), and touchEnd().

entity()

Returns the Entity object of this script node.

init()

init() is called when the entity is initialized. This happens only once.

log(value)

Outputs a message to the console (displayed on the right side of the Preview window). You can use this to debug your code by logging variables. Works the same as console.log() in a normal JavaScript context.

requested(name, value, sender)

This function is tied to the purple circle on the right side of some nodes. It’s a way to pass information without using signals.

scene()

Returns the Scene object.

signal(name, value, sender)

An entity’s signal() function is called upon receiving a signal from an input connection.
Input connections are added to a script node by clicking the “+” button on the left side of the node. You can see what node sent the signal with the sender variable.

start()

start() is called after all inits on other objects are called.

touchBegin(point)

Triggered when the player touches the screen. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, as in the example below.

touchEnd()

Triggered when the player lifts their finger. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, like in the example below.

touchMove(point)

Triggered when the player moves their finger. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, like in the example below.

ui()

Returns the Ui object connected to this 3D world on the mind map.

update(dt)

An entity’s update() function is called every frame.
Putting complex logic in this function can negatively affect performance.


animation(name)

Given the string name of an Animation node, this method returns the matching Animation node object. Returns null if no node is found with that name.

Parameters

string name – The name of the Animation node

Returns

Animation Animation node object

↑ Back to top


attribute(name)

Returns the value of an attribute of this script node. Attributes are useful for containing local information that only this script node will use. They are listed in the window on the right side of the BuildBox screen when a script node is open. New attributes are added with the “Add Attribute” button at the bottom right of the screen. Attributes can be various data types such as number, Vector3D, boolean, etc., so this method will return the data in that format.

Parameters

string name – Name of the attribute.

Returns

Value Value of the attribute.

function init(){
    // this script has a number attribute called maxLives, so if I assign `lives` this way, it will get that number value.
     let lives = this.attribute('maxLives');
}

↑ Back to top


emitSignal(name, value)

Sends a signal via an output connection.
Output connections are added to a script node by clicking the “+” button on the right side of the node.

Parameters

name – The name of the output connection.
value – Data sent through the signal. This can be any data type; string, number, boolean, object, etc.

function init(){
  // this script has an output connection named "Initialized".
  this.emitSignal("Initialized", true);
}

↑ Back to top


enableTouch(swallow, priority)

Enables touch events. The entity will start receiving events for three functions: touchBegin(point), touchMove(point), and touchEnd().

Parameters

boolean swallow – (optional) If this boolean is set to true, then entities with lower priority will not receive the touch event.
number priority – (optional) The priority of this component’s touch event. This value decides which entity’s touch events will be triggered first when multiple are touched at once. This value can be positive or negative.

function start(){
  this.enableTouch();
}

↑ Back to top


entity()

Returns the Entity object of this script node.

function start(){
  let ent = this.entity();
  ent.setPosition(0, 1, 0);
}

↑ Back to top


init()

init() is called when the entity is initialized. This happens only once.

function init(){
  // Called when the entity is initialized.
}

↑ Back to top


log(value)

Outputs a message to the console (displayed on the right side of the Preview window). You can use this to debug your code by logging variables. Works the same as console.log() in a normal JavaScript context.

let myString = "world!";
log("Hello ", myString); // output: Hello world!
let x = 5;
log("Value of x=", x); // output: Value of x=5

↑ Back to top


requested(name, value, sender)

This function is tied to the purple circle on the right side of some nodes. It’s a way to pass information without using signals. One way you could use it is to connect the purple circle of one script node to an input connection on another script node. This can help you keep code organized and make it easier to see how information is getting passed around visually. The information from the reference() function of the first script node will be sent to the second one whenever the second one calls this.attribute(‘Input’);.

// Script1
let health = 5;
function requested(name, value, sender) {
  return health;
  }
}
// Script2
function start() {
  log(this.attribute("InputHealth") // logs: 5
  }
}

↑ Back to top


scene()

Returns the Scene object.

function signal(name, value){
  // search for objects with the name passed from the signal.
  if(name == 'Object' && value){
    let scene = this.scene();
    let objs = scene.find(value);
  }
}

↑ Back to top


signal(name, value)

An entity’s signal() function is called upon receiving a signal from an input connection.
Input connections are added to a script node by clicking the “+” button on the left side of the node.

string name The name of the input connection.
value The data received through the signal. This can be any data type; string, number, boolean, object, etc.
string sender Which node sent the signal.

function signal(name, value, sender){
  if(value) { //value is a boolean in this case
        let amount = this.attribute('Amount');
        this.scene().addScorePoint( amount );
    }
}

↑ Back to top


start()

start() is called after all inits on other objects are called.

function start(){
  // Called after all inits on other objects are called.
}

↑ Back to top


touchBegin(point)

Triggered when the player touches the screen. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, as in the example below.

Parameters

object point – {x, y} coordinates of where the user touched on the screen. Screen coordinates start at {0, 0} in the upper left corner of the screen, going up to the resolution chosen ({640, 1136} for iPhone 5, for example).

Returns

boolean swallowed If your touchBegin() function returns true, other touch events will lower priority will not receive the touch event.

function touchBegan(point){
  originalPos = this.entity().position();
  this.entity().setPosition(point.x, point.y, originalPos.z);
  return true; 
}
component.touchBegan = touchBegan;

↑ Back to top


touchEnd()

Triggered when the player lifts their finger. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, like in the example below.

function touchEnded(){
  if (this.entity().position().x > 500){
    //invalid position, return to original spot
    this.entity.setPosition(originalPosition);
  }
}
component.touchEnded = touchEnded;

↑ Back to top


touchMove(point)

Triggered when the player moves their finger. To add custom behavior when a player touches the screen, you’ll need to add this function to your script, like in the example below.

Parameters

point – {x, y} coordinates of where the user moved their finger on the screen. Screen coordinates start at {0, 0} in the upper left corner of the screen, going up to the resolution chosen ({640, 1136} for iPhone 5, for example).

function touchMove(point){
  this.entity().setPosition(point.x, point.y, originalPos.z);
}
component.touchMove = touchMove;

↑ Back to top


ui()

Returns the Ui object connected to this 3D world on the mind map.

Returns

Ui the UI object connected to this 3D world on the mind map

let ui = this.ui();
let buttons = ui.find('Start Game');

↑ Back to top


update(dt)

An entity’s update() function is called every frame.
Putting complex logic in this function can negatively affect performance.

number dt Delta time, in seconds. The elapsed time since the last call to update().

function update(dt){

}

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.