# CharacterControllerComponent A component that manages character movement. ``` struct CharacterControllerComponent ``` ## Overview To use a character controller, add a `CharacterControllerComponent` to your entity to make it a character entity. Use [`moveCharacter(by:deltaTime:relativeTo:collisionHandler:)`](/documentation/RealityKit/Entity/moveCharacter(by:deltaTime:relativeTo:collisionHandler:)) to move your character and respond to collisions, or [`teleportCharacter(to:relativeTo:)`](/documentation/RealityKit/Entity/teleportCharacter(to:relativeTo:)) to place your character instantaneously in 3D space. > Note: ``doc://com.apple.RealityKit/documentation/RealityKit/PhysicsBodyComponent`` and ``doc://com.apple.RealityKit/documentation/RealityKit/CollisionComponent`` are incompatible with `CharacterControllerComponent`, and RealityKit deactivates them if you add them to the same entity. ## Handle collision Character entities are capsular, and you can specify their height and radius in the component’s initializer. A character’s capsule shape aligns with its [`upVector`](/documentation/RealityKit/CharacterControllerComponent/upVector) so that the top and bottom of the capsule pass through that direction vector. Although characters don’t have a `CollisionComponent`, they can still interact with colliders. The collision handler in `moveCharacter(by:deltaTime:relativeTo:collisionHandler:)` allows you to respond to collisions with solid colliders in your scene. ```swift entity.moveCharacter(by: velocity * deltaTime, deltaTime: deltaTime, relativeTo: nil) { event in // Your character collided with `event.hitEntity`. } ``` To handle collisions with colliders that have a [`mode`](/documentation/RealityKit/CollisionComponent/mode-swift.property) of [`CollisionComponent.Mode.trigger`](/documentation/RealityKit/CollisionComponent/Mode-swift.enum/trigger), subscribe to the [`CollisionEvents.Began`](/documentation/RealityKit/CollisionEvents/Began) event for your [`RealityView`](/documentation/RealityKit/RealityView). This event doesn’t occur for solid collisions with your character, but RealityKit invokes it when your character enters a trigger. This is useful for collecting coins, claiming checkpoints, activating enemy behavior when your character enters an area, and many other interactions within games. ## Update your character A common use case for `CharacterControllerComponent` is to control a character in a video game. Video games have update loops where characters and game logic update once each frame, allowing them to respond to player input in real time. `CharacterControllerComponent` works well in such a setup. To move your character in response to player input, subscribe to [`PhysicsSimulationEvents.WillSimulate`](/documentation/RealityKit/PhysicsSimulationEvents/WillSimulate) on [`RealityViewContent`](/documentation/RealityKit/RealityViewContent) for your scene. The event object contains information like the time delta since the last update, and you can treat this callback as the update loop for your game. > Note: You can also use ``doc://com.apple.RealityKit/documentation/RealityKit/SceneEvents/Update`` to run code for each frame, but avoid using it to control physics-based motion in your scene. Read the values from [`CharacterControllerStateComponent`](/documentation/RealityKit/CharacterControllerStateComponent) to accumulate forces (such as gravity) and to check whether the character is on the ground. RealityKit calculates [`isOnGround`](/documentation/RealityKit/CharacterControllerStateComponent/isOnGround) and [`velocity`](/documentation/RealityKit/CharacterControllerStateComponent/velocity) only after you call `moveCharacter(by:deltaTime:relativeTo:collisionHandler:)`, so it’s a good idea to call this function at each update. ```swift let gravity: SIMD3 = [0, -50, 0] let jumpSpeed: Float = 10 content.subscribe(to: PhysicsSimulationEvents.WillSimulate.self, on: playerEntity) { event in let deltaTime: Float = event.deltaTime var velocity: SIMD3 = .zero var isOnGround: Bool = false // RealityKit automatically adds `CharacterControllerStateComponent` after moving the character for the first time. if let ccState = playerEntity.components[CharacterControllerStateComponent.self] { velocity = ccState.velocity isOnGround = ccState.isOnGround } if !isOnGround { // Gravity is a force, so you need to accumulate it for each frame. velocity += gravity * deltaTime } else if myPlayerInput.jump { // Set the character's velocity directly to launch it in the air when the player jumps. velocity.y = jumpSpeed } playerEntity.moveCharacter(by: velocity * deltaTime, deltaTime: deltaTime, relativeTo: nil) { event in print("playerEntity collided with \(event.hitEntity.name)") } } ``` The following video shows a character entity jumping in response to player input:  ## Topics ### Creating a character controller component [`init()`](/documentation/RealityKit/CharacterControllerComponent/init()) Creates a character controller component using default values. [`init(radius:height:skinWidth:slopeLimit:stepLimit:upVector:collisionFilter:)`](/documentation/RealityKit/CharacterControllerComponent/init(radius:height:skinWidth:slopeLimit:stepLimit:upVector:collisionFilter:)) Creates a character controller component using specified values. ### Configuring a character [`height`](/documentation/RealityKit/CharacterControllerComponent/height) The capsule height. [`radius`](/documentation/RealityKit/CharacterControllerComponent/radius) The capsule radius. [`skinWidth`](/documentation/RealityKit/CharacterControllerComponent/skinWidth) An added tolerance around the character capsule. [`slopeLimit`](/documentation/RealityKit/CharacterControllerComponent/slopeLimit) The slope limit expressed as a limit angle in radians. [`stepLimit`](/documentation/RealityKit/CharacterControllerComponent/stepLimit) The maximum obstacle height that the controller can move over. [`upVector`](/documentation/RealityKit/CharacterControllerComponent/upVector) The y-axis direction relative to the physics origin. ### Managing character collisions [`collisionFilter`](/documentation/RealityKit/CharacterControllerComponent/collisionFilter) The character’s collision filter. ### Reading default values [`defaultHeight`](/documentation/RealityKit/CharacterControllerComponent/defaultHeight) The capsule height value RealityKit applies when you use the default initializer. [`defaultRadius`](/documentation/RealityKit/CharacterControllerComponent/defaultRadius) The capsule default radius RealityKit applies when you use the default initializer. [`defaultSkinWidth`](/documentation/RealityKit/CharacterControllerComponent/defaultSkinWidth) The skin width value RealityKit applies when you use the default initializer. [`defaultSlopeLimit`](/documentation/RealityKit/CharacterControllerComponent/defaultSlopeLimit) The slope limit value RealityKit applies when you use the default initializer. [`defaultStepLimit`](/documentation/RealityKit/CharacterControllerComponent/defaultStepLimit) The step limit value RealityKit applies when you use the default initializer. [`defaultUpVector`](/documentation/RealityKit/CharacterControllerComponent/defaultUpVector) The default up vector RealityKit applies when you use the default initializer. ### Animating a character [`JointTransforms`](/documentation/RealityKit/JointTransforms) A set of animatable transform values for joints that collectively represent a single skeletal pose. ### Handling collisions [`Collision`](/documentation/RealityKit/CharacterControllerComponent/Collision) A container that holds collision state for the character controller. [`CollisionFlags`](/documentation/RealityKit/CharacterControllerComponent/CollisionFlags) An option set that specifies which parts of the character capsule have collided with other objects. ## Relationships ### Conforms To [`Component`](/documentation/RealityKit/Component) --- Copyright © 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)