What is the Default Angle Unit in planck.js?

When developing 2D physics simulations for the web using planck.js—a 2D physics engine based on Box2D—understanding how it handles spatial and rotational measurements is crucial for accurate movement and rendering. This article explains the default unit of measurement for angles within planck.js, details how it affects your development workflow, and provides practical examples for converting these values into formats required by popular HTML5 rendering libraries.

The Default Unit: Radians

In planck.js, the default unit of measurement for angles is radians, not degrees. This design choice inherits directly from its predecessor, Box2D, and aligns with standard mathematical and physics computations used in game development.

When you query a body for its angle or set a fixture’s rotation, the engine expects and returns values based on a circle divided into \(2\pi\) units.

• A full rotation (360°): \(2\pi\) radians (approximately 6.283)
• A half rotation (180°): \(\pi\) radians (approximately 3.141)
• A quarter rotation (90°): \(\pi / 2\) radians (approximately 1.57)

Working with Radians in Code

Because many developers are more accustomed to thinking in degrees, you will frequently need to handle conversions. Furthermore, while the physics simulation operates strictly in radians, some rendering engines or asset pipelines might prefer degrees.

Setting and Getting Angles

When creating or manipulating a body, you interact with the angle property directly through radians.

// Creating a body with a 45-degree starting angle
const body = world.createBody({
    type: 'dynamic',
    position: pl.Vec2(0, 0),
    angle: Math.PI / 4 // 45 degrees in radians
});

// Retrieving the angle during the game loop
const currentAngle = body.getAngle(); 

Conversion Formulas

If you prefer to design your game layout using degrees, you can use simple conversion formulas to bridge the gap:

// Convert Degrees to Radians
function degreesToRadians(degrees) {
    return degrees * (Math.PI / 180);
}

// Convert Radians to Degrees
function radiansToDegrees(radians) {
    return radians * (180 / Math.PI);
}

Impact on Rendering Engines

When mapping your planck.js physics world to a visual canvas, you must pay attention to the target library’s expectations:

• HTML5 Canvas API: The native ctx.rotate() method natively accepts radians, making it a perfect 1:1 match with planck.js.
• PixiJS: Modern versions of PixiJS offer both .rotation (which uses radians) and .angle (which uses degrees). If you map directly to .rotation, no conversion is necessary.
• Phaser 3: Game objects in Phaser typically use .rotation for radians and .angle for degrees.

Matching the rotation properties correctly ensures that your visual sprites perfectly mirror the underlying physical collisions calculated by planck.js.