Physics World

These methods adjust the physics settings from the world menu. For more information, see the world options manual.

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.

Parameters

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

Returns

boolean true if there is a collision, false if not

↑ Back to top

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.

Parameters

boolean value – true to disable deactivation, false to enable it

↑ Back to top

getSphereCollisions(position, radius, filter)

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.

Parameters

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

Returns

Object with properties {bodies, sensors} – an array of bodies and an array of sensors within the sphere

↑ Back to top

rayTest(from, to, filter)

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}.

Parameters

Vec3 from – the starting coordinate
Vec3 to – the ending coordinate
string filter – / AssetModel filter / Entity filter the filter of items to look for

Returns

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;
    }
    

↑ Back to top

setSubSteps(value)

Sets the value of the sub steps setting in the world options menu.

Parameters

number value – the new sub steps value

↑ Back to top

setTimeWarp(value)

Sets the value of the time warp setting in the world options menu.

Parameters

number value – the new time warp value

↑ Back to top

subSteps()

Returns the value of sub steps from the world options menu.

Returns

number the sub step value

↑ Back to top

timeWarp()

Returns the value of time warp from the world options menu.

Returns

number the time warp value

↑ Back to top

Scene Path

The scene path is the path through the levels of your game. It is created using the start and end points on each level. To access your game’s Path object, use this.scene().path().

anchorAtPosition(value)

Returns the anchor position and rotation at the given path position.

Parameters

number value – the path position

Returns

Vec3 the {x, y, z} anchor position of the path at the given position

↑ Back to top

anchorPosition()

Returns the current anchor position of the path.

Returns

Vec3 the {x, y, z} anchor position of the path

↑ Back to top

anchorRotationQuat()

Returns the current anchor rotation of the path in quaternion.

Returns

quaternion the anchor rotation of the path

↑ Back to top

pathPosition()

Returns the current path position. The path position is simply how far along the path the game has moved.

Returns

number the current position along the path

↑ Back to top

pathSize()

Returns the path size.

Returns

Vec2 the {x, y} path size

↑ Back to top

pathTangent()

Returns the current path tangent.

Returns

Vec3 the {x, y, z} current path tangent

↑ Back to top

positionOnPath(entity)

Takes an entity or 3D world position and returns the position along the game path.

Parameters

Entity entity – the entity to find the game path position of or Vec3 pos a 3D world position

Returns

number the position on the game path of the given entity or 3D world position

↑ Back to top

setAutoPositionUpdate(value)

Enables/disables auto path update. If it is disabled, levels will not be created automatically along the game path.

Parameters

boolean value – true to enable auto position update, false to disable

↑ Back to top

setPathPosition(value)

Sets the current path position.

Parameters

number value – the new path position

↑ Back to top

Settings

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.

System

System functions are used to retrieve or update data on the device that your game is running on.

device()

Returns the name of the device that the game is running on.

Returns

string the identification name of the device that the game is running on. Will return “preview” in the preview window.

↑ Back to top

fps()

Returns the Frames Per Second that the game is currently running at.

Returns

number the current game FPS

↑ Back to top

frameSize()

Returns the size of the game window on the device.

Returns

Vec2 the size of the game window

let width = System.frameSize().x;
let height = System.frameSize().y;

↑ Back to top

isMuteBackgroundSound()

Returns true if the background sound is muted on this device, false if not.

Returns

boolean true if background sound is muted, false if not.

↑ Back to top

isMuteEffectsSound()

Returns true if effects are muted on this device, false if not.

Returns

boolean true if effects are muted, false if not.

↑ Back to top

save()

Saves all that game data custom for the specific game. This also includes the Settings object.

↑ Back to top

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. It returns a constant value: 1136×64for landscape and640×113 for portrait.

Returns

Vec2 The designer size of the device

↑ Back to top

sendHapticFeedback(intensity)

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.

Parameters

number intensity – the intensity of the haptic feedback. Accepted values: 1, 2

↑ Back to top

setMuteBackgroundSound(value)

Mutes or unmutes the background sound.

Parameters

boolean value – true to mute background sound, false to unmute

↑ Back to top

setMuteEffectsSound(value)

Mutes or unmutes effects.

Parameters

boolean value – true to mute effects, false to unmute

↑ Back to top

Quaternion

The Quaternion class represents a quaternion. Quaternions are used to describe rotation in 3D space. Quaternion contains several helpful static functions, which can be called like this: Quaternion.multiply(quat1, quat2). Objects of the Quaternion class have 4 number properties: x, y, z, and w.

inverse()

Inverts the quaternion.

Returns

boolean true if the inversion was successful, false if not

↑ Back to top

toEuler()

Converts from Quaternion to Euler angles (in degrees).

Returns

Vec3 the {x, y, z} yaw, pitch, and roll Euler angles

↑ Back to top

angle(quat1, quat2)

Returns the angle between two Quaternions.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion

Returns

number – the resulting angle

↑ Back to top

fromEuler(pitch, yaw, roll)

Converts from Euler angles to Quaternion.

Parameters

number pitch – the x-axis component
number yaw – the y-axis component
number roll – the z-axis component

Returns

Quaternion the resulting Quaternion

↑ Back to top

lerp(quat1, quat2, t)

Interpolates between two quaternions using linear interpolation and returns the result. Less accurate than slerp() but more efficient. The interpolation curve for linear interpolation between quaternions gives a straight line in quaternion space.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion
number t the interpolation coefficient

Returns

Quaternion the resulting Quaternion

↑ Back to top

lookAt(lookStart, lookEnd)

Returns a Quaternion oriented to the given 3D coordinates.

Parameters

Vec3 lookStart – the first set of 3D coordinates
Vec3 lookEnd – the second set of 3D coordinates

Returns

Quaternion – the resulting Quaternion

let _target;

function start(){
    _target = this.scene().findFirst("Cube");
}

function update(dt){
    // rotate the projectile to face the target
    let currentQuat = this.entity().rotationQuat();
    let nextQuat = Quaternion.lookAt(this.entity().position(), _target.position());
    nextQuat = Quaternion.slerp(currentQuat, nextQuat, 0.5);
    this.entity().setRotationQuat(nextQuat);

    // move the projectile toward the target in an arcing movement
    let mat = Mat4.createRotation(nextQuat);
    let forward = Mat4.transformPoint(mat, new Vec3(1, 1, -1));
    let curPos = this.entity().position();
    this.entity().setPosition(
        curPos.x + 0.1 * forward.x,
        curPos.y + 0.1 * forward.y,
        curPos.z + 0.1 * forward.z);
}

↑ Back to top

multiply(quat1, quat2)

Multiplies the given Quaternions and returns the result.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion

Returns

Quaternion – the resulting Quaternion

↑ Back to top

slerp(quat1, quat2, alpha)

Interpolates between two Quaternions using spherical spline interpolation and returns the result. More accurate than lerp() but less efficient. Spherical spline interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion
number t the interpolation coefficient

Returns

Quaternion the resulting Quaternion

↑ Back to top

Trail

A Trail is a node that creates a trail behind the Entity.

globalDepth()

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.

Returns

number – The global depth of the Trail

↑ Back to top

setColor(r, g, b, a)

Sets the color of the trail.

Parameters

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

↑ Back to top

setGlobalDepth(value)

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.

Parameters

number value – The global depth of the Animation

↑ Back to top

setUpVector(value)

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.

Parameters

Vec3 value – The new “up vector”

↑ Back to top

upVector()

Returns the “up vector” of the Trail.

Returns

Vec3 – The Trail’s “up vector”

↑ Back to top

Vec2

The Vec2 class represents a vector in 2D space. Here is how you initialize one and get values from it.

let pos = new Vec2(0, 1);
log(pos); // output: {0, 1}
log(pos.x); // output: 0

Here’s more examples of its usage.

let a = new Vec2(1, 3);
let b = new Vec2(3, 7);
let sum = a.add(b); 
let length = a.length();
let sqrLength = a.sqrLength(); //squared length
let normalized = a.normalize();
let diff = a.sub(b);
let dotProduct = a.dot(b);
let distanceBetweenPoints = a.distance(b);

let factor = 2;
let scaled = a.scale(factor); 

let alpha = 0.5;
let lerp = a.lerp(b, alpha); 

let pivot = new Vec2(3,1);
let angle = Math.PI/4;
let rotated = rotateByAngle(pivot, angle);

let c = new Vec3(101, null);
let cxe = c.isXEmpty(); //false
let cye = c.isYEmpty(); //true

Vec3

The Vec3 class represents a vector in 3D space. Here is how you initialize one and get values from it.

let pos = new Vec3(2, 0, 0);
log(pos); // output: {2, 0, 0}
log(pos.x); // output: 2

Here’s more examples of its usage.

let a = new Vec3(1, 3, 5);
let b = new Vec3(3, 7, 9);
log(a);
let sum = a.add(b); 
let length = a.length();
let sqrLength = a.sqrLength(); //squared length
let normalized = a.normalize();
let diff = a.sub(b);
let dotProduct = a.dot(b);
let crossProduct = a.cross(b);
let distanceBetweenPoints = a.distance(b);

let factor = 2;
let scaled = a.scale(factor); 

let alpha = 0.5;
let lerp = a.lerp(b, alpha); 

let c = new Vec3(101, null, null);
let cxe = c.isXEmpty(); //false
let cye = c.isYEmpty(); //true
let cze = c.isZEmpty(); //true