December 12, 2019
0

Physics Component – API Reference

By |

Physics Component

This component is used for processing physics. You can find the physics menu in the Start node. To access these functions, you can use this.entity().physics().

Function Description
activateBody()

When the body type is “kDynamic” and “Always Active” is disabled, the body will become inactive after a short period of time. This function activates it again.
affectedAsset()

Returns the affected asset set for the physics component. This decides what type of assets this body can interact with.
angularDamping()

Returns the angular damping factor. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.
angularVelocity()

Returns the current angular velocity value of the object.
clearVelocities()

Sets angular and linear velocity to zero.
collisionData()

Returns an object containing collision data for this entity. Optionally an Entity can be passed to get data about one entity specifically.
collisionGroup()

Returns the collision group of the object.
disableDeactivation(value)

A body will become inactive after a short period of time if left alone. If you disable deactivation, the body will always stay active. This is recommended for Linker entities.
friction()

Returns the body’s friction value.
gravity()

Returns the gravity value affecting the entity. If it hasn’t been adjusted for this entity, this method will return the gravity value of the Scene.
hasCollision(entity)

Returns true if the given entity collides with the current one.
isPhysics()

Returns true if physics is enabled on this entity, false if not.
linearDamping()

Returns the linear damping factor. Linear damping simulates drag; the higher the value, the more this entity will resist translation.
linearFactor()

Returns “position factor” of the physics component. The linear factor determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
linearVelocity()

Returns the current linear velocity value of the entity.
mass()

Returns the mass value of the entity. This defaults to 1.
mesh()

Returns the collision shape mesh if assigned. Null if a mesh is not being used as the collision shape.
parentEntity()

Returns the entity that this physics component belongs to.
predictedPosition(time)

Returns the predicted position of the body based on the given time.
rebuildShape()

Call this function to update the physics collision shape. This should be done if you change the shape or scale of your Entity in code.
restitution()

Returns the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.
setAffectedAsset(value)

Sets the affected asset for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.
setAngularDamping(value)

Sets the angular damping factor, range 0-1. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.
setAngularFactor(x, y, z)

Sets the “rotation factor” of the object. This determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
setAngularVelocity(x, y, z)

Sets the angular velocity value of the object.
setCollisionGroup(group)

Set the collision group of the entity.
setCreated(value)

Enables/disables everything that is connected to the “Start” node.
setFriction(value)

Sets the friction value for the body.
setGravity(x, y, z)

Sets gravity value affecting this entity. This will override the gravity value in the scene, and will not affect other objects.
setLinearDamping(value)

Sets the linear damping factor, range 0-1. Linear damping simulates drag; the higher the value, the more this entity will resist translation.
setLinearFactor(x, y, z)

Sets the “position factor” of the object. This determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
setLinearVelocity(x, y, z)

Sets the linear velocity of the entity.
setMass(value)

Sets the mass of the entity. A mass of 0 will not be affected by gravity.

setMesh(mesh)

Sets the mesh of the collision shape from a MeshModel script attribute.
setMesh(name)

Sets the mesh of the collision shape based on the name of the mesh.
setPhysics(value)

Enables/disables physics.
setRestitution(value)

Sets the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.
setShapePosition(x, y, z)

Sets the collision shape position of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeRotation(x, y, z)

Sets the collision shape rotation of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeScale(x, y, z)

Sets the collision shape scale of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeType(type)

Sets the shape type. Highly recommended to use “kHullShape” over “kMeshShape”.
setType(value)

Sets the type of the physics body.
shapePosition()

Returns the position of the collision shape.
shapeRotation()

Returns the rotation of the collision shape.
shapeScale()

Returns the scale of the collision shape.
shapeType()

Returns the shape type of the collision shape.
type()

Returns the type of the physics body.

activateBody()

When the body type is “kDynamic” and “Always Active” is disabled, the body will get inactive after a short period of time. This function activates it back.

↑ Back to top

affectedAsset()

Returns the affected asset set for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.

Returns

string / Asset – the asset or group of assets this body can interact with

↑ Back to top

angularDamping()

Returns the angular damping factor. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.

Returns

number – the angular damping factor, range 0-1

↑ Back to top

angularFactor()

Returns the “rotation factor” of the physics component. The angular factor determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Returns

Vec3 the {x, y, z} components of the angular factor.

↑ Back to top

angularVelocity()

Returns the current angular velocity value of the object.

Returns

Vec3 the {x, y, z} components of the angular velocity.

↑ Back to top

clearVelocities()

Sets angular and linear velocity to zero.

↑ Back to top

collisionData()

Returns an object containing collision data for this entity. Optionally an Entity can be passed to get data about one entity specifically.

The returned object will have these properties (Data types in parenthesis). Keep in mind that a property is accessed like this: this.entity().physics().collisionData().totalImpulse;.

entity – the entity that’s being collided with (Entity)
totalImpulse – the total impulse from all collision points (number)
collisionPoints – an array of objects containing data about each point of collision (array of Objects). Each object in the array has these properties:
– impulse – the impulse from the collision point (number)
– normal – the normal of the collision point (Vec3)
– position – the position of the collision point (Vec3)

Parameters

Entity (optional) an entity to check collision data with the current entity

Returns

Object – data object containing the information listed above

↑ Back to top

collisionGroup()

Returns the collision group of the object.

Returns

string possible values: kNone, kCharacter, kEnemy, kPlatform, kCoin

↑ Back to top

disableDeactivation(value)

A body will become inactive after a short period of time if left alone. If you disable deactivation, the body will always stay active. This is recommended for Linker entities.

Parameters

boolean value – true to keep the entity always active, false to allow it to become inactive as normal

↑ Back to top

friction()

Returns the body’s friction value. This can also be seen in the Start node unless altered at runtime.

Returns

number the friction value of the body

↑ Back to top

gravity()

Returns the gravity value affecting the entity. If it hasn’t been adjusted for this entity, this method will return the gravity value of the Scene.

Returns

number the current gravity value of the entity.

↑ Back to top

hasCollision(entity)

Returns true if the given entity collides with the current one.

Parameters

Entity entity the entity to check for a collision with

Returns

boolean true if the entities are colliding, false if not.

↑ Back to top

isPhysics()

Returns true if physics is enabled, false if not.

Returns

boolean true if physics is enabled, false if not.

↑ Back to top

linearDamping()

Returns the linear damping factor. Linear damping simulates drag; the higher the value, the more this entity will resist translation. Default value: 0

Returns

number the linear damping, range 0-1.

↑ Back to top

linearFactor()

Returns “position factor” of the physics component. The linear factor determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Returns

Vec3 the {x, y, z} linear factor.

↑ Back to top

linearVelocity()

Returns the current linear velocity value of the entity.

Returns

Vec3 the {x, y, z} linear velocity of the entity.

↑ Back to top

mass()

Returns the mass value of the entity. This defaults to 1.

Returns

number the mass of the entity

↑ Back to top

mesh()

Returns the collision shape mesh if assigned. Null if a mesh is not being used as the collision shape.

Returns

MeshModel the object of the collision shape mesh

↑ Back to top

parentEntity()

Returns the entity that this physics component belongs to.

Returns

Entity the parent entity of the physics component

↑ Back to top

predictedPosition(time)

Returns the predicted position of the body based on the given time.

Parameters

number time – the number of seconds from now that you’d like to predict the position of the entity

Returns

Vec3 entity’s predicted {x, y, z} position after time based on its current Velocity.

↑ Back to top

rebuildShape()

Call this function to update the physics collision shape. This should be done if you change the shape or scale of your Entity in code.

↑ Back to top

restitution()

Returns the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.

Returns

number the “Bounce” value of the physics component

↑ Back to top

setAffectedAsset(value)

Sets the affected asset for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.

Parameters

string value / Asset value – the asset or group of assets this body can interact with

↑ Back to top

setAngularDamping()

Sets the angular damping factor, range 0-1. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.

Parameters

number value – the angular damping factor

↑ Back to top

setAngularFactor(x, y, z)

Sets the “rotation factor” of the object. This determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Parameters

number x – the x component of the new angular factor
number y – the y component of the new angular factor
number z – the z component of the new angular factor

↑ Back to top

setAngularVelocity(x, y, z)

Sets the angular velocity value of the object.

Parameters

number x – the x component of the new angular velocity
number y – the y component of the new angular velocity
number z – the z component of the new angular velocity

↑ Back to top

setCollisionGroup(group)

Set the collision group of the entity.

Parameters

string group – possible values: kNone, kCharacter, kEnemy, kPlatform, kCoin

↑ Back to top

setCreated(value)

Enables/disables everything that is connected to the “Start” node.

Parameters

boolean value – true to enable, false to disable

↑ Back to top

setFriction(value)

Sets the friction value for the body. This can also be changed in the Start node.

Parameters

number value – the new friction value

↑ Back to top

setGravity(x, y, z)

Sets gravity value affecting this entity. This will override the gravity value in the scene, and will not affect other objects.

Parameters

number x – the x component of the new gravity
number y – the y component of the new gravity
number z – the z component of the new gravity

↑ Back to top

setLinearDamping(value)

Sets the linear damping factor, range 0-1. Linear damping simulates drag; the higher the value, the more this entity will resist translation.

Parameters

number value – the linear damping factor

↑ Back to top

setLinearFactor(x, y, z)

Sets the “position factor” of the object. This determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Parameters

number x – the x component of the new linear factor
number y – the y component of the new linear factor
number z – the z component of the new linear factor

↑ Back to top

setLinearVelocity(x, y, z)

Sets the linear velocity of the entity.

Parameters

number x – the x component of the new linear velocity
number y – the y component of the new linear velocity
number z – the z component of the new linear velocity

↑ Back to top

setMass(value)

Sets the mass of the entity. A mass of 0 will not be affected by gravity.

Parameters

number value – the new mass of the entity

↑ Back to top

setMesh(mesh)

Sets the mesh of the collision shape from a MeshModel script attribute.

Parameters

MeshModel mesh – the new mesh for the collision shape

↑ Back to top

setMesh(name)

Sets the mesh of the collision shape based on the name of the mesh.

Parameters

string name – the new mesh for the collision shape

↑ Back to top

setPhysics(value)

Enables/disables physics.

Parameters

boolean value – true to enable physics, false to disable

↑ Back to top

setRestitution(value)

Sets the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.

Parameters

number value – the new “Bounce” value

↑ Back to top

setShapePosition(x, y, z)

Sets the collision shape position of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape position
number y – the y component of the new shape position
number z – the z component of the new shape position

↑ Back to top

setShapeRotation(x, y, z)

Sets the collision shape rotation of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape rotation
number y – the y component of the new shape rotation
number z – the z component of the new shape rotation

↑ Back to top

setShapeScale(x, y, z)

Sets the collision shape scale of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape scale
number y – the y component of the new shape scale
number z – the z component of the new shape scale

↑ Back to top

setShapeType(type)

Sets the shape type. Highly recommended to use “kHullShape” over “kMeshShape”.

Parameters

string type – Possible values: “kCubeShape”, “kSphereShape”, “kCylinderShape”, “kHullShape”, “kMeshShape”.

↑ Back to top

setType(value)

Sets the type of the physics body.
kStatic – body is static and will never be moved but other objects can collide with it. Used for ground or walls in your game.
kDynamic – body is fully dynamic and can bounce off of other object and be affected by gravity.
kKinematic – body can be moved by directly setting position and rotation and will not react to other bodies collision or gravity. Used as obstacles or elevator platforms.
kNone – no physics enabled

Parameters

string type – Possible values: kStatic, kDynamic, kKinematic, kNone

↑ Back to top

shapePosition()

Returns the position of the collision shape.

Returns

Vec3 the {x, y, z} position of the collision shape

↑ Back to top

shapeRotation()

Returns the rotation of the collision shape.

Returns

Vec3 the {x, y, z} rotation of the collision shape

↑ Back to top

shapeScale()

Returns the scale of the collision shape.

Returns

Vec3 the {x, y, z} scale of the collision shape

↑ Back to top

shapeType()

Returns the shape type of the collision shape.

Returns

string Possible values: “kCubeShape”, “kSphereShape”, “kCylinderShape”, “kHullShape”, “kMeshShape”.

↑ Back to top

type()

Returns the type of the physics body. kStatic – body is static and will never be moved but other objects can collide with it. Used for ground or walls in your game.
kDynamic – body is fully dynamic and can bounce off of other object and be affected by gravity.
kKinematic – body can be moved by directly setting position and rotation and will not react to other bodies collision or gravity. Used as obstacles or elevator platforms.
kNone – no physics enabled

Returns

string Possible values: kStatic, kDynamic, kKinematic, kNone

let ph = this.entity().physics();
if(ph && ph.type() == 'kDynamic'){
  //Dynamic mode
}else{
  //Static or Kinematic mode
}

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

Camera – API Reference

By |

Camera

The Camera object can be aquired by calling this.scene().camera(). With it you can manipulate the attributes of your game’s camera.

Function Description
farPlane()

Returns the far render distance of the camera.
fieldOfView()

Returns the field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.
followForce()

Returns the follow force of the camera. This determines how much ‘force’ the camera follows an object with.
followOffset()

Returns the follow offset of the camera. The camera will follow the object from this many units away.
followThreshold()

Returns the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving.
nearPlane()

Returns the near render distance of the camera. This is the minimum distance from the camera that an object will be rendered.
orthoScale()

Returns the orthographic scale of the camera (only works if camera projection is orthographic)
position()

Returns the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will return {0, 0, 0} until the relative position is changed with setPosition(), even if you adjust the camera position in the settings.
projection()

Returns the projection type of the camera. There are only two possibilities, kPerspective or kOrthogonal.
rotation()

Returns the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will return {0, 0, 0} until the relative rotation is changed with setRotation(), even if you adjust the rotation of your camera in the settings.
rotationFollowSmooth()

Returns the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().
screenCenterRay()

Casts a ray based on the center of the Camera. The object returned has the properties origin and direction.
screenRay(point)

Casts a ray based on the given screen point. The object returned has the properties origin and direction. This is useful in coordination with Physic’s World’s rayTest().
screenToWorld(screenPoint)

Converts the given Vec2 screenPoint to a 3D World Position.
setFarPlane(value)

Sets the far render distance of the camera. This is the maximum distance from the camera that an object will be rendered.
setFieldOfView(value)

Sets field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.
setFollowForce(x, y, z)

Sets the follow force of the camera. This determines how much ‘force’ the camera follows an object with.
setFollowOffset(x, y, z)

Sets the follow offset of the camera. The camera will follow the object from this many units away.
setFollowThreshold(x, y, z)

Sets the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving.
setNearPlane(value)

Sets the Near Render Distance of the camera. This is the minimum distance from the camera that an object will be rendered.
setOrthoScale(value)

Sets the orthographic scale of the camera (only works if camera projection is orthographic)
setPosition(x, y, z)

Sets the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will not override a camera’s position in the settings, but adjust the position relative to the original camera position.
setPositionFollow(value)

Sets which object the Camera will follow. There are four options you can pass.
1. “None” – Camera will not follow anything
2. “Game Path” – Game Path will be followed
3. “Character” – Any Entity that is considered a Character will be followed
4. The Asset attribute that will be followed
setProjection(value)

Sets the projection type of the camera. There are two possibilities: kPerspective or kOrthogonal.
setProjectionMatrix(matrix)

Sets a custom projection matrix.
setRotation(x, y, z)

Sets the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will not override a camera’s rotation in the settings, but adjust the rotation relative to the original camera rotation.
setRotationFollow(value)

Sets the object whose rotation the Camera will match. There are four options you can pass. “None” – Camera will not match anything for rotation
“Game Path” – Game Path’s rotation will be matched
“Character” – Any Entity that is considered a Character will be followed for rotation
The Asset attribute whose rotation the camera will match
setRotationFollowSmooth(value)

Sets the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().
setRotationQuat(value)

Sets the “additional” rotation in Quaternion. Note that unlike in Entity, these “setRotation” and “setRotationQuat” are independent, meaning that the result rotation will be a sum of these two.
setWorldPosition(x, y, z)

Sets the actual position of the camera, the same way it is set in the camera settings panel. Note that if the camera is set to follow position of a character or path, this function won’t work. Use setPosition() to change the camera’s position relative to the object it’s following.
worldPosition()

Returns the actual position of the camera. This is the same position as the one set in the camera settings panel.
worldRotation()

Returns the actual rotation of the camera. This is the same rotation as the one set in the camera settings panel.
worldToScreen(x, y, z)

Projects a World (3D) position into Screen (2D) coordinates.

farPlane()

Returns the far render distance of the camera.

Returns

number The Far Render Distance of the camera. This is the maximum distance from the camera that an object will be rendered.

↑ Back to top

fieldOfView()

Returns the field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.

Returns

number the field of view of the camera.

↑ Back to top

followForce()

Returns the follow force of the camera. This determines how much ‘force’ the camera follows an object with.

Returns

Vec3 the {x, y, z} follow force of the camera.

↑ Back to top

followOffset()

Returns the follow offset of the camera. The camera will follow the object from this many units away.

Returns

Vec3 the {x, y, z} follow offset of the camera.

↑ Back to top

followThreshold()

Returns the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving.

Returns

Vec3 the {x, y, z} follow threshold of the camera.

↑ Back to top

nearPlane()

Returns the near render distance of the camera. This is the minimum distance from the camera that an object will be rendered.

Returns

number The near render distance of the camera.

↑ Back to top

orthoScale()

Returns the orthographic scale of the camera (only works if camera projection is orthographic)

Returns

number the orthographic scale of the camera

↑ Back to top

position()

Returns the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will return {0, 0, 0} until the relative position is changed with setPosition(), even if you adjust the camera position in the settings.

Returns

Vec3 the {x, y, z} relative position of the camera. 

let camera = this.camera();
camera.setPositionFollow("Character");
log(camera.position()); // result: {0, 0, 0}
camera.setPosition(0, 10, 0); // the camera still follows the Character, but 10 units higher
log(camera.position()); // result: {0, 10, 0}

↑ Back to top

projection()

Returns the projection type of the camera. There are only two possibilities, kPerspective or kOrthogonal.

Returns

string “kPerspective” if the projection is Perspective, “kOrthogonal” if the projection is Orthogonal

↑ Back to top

rotation()

Returns the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will return {0, 0, 0} until the relative rotation is changed with setRotation(), even if you adjust the rotation of your camera in the settings.

Returns

Vec3 the {x, y, z} relative rotation of the camera.

let camera = this.camera();
camera.setPositionFollow("Character");
log(camera.rotation()); // result: {0, 0, 0}, regardless of camera settings
camera.setRotation(30, 0, 0); // the camera still follows the Character, but rotated on the X axis
log(camera.position()); // result: {30, 0, 0}

↑ Back to top

rotationFollowSmooth()

Returns the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().

Returns

number the rotation follow smoothness/coefficient

↑ Back to top

screenCenterRay()

Returns a ray cast at the center of the Camera. The object returned has the properties origin and direction.

Returns

Object the ray cast into the 3D world based on the screen point

↑ Back to top

screenRay(point)

Returns a ray cast at the given screen point. The object returned has the properties origin and direction. This is useful in coordination with Physic’s World’s rayTest().

Parameters

Vec2 point – an {x, y} coordinate on the screen

Returns

Object the ray cast into the 3D world based on the screen point

function touchBegan(point){
    let cam = this.scene().camera();
    let ra = cam.screenRay(pt);
    log(ra.origin);
    log(ra.direction);
}

↑ Back to top

screenToWorld(screenPoint)

Converts the given Vec2 screenPoint to a 3D World Position.

Parameters

Vec2 screenPoint – an {x, y} coordinate on the screen

Returns

Vec3 the {x, y, z} 3D world coordinate relative to the given Vec2 screenPoint

function touchMove(point){
  // move an entity to the point where the user is touching the screen.
  let pos = this.scene().camera().screenToWorld(point);
  this.entity().setPosition(pos.x, pos.y, pos.z);
}

↑ Back to top

setFarPlane(value)

Sets the far render distance of the camera. This is the maximum distance from the camera that an object will be rendered.

Parameters

number value – the new far render distance of the camera. Minimum 100.

↑ Back to top

setFieldOfView(value)

Sets field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.

Parameters

number value – the field of view, from a range of 10-100. The smaller the number, the more “focused in” your field of view becomes.

↑ Back to top

setFollowForce(x, y, z)

Sets the follow force of the camera. This determines how much ‘force’ the camera follows an object with. Another way to think of this is the speed at which your camera reacts to the object’s movement.

Parameters

number x – the x axis component of the follow force
number y – the y axis component of the follow force
number z – the z axis component of the follow force

↑ Back to top

setFollowOffset(x, y, z)

Sets the follow offset of the camera. The camera will follow the object from this many units away.

Parameters

number x – the x axis component of the follow offset
number y – the y axis component of the follow offset
number z – the z axis component of the follow offset

↑ Back to top

setFollowThreshold(x, y, z)

Sets the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving. A 0 follow threshold means the camera will start moving as soon as the object does, whereas a 100 means the camera starts moving when the object is 100 units away. This function also accepts a Vec3 optionally instead of x, y, z.

Parameters

number x – the x axis component of the follow threshold
number y – the y axis component of the follow threshold
number z – the z axis component of the follow threshold

↑ Back to top

setNearPlane(value)

Sets the Near Render Distance of the camera. This is the minimum distance from the camera that an object will be rendered.

Parameters

number value – The Near Render Distance of the camera.

↑ Back to top

setOrthoScale(value)

Sets the orthographic scale of the camera (only works if camera projection is orthographic)

Parameters

number value – the new orthographic scale of the camera

↑ Back to top

setPosition(x, y, z)

Sets the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will not override a camera’s position in the settings, but adjust the position relative to the original camera position.

Parameters

number x – the relative x axis position
number y – the relative y axis position
number z – the relative z axis position

let camera = this.camera();
camera.setPositionFollow("Character");
log(camera.position()); // result: {0, 0, 0}
camera.setPosition(0, 10, 0); // the camera still follows the Character, but 10 units higher
log(camera.position()); // result: {0, 10, 0}

↑ Back to top

setPositionFollow(value)

Sets which object the Camera will follow. There are four options you can pass.
1. “None” – Camera will not follow anything
2. “Game Path” – Game Path will be followed
3. “Character” – Any Entity that is considered a Character will be followed
4. The Asset attribute that will be followed

Parameters

string/Asset – “None”, “Game Path”, “Character”, or Asset attribute

↑ Back to top

setProjection(value)

Sets the projection type of the camera. There are two possibilities: kPerspective or kOrthogonal. If an invalid string is passed, will default to perspective.

Parameters

string – two possibilities: “kPerspective” or “kOrthogonal”

↑ Back to top

setProjectionMatrix(matrix)

Sets a custom projection matrix.

Parameters

Mat4 matrix – custom projection matrix

↑ Back to top

setRotation(x, y, z)

Sets the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will not override a camera’s rotation in the settings, but adjust the rotation relative to the original camera rotation.

Parameters

number x – the relative x axis rotation
number y – the relative y axis rotation
number z – the relative z axis rotation

let camera = this.camera();
camera.setPositionFollow("Character");
log(camera.rotation()); // result: {0, 0, 0}, regardless of camera settings
camera.setRotation(30, 0, 0); // the camera still follows the Character, but rotated on the X axis
log(camera.position()); // result: {30, 0, 0}

↑ Back to top

setRotationFollow(value)

Sets the object whose rotation the Camera will match. There are four options you can pass.
1. “None” – Camera will not match anything for rotation
2. “Game Path” – Game Path’s rotation will be matched
3. “Character” – Any Entity that is considered a Character will be followed for rotation
4. The Asset attribute whose rotation the camera will match

Parameters

string/Asset – “None”, “Game Path”, “Character”, or Asset attribute

↑ Back to top

setRotationFollowSmooth(value)

Sets the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().

Parameters

number value – the new rotation follow smoothness/coefficient

↑ Back to top

setRotationQuat(value)

Sets the “additional” rotation in Quaternion. Note that unlike in Entity, these “setRotation” and “setRotationQuat” are independent, meaning that the result rotation will be a sum of these two.

Parameters

Quaternion value – the new rotation in Quaternion

↑ Back to top

setWorldPosition(x, y, z)

Sets the actual position of the camera, the same way it is set in the camera settings panel. Note that if the camera is set to follow position of a character or path, this function won’t work. Use setPosition() to change the camera’s position relative to the object it’s following.
Take care when using setWorldPosition and setPosition together, as setPosition sets a relative position based on the camera’s world position.

Parameters

number x – the x-axis component of the new world position
number y – the y-axis component of the new world position
number z – the z-axis component of the new world position

↑ Back to top

worldPosition()

Returns the actual position of the camera. This is the same position as the one set in the camera settings panel.

Returns

Vec3 {x, y, z} position of the camera

↑ Back to top

worldRotation()

Returns the actual rotation of the camera. This is the same rotation as the one set in the camera settings panel.

Returns

Quaternion the rotation of the camera in Quaternion

↑ Back to top

worldToScreen(x, y, z)

Projects a World (3D) position into Screen (2D) coordinates.

Parameters

number x – the x-axis 3D coordinate
number y – the y-axis 3D coordinate
number z – the z-axis 3D coordinate

Returns

Vec2 the resulting 2D screen coordinates

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

EasingFunctions – API Reference

By |

EasingFunctions

EasingFunctions is a helper class with a collection of easing functions. Easing functions are used to calculate interpolation to create an animation.

These functions take a value from 0 to 1 representing how far into the animation you are (0 = beginning, 1 = end). Think of this as the “percent complete”. You can use easing functions in an update loop to update your object every frame. The Animation action nodes have all this set up for you already.

This is a simplified example of how we use EasingFunctions in a position animation node. This example makes my entity fall to position {0, 0, 0} with a bounce out animation.

let duration = 5;               // length of the animation in seconds
let phaseT = 0;                 // how far into the animation we are (percentage complete)
let target = new Vec3(0, 0, 0); // the ending position of my object
let done = false;               // flag to detect when to stop animating

let animObj;                    // the object we're animating
let startPos;                   // our object's initial position

function start(){
	animObj = this.entity();
	startPos = animObj.position();
}

function update(dt) {
	if (done) return; // don't run this code if the animation is complete
	phaseT += dt / duration; // calculate the time difference since the last update call
	phaseT = Math.min(phaseT, 1); // don't allow the percentage complete to go over 100%

	// Pass the percentage complete into the EasingFunction, 
	// which will return the factor we need to multiply by to
	// find our target position for this frame:
	let anim = EasingFunctions.outBounce(phaseT); 

	// determine the new position based on the starting position, target position, and animation factor:
	let aPos = new Vec3;
	aPos.x = startPos.x * (1 - anim) + target.x * anim;
	aPos.y = startPos.y * (1 - anim) + target.y * anim;
	aPos.z = startPos.z * (1 - anim) + target.z * anim;

	// set the new position
	animObj.setPosition(aPos.x, aPos.y, aPos.z);

	if (phaseT == 1) {
		// if we reach 100% complete, set the flag to stop running the animation code
		done = true;
	}
}

Supported Easing Functions

Here is a website with graphs of all the easing functions, for visualization.

EasingFunctions = {
    linear
    inQuad
    outQuad
    inOutQuad
    inCube
    outCube
    inOutCube
    inQuart
    outQuart
    inOutQuart
    inQuint
    outQuint
    inOutQuint
    inSine
    outSine
    inOutSine
    inExpo
    outExpo
    inOutExpo
    inCirc
    outCirc
    inOutCirc
    inBack
    outBack
    inOutBack
    inBounce
    outBounce
    inOutBounce
    inElastic
    outElastic
    inOutElastic
}

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

Mat4 – API Reference

By |

Mat4

The Mat4 class represents a 4×4 matrix. Mat4 contains several helpful static functions, which can be called like this: Mat4.createRotation(quat)

Property Description
arr

The array that represents the matrix.
Function Description
rotate(x, y, z, angle)

Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.
scale(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.
translate(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified translation.
Static Function Description
createIdentity()

Creates and returns a 4×4 identity matrix.
createOrthographic(left, right, bottom, top, near, far)

Creates an orthographic projection transformation matrix. The parameters form a rectangular cuboid that defines the visible area of rendering.
createRotation(quat)

Creates a rotation matrix based on the given Quaternion.
createTranslation(x, y, z)

Creates a translation matrix based on the given x, y, z coordinates.
inverse(matrix)

Returns the inverse of the given matrix.
multiply(matrix1, matrix2)

Multipies the given matrices together.
transformPoint(matrix, vector)

Transforms the specified point by this matrix, and returns the result.
transformVector(matrix, vector)

Transforms the specified vector by this matrix by treating the fourth (w) coordinate as zero, and returns the result.

arr

array – the array that represents the matrix

↑ Back to top

rotate(x, y, z, angle)

Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.

Parameters

number x – the x-axis to rotate about
number y – the y-axis to rotate about
number z – the z-axis to rotate about
number angle – the angle of the rotation (radians)

↑ Back to top

scale(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.

Parameters

number x – the amount to scale along the x-axis
number y – the amount to scale along the y-axis
number z – the amount to scale along the z-axis

↑ Back to top

translate(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified translation.

Parameters

number x – the amount to translate along the x-axis
number y – the amount to translate along the y-axis
number z – the amount to translate along the z-axis

↑ Back to top

createIdentity()

Creates and returns a 4×4 identity matrix.

Returns

Mat4 matrix – A new identity matrix

↑ Back to top

createOrthographic(left, right, bottom, top, near, far)

Creates an orthographic projection transformation matrix. The parameters form a rectangular cuboid that defines the visible area of rendering.

Parameters

number left – farthest left on the x-axis
number right – farthest right on the x-axis
number bottom – farthest down on the y-axis
number top – farthest up on the y-axis
number near – closest on the z-axis
number far – furthest on the z-axis

Returns

Mat4 – the resulting orthographic projection matrix

↑ Back to top

createRotation(quat)

Creates a rotation matrix based on the given Quaternion.

Parameters

Quaternion quat – the Quaternion representation of the rotation

Returns

Mat4 – the resulting rotation matrix

↑ Back to top

createTranslation(x, y, z)

Creates a translation matrix based on the given x, y, z coordinates.

Parameters

number x – the translation on the x-axis
number y – the translation on the y-axis
number z – the translation on the z-axis

Returns

Mat4 – the resulting translation matrix

↑ Back to top

inverse(matrix)

Returns the inverse of the given matrix.

Parameters

Mat4 matrix – the matrix to be inverted

Returns

Mat4 – the inverted matrix

↑ Back to top

multiply(matrix1, matrix2)

Multipies the given matrices together.

Parameters

Mat4 matrix1 – the first matrix to multiply
Mat4 matrix2 – the second matrix to multiply

Parameters

Mat4 – the resulting matrix

↑ Back to top

transformPoint(matrix, point)

Transforms the specified point by this matrix, and returns the result.

Parameters

Mat4 matrix – the transformation matrix
Vec3 point – the point to transform

Returns

Vec3 – the transformed point

↑ Back to top

transformVector(matrix, vector)

Transforms the specified vector by this matrix by treating the fourth (w) coordinate as zero, and returns the result.

Parameters

Mat4 matrix – the transformation matrix
Vec3 vector – the vector to transform

Returns

Vec3 – the transformed vector

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

OBB – API Reference

By |

OBB

The OBB class represents an “oriented bounding box” for an object. OBB is more precise but more performance-heavy than AABB. The list below isn’t of functions but properties, so you can call them like this: this.entity().worldOBB().center

Property Description
center

Vec3 the {x, y, z} center of the OBB
extents

Vec3 the {x, y, z} extents of the OBB
xAxis

Vec3 the x-axis orientation axes
yAxis

Vec3 the y-axis orientation axes
zAxis

Vec3 the z-axis orientation axes

center

Vec3 the {x, y, z} center of the OBB

↑ Back to top

extents

Vec3 the {x, y, z} extents of the OBB

↑ Back to top

xAxis

Vec3 the x-axis orientation axes

↑ Back to top

yAxis

Vec3 the y-axis orientation axes

↑ Back to top

zAxis

Vec3 the z-axis orientation axes

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

AABB – API Reference

By |

AABB

Represents the “axis-aligned bounding box” for the object. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Together this can be used to ascertain the size of the bounding box.

Property Description
max

The Vec3 {right, top, far} maximum value of the AABB.
min

The Vec3 {left, bottom, near} minimum value of the AABB.

max

The Vec3 {right, top, far} maximum value of the AABB.

↑ Back to top

min

The Vec3 {left, bottom, near} minimum value of the AABB.

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

Event – API Reference

By |

Event

The Event class allows you to fire (broadcast) global events and subscribe to them. Here’s an example:

//// SENDER
let data = true; // this could be any value
eventName = "Some Name";
Event.fire(eventName, data);

//// RECEIVER
let SNCallback = function(data){
  log("callback: " + data);
};

function start(){
  Event.addListener("Some Name", SNCallback);
}
function onRemove(){
  Event.removeListener("Some Name", SNCallback);
}

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

Ads – API Reference

By |

Ads

These functions help you control advertisements shown in your game. Check out this page of the manual to learn how to monetize your game with advertisements. Note that you won’t see any ad banners or videos in the Preview window of BuildBox.

Static Function Description
hideBanner()

Hides a banner ad if it is visible.
isRemoveAdsPurchased()

Returns true if the user has paid to remove ads, and false if not.
isRewardedVideoAvailable()

Returns true if a rewarded video is available to show, and false if not.
showBanner()

Shows a banner ad.
showInterstitial()

Shows an interstitial (video advertisement) to the user.
showRewardedVideo(callback)

Shows Rewarded Video to the user. callback will be triggered when the video ends.

hideBanner()

Hides a banner ad if it is visible.

↑ Back to top

isRemoveAdsPurchased()

Returns true if the user has paid to remove ads, and false if not. Check this page of the manual to learn how to allow the user to pay to remove ads.

Returns

boolean true if the user has paid to remove ads, false if not

↑ Back to top

isRewardedVideoAvailable()

Returns true if a rewarded video is available to show, and false if not.

Returns

boolean true if a rewarded video is available to show, false if not

↑ Back to top

showBanner()

Shows a banner ad.

↑ Back to top

showInterstitial()

Shows an interstitial (video advertisement) to the user.

↑ Back to top

showRewardedVideo(callback)

Shows Rewarded Video to the user. callback will be triggered when the video ends.

let callback = function(){
    //when this fires, the rewarded video is complete. Give reward to player here 
}
 callback = callback.bind(this);
 Ads.showRewardedVideo(callback);

↑ Back to top

 

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?

December 12, 2019
0

Animation – API Reference

By |

Animation

This kind of Animation can be created from an Animation script attribute. It’s useful because you can instantiate many copies of the same animation attribute using code. An Animation is two-dimensional. Here’s an example of creating an Animation from an attribute.

    let attribute = this.attribute('Flame');
    let anim = new Animation(attribute, this);
Function Description
play()

Starts playing the animation from its beginning.
position()

Returns the Animation’s position relative to its Entity.
rotation()

Returns the rotation of the Animation. in degrees.
scale()

Returns the scale of the Animation.
setFrame(value)

Sets the Animation to a specific frame.

setOpacity(value)

Sets the opacity of the Animation.
setPosition(x, y, z)

Sets the position of the Animation.
setRotation(value)

Sets the rotation of the Animation, in degrees.
setScale(x, y, z)

Sets the scale of the Animation.
setVisible(value)

Sets the visibility of the Animation.

play()

Starts playing the animation from its beginning.

↑ Back to top

position()

Returns the Animation’s position relative to its Entity.

Returns

Vec3 {x, y} relative coordinates of the Animation.

↑ Back to top

rotation()

Returns the rotation of the Animation. in degrees.

Returns

number the rotation of the Animation, in degrees.

↑ Back to top

scale()

Returns the scale of the Animation.

Returns

Vec2 {x, y} scale of the Animation.

↑ Back to top

setFrame(value)

Sets the Animation to a specific frame.

Parameters

number value – the frame the Animation will be set to.

↑ Back to top

setOpacity(value)

Sets the opacity of the Animation.

Parameters

number value – new opacity value, range: 0-255

↑ Back to top

setPosition(x, y, z)

Sets the position of the Animation.

Parameters

number x – new x-axis position of the Animation
number y – new y-axis position of the Animation
number z – (optional) z-axis position of the Animation

↑ Back to top

setRotation(value)

Sets the rotation of the Animation, in degrees.

Parameters

number value – new rotation of the Animation, in degrees

↑ Back to top

setScale(x, y, z)

Sets the scale of the Animation.

Parameters

number x – x-axis scale of the Animation
number y – y-axis scale of the Animation
number z – (optional) z-axis scale of the Animation

↑ Back to top

setVisible(value)

Sets the visibility of the Animation.

Parameters

boolean value – true for visible, false for not visible.

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?