A little bit inline documentation, for local scaling of Bullet shapes.

panda/src/bullet/bulletBodyNode.cxx

@@ -192,12 +192,15 @@ add_shape(BulletShape *shape, CPT(TransformState) ts) {
     nassertv(previous->getShapeType() == EMPTY_SHAPE_PROXYTYPE);
 
     if (ts) {
-      // One shape, with transform
+      // After adding the shape we will have a total of one shape, without 
+      // local transform. We can set the shape directly.
       next = new btCompoundShape();
       ((btCompoundShape *)next)->addChildShape(trans, shape->ptr());
     }
     else {
-      // One shape, w/o transform
+      // After adding the shape we will have one shape, but with transform.
+      // We need to wrap the shape within a compound shape, in oder to
+      // be able to set the local transform.
       next = shape->ptr();
     }
 
@@ -207,27 +210,35 @@ add_shape(BulletShape *shape, CPT(TransformState) ts) {
     delete previous;
   }
   else if (_shapes.size() == 1) {
-    // Two shapes. Previous shape might already be a compound.
     if (previous->getShapeType() == COMPOUND_SHAPE_PROXYTYPE) {
+      // We have one shape, and add another shape. The previous shape is
+      // already a compound shape. So we just need to add the second shape
+      // to the compound shape.
       next = previous;
+
+      ((btCompoundShape *)next)->addChildShape(trans, shape->ptr());
     }
     else {
+      // We have one shape which is NOT a compound shape, and want to add
+      // a second shape. We need to wrap both shapes within a compound shape.
       next = new btCompoundShape();
 
       btTransform previous_trans = btTransform::getIdentity();
       ((btCompoundShape *)next)->addChildShape(previous_trans, previous);
-    }
-
-    ((btCompoundShape *)next)->addChildShape(trans, shape->ptr());
+      ((btCompoundShape *)next)->addChildShape(trans, shape->ptr());
 
-    get_object()->setCollisionShape(next);
-    _shape = next;
+      get_object()->setCollisionShape(next);
+      _shape = next;
+    }
   }
   else {
-    // Three or more shapes. Previous shape is always a compound
+    // We already have two or more shapes, and want to add another. So we
+    // already have a compound shape as wrapper, and just need to add the
+    // new shape to the compound.
     nassertv(previous->getShapeType() == COMPOUND_SHAPE_PROXYTYPE);
 
-    ((btCompoundShape *)previous)->addChildShape(trans, shape->ptr());
+    next = previous;
+    ((btCompoundShape *)next)->addChildShape(trans, shape->ptr());
   }
 
   _shapes.push_back(shape);