Actor API Reference


b5.Actor

An Actor represents a game object that can be added to a Scene for processing and display. You can add logic to the actor via its update() method and or by attaching an onTick event handler. 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
  • Timeline animations
  • Actions lists
  • 3D depth (allows easy parallax scrolling)
  • Angular, linear and depth velocity
  • Box2D physics support (including multiple fixtures and joints)
  • Bitmap frame animation
  • 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 dock and scroll content around

Other game object types are derived from Actor including:

Public properties

  • name – Name of actor (used to find game objects in the scene)
  • tag – Tag (used to find groups of game objects in the scene)
  • id – User defined ID
  • active – Active state, will not be updated when inactive (update method will not be called)
  • visible – Visible state, will not be draw if invisible (draw method will not be called)
  • touchable – Touchable state, true if can be touched / clicked and will receive touch events
  • layer – Visible sorting layer
  • x – X position in scene
  • y – Y position in scene
  • w – Visual width
  • h – Visual height
  • ox – X origin
  • oy – Y origin
  • absolute_origin – If true then ox and oy are taken as absolute coordinates, if false then ox and oy are taken as percentage of width and height
  • rotation – Rotation in radians
  • scale_x – X scale
  • scale_y – Y scale
  • depth – Z depth (3D depth), 0 represents no depth
  • opacity – Opacity (between 0 and 1)
  • use_parent_opacity – Scale opacity by parent opacity fi true
  • current_frame – Current bitmap animation frame
  • frame_speed – Bitmap animation playback speed in seconds
  • anim_frames – An array of frame indices, if set then current frame will be read from this array
  • bitmap – Bitmap (used if no atlas defined)
  • atlas – Image atlas
  • vr – Rotational velocity (when no physics body attached)
  • vx – X velocity (when no physics body attached)
  • vy – Y velocity (when no physics body attached)
  • vd – Depth velocity, rate at which depth changes
  • vr_damping – Rotational damping (when no physics body attached)
  • vx_damping – X velocity damping (when no physics body attached)
  • vy_damping – Y velocity damping (when no physics body attached)
  • vd_damping – Depth velocity damping
  • ignore_camera – If set to true them then this game object will not use camera translation
  • wrap_position – If true then game object will wrap at extents of scene
  • dock_x – X-axis docking (0 = none, 1 = left, 2 = right)
  • dock_y – Y-axis docking (0 = none, 1 = top, 2 = bottom)
  • margin – Margin to leave around game object when it has been docked [left, right, top, bottom]
  • bubbling – If true then touch events will be allowed to bubble up to parents
  • clip_children – If set to true then children will be clipped against extents of this one
  • clip_margin – Margin to leave around clipping [left, top, right, bottom]
  • clip_shape – If set then this shape will be used to clip, otherwise the usual extents / shape of this game object will be used to clip
  • self_clip – If set to true then this game object will be clipped against its own clipping
  • orphaned – If true then will ignore parent transforms
  • virtual – Set to true if supports a virtual canvas
  • anim_frames – Array of animation frame indices, if not set then frames will be used in order specified in the atlas
  • shadow – When set to true this object will show a shadow
  • shadow_x, shadow_y – Shadow offset
  • shadow_blur – Amount to blur shadow
  • shadow_colour- Colour of shadow (e.g #ffffff)
  • composite_op – Composite operation to use when drawing this object (e.g source-over)
  • cache – When set to true this actors rendering will be cached (does not apply down the entire child hierarchy)
  • merge_cache – When set to true, will try to render this object into a parent cache, if one is available
  • round_pixels – If enabled then vertices will be rounded to integer which can speed up rendering significantly but at a loss of precision

Internal properties

  • type – Actor type
  • scene – Parent Scene
  • parent – Parent actor (If null then this game object does not belong to an hierarchy)
  • actors – Array of child actors
  • removals – Array of actors that should be deleted at end of frame
  • joints – Array of physics joints that are attached
  • timelines – A timeline manager that contains and manages animations local to this game object
  • actions – An actions list manager that contains and manages actions local to this game object
  • frame_count – Number of frames that this object has been running
  • accum_scale_x – Accumulated X scale
  • accum_scale_y – Accumulated Y scale
  • accum_opacity – Accumulative opacity
  • body – Box2D body
  • transform – Current transform
  • transform_dirty – If set to true then transforms will be rebuilt next update
  • touching – Set to true when user is touching
  • touchmove – Set to true when touch is moving on this game object
  • layer – The visible layer that this object sits on
  • order_changed – When layer changes this property is marked as true to let the system know to resort all objects on the layer
  • cache_canvas – A canvas that contains cached drawing for this actor

Virtual canvas properties

These properties are only available if created with a virtual canvas or is made to support a virtual canvas using makeVirtual()

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

Setters

  • _x – Sets the x property
  • _y – Sets the y property
  • _ox – Sets the ox property
  • _oy – Sets the oy property
  • _rotation – Sets the rotation property
  • _scale – Sets both x and y scale property to the same value
  • _scale_x – Sets the scale_x property
  • _scale_y – Sets the scale_y property
  • _depth – Sets the depth property
  • _layer – Sets visible layer
  • _atlas – Sets the ImageAtlas from a path to or an instance of an ImageAtlas
  • _bitmap – Sets the Bitmap from a path to or an instance of a Bitmap
  • _clip_shape  – Sets the slipping shape from a path to or an instance of a Shape

Note: Use these setters instead of the likes of x, y, ox, oy etc.. to ensure that this game objects internal transform gets updated

Constants

  • Actor.Dock_None – No docking
  • Actor.Dock_Left – Docks to the left edge
  • Actor.Dock_Right – Docks to the right edge
  • Actor.Dock_Top – Docks to the top edge
  • Actor.Dock_Bottom – Docks to the bottom edge

Events

  • onCreate() – Called just after creation
  • onDestroy() – Called just before destruction
  • onTick(delta_time) – Called each update (every frame)
  • onTapped(touch_pos) – Called when tapped / clicked
  • onBeginTouch(touch_pos) – Called when user is touching
  • onEndTouch(touch_pos) – Called when user stops being touching
  • onLostTouchFocus(touch_pos) – Called when object loses touch focus
  • onMoveTouch(touch_pos) – Called when a touch is moved over the game object
  • onCollisionStart(contact) – Called when this game object starts colliding with another
  • onCollisionEnd(contact) – Called when this game object stops colliding with another

Methods

Actor(virtual) – Creates instance of an Actor object

  • virtual – If set to true then the actor will have a virtual canvas attached that can scroll / dock its child actors

setPosition(x, y) – Sets the scene position (causes internal transform to be recalculated if values differ to existing values).

  • x – X axis position
  • y – Y axis position

setPositionPhysics(x, y) – deprecated

setOrigin(x, y) – Sets the origin (causes internal transform to be recalculated if values differ to existing values).

  • x – X axis origin
  • y – Y axis origin

setScale(x, y) – Sets the scale (causes internal transform to be recalculated if values differ to existing values).

  • x – X axis scaling factor
  • y – Y axis scaling factor

setRotation(angle) – Sets the rotation angle (causes internal transform to be recalculated if values differ to existing values).

  • angle – Rotation in radians

setRotationPhysics(angle) – Deprecated

setDepth(depth) – Sets the actors 3D depth (causes internal transform to be recalculated if values differ to existing values). Actors with a depth value of anything other than 0 and 1 will undergo perspective transformation, the affect of this is that the actor will be scaled in size depending upon distance, the actors position will also be adjusted to take into account its depth.

  • depth – Depth value, 0 is the same as 1.0, greater values will project the actor further into the distance

release() – Releases the actor, this is called by the scene or actor systems when an actor has been destroyed.

destroy() – Begins the destruction of this game object, note that it will not actually be destroyed until the end of the scene or parent actors processing.

changeParent(parent) – Changes the actors parent to the new parent

  • parent – The new parent

addActor(actor) – Adds an actor to this actors list of children

  • actor –  The actor to add

removeActor(actor) – Removes the specified actor from this actors list of children

  • actor –  The actor to remove

removeActorsWithTag(tag) – Removes all child actors that have the specified tag.

  • tag –  A string tag

cleanupDestroyedActors() – Cleans up all destroyed actors, this is called by the actor to clean up any removed actors at the end of its update cycle.

findActor(name, recursive) – Searches child list for the named actor.

  • name: The name of the actor
  • recursive – If true then the complete child hierarchy will be searched
  • returns the found actor or null if not found

findFirstParent() – Travels up the child hierarchy to return the very first Actor parent

updateParenTransforms() – Travels up the child hierarchy updating all parent transforms

bringToFront() – Moves the actor to the end of the child list, bringing it to the front of all others in the parent.

sendToBack() – Moves the actor to the start of the child list, pushing it to the back of all others in the parent.

releaseBody() – Releases the attached physics body.

releaseJoints() – Releases all attached physics joints.

initBody(body_type, fixed_rotation, is_bullet) – Creates and attached a physics body to this actor, putting it under control of the Box2D physics system.

  • body_type – Type of body, can be either static, dynamic or kinematic
  • fixed_rotation – true if you want to fix rotation so that it cannot change
  • is_bullet – true if this is a very fast moving game object

addFixture(options) – Creates a new fixture and attaches it to the physics body.

  • options – An object describing the fixtures properties
    • type – Type of fixture (Shape.TypeBox, Shape.TypeCircle or Shape.TypePolygon)
    • density – Fixture density
    • friction – Fixture friction
    • restitution – Fixture restitution
    • is_sensor – true if this fixture is a sensor
    • width / height – Width and height of box (if type is box)
    • radius – Radius of shape (if type is circle)
    • points – An array of points of form [x1, y1, x2, y2 etc] that define a shape (if type is polygon)
  • returns the created fixture or in the case of a multi-fixture shape an array of fixtures

addJoint(options) – Creates a new joint and attaches it to the physics body.

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

removeJoint(joint) – Removes the specified joint from the joints list and destroys the joint.

  • joint – The joint to remove and destroy

updateTransform() – Forces the internal visual transform to update, call internally when the transform is dirtied.

draw() – Draws this actor and its children, this method can be overriden by derived actors

drawToCache() – Draws this actor to a cached canvas, subsequent calls to draw() will cause this cached canvas to be drawn instead

preDraw() – Pre drawing shared functionality

postDraw() – Post drawing shared functionality

baseUpdate(dt) – Base update function that should be called by all derived actors that wish to use base actor functionality, this is usually called from your update() method.

  • dt – The amount of time that has passed since last updated
  • returns true if active

update(dt) – Updates the actor, this method can be overriden by derived actors

  • dt – The amount of time that has passed since the last update
  • returns true if active

updateToPhysics() – Copies actor velocities to the physics system

dirty() – Dirties the game object and all child transforms

hitTest(position) – Performs a test of the specified position against the boundaries of the actor returning true if a hit occurs

  • position – The 2D position to test

transformPoint(x, y) – Transforms the point into the actors coordinate system

  • x,y – The 2D position to test
  • returns the transformed point as a point object {x, y}

overlaps(other) – Tests if two actors overlap

  • other – The other actor to test for overlap
  • returns true if both overlap

makeVirtual() – Attaches a virtual canvas

setClipping(context, x, y) – Used internally to set the clipping shape for this actor

  • context – Display context
  • x – x coordinate of clip
  • y – y coordinate of clip

Examples

Basic actor creation

Adding a bitmap image to an actor

Adding a bitmap image from the scene resources to an actor

Adding basic physics to an actor

Adding bitmap animation to an actor

Add a child actor

Adding an onTick event handler to an actor

Adding touch event handlers to an actor

Docking an actor to the edges of the scene

Adding an actions list

 

1,351 total views, 1 views today