A node, or component, is a piece of functionality that exists within a Mind Map. For more API information about specific nodes, check the drop down menu beneath Nodes in the sidebar. For information on accessing an Entity’s nodes, check the Entity reference.
| Function | Description |
|---|---|
| name() |
Returns the name of the given node. |
Returns the name of the given node.
string – the name of the 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, source), and requested(name, arg, 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. See more about creating attributes here. Attributes can be various data types such as number, Vector3D, boolean, etc., so this method will return the data in that format. |
| attributeNames() | Returns an array of the names of all the attributes within the script node. |
| attributeType(name) | Returns the data type of the given attribute. |
| disableTouch() | Disables touch events. Used together with enableTouch(). |
| 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: touchBegan(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, arg, sender) | This function is tied to the purple circle on the right side of some nodes. While emitSignal() sends out data, attribute(name) can be used to request data. 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). |
| scene() | Returns the Scene. The Scene object handles things at the 2D/3D world level. |
| signal(name, value, sender, source) | An entity’s signal() function is called upon receiving a signal from an input connection. |
| start() | start() is called after all inits on other objects are called. |
| touchBegan(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. |
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.
string name – The name of the Animation node
Animation Animation node object
Returns the value of an attribute of this script node. See more about creating attributes here. Attributes can be various data types such as number, Vector3D, boolean, etc., so this method will return the data in that format.
Note: For Asset attributes, this.attribute(‘MyAsset’).id() will return an id which can be used with the create() method.
Input and output connections also qualify as attributes. If this.attribute(name) is called on an input or output connection, an array of all the nodes connected to this attribute will be returned. For example, with three 3D Models connected to a script’s input called “My Models”, this.attribute(“My Models”) will return an array of the three 3D Models. The order of this array depends on the order the nodes were connected in.
See also requested().
string name – Name of the attribute.
Value arg – (Optional) Value to pass to requested() as an argument. This can be any data type; string, number, boolean, object, etc.
Value/Array Value of the attribute, or array containing all values connected to the attribute.
function init(){ let lives = this.attribute('maxLives'); log(lives); // prints: 3 }
A screenshot showing the maxLives number attribute used in the code example.
Returns an array of the names of all the attributes within the script node. All script nodes have the attributes “Name” and “Self”. “Name” is the name of the node, and “Self” refers to the purple output connection of the node (see requested() and the Custom Nodes for more information). Any custom attributes that have been added will be returned as well.
array – An array containing the string names of all the attributes within the script node.
This example uses the same attribute setup as the example in attribute().
function start(){
log(this.attributeNames()); // prints: [Name, Self, maxLives]
}
Returns the data type of the given attribute.
name – The name of the attribute
string – The data type of the attribute. Possible values: “number”, “bool”, “vec2”, “vec3”, “color”, “string”, “animation2d”, “mesh”, “texture”, “asset”, “sound”, “input”, “output”
Disables touch events. Used together with enableTouch(). Can be seen used in the Is Touched node.
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.
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); }
Enables touch events. The entity will start receiving events for three functions: touchBegan(point), touchMove(point), and touchEnd().
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 must be greater than zero.
function start(){
this.enableTouch();
}
component.touchBegan = function (pt) {
log("Touch began at ", pt);
}
component.touchMove = function (pt) {
// warning: this function will keep firing as you keep touching, so this log will probably slow your game down
log("Touch move at ", pt);
}
component.touchEnded = function (pt) {
log("Touch ended at ", pt);
}
Returns the Entity object of this script node.
function start(){ let ent = this.entity(); ent.setPosition(0, 1, 0); }
init() is called when the entity is initialized. This happens only once.
function init(){ // Called when the entity is initialized. }
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
This function is tied to the purple circle on the right side of some nodes. While emitSignal() sends out data, attribute(name) can be used to request data. 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). Note that this.attribute(name) returns an array when the referenced attribute is an input or output connection, because more than one node can be connected at once. The order of this array depends on the order the nodes were connected in.
string name The name attribute being requested (“Self” if using purple connection)
Value arg The data received through the request. This can be any data type; string, number, boolean, object, etc. Undefined if no data was sent.
ComponentScript sender The script node that sent the request.
// Script1 let health = 5; function requested(name, arg, sender) { if (arg == "Current") { return health; } }
// Script2 function start() { log(this.attribute("InputHealth", "Current")[0]); // logs: 5 }
Returns the Scene. object. The Scene object handles things at the 2D/3D world level.
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); } }
An entity’s signal() function is called upon receiving a signal from an input connection. See more about creating input connections here.
string name The name of the input connection that received the signal.
Value value The data received through the signal. This can be any data type; string, number, boolean, object, etc.
ComponentScript sender The script node that sent the signal.
string source The name of the output connection (within the sender) that sent the signal.
function signal(name, value, sender, source){ if(value) { //value is a boolean in this case let amount = this.attribute('Amount'); this.scene().addScorePoint( amount ); } }
start() is called after all inits on other objects are called.
function start(){ // Called after all inits on other objects are called. }
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.
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).
boolean swallowed If your touchBegan() 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;
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;
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.
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;
Returns the Ui object connected to this 3D world on the mind map.
Ui the UI object connected to this 3D world on the mind map
let ui = this.ui();
let buttons = ui.find('Start Game');
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){
}
Settings is a dummy class that can be extended in any way to store user information. Every time the user minimizes app, this class is serialized and saved in JSON format. It is restored during next game session.
Code example in Buildbox:
// store the name of the selected character Settings.selectedCharacter = this.entity().name(); // get the stored character name from Settings let charName = Settings.selectedCharacter;
You can also see this code in action in the Variable Save and Variable Load nodes.
Variables set in the Settings class can be accessed and changed after export from within Xcode (iOS), Android Studio (Android), and Visual Studio 2017 (Windows). This can be useful for custom SDK integration, A/B testing, and more. Note: Windows Exe files cannot be edited post-export.
To access the Settings class in Android Studio, import PTPSettingsController. Then you can set variables with setSettingsValue(), continue on the above example: setSettingsValue(“selectedCharacter”, “‘Character1′”) or for an object variable, setSettingsValue(“myObjectVariable”, “{objectid: 123, myString:’my string here’}”).
To access the Settings class in Xcode or Visual Studio 2017, import BBRuntime/BBRuntimeShared.h and use getSettingsValue and setSettingsValue.
The Scene API handles aspects of game at the 2D/3D world level.
| Function | Description |
|---|---|
| addChild(entity) |
Adds the given Entity as a child of the Scene. |
| addLevel(name) |
Adds a level to the queue of levels to be displayed. The engine will look for a Level Section (aka Scene) with the given name and schedule it for adding. As soon as the engine needs a new level section to display, it will look for scheduled ones first. |
| addScoreCoin(value) |
Increases the user’s coins by the amount given in value. You can also pass a negative value to decrease the user’s coins. Note: A coin is typically something the user can spend, while a point is not. |
| addScorePoint(value) |
Increases the user’s score by the amount given in value. You can also pass a negative value to decrease the user’s points. Note: A coin is typically something the user can spend, while a point is not. |
| bestCoins() |
Returns the highest value of coins in the current 2D/3D World. |
| bestGlobalCoins() |
Returns the highest amount of coins in the entire game. |
| bestGlobalPoints() |
Returns the highest amount of points in the entire game. |
| bestPoints() |
Returns the highest amount of points in the current 2D/3D World. |
| camera() |
Returns the Camera of the Scene. |
| characters() |
Returns an array of Characters that are currently in the Scene. Remember, there are two kinds of assets that can be placed in a Scene: characters and objects. |
| clone(originalEntity) |
Clones originalEntity and returns a copy of it. Note that the cloned entity’s start() function will be ran when it is cloned. |
| create(name, parent) |
Creates a new Entity using the Asset with the specified name, Asset, or id. |
| createLinker(name) |
Creates and returns a new Linker with the given name (optional). |
| currentCoins() |
Returns the current amount of coins in the 2D/3D World. |
| currentGlobalCoins() |
Returns the current amount of coins in the overall game. |
| currentGlobalPoints() |
Returns the current amount of points in the overall game. |
| currentLevelName() |
Returns the name of the current level. |
| currentPoints() |
Returns the current amount of points in the 2D/3D World. |
| decreaseCoins(value) |
Decreases the user’s coins by the amount given in value. |
| decreaseCurrentPoints(value) |
Decreases the user’s points by the amount given in value. |
| decreaseTotalPoints(value) |
Decreases the given value from the total points in the current 2D/3D World. |
| entities() |
Returns an array of all Entities in the Scene. |
| find(name) |
Returns the array of Entities with the specified name. |
| findFirst(name) |
Returns the first Entity found in the scene with the given name. Useful if you’re sure you only have one Object in the Scene with that name. Returns null if the Entity is not found. |
| path() |
Returns Path object of the Scene. |
| physicsWorld() |
Returns the Scene’s PhysicsWorld object. For more information, look at the PhysicsWorld API reference page. |
| purgeLevel() |
Removes the current first level section. |
| pushNavigation(name) |
Activates a Navigation button with the given name on the current UI, as if the user touched it. |
| rayTest(from, to) |
Returns objects (AABBs) that collide with a ray between the two given Vec3 coordinates. The object returned has the properties bodies and sensors. |
| restart() |
Restarts the scene. |
| setBackgroundColor(r, g, b) |
Sets the background color of the Scene. |
| setGravity(x, y, z) |
Sets the gravity of the Scene. |
| setScorePoint(value) |
Sets the current points to the given value. Note: A coin is typically something the user can spend, while a point is not. |
| setShadowsEnabled(enabled) |
Use this function to turn shadows on or off globally. This can make your game run better on certain devices. Defaults to true (shadows on). |
| setSpeed(value) |
Sets the path speed. |
| shadowsEnabled() |
Returns whether shadows are enabled in the Scene. |
| speed() |
Returns the path speed. |
| totalCoins() |
Returns the total amount of coins in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not. |
| totalGlobalCoins() |
Returns the total amount of coins in the overall game. |
| totalGlobalPoints() |
Returns the total amount of points in the overall game. |
| totalPoints() |
Returns the total amount of points in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not. |
Adds the given Entity as a child of the Scene.
Entity entity – the Entity to add to the Scene.
Adds a level to the queue of levels to be displayed. The engine will look for a Level Section (aka Scene) with the given name and schedule it for adding. As soon as the engine needs a new level section to display, it will look for scheduled ones first.
string name – the name of the level to be added
// scheduling levels sections ahead of time. Keep in mind that all level sections will not be placed all at once, but based on current distance. function init(){ this.scene().addLevel('LevelM1'); this.scene().addLevel('LevelM2'); this.scene().addLevel('LevelM3'); this.scene().addLevel('LevelM2'); this.scene().addLevel('LevelM1'); }
Increases the user’s coins by the amount given in value. You can also pass a negative value to decrease the user’s coins. Note: A coin is typically something the user can spend, while a point is not.
number value – the number to increase the coins by.
log(this.scene().totalCoins()); // output: 5 this.scene().addScoreCoin(2); log(this.scene().totalCoins()); // output: 7
Increases the user’s score by the amount given in value. You can also pass a negative value to decrease the user’s points. Note: A coin is typically something the user can spend, while a point is not.
number value – the number to increase the score by.
this.scene().addScorePoint(45);
Returns the highest value of coins in the current 2D/3D World.
number the highest value of coins in the current 2D/3D World
Returns the highest amount of coins in the entire game.
number the highest amount of coins in the entire game
Returns the highest amount of points in the entire game.
number the highest amount of points in the entire game
Returns the highest amount of points in the current 2D/3D World.
number the highest amount of points in the current 2D/3D World
Returns the Camera of the Scene.
Camera the Camera object of the Scene
Returns an array of Characters that are currently in the Scene. Remember, there are two kinds of assets that can be placed in a Scene: characters and objects.
array an array of Entities with the Character label in the Scene.
this.scene().characters()[0].setPosition(0, 0, 0); //set the position of the first character returned by characters()
Clones originalEntity and returns a copy of it. Note that the cloned entity’s start() function will be ran when it is cloned.
Entity originalEntity – the Entity you’d like to copy
Entity the new entity
// clone the current entity
let entity = this.scene().findFirst("Cone");
let copiedEntity = this.scene().clone(entity);
this.scene.addChild(copiedEntity);
Creates a new Entity using the Asset with the specified name, Asset, or id. For using an id, see attribute().
string/Asset/number name – The asset the new Entity should use.
Scene/LevelSector parent – (Optional) the parent Entity or LevelSector
Entity The entity that was just created.
let ent = this.scene().create('Obstacle1'); ent.setPosition(0, 20, 0);
Creates and returns a new Linker with the given name (optional). After creation, use methods like setEntities(a, b) and setPosition(vec3) to set up your linker.
string the name of the linker (optional)
Linker the new linker
Returns the current amount of coins in the 2D/3D World.
number the current amount of coins in the 2D/3D World
Returns the current amount of coins in the overall game.
number the current amount of coins in the overall game
Returns the current amount of points in the overall game.
number the current amount of points in the overall game
Returns the name of the current level.
string the name of the current level
Returns the current amount of points in the 2D/3D World.
number the current amount of points in the 2D/3D World
Decreases the user’s coins by the amount given in value.
number value – the amount to decrease the coins by
Decreases the user’s points by the amount given in value.
number value – the amount to decrease the points by
Decreases the given value from the total points in the current 2D/3D World.
number value – the amount to decrease the total points by
Returns an array of all Entities in the Scene.
array – the entities in the Scene
Returns the array of Entities with the specified name.
string name – The name of the Entity to be searched for.
array The array of Entities which match that name.
let ents = this.scene().find('myObstacle'); for(let i = 0; i < ents.length; i++){ // increase the y position of each entity let ent = ents[i]; let pos = ent.position(); ent.setPosition(pos.x, pos.y + 1, pos.z); } let player = this.scene().find('Character')[0]; // use this shorthand if you're confident in only getting one result from the search
Returns the first Entity found in the scene with the given name. Useful if you’re sure you only have one Object in the Scene with that name. Returns null if the Entity is not found.
string name – The name of the Entity to be searched for.
Entity – the entity found with the given name
Returns Path object of the Scene.
ScenePath the Scene’s path object
Returns the Scene’s PhysicsWorld object. For more information, look at the PhysicsWorld API reference page.
PhysicsWorld the Scene’s physics world object
Removes the current first level section.
Activates a Navigation button with the given name on the current UI, as if the user touched it.
string name – the name of the button to push
Returns objects (AABBs) that collide with a ray between the two given Vec3 coordinates. Optionally takes a filter as the third parameter, such as: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”.
The object returned by this function has the properties {bodies, sensors} which are each arrays. The bodies and sensors objects have the properties {object, hitPoint}.
Vec3 from – the starting coordinate
Vec3 to – the ending coordinate
string filter – optional
Object with properties {bodies, sensors}.
// choose an object as the Selected Character with ray testing. pt is where the user tapped. let ray = cam.screenRay(pt); let rtst = this.scene().rayTest( ray.origin, ray.origin.add(ray.direction.scale(100)) ); for (let i = 0; i < rtst.bodies.length; ++i) { let hit = rtst.bodies[i]; Settings.selectedCharacter = hit.object.parentEntity().name(); return; }
Restarts the scene.
Sets the background color of the Scene.
number r – the red component of the color
number g – the green component of the color
number b – the blue component of the color
Sets the gravity of the Scene.
number x – the x-axis component of the new gravity
number y – the y-axis component of the new gravity
number z – the z-axis component of the new gravity
Sets the current points to the given value. Note: A coin is typically something the user can spend, while a point is not.
number value – the new score value
Use this function to turn shadows on or off globally. This can make your game run better on certain devices. Defaults to true (shadows on).
boolean enabled – turn on/off shadows globally.
Sets the path speed.
number value – the new path speed
Returns whether shadows are enabled in the Scene.
boolean – true if shadows are enabled, false if not.
Returns the path speed.
number the current path speed
Returns the total amount of coins in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.
number the total amount of coins in the current 2D/3D World
Returns the total amount of coins in the overall game.
number the total amount of coins in the overall game
Returns the total amount of points in the overall game.
number the total amount of points in the overall game
Returns the total amount of points in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.
number the total amount of points in the current 2D/3D World
System functions are used to retrieve or update data on the device that your game is running on.
| Static Function | Description |
|---|---|
| device() |
Returns the name of the device that the game is running on. |
| fps() |
Returns the Frames Per Second that the game is running currently. |
| frameSize() |
Returns the size of the game window on the device. |
| isMuteBackgroundSound() |
Returns true if the background sound is muted on this device, false if not. |
| isMuteEffectsSound() |
Returns true if effects are muted on this device, false if not. |
| save() |
Saves all that game data custom for the specific game. This also includes the Settings object. |
| screenSize() |
(Deprecated) Returns the designer size of the device. This refers to the frame in the UI editor, and the frame when you enter the game camera mode. |
| sendHapticFeedback(intensity) |
Triggers haptic feedback (device vibration). |
| setMuteBackgroundSound(value) |
Mutes or unmutes the background sound. |
| setMuteEffectsSound(value) |
Mutes or unmutes effects. |
Returns the name of the device that the game is running on.
string the identification name of the device that the game is running on. Will return “preview” in the preview window.
Returns the Frames Per Second that the game is currently running at.
number the current game FPS
Returns the size of the game window on the device.
Vec2 the size of the game window
let width = System.frameSize().x; let height = System.frameSize().y;
Returns true if the background sound is muted on this device, false if not.
boolean true if background sound is muted, false if not.
Returns true if effects are muted on this device, false if not.
boolean true if effects are muted, false if not.
Saves all that game data custom for the specific game. This also includes the Settings object.
(Deprecated) Returns the designer size of the device. This refers to the frame in the UI editor, and the frame when you enter the game camera mode. It returns a constant value: 1136×64for landscape and640×113 for portrait.
Vec2 The designer size of the device
Triggers haptic feedback (device vibration). The intensity variable will adjust the strength of the vibration on iPhone, but Android doesn’t have a concept of vibration strength, so a higher intensity variable will make the vibration last slightly longer.
number intensity – the intensity of the haptic feedback. Accepted values: 1, 2
Mutes or unmutes the background sound.
boolean value – true to mute background sound, false to unmute
Mutes or unmutes effects.
boolean value – true to mute effects, false to unmute
A Trail is a node that creates a trail behind the Entity.
| Function | Description |
|---|---|
| globalDepth() |
Returns the depth of the Trail in a 2D World. |
setColor(r, g, b, a) |
Sets the color of the trail. |
| setGlobalDepth(value) |
Sets the depth of the Trail in a 2D World. |
| setUpVector(value) |
Sets the “up vector” of the Trail. This changes the orientation of the tail, which is useful for 2D games. |
| upVector() |
Returns the “up vector” of the Trail. |
Returns the global depth of the Trail node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.
number – The global depth of the Trail
Sets the color of the trail.
number red – the red component of the new color
number green – the green component of the new color
number blue – the blue component of the new color
number alpha – (Optional) the opacity component of the new color, max 255
let trail = this.entity().component("Trail"); trail.setColor(193, 66, 66); // set the trail to be red
Sets the global depth of the Animation node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.
number value – The global depth of the Animation
Sets the “up vector” of the Trail. This changes the orientation of the tail, which is useful for 2D games. The range is 0-1 for the x, y, and z values.
Vec3 value – The new “up vector”
Returns the “up vector” of the Trail.
Vec3 – The Trail’s “up vector”
A Sub Scene is used to control an imported FBX asset. Check the Manual page for more information.
| Function | Description |
|---|---|
| animationSpeed(anim) |
This method takes a Keyframe Animation Model object and returns the animation’s speed. It will return 0 if the animation isn’t currently active. |
| animationTimeElapsed(anim) |
This method takes a Keyframe Animation Model object and returns the time elapsed as an active animation. The time elapsed is a value from 0-1, 1 being the completion of the animation. This method will return -1 if the animation isn’t currently active. |
| animationTransitionTime(anim) |
Returns the transition time of the animation. This is the time during which this animation and the next one will be blended in transition. |
| animations() |
Returns an array of the currently active Keyframe Animation Models. |
| attachEntity(joint, entity) |
This method is used to attach an Entity to a joint of your Sub Scene. For example, it can be used to attach an item to the hand of your character. |
| isAnimationPlaying(anim) |
Returns true if the given animation is playing, false if not. |
| jointRotation(name) |
Returns the rotation of the given joint in degrees. Joints are named within the 3D modeling software used to create the fbx file. |
| jointRotationQuat(name) |
Returns the rotation of the given joint in Quaternion. Joints are named within the 3D modeling software used to create the fbx file. |
| jointScale(name) |
Returns the scale of the given joint. Joints are named within the 3D modeling software used to create the fbx file. |
| jointTranslation(name) |
Returns the translation of the given joint. Joints are named within the 3D modeling software used to create the fbx file. |
| jointWeight(name) |
Returns the weight of the given joint. Joints are named within the 3D modeling software used to create the fbx file. |
| meshComponents() |
Returns an array containing all the 3D Models associated with the Sub Scene. |
| playAnimation(anim) |
Plays the given Keyframe Animation Model. Optionally takes a second parameter bool looped to make the animation loop. |
| position() |
Returns the position of the Sub Scene. The Sub Scene’s position is relative to its parent Entity. |
| rotation() |
Returns the rotation of the Sub Scene in degrees. The Sub Scene’s rotation is relative to its parent Entity. |
| rotationQuat() |
Returns the rotation of the Sub Scene in Quaternion. The Sub Scene’s rotation is relative to its parent Entity. |
| scale() |
Returns the scale of the Sub Scene. The Sub Scene’s scale is relative to its parent Entity. |
| setAnimationSpeed(anim, speed) |
This method sets the animation speed for the given Keyframe Animation Model. |
| setAnimationTransitionTime(anim, value) |
Sets the transition time of the animation. This is the time during which this animation and the next one will be blended in transition. |
| setColor(r, g, b, a) |
Sets the RGB color of the Sub Scene. Alpha is optional. |
| setJointRotation(name, value) |
Sets the rotation of the given joint in degrees. Joints are named within the 3D modeling software used to create the fbx file. |
| setJointRotationQuat(quat) |
Sets the rotation of the given joint in Quaternion. Joints are named within the 3D modeling software used to create the fbx file. |
| setJointScale(name, value) |
Sets the scale of the given joint. Joints are named within the 3D modeling software used to create the fbx file. The scale can be given in Vec3 or as setJointScale(name, x, y, z). |
| setJointTranslation(name, value) |
Sets the translation of the given joint. Joints are named within the 3D modeling software used to create the fbx file. The translation can be given in Vec3 or as setJointTranslation(name, x, y, z). |
| setJointWeight(name, value) |
Sets the weight of the given joint. Joints are named within the 3D modeling software used to create the fbx file. |
| setPosition(value) |
Sets the position of the Sub Scene. The Sub Scene’s position is relative to its parent Entity. The position can be given as Vec3 or as setPosition(x, y, z). |
| setRotation(value) |
Sets the rotation of the Sub Scene in degrees. The Sub Scene’s rotation is relative to its parent Entity. The rotation can be given as Vec3 or as setRotation(x, y, z). |
| setRotationQuat(quat) |
Sets the rotation of the Sub Scene in Quaternion. The Sub Scene’s rotation is relative to its parent Entity. |
| setScale(value) |
Sets the scale of the Sub Scene. The Sub Scene’s scale is relative to its parent Entity. The scale can be given as Vec3 or as setScale(x, y, z). |
| stopAnimation(anim) |
Stops the given Keyframe Animation Model. |
This method takes a Keyframe Animation Model object and returns the animation’s speed. It will return 0 if the animation isn’t currently active.
Keyframe Animation Model – the animation
number the speed of the animation
This method takes a Keyframe Animation Model object and returns the time elapsed as an active animation. The time elapsed is a value from 0-1, 1 being the completion of the animation. This method will return -1 if the animation isn’t currently active.
Keyframe Animation Model – the animation
number the time elapsed of the animation
Returns the transition time of the animation. This is the time during which this animation and the next one will be blended in transition.
Keyframe Animation Model – the animation
number the transition time
Returns an array of the currently active Keyframe Animation Models.
Array the array of currently active Keyframe Animation Models.
This method is used to attach an Entity to a joint of your Sub Scene. For example, it can be used to attach an item to the hand of your character.
string joint – the joint name
Entity entity – the entity
Returns true if the given animation is playing, false if not.
Keyframe Animation Model anim – the animation to check
boolean true if the animation is playing, false if not
Returns the rotation of the given joint in degrees. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Vec3 the rotation of the joint in degrees
Returns the rotation of the given joint in degrees. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Quaternion the rotation of the joint in Quaternion
Returns the scale of the given joint. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Vec3 the {x, y, z} scale of the joint
Returns the translation of the given joint. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Vec3 the translation of the joint
Returns the weight of the given joint. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
number the weight of the joint
Returns an array containing all the 3D Models associated with the Sub Scene.
Array – an array of 3D Models
number the weight of the joint
Plays the given Keyframe Animation Model. Optionally takes a second parameter bool looped to make the animation loop.
Keyframe Animation Model anim – the animation
bool looped – (optional) true if the animation should loop, false if not
Returns the position of the Sub Scene. The Sub Scene’s position is relative to its parent Entity.
Vec3 the {x, y, z} position of the Sub Scene
Returns the rotation of the Sub Scene in degrees. The Sub Scene’s rotation is relative to its parent Entity.
Vec3 the {x, y, z} rotation of the Sub Scene
Returns the rotation of the Sub Scene in Quaternion. The Sub Scene’s rotation is relative to its parent Entity.
Quaternion the rotation of the Sub Scene in Quaternion
Returns the scale of the Sub Scene. The Sub Scene’s scale is relative to its parent Entity.
Vec3 the {x, y, z} scale of the Sub Scene
This method sets the animation speed for the given Keyframe Animation Model.
Keyframe Animation Model anim – the animation
number speed – the speed
Sets the transition time of the animation. This is the time during which this animation and the next one will be blended in transition.
Keyframe Animation Model anim – the animation number value the transition time
Sets the RGB color of the Sub Scene. Alpha is optional.
number r – the red component of the color range 0-255
number g – the green component of the color range 0-255
number b – the blue component of the color range 0-255
number a – (optional) the alpha component of the color range 0-255
Sets the rotation of the given joint in degrees. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Vec3 value – the rotation in degrees
// example: rotate the models head to follow the players touch let subScene; let prev; let delta = new Vec2(0,0); function init(){ subScene = this.attribute('Scene')[0]; // the sub scene is connected to this node by reference this.enableTouch(true); } function touchBegan(point){ // save the point where the touch started prev = point; } component.touchBegan = touchBegan; function touchMove(point){ // calculate the distance between this touch point and the last one delta = new Vec2 ( delta.x + prev.x - point.x, delta.y + prev.y - point.y); prev = point; } component.touchMove = touchMove; function update(dt){ // change the rotation of the head joint based on the touch subScene.setJointRotation('head', new Vec3(-delta.x,0,-delta.y)); }
Sets the rotation of the given joint in Quaternion. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
Quaternion value – the rotation in Quaternion
Sets the scale of the given joint. Joints are named within the 3D modeling software used to create the fbx file. The scale can be given in Vec3 or as setJointScale(name, x, y, z).
string name – the name of the joint
Vec3 value – the {x, y, z} scale of the joint
Sets the translation of the given joint. Joints are named within the 3D modeling software used to create the fbx file. The translation can be given in Vec3 or as setJointTranslation(name, x, y, z).
string name – the name of the joint
Vec3 value – the {x, y, z} translation of the joint
Sets the weight of the given joint. Joints are named within the 3D modeling software used to create the fbx file.
string name – the name of the joint
number value – the weight of the joint
Sets the position of the Sub Scene. The Sub Scene’s position is relative to its parent Entity. The position can be given as Vec3 or as setPosition(x, y, z).
Vec3 value – the position of the Sub Scene
Sets the rotation of the Sub Scene in degrees. The Sub Scene’s rotation is relative to its parent Entity. The rotation can be given as Vec3 or as setRotation(x, y, z).
Vec3 value – the rotation of the Sub Scene
Sets the rotation of the Sub Scene in Quaternion. The Sub Scene’s rotation is relative to its parent Entity.
Quaternion quat – the rotation of the Sub Scene
Sets the scale of the Sub Scene. The Sub Scene’s scale is relative to its parent Entity. The scale can be given as Vec3 or as setScale(x, y, z).
Vec3 value – the {x, y, z} scale of the Sub Scene
Stops the given Keyframe Animation Model.
Keyframe Animation Model anim – the animation to stop
These methods adjust the physics settings from the world menu. For more information, see the world options manual.
| Function | Description |
|---|---|
| checkSphereCollision(position, radius, filter) |
Checks if anything collides with the sphere at the given position with the given radius. Filter has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, value from Asset Attribute, Entity. |
| disableDeactivation(value) |
When a dynamic body is not moved for a few seconds, it will go into sleep mode. In sleep mode, the physics engine skips the body’s simulation. Sleep mode can be disabled with this method. By default, sleep mode is be enabled. |
| getSphereCollisions(position, radius, filter) |
Returns colliders with a sphere at the given position with the given radius. Filter has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, value from Asset Attribute, Entity. |
| rayTest(from, to, filter) |
Returns physics bodies that collide with a ray between the two given Vec3 coordinates. The object returned has the properties bodies and sensors. Optional filter has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, value from Asset Attribute, Entity. |
| setSubSteps(value) |
Sets the value of the sub steps setting in the world options menu. |
| setTimeWarp(value) |
Sets the value of the time warp setting in the world options menu. |
| subSteps() |
Returns the value of sub steps from the world options menu. |
| timeWarp() |
Returns the value of time warp from the world options menu. |
Checks if anything collides with the sphere at the given position with the given radius. Filter has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, value from Asset Attribute, entity.
Vec3 position – the position of the sphere
number radius – the radius of the sphere
string filter – / AssetModel / Entity / optional: “kAll” the filter of items to look for
boolean true if there is a collision, false if not
When a dynamic body is not moved for a few seconds, it will go into sleep mode. In sleep mode, the physics engine skips the body’s simulation. Sleep mode can be disabled with this method. By default, sleep mode is be enabled.
boolean value – true to disable deactivation, false to enable it
Returns colliders with a sphere at the given position with the given radius. One use case for this method would be interating through all the colliders within a sphere and adding damage to them for an explosion. Filter has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kGround”, value from Asset Attribute, entity.
Vec3 position – the position of the sphere
number radius – the radius of the sphere
string filter – / AssetModel filter / Entity filter the filter of items to look for
Object with properties {bodies, sensors} – an array of bodies and an array of sensors within the sphere
Returns physics bodies that collide with a ray between the two given Vec3 coordinates. Optionally takes a filter parameter which has these possible values: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, value from Asset Attribute, entity.
The object returned by this function has the properties {bodies, sensors} which are each arrays. The bodies and sensors objects have the properties {object, hitPoint}.
Vec3 from – the starting coordinate
Vec3 to – the ending coordinate
string filter – / AssetModel filter / Entity filter the filter of items to look for
Object with properties {bodies, sensors}.
// choose an object as the Selected Character with ray testing. pt is where the user tapped. let ray = cam.screenRay(pt); let rtst = this.scene().physicsWorld().rayTest( ray.origin, ray.origin.add(ray.direction.scale(100)) ); for (let i = 0; i < rtst.bodies.length; ++i) { let hit = rtst.bodies[i]; Settings.selectedCharacter = hit.object.parentEntity().name(); return; }
Sets the value of the sub steps setting in the world options menu.
number value – the new sub steps value
Sets the value of the time warp setting in the world options menu.
number value – the new time warp value
Returns the value of sub steps from the world options menu.
number the sub step value
Returns the value of time warp from the world options menu.
number the time warp value
The Buildbox JavaScript panel allows you to link a custom node script to a JavaScript file on your computer, allowing you to use an external text editor to update and change your custom node script. Whether you update the file in the Buildbox JavaScript panel or external editor, it will be updated in both locations
To access the JavaScript panel, on an asset’s node map, double-click a node or click its edit icon.
To link a file to the JavaScript panel, click Link File 
at the bottom-right of the JavaScript panel, and depending on whether you need to export the file from or import it to Buildbox, choose one of the following procedures below.
After you link a JavaScript file to a node, click the 
icon at the bottom right of the JavaScript panel to view the following options:
| Option | Description |
| Open Externally | Opens the linked JavaScript file using your default script editor. |
| Show in Folder | Opens the folder that contains the linked JavaScript file. |
| Export to File & Link | Creates and saves a JavaScript file that contains your custom node script locally on your computer and links the file to the Buildbox JavaScript panel. |
| Import from File & Link | Imports and creates a link to a JavaScript file from your computer to the Buildbox JavaScript panel. |
| Unlink | Unlinks the JavaScript file from the Buildbox JavaScript panel. The updates will no longer be synchronized. |
By clicking ‘Subscribe’, you agree to receive updates, game design tips and other marketing messages from Buildbox Inc. You can unsubscribe from marketing emails at any time (e.g. by clicking the unsubscribe link in emails). View Privacy Policy.
©2025 AppOnboard, Inc | Privacy Policy | Terms