Exploring Buildbox Content Nodes — The Button Node (API)

In this blog post, we’re delving into the Button node, this time we will be looking into the API aspect of it.

Overview

Here’s the full list of API functions that the Buttons has:

let button = this.ui().find('My Button')[0]; // get First instance of this button

button.activate();
button.position();
button.setPosition(value);
button.rotation();
button.setRotation(value);
button.scale();
button.setScale(value);
button.opacity();
button.setOpacity(value);
button.isVisible();
button.setVisible(value);
button.onClick = function (){ /*Code */ }; // special case

Table of Contents

· activate()
· position()
· setPosition(value)
· rotation()
· setRotation(value)
· scale()
· setScale(value)
· opacity()
· setOpacity()
· isVisible()
· setVisible(value)
· onClick

activate()

Function: Triggers the action assigned to the button as if it were tapped.

Usage: This function simulates a user’s tap on the button, making it perfect for automating interactions. Below you can find an example of how to trigger a UI button called “MyButton” when an input signal is received.

function signal(name, value, sender, source){
  if(value){
    let button = this.ui().find('MyButton')[0];
    button.activate();
  }
}

position()

Function: Returns the current position of the button in the game world as a Vec3 object {x, y, z}.

Usage: Determine the precise location of the button.

function init(){
  let button = this.ui().find('MyButton')[0];
  let buttonPosition = button.position();
}

setPosition(value)

Function: Sets the screen position of the button using a {x, y} value.

Usage: Precisely control the button’s on-screen location.

let button, startPosition;
let outOfBoundsPosition = new Vec2(0, -100);
function init() {
  button = this.ui().find('MyButton')[0];
  startPosition = button.position();
}

function signal(name, value, sender, source){
  if(value){
      button.setPosition(outOfBoundsPosition);
  }else{
      button.setPosition(startPosition);
  }
}

rotation()

Function: Returns the current rotation of the button in the game world.

Usage: Get insights into the button’s orientation.

function init(){
  let button = this.ui().find('MyButton')[0];
  let buttonRotation = button.rotation(); //  number from 0 - 360
}

setRotation(value)

Function: Sets the 2D rotation of the button in degrees.

Usage: Control the button’s orientation in degrees.

let button, startRotation;
let rot45Degrees = 45;
function init() {
  button = this.ui().find('MyButton')[0];
  startRotation = button.rotation();
}

function signal(name, value, sender, source){
  if(value){
      button.setRotation(rot45Degrees); // Rotate the button 45 degrees
  }else{
      button.setRotation(startRotation);
  }
}

scale()

Function: Returns the current scale of the button.

Usage: Understand the button’s size relative to its original dimensions.

function init(){
  let button = this.ui().find('MyButton')[0];
  let buttonInitialScale= button.scale();
}

setScale(value)

Function: Sets the screen position of the button using a {x, y} value.

Usage: Precisely control the button’s on-screen location.

let button, initialScale;
let invisibleScale = new Vec2(0, 0); // Hide it
function init() {
  button = this.ui().find('MyButton')[0];
  initialScale = button.scale(); // {x:1, y: 1}
}

function signal(name, value, sender, source){
  if(value){
      button.setScale(invisibleScale); // hide the button for now
  }else{
      button.setScale(initialScale);
  }
}

opacity()

Function: Returns the current opacity of the button, ranging from 0 to 255. Usage: Check the button’s current opacity setting.

Note: if the button has opacity 0 it’s invisible but you can click and/or trigger it by taping on the “hidden area”

function init() {
  let button = this.ui().find('MyButton')[0];
  let opacity = button.opacity();
  log(opacity); //  opacity of the button 0 - 255
}

setOpacity()

Function: Sets the opacity of a button to the specified value (0–255).

Usage: Adjust opacity to create visual effects. An opacity of 0 makes the button invisible but still tappable.

let button, initialOpacity, semiTransparentOpacity = 128;
function init() {
  button = this.ui().find('MyButton')[0];
  initialOpacity = button.opacity();
  log(initialOpacity); //  opacity of the button 0 - 255
}

function start(){
  button.setOpacity(semiTransparentOpacity); // Set opacity to 128 (semi-transparent)
}

function signal(name, value, sender, source){
  if(value){
      button.setOpacity(semiTransparentOpacity); // hide the button for now
  }else{
      button.setOpacity(initialOpacity);
  }
}

isVisible()

Function: Returns true if the Button is currently visible, false if not. If a Button is not visible, it cannot be tapped.

Usage: Use this function to check whether the button is visible to users.

Here’s an example to trigger an Invisible button.

let button;
function init() {
  button = this.ui().find('MyButton')[0];
  button.setVisible(false); // we hide the button
}

function signal(name, value, sender, source){
  if(value){
    if(!button.isVisible())
      button.activate();
  }
}

setVisible(value)

Function: Sets the visibility of a button (true for visible, false for not visible).

Usage: Control when the button is displayed or hidden. If not visible, it cannot be tapped.

let button;
function init() {
  button = this.ui().find('MyButton')[0];
  button.setVisible(false); // We hide the button
}

onClick

Property: Function assigned to this property will be executed when the user touches the button.

Usage: Define specific actions or behaviors triggered by button clicks.

Below you can find an example of how to make a custom function of a button to trigger an interstitial via code. Note this works only on Navigation buttons with the Custom function selected.

function init(){
  let button = this.ui().find('Trigger Interstitials')[0];
  button.onClick = function () {
      // Define the action to be taken when the button is clicked.
      Ads.showInterstitial();
  }
}

Note: find function returns an array of objects with the provided name or null if there are no objects in the UI with the specified name. so we select only the first one in the list with `[0]` If you want to do the same onClick behavior for all the objects called “Trigger Interstitials” then we can do it like this:

function init(){
  let buttons = this.ui().find('Trigger Interstitials');
  buttons.forEach(button => {
    button.onClick = function () {
        // Define the action to be taken when the button is clicked.
        Ads.showInterstitial();
    }
  });
}