OptionaldeterminismThe reproducibility tier the world asks for (§33). Defaults to
"same-runtime" (Appendix A). A world may not ask for more than its
adapter declares in PhysicsCapabilities.determinism; the world checks
that at construction (WP-5.3).
"2d" or "3d" (§21). Required — there is no defensible default.
OptionalgravityWorld gravity in m/s². Defaults to (0, -9.81, 0) (Appendix A); a
Vector2 widens to z = 0, and a "2d" world rejects a non-zero z.
Optionallocal§21 simulation plane in world space. Bodies with
RigidBody.space === "local-plane" author a 2D pose in this plane's
frame; feed/publish maps through the plane basis.
Omitted means origin 0, normal +Z, xAxis +X (the world XY plane —
the 2D default). addBody accepts "local-plane" against that default.
Screen / viewport / camera / billboard stay refused (§8).
Engine-side: not forwarded to adapter.initialize.
OptionalonCalled once per solver "auto" skips, in registration order — the
solver-side twin of §62's fallback diagnostics event, and a callback for
the same reason: the frozen §3.1 matrix gives @fourjs/physics no
@fourjs/diagnostics edge.
Never called for an explicitly named solver, which is handed back unfiltered so the world reports the mismatch itself.
Optionalsleeping§32 sleeping thresholds. A partial record is merged over
DEFAULT_SLEEPING_CONFIG by resolveSleepingConfig, so
{ timeThreshold: 2 } changes one field and keeps Appendix A's rest.
OptionalsolverConstraint-solver iterations per step (§28 "solver iterations") — a world-level accuracy/cost dial, closing the gap recorded at the Phase 6 exit ("§28 solver-iterations feature not exposed anywhere", 2026-08-02; closed 2026-08-04).
World-level and not per-joint because that is what solvers actually
offer: Rapier 0.19.3 exposes exactly World.numSolverIterations
(default 4 — more iterations, stiffer joints and stacks, linearly more
cost). Omitted means the solver's own default, so existing worlds —
and every recorded §33/§34 checksum and replay — are untouched.
Setting it is checksum-affecting, exactly like changing gravity: two
runs must use the same value to reproduce.
A positive integer; validated at construction (§85).
Optionalunits§40 scale factors for authored numbers (§40, §101).
Structurally the scale half of @fourjs/core's unit-system record
(lengthToMeters, massToKilograms); pass that record through. When
set, authored gravity / poses / masses are converted into SI for the
solver and converted back on publish. Internal solver state is SI.
Omitted means today's identity path — existing tests stay bit-identical.
This field is engine-side: adapter.initialize is handed the
resolved SI gravity and never sees the scale record.
PhysicsWorldOptions plus the §37 rejection report.