dimforge / rapier.rs Goto Github PK
View Code? Open in Web Editor NEWOfficial website for the Rapier physics engine.
Home Page: https://rapier.rs
Official website for the Rapier physics engine.
Home Page: https://rapier.rs
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?
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.
Add templates. This issue's structure is an example of what an issue template could be (inspired by one of Bevy's issue templates).
Keep it as is, without any default structure or guidance.
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.
In the first example shown here, there are two missing parentheses that finish the insert()
part. Furthermore, upon adding the parenthesis and pasting the code into my own project I get an error, as you can see in the image below.
I must admit I only skimmed through the documentation, and therefore my shallow understanding of the particulars of this crate may have caused some kind of misunderstanding, leading to this.
I apologize if this issue was a product of my own stupidity, and insight would be greatly appreciated
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).
Document timesteps and physics scheduling for Bevy. This could have its own page or be a part of something like #91.
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
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
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.
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.
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.
The page https://rapier.rs/docs/user_guides/rust/simulation_structures/ mentions physics_pipeline.update(...);
- is that meant to be physics_pipeline.step(...);
instead?
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.
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()
});
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.
Document transform interpolation, how it works, and the potential tradeoffs it has. This could be in the same section as #95.
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>`
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)
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.
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.
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
The docs contain broken links - examples:
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.
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.
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).
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.
Page:
https://rapier.rs/docs/user_guides/javascript/physics_event_handling
Should be .drainIntersectionEvents
vs .drainIntersection
.
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(),
);
On the JS docs on colliders (https://rapier.rs/docs/user_guides/javascript/colliders), this link doesn't lead anywhere:
It points to this anchor which doesn't seem to exist:
https://rapier.rs/docs/user_guides/javascript/colliders#compound-shapes
I found some notes in https://rapier.rs/docs/user_guides/rust/colliders#compound-shapes,
but seems the compound
/ convex_decomposition
methods don't exist in the JavaScript API?
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.
Document additional solver iterations for rigid bodies.
The Getting Started page includes a Basic Simulation example. However, the line:
let mut broad_phase = BroadPhase::new();
gives a compilation error. I changed it to:
let mut broad_phase = BroadPhaseMultiSap::new();
and it seemed to work. However, I've only been learning Rust and Rapier for about 20mins - so just a guess.
I broke yarn build
with https://github.com/dimforge/rapier.rs/pull/104/files#r1629733861. Adding yarn build
to the CI would be great.
See Vrixyz#5 for a (failed) attempt.
I'm on bevy_rapier_2d 13.1, and it wouldn't let me compile the program without making that method plural. The documentation on the website has it as "contact_pair.has_any_active_contact()". Also, the documentation in the rust docs doesn't mention that function at all, but does mention something called ContactPair::has_any_active_collider, which I am not sure exists?
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.