feat: Let the length unit be set through initializeForge2D (#120)

# Description

Box2D has a handful of tolerances that are absolute lengths rather than
fractions of the shapes
they apply to. The most visible one is the speculative distance:
`manifold.c` stops generating
contact points past `B2_SPECULATIVE_DISTANCE` (`4 * B2_LINEAR_SLOP`, so
0.02 m), and
`contact.c` sets `touching = pointCount > 0`, which means `beginContact`
fires while there is
still a gap of up to 2 cm. A world laid out at a much smaller scale than
a meter is dominated by
this: shapes that are only a couple of centimeters across are
permanently in contact with their
neighbors.

This came up while migrating flame_forge2d (flame-engine/flame#3952),
where a reporter's ball had
a radius of exactly 0.02, and it took a week to track down because the
0.02 is not discoverable
from Dart.

Box2D's answer is `b2SetLengthUnitsPerMeter`, which scales all of them.
Its contract is
`@warning This must be modified before any calls to Box2D`, which a
free-standing setter cannot
enforce, so it is exposed through the `initializeForge2D` gate that
already has to run first:

```dart
await initializeForge2D(lengthUnitsPerMeter: 100);
```

- Passing the value already in effect is a no-op, so several games that
agree on a scale can each
ask for it. The comparison round-trips through float32, since that is
how Box2D stores it and
  values like `0.04` are not representable in either float width.
- A value that conflicts with the one in effect throws a `StateError`
once a `World` exists,
rather than silently corrupting live simulations and the defaults Box2D
hands out.
- Non-positive and non-finite values throw an `ArgumentError`.

`Tolerances` exposes the derived constants (`lengthUnitsPerMeter`,
`linearSlop`,
`speculativeDistance`, `aabbMargin`), so the 0.02 becomes a documented
number that callers can
reason about and assert against instead of a mystery.

The web backend needs a keepalive wrapper: `b2SetLengthUnitsPerMeter`
and
`b2GetLengthUnitsPerMeter` are plain `B2_API` functions, so emcc drops
them without one.

The README gains a "Units" section covering the scale to lay a world out
at, the absolute
tolerances that bite when you do not, and how the other quantities scale
when you rescale a world
(lengths, velocities and gravity by `S`, masses by `S²`, forces and
impulses by `S³`, torques by
`S⁴`, with densities, friction, restitution and damping unchanged, which
leaves the timing of the
simulation unchanged).

## Testing

`dart test` runs suites as isolates that share one process, and
therefore one copy of the native
library, so a suite that changes the length unit would be visible to
whichever suites run
alongside it. `dart_test.yaml` therefore sets `concurrency: 1`, so
suites run one at a time as
part of the normal test run, and the mutating suite puts the length unit
back when it is done.
The whole suite takes a couple of seconds either way.

`melos test` passes and `melos analyze` is clean.

## Checklist

- [x] The title of my PR starts with a [Conventional Commit] prefix
(`fix:`, `feat:`, `docs:` etc).
- [x] I have read the [Contributor Guide] and followed the process
outlined for submitting PRs.
- [x] I have updated/added tests for ALL new/updated/fixed
functionality.
- [x] I have updated/added relevant documentation in `docs` and added
dartdoc comments with `///`.
- [-] I have updated/added relevant examples in `examples`.

## Breaking Change

- [ ] Yes, this is a breaking change.
- [x] No, this is *not* a breaking change.

Everything is additive: the new parameter is optional and defaults to
leaving the length unit
alone, and `Tolerances` is a new class.

## Related Issues

Needed by flame-engine/flame#3952, which uses it for worlds that cannot
be laid out at a
realistic scale, and reports the underlying problem as a debug-mode
warning.

<!-- Links -->
[issue database]: https://github.com/flame-engine/flame/issues
[Contributor Guide]:
https://github.com/flame-engine/flame/blob/main/CONTRIBUTING.md
[Flame Style Guide]:
https://github.com/flame-engine/flame/blob/main/STYLEGUIDE.md
[Conventional Commit]: https://conventionalcommits.org

Author: spydon

.github/workflows/build-wasm.yml

@@ -21,14 +21,21 @@ jobs:
           version: 4.0.15
       - name: Rebuild box2d.wasm
         run: packages/forge2d/tool/build_wasm.sh
+      # Uploaded before the check so that the fresh build is downloadable
+      # exactly when the check fails and you need it.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: box2d-wasm
+          path: packages/forge2d/lib/src/backend/wasm/box2d.wasm
       - name: Verify the committed artifact is up to date
         run: |
           if ! git diff --exit-code --stat -- packages/forge2d/lib/src/backend/wasm/box2d.wasm; then
             echo "The committed box2d.wasm differs from a fresh build."
-            echo "Rebuild it with tool/build_wasm.sh using emsdk 4.0.15."
+            echo
+            echo "emcc output is only reproducible on the same host platform,"
+            echo "and this check builds on Linux, so a rebuild on macOS or"
+            echo "Windows will not match byte for byte even with emsdk 4.0.15."
+            echo "Download the box2d-wasm artifact from this run and commit it"
+            echo "instead of the locally built one."
             exit 1
           fi
-      - uses: actions/upload-artifact@v4
-        with:
-          name: box2d-wasm
-          path: packages/forge2d/lib/src/backend/wasm/box2d.wasm

README.md

@@ -81,6 +81,51 @@ Highlights of the API:
 - `DebugDraw` can be implemented to render the physics world for
   debugging.
 
+## Units
+
+Box2D is tuned for meters, kilograms and seconds, so lay your world out in
+meters and aim to keep moving objects roughly between 0.1 and 10 of them,
+with 1 being the sweet spot. Rendering scale is a separate concern: decide
+how many pixels a meter is worth in your renderer, not in the simulation.
+
+Some of the tolerances are absolute lengths rather than fractions of the
+shapes they apply to, so a world laid out at a much smaller scale behaves
+oddly. The most visible one is the speculative distance: Box2D creates
+contact points for shapes that are approaching but not yet touching, which
+is what stops fast objects from passing through each other, and it means
+`beginContact` fires while there is still a gap of up to `0.02` meters. A
+shape that is only a couple of centimeters across is therefore permanently
+in contact with its neighbors. `Tolerances` exposes these values:
+
+```dart
+Tolerances.linearSlop;           // 0.005
+Tolerances.speculativeDistance;  // 0.02
+Tolerances.aabbMargin;           // 0.05
+```
+
+`WorldDef.restitutionThreshold` (1 m/s), `WorldDef.hitEventThreshold`
+(1 m/s), `WorldDef.maxContactPushSpeed` (3 m/s),
+`WorldDef.maximumLinearSpeed` (400 m/s) and `BodyDef.sleepThreshold`
+(0.05 m/s) are absolute in the same way, but they are per world or per body,
+so they can simply be set.
+
+When a world genuinely cannot be laid out at that scale, tell Box2D how many
+of your length units make up a meter and every tolerance above moves with it:
+
+```dart
+await initializeForge2D(lengthUnitsPerMeter: 100);
+```
+
+A good rule of thumb is to pass the height of your player character. You are
+then on the hook for gravity, densities and forces being sensible at that
+scale. For a length scale factor of `S`, velocities and accelerations scale
+by `S`, masses by `S²`, forces and impulses by `S³` and torques by `S⁴`,
+while densities, friction, restitution and damping stay as they are. Scaling
+lengths and gravity together leaves the timing of the simulation unchanged.
+
+The length unit is process-wide and cannot change once a `World` exists,
+which is why it is set through `initializeForge2D`.
+
 ## Performance
 
 The standard [bench2d](https://github.com/joelgwebber/bench2d) benchmark

packages/forge2d/dart_test.yaml

@@ -3,3 +3,11 @@
 #   dart test -p chrome            (dart2js)
 #   dart test -p chrome -c dart2wasm
 platforms: [vm]
+
+# The Box2D length unit is a process-wide global, and `dart test` runs suites
+# as isolates that share one process and therefore one copy of the library, so
+# a suite that changes it would be visible to any suite running alongside it.
+# Suites run one at a time instead, and the ones that change the length unit
+# put it back when they are done. The whole suite takes a couple of seconds
+# either way, so there is nothing to win by relaxing this.
+concurrency: 1

packages/forge2d/lib/forge2d.dart

@@ -21,5 +21,6 @@ export 'src/api/joints/weld_joint.dart';
 export 'src/api/joints/wheel_joint.dart';
 export 'src/api/math.dart';
 export 'src/api/shape.dart';
+export 'src/api/tolerances.dart';
 export 'src/api/world.dart';
-export 'src/initialize.dart' show initializeForge2D;
+export 'src/initialize.dart' show debugResetLengthUnitLock, initializeForge2D;

packages/forge2d/lib/src/api/tolerances.dart

@@ -0,0 +1,53 @@
+import 'package:forge2d/src/initialize.dart';
+
+/// The Box2D tolerances that scale with the length unit.
+///
+/// Box2D is tuned for meters, kilograms and seconds, and a handful of its
+/// tolerances are absolute lengths rather than fractions of the objects they
+/// apply to. If a world is laid out at a much smaller scale than a meter,
+/// those tolerances stop being "visually insignificant" and start dominating
+/// the simulation: shapes report contacts before they touch, and the
+/// broadphase margin grows larger than the shapes themselves.
+///
+/// The usual fix is to lay the world out so that moving objects are roughly
+/// 0.1 to 10 meters, with 1 meter being the sweet spot. When that is not
+/// possible, tell Box2D what a meter means in your units with
+/// `initializeForge2D(lengthUnitsPerMeter: ...)`, and every value here moves
+/// with it.
+///
+/// These mirror the constants in `src/constants.h` of Box2D v3.1.1. There are
+/// further absolute thresholds that the length unit scales but that are
+/// per-world or per-body rather than global, so they are fields on the
+/// definitions instead: `WorldDef.restitutionThreshold`,
+/// `WorldDef.hitEventThreshold`, `WorldDef.maxContactPushSpeed`,
+/// `WorldDef.maximumLinearSpeed` and `BodyDef.sleepThreshold`.
+abstract final class Tolerances {
+  /// How many length units make up one meter, mirroring
+  /// `b2GetLengthUnitsPerMeter`.
+  ///
+  /// Defaults to 1, meaning that forge2d lengths are meters. Set it through
+  /// `initializeForge2D(lengthUnitsPerMeter: ...)`.
+  static double get lengthUnitsPerMeter => rawBox2D.getLengthUnitsPerMeter();
+
+  /// The collision and constraint tolerance, `0.005` of a meter.
+  ///
+  /// Shapes are allowed to overlap by this much so that contacts stay stable.
+  static double get linearSlop => 0.005 * lengthUnitsPerMeter;
+
+  /// The separation at which shapes start reporting contacts, `0.02` of a
+  /// meter, or four times the [linearSlop].
+  ///
+  /// Box2D creates contact points for shapes that are approaching but not yet
+  /// touching, which is what keeps fast objects from passing through each
+  /// other and removes most collision jitter. It also means that
+  /// `beginContact` fires while there is still a visible gap, so shapes that
+  /// are not comfortably larger than this behave as if they were permanently
+  /// in contact.
+  static double get speculativeDistance => 4 * linearSlop;
+
+  /// How much the broadphase fattens shape bounds, `0.05` of a meter.
+  ///
+  /// Lets a shape move a little without the dynamic tree having to be
+  /// rebuilt.
+  static double get aabbMargin => 0.05 * lengthUnitsPerMeter;
+}

packages/forge2d/lib/src/api/world.dart

@@ -46,7 +46,10 @@ class World {
         maximumLinearSpeed: definition.maximumLinearSpeed,
         enableSleep: definition.enableSleep,
         enableContinuous: definition.enableContinuous,
-      );
+      ) {
+    // Freezes the length unit: it is baked into this world's tolerances.
+    markWorldCreated();
+  }
 
   /// The packed native world id.
   @internal

packages/forge2d/lib/src/backend/raw_box2d.dart

@@ -8,6 +8,17 @@
 /// The contract is deliberately restricted so that every implementation can
 /// provide it cheaply. See README.md in this directory before changing it.
 abstract interface class RawBox2D {
+  // Global tuning.
+
+  /// Sets the process-wide length unit, mirroring `b2SetLengthUnitsPerMeter`.
+  ///
+  /// Box2D must not have been called before this, which the API layer
+  /// enforces in `initializeForge2D`.
+  void setLengthUnitsPerMeter(double lengthUnits);
+
+  /// The process-wide length unit, mirroring `b2GetLengthUnitsPerMeter`.
+  double getLengthUnitsPerMeter();
+
   // World lifecycle.
 
   /// Creates a world and returns its packed id.

packages/forge2d/lib/src/backend/raw_box2d_ffi.dart

@@ -61,6 +61,15 @@ final class RawBox2DFfi implements RawBox2D {
     ..c = cos
     ..s = sin;
 
+  // Global tuning.
+
+  @override
+  void setLengthUnitsPerMeter(double lengthUnits) =>
+      b2.b2SetLengthUnitsPerMeter(lengthUnits);
+
+  @override
+  double getLengthUnitsPerMeter() => b2.b2GetLengthUnitsPerMeter();
+
   // World.
 
   @override

packages/forge2d/lib/src/backend/raw_box2d_wasm.dart

@@ -110,6 +110,16 @@ final class RawBox2DWasm implements RawBox2D {
     _unsigned32(_runtime.readI32(_out + 4)),
   );
 
+  // Global tuning.
+
+  @override
+  void setLengthUnitsPerMeter(double lengthUnits) =>
+      _call('f2d_set_length_units_per_meter', [lengthUnits]);
+
+  @override
+  double getLengthUnitsPerMeter() =>
+      _callF('f2d_get_length_units_per_meter', const []);
+
   // World.
 
   @override