feat!: Migrate flame_forge2d to the Box2D v3 based forge2d - #3952
feat!: Migrate flame_forge2d to the Box2D v3 based forge2d#3952spydon wants to merge 23 commits into
Conversation
Every widget of the default flutter create counter app rests on a Forge2D body and drops to the floor, keeping its normal function. Pressing the button counts and launches it, and pressing any widget sends it flying. The bodies follow the shape Material draws: capsules for the text, a rounded box for the button. Every widget is given the same mass so the wide app bar does not crush the small counter, and the walls are solid boxes so nothing squeezes out through a corner.
Add a heroTag to the counter button, drop a redundant trailing zero in hue_decorator, teach cspell the word subclassing and use the en_US spelling of neighboring.
There was a problem hiding this comment.
Pull request overview
This PR migrates flame_forge2d (and the repo’s usages/examples/docs) from the legacy pure-Dart Box2D 2.x API to the new Box2D v3-based forge2d ^0.15.0, introducing the new polled contact/sensor event model, updated shape/joint/query APIs, and the required Forge2D initialization flow (especially for web/WASM).
Changes:
- Reworks
flame_forge2dcore APIs: lazy physics-world creation + stepping/substepping, new contact event dispatching, newContactwrapper, andBodyComponentshape rendering viaShape.geometry. - Introduces meters-to-pixels scaling via
Forge2DViewfinder/Forge2DGame.metersToPixels(decoupled from camera zoom). - Migrates/updates tests, examples, and documentation (including new migration guides) to the Forge2D 0.15 / Box2D v3 API surface.
Reviewed changes
Copilot reviewed 71 out of 77 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| scripts/customer_testing.dart | Excludes flame_forge2d from customer testing with rationale (native toolchain requirement). |
| packages/flame/lib/src/rendering/hue_decorator.dart | Minor constant formatting change. |
| packages/flame/lib/src/events/dispatchers/multi_tap_dispatcher.dart | Marks handleTapDown as @visibleForTesting for tests. |
| packages/flame_forge2d/test/world_contact_listener_test.dart | Removes tests for deleted legacy listener API. |
| packages/flame_forge2d/test/helpers/mocks.dart | Removes mocks tied to removed legacy Forge2D types. |
| packages/flame_forge2d/test/helpers/helpers.dart | Removes obsolete export. |
| packages/flame_forge2d/test/forge2d_world_test.dart | Updates/expands world behavior tests for new stepping/bodies/query/callback APIs. |
| packages/flame_forge2d/test/forge2d_viewfinder_test.dart | Adds tests for new meters-to-pixels viewfinder behavior. |
| packages/flame_forge2d/test/forge2d_game_test.dart | Updates screen/world conversion tests for meters-to-pixels scaling. |
| packages/flame_forge2d/test/contact_test.dart | Adds tests for new flame-side Contact wrapper. |
| packages/flame_forge2d/test/contact_events_dispatcher_test.dart | Adds tests for new contact/sensor event dispatcher + integration with Forge2DGame. |
| packages/flame_forge2d/test/contact_callbacks_test.dart | Updates tests for new contact model and auto-enabling event flags. |
| packages/flame_forge2d/test/body_component_test.dart | Migrates rendering/shape tests and adds coverage for new behaviors. |
| packages/flame_forge2d/README.md | Updates Forge2D description + adds 0.19→0.20 migration section. |
| packages/flame_forge2d/pubspec.yaml | Bumps dependency to forge2d: ^0.15.0. |
| packages/flame_forge2d/lib/world_contact_listener.dart | Removes legacy listener-based API. |
| packages/flame_forge2d/lib/forge2d_world.dart | Implements lazy world creation, stepping/substeps, bodies tracking, queries, callbacks, and event dispatching. |
| packages/flame_forge2d/lib/forge2d_viewfinder.dart | Adds Forge2DViewfinder to separate meters-to-pixels scaling from camera zoom. |
| packages/flame_forge2d/lib/forge2d_game.dart | Awaits Forge2D initialization on load; wires Forge2DViewfinder and metersToPixels. |
| packages/flame_forge2d/lib/flame_forge2d.dart | Updates exports (adds new types, removes old listener). |
| packages/flame_forge2d/lib/contact.dart | Adds flame-side Contact wrapper spanning contact + sensor events. |
| packages/flame_forge2d/lib/contact_events_dispatcher.dart | Adds polled-events dispatcher routing to ContactCallbacks via userData. |
| packages/flame_forge2d/lib/contact_callbacks.dart | Updates docs/API to shape-based contacts and new preSolve/hit guidance. |
| packages/flame_forge2d/lib/body_component.dart | Replaces fixtures with ShapeSpec/shapes; updates rendering and hit-testing for new geometry model. |
| packages/flame_forge2d/example/lib/main.dart | Migrates package example to new shape/material APIs. |
| examples/lib/stories/bridge_libraries/flame_forge2d/widget_example.dart | Rebuilds widget overlay example on new API; bodies fitted to measured widget sizes. |
| examples/lib/stories/bridge_libraries/flame_forge2d/utils/style.dart | Adds shared example palette + Forge2DExampleGame + glowing rendering mixin. |
| examples/lib/stories/bridge_libraries/flame_forge2d/utils/joint_renderer.dart | Adds joint rendering helpers compatible with new joint API. |
| examples/lib/stories/bridge_libraries/flame_forge2d/utils/boxes.dart | Migrates box components + adds mouse-joint rendering. |
| examples/lib/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart | Migrates boundary walls; updates defaults and styling. |
| examples/lib/stories/bridge_libraries/flame_forge2d/utils/balls.dart | Migrates balls to new shapes/materials; integrates shared styling. |
| examples/lib/stories/bridge_libraries/flame_forge2d/tap_callbacks_example.dart | Migrates example to Forge2DExampleGame + async onLoad. |
| examples/lib/stories/bridge_libraries/flame_forge2d/sprite_body_example.dart | Migrates sprite-body example to new API and async onLoad. |
| examples/lib/stories/bridge_libraries/flame_forge2d/revolute_joint_with_motor_example.dart | Migrates revolute/motor example; updates shapes/joints/materials. |
| examples/lib/stories/bridge_libraries/flame_forge2d/raycast_example.dart | Migrates raycast example to castRayClosest/castRayAll. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/wheel_joint.dart | Adds new wheel joint example for Box2D v3 API. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/weld_joint.dart | Migrates weld joint example and adds joint rendering. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/rope_joint.dart | Removes rope joint example (not in Box2D v3). |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/revolute_joint.dart | Migrates revolute joint example and adds joint rendering. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/pulley_joint.dart | Removes pulley joint example (not in Box2D v3). |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/prismatic_joint.dart | Migrates prismatic joint example; replaces custom renderer with shared renderer. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/mouse_joint.dart | Migrates mouse joint example; adds joint rendering. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/motor_joint.dart | Migrates motor joint example; uses new joint API + renderer. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/gear_joint.dart | Removes gear joint example (not in Box2D v3). |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/friction_joint.dart | Removes friction joint example (not in Box2D v3). |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/filter_joint.dart | Adds filter joint example for Box2D v3 API. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/distance_joint.dart | Migrates distance joint example; uses new spring parameters + renderer. |
| examples/lib/stories/bridge_libraries/flame_forge2d/joints/constant_volume_joint.dart | Removes constant-volume joint example (not in Box2D v3). |
| examples/lib/stories/bridge_libraries/flame_forge2d/flame_forge2d.dart | Updates dashbook story set to match new/removed joint examples. |
| examples/lib/stories/bridge_libraries/flame_forge2d/drag_callbacks_example.dart | Migrates drag callbacks example and async onLoad. |
| examples/lib/stories/bridge_libraries/flame_forge2d/domino_example.dart | Reworks domino example for new API and shared styling. |
| examples/lib/stories/bridge_libraries/flame_forge2d/contact_callbacks_example.dart | Migrates contact callbacks example and async onLoad. |
| examples/lib/stories/bridge_libraries/flame_forge2d/composition_example.dart | Migrates composition example to new base game + async onLoad. |
| examples/lib/stories/bridge_libraries/flame_forge2d/camera_example.dart | Migrates camera example to Forge2DExampleGame and new scaling model. |
| examples/lib/stories/bridge_libraries/flame_forge2d/blob_example.dart | Removes blob example (depended on removed joint/system). |
| examples/lib/stories/bridge_libraries/flame_forge2d/animated_body_example.dart | Migrates animated body example and async onLoad. |
| examples/lib/main.dart | Updates direct-route game registry to match available joint examples. |
| examples/games/padracing/lib/wall.dart | Migrates PadRacing wall shape/material usage. |
| examples/games/padracing/lib/tire.dart | Migrates tire body + revolute joint creation; updates renamed APIs. |
| examples/games/padracing/lib/padracing_game.dart | Updates base game scaling init (meters-to-pixels vs zoom). |
| examples/games/padracing/lib/lap_line.dart | Migrates lap sensor to shape-based sensor events. |
| examples/games/padracing/lib/car.dart | Migrates car body shapes/materials and enables sensor events for lap detection. |
| examples/games/padracing/lib/ball.dart | Migrates ball component to shape/material/contact-event flags. |
| doc/other_modules/other_modules.md | Adds Forge2D module + navigation entries. |
| doc/other_modules/forge2d/migration.md | Adds Forge2D 0.14→0.15 migration guide. |
| doc/other_modules/forge2d/forge2d.md | Adds Forge2D module overview and getting-started docs. |
| doc/bridge_packages/flame_forge2d/migration.md | Adds flame_forge2d 0.19→0.20 migration guide. |
| doc/bridge_packages/flame_forge2d/forge2d.md | Updates Forge2D bridge docs for new initialization and scaling model. |
| doc/bridge_packages/flame_forge2d/flame_forge2d.md | Adds migration page to docs toctree. |
| .github/.cspell/words_dictionary.txt | Adds “subclassing” to spelling dictionary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Asserts are stripped in release builds, so a Box2D world that fails to allocate (for example when the world limit is hit) would be cached and used by every later step, crashing far from the cause. Check it at runtime and throw a StateError.
|
I'm testing this with my existing game / paradigm, I'll let you know. If you want I can also do a full review of the code |
|
oops something happened with gravity :D I think I also need to re-do my contact callback / hit recognition (I might have forgot to toggle it on) because it should have detected the end of the level. I'll play around some more... The good news is, all the basics work and it really wasn't a huge effort to migrate the code so far Screencast_20260803_170348.webmWould I expect to see lower CPU use? (it's hard to tell with my app the majority of CPU comes from data streaming, logging network message polling) |
That'd be awesome! :)
You would mostly see a lower CPU usage when you have a lot of bodies. |
Indeed correct, added some more explanation in the migration instructions: 8f29298
Tell me if you come up with anything regarding this that we should add to the migration guide. :)
🙌 |
|
So it was def my bad with the contact callback, I forgot that I had turned the finish line into a sensor a few months (which made more sense, it's not really a physical object), and I hadn't turned on Gravity I'm still struggling with... it seems like some of the physics have changed a little - but if the examples work as expected then it's some quirk of my handling. I'll investigate a little more and I'm starting to go through the PR code now :) |
|
On further investigation, it seems like a contact event is getting triggered while it is not actually in contact. I'll keep digging, but it could be that the ball is just passing straight through the paddle somehow (although would be weird because I could control it before) Visually, it does not look like it touches the bottom wall (i turned on renderbody to be sure) Screencast_20260806_164103.webmthis is with gravity scaled down to 0.2 (* 9.81), the paddle is sitting on the bottom "wall" the ball touches the paddle (not of type Wall), then the
|
|
I'm either losing my mind (possible) or this might be a legit bug, but to confirm that I will need to create a MWE. This is the contact event that fires - it's far enough away that it shouldn't be a floating point error, and the ball is very squarely outsided of the wall boundary, as well as the event itself being outside of the boundaries of the wall |
/// Reproduction of unwanted contact
library;
import 'package:flame/game.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flutter/material.dart';
const double kWidth = 1.0; // x: -0.5 .. 0.5
const double kHeight = 1.0; // y: 0 .. -1
const double kBallRadius = 0.02;
const double kWallThickness = 0.1;
const double kGravity = 9.81;
const double kMetersToPixels = 10.0;
/// How the walls are built
enum WallShape { polygon, segment }
/// Make it segment to use "thin" walls
const WallShape kWallShape = WallShape.polygon;
/// Where the ball starts.
final Vector2 kBallStart = Vector2(0, -0.0399);
void main() {
runApp(GameWidget(game: MweGame()));
}
class MweGame extends Forge2DGame {
MweGame()
: super(gravity: Vector2(0, kGravity), metersToPixels: kMetersToPixels);
@override
Future<void> onLoad() async {
await super.onLoad();
// Fit the 1x1 playfield in the viewport
camera.viewfinder.zoom = size.x / kWidth;
camera.viewfinder.position = Vector2(0, -kHeight / 2);
await world.addAll([
// Bottom wall: top face at y = 0, bottom face at y = +1.
// This is the wall the ball contacts.
MweWall(
'bottom',
Vector2(-kWidth / 2, 0),
Vector2(kWidth / 2, 1),
const Color(0xFF474747),
horizontal: true,
),
// Right wall.
MweWall(
'right',
Vector2(kWidth / 2, 0),
Vector2(kWidth / 2 + kWallThickness, -kHeight),
const Color(0xFF00FF33),
horizontal: false,
),
// Top wall.
MweWall(
'top',
Vector2(kWidth / 2, -kHeight),
Vector2(-kWidth / 2, -kHeight - kWallThickness),
const Color(0xFF3355FF),
horizontal: true,
),
// Left wall.
MweWall(
'left',
Vector2(-kWidth / 2, -kHeight),
Vector2(-kWidth / 2 - kWallThickness, 0),
const Color(0xFFCCFF00),
horizontal: false,
),
// Kinematic paddle sitting just above the bottom wall (should prevent contact)
MwePaddle(),
MweBall(),
]);
_dumpShapes();
}
void _dumpShapes() {
debugPrint(
'=== stored shape geometry (wall shape: ${kWallShape.name}) ===',
);
for (final component in world.children.query<BodyComponent>()) {
for (final shape in component.body.shapes) {
final geometry = shape.geometry;
final description = switch (geometry) {
Polygon(:final points, :final radius) =>
'Polygon(radius: $radius, points: $points)',
Segment(:final point1, :final point2) =>
'Segment($point1 -> $point2)',
Circle(:final center, :final radius) =>
'Circle(center: $center, radius: $radius)',
Capsule(:final radius) => 'Capsule(radius: $radius)',
};
// Body-local geometry + AABB.
debugPrint(' $component');
debugPrint(' body position : ${component.body.position}');
debugPrint(' geometry : $description');
debugPrint(
' world aabb : '
'x[${shape.aabb.lowerBound.x}, ${shape.aabb.upperBound.x}] '
'y[${shape.aabb.lowerBound.y}, ${shape.aabb.upperBound.y}]',
);
}
}
debugPrint('=== end shape geometry ===');
}
}
/// Static wall
class MweWall extends BodyComponent {
MweWall(
this.name,
this._start,
this._end,
Color color, {
required this.horizontal,
}) : super(
paint: Paint()
..color = color
..style = PaintingStyle.fill,
);
final String name;
final Vector2 _start;
final Vector2 _end;
final bool horizontal;
/// The face the ball can actually reach, starting at [_start].
Vector2 get _faceEnd =>
horizontal ? Vector2(_end.x, _start.y) : Vector2(_start.x, _end.y);
/// AABB
String get bounds {
final x1 = _start.x < _end.x ? _start.x : _end.x;
final x2 = _start.x < _end.x ? _end.x : _start.x;
final y1 = _start.y < _end.y ? _start.y : _end.y;
final y2 = _start.y < _end.y ? _end.y : _start.y;
return 'x[$x1, $x2] y[$y1, $y2]';
}
@override
Body createBody() {
final ShapeGeometry shape = switch (kWallShape) {
WallShape.polygon => Polygon([
_start,
Vector2(_end.x, _start.y),
_end,
Vector2(_start.x, _end.y),
]),
WallShape.segment => Segment(point1: _start, point2: _faceEnd),
};
final shapeDef = ShapeDef(
material: SurfaceMaterial(friction: 0.3),
density: 1.0,
enableContactEvents: true,
);
final bodyDef = BodyDef(
type: BodyType.static,
userData: this,
position: Vector2.zero(),
);
renderBody = true;
return world.createBody(bodyDef)..createShape(shape, shapeDef);
}
@override
String toString() => 'Wall($name)';
}
/// Kinematic paddle, sitting above the bottom wall
class MwePaddle extends BodyComponent {
MwePaddle()
: super(
paint: Paint()
..color = const Color(0xFF00BBFF)
..style = PaintingStyle.fill,
);
static const double halfWidth = 0.15;
static const double halfHeight = 0.005;
@override
Body createBody() {
final shape = Polygon.box(halfWidth, halfHeight);
final shapeDef = ShapeDef(
material: SurfaceMaterial(friction: 20.0, rollingResistance: 1.0),
density: 1.0,
);
final bodyDef = BodyDef(
type: BodyType.kinematic,
userData: this,
position: Vector2(-0.32, -0.1),
gravityScale: 0,
);
renderBody = true;
return world.createBody(bodyDef)..createShape(shape, shapeDef);
}
@override
String toString() => 'Paddle';
}
/// Dynamic ball, same body/shape parameters as the paradigm's ball.
class MweBall extends BodyComponent with ContactCallbacks {
MweBall()
: super(
paint: Paint()
..color = const Color(0xFFFF3366)
..style = PaintingStyle.fill,
);
@override
Body createBody() {
final bodyDef = BodyDef(
type: BodyType.dynamic,
position: kBallStart.clone(),
linearDamping: 1.0,
angularDamping: 0.8,
gravityScale: 1.0,
);
final shapeDef = ShapeDef(
material: SurfaceMaterial(friction: 0.5, restitution: 0.0),
density: 5.0,
enableContactEvents: true,
enableSensorEvents: true,
userData: this,
);
renderBody = true;
return world.createBody(bodyDef)
..createShape(Circle(radius: kBallRadius), shapeDef);
}
@override
void beginContact(Object other, Contact contact) {
final p = body.position;
debugPrint('--- beginContact with $other ---');
debugPrint(' normal : ${contact.normal}');
debugPrint(' isSensorEvent : ${contact.isSensorEvent}');
for (final point in contact.points ?? const <ContactPoint>[]) {
debugPrint(
' point : ${point.point} separation: ${point.separation}',
);
}
debugPrint(' ball position : $p velocity: ${body.linearVelocity}');
debugPrint(
' ball bounds : x[${p.x - kBallRadius}, ${p.x + kBallRadius}] '
'y[${p.y - kBallRadius}, ${p.y + kBallRadius}]',
);
if (other is MweWall) {
debugPrint(' wall bounds : ${other.bounds}');
// For the bottom wall (face at y = 0)
debugPrint(' gap to y=0 : ${0.0 - (p.y + kBallRadius)}');
}
}
@override
void endContact(Object other, Contact contact) {
debugPrint('--- endContact with $other (ball y=${body.position.y}) ---');
}
@override
String toString() => 'Ball';
}This reproduces the problem. I think it's to do with the linear slop and how it fuzzes it - it seems like there's a (hardcoded?) 0.02 coming in somehwere... I think the issue here is that I'm using the default 10 pixels per meter, as I was before, but now objects that are quite "far" apart are triggering contact events, and this seems like a change in behaviour |
|
@spydon I think it might be an option (but it will add complexity if used - e.g. will need to be gated if it can't be used after other calls) to expose https://github.com/flame-engine/forge2d/blob/49dd4048d3be73af542976f9438ac3ed22cf06d4/packages/forge2d/lib/src/ffi/box2d.g.dart#L115 I can see that approach possibly breaking down if you have multiple game instances (or games) that would have a different value for but something like: // in flame_forge2d
void setLengthUnitsPerMeter(double lengthUnits) => rawBox2D.setLengthUnitsPerMeter(lengthUnits);
// in user code
class myGame extends Forge2DGame {
static const double lengthUnitsPerMeter = 0.04; // reduces tolerances
@override
Future<void> onLoad() async {
await initializeForge2D();
setLengthUnitsPerMeter(lengthUnitsPerMeter);
await super.onLoad();
}
}The speculative collision that is new in v3 causes this problem, so if the play area is zoomed to avoid velocity limits, then the tolerances will become relatively large compared to the on-screen/pixel size...alternatively if that makes more sense, it could be a part of the What do you think? |
Description
Migrates
flame_forge2d(and everything in the monorepo that uses it) to the new forge2d, thenative Box2D v3.1.1 bindings that are currently in review in the stacked chain
flame-engine/forge2d#115 (the native rewrite) and flame-engine/forge2d#116 (web support through a
WebAssembly build). This both prepares the migration and serves as real-world validation of the new
forge2d API while that chain is in review.
flame_forge2dnow depends on the publishedforge2d: ^0.15.0.flame_forge2dstays in thecustomer_testing.dartexclusions, because forge2d compiles Box2D from source through the Dartbuild hooks and so needs a C toolchain on the flutter/flutter presubmit runner; the reasoning is
documented next to the exclusion.
Core package
Forge2DWorldsteps the world withphysicsWorld.step(dt, subStepCount: subStepCount)and thendispatches the polled contact and sensor events through the new overridable
ContactEventsDispatcher(replacingWorldContactListener, since listener interfaces no longerexist). It keeps a Dart-side
bodiesset (upstream no longer exposes one) which the gravitysetter uses to wake bodies, and exposes the new query API (
castRayClosest,castRay,castRayAll,overlapAabb) plus forwarding setters forpreSolveCallbackandcustomFilterCallback.ContactCallbackskeeps its familiarbeginContact(Object other, Contact contact)shape througha new lightweight flame-side
Contactclass that wraps both contact and sensor events.BodyComponentrenders from the newShape.geometryread-back (Circle,Capsule,Segment,Polygon; chain segments arrive asSegments), withrenderShape/renderSegmentand a newrenderCapsule.fixtureDefsis replaced byshapeSpecs(a list ofShapeSpec, pairing aShapeGeometrywith an optionalShapeDef). The defaultcreateBody()auto-enablescontact/sensor events on shapes whose body or shape userData is a
ContactCallbacks, since thenew engine only generates events for shapes that opted in.
>=3.12.0/ Flutter>=3.44.0(root workspace, melos bootstrap,package, and
FLUTTER_MIN_VERSIONin CI).Forge2DGameawaitsinitializeForge2D()in itsonLoad, andForge2DWorldcreates itsphysics world lazily so that this can happen first. Without it every
Forge2DGamethrows on theweb, since that call is what loads the Box2D WebAssembly module. Code that creates a world
outside of a
Forge2DGamehas to await it itself.Fixture/Contact/Manifoldare gone) andall goldens regenerated.
flame'sMultiTapDispatcher.handleTapDownannotation changed from@internalto@visibleForTestingso the tests can use it without ignores.Examples and docs
padracing, and the package example are migrated. The examples for jointsthat no longer exist in Box2D v3 (gear, pulley, rope, friction, constant-volume) and the blob
example are removed.
doc/bridge_packages/flame_forge2d/forge2d.mdandjoints.mdare rewritten for the new API(including the new filter and wheel joints).
Verification
flutter testinpackages/flame_forge2d(45 tests, compiles native Box2D through build hooks),goldens visually inspected.
dart analyzeclean across the whole workspace.flutter build webof the examples app confirms the Box2D wasm module is bundled automaticallyat the package asset path.
Notes for the forge2d review (found during this migration)
Shape.geometryread-back was added upstream during this work and is what makesBodyComponentrendering possible without a Dart-side geometry registry.Forge2DWorld.BodyComponents no longer receive a finalendContactfor contacts that end due to thedestruction (the old engine fired those synchronously inside destroy).
Checklist
docsand added dartdoc comments with///.examplesordocs.Breaking Change?
Migration instructions
FixtureandFixtureDefare gone: create shapes withbody.createShape(geometry, ShapeDef(...)), where the geometry is aCircle,Capsule,Segment, orPolygon. Friction and restitution now live inShapeDef.material(a
SurfaceMaterial).body.fixturesbecomesbody.shapes.BodyComponent.fixtureDefsbecomesshapeSpecs, a list ofShapeSpec(geometry, [shapeDef]).renderFixturebecomesrenderShape,renderEdgebecomesrenderSegment, andrenderChainis gone (chain segments render as segments).
CircleShape()..radius = rbecomesCircle(radius: r, center: c),EdgeShape()..set(a, b)becomesSegment(point1: a, point2: b),PolygonShape()..setAsBoxXY(w, h)becomesPolygon.box(w, h), andChainShape()..createChain/createLoopbecomesbody.createChain(ChainDef(points: ..., isLoop: ...))(chains now require at least four points; the first and last points of an open chain areghost anchors).
BodyDef.anglebecomesBodyDef(rotation: Rot.fromAngle(angle)).ShapeDef.enableContactEvents(andenableSensorEventsfor sensors and their visitors). The defaultBodyComponent.createBody()enables them automatically when a
ContactCallbacksis present in the body's or shape'suserData.
ContactCallbacks.beginContact/endContactkeep their signatures but receive the new flame-sideContact(withshapeA,shapeB,bodyA,bodyB, begin-onlynormal/points, andisSensorEvent).preSolve/postSolveare removed: useForge2DWorld.preSolveCallbackwithShapeDef.enablePreSolveEvents, and hit events (ShapeDef.enableHitEvents+world.physicsWorld.contactEvents.hit) respectively.WorldContactListeneris replaced byContactEventsDispatcher, and thecontactListenerparameter of
Forge2DGamebycontactEventsDispatcher.world.physicsWorld.createRevoluteJoint(RevoluteJointDef(bodyA: ..., bodyB: ...))andjoint.destroy(). The available joints are distance, filter, motor, mouse, prismatic, revolute,weld, and wheel; gear, pulley, rope, friction, and constant-volume joints no longer exist. The
def
initializehelpers are gone; anchors are passed as local points(
body.localPoint(worldAnchor)).world.raycast(callback, p1, p2)becomescastRayClosest/castRay/castRayAll(taking an origin and a translation),
queryAABBbecomesoverlapAabb, andclearForcesandthe particle system are removed.
worldCenterbecomesworldCenterOfMass,setAwake(x)becomesisAwake = x,getInertia()becomesrotationalInertia, andworldVector(v)becomesrotation.rotate(v).platforms, and nothing extra on the web (the Box2D wasm module is bundled automatically).
Related Issues
Depends on flame-engine/forge2d#115 and flame-engine/forge2d#116.
Closes #2613