Class

ModelEntity

A representation of a physical object that RealityKit renders and optionally simulates.

Declaration

class ModelEntity : Entity

Overview

Use one or more model entities to place physical objects in a scene. In addition to the components they inherit from the Entity class, model entities have geometry, described by their ModelComponent. Model entities acquire the model component by conforming to the HasModel protocol. You specify meshes and materials to control how a model entity appears.

Diagram showing the components present in the model entity.

Models respond to physics simulations because they conform to the HasPhysics protocol. You give them mass and other physical properties with a PhysicsBodyComponent instance, and then apply forces or impulses. The simulator uses a PhysicsMotionComponent to manage the linear and angular velocity of the object. Alternatively, you can selectively circumvent the simulation to control position and velocity yourself. Do this for a given model by setting its physics body mode to PhysicsBodyMode.kinematic.

Models can also collide with one another, and with other entities that conform to the HasCollision protocol. The CollisionComponent provides parameters that let you manage which models collide with each other. It also lets you control the collision shape, which for performance reasons, is typically simpler than the visual geometry.

Topics

Creating a Model

init()

Creates a model entity.

init(mesh: MeshResource, materials: [Material])

Creates a model entity with a particular mesh and set of materials.

init(mesh: MeshResource, materials: [Material], collisionShape: ShapeResource, mass: Float)

Creates a model entity with a particular mesh, set of materials, collision shape, and mass.

init(mesh: MeshResource, materials: [Material], collisionShapes: [ShapeResource], mass: Float)

Creates a model entity with a particular mesh, set of materials, a composite collision shape, and mass.

func clone(recursive: Bool) -> Self

Duplicates a model entity to create a new entity.

Identifying a Model Entity

var id: ObjectIdentifier

The stable identity of the entity associated with self.

var id: UInt64

The stable identity of the model entity.

typealias ModelEntity.ID

A type of unique identifier used for a model entity.

Configuring the Model

var model: ModelComponent?

The model component for the model entity.

struct ModelComponent

A collection of resources that create the visual appearance of an entity.

var jointNames: [String]

The names of all the joints in the model entity.

var jointTransforms: [Transform]

The relative joint transforms of the model entity.

protocol HasModel

An interface that provides meshes and materials to define the visual appearance of an entity.

Detecting Collisions

var collision: CollisionComponent?

The collision component for the model entity.

struct CollisionComponent

A component that gives an entity the ability to collide with other entities that also have collision components.

enum CollisionEvents

Events associated with collisions.

protocol HasCollision

An interface used for ray casting and collision detection.

Simulating Forces and Impulses

var physicsBody: PhysicsBodyComponent?

A component that is used for physics simulations of the model entity in accordance with the laws of Newtonian mechanics.

struct PhysicsBodyComponent

A component that defines an entity’s behavior in physics body simulations.

func addForce(SIMD3<Float>, relativeTo: Entity?)

Applies a force to the physics body at its center of mass.

func addForce(SIMD3<Float>, at: SIMD3<Float>, relativeTo: Entity?)

Applies a force to the physics body at the specified position.

func addTorque(SIMD3<Float>, relativeTo: Entity?)

Applies a torque to the physics body at its center of mass.

func clearForcesAndTorques()

Clears all forces previously added to the physics body.

func applyLinearImpulse(SIMD3<Float>, relativeTo: Entity?)

Applies an impulse to the physics body at its center of mass.

func applyAngularImpulse(SIMD3<Float>, relativeTo: Entity?)

Applies an angular (torque) impulse to the physics body at its center of mass.

func applyImpulse(SIMD3<Float>, at: SIMD3<Float>, relativeTo: Entity?)

Applies an impulse to the physics body at the specified position.

func resetPhysicsTransform(recursive: Bool)

Resets the position, orientation, and velocities of the simulated physics body.

func resetPhysicsTransform(Transform, recursive: Bool)

Resets the position and velocities of the simulated physics body.

Deprecated
protocol HasPhysicsBody

An interface that enables physics simulations based on the rules of Newtonian mechanics.

Simulating Movement

var physicsMotion: PhysicsMotionComponent?

The physics motion component used by physics simulations of the model entity.

struct PhysicsMotionComponent

A component that controls the motion of the body in physics simulations.

protocol HasPhysicsMotion

An interface that provides velocity properties for physics simulations.

protocol HasPhysics

An interface that combines the physics body and physics motion interfaces.

Loading a Stored Entity

Stored Entities

Manage entities stored as assets on disk.

Positioning Entities in Space

Finding the Nearest Anchor

Calculating the Collision Shape

Describing the Model

See Also

Scene Elements

class AnchorEntity

An anchor that tethers virtual content to a real-world object in an AR session.

class TriggerVolume

An invisible 3D shape that detects when objects enter or exit a given region of space.

class BodyTrackedEntity

An entity used to animate a virtual character in an AR scene by tracking a real person.