RealityCollisions

Named Collision Groups

RealityCollisions is an open-source Swift package that makes RealityKit collision filters easier to define and assign.

Instead of using the default filters that collide with everything, you define your groups in an enum and call setNewCollisionFilter(belongsToGroup:canCollideWith:) on an entity. The method writes a CollisionFilter onto the entity, and it creates a collision component when one is missing.

Here is the same collision relationship both ways: an alien that can collide with teammates.

With RealityCollisions

enum CollisionGroups: Int, CaseIterable, HasCollisionGroups {
    case teammates
    case aliens
}

alien.setNewCollisionFilter(
    belongsToGroup: CollisionGroups.aliens,
    canCollideWith: [.teammates]
)

enum CollisionGroups: Int, CaseIterable, HasCollisionGroups {
    case teammates
    case aliens
}

alien.setNewCollisionFilter(
    belongsToGroup: CollisionGroups.aliens,
    canCollideWith: [.teammates]
)

enum CollisionGroups: Int, CaseIterable, HasCollisionGroups {
    case teammates
    case aliens
}

alien.setNewCollisionFilter(
    belongsToGroup: CollisionGroups.aliens,
    canCollideWith: [.teammates]
)

With RealityKit’s native collision groups

let teammates = CollisionGroup(rawValue: 1 << 0)
let aliens = CollisionGroup(rawValue: 1 << 1)

alien.components[CollisionComponent.self] = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: [1, 1, 1])],
    filter: CollisionFilter(group: aliens, mask: teammates)
)

let teammates = CollisionGroup(rawValue: 1 << 0)
let aliens = CollisionGroup(rawValue: 1 << 1)

alien.components[CollisionComponent.self] = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: [1, 1, 1])],
    filter: CollisionFilter(group: aliens, mask: teammates)
)

let teammates = CollisionGroup(rawValue: 1 << 0)
let aliens = CollisionGroup(rawValue: 1 << 1)

alien.components[CollisionComponent.self] = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: [1, 1, 1])],
    filter: CollisionFilter(group: aliens, mask: teammates)
)

Why Use It Instead of Native Setup?

Apple’s native collision workflow gives you the low-level building blocks: collision shapes, a CollisionComponent, and group-and-mask bit fields. That flexibility is useful, but a project with several categories must consistently assign bit positions, construct masks, attach components, generate shapes, and decode event participants throughout the codebase.

RealityCollisions does not replace RealityKit’s physics system. It adds a typed convenience layer on top of it. Your enum becomes the single source of truth for collision categories, while the package converts those cases into RealityKit’s bit masks. This replaces scattered shift operations and raw masks with names such as .teammates, .aliens, and .sceneMesh, making collision intent easier to read and update.

It also removes repetitive setup. setNewCollisionFilter updates an existing component or creates one and recursively generates shapes when needed. Dedicated helpers add or remove collision relationships, opt an entity into LiDAR scene-mesh collisions, create filters for custom components, and translate collision-event entities back into your enum cases.

Built for Selective Collisions

• Custom groups through an enum that conforms to HasCollisionGroups, supporting up to 32 groups

• Selective masks so entities collide only with the groups you name, including their own group when you include it

• LiDAR scene mesh support through addCollisionWithLiDARMesh() or a group named sceneMesh

• Collision events mapped back to your enum with fetchCollisionGroups(from:of:)

Installation and Compatibility

Install RealityCollisions through Swift Package Manager using the GitHub repository. It supports iOS, macOS, tvOS, and visionOS, requires Swift 5.9, and is available under the MIT License.