PhysicsSystem Class
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
Parameters:
-
entitySystemManager
ManagerThe entity system manager whose entities this system will be working on.
Item Index
Methods
- contactData.collisionData.getCollisionNormal
- contactData.collisionData.getNormalImpulse
- contactData.collisionData.getPenetration
- contactData.collisionData.getTangentImpulse
- contactData.getEntityA
- contactData.getEntityB
- contactData.preventCollisionSolving
- debugDraw.entities
- debugDraw.quadTree
- destroy
- subscribe
- trigger
- unsubscribe
- update
- world.configure.setNumberOfTestsPerFrameForFastObjects
- world.initialize
- world.queryEntitiesWithAABB
- world.queryEntitiesWithRay
- world.queryEntitiesWithShape
Methods
contactData.collisionData.getCollisionNormal
-
vector
This method is valid in all event callbacks.
Parameters:
-
vector
Vector2DVector 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
Vector2DVector to which the impulse will be copied.
contactData.collisionData.getPenetration
()
Number
This method is valid in all event callbacks.
Returns:
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
Vector2DVector to which the impulse will be copied.
contactData.getEntityA
()
Entity
Returns the first entity of the contact pair.
Returns:
contactData.getEntityB
()
Entity
Returns the second entity of the contact pair.
Returns:
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
ViewView to be rendered to.
-
drawAABBs
BooleanSpecifies whether Axis-Aligned Bounding Boxes should be rendered for the entities.
-
drawVelocities
BooleanSpecifies whether velocity vectors should be rendered for dynamic physics bodies.
debugDraw.quadTree
-
view
Draws the spatial partitioning object.
Parameters:
-
view
ViewView to be rendered to.
destroy
()
subscribe
-
event
-
callback
-
[subscriber]
Parameters:
-
event
StringName of the event being subscribed to.
-
callback
FunctionFunction that will be called back when the specified event is triggered.
-
[subscriber]
Object optionalAn 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
StringThe event to be triggered.
-
[eventObject]
Object optionalAll 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
NumberThe 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
NumberThe 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
NumberThe width of the world.
-
height
NumberThe height of the world.
-
maximumEntitiesPerLeaf
NumberThe 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
NumberThe 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
Returns an array of entities whose Axis-Aligned Bounding Boxes overlap the one specified as the parameter.
Parameters:
-
AABB
AABBThe AABB describing area from which entities should be retrieved.
Returns:
world.queryEntitiesWithRay
-
ray
-
[category]
-
[collideWith]
Returns an the first entity that intersects the ray from the ray's begin point.
Parameters:
-
ray
RayThe querying ray.
-
[category]
Number optionalA bit mask used to filter the entities being queried. Same as the category on the Collidable component.
-
[collideWith]
Number optionalA bit mask used to filter the entities being queried. Same as the collideWith on the Collidable component.
Returns:
world.queryEntitiesWithShape
-
position
-
shape
-
[category]
-
[collideWith]
Returns an array of entities whose shapes overlap the specified shape.
Parameters:
-
position
PositionPosition of the querying shape.
-
shape
ShapeThe shape describing the area from which entities should be retrieved.
-
[category]
Number optionalA bit mask used to filter the queried entities. Same as the category on the Collidable component.
-
[collideWith]
Number optionalA bit mask used to filter the queried entities. Same as the collideWith on the Collidable component.
Returns:
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.