An element of a RealityKit scene to which you attach components that provide
appearance and behavior characteristics for the entity.
You create and configure entities to embody objects that you want to place
in the real world in an AR app. You do this by adding ``Entity`` instances
to the ``Scene`` instance associated with an ``ARView``.
RealityKit defines a few concrete subclasses of ``Entity`` that provide
commonly used functionality. For example, you typically start by creating an
instance of ``AnchorEntity`` to anchor your content, and add the anchor to a
scene’s ``Scene/anchors`` collection. You might then instantiate a
``ModelEntity`` to represent a physical object in the scene, and add that as
a child entity to the anchor. You can also create custom entities, and add
them either to an anchor, or as children of another entity.
You can load predefined entities or a hierarchy of entities from your app’s
bundle, or from a file on disk, using the methods in <doc:stored-entities>.
Alternatively, you can create entities programmatically.
Entities contain components (instances conforming to the ``Component``
protocol) that provide appearance and behaviors for the entity. For example,
the ``Transform`` component contains the scale, rotation, and translation
information needed to position an entity in space. You store components in
the entity’s ``Entity/components`` collection, which can hold exactly one of
any component type. It makes sense to have only a single ``Transform``
component, one ``ModelComponent`` (specifying the visual appearance of the
entity), and so on.
All entities inherit a few common components from the ``Entity`` base class:
the ``Transform`` component for spatial positioning, and
``SynchronizationComponent``, which enables synchronization of the entity
among networked peers. Specific types of entities define additional
behaviors. For example, the model entity has components for visual
appearance (``ModelComponent``), collision detection
(``CollisionComponent``), and physics simulations (``PhysicsBodyComponent``
and ``PhysicsMotionComponent``).
Recursively searches all descendant entities for one with the given
name.
The ``Entity/findEntity(named:)`` method conducts a depth-first,
recursive search over all of the entity’s descendants for one whose
``Entity/name`` property matches the given name. The method returns the
first match. Entity names need not be unique.
- Parameters:
- name: The entity name for which to search.
- Returns: An entity with the given name, or `nil` if no entity is
found.
get · iOS 13.0+
components
TypeScript
get components(): Promise<Entity_ComponentSet>
Swift declaration
@MainActor @preconcurrency var components: Entity.ComponentSet { get set }
All the components that an entity stores.
You can only store one component of a given type on an entity.
Creates an entity with multiple components.
- Parameter components: The components to add to the entity.
This initializer adds the contents of `components` to the new ``Entity``.
The components you specify in this initializer override any default
components of the same type that RealityKit creates the entity with,
such as ``Transform``.
For example, you can use this initializer to create an entity that
anchors to the floor, displays a 1x1x1m box,
and has a y-position of 0.5:
```swift
let floorCubeComponents = [
AnchoringComponent(.plane(.horizontal, classification: .floor, minimumBounds: [1, 1])),
ModelComponent(mesh: .generateBox(size: 1), materials: []),
Transform(translation: [0, 0.5, 0])
]
let floorCubeEntity = Entity(components: floorCubeComponents)
```
- Note: You can change any of the entity's components at any time by modifying
the entity's ``Entity/components`` set.
Creates an entity by asynchronously loading it from a file URL.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files.
For Reality files that contain multiple scenes, specify which scene to load
by appending a URL fragment with the scene name — for example,
`my.reality#MyScene`. Construct the URL using `URLComponents` or
`URL(string:)` to preserve the fragment:
```swift
var components = URLComponents()
components.scheme = "file"
components.path = "/path/to/MyContent.reality"
components.fragment = "MyScene"
if let url = components.url {
let entity = try await Entity(contentsOf: url)
}
```
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
See ``init(named:in:)`` for an example of optimally loading content.
- Parameters:
- url: A file URL representing the file to load. For Reality files, append
a URL fragment to specify a scene name — for example,
`my.reality#MyScene`.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The root entity of the loaded file.
get · iOS 13.0+
isAnchored
TypeScript
get isAnchored(): Promise<boolean>
Swift declaration
@MainActor @preconcurrency var isAnchored: Bool { get }
A Boolean that indicates whether the entity is anchored.
The value of this property is `true` if the entity is anchored in a
scene. An entity that isn’t anchored becomes inactive
(``Entity/isActive`` returns `false`), meaning RealityKit doesn’t render
or simulate it.
Synchronously loads an anchor entity from a file URL.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- url: A file URL representing the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The root entity in the loaded file, which Reality Kit casts as an ``AnchorEntity``.
Synchronously loads an anchor entity from a bundle.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: The root entity in the loaded file, which Reality Kit casts as an ``AnchorEntity``.
get · iOS 26.0+
observable
TypeScript
get observable(): Promise<Entity_Observable>
Swift declaration
@MainActor var observable: Entity.Observable { get set }
Prepares an audio resource for playback.
To start playback right away with default `AudioPlaybackController` properties, use the
``Entity/playAudio(_:)`` method instead.
- Note: As soon as the system prepares an audio resource, the audio engine begins tracking the
position of the entity and allocates rendering resources, which incurs a power cost.
For optimal system resource usage, avoid preparing sounds before they are needed. For example:
```swift
let controller = entity.prepareAudio(anAudioResource)
controller.gain = -10 // Apply a custom gain, if desired.
controller.speed = 1.2 // Apply a custom speed, if desired.
controller.play()
```
- Parameters:
- resource: The audio resource the method plays.
Load an audio resource from the file system with
``AudioFileResource/init(named:in:configuration:)`` ,
or from a URL with
``AudioFileResource/init(contentsOf:withName:configuration:)``.
- Returns: An ``AudioPlaybackController`` object that you can use to start and
stop audio playback for this specific instance of a resource playing on this entity.
You can also use this controller to update playback properties, such as gain and speed, during playback.
get · iOS 18.0+
spatialAudio
TypeScript
get spatialAudio(): Promise<(SpatialAudioComponent) | null>
Swift declaration
@MainActor @preconcurrency var spatialAudio: SpatialAudioComponent? { get set }
The component that configures the spatial rendering of sounds from this entity.
@MainActor @preconcurrency var spatialAudio: SpatialAudioComponent? { get set }
The component that configures the spatial rendering of sounds from this entity.
method · iOS 13.0+
stopAllAudio
TypeScript
stopAllAudio(): Promise<void>
Swift declaration
@MainActor @preconcurrency func stopAllAudio()
Stops playback for all audio on this entity.
You can stop a specific ``AudioPlaybackController`` instance from
playing a particular resource by calling the controller’s
``AudioPlaybackController/stop()`` method.
Moves the character along a specified vector over a period of time.
Moves the character in the collision world, with continuous collision checking and response.
This will create character collision events.
Entity.transform will be updated on the next engine tick.
Use `CharacterControllerStateComponent` to get additional information about the state of the character after the move.
- Parameters:
- moveDelta: Delta vector to attempt to move capsule in collision world.
- deltaTime: Time between last frame and current.
- referenceEntity: Reference entity that defines the frame of reference of the move delta.
Can be `nil`, which is equivalent to "world space".
- collisionHandler: Optional callback when an entity was hit. One call per each hit entity.
- Returns: Collision flags that indicate the location of the collision.
Plays all the animations with the given name on the entity.
The method plays all the animations in the
``Entity/availableAnimations`` property with a matching name. If there
are none, the method returns a controller showing a stopped animation.
- Parameters:
- animationName: The name of the animation.
- transitionDuration: The duration in seconds over which the animation
fades in or cross-fades.
- startsPaused: A Boolean that you set to `true` to return from the call
with the animations paused. Set to `false` to start the animations right
away.
- recursive: Indicates whether to also play animations on all
descendants of the entity.
- Returns: An animation playback controller that you can use to start
and stop the animations.
Plays the given animation on the entity.
- Parameters:
- animation: The animation to play.
- transitionDuration: The duration in seconds over which the animation
fades in or cross-fades.
- startsPaused: A Boolean that you set to `true` to return from the call
with the animation paused. Set to `false` to start the animation right away.
- Returns: An animation playback controller that you can use to start
and stop the animation.
Plays an animation with the specified options.
Call this method to play an animation and configure playback options.
RealityKit supports blending up to two different animations at the same
time. When RealityKit applies multiple animations to an entity, the
order in which it applies the animations affects the final animation.
Use the `blendLayerOffset` parameter to specify the order of animations
when playing multiple animations at the same time.
- Parameters:
- animation: The animation to play.
- transitionDuration: The duration in seconds over which the animation
fades in or cross-fades.
- blendLayerOffset: An integer that specifies the order in which to
apply animations when more than one animation is playing.
- separateAnimatedValue: When set to false, this value indicates that the
animation will write directly to the entity's base value. When set to true,
this value indicates that the animation will write to an interim value for
the duration of the animation. If this value is set to true then when the
animation completes, the entity's value will be reset to the base value.
- startsPaused: A Boolean that pauses the progress of an animation when
set to `true`.
- clock: An optional clock to drive the animation with a custom timescale.
- handoffType: Type of handoff behavior between a currently-playing animation
and the new animation. Defaults to `.snapshotAndReplace(applyToAllLayers: true)`.
- Returns: An animation playback controller that you can use to start
and stop the animation.
Plays an animation with the specified options.
Call this method to play an animation and configure playback options.
RealityKit supports blending up to two different animations at the same
time. When RealityKit applies multiple animations to an entity, the
order in which it applies the animations affects the final animation.
Use the `blendLayerOffset` parameter to specify the order of animations
when playing multiple animations at the same time.
- Parameters:
- animation: The animation to play.
- transitionDuration: The duration in seconds over which the animation
fades in or cross-fades.
- blendLayerOffset: An integer that specifies the order in which to
apply animations when more than one animation is playing. Valid values
are `0` or `1`.
- separateAnimatedValue: When set to false, this value indicates that the
animation will write directly to the entity's base value. When set to true,
this value indicates that the animation will write to an interim value for
the duration of the animation. If this value is set to true then when the
animation completes, the entity's value will be reset to the base value.
- startsPaused: A Boolean that pauses the progress of an animation when
set to `true`.
- clock: An optional clock to drive the animation with a custom
timescale.
- Returns: An animation playback controller that you can use to start
and stop the animation.
get · iOS 15.0+
bindableValues
TypeScript
get bindableValues(): Promise<BindableValuesReference>
Swift declaration
@MainActor @preconcurrency var bindableValues: BindableValuesReference { get set }
Returns a load request that creates a model entity by asynchronously loading
it from a file URL and flattening the model entity's hierarchy.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
- Parameters:
- url: The location of a file that represents an entity.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
Asynchronously loads a model entity from a bundle.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: A resource loader that publishes the root entity in the
loaded file as a ``ModelEntity``.
Asynchronously loads an anchor entity from a file URL.
- Parameters:
- url: A file URL representing the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: A resource loader that publishes the root entity in the
loaded file as an ``AnchorEntity``.
Asynchronously loads an anchor entity from a bundle.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: A resource loader that publishes the root entity in the
loaded file as an ``AnchorEntity``.
Synchronously loads a body-tracked entity from a file URL.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- url: A file URL representing the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The root entity in the loaded file, cast as a ``BodyTrackedEntity``.
Synchronously loads a body-tracked entity from a bundle.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: The root entity in the loaded file, cast as a ``BodyTrackedEntity``.
get · iOS 13.0+
debugDescription
TypeScript
get debugDescription(): Promise<string>
Swift declaration
@MainActor @preconcurrency var debugDescription: String { get }
Moves the character instantly to a new position.
This method moves the character to a location specified relative to another entity. Pass `nil` in
`relativeTo` to specify a position in world coordinates. A teleport move happens instantly.
RealityKit does no collision checking when it moves the entity.
- Parameters:
- position: The position to move the character to, relative to `referenceEntity`.
- referenceEntity: The entity that defines a frame of reference.
Set this to `nil` to indicate world space.
get · iOS 14.0+ · Deprecated in iOS 17.0
accessibilityLabel
TypeScript
get accessibilityLabel(): Promise<(string) | null>
Swift declaration
@MainActor @preconcurrency var accessibilityLabel: String? { get set }
A succinct label that identifies the purpose of the image.
The default value for this property is `false`.
For entities with ``Entity/isAccessibilityElement`` set to
<doc://com.apple.documentation/documentation/swift/true>, iOS uses this
string to provide information to users of assistive technologies like
VoiceOver. Set this property to a name or short description that
accurately describes the entity. If you wish to provide additional
information or a longer description of the entity, you can use
``Entity/accessibilityDescription``.
@MainActor @preconcurrency var accessibilityLabel: String? { get set }
A succinct label that identifies the purpose of the image.
The default value for this property is `false`.
For entities with ``Entity/isAccessibilityElement`` set to
<doc://com.apple.documentation/documentation/swift/true>, iOS uses this
string to provide information to users of assistive technologies like
VoiceOver. Set this property to a name or short description that
accurately describes the entity. If you wish to provide additional
information or a longer description of the entity, you can use
``Entity/accessibilityDescription``.
get · iOS 13.0+
availableAnimations
TypeScript
get availableAnimations(): Promise<Array<AnimationResource>>
Swift declaration
@MainActor @preconcurrency var availableAnimations: [AnimationResource] { get }
The list of animations associated with the entity.
When you import an entity from a file, for example by using the
``Entity/load(named:in:)`` method, the entity might contain associated
animations. Any that RealityKit supports appear in the
``Entity/availableAnimations`` array.
To play a particular animation resource from the list, call the
``Entity/playAnimation(_:transitionDuration:startsPaused:)`` method.
Alternatively, to play all animations with a given name, call the
`playAnimation(named:transitionDuration:startsPaused:)` method instead.
get · iOS 15.0+
characterController
TypeScript
get characterController(): Promise<(CharacterControllerComponent) | null>
Swift declaration
@MainActor @preconcurrency var characterController: CharacterControllerComponent? { get set }
The character controller component for the entity.
Apply a tap to an Entity or one of its ancestors to trigger a RealityComposer behavior if one is present.
This method looks for a RealityComposer tap trigger, starting with `self` and moving up the Entity hierarchy.
As soon as an entity with a tap trigger is found, the trigger is fired, and the method returns `true`. If no
tap trigger is found, the method returns `false`.
- Returns: `true` if a tap trigger was fired, otherwise returns `false`.
```swift
struct ContentView: View {
var body: some View {
RealityView() { content in
if let entity = try? await Entity(named: "Content") {
content.add(entity)
}
}.gesture(TapGesture().targetedToAnyEntity().onEnded { value in
if value.entity.applyTapForBehaviors() {
// Behavior was activated
} else {
// Behavior was not activated
}
})
}
}
```
get · iOS 13.0+
isEnabledInHierarchy
TypeScript
get isEnabledInHierarchy(): Promise<boolean>
Swift declaration
@MainActor @preconcurrency var isEnabledInHierarchy: Bool { get }
A Boolean that indicates whether the entity and all of its ancestors are
enabled.
The value of this property is `true` if the entity and all of its
ancestors are enabled, regardless of anchor state.
Asynchronously loads a body-tracked entity from a file URL.
- Parameters:
- url: A file URL representing the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: A resource loader that publishes the root entity in the
loaded file as a ``BodyTrackedEntity``.
Asynchronously loads a body-tracked entity from a bundle.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: A resource loader that publishes the root entity in the
loaded file as a ``BodyTrackedEntity``.
get · iOS 15.0+
defaultAnimationClock
TypeScript
get defaultAnimationClock(): Promise<unknown>
Swift declaration
@MainActor @preconcurrency var defaultAnimationClock: CMClockOrTimebase { get set }
Returns the default animation clock for this entity.
Creates the shape used to detect collisions between two entities that
have collision components.
Call this method on entities that have a mesh to prepare a shape used for collision
detection. The method stores the shape in the entity’s
``CollisionComponent`` instance.
This method has no effect for entities without a mesh. Nevertheless, the
method is defined for all entities so that you can call it on any
entity, and have the calculation propagate recursively to all that
entity’s descendants.
- Parameters:
- recursive: A Boolean that you set to `true` to also generate the
collision shapes for all descendants of the entity. If a descendant is in a
`LevelOfDetailComponent`'s level and is not the base level it will be
skipped.
- isStatic: A Boolean value that indicates whether the colliders move. Set this to `true` to indicate the colliders don't move.
Non-moving, static colliders are more efficient to use than non-static ones.
Creates the shape used to detect collisions between two entities that
have collision components.
Call this method on entities that have a mesh to prepare a shape used for collision
detection. The method stores the shape in the entity’s
``CollisionComponent`` instance.
This method has no effect for entities without a mesh. Nevertheless, the
method is defined for all entities so that you can call it on any
entity, and have the calculation propagate recursively to all that
entity’s descendants.
- Parameters:
- recursive: A Boolean that you set to `true` to also generate the
collision shapes for all descendants of the entity.
get · iOS 14.0+ · Deprecated in iOS 17.0
accessibilityDescription
TypeScript
get accessibilityDescription(): Promise<(string) | null>
Swift declaration
@MainActor @preconcurrency var accessibilityDescription: String? { get set }
A longer description of the entity for use by assistive technologies.
Loads an entity from a configuration catalog and a dictionary of configuration choices.
- Parameters:
- catalog: A collection of alternative representations for an entity.
- configurations: A dictionary of configuration choices the initializer applies as it loads the entity,
mapping the ID of a configuration set to the ID of a configuration within that set.
Creates an entity by asynchronously loading it from the in-memory contents of a file stored in a Data object.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files. Pass the data's format as the
`contentType` so RealityKit selects a parser directly instead of guessing
the file type from the data. Prefer this initializer over
``init(from:named:)`` when the format is already known — for example from a
server's `Content-Type` or a MIME type.
The supported content types are:
- `UTType.usd` for USD content (`.usd`, `.usda`, `.usdc`).
- `UTType.usdz` for USD package files (`.usdz`).
- `UTType.realityFile` for Reality files (`.reality`).
When you only have a file name or extension, look up the `UTType` using `UTType()`, e.g.:
```swift
let contentType = UTType(filenameExtension: url.pathExtension) ?? .usd
let entity = try await Entity(from: data, contentType: contentType)
```
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
See ``init(named:in:)`` for an example of optimally loading content.
- Parameters:
- data: The Data object containing the in-memory contents of the file to load.
- named: The name of the scene to load, if loading from a `.reality` file.
- contentType: The format of `data`, expressed as a `UTType`. RealityKit
uses this value to select a parser instead of guessing the file type from the data.
- Returns: The root entity of the loaded file.
Creates an entity by asynchronously loading it from the in-memory contents of a file stored in a Data object.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files.
This method automatically determines the file type using the first few bytes of the Data object.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
See ``init(named:in:)`` for an example of optimally loading content.
- Parameters:
- data: The Data object containing the in-memory contents of the file to load.
- named: The name of the scene to load, if loading from a `.reality` file.
- Returns: The root entity of the loaded file.
Returns an entity by synchronously loading it from a file URL.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files. For Reality files that contain
multiple scenes, specify which scene to load by appending a URL fragment
with the scene name — for example, `my.reality#MyScene`.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
- Parameters:
- url: A file URL representing the file to load. For Reality files, append
a URL fragment to specify a scene name — for example,
`my.reality#MyScene`.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The root entity in the loaded file.
Returns an entity by synchronously loading it from a bundle.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files.
When building your app, Xcode automatically converts any Reality
Composer projects (`.rcproject`) in the selected target into Reality
files, which it then copies into your app’s bundle.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
- Parameters:
- name: The base name of the file to load. An extension isn't required,
but you can provide one to resolve collisions. In the presence of a collision,
the provided name resolves with the following order of precedence:
[`.usdz`, `.usd`, `.usdc`, `.usda`].
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: The root entity in the loaded file.
get · iOS 13.0+
name
TypeScript
get name(): Promise<string>
Swift declaration
@MainActor @preconcurrency var name: String { get set }
The name of the entity.
You can find an entity by name in a scene by calling the scene’s
``Scene/findEntity(named:)`` method. Or you can recursively search among
the children of a given entity by calling the entity’s
``Entity/findEntity(named:)`` method.
Entity names are not guaranteed to be unique. When you search by name,
these methods return the first entity encountered with the given name.
set · iOS 13.0+
name
TypeScript
setName(value: string): Promise<void>
Swift declaration
@MainActor @preconcurrency var name: String { get set }
The name of the entity.
You can find an entity by name in a scene by calling the scene’s
``Scene/findEntity(named:)`` method. Or you can recursively search among
the children of a given entity by calling the entity’s
``Entity/findEntity(named:)`` method.
Entity names are not guaranteed to be unique. When you search by name,
these methods return the first entity encountered with the given name.
get · iOS 18.0+
pins
TypeScript
get pins(): Promise<EntityGeometricPins>
Swift declaration
@MainActor @preconcurrency var pins: EntityGeometricPins { get }
The entity's geometric pins.
You can look up, add, and remove a ``GeometricPin`` for the owning entity
through this ``EntityGeometricPins`` instance.
The entity's ``GeometricPinsComponent`` stores any added geometric pins.
Other ``Component`` types on an ``Entity`` may also provide ``GeometricPin`` instances,
such as for skeletal pose joints.
There is no distinction between these two when ``GeometricPin`` instances are accessed.
### Geometric pins for skeletal pose joints
Pins for skeletal pose joints are not predefined, they need to be set in entity's GeometricPinsComponent before you can access them. When associating a pin with a skeletal pose joint, you need to pass in the
correct joint names either in full pose joint name or with its leaf joint name:
```swift
let fullNamePin = skeletalPoseEntity.pins.set(named: "fullName", skeletalJointName: "root/hips_joint/spine_1_joint/spine_2_joint")
let shortNamePin = skeletalPoseEntity.pins.set(named: "shortName", skeletalJointName: "spine_2_joint")
```
The pose (position and orientation) of the ``GeometricPin`` is the current pose of the joint
in the coordinate frame of the ``Entity`` (i.e. *not* relative to the parent joint).
While the skeletal pose is animated, the ``GeometricPin`` pose change on every frame.
To print all the pins, you can loop over ``Entity/pins``.
```swift
for pin in skeletalPoseEntity.pins {
print("joint name: \(pin.name)") // Full joint path name.
print(" position: \(pin.position)") // In coordinate frame of skeletalPoseEntity.
print(" orientation: \(pin.orientation)") // In coordinate frame of skeletalPoseEntity.
}
```
In skeletal pose joint names, prefix the characters
`.`, `[`, `]` and `\`
with an escaping character (`\`).
For example, to access a skeletal pose joint named `"my.joint"`:
```swift
// To include a literal backslash in a string,
// escape it with an additional backslash.
let myJointPinEscaped = skeletalPoseEntity.pins.set(named: "myJointPinEscaped", skeletalJointName: "my\\.joint")
// Alternatively, use Swift's raw string feature
// by enclosing the string in # symbols.
let myJointPinRaw = skeletalPoseEntity.pins.set(named: "myJointPinEscaped", skeletalJointName: #"my\.joint"#)
```
- Note: Character escaping is only required for skeletal pose joints.
Duplicates an entity to create a new entity.
All component data is cloned automatically. If you clone an entity that
stores custom data that’s not part of a component, override the
``Entity/didClone(from:)`` method to copy that data manually.
- Parameters:
- recursive: A Boolean that you set to `true` to recursively copy all
the children of the entity. Otherwise, no descendants are copied.
- Returns: The duplicate.
Creates an entity by asynchronously loading it from a bundle.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
You can use a task group to await all loads before adding them to the scene to
display content from multiple scenes without hitches or pop-in.
```swift
struct SomeRealityView: View {
var body: some View {
RealityView { content in
// Add the initial RealityKit content.
let entities : [Entity] = await withTaskGroup(of: Entity?.self) { taskGroup in
// Load all the scenes concurrently.
taskGroup.addTask { return try? await Entity(named: "SceneA", in: realityKitContentBundle) }
taskGroup.addTask { return try? await Entity(named: "SceneB", in: realityKitContentBundle) }
taskGroup.addTask { return try? await Entity(named: "SceneC", in: realityKitContentBundle) }
var entities = [Entity]()
// Wait for all the scenes to load.
for await entity in taskGroup {
if let entity {
entities.append(entity)
}
}
return entities
}
// Add all the content.
for entity in entities {
content.add(entity)
}
}
}
}
```
- Parameters:
- name: The base name of the file to load, omitting the filename extension, or scene name if loading from a `.reality` file.
- bundle: The bundle containing the file. Use `nil` to search the app's main bundle.
- Returns: The root entity in the loaded file.
get · iOS 13.0+
scene
TypeScript
get scene(): Promise<(Scene) | null>
Swift declaration
@MainActor @preconcurrency var scene: Scene? { get }
The scene that owns the entity.
An entity belongs to a scene if the entity is part of a hierarchy that’s
rooted in the scene’s ``Scene/anchors`` collection.
The value of the property is `nil` if the entity isn’t currently
attached to any scene.
Exports the entity as a RealityKit file to a location in the file system.
- Parameters:
- url: The location URL in the file system where you want to save the `.reality` file.
This method generates a file with a `.reality` suffix,
automatically setting its compatibility with other systems based on the Entity's tree content.
The Entity and its children may contain components or assets that can require the resulting RealityKit file
to be compatible with system versions between:
- iOS 18 or later
- macOS 15 or later
- visionOS 2 or later
- tvOS 26 or later
Logs with the prefix [RealityKit File Compatibility Info] will be posted to the console
whenever a component or asset requires a compatibility adjustment.
> Important:
> During its initial setup phase, this method can indirectly block the main thread,
> and also has the potential to block it for the full duration of the call if the system
> has additional work it needs to do there.
Exports an array of entities as separate scenes within a single RealityKit file.
- Parameters:
- entities: An array of named entities to be written as separate scenes in the Reality file.
- url: The location URL in the file system where you want to save the `.reality` file.
- options: Options for writing the Reality file, such as texture compression settings.
This method generates a file with a `.reality` suffix,
automatically setting its compatibility with other systems based on all the entity tree contents.
The entities and their children may contain components or assets that can require the resulting RealityKit file
to be compatible with system versions between:
- iOS 18 or later
- macOS 15 or later
- visionOS 2 or later
- tvOS 26 or later
Elements of the `entities` array must have a non-empty ``Entity/name`` property.
Each name must be unique within the array to allow unambiguous scene loading.
After writing, individual scenes can be loaded using the ``Entity/init(contentsOf:withName:)`` initializer
with the entity's name as the scene identifier.
Logs with the prefix [RealityKit File Compatibility Info] will be posted to the console
whenever a component or asset requires a compatibility adjustment.
- Throws: An error if any entity in the array has an empty name.
> Important:
> During its initial setup phase, this method can indirectly block the main thread,
> and also has the potential to block it for the full duration of the call if the system
> has additional work it needs to do there.
get · iOS 13.0+
anchor
TypeScript
get anchor(): Promise<(SDKHandle) | null>
Swift declaration
@MainActor @preconcurrency var anchor: (any HasAnchoring)? { get }
The nearest ancestor entity that can act as an anchor.
This property returns `nil` if no ancestor can act as an anchor. An
entity can act as an anchor if it adopts the ``HasAnchoring`` protocol.
Just because an ancestor can be anchored doesn’t mean that it is.
Inspect the ``Entity/isAnchored`` property to see if an entity (or one
of its ancestors) is anchored.
@MainActor func attach(_ source: GeometricPin? = nil, to target: GeometricPin)
Attach an entity to a target pin owned by another entity with an optional specified source pin
This utility function has the same effect of adding an AttachedTransformComponent
created with the same parameter to the entity you are calling upon
- Parameter source: The optional source pin existed on the current entity
- Parameter target: The target pin existed on the target entity
Tells a newly cloned entity that cloning is complete.
This method clones all component data automatically. When you clone an
entity that stores custom data that’s not part of a component, override
the ``Entity/didClone(from:)`` method to copy that data manually after
the clone finishes.
- Parameters:
- source: The entity from which the cloned entity was copied.
get · iOS 13.0+
isActive
TypeScript
get isActive(): Promise<boolean>
Swift declaration
@MainActor @preconcurrency var isActive: Bool { get }
A Boolean that indicates whether the entity is active.
The value of this property is `true` if the entity is anchored in a
scene, and it and all of its ancestors are enabled (``Entity/isEnabled``
is set to `true`). RealityKit doesn’t simulate or render inactive
entities.
get · iOS 13.0+
isEnabled
TypeScript
get isEnabled(): Promise<boolean>
Swift declaration
@MainActor @preconcurrency var isEnabled: Bool { get set }
A Boolean that you set to enable or disable the entity and its
descendants.
Set this value to `true` to enable the entity. Unless an ancestor is
disabled, the entity and all of its enabled descendants, up to the first
that’s disabled, report ``Entity/isEnabledInHierarchy`` of `true`. If an
ancestor is disabled, they all report `false`. The state of
``Entity/isActive`` for enabled entities is `true` if they are anchored,
or `false` otherwise.
If you disable an entity, it and all of its descendants become both
disabled (``Entity/isEnabledInHierarchy`` returns `false`) and inactive
(``Entity/isActive`` returns `false`), regardless of any other state.
When an entity is disabled, it's no longer visible in your scene. However, the entity is still included in an ``RealityKit/EntityQuery``.
set · iOS 13.0+
isEnabled
TypeScript
setIsEnabled(value: boolean): Promise<void>
Swift declaration
@MainActor @preconcurrency var isEnabled: Bool { get set }
A Boolean that you set to enable or disable the entity and its
descendants.
Set this value to `true` to enable the entity. Unless an ancestor is
disabled, the entity and all of its enabled descendants, up to the first
that’s disabled, report ``Entity/isEnabledInHierarchy`` of `true`. If an
ancestor is disabled, they all report `false`. The state of
``Entity/isActive`` for enabled entities is `true` if they are anchored,
or `false` otherwise.
If you disable an entity, it and all of its descendants become both
disabled (``Entity/isEnabledInHierarchy`` returns `false`) and inactive
(``Entity/isActive`` returns `false`), regardless of any other state.
When an entity is disabled, it's no longer visible in your scene. However, the entity is still included in an ``RealityKit/EntityQuery``.
Returns a load request that creates an entity by asynchronously loading
it from a file URL and preserving the entity’s hierarchy.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files. For Reality files that contain
multiple scenes, specify which scene to load by appending a URL fragment
with the scene name — for example, `my.reality#MyScene`.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
- Parameters:
- url: A file URL representing the file to load. For Reality files, append
a URL fragment to specify a scene name — for example,
`my.reality#MyScene`.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
Returns a load request that creates an entity by asynchronously loading it from a bundle.
RealityKit supports loading entities from USD (`.usd`, `.usda`, `.usdc`,
`.usdz`) and Reality (`.reality`) files.
When building your app, Xcode automatically converts any Reality
Composer projects (`.rcproject`) in the selected target into Reality
files, which it then copies into your app’s bundle.
For more information on loading entities, see
<doc:loading-entities-from-a-file>.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: A resource loader that publishes the root entity in the
loaded file.
Synchronously loads a model entity from a file URL.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- url: A file URL representing the file to load.
- resourceName: A unique name the method assigns to the resource it loads,
for use in network synchronization.
- Returns: The root entity in the loaded file, which Reality Kit casts as a ``ModelEntity``.
Synchronously loads a model entity from a bundle.
Loading an ``Entity`` with this method blocks the main actor because it’s synchronous, so only call it from a command-line application.
The method can stall a regular app, which makes it visibly hitch, and the system terminates an app if its UI becomes unresponsive.
See ``init(named:in:)`` for an example that demonstrates how to safely load content.
- Parameters:
- name: The base name of the file to load, omitting the filename extension.
- bundle: The bundle containing the file. Use `nil` to search the app’s
main bundle.
- Returns: The root entity in the loaded file, which Reality Kit casts as a ``ModelEntity``.
Asynchronously prepares and plays a new audio playback instance at a specified time on this entity.
Use this method to schedule playback of a sound source to a precise time in the future.
This method enables sample-accurate timing for individual sounds and synchronization of multiple
audio sources.
The method prepares the audio by calling `prepareAudio(_:)`, and then immediately calls the
`play(at: time)` method of the controller that it returns. Any call to play() will cancel pending
scheduled time and play audio immediately, while any call to `playAudio(at: time)` will
cancel current scheduled time and schedule for new time.
Audio preparation must complete before the scheduled playback time to maintain precise timing.
If preparation is still in progress when the scheduled time arrives, or if the scheduled time is
in the past, playback starts immediately, which may result in timing drift. For accurate
synchronization, schedule a time sufficiently far in the future.
The returned controller's `isPlaying` property becomes `true` immediately after calling
`playAudio(at: time)`. This ensures that checking the `isPlaying` property immediately
returns the correct state for subsequent operations, such as deciding whether to play
the audio again.
For synchronizing multiple sounds, use the same base time for all scheduled playback calls.
- Parameters:
- resource: The audio resource the method plays. Load an audio resource from the file system
with `init(named:in:configuration:)`, or from a URL with `init(contentsOf:withName:configuration:)`.
- time: The AVAudioTime when the audio file should start playing.
- Returns: An `AudioPlaybackController` object that you can use to start and stop audio playback
for this specific instance of a resource playing on this entity. You can also use this controller
to update playback properties, such as gain and speed, during playback.
Prepares and plays a new audio playback instance on this entity.
The method prepares the audio by calling
``Entity/prepareAudio(_:)``, and then immediately calls the
``AudioPlaybackController/play()`` method of the controller that it returns.
To begin multiple playback instances you can call `playAudio` multiple times.
- Parameters:
- resource: The audio resource the method plays.
Load an audio resource from the file system with
``AudioFileResource/init(named:in:configuration:)`` ,
or from a URL with
``AudioFileResource/init(contentsOf:withName:configuration:)``.
- Returns: An ``AudioPlaybackController`` object that you can use to start and
stop audio playback for this specific instance of a resource playing on this entity.
You can also use this controller to update playback properties, such as gain and speed, during playback.
