Merge pull request #20 from diarmidmackenzie/ammo-perf

Ammo performance improvements

Author: diarmidmackenzie

AmmoDriver.md

@@ -134,7 +134,15 @@ An `ammo-body` component may be added to any entity in a scene. While having onl
 The `type` of an ammo body can be one of the following:
 
 - `dynamic`: A freely-moving object. Dynamic bodies have mass, collide with other bodies, bounce or slow during collisions, and fall if gravity is enabled.
+
 - `static`: A fixed-position object. Other bodies may collide with static bodies, but static bodies themselves are unaffected by gravity and collisions. These bodies should typically not be moved after initialization as they cannot impart forces on `dynamic` bodies.
+
+  - If you do re-position a static object after initialization, you'll need to explicitly update the physics system with the new position.  You can do that like this:
+
+    ```
+    this.el.components['ammo-body'].syncToPhysics();
+    ```
+
 - `kinematic`: Like a `static` body, except that they can be moved via updating the position of the entity. Unlike a `static` body, they impart forces on `dynamic` bodies when moved. Useful for animated or remote (networked) objects.
 
 #### Activation States
@@ -252,6 +260,10 @@ Any entity with an `ammo-body` component can also have 1 or more `ammo-shape` co
 - `fit: all` – Requires a mesh to exist on the entity. The specified shape will be created to contain all the vertices of the mesh.
 - `fit: manual` – Does not require a mesh, however you must specifiy either the `halfExtents` or `sphereRadius` manually. This is not supported for `hull`, `hacd`, `vhacd` and `mesh` types.
 
+Note that in general, `fit: manual` is more performant than `fit: all`.  This is because  `fit: all` iterates over every point in the geometry to determine a suitable bounding volume, whereas `fit: manual` can just create the shape to the specified parameters.  This is particularly important if you are going to be spawning new instances of objects while the physics simulation is ongoing.
+
+Note that there is currently no caching of shapes generated from geometries, so even if you are creating shapes for the same geometry over & over you'll still pay this performance penalty for each new `ammo-shape`.
+
 ### `ammo-constraint`
 
 The `ammo-constraint` component is used to bind `ammo-bodies` together using hinges, fixed distances, or fixed attachment points. Note that an `ammo-shape` is not required for `ammo-constraint` to work, however you may get strange results with some constraint types.

dist/aframe-physics-system.js

@@ -16566,7 +16566,9 @@ let AmmoBody = {
 
   beforeStep: function() {
     this._updateShapes();
-    if (this.data.type !== TYPE.DYNAMIC) {
+    // Note that since static objects don't move,
+    // we don't sync them to physics on a routine basis.
+    if (this.data.type === TYPE.KINEMATIC) {
       this.syncToPhysics();
     }
   },

dist/aframe-physics-system.min.js

@@ -69,7 +69,8 @@ AFRAME.registerComponent('dynamic-ball', {
 
       if (this.data.physics === "ammo") {
           el.setAttribute('ammo-body', 'type:dynamic')
-          el.setAttribute('ammo-shape', 'type:sphere; fit:all')
+          // Explicitly specifying a shape is more efficient than auto-fitting.
+          el.setAttribute('ammo-shape', 'type:sphere; fit:manual; sphereRadius: 0.3')
       }
       else if (this.data.physics === "cannon") {
           // necessary to explicitly specify sphere radius, as async call to 

examples/components/pinboard.js

@@ -356,7 +356,9 @@ let AmmoBody = {
 
   beforeStep: function() {
     this._updateShapes();
-    if (this.data.type !== TYPE.DYNAMIC) {
+    // Note that since static objects don't move,
+    // we don't sync them to physics on a routine basis.
+    if (this.data.type === TYPE.KINEMATIC) {
       this.syncToPhysics();
     }
   },