<!--
{
  "availability" : [
    "visionOS: 26.0.0 -",
    "Xcode: 26.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "visionOS",
  "identifier" : "/documentation/visionOS/manipulating-entities-with-solid-collisions",
  "metadataVersion" : "0.1.0",
  "role" : "sampleCode",
  "title" : "Manipulating entities with solid collisions"
}
-->

# Manipulating entities with solid collisions

Extend the capabilities of your app by using entities, components, and systems to maintain solid collisions when manipulating entities.

## Overview

Set up an interaction using <doc://com.apple.documentation/documentation/RealityKit/ManipulationComponent>,  <doc://com.apple.documentation/documentation/RealityKit/ForceEffectComponent>, and custom components that maintain solid collisions while manipulating entities.
This sample shows how to create a proxy <doc://com.apple.documentation/documentation/RealityKit/Entity> that follows the manipulated entity using forces.
Because it is moved with forces, the proxy bumps into solid objects as person drags the entity with their hand.

![A screen recording showing a person manipulating a toy car and a toy robot on visionOS while maintaining solid collisions between objects.](videos/com.apple.visionOS/device.mp4)

## Configure the entity with a custom component

After configuring an entity with <doc://com.apple.documentation/documentation/RealityKit/ManipulationComponent>, it passes through other colliders while using the gesture.
The entity ignores other colliders because its motion is guided by the person’s hand.
To create an interaction where an entity respects collisions and forces during a gesture, this sample moves the visual components from the “real” entity to a “proxy” entity for the duration of the gesture.
With the real entity invisible and the proxy entity visible, <doc://com.apple.documentation/documentation/RealityKit/ForceEffectComponent> applies forces to the proxy entity that move it toward the real entity.
This creates an interaction where you can manipulate the entity, but it no longer passes through solid colliders.

An extension for the custom <doc://com.apple.documentation/documentation/RealityKit/Component>, `ManipulateWithSolidCollisionsComponent`, configures the entity for the interaction.
This method first creates and places a proxy entity as a descendant of the real entity.
Then it copies the real entity’s <doc://com.apple.documentation/documentation/RealityKit/ModelComponent> and <doc://com.apple.documentation/documentation/RealityKit/GroundingShadowComponent> onto the proxy.

For more information about the entity component system (ECS) in RealityKit, see <doc://com.apple.documentation/documentation/RealityKit/implementing-systems-for-entities-in-a-scene>.

## Modify entities at specific moments during a gesture

To run code at specific moments during a manipulation gesture for a specific entity use <doc://com.apple.documentation/documentation/RealityKit/ManipulationEvents/WillBegin> and <doc://com.apple.documentation/documentation/RealityKit/ManipulationEvents/WillRelease>.
To subscribe to these events, the sample first subscribes to <doc://com.apple.documentation/documentation/RealityKit/ComponentEvents/DidAdd> inside the initializer for a custom system.

```swift
// Subscribe to an event for when the component is added.
scene.subscribe(to: ComponentEvents.DidAdd.self,
                componentType: ManipulateWithSolidCollisionsComponent.self,
                onDidAddManipulateWithSolidCollisionsComponent).store(in: &subscriptions)
```

When the custom component is added to an entity, the app subscribes to the manipulation events on the entity.

```swift
// Subscribe to manipulation events when ManipulateWithSolidCollisionsComponent is added to an entity.
event.entity.scene?.subscribe(to: ManipulationEvents.WillBegin.self,
                              on: event.entity,
                              onManipulationWillBegin).store(in: &subscriptions)
event.entity.scene?.subscribe(to: ManipulationEvents.WillRelease.self,
                              on: event.entity,
                              onManipulationWillRelease).store(in: &subscriptions)
```

When the manipulation gesture begins, the app hides the real entity and reveals the proxy.
To do this, the app copies <doc://com.apple.documentation/documentation/RealityKit/PhysicsBodyComponent>, <doc://com.apple.documentation/documentation/RealityKit/CollisionComponent>, and <doc://com.apple.documentation/documentation/RealityKit/OpacityComponent> from the real entity to the proxy:

```swift
// Copy physics components from the real entity to the proxy.
if let physicsBody = event.entity.components[PhysicsBodyComponent.self] {
    proxy.components.set(physicsBody)
    event.entity.components.remove(PhysicsBodyComponent.self)
}
if var collision = event.entity.components[CollisionComponent.self] {
    collision.filter.group = ManipulateWithSolidCollisionsComponent.proxyGroup
    proxy.components.set(collision)
    event.entity.components.remove(CollisionComponent.self)
}
if let opacity = event.entity.components[OpacityComponent.self] {
    proxy.components.set(opacity)
}
event.entity.components[OpacityComponent.self]?.opacity = 0
```

> Note: Use a <doc://com.apple.documentation/documentation/RealityKit/CollisionGroup> to control how a collider interacts with other colliders and forces in your scene.

The inverse operations occur when a person releases the entity and the app transfers the components back to the real entity.

## Use forces to move the entity with realistic physics

During the manipulation gesture, a custom <doc://com.apple.documentation/documentation/RealityKit/System> runs code each frame to apply a <doc://com.apple.documentation/documentation/RealityKit/ForceEffectComponent> to the real entity.
<doc://com.apple.documentation/documentation/RealityKit/ConstantRadialForceEffect> attracts physics bodies to its center.
<doc://com.apple.documentation/documentation/RealityKit/DragForceEffect> applies a force opposite to an entity’s direction of motion.
Together these forces move the proxy entity toward the real entity during the manipulation gesture.

Additionally, configure each <doc://com.apple.documentation/documentation/RealityKit/ForceEffect> with a mask so that forces are only applied to entities that belong to a particular group.

```swift
// `ConstantRadialForce` will attract entities toward its center.
// This force will cause the proxy entity to move toward the real entity.
let constantForceEffect = ConstantRadialForceEffect(
    strength: strength * strengthMultiplier,
)

// Apply a drag force to avoid orbiting.
// Without this force, the proxy entity will be difficult to control.
let dragForceEffect = DragForceEffect(strength: strength)

// Set the `ForceEffectComponent` on the real entity.
entity.components.set(ForceEffectComponent(effects: [
    // Use a collision group as a mask to only affect colliders in the group.
    ForceEffect(effect: constantForceEffect, mask: ManipulateWithSolidCollisionsComponent.proxyGroup),
    ForceEffect(effect: dragForceEffect, mask: ManipulateWithSolidCollisionsComponent.proxyGroup)
]))
```

---

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)