A drawback of substepping is that it does not damp out high frequency vibrations due to reduced numerical damping. This can yield visual jittering. However, numerical damping can easily be reintroduced by adding true physical damping. Also, for small time steps, double precision floating point numbers are required. While doubles are as fast as floats on CPUs, they currently still reduce the performance on GPUs. Updating constraint directions after each projection might cause instabilities when simulating tall stacks or piles of objects. Investigating this problem is one of our directions of future work.

Had a go at making crates with different precision levels, since it seems there are good reasons to prefer f64.

What do you think? It adds a bit of complexity to the crate, though... perhaps it's better to just scrap the f32 versions, like in @Aceeri's https://github.com/Jondolf/bevy_xpbd/compare/main...Aceeri:bevy_xpbd:doubles?expand=1 ?

I'm messing around with some simple planets and I'm trying to manually set the mass in order to calculate gravitational pull or what not. Right now, I can do something like that:

#[derive(Bundle)]
pub struct PlanetBundle {
    pub planet: Planet,

    pub position: Position,

    pub rigid_body: RigidBody,

    pub mass: Mass,
}

But it's never exactly what I set it to after the first frame or so. For example, when I set a mass of 200.0 it eventually gets changed to 219.31 or something. I remember seeing some code in the lib that added to the mass based off the mass properties so that's probably why.

Is there any way to override the default behavior of the mass changing?

Currently, bevy_xpbd uses the components Pos and Rot for describing the position and orientation of bodies. At the end of each iteration of the main physics loop, these are synchronized with bevy's Transforms.

I'd like to discuss if we should remove the separate components and move to just using bevy's own Transforms.

Advantages

• More familiar and convenient for bevy users
• More complete APIs
• Reduces code and maintenance overhead (for example, no custom Rot implementations for 2D and 3D, all rotations use Quats)
• Less components and nicer queries (Transform and PrevTransform instead of Pos, PrevPos, Rot, and PrevRot)
• No need for synchronization step
• If/when bevy gets an editor eventually, it would make more sense to manipulate Transforms directly
• It's what most physics engines seem to do (like bevy_rapier)

Disadvantages

• Transform hierarchies, scaling and shearing can cause serious problems (see comments below)
• Parallellism might be harder, since two systems can't access the same Transform at once. Separate systems with Pos and Rot can run simultaneously.
• No f64 version of Transform unless we make a custom one (adding f64 as a crate feature: #7)
• In 2D, Pos uses Vec2 and Rot uses a scalar value. Transforms just have a Vec3 and a Quat, which can be considered less ergonomic for 2D. However, bevy users are used to working with them, and they might provide more freedom, so this may not be an issue.
• Migration pain (not a problem for us now, but could be in the future if this crate becomes more popular)
• Something else?

Conclusion

Personally, at least from an API standpoint, I think it makes sense to move to using just Transforms, as it would generally be much more convenient and familiar for bevy users, and it would also probably reduce the engine's code and complexity. Using Transforms for physics can cause many problems as well though, which is why I'd like to hear what others think.

Hi Jondolf, author of bevy_xpbd-the tutorial series here :) fun to see I inspired something and the project still goes on :)

From time to time, I've been toying with the idea of picking up and finishing my tutorial. My plan was to wrap up the friction chapter, clean up the language, and then making my own bevy_xpbd repo public and release on crates.io... which I guess I no longer have to do since you're way ahead of me :P

I'm still wondering if I should finish the tutorial itself, though, and I'm thinking about looking at your code for inspiration :) ...but I'm wondering: would you mind dual-licensing your code under Apache-2 as well? That way anything you/we make can easily be moved between the various crates in the bevy ecosystem.

Also: what's your plan for nalgebra/parry types in public API, is it going to stay or not?

Because AngVel implements Deref<f32>, we will get std::f32::to_radians, which converts from degrees to radians, but AngVel is already in radians...

Not sure how we'd fix this besides removing the derive for Deref from AngVel and the other components... It's a trade-off and we'd lose some nice ergonomics. Just putting this here in case anyone else has a good idea about how to go about it.

This refactors the high-level xpbd algorithm structure to take advantage of bevy_ecs schedule v3 (i.e. stageless).

The algorithm is split into two schedules, one high-level for running one high-level physics step (i.e. DELTA_TIME) step, and one lower-level for the inner substepping (integrate, solve etc.).

Another option. I wanted to see what it would take to have both f32 and f64 function at the same time.

This makes each implementation available under bevy_xpbd_3d::single::XpbdPlugin and bevy_xpbd_3d::double::XpbdPlugin. If only one of them is defined, adds re-exports at the crate level, i.e. bevy_xpbd_3d::XpbdPlugin.

Not sure what I think of it though, but just thought I'd share.

Adds insta tests to ensure that we get the same output every time we run a given simulation.

Adds a new integration test that uses a copy of the cubes example, and confirms the transforms are the same each time the test is run.

Okay, so after #4 the algorithm logic got a lot less awkward, and that opens up some possibilities. Currently DELTA_TIME is hard-coded to 60 Hz, but it should probably be configurable at some level.

The obvious thing would be to just make it a resource:

pub struct PhysicsTimeStep(pub f32)

However I'm wondering, would that hurt performance? Does the rust compiler precompute constants, that means we shouldn't do this?

If so, perhaps we should consider if we can somehow use const-generics to still make it configurable at build-time (at least at an internal level).

Second question is: would it make sense to also allow a variable timestep? i.e. consume the remainder of the accumulator with one not-whole physics step.

Would obviously not be deterministic, but could perhaps produce smoother visuals if you don't do smoothing in your renderer.

Depends on #31.

Description

Implements sleeping to improve performance and reduce small jitter.

Bodies with the Sleeping component are not simulated by the physics engine. Bodies are marked with the component when their linear and angular velocities are below the values of the SleepingThreshold resource for a duration indicated by the DeactivationTime resource.

The TimeSleeping component is used to track the time that the velocity has been below the threshold, and it is reset to 0 whenever the threshold is exceeded.

Bodies are woken up when they interact with active dynamic or kinematic bodies or joints, or when gravity changes, or when the body's position, rotation, velocity, or external forces are changed.

Sleeping can be disabled for all bodies with a negative sleeping threshold, and for specific entities with the SleepingDisabled component.

Examples

Below is the current behaviour in a couple examples. The red color indicates that a body is sleeping and isn't being simulated.

First, the cubes example. At the end I change the velocity of the boxes. Sleeping doesn't help keep the cube stack stable unless a really high sleeping threshold is specified, but it does help keep them still on the ground.

https://github.com/Jondolf/bevy_xpbd/assets/57632562/63d8948c-6ff0-4665-9b3f-9066c087e665

move_marbles example:

https://github.com/Jondolf/bevy_xpbd/assets/57632562/bf19fc03-1538-4fc4-acb7-611cf831891e

Considerations and future improvements

• As can be seen in the cubes example, sleeping doesn't fix jittery collisions (#2). However, it does help keep slowly drifting bodies still, so in many cases it might be enough until a proper fix for unstable collisions is found.
• The default SleepingThreshold should perhaps be scaled depending on the world scale, e.g. in 2D, objects might be hundreds of pixels wide, so a threshold of 0.1 would be tiny. Maybe we should introduce a PhysicsScale resource, similar to rapier?
• Sleeping can cause unrealistic behaviour in some cases, e.g. removing the floor under a sleeping body will leave the body floating. But AFAIK this is a thing in other engines as well, and it should probably just be mentioned in the docs somewhere.
• Currently, sleeping is done per body. Many physics engines seem to use an island architecture where entities are grouped into islands, and sleeping controls the entire islands. This might have some benefits that are worth considering later.

Todo

• [x] Wake up bodies when their position or rotation is changed (constraints waking up bodies was bugged, now things work)
• [x] Figure out better place for sleeping systems than the sync step
  • I added a separate step and plugin for sleeping since I couldn't come up with another logical place.
• [x] Allow disabling sleeping for specific entities using a component
• [x] Allow separate sleeping threshold for linear and angular velocity
• [x] Add some more documentation

Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: actions/checkout@v2, actions-rs/toolchain@v1, actions-rs/cargo@v1.

I updated to actions/checkout@v3 and replaced the actions-rs commands with manual commands because actions-rs is no longer maintained.

I have a game with a ship as rigid body with a collider and engines attached to it as children, each has colliders and mass as well. I've enabled debug renderer to see the colliders. Engines' colliders don't move with teh ship, but instead stay at (0, 0, 0). Also, they don't have any rotation or scale applied. I'm not sure if this is a bug with only debug renderer, or handling of hierarchy is not even intended, but this does bother me while I'm transitioning to this engine from rapier as an experiment.

This pull request adds a SpatialQueryPlugin that is responsible for ray casting, shape casting, point projection, and intersection tests. There is also a SpatialQueryFilter that can be used to select specific collision layers or to exclude entities.

The SpatialQueryPipeline resource has a Qbvt that is used as an acceleration structure. The implementation of the pipeline and the queries is mostly based on Rapier's QueryPipeline, but modified to fit Bevy better and to provide a more consistent API.

API

There are two types of APIs for spatial queries: the SpatialQuery system parameter and the component based RayCaster and ShapeCaster.

SpatialQuery

SpatialQuery is a new system parameter that provides similar querying methods as Rapier's global context. It is the most feature-rich option and great when you need a lot of control over when and how you want to ray cast for example.

It looks like this:

fn print_hits(spatial_query: SpatialQuery) {
    let hits = spatial_query.ray_hits(
        Vec3::ZERO,                    // Origin
        Vec3::X,                       // Direction
        100.0,                         // Maximum time of impact (travel distance)
        20,                            // Maximum number of hits
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
    );

    for hit in hits.iter() {
        println!("Hit entity {:?}", hit.entity);
    }
}

There are similar methods for shape casts, point projection and intersection tests.

RayCaster

RayCaster allows for a more component-based approach to ray casting that can often be more convenient than manually calling query methods. A system is run once per physics frame to fill the RayHits component with the intersections between the ray and the world's colliders.

Unlike the methods in SpatialQuery, RayCaster uses a local origin and direction, so it will move with the body it is attached to or its parent. For example, if you cast rays from a car for a driving AI, you don't need to compute the new origin and direction manually, as the RayCaster will follow the car.

Using RayCaster looks like this:

fn setup(mut commands: Commands) {
    // Spawn a ray at the center travelling right
    commands.spawn(RayCaster::new(Vec3::ZERO, Vec3::X));
    // ...spawn colliders and other things
}

fn print_hits(query: Query<(&RayCaster, &RayHits)>) {
    for (ray, hits) in &query {
        // For the faster iterator that isn't sorted, use `.iter()`
        for hit in hits.iter_sorted() {
            println!(
                "Hit entity {:?} at {} with normal {}",
                hit.entity,
                ray.origin + ray.direction * hit.time_of_impact,
                hit.normal,
            );
        }
    }
}

You can configure the ray caster's properties using various builder methods.

One caveat that isn't instantly clear is that the hits aren't in order by default because of the underlying Qbvh traversal algorithm. If the number of hits is larger than the ray caster's max_hits property, some hits will be missed, and this could be any hit including the closest one. If you want to guarantee that the closest hit is included, max_hits must either be 1 or a value large enough to hold all of the hits.

ShapeCaster

ShapeCaster is very similar to RayCaster, but it also has an associated shape and rotation, and it can only get the first hit.

Using ShapeCaster looks like this:

fn setup(mut commands: Commands) {
    // Spawn a shape caster with a ball shape travelling right starting from the origin
    commands.spawn(ShapeCaster::new(
        Collider::ball(0.5),
        Vec3::ZERO,
        Quat::default(),
        Vec3::X
    ));
}

fn print_hits(query: Query<(&ShapeCaster, &ShapeHit)>) {
    for (shape_caster, hit) in &query {
        if let Some(hit) = hit.0 {
            println!("Hit entity {:?}", hit.entity);
        }
    }
}

SpatialQueryFilter

The SpatialQueryFilter can be used to only include colliders with specific CollisionLayers or to exclude specific entities from spatial queries. There are no flags or predicate yet unlike in Rapier.

Using a SpatialQueryFilter looks like this: (although this example doesn't make sense usage-wise)

fn setup(mut commands: Commands) {
    let object = commands.spawn(Collider::ball(0.5)).id();

    // A query filter that only includes one layer and excludes the `object` entity
    let query_filter = SpatialQueryFilter::new()
        .with_layers(CollisionLayers::from_bits(0b1111, 0b0001))
        .without_entities([object]);

    // Spawn a ray caster with the query filter
    commands.spawn(RayCaster::default().with_query_filter(query_filter));
}

Todo

• [x] Add remaining intersection test methods to SpatialQuery
  • [x] point_intersections
  • [x] aabb_intersections_with_aabb
  • [x] shape_intersections
• [ ] Add high level documentation that goes through the different spatial query types and when to use each one
• [ ] Add 2D (and 3D) examples
• [ ] Add tests

The velocity update applying dynamic friction is probably wrong in the paper (Detailed Rigid Body Simulation with Extended Position Based Dynamics). We had a discussion about in the "10 minutes physics" discord channel (channel created by the papers author, Matthias Müller) Equation 30 in the paper doesn't make sense unit wise. The equation is supposed to calculate a velocity Δv = [m/s, meter per second] The left side in the min has unit force⋅time [ N⋅s = kg⋅m/s2 ⋅ s = kg ⋅ m / s], the right has velocity. So there is a mass discrepancy, either divide the left side in the min with mass, or instead calculate an impulse p (= force⋅time) So instead of calculating Δv with equation 30, we calculate the impulse p, therefore the right side in the min needs to be multiplied by mass. We have p = Δv / (w1+w2), using vt as Δv also makes sense, since this is the impulse needed to counteract all relative velocity of the contact. The new equation then becomes p = -vt / |vt| ⋅ min(h ⋅ μ ⋅ |fn|, |vt|/(w0+w1)), then apply the p as usual according to (33)

ref: https://discord.com/channels/691052431525675048/1084206740570124372/1089161165088772146

This check doesn't appear in the paper, but without it, I'm getting issues on object with sharp corners (in my own version of bevy_xpbd).

https://user-images.githubusercontent.com/2620557/227721679-12c3d16f-08ed-4ace-a88a-4c37f3cc09dc.mp4

I think the alternative would be to say that perfectly sharp corners are just not allowed.

You mentioned in #1 that you were struggling with "unstable collisions", and this was something you'd like to fix before releasing. Just though it might be useful to have an issue for it.

Maybe explaining it and having some extra eyes on it would help :)

(fwiw I was also having trouble with unstable things as I added friction in the tutorial series), and I never quite figured it out, perhaps this is the same thing?