The world space vector representing global gravity in the physics simulation. Defaults to [0, -9.81, 0] which is an approximation of the gravitational force on Earth.
Scales the time the simulation is advanced by each frame. Defaults to 1. Values below 1 run physics in slow motion and values above 1 speed it up. 0 pauses the simulation: the system stops advancing it, bodies freeze in place, entity transforms are no longer driven by their bodies and no contact or trigger events fire. The rest of the application keeps running, so this suits a pause menu or inventory screen that must stay interactive while the game world stands still. Negative values are treated as 0.
This scale is applied on top of AppBase#timeScale. The simulation can still be advanced manually with RigidBodyComponentSystem#step while paused, for example to drive it from a custom time source.
Slow motion that advances the simulation by less than one fixed substep per frame steps it intermittently; the Ammo backend interpolates body transforms between steps so motion stays smooth. Fast forward is limited by the maximum number of substeps the simulation may take per frame, beyond which it runs slower than requested.
Forces applied with RigidBodyComponent#applyForce while paused accumulate on the body and are applied together on the next step, because forces are only cleared when the simulation steps. Impulses and velocity changes take effect immediately.
Alpha
Gets the installed physics backend, or null when no backend is installed. Supply a backend via AppOptions#physicsWorld, or load the Ammo.js library to have one installed automatically.
Fire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optionalarg1: any
First argument that is passed to the event handler.
Optionalarg2: any
Second argument that is passed to the event handler.
Optionalarg3: any
Third argument that is passed to the event handler.
Optionalarg4: any
Fourth argument that is passed to the event handler.
Optionalarg5: any
Fifth argument that is passed to the event handler.
Optionalarg6: any
Sixth argument that is passed to the event handler.
Optionalarg7: any
Seventh argument that is passed to the event handler.
Optionalarg8: any
Eighth argument that is passed to the event handler.
Self for chaining.
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Use this form to remove all listeners matching a name (and optionally callback/scope). To remove a single known subscription, prefer retaining the EventHandle returned by EventHandler#on / EventHandler#once and calling its EventHandle#off: it removes exactly that subscription and is faster (no scan of the callback list).
Optionalname: string
Name of the event to unbind.
Optionalcallback: HandleEventCallback
Function to be unbound.
Optionalscope: any
Scope that was used as the this when the event is fired.
Self for chaining.
const handler = () => {};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optionalscope: any = ...
Object to use as 'this' when the event is fired, defaults to current this.
An event handle. For later removal, prefer retaining this handle and calling its EventHandle#off over EventHandler#off with a name/callback: it removes exactly this subscription and is faster (no scan of the callback list).
Attach an event handler to an event. This handler will be removed after being fired once.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optionalscope: any = ...
Object to use as 'this' when the event is fired, defaults to current this.
An event handle. For removal before it fires, prefer retaining this handle and calling its EventHandle#off over EventHandler#off with a name/callback: it removes exactly this subscription and is faster (no scan of the callback list).
Raycast the world and return all entities the ray hits. It returns an array of RaycastResult, one for each hit. If no hits are detected, the returned array will be of length 0. Results are sorted by distance with closest first.
The world space point where the ray starts.
The world space point where the ray ends.
Optionaloptions: {The additional options for the raycasting.
OptionalfilterCallback?: FunctionCustom function to use to filter entities. Must return true to proceed with result. Takes the entity to evaluate as argument.
OptionalfilterCollisionGroup?: numberCollision group to apply to the raycast.
OptionalfilterCollisionMask?: numberCollision mask to apply to the raycast.
OptionalfilterTags?: any[]Tags filters. Defined the same way as a Tags#has query but within an array.
Optionalsort?: booleanWhether to sort raycast results based on distance with closest first. Defaults to false.
An array of raycast hit results (0 length if there were no hits).
// Return all results of a raycast between 0, 2, 2 and 0, -2, -2
const hits = this.app.systems.rigidbody.raycastAll(new Vec3(0, 2, 2), new Vec3(0, -2, -2));
// Return all results of a raycast between 0, 2, 2 and 0, -2, -2
// where hit entity is tagged with `bird` OR `mammal`
const hits = this.app.systems.rigidbody.raycastAll(new Vec3(0, 2, 2), new Vec3(0, -2, -2), {
filterTags: [ "bird", "mammal" ]
});
// Return all results of a raycast between 0, 2, 2 and 0, -2, -2
// where hit entity has a `camera` component
const hits = this.app.systems.rigidbody.raycastAll(new Vec3(0, 2, 2), new Vec3(0, -2, -2), {
filterCallback: (entity) => entity && entity.camera
});
// Return all results of a raycast between 0, 2, 2 and 0, -2, -2
// where hit entity is tagged with (`carnivore` AND `mammal`) OR (`carnivore` AND `reptile`)
// and the entity has an `anim` component
const hits = this.app.systems.rigidbody.raycastAll(new Vec3(0, 2, 2), new Vec3(0, -2, -2), {
filterTags: [
[ "carnivore", "mammal" ],
[ "carnivore", "reptile" ]
],
filterCallback: (entity) => entity && entity.anim
});
Raycast the world and return the first entity the ray hits. Fire a ray into the world from start to end, if the ray hits an entity with a collision component, it returns a RaycastResult, otherwise returns null.
The world space point where the ray starts.
The world space point where the ray ends.
Optionaloptions: {The additional options for the raycasting.
OptionalfilterCallback?: FunctionCustom function to use to filter entities. Must return true to proceed with result. Takes one argument: the entity to evaluate.
OptionalfilterCollisionGroup?: numberCollision group to apply to the raycast.
OptionalfilterCollisionMask?: numberCollision mask to apply to the raycast.
OptionalfilterTags?: any[]Tags filters. Defined the same way as a Tags#has query but within an array.
The result of the raycasting or null if there was no hit.
Advances the physics simulation by dt seconds. Synchronizes triggers, compound shapes and kinematic bodies from their entities, steps the backend in fixed-length substeps (up to a maximum number per call), writes the resulting transforms of dynamic bodies back to their entities and fires contact and trigger events.
The system calls this once per frame with the frame delta time multiplied by RigidBodyComponentSystem#timeScale, unless that is 0. Call it directly to step the simulation manually: to advance it while paused, to fast forward it by stepping several times in one frame, or to drive it from a custom time source. Automatic stepping continues while timeScale is above 0, so calling this every frame as well advances the simulation twice per frame. Set timeScale to 0 first when taking over stepping entirely. The delta is used as given, without applying timeScale. Does nothing when no physics backend is installed.
The amount of time to advance the simulation by, in seconds.
StaticEVENT_Fired when a contact occurs between two rigid bodies. The handler is passed a SingleContactResult object containing details of the contact between the two bodies.
The RigidBodyComponentSystem manages the physics simulation for all rigid body components in the application. It creates and maintains the underlying physics world, handles physics object creation and destruction, performs physics raycasting, detects and reports collisions, and updates the transforms of entities with rigid bodies after each physics step.
The system controls global physics settings like gravity and provides methods for raycasting and collision detection.
This system is only functional once a physics backend is installed: either by supplying AppOptions#physicsWorld when creating the application, or automatically when the application has loaded the Ammo.js WasmModule.
The simulation is stepped automatically once per frame. Set RigidBodyComponentSystem#timeScale to slow it down, speed it up or pause it, for example while a pause menu is open, and call RigidBodyComponentSystem#step to advance the simulation manually.