Class

Entity

An element of a RealityKit scene to which you attach components that provide appearance and behavior characteristics for the entity.

Declaration

class Entity

Overview

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 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.

Block diagram showing how entity hierarchies, composed of different kinds of entities, attach to a scene, which is itself a child of the AR view.

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 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 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.

Diagram showing the components present in the base entity class, as well as in the derived anchor entity and model entity classes.

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).

Topics

Creating an Entity

init()

Creates a new entity.

func clone(recursive: Bool) -> Self

Duplicates an entity to create a new entity.

func didClone(from: Entity)

Tells a newly cloned entity that cloning is complete.

Loading a Stored Entity

Stored Entities

Manage entities stored as assets on disk.

Identifying an Entity

var scene: Scene?

The scene that owns the entity.

var name: String

The name of the entity.

func findEntity(named: String) -> Entity?

Recursively searches all descendant entities for one with the given name.

var id: ObjectIdentifier

The stable identity of the entity associated with self.

var id: UInt64

The stable identity of the entity.

typealias Entity.ID

A type of unique identifier used for an entity.

Getting State

var isEnabled: Bool

A Boolean that you set to enable or disable the entity and its descendants.

var isEnabledInHierarchy: Bool

A Boolean that indicates whether the entity and all of its ancestors are enabled.

var isActive: Bool

A Boolean that indicates whether the entity is active.

var isAnchored: Bool

A Boolean that indicates whether the entity is anchored.

Establishing a Hierarchy

var parent: Entity?

The parent entity.

func setParent(Entity?, preservingWorldTransform: Bool)

Attaches the entity as a child to the specified entity.

func removeFromParent(preservingWorldTransform: Bool)

Removes the entity from its current parent or from the scene if it is a root entity.

var children: Entity.ChildCollection

The child entities that the entity manages.

func addChild(Entity, preservingWorldTransform: Bool)

Adds the given entity to the collection of child entities.

func removeChild(Entity, preservingWorldTransform: Bool)

Removes the given child from the entity.

struct Entity.ChildCollection

A collection of child entities.

protocol HasHierarchy

An interface that provides access to a parent entity and child entities.

Adding Components

var components: Entity.ComponentSet

All the components stored on the entity.

struct Entity.ComponentSet

A set of stored components.

Positioning Entities in Space

The Transform Component

Manipulate the scale, rotation, and position of the entity.

protocol HasTransform

An interface that enables manipulating the scale, rotation, and translation of an entity.

Synchronizing an Entity Among Peers

var synchronization: SynchronizationComponent?

The entity’s synchronization component.

struct SynchronizationComponent

A component that synchronizes an entity between processes and networked applications.

var isOwner: Bool

A Boolean that indicates whether the calling process owns the entity.

func withUnsynchronized(() -> Void)

Calls the given closure in a way such that component changes that the closure makes don’t trigger synchronization.

protocol HasSynchronization

An interface that enables an entity to be synchronized between processes and networked applications.

Finding the Nearest Anchor

var anchor: HasAnchoring?

The nearest ancestor entity that can act as an anchor.

Calculating the Collision Shape

func generateCollisionShapes(recursive: Bool)

Creates the shape used to detect collisions between two entities that have collision components.

Playing Audio

func playAudio(AudioResource) -> AudioPlaybackController

Plays sound from an audio resource on this entity.

func prepareAudio(AudioResource) -> AudioPlaybackController

Prepares an audio resource for playback.

func stopAllAudio()

Stops audio playback.

Describing the Entity

var debugDescription: String

A human readable description of the entity.

Comparing Entities

static func == (Entity, Entity) -> Bool

Indicates whether two entities are equal.

static func != (Entity, Entity) -> Bool

Indicates whether two entities are not equal.

func hash(into: inout Hasher)

Hashes the essential components of the entity by feeding them into the given hash function.

var hashValue: Int

The hashed value of the entity.

See Also

The Entity Component System

class Scene

A container that holds the collection of entities rendered by an AR view.

Beta
protocol Component

A representation of a geometry or a behavior that you apply to an entity.

Beta
protocol Resource

A shared resource you use to configure a component, like a material, mesh, or texture.

Beta

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software