dimforge/rapier.rs

Official website for the Rapier physics engine.

Website

This website is built using Docusaurus 2, a modern static website generator.

Installation

$ yarn

Local Development

$ yarn start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Build

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

rapier.rs's Issues

The bevy_plugin/advanced_collision_detection page is out-of-date

Thank you for the amazing library, and the amazing docs! There was just one thing I noticed.

There's this code block on the website:

fn main() {
    App::build()
        .add_plugins(DefaultPlugins)
        .add_plugin(RapierPhysicsPlugin::<NoUserData>::default())
        .add_startup_system(setup_physics.system())
        .run();
}

struct MyPhysicsHooks;

impl PhysicsHooksWithQuery<NoUserData<'_>> for MyPhysicsHooks {
    fn modify_solver_contacts(
        &self, 
        context: ContactModificationContextView,
        _user_data: &Query<NoUserData>
    ) {
        // This is a silly example of contact modifier that does silly things
        // for illustration purpose:
        // - Flip all the contact normals.
        // - Delete the first contact.
        // - Set the friction coefficients to 0.3
        // - Set the restitution coefficients to 0.4
        // - Set the tangent velocities to X * 10.0
        *context.normal = -*context.normal;

        if !context.solver_contacts.is_empty() {
            context.solver_contacts.swap_remove(0);
        }

        for solver_contact in &mut *context.solver_contacts {
            solver_contact.friction = 0.3;
            solver_contact.restitution = 0.4;
            solver_contact.tangent_velocity.x = 10.0;
        }

        // Use the persistent user-data to count the number of times
        // contact modification was called for this contact manifold
        // since its creation.
        *context.user_data += 1;
        println!("Contact manifold has been modified {} times since its creation.", *context.user_data);
    }
}

fn setup_physics(mut commands: Commands) {
    // Register our physics hooks.
    commands.insert_resource(PhysicsHooksWithQueryObject(Box::new(MyPhysicsHooks {})));

    // Add colliders with a `CustomFilterTag` component. Only colliders
    // with the same `CustomFilterTag` variant will collider thanks to
    // our custom physics hooks:
    commands.spawn()
        .insert(Collider::ball(0.5))
        .insert(ActiveHooks::MODIFY_SOLVER_CONTACTS);

    // TODO: add other colliders in a similar way.
}

This is out of date in multiple ways. PhysicsHooksWithQueryObject has been renamed to PhysicsHooksWithQueryResource. Also, NoUserData<'_> no longer takes a type parameter. Additionally, ContactModificationContextView has no normal or solver_contacts fields

I'd make a PR and the first two are pretty easy to fix, but the last one requires going from context.normal to context.raw.manifold.data.normal, but that causes an error on the *context.normal = -*context.normal; line:

cannot apply unary operator `-` to type `bevy_rapier3d::nalgebra::coordinates::XYZ<f32>`

Code blocks have light background even when dark mode is enabled

Regular dark mode:

Dark mode with DarkReader:

[docs typo]

would make pr but dont know where they are
lean 🥤

Document `AsyncCollider` and `AsyncSceneCollider` for Bevy plugin

AsyncCollider and AsyncSceneCollider are pretty commonly needed by users of the Bevy plugin, but they are not mentioned in the usage docs and don't have any code examples in the docs.rs docs, which makes them difficult to discover.

The components should be documented on the Colliders page along with a code example. (They should also have a docs.rs code example on the bevy_rapier side and an example in the bevy_rapier repository)

Benchmarks are broken

https://www.rapier.rs/benchmarks/

Missing tuple brackets in query

rapier.rs/docs/user_guides/templates/character_controller_setup.mdx

Line 130 in fd45995

fn read_result_system(controllers: Query<Entity, &KinematicCharacterControllerOutput>) {

Benchmarks page is out of date

The latest benchmark on https://rapier.rs/benchmarks/ is from 2021-09-12. Probably the page should be updated, removed, or at least a notice at the top explaining the state of Rapier benchmarks.

Add issue and PR templates

What problem does this solve or what need does it fill?

This repository doesn't have any issue or PR templates. For consistency and to uphold a certain bar of quality for issues, basic templates could be very useful.

What solution would you like?

Add templates. This issue's structure is an example of what an issue template could be (inspired by one of Bevy's issue templates).

What alternative(s) have you considered?

Keep it as is, without any default structure or guidance.

"Collision groups and solver groups" for bevy plugin is out of date

The corresponding section of documentation is provided with out of date examples -- the code just does not compile.

// fails
// CollisionGroups::new(0b1101.into(), 0b0100.into());
// SolverGroups::new(0b0011.into(), 0b1011.into());

// ok
CollisionGroups::new(
    Group::from_bits(0b1101).unwrap(),
    Group::from_bits(0b0100).unwrap(),
);
SolverGroups::new(
    Group::from_bits(0b0011).unwrap(),
    Group::from_bits(0b1011).unwrap(),
);

Document how to control simulation parameters

What problem does this solve or what need does it fill?

Simulation details like the timestep, solver iteration count, "slop" (allowed penetration), damping, and so on can be modified using the IntegrationParameters configuration. It is briefly mentioned in the "Simulation structures" section of the core Rapier docs, but it essentially just points to API docs, which doesn't really cover how the parameters can be accessed or modified. The descriptions of the properties are also rather brief and often not very user-friendly (What are PGS iterations? Or islands? How do CCD substeps differ from solver iterations?).

In addition, the docs for the Bevy plugin and JS bindings don't mention the integration parameters at all, and the way they are accessed is different from the core Rapier. For example, in the Bevy plugin, they are in the RapierContext resource (which is also not on the website except for the spatial query sections).

What solution would you like?

It would be very useful to have these kinds of simulation configuration options documented. It should cover how they can be accessed and modified, and how the most important options (like the timestep and solver iteration count) affect the simulation. These docs should exist for the Bevy plugin and JS bindings in addition to the core Rapier.

Document `RapierContext` resource for Bevy plugin

What problem does this solve or what need does it fill?

The RapierContext resource is quite a critical part of bevy_rapier. It contains all of the simulation structures, rigid body and collider sets, and IntegrationParameters (also related: #91). It is also used for scene queries and for getting collider parents and contact pairs, and I believe it can even be used to manually step the simulation. Despite all this, it is not mentioned anywhere in the bevy_rapier usage docs except that it is used for scene queries.

It should really be documented to at least mention the things that it contains, and all of the core tasks that it can be used for, along with code examples.

What solution would you like?

Document RapierContext on the website. This could be a part of a "Simulation structures" section similar to the core Rapier, but with more code examples and concrete usage docs, or it could have its completely own section.

Parallel queries from JS

I would love to take advantage of the multi threading inside Rapier when I raycast or shapecast. Would it be possible to add a set of bulk functions that would take an array of queries and return the responses? Ideally one that I could provide the pre-allocated results so that I can re-use them frame to frame.

The JS multi threading is garbage and my Rust is not very strong otherwise I'd do it myself. I'm using the wasm version.

Great work on the library!

Document `RopeJoint`

Similarly to #89, the RopeJoint should be documented on the website.

Broken links

The docs contain broken links - examples:

• https://rapier.rs/docs/user_guides/rust/colliders/ : "or with contact modification"
• https://rapier.rs/docs/user_guides/rust/advanced_collision_detection/ : "See the rigid-body CCD section for details"

Note these are just 2 examples i ran into, there's probably more (especially since both seem to have the same cause - the relative links should go up first).

Both return 404 so it should be possible to write a periodic CI action to check all links on the website and detect this automatically.

nalgebra `vector!` macro usage in Rust > Getting Started causing issues

Just tried out the Getting Started code example (on complete_docs branch) and it currently doesn't compile since the vector! macro errors at compile time: use of undeclared crate or module nalgebra.

I tried importing the macro by using use rapier3d::na::vector; but I still have the same error. I've worked around it by just using rapier3d::na::Vector3 for now.

bevy add_plugin and add_startup_system deprecated

Was going through the doc to run example code for bevy plugin and noticed some deprecated calls.

From the doc:
add_plugin , deprecated as of 0.11.0. use add_plugins instead.
add_startup_system, deprecated as of 0.11.0, use add_systems(Startup, your_system).

I'll create a PR for this since it's a simple enough update.

Document `SpringJoint`

Rapier has a SpringJoint for constraining the distance between two bodies, but it is not mentioned on the website. People often have to ask whether a joint like this exists or scramble through the API docs and source code to find it.

It should have usage documentation like the other joints. This currently applies to all versions of Rapier, including the Bevy plugin and JS bindings.

Document timesteps and scheduling for the Bevy plugin

What problem does this solve or what need does it fill?

Related to #91.

Timesteps and scheduling details can be very important for Bevy games. The default timestep in bevy_rapier is a variable timestep, but for a lot of games it can be better to run physics in FixedUpdate with a fixed timestep, or even in a custom schedule for e.g. networking purposes. I believe a fixed timestep is even the default in most game engines like Unity.

It should be properly documented how users can configure their timesteps and the schedule in which physics is run, and what tradeoffs and benefits each option has (e.g. determinism, performance, visual smoothness, and so on).

What solution would you like?

Document timesteps and physics scheduling for Bevy. This could have its own page or be a part of something like #91.

Nonexistent method in docs

The page https://rapier.rs/docs/user_guides/rust/simulation_structures/ mentions physics_pipeline.update(...); - is that meant to be physics_pipeline.step(...); instead?

JS: make sure all the functions taking callbacks are not registering an event listener.

This has been a common misconception where, an JS, event listener are a quite common pattern. But, in Rapier, these function (drainCollisionEvents,intersectionsWith, etc.) only gets called once as they don’t register any persistent "event handler".
See https://discord.com/channels/507548572338880513/748814906953826334/1197087923053535272

'Joints must be inserted into a ImpulseJointSet'?

Please correct me if I'm misunderstanding, but this seems to ignore the existence of Multibody joints:

rapier.rs/docs/user_guides/templates/joints.mdx

Lines 44 to 45 in 7307c90

	Currently, Rapier supports **fixed**, **spherical**, **prismatic**, and **revolute** joints. Joints must be inserted into a
	`ImpulseJointSet`. Each joint is attached to two distinct rigid-bodies identified by they rigid-body handles.

This other page referencing ImpulseJointSet as the only joint set may also need a change to include Multibody joints:

rapier.rs/docs/user_guides/templates/simulation_structures.mdx

Lines 132 to 138 in 7307c90

	## Joint set
	The `ImpulseJointSet` contains all the **impulse-based joints** that needs to be simulated. This set is represented as a
	generational-arena, i.e., a vector where each element is indexed using a __handle__ that combines
	an `u32` index and an `u32` generation number. This ensures that every joint is
	given a unique handle.
	Learn more about joints in [the dedicated page](joints).

Redundant code in character controller offset example

docs/user_guides/bevy_plugin/character_controller#character-offset has two copies of the same code, with slightly different comments. Probably a merge gone wrong.

/* Configure the character controller when the collider is created. */
commands.spawn(Collider::ball(0.5))
    .insert(KinematicCharacterController {
        // The character offset is set to 0.01.
        offset: CharacterLength::Absolute(0.01),
        ..default()
    });

commands.spawn(Collider::ball(0.5))
    .insert(KinematicCharacterController {
        // The character offset is set to 0.01 multiplied by the collider’s height.
        offset: CharacterLength::Absolute(0.01),
        ..default()
    });

Document additional solver iterations

What problem does this solve or what need does it fill?

Related to #91.

The new small-steps solver added the ability to give rigid bodies additional solver iterations to improve the simulation accuracy of individual bodies. In bevy_rapier, this uses the AdditionalSolverIterations component.

This is not documented anywhere on the website.

What solution would you like?

Document additional solver iterations for rigid bodies.

Document vehicle controller

Rapier and its JS bindings (but not the Bevy plugin) have a vehicle controller. However, it is not mentioned anywhere on the website, making it difficult to discover, especially considering the rather verbose name DynamicRayCastVehicleController.

The vehicle controller should be mentioned on the website and have usage documentation, assuming it is complete enough to be properly usable.

Thoughts from a newb on the getting started documentation

I have been starting to use Rapier for a project, and thought I would write down some of the sticking-points regarding the getting started guide. I am something of a newbie at rust and at physics engines, so feel free to close this issue if you think it is off-topic or if I am being to noobish.

---

The rust user guide for how to use bevy ends with the main loops being:

loop {
        pipeline.step(
            &gravity,
            &integration_parameters,
            &mut broad_phase,
            &mut narrow_phase,
            &mut bodies,
            &mut colliders,
            &mut joints,
            &mut ccd_solver,
            &physics_hooks,
            &event_handler
        );
    }

for all the demos.

As a new user of rapier, I was initially confused how to get information back out of the engine (aka what do I do with a body handle). Perhaps extending the first example with:

println!(bodies.get(body_handle).position())

---

I initially found attaching collision shapes to rigid bodies fairly confusing: To me a CollisionSet was a just set of collision shapes - the same as the RigidBodySet is just a set of rigid bodies. This isn't helped by the getting started guide stating

A collider set is a container that maps a unique handle to a collider:

Perhaps a simple change to:

A collider set is a container that maps a unique handle to a collider and maps colliders to rigid bodies

---

Do you think it is worth me creating a PR with these changes?

---

Side note, why does every rust project have a bunch of documentation outside cargo-doc? It means I have to learn dozens of different static site generators to make PR's on them, and it's out-of-sync with the codebase, not auto-tested etc. etc.
Have you considering moving the pure-rust documentation into the crates module-level docs? There is a lot of stuff that can be directly copy-pasted from one to the other. Is it worth creating a bunch of PR's on the main Rapier repo doing this?

Document Bevy `Transform` interpolation

What problem does this solve or what need does it fill?

Related to #95.

The movement of rigid bodies in the Bevy plugin can be interpolated by using TimeStepMode::Interpolated and adding the TransformInterpolation component to a rigid body. However, this is not documented anywhere on the website.

What solution would you like?

Document transform interpolation, how it works, and the potential tradeoffs it has. This could be in the same section as #95.

Documentation issue

Page:
https://rapier.rs/docs/user_guides/javascript/physics_event_handling

Should be .drainIntersectionEvents vs .drainIntersection.

Javascript user guide on joint has incorrect examples

The examples for the joints on this url https://rapier.rs/docs/user_guides/javascript/joints

Says RAPIER.JointParams but since 0.8 when createJoint was renamed createImpulseJoint, JointParams was renamed JointData.

Add links to the the Bevy plugin's docs.rs under API Documentation

The API Documentation section in the side menu has links to the various flavors of the JavaScript APIs and to various flavors of the main Rapier APIs, but not to the Bevy plugin APIs (bevy_rapier2d and bevy_rapier3d). It would be helpful if you could add them.