Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved contact types #616

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Improved contact types #616

wants to merge 9 commits into from

Conversation

Jondolf
Copy link
Owner

@Jondolf Jondolf commented Jan 5, 2025

Objective

A lot of Avian's current contact types store some redundant data, aren't properly optimized, and aren't explicit enough about what they represent.

This PR is a clean-up pass to make the types a bit smaller and clearer.

Solution

Contacts

  • Replace total_normal_impulse property with total_normal_impulse, total_normal_impulse_magnitude, and max_normal_impulse helpers
  • Deprecate total_normal_force helper
    • You can just divide by the substep timestep
  • Remove total_tangent_impulse property and total_friction_force helper
    • These could previously technically be wrong/misleading, since each contact point can have a different tangent direction, especially in 3D, and they can also change between substeps. The tangent impulse magnitudes of each individual point can still be accessed.

ContactManifold

  • Rename ContactManifold::contacts to ContactManifold::points
  • Use an ArrayVec with a capacity of 2 instead of a Vec to store 2D ContactManifold points directly on the stack
  • Replace the local normal1 and normal2 with a single world-space normal
    • Internals only need the world-space normal, and it makes e.g. contact modification more straightforward
  • Add total_normal_impulse and max_normal_impulse helpers

ContactData

  • Rename ContactData to ContactPoint (represents a point in a contact manifold)
    • Another option would be ManifoldPoint like in Box2D; not sure which one is better
  • Rename point1 and point2 to local_point1 and local_point2 for explicitness
  • Remove normal1 and normal2 from ContactPoint, since the normal is already stored in the ContactManifold

Other

  • Many documentation improvements
  • Contact force debug rendering uses per-point forces instead of the total force for the contact pair

Migration Guide

There have been several changes to Avian's contact types to make them more optimized and clearer.

Contacts

  • The total_normal_impulse property has been replaced with a total_normal_impulse helper method.
  • The total_normal_force helper has been deprecated. Instead, just divide the impulse by the substep timestep.
  • The total_tangent_impulse property and total_friction_force helper have been removed for being inaccurate/misleading. The tangent impulse magnitudes of each individual point can still be accessed.

ContactManifold

  • ContactManifold::contacts has been renamed to ContactManifold::points.
  • The local normal1 and normal2 have been replaced with a single world-space normal, pointing from the first shape to the second.

ContactData

  • ContactData has been renamed to ContactPoint, since it specifically represents a point in a contact manifold, not general contact data.
  • point1 and point2 have been renamed to local_point1 and local_point2 for explicitness
  • normal1 and normal2 have been removed, since the normal is already stored in the ContactManifold.

@Jondolf Jondolf added C-Enhancement New feature or request A-Collision Relates to the broad phase, narrow phase, colliders, or other collision functionality C-Usability A quality-of-life improvement that makes Avian easier to use labels Jan 5, 2025
@Jondolf Jondolf added this to the 0.3 milestone Jan 5, 2025
Comment on lines 260 to 262
pub during_current_frame: bool,
/// True if the bodies were in contact during the previous frame.
pub during_previous_frame: bool,
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These and is_sensor should use a ContactPairFlags bitflag type or similar, but I'll do that in another PR where I rework contact pair management.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Collision Relates to the broad phase, narrow phase, colliders, or other collision functionality C-Enhancement New feature or request C-Usability A quality-of-life improvement that makes Avian easier to use
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant