crashcat

crashcat is a pure JavaScript physics engine designed for games, simulations, and creative websites. It is built to be highly tree-shakeable, allowing developers to only include the features they use. It is engine-agnostic and can be integrated with libraries like Babylon.js, PlayCanvas, Three.js, or custom engines.

Core Capabilities:

• Rigid Body Simulation: Full support for rigid body dynamics.
• Shape Support: Convex shapes, triangle meshes, and custom shapes.
• Constraints: Includes hinge, slider, distance, point, fixed, cone, swing-twist, and six-dof constraints, all supporting motors and springs.
• Collision Detection: Continuous Collision Detection (CCD) for high-speed objects and broadphase spatial acceleration using dynamic BVH.
• Advanced Features: Flexible collision filtering, rigid body sleeping, sensor rigid bodies, and hooks for intercepting/modifying physics events.

crashcat uses a two-tier layer system to manage collision detection efficiently:

1. Broadphase Layers

Broadphase layers partition space using spatial acceleration structures (dynamic BVH trees). Each broadphase layer has its own tree. Bodies in different broadphase layers do not check for collisions against each other via the same tree, which improves performance.

• Usage: Use addBroadphaseLayer(worldSettings) to create a layer.
• Strategy: A common approach is to have a "moving" layer and a "not moving" layer. Advanced users might separate by update frequency (e.g., static terrain vs. dynamic debris).
• Constraint: Each body belongs to exactly one broadphase layer.

2. Object Layers

Object layers control collision filtering (which specific types of objects hit each other). Every object layer must belong to exactly one broadphase layer.

• Usage: Use addObjectLayer(worldSettings, broadphaseLayer) to create a layer.
• Collision Rules: Use enableCollision(worldSettings, layerA, layerB) to define if objects in layerA can collide with objects in layerB.
• Example: You can define that "projectiles" hit "enemies" but do not hit other "projectiles".

const worldSettings = createWorldSettings();

// Define Broadphase
const LAYER_MOVING_BP = addBroadphaseLayer(worldSettings);
const LAYER_STATIC_BP = addBroadphaseLayer(worldSettings);

// Define Object Layers
const PLAYER_OBJ = addObjectLayer(worldSettings, LAYER_MOVING_BP);
const WALL_OBJ = addObjectLayer(worldSettings, LAYER_STATIC_BP);

// Define Collision Rules
enableCollision(worldSettings, PLAYER_OBJ, WALL_OBJ);

When creating constraints, you can define attachment points (pointA, pointB) relative to the world or the body's center of mass:

• ConstraintSpace.WORLD: Attachment points are absolute world coordinates.
• ConstraintSpace.LOCAL: Attachment points are offsets relative to each body's center of mass.

// world space - specify attachment points in world coordinates
const worldConstraint = pointConstraint.create(world, {
    bodyIdA: bodyA.id,
    bodyIdB: bodyB.id,
    pointA: [0, 5, 0], // absolute world position
    pointB: [0, 3, 0], // absolute world position
    space: ConstraintSpace.WORLD, // default
});

// local space - specify attachment points relative to body center of mass
const localConstraint = pointConstraint.create(world, {
    bodyIdA: bodyA.id,
    bodyIdB: bodyB.id,
    pointA: [0, 0.5, 0], // offset from bodyA's center
    pointB: [0, -0.5, 0], // offset from bodyB's center
    space: ConstraintSpace.LOCAL,
});

A Listener allows you to react to and modify physics events during world updates. You pass a Listener object to the updateWorld() function to receive callbacks for various collision and contact events.

Common callbacks include:

• onContactAdded: Called when a new contact is detected.
• onContactPersisted: Called when a contact from the previous frame remains active.
• onContactRemoved: Called when a contact is no longer active. Warning: Because bodies may be destroyed during the update, only the body IDs are safe to use in this callback.
• onBodyPairValidate: Runs before narrowphase collision detection. Use this for custom filtering logic (e.g., faction systems) to avoid expensive collision calculations.
• onContactValidate: Called after collision detection but before adding the contact constraint. Use this for logic that requires contact information (like one-way platforms). Note that rejecting contacts here is more expensive than using onBodyPairValidate.
• onContactAdded (with settings): Can be used to modify contact properties like combinedFriction and combinedRestitution.

// create a listener to react to physics events
const listener: Listener = {
    onContactAdded: (bodyA, bodyB, manifold, settings) => {
        // called when a new contact is detected
        console.log('contact added between', bodyA.id, 'and', bodyB.id);
    },
    onContactPersisted: (bodyA, bodyB, manifold, settings) => {
        // called when a contact from last frame is still active
    },
    onContactRemoved: (bodyIdA, bodyIdB, subShapeIdA, subShapeIdB) => {
        // called when a contact is no longer active
        // WARNING: bodies may be destroyed, only body IDs are safe to use
    },
};

// pass listener to updateWorld
updateWorld(world, listener, 1 / 60);