Buildbox API Script Node

Script Nodes (also called Script Components) consist of four functions by default: init(), start(), update(dt), signal(name, value, sender, source), and requested(name, arg, sender). Let me give you a few examples of how you can use them.

Photo by Caspar Camille Rubin on Unsplash

Let's start with the basics:

In what order are the functions called?

The only exception we have from the list is the “requested” function but the rest of the functions run in the following order:

1st is init
2nd is start
3rd is signal
4th is update

Note: The requested function gets called based on where it was triggered, so if you call it from init() it will be after init() and before start(), from start() it will be after start() and before signal() and from signal() it will go after signal() and before() update.

Function init() — this function starts before anything is loaded inside the UI screen or scene. It is usually used to get attribute references and it is initialized only once.

Base:

function init() {

}

Attributes reference:

let scorePoint; /* Define the variable name for a 
                attribute that's a number type */
function init() {
  scorePoint = this.attribute("Score Point");
}

How to add an Attribute and save it at scorePoints?

Function start() — this function starts after all the entities in the scene have their init() function triggered. It is usually used to spawn new entities if needed or to start a game logic or timer etc

Base:

function start() {
}

Use case/example:

let enabled; /* Define a ON/OFF variable to 
            enable / disable the Update runtime */
function init() {
  enabled = false;
}

function start() {
  enabled = true;
}

function update(dt) {
  if(!enabled) return;

  // Code execution goes here
  log('Cod Execution');
}

How to use the start function to enable/disable code execution?

Function update (dt) — this function runs every frame and it’s triggered after the signal() function. It is usually used to move the entity around, update score/health bars and game logic.

Get NV’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

It has dt as the parameter standing for delta time that’s frame dependent and has the value of 1/60 (default refresh rate) or 1/120 (on high-end devices). NOTE: Putting complex logic in this function can negatively affect performance.

Base:

function update(dt) {
}

Use case/example disable update function after 100 runs:

let enabled; /* Define a ON/OFF variable to 
            enable / disable the Update runtime */
let counter;
function init() {
  enabled = false;
  counter = 0;
}

function start() {
  enabled = true;
}

function update(dt) {
  if(!enabled) return;

  // Code execution goes here
  log('Cod Execution ', counter);

  if(counter >= 100)
      enabled = false;

  counter += 1; // Add 1 to current counter value
}

Function signal(name, value, sender, source) — this function runs every time the input is triggered on that specific node.

name The name of the input connection that received the signal.
value The data received through the signal. This can be any data type; string, number, boolean, object, etc.
sender The script node that sent the signal.
source The name of the output connection (within the sender) that sent the signal.

Base:

function signal(name, value, sender, source){
}

How to add points using signal node:

function signal(name, value, sender, source){
  if(value) { //value is a boolean in this case
        let amount = this.attribute('Amount');
        this.scene().addScorePoint( amount ); // 10
        
        // print current Points Count
        log(this.scene().currentPoints());
    }
}

Function requested(name, arg, sender)— This function is tied to the purple circle on the right side of some nodes. If you connect the purple circle of one script node to an input connection on another script node, the data from the requested() function of the first script node will be sent to the second one whenever the second one calls this.attribute(name)

name — The name attribute being requested (“Self” if using purple connection)
arg — The data received through the request. This can be any data type; string, number, boolean, object, etc. Undefined if no data was sent.
sender The script node that sent the request.

Base:

function requested(name, arg, sender) {
}

How to get health using arguments, maxHealth and null using the requested function:

//Script 1:
let health = 5;
let maxHealth = 15;

function requested(name, arg, sender) {
  if (arg == "Current") {
    return health;
  }
  if(name == "Player" && arg == "MaxHealth"){
    return maxHealth;
  }

  // default value returned
  return null;
}

function start() {
  log(this.attribute("InputHealth", "Current")[0]); // logs: 5
  log(this.attribute("PlayerHealth", "MaxHealth" )[0]); // logs: 15
  log(this.attribute("InputHealth", "")[0]); // logs: null
  log(this.attribute("InputHealth")[0]); // logs: null
}