CharacterControllerComponent

struct · iOS 15.0+ · SDK 27.1

struct CharacterControllerComponent

A component that manages character movement. To use a character controller, add a `CharacterControllerComponent` to your entity to make it a character entity. Use ``Entity/moveCharacter(by:deltaTime:relativeTo:collisionHandler:)`` to move your character and respond to collisions, or ``Entity/teleportCharacter(to:relativeTo:)`` to place your character instantaneously in 3D space. > Note: ``PhysicsBodyComponent`` and ``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`` 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 ``CollisionComponent/mode-swift.property`` of ``CollisionComponent/Mode-swift.enum/trigger``, subscribe to the ``CollisionEvents/Began`` event for your ``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`` on ``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 ``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`` to accumulate forces (such as gravity) and to check whether the character is on the ground. RealityKit calculates ``CharacterControllerStateComponent/isOnGround`` and ``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<Float> = [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<Float> = .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: @Video( source:character_controller_component_jump.mp4, alt: "A video of a white capsule jumping on a flat gray plane in response to player input.", poster:character_controller_component_jump_poster.png )

Members (21)

get slopeLimit(): number

var slopeLimit: Float

set slopeLimit(value: number)

var slopeLimit: Float

static get defaultHeight(): number

static let defaultHeight: Float

static get defaultRadius(): number

static let defaultRadius: Float

get collisionFilter(): CollisionFilter

var collisionFilter: CollisionFilter

set collisionFilter(value: CollisionFilter)

var collisionFilter: CollisionFilter

static get defaultUpVector(): SDKHandle

static let defaultUpVector: SIMD3<Float>

static get defaultSkinWidth(): number

static let defaultSkinWidth: Float

static get defaultStepLimit(): number

static let defaultStepLimit: Float

static get defaultSlopeLimit(): number

static let defaultSlopeLimit: Float

get height(): number

var height: Float

set height(value: number)

var height: Float

get radius(): number

var radius: Float

set radius(value: number)

var radius: Float

get upVector(): SDKHandle

var upVector: SIMD3<Float>

set upVector(value: SDKHandle)

var upVector: SIMD3<Float>

get skinWidth(): number

var skinWidth: Float

set skinWidth(value: number)

var skinWidth: Float

get stepLimit(): number

var stepLimit: Float

set stepLimit(value: number)

var stepLimit: Float

static init(): CharacterControllerComponent

init()

All RealityFoundation types →