repository·master·Indexed 26 days ago
https://github.com/piqnt/planck.jsA high-performance 2D JavaScript/TypeScript physics engine for cross-platform HTML5 game development. As a port of the Box2D engine, it provides an idiomatic API for managing bodies, fixtures, and joints using MKS (Meters-Kilogram-Second) units. Version 1.5.0 includes features for continuous collision detection (CCD), body sleep parameters, and flexible user data attachment for linking physics objects to game logic.
Collision processing in Planck.js is split into two stages:
BroadPhase class (internally powered by a DynamicTree) to quickly identify potential colliding pairs, reducing the complexity from $O(N^2)$ to a much lower load.Users typically interact with the World class rather than managing the BroadPhase directly.
Contacts manage collisions between two fixtures. Key concepts include:
fixtureA to fixtureB.Shapes in Planck.js define collision geometry and are independent of the physics simulation. They are considered immutable.
Key behaviors to note:
Shape base class, which provides methods for point testing, ray casting, AABB computation, and mass property computation.type member and a radius (the radius also applies to polygons).Planck.js is a 2D physics engine built around several fundamental objects that interact to simulate physical motion:
FrictionJoint is used to simulate top-down friction. It provides both 2D translational friction and angular friction between two bodies. For low-level implementation details, refer to FrictionJoint.js and ApplyForce.js in the source.Because the Planck.js solver advances bodies using discrete time steps, fast-moving objects may 'tunnel' through other objects. To prevent this, Planck.js uses two specialized mechanisms:
To use the testbed via CDN, use the planck-with-testbed.min.js distribution. Note that the testbed typically requires specific HTML elements (like #testbed-info, #testbed-status, and #testbed-play) to function correctly.
<html><body>
<span id="testbed-info"></span>
<span id="testbed-status"></span>
<button id="testbed-play">Play</button>
<script src="https://cdn.jsdelivr.net/npm/planck/dist/planck-with-testbed.min.js"></script>
<script>
const { World, Testbed } = planck;
const world = new World();
const testbed = Testbed.mount();
testbed.start(world);
</script>
</body></html>A Fixture attaches a shape to a body, giving it physical properties. A body with multiple fixtures is known as a compound body.
To create a fixture, pass a definition object to body.createFixture(). You do not need to manually manage the fixture's lifecycle; it is automatically destroyed when the parent body is destroyed. To manually remove a specific fixture (e.g., for breakable objects), use body.destroyFixture(fixture).
let myFixture = myBody.createFixture({
shape: myShape,
density: 1,
});
// To destroy it manually:
myBody.destroyFixture(myFixture);A WeldJoint attempts to constrain all relative motion between two bodies.
Important Limitation: Because the Planck.js solver is iterative, weld joints are 'soft'. If you connect a chain of bodies using weld joints, the structure will flex rather than remaining perfectly rigid.
Best Practice for Breakable Structures: Do not use a chain of weld joints to create breakable structures. Instead, create a single body with multiple fixtures. To simulate breaking, destroy a fixture and recreate it on a new body.