Class: Actor

b5. Actor

b5.Actor

new b5.Actor(virtual){b5.Actor}

actor/actor.js, line 262

An Actor is a basic game object that carries our game logic and rendering. The base Actor has the following features:

  • Position, size, scale, rotation
  • Absolute (pixel coordinate) and relative (based on visible size) origins
  • Layering
  • Support for cached rendering
  • 3D depth (allows easy parallax scrolling)
  • Angular, linear and depth velocity
  • Box2D physics support (including multiple fixtures and joints)
  • Bitmap frame animation
  • Timeline animation manager
  • Actions list manager
  • Tasks manager
  • Sprite atlas support
  • Child hierarchy
  • Angular gradient fills
  • Shadows
  • Composite operations
  • Begin, end and move touch events (when touchable is true), also supports event bubbling
  • Canvas edge docking with dock margins
  • Can move in relation to camera or be locked in place
  • Can be made to wrap with scene extents on x and y axis
  • Clip children against the extents of the parent with margins and shapes
  • Supports opacity
  • Can be represented visually by arcs, rectangles, polygons, bitmaps and labels
  • Support for a virtual canvas that can scroll content around

Supports the following event handlers:

  • onCreate() - Called just after Actor has been created (only called from Xoml)
  • onDestroy() - Called just before Actor is destroyed
  • onTick(delta_time) - Called each time the Actor is updated (every frame)
  • onTapped(touch_pos) - Called when the Actor is tapped / clicked
  • onBeginTouch(touch_pos) - Called if the user begins to touch this actor
  • onEndTouch(touch_pos) - Called when the user stops touching display and this actor was beneath last touch point
  • onLostTouchFocus(touch_pos) - Called if actor was touched on initial begin touch event when the user stops touching display, even if this actor is not under touch point
  • onMoveTouch(touch_pos) - Called when a touch is moved over the Actor
  • onCollisionStart(contact) - Called when the Actor started colliding with another
  • onCollisionEnd(contact) - Called when the Actor stopped colliding with another

For an actor to be processed and rendered you must add it to a added to a b5.Scene or another b5.Actor that is part of a scene hierarchy

Examples

Example showing how to create a basic actor:

 var actor = new b5.Actor();
 actor.x = 100;
 actor.y = 100;
 actor.w = 200;
 actor.h = 200;
 actor.bitmap = my_bitmap;
 scene.addActor(actor);   // Add to scene

Adding a bitmap image to the actor example

 bg.bitmap = new b5.Bitmap("background", "images/background.jpg", true);

Adding a bitmap image from the scene resources to an actor example

 bg.bitmap = scene.findResource("background", "bitmap");

Adding basic physics to a basic actor example

 actor.initBody("dynamic", false, false);    // Initialise physics body
 actor.addFixture({type: Shape.TypeBox, width: actor.w, height: actor.h}); // Add a physics fixture

Adding bitmap animation to an actor example

 actor.atlas = new b5.ImageAtlas("sheep", new b5.Bitmap("sheep", "images/sheep.png", true)); // Create an image atlas from a bitmap image
 actor.atlas.addFrame(0,0,86,89);     // Add frame 1 to the atlas
 actor.atlas.addFrame(86,0,86,89);    // Add frame 2 to the atlas
 actor.current_frame = 0;             // Set initial animation frame
 actor.frame_speed = 1;               // Set animation playback speed

Adding collection of bitmap animation to an actor example

 actor.atlas = new ImageAtlas("sheep", new Bitmap("sheep", "images/sheep.png", true));
 actor.atlas.addFrame(0,0,32,32,0,0);    // Add frame 1 to the atlas
 actor.atlas.addFrame(32,0,32,32,0,0);   // Add frame 2 to the atlas
 actor.atlas.addFrame(64,0,32,32,0,0);   // Add frame 3 to the atlas
 actor.atlas.addFrame(96,0,32,32,0,0);   // Add frame 4 to the atlas
 actor.atlas.addFrame(128,0,32,32,0,0);   // Add frame 5 to the atlas
 actor.atlas.addFrame(160,0,32,32,0,0);   // Add frame 6 to the atlas
 actor.atlas.addAnim("walk", [0, 1, 2, 3], 10);
 actor.atlas.addAnim("idle", [4, 5], 10);
 actor.playAnim("walk");

Add a child actor example

 var child_actor = new b5.Actor();
 actor.addActor(child_actor);

Adding an onTick event handler to an actor example

 Actor.onTick = function(dt) {
     this.x++;
 };

Adding touch event handlers to an actor example

 actor.touchable = true ; // Allow actor to be tested for touches
 actor.onTapped = function(touch_pos) {
     console.log("Actor tapped");
 };
 actor.onBeginTouch = function(touch_pos) {
     console.log("Actor touch begin");
 };
 actor.onEndTouch = function(touch_pos) {
     console.log("Actor touch end");
 };
 actor.onMoveTouch = function(touch_pos) {
     console.log("Actor touch move");
 };

Docking an actor to the edges of the scene example

 actor.dock_x = Actor.Dock_Left;
 actor.dock_y = Actor.Dock_Top;
 actor.ignore_camera = true;

Self clipped actor example

 // Create a clip shape
 var shape = new b5.Shape();
 shape.type = b5.Shape.TypePolygon;
 shape.vertices = [0, -20, 20, 20, -20, 20];

 // Set clip shape and enable self clipping
 actor.self_clip = true;
 actor.clip_shape = shape;

Adding a physics joint example

 actor1.addJoint({ type: "weld", actor_b: actor2, anchor_a: { x: 0, y: 0 }, anchor_b: { x: 0, y: 0 }, self_collide: true });

Handling collision example

 actor1.onCollisionStart = function (contact) {
      var actor1 = contact.GetFixtureA().GetBody().GetUserData();
      var actor2 = contact.GetFixtureB().GetBody().GetUserData();
      console.log(actor1.name + " hit " + actor2.name);
 };

Apply force and torque example

 var b2Vec2 = Box2D.Common.Math.b2Vec2;
 var pos = actor.body.GetWorldPoint(new b2Vec2(0,0));
 actor.body.ApplyForce(new b2Vec2(fx, fy), pos);

Changing velocity and applying impulses example

 var b2Vec2 = Box2D.Common.Math.b2Vec2;
 actor.body.SetLinearVelocity(new b2Vec2(vx, vy));
 actor.body.SetAngularVelocity(vr);
 actor.body.ApplyImpulse(new b2Vec2(ix, iy), pos);

Creating and adding a timeline animation example

 // Create a timeline that targets the x property of my_object with 4 key frames spaced out every 5 seconds and using
 // QuarticIn easing to ease between each frame
 var timeline = new b5.Timeline(my_object, "_x", [0, 100, 300, 400], [0, 5, 10, 15], 0, [b5.Ease.quartin, b5.Ease.quartin, b5.Ease.quartin]);
 my_object.timelines.add(timeline); // Add to timeline manager to be processed

For a complete overview of the Actor class see Booty5 Actor Overview

Name Type Description
virtual boolean

If true then this Actor will support a virtual scrollable canvas

Properties:
Name Type Description
type number

Type of actor (internal)

scene b5.Scene

Parent scene (internal)

parent b5.Actor

Parent actor (If null then this actor does not belong to an actor hierarchy) (internal)

actors Array.<b5.Actor>

Array of child actors (internal)

removals Array.<b5.Actor>

Array of actors that should be deleted at end of frame (internal)

joints Array.<object>

Array of Box2D physics joints that weer created by this actor (internal)

timelines b5.TimelineManager

Actor local animation timelines (internal)

actions b5.ActionsListManager

Actions list manager (internal)

tasks b5.TasksManager

Tasks manager (internal)

frame_count number

Number of frames that this actor has been running (internal)

accum_scale_x number

Accumulated X scale (internal)

accum_scale_y number

Accumulated Y scale (internal)

accum_opacity number

Accumulative opacity (internal)

body Box2DBody

Box2D body (null if none attached) (internal)

transform Array.<number>

Current visual transform (internal)

transform_dirty boolean

If set to true then transforms will be rebuilt next update (internal)

touching boolean

Set to true when user touching (internal)

touchmove boolean

Set to true when touch is moving on this actor (internal)

layer number

Visible layer (set via property _layers) (internal)

order_changed boolean

Set to true when child actors change order (internal)

cache_canvas Canvas

The HTML5 Canvas object that is used to cache rendering (internal)

name string

Name of actor (used to find actors in the scene)

tag string

Tag (used to find groups of actors in the scene)

id number

User defined ID (default is -1)

active boolean

Active state, inactive actors will not be updated (default is true)

visible boolean

Visible state, invisible actors will not be drawn (default is true)

touchable boolean

Touchable state, true if currently touched (default is false)

layer number

Actor sorting layer, set via _layer (default is 0)

x number

X position in scene, set via _x (default is 0)

y number

Y position in scene, set via _y (default is 0)

w number

Width of actor (default is 0)

h number

Height of actor (default is 0)

ox number

X origin (between -1 and 1), set via _ox, if value falls outside that range then origin will be interpreted as pixels (default is 0)

oy number

Y origin (between -1 and 1), set via _oy, if value falls outside that range then origin will be interpreted as pixels (default is 0)

ignore_atlas_size boolean

If true then the actor will not change size top match the size of the sub image from the atlas

absolute_origin boolean

If true then origin will be taken as absolute coordinates, otherwise it will be taken as a proportion of actors size (default is true)

rotation number

Rotation in radians, set via _rotation (default is 0)

scale_x number

X scale, set via _scale_x or _scale (default is 1)

scale_y number

Y scale, set via _scale_y or _scale (default is 1)

depth number

Z depth (3D depth), set via _depth, 0 represents no depth (default is 0)

opacity number

Opacity (between 0 and 1) (default is 1)

use_parent_opacity boolean

Scale opacity by parent opacity if true (default is true)

current_frame number

Current bitmap animation frame (default is 0)

frame_speed number

Bitmap animation playback speed in seconds (default is 0)

anim_frames Array.<number>

Array of animation frame indices, if not set then frames will be used in order specified in the atlas (default is null)

bitmap b5.Bitmap

Bitmap (used if no atlas defined), if set via _bitmap then instance of bitmap or string based path to bitmap can be used (default is null)

atlas b5.ImageAtlas

Image atlas, if set via _bitmap then instance of atlas or string based path to atlas can be used (default is null)

vr number

Rotational velocity (when no body attached) (default is 0)

vx number

X velocity (when no body attached) (default is 0)

vy number

Y velocity (when no body attached) (default is 0)

vd number

Depth velocity, rate at which depth changes (default is 0)

vr_damping number

Rotational damping (when no body attached) (default is 1)

vx_damping number

X velocity damping (when no body attached) (default is 1)

vy_damping number

Y velocity damping (when no body attached) (default is 1)

vd_damping number

Depth velocity damping (default is 1)

ignore_camera boolean

If set to true them then this actor will not use camera translation (default is false)

wrap_position boolean

If true then actor will wrap at extents of scene (default is false)

dock_x number

X-axis docking (0 = none, 1 = left, 2 = right) (default is 0)

dock_y number

Y-axis docking (0 = none, 1 = top, 2 = bottom) (default is 0)

margin Array.<number>

Margin to leave around docked actors [left, right, top, bottom] (default is [0,0,0,0])

bubbling boolean

If true then touch events will be allowed to bubble up to parents (default is false)

clip_children boolean

If set to true then child actors will be clipped against extents of this actor (default is false)

clip_margin Array.<number>

Margin to leave around clipping [left, top, right, bottom] (default is [0,0,0,0])

clip_shape b5.Shape

Shape to clip this actor and / or its children against, if set via _clip_shape then instance of shape or string based path to shape can be used (default is null)

self_clip boolean

If set to true then this actor will be clipped against its own clipping shape (default is false)

orphaned boolean

If set to true then this actor will not use its parent actors transform, scene transform will be used instead (default is false)

virtual boolean

If true then actor will be classed as a container with a virtual canvas that can scroll and stack its content (default is false)

shadow boolean

If set to true then shadow will be added to text (default is false)

shadow_x number

Shadow x axis offset (default is 0)

shadow_y number

Shadow y axis offset (default is 0)

shadow_blur number

Shadow blur (default is 0)

shadow_colour string

Shadow colour (default is "#000000")

composite_op string

Composite operation (default is null)

cache boolean

If true then resource will be rendered to a cached canvas (default is false)

merge_cache boolean

If true then resource will be rendered to parent cached canvas (default is false)

round_pixels boolean

If set to true then vertices will be rounded before rendered which can boost performance, but there will be a loss in precision (default is false)

Returns:
Type Description
b5.Actor The created Actor

Members

static,constantb5.Actor.Dock_Bottom

Actor is docked against bottom of scene / actor on y-axis

static,constantb5.Actor.Dock_Left

Actor is docked against left of scene / actor on x-axis

static,constantb5.Actor.Dock_None

Actor is not docked

static,constantb5.Actor.Dock_Right

Actor is docked against right of scene / actor on x-axis

static,constantb5.Actor.Dock_Top

Actor is docked against top of scene / actor on y-axis

static,constantb5.Actor.Type_Arc

Actor is an arc based actor

static,constantb5.Actor.Type_Image

Actor is an image based actor

static,constantb5.Actor.Type_Label

Actor is a label based actor

static,constantb5.Actor.Type_Map

Actor is a tiled map based actor

static,constantb5.Actor.Type_Particle

Actor is a particle based actor

static,constantb5.Actor.Type_Polygon

Actor is a polygon based actor

static,constantb5.Actor.Type_Rect

Actor is a rectangular based actor

Methods

addActor(actor){b5.Actor}

actor/actor.js, line 628

Adds the specified actor to this actors child list, placing the specified actor under control of this actor

Name Type Description
actor b5.Actor

An actor

Returns:
Type Description
b5.Actor The supplied actor

addFixture(options){object}

actor/actor.js, line 972

Adds a new fixture to this actors physics body

Name Type Description
options object

An object describing the fixtures properties:

  • type {number} – Type of fixture (Shape.TypeBox, Shape.TypeCircle or Shape.TypePolygon)
  • density {number} – Fixture density
  • friction {number} – Fixture friction
  • restitution {number} – Fixture restitution
  • is_sensor {boolean} – true if this fixture is a sensor
  • width {number} – Width and height of box (if type is box)
  • height {number} – Width and height of box (if type is box)
  • radius {number} – Radius of shape (if type is circle)
  • material {b5.Material} – A Material resource, if passed then density, friction, restitution will be taken from the material resource
  • shape {b5.Shape} – A Shape resource, if passed then width, height, type and vertices will be taken from the shape resource
Returns:
Type Description
object The created fixture or in the case of a multi-fixture shape an array of fixtures

addJoint(options){object}

actor/actor.js, line 1087

Adds a new joint to this actor

Name Type Description
options object

An object describing the joints properties:

  • type {string} – Type of joint to create (weld, distance, revolute, prismatic, pulley, wheel, mouse)
  • actor_b (b5.Actor) – The other actor that this joint attaches to
  • anchor_a {object} - The joints x, y anchor point on this body
  • anchor_b {object} - The joints x, y anchor point on actor_b’s body
  • self_collide {boolean} – If set to true then actors that are connected via the joint will collide with each other
  • frequency {number} – Oscillation frequency in Hertz (distance joint)
  • damping {number} – Oscillation damping ratio (distance and wheel joints)
  • limit_joint {boolean} – If true then joint limits will be applied (revolute, prismatic, wheel joints)
  • lower_limit {number} – Lower limit of joint (revolute, prismatic, wheel joints)
  • upper_limit {number} – Upper limit of joint (revolute, prismatic, wheel joints)
  • motor_enabled {boolean} – If true then the joints motor will be enabled (revolute, prismatic, wheel joints)
  • motor_speed {number} – Motor speed (revolute, prismatic, wheel joints)
  • max_motor_torque {number} – Motors maximum torque (revolute joints)
  • max_motor_force {number} – Motors maximum force (prismatic, wheel, mouse joints)
  • axis {object} – Movement x, y axis (prismatic, wheel joints)
  • ground_a {object} – Ground x, y offset for this actor (pulley joints)
  • ground_b {object} – Ground x, y offset for actor_b (pulley joints)
Returns:
Type Description
object The created joint

baseUpdate(dt)

actor/actor.js, line 1527

Main base actor update method that is called by the main app object each logic loop. Performs many actions including:

  • Calling onTick() callback
  • Updating local timelines manager
  • Updating local actions manager
  • Updating local tasks manager
  • Providing virtual canvas functionality
  • Updating bitmap animation
  • Updating position / rotation from physics or updating arcade physics
  • Scene edge wrapping
  • Applying docking
  • Updating child hierarchy
  • Cleaning up destroyed child actors
  • Sorting child actor layers
Name Type Description
dt number

Time that has passed since this actor was last updated in seconds

bringToFront()

actor/actor.js, line 795

Moves the actor to the end of its parents child list, effectively rendering it on top of all other actors that have the same depth

changeParent(parent)

actor/actor.js, line 600

Removes the actor from its current parent and places it into a new parent

Name Type Description
parent b5.Actor | b5.Scene

New parent

destroy()

actor/actor.js, line 587

Destroys the actor, removing it from the scene

dirty()

actor/actor.js, line 1670

Dirties this actor and all child actor transforms forcing them to be rebuilt

draw()

actor/actor.js, line 1322

Renders this actor and all of its children, called by the base app render loop. You can derive your own actor types from Actor and implement draw() to provide your own custom rendering

drawToCache()

actor/actor.js, line 1434

Renders this actor to a cache which can speed up rendering it the next frame

findActor(name, recursive){b5.Actor}

actor/actor.js, line 697

Searches the actors children to find the named actor

Name Type Description
name string

Name of actor to find

recursive boolean

If true then this actors entire child actor hierarchy will be searched

Returns:
Type Description
b5.Actor The found actor or null if not found

findActorById(id, recursive){b5.Actor}

actor/actor.js, line 723

Searches the actors children to find the actor by its id

Name Type Description
id number

Id of actor to find

recursive boolean

If true then this actors entire child actor hierarchy will be searched

Returns:
Type Description
b5.Actor The found actor or null if not found

findFirstCachedParent(){b5.Actor}

actor/actor.js, line 763

Search up the actors parent hierarchy for the first actor that is cached

Returns:
Type Description
b5.Actor The found actor or null if not found

findFirstParent(){b5.Actor}

actor/actor.js, line 747

Search up the actors parent hierarchy for the first actor parent of this actor

Returns:
Type Description
b5.Actor The found actor or null if not found

hitTest(position){b5.Actor}

actor/actor.js, line 1851

Tests to see if the supplied position has hit the actor or any of its children. This function does not work with actors that have been rotated around any point except their centre, also does not work with actors that have depth.

Name Type Description
position object

The x,y position to be tested

Returns:
Type Description
b5.Actor The actor that was hit or null if no actor was hit

initBody(body_type, fixed_rotation, is_bullet){object}

actor/actor.js, line 934

Creates and attached a physics body 5to this actor, placing this actor under control of the Box2D physics system

Name Type Description
body_type string

Type of body, can be static, dynamic or kinematic.

fixed_rotation boolean

If set to true then the physics body will be prevented from rotating

is_bullet boolean

If set to true then the physics body will be marked as a bullet which can be useful for very fast moving objects

Returns:
Type Description
object The created body

makeVirtual()

actor/actor.js, line 1695

Attaches a virtual canvas providing new actor properties:

  • prev_scroll_pos_x {number} - Previous canvas scroll X position
  • prev_scroll_pos_y {number} - Previous canvas scroll Y position
  • scroll_pos_x {number} - Canvas scroll X position
  • scroll_pos_y {number} - Canvas scroll Y position
  • scroll_vx {number} - Canvas scroll X velocity
  • scroll_vy {number} - Canvas scroll Y velocity
  • scroll_range {number} - Scrollable range of canvas (left, top, width, height)

Child actors that apply docking will be docked to this container instead of the scene

onBeginTouchBase(touch_pos)

actor/actor.js, line 854

Called by the main app object when the user begins to touch this actor, provided that this actor is marked as touchable Calls a user supplied onBeginTouch() method if one is supplied

Name Type Description
touch_pos object

x,y position of touch

onEndTouchBase(touch_pos)

actor/actor.js, line 869

Called by the main app object when the user stops touching this actor, provided that this actor is marked as touchable Calls a user supplied onEndTouch() method if one is supplied

Name Type Description
touch_pos object

x,y position of touch

onMoveTouchBase(touch_pos)

actor/actor.js, line 887

Called by the main app object when the user moves their finger or mouse whilst touching this actor, provided that this actor is marked as touchable Calls a user supplied onEndTouch() method if one is supplied

Name Type Description
touch_pos object

x,y position of touch

overlaps(other){boolean}

actor/actor.js, line 1947

Basic test to see if actors overlap (no scaling, rotation, origin or shape currently taken into account)

Name Type Description
other b5.Actor

Other actor to test overlap with

Returns:
Type Description
boolean true if overlapping, false if not

playAnim(name)

actor/actor.js, line 553

Plays the named animation of the attached b5.ImageAtlas brush on this actor

Name Type Description
name string

Name of animation to play

postDraw()

actor/actor.js, line 1500

Called after rendering the actor to perform various post-draw activities such as disabling shadows and resetting composite operations

preDraw()

actor/actor.js, line 1482

Called before rendering the actor to perform various pre-draw activities such as setting opacity, shadows and composite operations

release()

actor/actor.js, line 576

Releases the actor, calling the actors onDestroy() handler and releases physics, does not remove actor from the scene

releaseBody()

actor/actor.js, line 905

Releases this actors physics body destroying the body, taking control of the actor from the Box2D physics system

releaseJoints()

actor/actor.js, line 917

Releases all joints that this actor created, destroying the joints

removeActor(actor)

actor/actor.js, line 640

Removes the specified actor from this actors child list

Name Type Description
actor b5.Actor

An actor

removeActorsWithTag(tag)

actor/actor.js, line 649

Removes all actors from this actors child list that match the specified tag

Name Type Description
tag string

Actor tag

removeJoint(joint)

actor/actor.js, line 1213

Removes and destroys the specified joint

Name Type Description
joint object

The joint to remove

sendToBack()

actor/actor.js, line 822

Moves the actor to the start of its parents child list, effectively rendering behind all other actors that have the same depth

setDepth(depth)

actor/actor.js, line 540

Sets the actors 3D depth

Name Type Description
depth number

3D depth, use 0 to disable depth projection

setOrigin(x, y)

actor/actor.js, line 495

Sets the actors render origin

Name Type Description
x number

X coordinate

y number

Y coordinate

setPosition(x, y)

actor/actor.js, line 471

Sets the actors scene position

Name Type Description
x number

X coordinate

y number

Y coordinate

setRotation(angle)

actor/actor.js, line 522

Sets the actors rotation

Name Type Description
angle number

Angle in radians

setScale(x, y)

actor/actor.js, line 509

Sets the actors scale

Name Type Description
x number

X scale

y number

Y scale

transformPoint(x, y){object}

actor/actor.js, line 1899

Transforms supplied point by actors visual transform

Name Type Description
x number

X coordinate local to actor

y number

Y coordinate local to actor

Returns:
Type Description
object Transformed point

update(dt)

actor/actor.js, line 1649

Main actor update method that is called by the main app object each logic loop. If you derive your own Actor class then you should override this method to provide your own functionality, but remember to call baseUpdate() if you would like to keep the existing base Actor functionality

Name Type Description
dt number

Time that has passed since this actor was last updated in seconds

updateParentTransforms()

actor/actor.js, line 778

Updates the transforms of all parents of this actor

updateToPhysics()

actor/actor.js, line 1657

Copies actor velocities to the physics body

updateTransform()

actor/actor.js, line 1235

Checks if this actors visual transform is dirty and if so rebuilds the transform and mark the transform as clean