API Docs for:
Show:

PhysicsSystem Class

Extends EventHandler
Defined in: physics\System.js:1

This system is responsible for handling physics for entities. All entities that have the Position, Movable and Shape components are treated as dynamic physics bodies. All entities that have the Position and Shape components, but don't have the Movable component are treated as static physics bodies. Entities that have the Collidable component are also valid candidates for collision detection. To update a position of a static body, it should have one of the required components removed and added again. Directly changing a position of a static entity doesn't update its position in the system. This physics system works with the standard 2D coordinate system where the x axis grows left to right and the y axis grows top to bottom. Please keep this in mind when working with this system and the components and objects it requires. When the system handles collisions between entities, it will send events. A "contactDetected" event is sent when two entities overlap. A "collisionDetected" event is sent when two entities are collidable with one another. A "collisionResolved" event is sent once the collision between two entities is resolved. All events send a contact object. The contact object is described in the documentation as a property on the system.

Constructor

PhysicsSystem

(
  • entitySystemManager
)

Defined in physics\System.js:1

Parameters:

  • entitySystemManager Manager

    The entity system manager whose entities this system will be working on.

Methods

contactData.collisionData.getCollisionNormal

(
  • vector
)

This method is valid in all event callbacks.

Parameters:

  • vector Vector2D

    Vector to which the normal will be copied.

contactData.collisionData.getNormalImpulse

(
  • vector
)

This method is valid only in the "collisionResolved" event callback. The method retrieves the total impulse along the contact normal for this collision. It describes how "hard" both entities "bounced off" of each other.

Parameters:

  • vector Vector2D

    Vector to which the impulse will be copied.

contactData.collisionData.getPenetration

() Number

This method is valid in all event callbacks.

Returns:

Number:

contactData.collisionData.getTangentImpulse

(
  • vector
)

This method is valid only in the "collisionResolved" event callback. The method retrieves the total impulse along the contact surface for this collision. It describes friction.

Parameters:

  • vector Vector2D

    Vector to which the impulse will be copied.

contactData.getEntityA

() Entity

Returns the first entity of the contact pair.

Returns:

Entity: The first entity of the contact pair.

contactData.getEntityB

() Entity

Returns the second entity of the contact pair.

Returns:

Entity: The second entity of the contact pair.

contactData.preventCollisionSolving

()

This function can be used to prevent a collision from being solved. Its usage is only valid in the "collisionDetected" event callback.

debugDraw.entities

(
  • view
  • drawAABBs
  • drawVelocities
)

Draws the physical representations of all entities.

Parameters:

  • view View

    View to be rendered to.

  • drawAABBs Boolean

    Specifies whether Axis-Aligned Bounding Boxes should be rendered for the entities.

  • drawVelocities Boolean

    Specifies whether velocity vectors should be rendered for dynamic physics bodies.

debugDraw.quadTree

(
  • view
)

Draws the spatial partitioning object.

Parameters:

  • view View

    View to be rendered to.

destroy

()

subscribe

(
  • event
  • callback
  • [subscriber]
)

Parameters:

  • event String

    Name of the event being subscribed to.

  • callback Function

    Function that will be called back when the specified event is triggered.

  • [subscriber] Object optional

    An optional parameter that specifies an object that's subscribing. When a function is subscribed with an object, that function will be called back with "this" set to the object.

trigger

(
  • event
  • [eventObject]
)

Triggers the event, calling all functions that subscribed to it.

Parameters:

  • event String

    The event to be triggered.

  • [eventObject] Object optional

    All functions that were subscribed to the specified event will be called with this as the argument.

unsubscribe

(
  • event
  • [callback]
  • [subscriber]
)

This is a multi-purpose method. See the example for all the ways it can be overloaded.

Parameters:

  • event Object
  • [callback] Object optional
  • [subscriber] Object optional

Example:

   //Unsubscribing all callbacks for a given event.
  eventHandler.unsubscribe('eventName');

  //Unsubscribing all callbacks subscribed by the object.
  eventHandler.unsubscribe(object);

  //Unsubscribing all callbacks an object made for the given event.
  eventHandler.unsubscribe('eventName', object);

  //Unsubscribing a callback that was subscribed with an object.
  eventHandler.unsubscribe('eventName', callback, object);

  //Unsubscribing a callback subscribed by itself.
  eventHandler.unsubscribe('eventName', callback);
  //The last method can't be used to unsubscribe callbacks which were subscribed with an object.

update

(
  • deltaTime
)

Steps the world.

Parameters:

  • deltaTime Number

    The time that passed since last update.

world.configure.setNumberOfTestsPerFrameForFastObjects

(
  • number
)

This function specifies how many tests per frame should be performed to prevent fast moving objects from passing through other objects.

Parameters:

  • number Number

    The amount of tests to be performed.

world.initialize

(
  • width
  • height
  • maximumEntitiesPerLeaf
  • maximumLeafDepth
)

Sets up the system's environment. This function needs to be called at least once before updating the system.

Parameters:

  • width Number

    The width of the world.

  • height Number

    The height of the world.

  • maximumEntitiesPerLeaf Number

    The maximum number of entities that a leaf of the entity quad tree used to parse space can contain before it splits. This variable should be dependant on the size of entities. It should be easy to tweak when using debug drawing.

  • maximumLeafDepth Number

    The maximum number of times that the entity quad tree used to parse space can split. This variable should be dependant on the size of entities. It should be easy to tweak when using debug drawing.

world.queryEntitiesWithAABB

(
  • AABB
)
Array

Returns an array of entities whose Axis-Aligned Bounding Boxes overlap the one specified as the parameter.

Parameters:

  • AABB AABB

    The AABB describing area from which entities should be retrieved.

Returns:

Array: Array holding the retrieved entities. This function always returns the same array, so the data contained in it isn't persistent. If it's required for the data to be persistent, copy it using slice.

world.queryEntitiesWithRay

(
  • ray
  • [category]
  • [collideWith]
)
Object | Null

Returns an the first entity that intersects the ray from the ray's begin point.

Parameters:

  • ray Ray

    The querying ray.

  • [category] Number optional

    A bit mask used to filter the entities being queried. Same as the category on the Collidable component.

  • [collideWith] Number optional

    A bit mask used to filter the entities being queried. Same as the collideWith on the Collidable component.

Returns:

Object | Null: Object holding the contact data if the ray intersects an entity, otherwise null. The object has three fields, entity holding the entity that intersects the ray, contactPoint of the type Vector2D storing the point of intersection and contactNormal of the type Vector2D which holds the surface normal at the point of intersection.

world.queryEntitiesWithShape

(
  • position
  • shape
  • [category]
  • [collideWith]
)
Array

Returns an array of entities whose shapes overlap the specified shape.

Parameters:

  • position Position

    Position of the querying shape.

  • shape Shape

    The shape describing the area from which entities should be retrieved.

  • [category] Number optional

    A bit mask used to filter the queried entities. Same as the category on the Collidable component.

  • [collideWith] Number optional

    A bit mask used to filter the queried entities. Same as the collideWith on the Collidable component.

Returns:

Array: Array holding the retrieved entities. This function always returns the same array, so the data contained in it isn't persistent. If it's required for the data to be persistent, copy it using slice.

Properties

configure

Object final

Interface for configuring the system.

contactData

Object final

This is the contact object that's sent with all contact and collision events. Every event uses the same object, so the data contained in it is not persistent outside of the event callback functions.

contactData.collisionData

Object final

This object contains the collision data for the entity pair.

debugDraw

Object final

The debugging interface. It's used to render the physical representation of entities as well as the spatial partitioning object used by the engine.

debugDraw.configure

Object final

This object is used to set the colors of the objects being drawn as well as line thickness.

debugDraw.configure.dynamicEntitiesColor

String

Specifies the color used when rendering dynamic physics bodies.

Default: 'green'

debugDraw.configure.lineThickness

Number

Specifies line thickness for rendered objects.

Default: 1

debugDraw.configure.quadTreeColor

String

Specifies the color used when rendering the spatial partitioning object.

Default: 'blue'

debugDraw.configure.staticEntitiesColor

String

Specifies the color used when rendering static physics bodies.

Default: 'red'

world

Object final

Interface for working with the world.