# Migrating From v0.2 to v0.3

## Collision Hooks

PRs: [#610](https://github.com/avianphysics/avian/pull/610)

The `BroadPhasePlugin`, `NarrowPhasePlugin`, and many `NarrowPhase` methods now take generics for `CollisionHooks`. If you have no collision hooks, you can use `()`.

## Physics Picking

PRs: [#632](https://github.com/avianphysics/avian/pull/632)

The `RenderLayers` of cameras and collider entities no longer affect physics picking. Add the new `PhysicsPickingFilter` component to cameras to control which `CollisionLayers` and colliders are included in picking.

## Default Layers for `ColliderConstructorHierarchy`

PRs: [#649](https://github.com/avianphysics/avian/pull/649)

`ColliderConstructorHierarchy` now defaults to one membership (the first layer) and all filters for the `CollisionLayers` of generated colliders. This is consistent with how the `CollisionLayers` component already works normally.

Previously, it was still using the old default of *all* memberships and all filters.

## Improved Contact Types

PRs: [#616](https://github.com/avianphysics/avian/pull/616) [#685](https://github.com/avianphysics/avian/pull/685)

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

### `Contacts`

- `Contacts` has been renamed to `ContactPair`.
- 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`.

## Add `Context` to `AnyCollider`

PRs: [#665](https://github.com/avianphysics/avian/pull/665)

- `AnyCollider` implementors now need to specify a `Context` associated `SystemParam`. If this is unnecessary, `()` should be used.
- When trying to use methods from `AnyCollider` on an implementation with `()` context, `SimpleCollider` should be used instead.
- Methods on `AnyCollider` have been suffixed with `_with_context`.

## Bevy 0.16 Support

PRs: [#670](https://github.com/avianphysics/avian/pull/670)

Avian now uses Bevy 0.16.

The `AncestorMarkerPlugin` no longer requires a schedule or system set.

## Change `ColliderParent` to `ColliderOf` relationship

PRs: [#671](https://github.com/avianphysics/avian/pull/671)

The `ColliderParent` component has been renamed to `ColliderOf`, and it is now a `Relationship`. The `ColliderHierarchyPlugin` (included in `PhysicsPlugins`) must be enabled for colliders to be automatically attached to rigid bodies, but `ColliderOf` can also be inserted manually otherwise.

The transform management in `ColliderHierarchyPlugin` has been extracted into a new `ColliderTransformPlugin`. The `ColliderHierarchyPlugin` no longer takes a schedule.

## Reworked Contact Pair Management

PRs: [#683](https://github.com/avianphysics/avian/pull/683)

Avian's collision detection pipelines and contact pair management have been massively reworked for better performance and robustness.

### `PostProcessCollisions`

The `PostProcessCollisions` schedule and `NarrowPhaseSet::PostProcess` system set have been removed, as it is incompatible with new optimizations to narrow phase collision detection. Instead, use `CollisionHooks` for contact modification.

### Contact Reporting

The `ContactReportingPlugin` and `PhysicsStepSet::ReportContacts` system set have been removed. Contact reporting is now handled by the `NarrowPhasePlugin` directly.

The `Collision` event no longer exists. Instead, use `Collisions` directly, or get colliding entities using the `CollidingEntities` component.

The `CollisionStarted` and `CollisionEnded` events are now only sent if either entity in the collision has the `CollisionEventsEnabled` component. If you'd like to revert to the old behavior of having collision events for all entities, consider making `CollisionEventsEnabled` a required component for `Collider`:

```rust
app.register_required_components::<Collider, CollisionEventsEnabled>();
```

### `Collisions`

The `Collisions` resource is now a `SystemParam`.

```rust
// Old
fn iter_collisions(collisions: Res<Collisions>) {
    todo!()
}

// New
fn iter_collisions(collisions: Collisions) {
    todo!()
}
```

Internally, `Collisions` now stores a `ContactGraph` that stores both touching and non-touching contact pairs. The `Collisions` system parameter is just a wrapper that provides a simpler API and only returns touching contacts.

The `collisions_with_entity` method has also been renamed to `collisions_with`, and all methods that mutatate, add, or remove contact pairs have been removed from `Collisions`. However, the following mutating methods are available on `ContactGraph`:

- `get_mut`
- `iter_mut`
- `iter_touching_mut`
- `collisions_with_mut`
- `add_pair`/`add_pair_with_key`
- `insert_pair`/`insert_pair_with_key`
- `remove_pair`
- `remove_collider_with`

For most scenarios, contact modification and removal are intended to be handled with `CollisionHooks`.

### Contact Pairs

The `during_current_frame` and `during_previous_frame` properties of `ContactPair` have been removed in favor of a `flags` property storing information in a more compact bitflag format. The `is_sensor`, `is_touching`, `collision_started`, and `collision_ended` helper methods can be used instead.

### Contact Manifolds

Methods such as `AnyCollider::contact_manifolds_with_context` now take `&mut Vec<ContactManifold>` instead of returning a new vector every time. This allows manifolds to be persisted more effectively, and reduces unnecessary allocations.

### `BroadCollisionPairs`

The `BroadCollisionPairs` resource has been removed. Use the `ContactGraph` resource instead.

### `AabbIntersections`

The `AabbIntersections` component has been removed. Use `ContactGraph::entities_colliding_with` instead.

## Change `CollisionLayers` to a Required Component

PRs: [#693](https://github.com/avianphysics/avian/pull/693)

`CollisionLayers` is now a required component for colliders and is inserted automatically. Collision detection may not work properly without it.

## Reorganize Collision Detection Modules and Re-Exports

PRs: [#698](https://github.com/avianphysics/avian/pull/698)

Some collision detection modules and imports have been reorganized.

The following modules have been moved:

- `layers` from `collision` to `collision::collider`
- `contact_query` from `collision` to `collision::collider::parry`
- `feature_id` from `collision` to `collision::contact_types`

Previously, a lot of collision detection types were also re-exported directly from the `collision` module. Now, there is instead a `prelude` for the `collision` module.

## Contact Constraint Generation System Ordering

PRs: [#699](https://github.com/avianphysics/avian/pull/699)

`NarrowPhaseSet::GenerateConstraints` has been removed. Contact constraints are now generated as part of `NarrowPhaseSet::Update`.

## Rename Entity Properties

PRs: [#718](https://github.com/avianphysics/avian/pull/718) [#719](https://github.com/avianphysics/avian/pull/719)

- `ContactPair`: The `entity1` and `entity2` properties are now `collider1` and `collider2`, and `body_entity1` and `body_entity2` are now `body1` and `body2`.
- `ContactConstraint`: The `entity1` and `entity2` properties are now `body1` and `body2`, and `collider_entity1` and `collider_entity2` are now `collider1` and `collider2`.
- `ColliderQuery`: The `rigid_body` property has been renamed to `of` (for `ColliderOf`) and there is a new `body` helper to get the contained entity directly.
