Phaser Box2D

This library is a direct JavaScript conversion of the original C functions. While most documentation from box2d.org applies, the primary difference is that C typedef structs (like b2Vec2) are implemented as JavaScript classes. You must instantiate these using the new keyword.

Example: Instead of C-style initialization: bodyDef.position = (b2Vec2){0.0f, 4.0f};

You must use: bodyDef.position = new b2Vec2(0.0, 4.0);

When using the Sprite-to-Body pairing, follow these movement principles:

• Move via the Body: To move an object, apply forces or impulses to the Box2D Body. Do not move the Sprite directly, as UpdateWorldSprites will overwrite the sprite's position with the body's position.
• Unlocking the pairing: If you need to move a Sprite independently (e.g., via a Phaser Tween), use RemoveSpriteFromWorld to break the link. Note that the Box2D body will continue to simulate and remain active in the world even if the sprite is unlinked. You can re-link them later using AddSpriteToWorld.

To view the local API documentation server, follow these steps:

1. Run npm install in the root directory.
2. Run npm run docs to launch the documentation server.
3. Open your browser to the provided URL (typically http://localhost:8000).

You can install the Phaser Box2D library using npm to add it to your project. This library is a standalone port of Box2D v3 and can be used with or without the Phaser game framework.

npm i phaser-box2d

To progress the simulation and visualize it, you must perform two steps in your update loop:

1. Step the simulation: Call WorldStep({ worldId, deltaTime }) to advance the physics. deltaTime is the time elapsed since the last frame (typically 1/60).
2. Draw the world: Call b2World_Draw(worldId, renderer) to render the bodies and joints using a debug renderer.

For a vanilla JS implementation, you can use CreateDebugDraw(canvas, ctx, scale) to create a renderer and RAF(update) to manage the animation loop.

// Inside an update loop
function update (deltaTime)
{
    WorldStep({ worldId: world.worldId, deltaTime: deltaTime });

    ctx.clearRect(0, 0, canvas.width, canvas.height);

    b2World_Draw(world.worldId, m_draw);
}

To visualize the physics simulation, use the provided debug drawing system. This requires a HTML <canvas> element and a 2D context.

// 1. Set the scale for drawing
const m_drawScale = 7.0;

// 2. Get canvas and context
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');

// 3. Create the debug drawing system
const m_draw = CreateDebugDraw(canvas, ctx, m_drawScale);

// 4. Inside your animation loop, clear and redraw
function update() {
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    b2World_Draw(worldId, m_draw);
}

Phaser Box2D is available in the dist folder of the GitHub repository. You should choose between the Debug and Release builds based on your current development stage:

Debug Build

Files: PhaserBox2D-Debug.js and PhaserBox2D-Debug.js.map

• Use for: Development and troubleshooting physics issues.
• Features: Includes console.asset statements and a built-in Canvas debug renderer.
• Warning: Do not use this for production. The assertion statements significantly impact performance.

Release Build

Files: PhaserBox2D.js and PhaserBox2D.min.js

• Use for: Production games.
• Features: All assertions, debug calls, and the debug renderer have been stripped to optimize performance and file size.
• Note: You can use this during development, but you may need to swap to the Debug version if you need to trace physics-related issues.

The library provides wrapper functions in physics.js to simplify the multi-step creation process of worlds, bodies, and shapes into single calls using configuration objects.

import { CreateWorld, CreateBoxPolygon } from 'physics.js';

let world = CreateWorld({ worldDef: b2DefaultWorldDef() });

let box = CreateBoxPolygon({
    worldId: world.worldId,
    bodyDef: b2DefaultBodyDef(),
    type: b2BodyType.b2_dynamicBody,
    position: new b2Vec2(0, 4),
    size: 1,
    density: 1.0,
    friction: 0.3
});