Godot Rapier Physics: swapping Godot's physics core for a Rust one

A drop-in replacement for the physics engine Godot ships with

Godot Rapier Physics is a physics engine for the Godot game engine, in both 2D and 3D. It is not a plugin that adds new gameplay to your project. It replaces the solver, and the project presents it as a drop-in replacement, which is a stronger claim than it sounds: the surrounding Godot API stays the same and only the implementation behind it changes.

The core is rapier, the Rust physics library, and the fluid simulation comes from salva, another Rust library from the same ecosystem. The addon itself is written in Rust and ships as a GDExtension, so the physics runs in native code rather than in the engine's own implementation.

The stated motivations are stability without the jittering some simulations show, performance, liquids, determinism, state serialization, and the absence of ghost collisions. Several of those are visible in the repository structure itself, with bin2d/ and bin3d/ directories holding the per-dimension binaries, src/ holding the Rust source, and THIRDPARTY.txt recording the licensing of the vendored dependencies.

The licence is MIT, and the project is not archived, with the last push on 2026-10-14.

The whole installation is one setting change

There are two routes, and the recommended one is automatic. The plugin is on the Godot Asset Store, with a separate entry for Rapier Physics 2D and for Rapier Physics 3D, and you install it from the Asset Store tab inside Godot. There is a single build per dimension, and that build runs the parallel SIMD solver and is cross platform deterministic.

The manual route is to download the latest GitHub release and move only the addons folder into your project's addons folder. No other files are needed, because the compiled binaries and the addon metadata travel together in that folder.

Either way the same two steps finish the job. In Godot, go to Advanced Settings, then Physics, then 2D or 3D, and change the Physics Engine value to Rapier2D or Rapier3D. That setting is the switch. There is no separate scene, no autoload to register and no configuration file to edit, which is what makes this a realistic thing to try on a real project rather than a demo.

The web and mobile targets are covered by the same builds, so a project that ships on desktop and web does not need two physics configurations to test.

Determinism and SIMD are not things you opt into

The build configuration is where this project differs from an ordinary addon, and it is worth reading before you copy a Cargo snippet from somewhere else.

SIMD is always compiled, with a scalar fallback on targets that lack it, and enhanced-determinism is enabled on the rapier dependencies for every build. The parallel feature stays optional because web builds cannot use it. In other words, the claims of exact simulation on the same platform and across platforms are properties of the shipped build rather than a compile-time choice you can forget.

The dependency declaration pins a tag and a dimension feature, and the project asks you to use exactly one Godot API feature, choosing between api-4-4, api-4-5, api-4-6 and api-4-7.

[dependencies]
godot-rapier = { git = "https://github.com/appsinacup/godot-rapier-physics.git", tag = "v0.36.0", features = ["single-dim2"] }

The feature sets that match the shipped addon builds are listed in the documentation, and they name the same combination for both dimensions, single-dim2 or single-dim3 together with serde-serialize, parallel, experimental-threads, register-docs and api-4-7.

For web and Emscripten builds the choice narrows to one of two features, experimental-wasm for threaded web builds and experimental-wasm-nothreads for builds without threads, where the second includes the first.

The one-main-extension rule bites Rust developers

If you embed the physics in your own Rust GDExtension rather than shipping the standalone addon, you hit a Godot constraint that the documentation explains in detail. Godot runs only one main ExtensionLibrary, so your extension has to set the GDRUST_MAIN_EXTENSION environment variable to your own ExtensionLibrary type and forward Godot Rapier's init stages explicitly, registering the Rapier server and classes as well.

The forward of the init and deinit stages to RapierPhysics3DExtensionLibrary is the part that is easy to miss. For a 2D project you use RapierPhysics2DExtensionLibrary instead.

There is a related trap in the same paragraph. You must not load the standalone Godot Rapier addon in the same Godot project when you bundle it through another Rust GDExtension, because Godot classes can be registered twice. In practice that means picking one integration route per project rather than combining them for convenience.

For teams that want the physics inside a Godot build rather than as an extension, the project publishes separate module repositories for the 2D and 3D versions, which is the other way to consume the same code.

Where the behaviour differs from stock Godot on purpose

The limitations section is unusually specific, and two entries will change how your existing code behaves.

The first is asymmetric collisions. There is no support for a case where object 1 hits object 2 but object 2 does not hit object 1. The check rapier performs is given exactly in the documentation, (A.layer & B.mask) != 0 || (B.layer & A.mask) != 0, which means a pair collides if either side's layer intersects the other's mask. If your project relies on one-sided collision responses, that assumption breaks here.

The second is 2D point queries. intersect_point skips objects whose input_pickable is off, and physics bodies have that flag off by default. The reason is that Godot does not tell a GDExtension whether a point query came from mouse picking or from a script, so Rapier honours input_pickable for both, in order to keep mouse picking correct.

The fix is one of two switches. Turn on input_pickable on the bodies, or disable the physics/rapier/queries/point_query_honors_pickable project setting. With the setting off, mouse picking also reaches objects that are not pickable, which is the trade the documentation is making explicit.

The 2D side is stable and the 3D side is not finished

The implementation progress statement in the project is direct about this. The 2D part is described as pretty stable, though with some issues, and the 3D part as still missing some things. The project points at a progress page that lists the status of each feature so you can see where a given capability stands rather than guessing from a release number.

That distinction matters when you decide whether to switch a whole project. A 2D game that needs deterministic stepping and fluids has a fairly complete tool to move to. A 3D game has to check the specific features it depends on, because the gap is itemised rather than described in general terms.

The feature list is also where the differences from a default solver become concrete. There are 2D and 3D fluid demonstrations, body skin, inverse kinematics, ghost collision comparisons, improved stacking, and save and load of physics state. Those are the capabilities worth matching against your own list of requirements before you spend an afternoon switching engines.

One build note belongs with the limitations rather than the features: double-precision builds have to be built manually, so the shipped addons are single precision.

MIT terms, a Rust toolchain requirement and frequent releases

The licence is MIT, and the repository also ships THIRDPARTY.txt, which is the file to read if you are bundling the addon into a commercial game, because the vendored rapier and salva code carries its own licensing terms. We are not in a position to advise on the details, but the file exists and it is short.

The build requirements are specific. The crate declares version 0.36.0, on edition 2024, with a rust-version of 1.94, and the package is marked as not for publishing. The library builds as a cdylib, a staticlib and an rlib, which is what allows the same source to serve the extension build, the module builds and the tests.

Release activity is high. v0.36.0 shipped on 2026-10-02, preceded by v0.35.4 on 2026-09-08 and v0.35.3 on 2026-08-30, and the last push was on 2026-10-14. A changelog is kept in the repository, and the project is active enough that the changelog, rather than the version number, is the place to look before upgrading a shipped game.

There is also documentation, a Discord server, a contributing guide and an architecture document in the repository, plus a showcase page for games built with the addon.

Editorial conclusion

Godot Rapier Physics fits a Godot 4.7 project that needs deterministic simulation for replays or networked play, wants liquid behaviour in 2D or 3D, or has hit stacking and ghost collision artefacts in the built-in solver. It does not fit a project that needs the 3D feature set to be complete today, or a web build that assumes the parallel solver is available, because the parallel feature is unavailable on web targets. Verify three things before switching: the asset store entry for your dimension, since there is a single build per dimension, the implementation progress page for the 3D features you actually need, and the 2D point query behaviour, because intersect_point honours input_pickable by default and that changes what your script queries can see.

Frequently asked questions

Official sources

1. appsinacup/godot-rapier-physics on GitHub
2. License: MIT
3. Project website
4. README
5. Releases