Components for A-Frame physics integration, built on CANNON.js.
NOTE: This package is included by default in A-Frame Extras, or can be used as a standalone physics system.
In the dist/ folder, download the full or minified build. Include the script on your page, and all components are automatically registered for you:
CDN builds for aframe-physics-system/v3.0.0:
npm install --save aframe-physics-system
npm install -g browserifybrowserify my-app.js -o bundle.js
bundle.js may then be included in your page. See here for a better introduction to Browserify.
<!-- The debug:true option creates a wireframe around each physics body. If you don't see a wireframe,the physics system may be unable to parse your model without a shape:box or shape:hull option. --><!-- Camera --><!-- Floor --><!-- Immovable box --><!-- Dynamic box -->
static-body components may be added to any
<a-entity/> that contains a mesh. Generally, each scene will have at least one
static-body for the ground, and one or more
dynamic-body instances that the player can interact with.
||5||Simulated mass of the object, > 0.|
||0.01||Resistance to movement.|
||0.01||Resistance to rotation.|
||—||Override default radius of bounding sphere.|
||—||Override default axis of bounding cylinder.|
Body components will attempt to find an appropriate CANNON.js shape to fit your model. When defining an object you may choose a shape or leave the default,
auto. Select a shape carefully, as there are performance implications with different choices:
auto) – Chooses automatically from the available shapes.
box) – Great performance, compared to Hull or Trimesh shapes, and may be fitted to custom models.
cylinder) – See
sphere) – See
hull) – Wraps a model like shrink-wrap. Convex shapes are more performant and better supported than Trimesh, but may still have some performance impact when used as dynamic objects.
mesh) – Deprecated. Trimeshes adapt to fit custom geometry (e.g. a
.DAEfile), but have very minimal support. Arbitrary trimesh shapes are difficult to model in any JS physics engine, will "fall through" certain other shapes, and have serious performance limitations.
none) – Does not add collision geometry.
For more details, see the CANNON.js collision matrix.
Example using a bounding box for a custom model:
<!-- Box --><!-- Cylinder -->
constraint component is used to bind physics bodies together using hinges, fixed distances, or fixed attachment points.
||Type of constraint. Options:
|target||—||—||Selector for a single entity to which current entity should be bound.|
|maxForce||—||1e6||Maximum force that may be exerted to enforce this constraint.|
|collideConnected||—||true||If true, connected bodies may collide with one another.|
|wakeUpBodies||—||true||If true, sleeping bodies are woken up by this constraint.|
||auto||Distance at which bodies should be fixed. Default, or 0, for current distance.|
||0 0 0||Offset of the hinge or point-to-point constraint, defined locally in this element's body.|
||0 0 0||Offset of the hinge or point-to-point constraint, defined locally in the target's body.|
||0 0 1||An axis that each body can rotate around, defined locally to this element's body.|
||0 0 1||An axis that each body can rotate around, defined locally to the target's body.|
In A-Frame, each entity's
CANNON.Body instance is exposed on the
el.body property. To apply a quick push to an object, you might do the following:
var el = sceneEl;elbody;
NOTE: Collision events are currently only supported with the local driver, and will not be fired with
CANNON.js generates events when a collision is detected, which are propagated onto the associated A-Frame entity. Example:
var playerEl = document;playerEl;
Note that CANNON.js cannot perfectly detect collisions with very fast-moving bodies. Doing so requires Continuous Collision Detection, which can be both slow and difficult to implement. If this is an issue for your scene, consider (1) slowing objects down, (2) detecting collisions manually (collisions with the floor are easy –
position.y - height / 2 <= 0), or (3) attempting a PR to CANNON.js. See: Collision with fast bodies.
Contact materials define what happens when two objects meet, including physical properties such as friction and restitution (bounciness). The default, scene-wide contact materials may be configured on the scene element:
<!-- ... -->
NOTE: It is possible to run physics on a Web Worker using the
physics="driver: worker"option. Using a worker is helpful for maintaining a smooth framerate, because physics simulation does not block the main thread. However, scenes needing highly-responsive interaction (for example, tossing and catching objects) may prefer to run physics locally, where feedback from the physics system will be immediate.
|debug||true||Whether to show wireframes for debugging.|
|gravity||-9.8||Force of gravity (in m/s^2).|
|iterations||10||The number of solver iterations determines quality of the constraints in the world. The more iterations, the more correct simulation. More iterations need more computations though. If you have a large gravity force in your world, you will need more iterations.|
|maxInterval||0.0667||Maximum simulated time (in milliseconds) that may be taken by the physics engine per frame. Effectively prevents weird "jumps" when the player returns to the scene after a few minutes, at the expense of pausing physics during this time.|
|friction||0.01||Coefficient of friction.|
|restitution||0.3||Coefficient of restitution (bounciness).|
|contactEquationStiffness||1e8||Stiffness of the produced contact equations.|
|contactEquationRelaxation||3||Relaxation time of the produced contact equations.|
|frictionEquationStiffness||1e8||Stiffness of the produced friction equations.|
|frictionEquationRegularization||3||Relaxation time of the produced friction equations|
|workerFps||60||Steps per second to be used in physics simulation on worker.|
|workerInterpolate||true||Whether the main thread should interpolate physics frames from the worker.|
|workerInterpBufferSize||2||Number of physics frames to be 'padded' before displaying. Advanced.|
|workerDebug||false||If true, the worker codepaths are used on the main thread. This is slow, because physics snapshots are needlessly serialized, but helpful for debugging.|