struct · iOS 13.0+ · SDK 27.1
struct PhysicsBodyComponentA component that defines an entity’s behavior in physics body simulations. Only entities with a ``RealityKit/PhysicsBodyComponent`` and a ``RealityKit/CollisionComponent`` can participate in a scene's physics simulation. If you need to move an entity that participates in the physics system, it also needs a ``RealityKit/PhysicsMotionComponent``. Add a physics body component to an entity by adopting the ``HasPhysicsBody`` protocol, which allows RealityKit’s physics simulation to compute behavior in response to forces acting upon the body, following basic rules of Newtonian mechanics. Note the following when considering applying a non-uniform scale to an entity: - Non-uniform scaling is applicable only to box, convex mesh and triangle mesh collision shapes. - Non-uniform scaling is not supported for all other types of collision shapes. In this case the scale.x value is duplicated to the scale's y and z components as well to force scale uniformity based on the x component. - If the entity has a non-uniform scale assigned to its transform then that entity should not have any descendants assigned that contain rotations in their transforms. A good rule of thumb is to assign the non-uniform scale to the entity that has the collision shape, and avoid adding children below that entity. - Note: Model entities have a physics body component by default.
get linearDamping(): numbervar linearDamping: Float { get set }The value that controls how fast a dynamic rigid body's translation motion approaches the zero rest state. - Important: Use a non-negative value for linear damping.
set linearDamping(value: number)var linearDamping: Float { get set }The value that controls how fast a dynamic rigid body's translation motion approaches the zero rest state. - Important: Use a non-negative value for linear damping.
get angularDamping(): numbervar angularDamping: Float { get set }The value that controls how fast a dynamic rigid body's rotational motion approaches the zero rest state. - Important: Use a non-negative value for angular damping.
set angularDamping(value: number)var angularDamping: Float { get set }The value that controls how fast a dynamic rigid body's rotational motion approaches the zero rest state. - Important: Use a non-negative value for angular damping.
static initMassPropertiesMaterialMode(massProperties?: PhysicsMassProperties, material?: (PhysicsMaterialResource) | null, mode?: PhysicsBodyMode): PhysicsBodyComponentinit(massProperties: PhysicsMassProperties = .default, material: PhysicsMaterialResource? = nil, mode: PhysicsBodyMode = .dynamic)Creates a physics body component with the given mass properties, material, and mode. - Parameters: - massProperties: The mass properties, like inertia. - material: The material properties, like friction. - mode: The simulation mode that indicates how a body responds to forces.
get massProperties(): PhysicsMassPropertiesvar massProperties: PhysicsMassPropertiesThe physics body’s mass properties, like inertia and center of mass. By default, the mass properties value is ``PhysicsMassProperties/default``, which matches the properties of a unit sphere with mass of 1 kilogram.
set massProperties(value: PhysicsMassProperties)var massProperties: PhysicsMassPropertiesThe physics body’s mass properties, like inertia and center of mass. By default, the mass properties value is ``PhysicsMassProperties/default``, which matches the properties of a unit sphere with mass of 1 kilogram.
get isRotationLocked(): { "x": boolean; "y": boolean; "z": boolean }var isRotationLocked: (x: Bool, y: Bool, z: Bool)A tuple of Boolean values that you use to lock rotation of the physics body around any of the three axes. For any one of the three Booleans in the tuple that you set to `true`, rotation is restricted on the axis represented by that item. For example, if you set the `x` item to true, then the body can’t rotate around the x-axis. By default, rotation isn’t restricted.
set isRotationLocked(value: { "x": boolean; "y": boolean; "z": boolean })var isRotationLocked: (x: Bool, y: Bool, z: Bool)A tuple of Boolean values that you use to lock rotation of the physics body around any of the three axes. For any one of the three Booleans in the tuple that you set to `true`, rotation is restricted on the axis represented by that item. For example, if you set the `x` item to true, then the body can’t rotate around the x-axis. By default, rotation isn’t restricted.
get isAffectedByGravity(): booleanvar isAffectedByGravity: Bool { get set }A Boolean value that indicates whether gravity acts on dynamic rigid bodies.
set isAffectedByGravity(value: boolean)var isAffectedByGravity: Bool { get set }A Boolean value that indicates whether gravity acts on dynamic rigid bodies.
get isTranslationLocked(): { "x": boolean; "y": boolean; "z": boolean }var isTranslationLocked: (x: Bool, y: Bool, z: Bool)A tuple of Boolean values that you use to lock the position of the physics body along any of the three axes. You can restrict movement of the body along one or more axes by setting the corresponding item in the tuple to `true`. For example, if you set the `x` and the `z` items in the tuple to `true`, then the body can move only along the y-axis. By default, movement isn’t restricted.
set isTranslationLocked(value: { "x": boolean; "y": boolean; "z": boolean })var isTranslationLocked: (x: Bool, y: Bool, z: Bool)A tuple of Boolean values that you use to lock the position of the physics body along any of the three axes. You can restrict movement of the body along one or more axes by setting the corresponding item in the tuple to `true`. For example, if you set the `x` and the `z` items in the tuple to `true`, then the body can move only along the y-axis. By default, movement isn’t restricted.
get isContinuousCollisionDetectionEnabled(): booleanvar isContinuousCollisionDetectionEnabled: BoolA Boolean that controls whether the physics simulation performs continuous collision detection. Set the value to `true` to perform continuous collision detection. The value is `false` by default, indicating the simulation should apply discrete collision detection. Discrete collision detection considers only the position of a body once per rendered frame, or about every 16 milliseconds at 60 frames per second. Continuous collision detection considers the position of the body throughout the frame interval. The latter is more computationally expensive, but can help to avoid missing a collision for a quickly moving object, like a projectile.
set isContinuousCollisionDetectionEnabled(value: boolean)var isContinuousCollisionDetectionEnabled: BoolA Boolean that controls whether the physics simulation performs continuous collision detection. Set the value to `true` to perform continuous collision detection. The value is `false` by default, indicating the simulation should apply discrete collision detection. Discrete collision detection considers only the position of a body once per rendered frame, or about every 16 milliseconds at 60 frames per second. Continuous collision detection considers the position of the body throughout the frame interval. The latter is more computationally expensive, but can help to avoid missing a collision for a quickly moving object, like a projectile.
get mode(): PhysicsBodyModevar mode: PhysicsBodyModeThe behavioral mode that controls the way the physics body moves and interacts with other physics bodies in a simulation. The property's default value is ``PhysicsBodyMode/dynamic``, which means the physics body responds to forces and can collide with all other physics bodies in the simulation. - Important: Improve the performance of your app by applying `dynamic` mode to the physics bodies for just entities that need to interact with all other physics bodies, because each dynamic physics body can be computationally expensive. To configure the physics body so that an entity can move around the simulation without reacting to forces, set the property to ``PhysicsBodyMode/kinematic``. Apps typically use kinematic mode for entities the app programmatically controls, such as in response to a control or a person's interaction. For entities that don't need to move at all, set its physics body's mode to ``PhysicsBodyMode/static``. Physics bodies in `static` or `kinematic` mode can't collide with other physics bodies with either mode, by default. Optionally, you can add collision support for entities that have a physics body in either static or kinematic mode by adding a ``PhysicsSimulationComponent`` to an entity that's a common ancestor to the entities you want to collide. Then you can set ``PhysicsSimulationComponent/CollisionOptions`` to your preference. You can change the mode of an entity's physics body at any time, but changing it from `static` to another mode can affect your app's performance because the transition to a non-static mode can trigger the simulation to rebuild its state. - Tip: Set the mode of an entity's physics body to `static` if you know the entity doesn't ever need to move; otherwise, set the mode to `kinematic` or `dynamic`, even if the entity isn't currently moving.
set mode(value: PhysicsBodyMode)var mode: PhysicsBodyModeThe behavioral mode that controls the way the physics body moves and interacts with other physics bodies in a simulation. The property's default value is ``PhysicsBodyMode/dynamic``, which means the physics body responds to forces and can collide with all other physics bodies in the simulation. - Important: Improve the performance of your app by applying `dynamic` mode to the physics bodies for just entities that need to interact with all other physics bodies, because each dynamic physics body can be computationally expensive. To configure the physics body so that an entity can move around the simulation without reacting to forces, set the property to ``PhysicsBodyMode/kinematic``. Apps typically use kinematic mode for entities the app programmatically controls, such as in response to a control or a person's interaction. For entities that don't need to move at all, set its physics body's mode to ``PhysicsBodyMode/static``. Physics bodies in `static` or `kinematic` mode can't collide with other physics bodies with either mode, by default. Optionally, you can add collision support for entities that have a physics body in either static or kinematic mode by adding a ``PhysicsSimulationComponent`` to an entity that's a common ancestor to the entities you want to collide. Then you can set ``PhysicsSimulationComponent/CollisionOptions`` to your preference. You can change the mode of an entity's physics body at any time, but changing it from `static` to another mode can affect your app's performance because the transition to a non-static mode can trigger the simulation to rebuild its state. - Tip: Set the mode of an entity's physics body to `static` if you know the entity doesn't ever need to move; otherwise, set the mode to `kinematic` or `dynamic`, even if the entity isn't currently moving.
static initShapesMassMaterialMode(shapes: Array<ShapeResource>, mass: number, material?: (PhysicsMaterialResource) | null, mode?: PhysicsBodyMode): Promise<PhysicsBodyComponent>@MainActor @preconcurrency init(shapes: [ShapeResource], mass: Float, material: PhysicsMaterialResource? = nil, mode: PhysicsBodyMode = .dynamic)Creates a physics body component deriving mass properties from shape and mass. - Parameters: - shapes: The shape for which to estimate the rotational inertia and center of mass. - mass: The mass of the object in kilograms. - material: The material properties, like friction. - mode: The simulation mode that indicates how a body responds to forces.
static initShapesDensityMaterialMode(shapes: Array<ShapeResource>, density: number, material?: (PhysicsMaterialResource) | null, mode?: PhysicsBodyMode): Promise<PhysicsBodyComponent>@MainActor @preconcurrency init(shapes: [ShapeResource], density: Float, material: PhysicsMaterialResource? = nil, mode: PhysicsBodyMode = .dynamic)Creates a physics body component deriving mass properties from shape and density. - Parameters: - shapes: The shape for which to estimate the mass, rotational inertia, and center of mass. - density: The density of the object in kilograms per cubic meter. - material: The material properties, like friction. - mode: The simulation mode that indicates how a body responds to forces.
get material(): PhysicsMaterialResourcevar material: PhysicsMaterialResourceThe physics body’s material properties, like friction. By default, the body’s material resource is set to ``PhysicsMaterialResource/default``, which provides a modest amount of friction and restitution (bounciness).
set material(value: PhysicsMaterialResource)var material: PhysicsMaterialResourceThe physics body’s material properties, like friction. By default, the body’s material resource is set to ``PhysicsMaterialResource/default``, which provides a modest amount of friction and restitution (bounciness).
static init(): PhysicsBodyComponentinit()Creates a physics body component with default settings. For the default settings used in a new physics body component, see the discussions of the component’s individual properties.
No declarations were skipped in this snapshot.