Physics Engines: Porting Box2DFlash to Matter.js & Modern JavaScript Game Engines

1. Box2DFlash Architecture: The Physics World & Pixel Scaling Factor

Box2D was engineered from first principles around the laws of Newtonian mechanics using the Meter-Kilogram-Second (MKS) unit system. Its iterative constraint solver is numerically tuned for rigid bodies ranging between 0.1 meters (an apple) and 10 meters (a bus).

Because Flash display coordinates were measured in pixels (or twips), developers had to decouple the physics simulation world (b2World) from the rendering DisplayList. This was accomplished using a global scaling conversion constant, conventionally defined as 30 pixels per meter:

// Box2DFlash Coordinate Scaling Paradigm
public static const SCALE:Number = 30.0; // 30 pixels = 1 meter

// Creating a dynamic rigid body in Box2DFlash
var bodyDef:b2BodyDef = new b2BodyDef();
bodyDef.type = b2Body.b2_dynamicBody;
bodyDef.position.Set(pixelX / SCALE, pixelY / SCALE); // Convert to meters

var body:b2Body = world.CreateBody(bodyDef);

var boxShape:b2PolygonShape = new b2PolygonShape();
boxShape.SetAsBox((pixelWidth / 2) / SCALE, (pixelHeight / 2) / SCALE);

var fixtureDef:b2FixtureDef = new b2FixtureDef();
fixtureDef.shape = boxShape;
fixtureDef.density = 1.0;
fixtureDef.friction = 0.5;
fixtureDef.restitution = 0.2; // Bounciness
body.CreateFixture(fixtureDef);

Every frame during the ENTER_FRAME tick, the game stepped the physics world (world.Step(1/60, 10, 10)) and synchronized the visual DisplayObject's x, y, and rotation properties by multiplying meters back by the scale constant.

2. Collision Filtering Bitmasks: 16-Bit Category & Mask Translation

In complex physics games, not every object should collide with every other object. For example, friendly projectiles should pass through player characters but collide with enemy fortifications and terrain. Box2D resolved this using 16-bit binary masks:

• categoryBits: The collision identity of the fixture (must be a power of two: 0x0001, 0x0002, 0x0004, etc.).
• maskBits: A bitwise OR combination of categories that this fixture collides with.
• groupIndex: An override integer; positive values always collide, while negative values never collide among matching group IDs.

Modern web physics engines like Matter.js preserve this exact mathematical formulation, allowing developers to port legacy collision configuration tables with zero logic alterations:

// Modern Matter.js Collision Filtering (1:1 Box2D Alignment)
const CATEGORY_TERRAIN   = 0x0001;
const CATEGORY_PLAYER    = 0x0002;
const CATEGORY_PROJECTILE= 0x0004;
const CATEGORY_ENEMY     = 0x0008;

const projectile = Bodies.circle(x, y, radius, {
  density: 0.002,
  restitution: 0.4,
  collisionFilter: {
    category: CATEGORY_PROJECTILE,
    mask: CATEGORY_TERRAIN | CATEGORY_ENEMY // Ignores CATEGORY_PLAYER
  }
});

3. Modern Engine Comparison: Matter.js vs. Rapier2D WebAssembly vs. Planck.js

When selecting a modern web runtime to replace Box2DFlash, development teams must balance bundle size, API compatibility, and raw simulation throughput:

4. Porting Constraint Joints: Revolute, Distance & Prismatic Hinges

Vehicles, ragdoll characters, and mechanical puzzle contraptions rely on constraint joints to bind rigid bodies together. In Box2DFlash, joints were created via specialized definition classes:

• Revolute Joint (Hinge): Pins two bodies together at a shared rotational anchor point, optionally with motorized angular velocity and joint limits.
• Distance Joint (Rod/Spring): Enforces a constant or spring-damped distance between two body anchor points.
• Prismatic Joint (Piston/Slider): Restricts relative motion to linear sliding along a single translation vector.

In Matter.js, distance and revolute joints are unified under the Matter.Constraint class:

// Porting a Revolute Pin Joint to Matter.js
const pinJoint = Constraint.create({
  bodyA: chassisBody,
  pointA: { x: 50, y: 20 }, // Local offset on chassis
  bodyB: wheelBody,
  pointB: { x: 0, y: 0 },    // Center of wheel
  stiffness: 1.0,           // Rigid link
  length: 0                 // Shared pivot coordinate
});
Composite.add(engine.world, [chassisBody, wheelBody, pinJoint]);

5. Determinism & Replay Desynchronization Prevention

Many classic Flash games relied on recorded input replays for global leaderboards and puzzle verification. Porting these games to modern web runtimes requires strict physics determinism:

• Fixed Timestep Integration: Never use variable deltaTime in the physics step loop. Run the simulation on a fixed 16.666ms (60 Hz) timestep using an accumulator pattern inside the requestAnimationFrame loop.
• Deterministic Solvers: If 100% cross-platform bit-identical determinism is mandatory (e.g., verifying user solutions on a server), deploy Rapier2D or Planck.js in an isolated WebAssembly sandbox to eliminate JavaScript JIT floating-point optimization discrepancies between V8, JavaScriptCore, and SpiderMonkey.

Frequently Asked Questions