decentraland / decentraland/godot-explorer
Locomotion Iteration #1: Migrate Godot Physics to Jolt
- Dominant language
- Rust
- Stars
- 18
- Forks
- 19
- Avg merge
- 4d 2h
- Merged PRs (30d)
- 43
Description
## **⚠️ Problem:**
Godot Physics resolves capsule-vs-trimesh contacts inconsistently on thin and non-convex scene geometry — players tunnel through floors and stick on ramps that hold on desktop. Drives **Playtime**; no instrumented mobile baseline for fall-through rate exists today.
## **🏁 Scope:**
Swap the 3D physics server to Jolt on all build targets and revalidate character, scene-collider and raycast behavior. No locomotion tuning here — parameter parity ships in #1557, #2850, #2753.
## **📝 Deliverables:**
- [ ] Jolt enabled as 3D physics server; Godot Physics removed from build config
- [ ] iOS + Android + macOS + Windows + Linux builds green
- [ ] `SeparationRayShape3D` under the player verified against Jolt contact resolution
- [ ] Scene trimesh + primitive collider generation (`scene.rs`, `mesh_collider.rs`) regression-tested
- [ ] SDK raycast hit distances unchanged on flat + sloped geometry — guards #2830
- [ ] `stuck_detector` and `camera_mode_area_detector` Area3D overlaps unchanged
- [ ] Physics tick cost measured before/after on a mid-tier Android device
- [ ] Test scene `-98,103` walkthrough recorded before/after
## Notes
The #905 audit (§7) recommends against bundling the engine swap with parity behavior changes: all 6 parity bugs (B1–B6) are solver-independent script logic, and Jolt does not fix B2 — the one-way flag is set in `scene.rs`, not by the solver. Landing an engine swap and behavior changes in the same window makes regressions unattributable, the failure mode that killed #943 and #1417.
Product call: ship it in Iteration 1 anyway. Mitigation — keep Jolt in its own PR, separate from every parity fix, so a bisect stays possible.
## **🔗 References:**
- [#905](https://github.com/decentraland/godot-explorer/issues/905) — parent audit; §7 is the Jolt evaluation this issue overrides
- [#943](https://github.com/decentraland/godot-explorer/pull/943), [#1417](https://github.com/decentraland/godot-explorer/pull/1417) — both bundled Jolt with locomotion changes, both closed unmerged 2026-04-19
- [#1529](https://github.com/decentraland/godot-explorer/issues/1529) — one-way colliders act two-way (SPIKE, closed); root cause is our flag, not the solver — Jolt will not close it
- [#2830](https://github.com/decentraland/godot-explorer/issues/2830) — raycast `hitDistance` grows on sloped geometry, mobile only; the solver swap must not move it
Contributor guide
Assessment
This issue has not been assessed yet.