Add AppOptions.physicsWorld for explicit physics backend selection

[willeastcott]

Description

Follow-up to #9043, which decoupled physics into a backend abstraction but deferred "a public selection API (e.g. via AppOptions) until a second real backend lands". This PR lands that API now, proven with the existing backends, so that a future backend (e.g. Jolt) becomes purely additive — a new leaf module plus one line of user code, with zero framework changes.

const options = new AppOptions();
options.physicsWorld = new AmmoPhysicsWorld(); // or new NullPhysicsWorld()

What changed

• AppOptions.physicsWorld (instance-valued, mirroring soundManager): AppBase.init() installs it into the RigidBodyComponentSystem, which registers itself as the world's contact listener — users never touch listener plumbing. Injection happens before onLibrariesLoaded, so Ammo auto-detection is cleanly skipped when a world is supplied.
• Minimal public @alpha surface: PhysicsWorld, AmmoPhysicsWorld and NullPhysicsWorld are exported; the documented API is just the constructors, PhysicsWorld#nativeWorld (the native escape hatch) and RigidBodyComponentSystem#physicsWorld. The backend contract methods (createBody, createShape, joints, raycasts, descriptor typedefs) stay @ignored — implementer documentation lives in the source and the .d.ts retains full types for subclassing, but the docs site and API report only advertise what applications actually call.
• Parameterless constructors: the contactListener constructor option was redundant once the system wires the listener on install, so it's removed. AmmoPhysicsWorld now Debug.asserts with a clear message if constructed before the Ammo library has loaded.
• Cleanups: removed the dead off('update') branch in onLibraryLoaded, declared the Ammo world's constructor-assigned internals as tagged class fields so they no longer leak into the generated API reference, and made the RigidBodyComponentSystem class doc backend-neutral.
• Tests: new test/framework/physics/app-options-physics-world.test.mjs — the first tests to construct AppBase + AppOptions directly — covering installation during init, contact listener wiring, auto-detect skip, component body creation through the injected world, the single-install assert and world ownership on destroy.

Notes for reviewers

• No behavior change for existing applications: the Ammo auto-detect path (onLibraryLoaded) is untouched and remains the default for the Editor and engine-only apps that load Ammo without setting the option. It becomes the deprecation target for a future major, once explicit injection is the norm.
• The API report will flag the new @alpha surface — that's the intended minimal set.
• Generated docs pages were verified to show only the constructor and nativeWorld for each world class.

Checklist

• I have read the contributing guidelines
• My code follows the project's coding standards
• This PR focuses on a single change

🤖 Generated with Claude Code

[github-actions]

Public API report

This PR changes the public API surface (+11 / −0), per the docs' rules (@ignore / @Private / undocumented are excluded).

Show API diff

+AmmoPhysicsWorld.constructor()
+AmmoPhysicsWorld.nativeWorld: any
+AppOptions.physicsWorld: PhysicsWorld
+NullPhysicsWorld.constructor()
+NullPhysicsWorld.nativeWorld: any
+PhysicsWorld.constructor()
+PhysicsWorld.nativeWorld: any
+RigidBodyComponentSystem.get physicsWorld(): PhysicsWorld | null
+class AmmoPhysicsWorld extends PhysicsWorld
+class NullPhysicsWorld extends PhysicsWorld
+class PhysicsWorld

Informational only — this never fails the build.

[github-actions]

Build size report

This PR changes the size of the minified bundles.

Bundle	Minified	Gzip	Brotli
playcanvas.min.js	2391.8 KB (+0.4 KB, +0.02%)	615.1 KB (+0.1 KB, +0.02%)	477.1 KB (−0.1 KB, −0.03%)
playcanvas.min.mjs	2389.1 KB (+0.4 KB, +0.02%)	613.8 KB (+0.1 KB, +0.02%)	476.8 KB (+0.1 KB, +0.01%)

[willeastcott]

@LeXXik @mvaligursky, this is the groundwork needed to offer alternative physics back-ends. It's treeshake-friendly. Let me know if you have any concerns.

[LeXXik]

Looks good. I noticed we don't have an ability to pause the backend (e.g. game menu opened - world freezes). Something like app.physics.paused = true, so that step is not called (or can be called manually). Can be in another PR.

Edit: extracted feature request to #9272

[mvaligursky]

Look great.