What is a Ghost Object in Ammo.js

This article explains the concept of ghost objects in Ammo.js, a powerful 3D physics engine for the web. It defines what a ghost object is, explores how it functions within a physics simulation, and outlines the specific development scenarios where you should utilize it to optimize your application’s performance and collision detection.

Understanding Ghost Objects in Ammo.js

In Ammo.js (the JavaScript port of the Bullet physics engine), a ghost object—represented by the class btPairCachingGhostObject or btGhostObject—is a special type of collision object. Unlike standard rigid bodies, ghost objects are physically intangible. They do not react to forces like gravity, torque, or collisions, and other rigid bodies can pass directly through them without any physical resistance.

The primary purpose of a ghost object is to keep track of its own overlapping pairs. It maintains a localized cache of all other physics objects currently intersecting with its collision shape. This allows developers to quickly query which objects are inside the ghost object’s volume without performing expensive global collision sweeps.

When to Utilize Ghost Objects

Ghost objects are highly efficient and should be utilized in the following scenarios:

1. Creating Trigger Zones and Sensors

The most common use case for a ghost object is acting as a trigger volume. If you need to detect when a player or object enters a specific region, a ghost object is the ideal tool. Examples include: * Opening a sliding door when a character approaches. * Triggering a cutscene or checkpoint in a game. * Applying area-of-effect (AoE) environmental hazards, such as a zone that drains health or applies a speed boost.

2. Implementing Character Controllers

Standard rigid bodies are often difficult to control for player characters because physics forces (like friction, sliding, and bouncing) can make movement feel unnatural. Ammo.js uses a ghost object as the foundation for its btKinematicCharacterController. By using a ghost shape (usually a capsule), the character controller can detect walls, slopes, and steps to handle movement logic manually while ignoring standard rigid-body physics.

3. Proximity and AI Detection

If an AI agent needs to detect nearby entities, a cone-shaped or spherical ghost object can simulate the agent’s field of view or hearing range. Instead of raycasting in every direction, the AI can simply query the ghost object’s overlapping pair cache to instantly get a list of potential targets within range.

4. Area Queries (e.g., Explosions)

When an explosion occurs, you need to determine which objects are within the blast radius to apply damage or forces. By temporarily positioning a spherical ghost object at the epicenter, you can instantly retrieve all affected objects within the volume and apply the appropriate physics impulses.

Key Implementation Note

For a ghost object to work correctly in Ammo.js, it must be added to the dynamics world with the correct collision filter flags, and the world’s broadphase pair cache must be configured to support ghost pair detection. This is typically achieved by adding an overlapping pair callback to the physics world during initialization.