Forge2D

To ensure compatibility between Native (FFI) and Web (Wasm) backends, all data crossing the RawBox2D seam must follow strict contract rules. If you are extending the backend or working with low-level primitives, adhere to these constraints:

• Primitives Only: Use only int, double, bool, String, records of these types, and typed-data lists. Do not use dart:ffi or dart:js_interop types, or any Dart classes from the API layer.
• 32-bit Integer Limit: Do not use 64-bit integers as dart2js cannot represent them.
  • World IDs: Pack as index1 | (generation << 16) (both are 16-bit).
  • Body/Shape/Chain/Joint IDs: Use a pair (index1, world0 | (generation << 16)) passed as two separate int parameters and returned as an (int, int) record.
  • Bit Fields: 64-bit collision filter masks must be passed as int using sign-extension semantics (e.g., -1 represents all bits set).
• No Callbacks: Avoid passing callbacks across the seam. Instead, use polling for events or ensure queries return full results to avoid the high cost of passing function pointers to Wasm.
• Flattened Structs: Definition structs (e.g., b2BodyDef) cross the seam as flattened named parameters. The implementation overwrites native b2Default*Def() values with the received parameters.
• Ownership: The API layer owns all Dart objects. Native user data pointers should remain untouched; user data must never cross the seam.

Forge2D 0.15 is a rewrite based on Box2D v3. Key changes include:

• Resource Management: World, Body, Shape, and Chain are now value-like handles. They are NOT garbage collected; you must call destroy() explicitly and check isValid for existing handles.
• Fixtures are gone: Bodies now carry Shapes directly via body.createShape(geometry, ShapeDef(...)). Use Circle, Capsule, Segment, or Polygon as geometry.
• Material Properties: Friction, restitution, and rolling resistance are now set via ShapeDef(material: SurfaceMaterial(...)) instead of FixtureDef.
• Event Model: ContactListener callbacks are replaced by polling world.contactEvents, world.sensorEvents, and world.bodyMoveEvents after a step.
• Joints: Use type-specific methods like world.createRevoluteJoint(RevoluteJointDef(...)). Note that Gear, Pulley, Rope, Friction, and Constant-Volume joints are no longer supported.
• Rotations: Use the Rot type (e.g., Rot.fromAngle(radians)) for BodyDef(rotation: ...) and body.setTransform(position, rotation). body.angle still returns a double.
• Forces: body.applyForce and body.applyLinearImpulse now require a named point argument. applyForceToCenter has been removed; to apply at the center of mass, omit the point argument.
• Gravity: A default World() now has a gravity of (0, -10). For top-down games, use World(gravity: Vector2.zero()).

The World class is the central container for all physics entities, including bodies, shapes, and joints.

Key Lifecycle Rules:

• Creation: Worlds are created using the World constructor. You can provide a gravity vector or a full WorldDef for advanced configuration.
• Threading: A world must only be used from the isolate that created it.
• Destruction: You must explicitly call destroy() to free all bodies, shapes, and joints. Once destroyed, the world is no longer valid.
• Mutation during stepping: You cannot create bodies or joints while the world is currently in a step(). If you attempt to destroy objects during a step (e.g., inside a collision callback), Forge2D automatically defers these actions until the step completes.

// Basic world creation
final world = World(gravity: Vector2(0, -9.8));

// Advanced creation
final world = World(definition: WorldDef(
  gravity: Vector2(0, -9.8),
  enableSleep: true,
  enableContinuous: true,
));

// Simulation loop
world.step(1 / 60);

// Cleanup
world.destroy();

To run a simulation, initialize the engine, create a World, define bodies with BodyDef, and attach shapes using createShape. Use world.step(dt) to advance the simulation. Note that World, Body, Shape, and Chain are value-like handles; you must call destroy() on them explicitly to free native resources.

import 'package:forge2d/forge2d.dart';

Future<void> main() async {
  await initializeForge2D();

  final world = World();

  // Static ground: a wide box whose top surface is at y = 0.
  world
      .createBody(BodyDef(position: Vector2(0, -1)))
      .createShape(Polygon.box(50, 1));

  // A dynamic box dropped from above.
  final box = world.createBody(
    BodyDef(type: BodyType.dynamic, position: Vector2(0, 10)),
  )..createShape(Polygon.square(0.5));

  for (var i = 0; i < 90; i++) {
    world.step(1 / 60);
  }
  print(box.position); // The box has landed on the ground.

  world.destroy();
}

To create a WheelJoint, you must first define its properties using WheelJointDef. A wheel joint provides suspension, allowing bodyB to rotate freely around an anchor while translating along a specific axis on bodyA. It supports an optional spring, translation limits, and a motor.

Configuration Properties

final wheelDef = WheelJointDef(
  bodyA: chassisBody,
  bodyB: wheelBody,
  localAnchorA: Vector2(0, -1),
  localAnchorB: Vector2.zero(),
  localAxisA: Vector2(0, 1),
  enableSpring: true,
  hertz: 5.0,
  dampingRatio: 0.7,
  enableMotor: true,
  motorSpeed: 10.0,
  maxMotorTorque: 20.0,
);