Ammo.js Compound Shape Max Child Shapes

This article provides a quick overview of the recommended maximum number of child shapes for a compound shape in ammo.js. It explains the practical performance limits, the impact of complex collision shapes on web-based physics simulations, and alternative strategies for handling complex 3D geometry efficiently.

In ammo.js—the JavaScript port of the Bullet physics engine—there is no hard-coded technical limit on the number of child shapes you can add to a btCompoundShape. However, for optimal real-time performance in web browsers, it is highly recommended to keep the number of child shapes under 15 to 20 for dynamic (moving) bodies, and under 50 for static bodies.

The primary constraint is CPU performance. Every active child shape in a dynamic compound shape increases the overhead of the collision detection pipeline. During every physics step, the engine must perform broadphase and narrowphase collision tests against the child shapes. If a moving body contains dozens of child shapes, it will quickly bottleneck the single-threaded JavaScript execution environment, leading to noticeable frame rate drops.

To maintain a smooth 60 frames per second, you should employ the following optimization strategies when designing collision shapes:

• Use Simple Primitives: Construct your compound shapes using basic primitives like spheres, boxes, and capsules. These shapes have highly optimized mathematical formulas for collision detection, which require far less CPU power than convex hulls.
• Convex Decomposition: For highly complex dynamic objects, do not manually build massive compound shapes. Instead, use a convex decomposition tool (such as V-HACD) to simplify the 3D mesh into a small set of convex hulls—ideally fewer than 10.
• Avoid Compound Shapes for Static Worlds: If you are building static environment collision structures (like terrain or buildings), do not use btCompoundShape. Instead, use btBvhTriangleMeshShape, which utilizes an optimized bounding volume hierarchy designed specifically for static, complex meshes.