Ammo.js btDefaultCollisionConfiguration Memory Guide

This article provides an overview of btDefaultCollisionConfiguration in ammo.js, explaining its role in collision detection setup and its direct impact on WebAssembly memory allocation. You will learn how this configuration class manages internal memory pools and how to optimize it to prevent memory bloat or out-of-memory crashes in your web-based 3D applications.

What is btDefaultCollisionConfiguration?

In Bullet Physics—and by extension, ammo.js (its Emscripten port to JavaScript and WebAssembly)—btDefaultCollisionConfiguration is a setup class that configures the algorithms and memory allocators used for collision detection. It serves as the blueprint for the collision pipeline, defining which collision algorithms should be used for different shape pairs (such as sphere-versus-box or box-versus-box) and establishing the memory structures required to run these calculations.

When you instantiate a physics world in ammo.js, this configuration is typically the first object you create. It is then passed as an argument to the collision dispatcher, which manages the lifecycle of collision pairs.

How it Influences Ammo.js Memory Allocation

Ammo.js runs inside a virtual WebAssembly (Wasm) heap, which is a fixed-size buffer allocated in the browser’s memory. Because C++ manages memory manually under the hood, btDefaultCollisionConfiguration plays a critical role in how this WebAssembly memory is partitioned and utilized.

It influences memory allocation in three primary ways:

1. Pre-Allocated Stack and Pool Allocators

Upon initialization, btDefaultCollisionConfiguration sets up internal memory pools (using btPoolAllocator) and stack allocators (using btStackAllocator). These allocators pre-reserve chunks of the WebAssembly heap for handling temporary collision data, contact points, and broadphase overlaps. * The Stack Allocator is used for quick, short-lived memory allocations during a physics tick. * The Pool Allocators are used for recurring objects like collision algorithms and contact joints, avoiding the overhead of frequent dynamic memory allocation (malloc).

2. Tuning Memory with btDefaultCollisionConstructionInfo

By default, ammo.js allocates standard pool sizes designed for desktop C++ applications. In resource-constrained browser environments, these defaults might allocate more memory than necessary, or conversely, be too small for complex scenes with thousands of interacting bodies.

You can customize these allocations by passing a btDefaultCollisionConstructionInfo object to the configuration constructor. This structure allows you to manually adjust: * m_stackAllocatorSize: The maximum size of the temporary stack allocator. * m_defaultMaxPersistentManifoldPoolSize: The maximum number of persistent contact manifolds (points of contact between colliding objects) that can be allocated. * m_defaultMaxCollisionAlgorithmPoolSize: The maximum number of concurrent collision algorithms.

Decreasing these values reduces the initial WebAssembly memory footprint, while increasing them prevents engine instability in high-density simulation environments.

3. Preventing WebAssembly Memory Leaks

Because ammo.js cannot rely on JavaScript’s garbage collector to clean up WebAssembly memory, objects created by btDefaultCollisionConfiguration must be freed manually.

If you recreate your physics world (for example, when switching game levels) without destroying the collision configuration, the pre-allocated pools will remain leaked in the Wasm heap. To prevent this, you must explicitly call Ammo.destroy() on your configuration instance when it is no longer needed:

Ammo.destroy(collisionConfiguration);

By understanding and configuring btDefaultCollisionConfiguration, you can maintain a stable, highly optimized memory footprint for physics simulations in web applications.