Struct TrackedContact

pub struct TrackedContact<Data> {
    pub local_p1: Point<f32>,
    pub local_p2: Point<f32>,
    pub dist: f32,
    pub fid1: PackedFeatureId,
    pub fid2: PackedFeatureId,
    pub data: Data,
}

A single contact point between two shapes.

A TrackedContact represents a single point of contact between two shapes, with enough information to track the contact across multiple frames and identify which geometric features (vertices, edges, faces) are in contact.

Understanding Contact Points

Each contact point consists of:

• Two contact positions (one on each shape, in local coordinates)
• A distance value (negative = penetrating, positive = separated)
• Feature IDs that identify which part of each shape is in contact
• Optional user data for tracking contact-specific information

Local vs World Space

Contact points are stored in local space (the coordinate system of each shape). This is important because:

• Shapes can move and rotate, but local coordinates remain constant
• Contact tracking works by comparing feature IDs and local positions
• To get world-space positions, transform the local points by the shape’s position

Distance Convention

The dist field uses the following convention:

• dist < 0.0: Shapes are penetrating (overlapping). The absolute value is the penetration depth.
• dist == 0.0: Shapes are exactly touching.
• dist > 0.0: Shapes are separated. This happens when using contact prediction.

Example: Basic Contact Query

use parry3d::query::{ContactManifold, TrackedContact};
use parry3d::query::details::contact_manifold_ball_ball;
use parry3d::shape::Ball;
use parry3d::math::Isometry;

// Two balls, one slightly overlapping the other
let ball1 = Ball::new(1.0);
let ball2 = Ball::new(1.0);
let pos12 = Isometry::translation(1.5, 0.0, 0.0); // Overlapping by 0.5

let mut manifold = ContactManifold::<(), ()>::new();
contact_manifold_ball_ball(&pos12, &ball1, &ball2, 0.0, &mut manifold);

if let Some(contact) = manifold.points.first() {
    println!("Penetration depth: {}", -contact.dist);
    println!("Contact on ball1 (local): {:?}", contact.local_p1);
    println!("Contact on ball2 (local): {:?}", contact.local_p2);
}

Example: Converting to World Space

use parry3d::query::{ContactManifold, TrackedContact};
use parry3d::query::details::contact_manifold_ball_ball;
use parry3d::shape::Ball;
use parry3d::math::Isometry;

let ball1 = Ball::new(1.0);
let ball2 = Ball::new(1.0);

// Position shapes in world space
let pos1 = Isometry::translation(0.0, 0.0, 0.0);
let pos2 = Isometry::translation(1.5, 0.0, 0.0);
let pos12 = pos1.inverse() * pos2; // Relative position

let mut manifold = ContactManifold::<(), ()>::new();
contact_manifold_ball_ball(&pos12, &ball1, &ball2, 0.0, &mut manifold);

if let Some(contact) = manifold.points.first() {
    // Convert local positions to world space
    let world_p1 = pos1 * contact.local_p1;
    let world_p2 = pos2 * contact.local_p2;

    println!("Contact in world space:");
    println!("  On ball1: {:?}", world_p1);
    println!("  On ball2: {:?}", world_p2);
}

Feature IDs

The fid1 and fid2 fields identify which geometric features are in contact:

• For a ball: Always the face (surface)
• For a box: Could be a vertex, edge, or face
• For a triangle: Could be a vertex, edge, or the face

These IDs are used to track contacts across frames. If the same feature IDs appear in consecutive frames, it’s likely the same physical contact point.

Fields

local_p1: Point<f32>

The contact point in the local-space of the first shape.

This is the point on the first shape’s surface (or interior if penetrating) that is closest to or in contact with the second shape.

local_p2: Point<f32>

The contact point in the local-space of the second shape.

This is the point on the second shape’s surface (or interior if penetrating) that is closest to or in contact with the first shape.

dist: f32

The signed distance between the two contact points.

• Negative values indicate penetration (shapes are overlapping)
• Positive values indicate separation (used with contact prediction)
• Zero means the shapes are exactly touching

The magnitude represents the distance along the contact normal.

fid1: PackedFeatureId

The feature ID of the first shape involved in the contact.

This identifies which geometric feature (vertex, edge, or face) of the first shape is involved in this contact. Used for contact tracking across frames.

fid2: PackedFeatureId

The feature ID of the second shape involved in the contact.

This identifies which geometric feature (vertex, edge, or face) of the second shape is involved in this contact. Used for contact tracking across frames.

data: Data

User-data associated to this contact.

This can be used to store any additional information you need to track per-contact, such as:

• Accumulated impulses for warm-starting in physics solvers
• Contact age or lifetime
• Material properties or friction state
• Custom identifiers or flags

Implementations

impl<Data: Default + Copy> TrackedContact<Data>

pub fn new( local_p1: Point<f32>, local_p2: Point<f32>, fid1: PackedFeatureId, fid2: PackedFeatureId, dist: f32, ) -> Self

Creates a new tracked contact.

Arguments

• local_p1 - Contact point on the first shape (in its local space)
• local_p2 - Contact point on the second shape (in its local space)
• fid1 - Feature ID of the first shape (which part is in contact)
• fid2 - Feature ID of the second shape (which part is in contact)
• dist - Signed distance between the contact points (negative = penetrating)

The contact data is initialized to its default value.

Example

use parry3d::query::TrackedContact;
use parry3d::shape::PackedFeatureId;
use parry3d::math::Point;

let contact = TrackedContact::<()>::new(
    Point::new(1.0, 0.0, 0.0),  // Point on shape 1
    Point::new(-1.0, 0.0, 0.0), // Point on shape 2
    PackedFeatureId::face(0),    // Face 0 of shape 1
    PackedFeatureId::face(0),    // Face 0 of shape 2
    -0.1,                         // Penetration depth of 0.1
);

assert_eq!(contact.dist, -0.1);

pub fn flipped( local_p1: Point<f32>, local_p2: Point<f32>, fid1: PackedFeatureId, fid2: PackedFeatureId, dist: f32, flipped: bool, ) -> Self

Creates a new tracked contact where its input may need to be flipped.

pub fn copy_geometry_from(&mut self, contact: Self)

Copy to self the geometric information from contact.

Trait Implementations

impl<Data: Clone> Clone for TrackedContact<Data>

fn clone(&self) -> TrackedContact<Data>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Data: Debug> Debug for TrackedContact<Data>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Data: Copy> Copy for TrackedContact<Data>