Scene

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.

addChild(entity)

Adds the given Entity as a child of the Scene.

Parameters

Entity entity – the Entity to add to the Scene.

↑ Back to top

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.

Parameters

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

↑ Back to top

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.

Parameters

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

↑ Back to top

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.

Parameters

number value – the number to increase the score by.

  this.scene().addScorePoint(45);

↑ Back to top

bestCoins()

Returns the highest value of coins in the current 2D/3D World.

Returns

number the highest value of coins in the current 2D/3D World

↑ Back to top

bestGlobalCoins()

Returns the highest amount of coins in the entire game.

Returns

number the highest amount of coins in the entire game

↑ Back to top

bestGlobalPoints()

Returns the highest amount of points in the entire game.

Returns

number the highest amount of points in the entire game

↑ Back to top

bestPoints()

Returns the highest amount of points in the current 2D/3D World.

Returns

number the highest amount of points in the current 2D/3D World

↑ Back to top

camera()

Returns the Camera of the Scene.

Returns

Camera the Camera object of the Scene

↑ Back to top

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.

Returns

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()

↑ Back to top

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.

Parameters

Entity originalEntity – the Entity you’d like to copy

Returns

Entity the new entity

// clone the current entity
let entity = this.scene().findFirst("Cone");
let copiedEntity = this.scene().clone(entity);
this.scene.addChild(copiedEntity);

↑ Back to top

create(name, parent)

Creates a new Entity using the Asset with the specified name, Asset, or id. For using an id, see attribute().

Parameters

string/Asset/number name – The asset the new Entity should use.
Scene/LevelSector parent – (Optional) the parent Entity or LevelSector

Returns

Entity The entity that was just created.

let ent = this.scene().create('Obstacle1');
ent.setPosition(0, 20, 0);

↑ Back to top

createLinker()

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.

Parameters

string the name of the linker (optional)

Returns

Linker the new linker

↑ Back to top

currentCoins()

Returns the current amount of coins in the 2D/3D World.

Returns

number the current amount of coins in the 2D/3D World

↑ Back to top

currentGlobalCoins()

Returns the current amount of coins in the overall game.

Returns

number the current amount of coins in the overall game

↑ Back to top

currentGlobalPoints()

Returns the current amount of points in the overall game.

Returns

number the current amount of points in the overall game

↑ Back to top

currentLevelName()

Returns the name of the current level.

Returns

string the name of the current level

↑ Back to top

currentPoints()

Returns the current amount of points in the 2D/3D World.

Returns

number the current amount of points in the 2D/3D World

↑ Back to top

decreaseCoins(value)

Decreases the user’s coins by the amount given in value.

Parameters

number value – the amount to decrease the coins by

↑ Back to top

decreaseCurrentPoints(value)

Decreases the user’s points by the amount given in value.

Parameters

number value – the amount to decrease the points by

↑ Back to top

decreaseTotalPoints(value)

Decreases the given value from the total points in the current 2D/3D World.

Parameters

number value – the amount to decrease the total points by

↑ Back to top

entities()

Returns an array of all Entities in the Scene.

Returns

array – the entities in the Scene

↑ Back to top

find(name)

Returns the array of Entities with the specified name.

Parameters

string name – The name of the Entity to be searched for.

Returns

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

↑ Back to top

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.

Parameters

string name – The name of the Entity to be searched for.

Returns

Entity – the entity found with the given name

↑ Back to top

path()

Returns Path object of the Scene.

Returns

ScenePath the Scene’s path object

↑ Back to top

physicsWorld()

Returns the Scene’s PhysicsWorld object. For more information, look at the PhysicsWorld API reference page.

Returns

PhysicsWorld the Scene’s physics world object

↑ Back to top

purgeLevel()

Removes the current first level section.

↑ Back to top

pushNavigation(name)

Activates a Navigation button with the given name on the current UI, as if the user touched it.

Parameters

string name – the name of the button to push

↑ Back to top

rayTest(from, to)

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

Parameters

Vec3 from – the starting coordinate
Vec3 to – the ending coordinate
string filter – optional

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().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

restart()

Restarts the scene.

↑ Back to top

setBackgroundColor(r, g, b)

Sets the background color of the Scene.

Parameters

number r – the red component of the color
number g – the green component of the color
number b – the blue component of the color

↑ Back to top

setGravity(x, y, z)

Sets the gravity of the Scene.

Parameters

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

↑ Back to top

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.

Parameters

number value – the new score value

↑ Back to top

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

Parameters

boolean enabled – turn on/off shadows globally.

↑ Back to top

setSpeed(value)

Sets the path speed.

Parameters

number value – the new path speed

↑ Back to top

shadowsEnabled()

Returns whether shadows are enabled in the Scene.

Returns

boolean – true if shadows are enabled, false if not.

↑ Back to top

speed()

Returns the path speed.

Returns

number the current path speed

↑ Back to top

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.

Returns

number the total amount of coins in the current 2D/3D World

↑ Back to top

totalGlobalCoins()

Returns the total amount of coins in the overall game.

Returns

number the total amount of coins in the overall game

↑ Back to top

totalGlobalPoints()

Returns the total amount of points in the overall game.

Returns

number the total amount of points in the overall game

↑ Back to top

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.

Returns

number the total amount of points in the current 2D/3D World

↑ Back to top

About Buildbox

Buildbox is the world's first software that truly allows anyone to create amazing games regardless of technical skill. Due to its unique user interface, making games becomes a fluid process that doesn't require any scripting, programming or software design experience.

STAY UP TO DATE

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.