Class: ParticleActor

b5. ParticleActor

b5.ParticleActor

new b5.ParticleActor(){b5.ParticleActor}

actor/particleActor.js, line 78

A ParticleActor is derived from a b5.Actor and is an actor that can generate and display particles (a particle system), a particle can be an actor of any kind, including another particle actor. To use a particle system actor you create an instance of ParticleActor then create and add individual actor particles, specifying a life span (the amount of time the particle exists), a spawn delay (the amount of time to wait before spawning the particle) and the total number of times the particle can be reborn. When a particle system has no particles left alive it will be destroyed. A ParticleActor should be added to a b5.Scene or another b5.Actor that is part of a scene hierarchy

Supports the following event handlers:

  • onParticlesEnd() - Called when The particle system has finished and no particles are left
  • onParticleLost(particle) - Called each time a particle is lost, if this function returns false then the particle will not be destroyed

Note that when an actor is added to a particle actor it is given the following additional properties:

  • vo - Opacity velocity
  • vsx - X axis scale velocity
  • vsy - Y axis scale velocity

Example of creating a particle system particle by particle:

 var particles = new b5.ParticleActor();
 particles.gravity = 40;
 my_scene.addActor(particles);   // Add particle system actor to scene for processing
 for (var t = 0; t < 20; t++)
 {
     var particle = new b5.Actor();
     particle.fill_style = "#FFFF00";
     particle.radius = 30;
     particle.vx = Math.random() * 200 - 100;
     particle.vy = Math.random() * 200 - 100;
     particle.vo = -1 / 2;
     particles.addParticle(particle, 2, 0, t * 0.1);
 }

Example of creating a particle explosion using the utility method:

 var particles = new b5.ParticleActor();
 my_scene.addActor(particles);     // Add particle system actor to scene for processing
 particles.generateExplosion(50, b5.ArcActor, 2, 50, 10, 1, 0.999, {
     fill_style: "#ffff00",
     radius: 30
 );

Example of creating a particle system that represents a smoke plume using a utility method:

 var particles = new b5.ParticleActor();
 my_scene.addActor(particles);     // Add particle system actor to scene for processing
 particles.generatePlume(20, b5.ArcActor, 3, 40, 10, 0.25, 1, {
     fill_style: "#ffff00",
     radius: 20,
     vsx: 0.6,
     vsy: 0.6
 });

Examples

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

Properties:
Name Type Description
gravity number

Amount of gravity to apply to particles (default is 0)

Returns:
Type Description
b5.ParticleActor The created ParticleActor

Extends

Methods

inherited 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

inherited 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

inherited 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

addParticle(actor, life_span, num_lives, spawn_delay){b5.Actor}

actor/particleActor.js, line 135

Adds an actor to the particle system as a particle

Name Type Description
actor b5.Actor

The actor to add as a particle, can be any derived actor type

life_span number

The life span of the particle in seconds

num_lives number

The number of times a particle will respawn before it is destroyed (0 for infinite)

spawn_delay number

The number of seconds to wait before spawning this particle

Returns:
Type Description
b5.Actor The created actor particle

inherited 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

inherited 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

inherited 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

inherited destroy()

actor/actor.js, line 587

Destroys the actor, removing it from the scene

inherited dirty()

actor/actor.js, line 1670

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

inherited 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

inherited drawToCache()

actor/actor.js, line 1434

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

inherited 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

inherited 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

inherited 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

inherited 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

generateExplosion(count, type, duration, speed, spin_speed, rate, damping, properties)

actor/particleActor.js, line 255

Utility method to create a basic explosion particle system

Name Type Description
count number

Total number of particles to create

type object | string

The actor type of each particle created, for example b5.ArcActor or "ArcActor"

duration number

The total duration of the particle system in seconds

speed number

The speed at which the particles blow apart

spin_speed number

The speed at which particles spin

rate number

The rate at which particles are created

damping number

A factor to reduce velocity of particles each frame, values greater than 1 will increase velocities

properties object

A collection of actor specific property / value pairs that will be assigned to each created particle

generatePlume(count, type, duration, speed, spin_speed, rate, damping, properties)

actor/particleActor.js, line 288

Utility method to create a basic smoke plume particle system

Name Type Description
count number

Total number of particles to create

type object | string

The actor type of each particle created, for example b5.ArcActor or "ArcActor"

duration number

The total duration of the particle system in seconds

speed number

The speed at which the particles rise

spin_speed number

The speed at which particles spin

rate number

The rate at which particles are created

damping number

A factor to reduce velocity of particles each frame, values greater than 1 will increase velocities

properties object

A collection of actor specific property / value pairs that will be assigned to each created particle

generateRain(count, type, duration, speed, spin_speed, rate, damping, width, properties)

actor/particleActor.js, line 322

Utility method to create a basic rain particle system

Name Type Description
count number

Total number of particles to create

type object | string

The actor type of each particle created, for example b5.ArcActor or "ArcActor"

duration number

The total duration of the particle system in seconds

speed number

The speed at which the particles fall

spin_speed number

The speed at which particles spin

rate number

rate at which particles are created

damping number

A factor to reduce velocity of particles each frame, values greater than 1 will increase velocities

width number

The width of the area over which to generate particles

properties object

A collection of actor specific property / value pairs that will be assigned to each created particle

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited 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

inherited release()

actor/actor.js, line 576

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

inherited releaseBody()

actor/actor.js, line 905

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

inherited releaseJoints()

actor/actor.js, line 917

Releases all joints that this actor created, destroying the joints

inherited removeActor(actor)

actor/actor.js, line 640

Removes the specified actor from this actors child list

Name Type Description
actor b5.Actor

An actor

inherited 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

inherited removeJoint(joint)

actor/actor.js, line 1213

Removes and destroys the specified joint

Name Type Description
joint object

The joint to remove

inherited 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

inherited 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

inherited setOrigin(x, y)

actor/actor.js, line 495

Sets the actors render origin

Name Type Description
x number

X coordinate

y number

Y coordinate

inherited setPosition(x, y)

actor/actor.js, line 471

Sets the actors scene position

Name Type Description
x number

X coordinate

y number

Y coordinate

inherited setRotation(angle)

actor/actor.js, line 522

Sets the actors rotation

Name Type Description
angle number

Angle in radians

inherited setScale(x, y)

actor/actor.js, line 509

Sets the actors scale

Name Type Description
x number

X scale

y number

Y scale

inherited 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/particleActor.js, line 180

Overrides the base b5.Actor.update() method to perform particle system update

Name Type Description
dt number

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

inherited updateParentTransforms()

actor/actor.js, line 778

Updates the transforms of all parents of this actor

inherited updateToPhysics()

actor/actor.js, line 1657

Copies actor velocities to the physics body

inherited 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