<!--
{
  "documentType" : "article",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/physics-collision-detection",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Collision detection"
}
-->

# Collision detection

Determine when entities collide with each other or the environment.

## Overview

RealityKit can automatically detect when two objects participating in the physics system
collide with each other if both entities have a [`CollisionComponent`](/documentation/RealityKit/CollisionComponent) with at least one *collision shape*.
Because doing collision detection with complex 3D models can be computationally expensive, collision shapes are simpler,
invisible shapes RealityKit uses to detect collision, as well as doing hit testing, ray casts, and convex shape casts.

Entities can participate in the scene simulation in two different modes: as a *rigid body* or as a *trigger*.
A rigid body fully participates in the collision simulation.
It affects the velocity and direction of other rigid body entities with which it collides.
An entity with a rigid body [`mode`](/documentation/RealityKit/PhysicsBodyComponent/mode) of [`PhysicsBodyMode.dynamic`](/documentation/RealityKit/PhysicsBodyMode/dynamic),
other rigid body entities can affect its velocity and direction.
A trigger entity doesn’t have any impact on the other rigid bodies in the scene,
but can trigger code or Reality Composer Pro behaviors when another rigid body entity overlaps it.

Turn an entity into a trigger by adding a [`CollisionComponent`](/documentation/RealityKit/CollisionComponent) to it and setting its
[`mode`](/documentation/RealityKit/CollisionComponent/mode-swift.property) to [`CollisionComponent.Mode.trigger`](/documentation/RealityKit/CollisionComponent/Mode-swift.enum/trigger).

Turn an entity into a *rigid body* by adding a [`PhysicsBodyComponent`](/documentation/RealityKit/PhysicsBodyComponent) to the entity in addition to a [`CollisionComponent`](/documentation/RealityKit/CollisionComponent).
The [`PhysicsBodyComponent`](/documentation/RealityKit/PhysicsBodyComponent) defines the physical properties of the entity, such as its mass and collision shape.

> Note: RealityKit ignores an entity’s collision component mode if the entity also has a ``doc://com.apple.RealityKit/documentation/RealityKit/PhysicsBodyComponent``.
> An entity can be a rigid body, or a trigger, but not both at the same time.

## Topics

### Collision shapes and groups

[Simulating physics with collisions in your visionOS app](/documentation/RealityKit/simulating-physics-with-collisions-in-your-visionos-app)

Create entities that behave and react like physical objects in a RealityKit view.

[Configuring Collision in RealityKit](/documentation/RealityKit/configuring-collision-in-realitykit)

Use collision groups and collision filters to control which objects collide.

  <doc://com.apple.documentation/documentation/visionOS/creating-an-interactable-3d-model-in-visionos>

[`CollisionComponent`](/documentation/RealityKit/CollisionComponent)

A component that gives an entity the ability to collide with other entities
that also have collision components.

[`Mode`](/documentation/RealityKit/CollisionComponent/Mode-swift.enum)

A mode that dictates how much collision data is collected for a given
entity.

[`ShapeResource`](/documentation/RealityKit/ShapeResource)

A representation of a shape.

[`ShapeResourceError`](/documentation/RealityKit/ShapeResourceError)

[`CollisionGroup`](/documentation/RealityKit/CollisionGroup)

A bitmask used to define the collision group to which an entity belongs.

[`CollisionFilter`](/documentation/RealityKit/CollisionFilter)

A set of masks that determine whether entities can collide during
simulations.

[`TriggerVolume`](/documentation/RealityKit/TriggerVolume)

An invisible 3D shape that detects when objects enter or exit a given region
of space.

### Collision-related notifications

[`CollisionEvents`](/documentation/RealityKit/CollisionEvents)

[`Contact`](/documentation/RealityKit/Contact)

Events associated with collisions.

### Ray casting

[`CollisionCastHit`](/documentation/RealityKit/CollisionCastHit)

A hit result of a collision cast.

[`TriangleHit`](/documentation/RealityKit/CollisionCastHit/TriangleHit-swift.struct)

Information returned when ray intersects a triangle mesh.

[`CollisionCastQueryType`](/documentation/RealityKit/CollisionCastQueryType)

The kinds of ray and convex shape cast queries that you can make.

[`PixelCastHit`](/documentation/RealityKit/PixelCastHit)

### Entity compliance

[`HasCollision`](/documentation/RealityKit/HasCollision)

An interface used for ray casting and collision detection.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)