xr-frame / Exports / Rigidbody

# Class: Rigidbody

刚体组件。

让物体在物理系统中成为一个有质量的刚体。只有添加了这个组件之后，物体才有可能在物理系统的物理模拟阶段发生位移和旋转。

# Hierarchy

Component<IRigidbodyData>

↳ Rigidbody

# Table of contents

# Events

# Properties

# Accessors

# Methods

# Events

# onAdd

▸ onAdd(parent, data): void

所挂载的element被挂载到场景时触发的回调。

# Parameters

Name	Type
`parent`	`Element`
`data`	`IRigidbodyData`

# Returns

void

# Inherited from

Component.onAdd

# onRelease

▸ onRelease(data): void

从被挂载的element上被移除，或是element被销毁时，触发的回调。一般用于释放持有的资源。

# Parameters

Name	Type
`data`	`IRigidbodyData`

# Returns

void

# Inherited from

Component.onRelease

# onRemove

▸ onRemove(parent, data): void

所挂载的element从父节点parent被移除时，或者自己从element上被移除时，触发的回调。一般用于消除功能的运作。 如果一个组件的元素直接被销毁了，那这个组件就不会经历onRemove而是直接进入onRelease。

# Parameters

Name	Type
`parent`	`Element`
`data`	`IRigidbodyData`

# Returns

void

# Inherited from

Component.onRemove

# onTick

▸ onTick(dateTime, data): void

渲染每帧触发的回调。

# Parameters

Name	Type
`dateTime`	`number`
`data`	`IRigidbodyData`

# Returns

void

# Inherited from

Component.onTick

# onUpdate

▸ onUpdate(data, preData): void

数据更新时触发的回调。

# Parameters

Name	Type
`data`	`IRigidbodyData`
`preData`	`IRigidbodyData`

# Returns

void

# Inherited from

Component.onUpdate

# Properties

# priority

• Readonly priority: number = 401

自定义组件的更新优先级。

# Overrides

Component.priority

# schema

• Readonly schema: IComponentSchema

自定义组件的schema。

# Overrides

Component.schema

# EVENTS

▪ Static EVENTS: string[] = []

# Inherited from

Component.EVENTS

# Accessors

# angularDamping

• get angularDamping(): number

角速度阻尼。影响物体的角速度。

limit angularDamping >= 0

default 0.05

# Returns

number

• set angularDamping(v): void

角速度阻尼。影响物体的角速度。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# angularVelocity

• get angularVelocity(): Vector3

刚体的角速度。

# Returns

Vector3

• set angularVelocity(v): void

刚体的角速度。

# Parameters

Name	Type
`v`	`Vector3`

# Returns

void

# centerOfMass

• get centerOfMass(): Vector3

刚体的质心相对于LocalTransform的偏移量。如果不手动设置这一项，会自动根据刚体附着的轮廓来计算质心。

see resetCenterOfMass

# Returns

Vector3

• set centerOfMass(v): void

刚体的质心相对于LocalTransform的偏移量。如果不手动设置这一项，会自动根据刚体附着的轮廓来计算质心。

# Parameters

Name	Type
`v`	`Vector3`

# Returns

void

# collisionDetectionMode

• get collisionDetectionMode(): CollisionDetectionMode

设置刚体的碰撞检测模式。详见{@link CollisionDetectionMode}。

default {@link CollisionDetectionMode.Discrete}

# Returns

CollisionDetectionMode

• set collisionDetectionMode(v): void

设置刚体的碰撞检测模式。详见{@link CollisionDetectionMode}。

# Parameters

Name	Type
`v`	`CollisionDetectionMode`

# Returns

void

# detectCollisions

• get detectCollisions(): boolean

unimplemented

default true

# Returns

boolean

• set detectCollisions(v): void

# Parameters

Name	Type
`v`	`boolean`

# Returns

void

# el

• get el(): Element

挂载的元素。

# Returns

Element

# freezeRotation

• get freezeRotation(): boolean

是否允许物理模拟过程中对刚体进行旋转。

default true

# Returns

boolean

• set freezeRotation(v): void

是否允许物理模拟过程中对刚体进行旋转。

# Parameters

Name	Type
`v`	`boolean`

# Returns

void

# inertiaTensor

• get inertiaTensor(): number

刚体的转动惯量。如果不手动设置的话，会自动根据刚体上附着的轮廓计算得出。

see resetInertiaTensor

# Returns

number

• set inertiaTensor(v): void

刚体的转动惯量。如果不手动设置的话，会自动根据刚体上附着的轮廓计算得出。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# isKinematic

• get isKinematic(): boolean

是否为运动学(Kinematic) 刚体。设置为运动学刚体后，除非手动调用movePosition，否则物体不会在物理模拟阶段发生位移或旋转。可以理解为，刚体的行为完全在用户的控制之下。

default false

# Returns

boolean

• set isKinematic(v): void

# Parameters

Name	Type
`v`	`boolean`

# Returns

void

# linearDamping

• get linearDamping(): number

线性阻尼。影响物体的线性速度。

limit linearDamping >= 0

default 0

# Returns

number

• set linearDamping(v): void

线性阻尼。影响物体的线性速度。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# mass

• get mass(): number

刚体的质量。

limit mass > 0

default 1

# Returns

number

• set mass(v): void

刚体的质量。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# maxAngularVelocity

• get maxAngularVelocity(): number

最大角速度（弧度）。

default 7

# Returns

number

• set maxAngularVelocity(v): void

最大角速度（弧度）。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# maxDepenetrationVelocity

• get maxDepenetrationVelocity(): number

最大分离速度。 物理模拟解决碰撞（相交）的过程中，最大能允许的分离速度。

default Infinity

# Returns

number

• set maxDepenetrationVelocity(v): void

最大分离速度。 物理模拟解决碰撞（相交）的过程中，最大能允许的分离速度。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# position

• get position(): Vector3

直接获取或修改刚体在物理系统中的位置。物理系统中的位置是独立于Transform组件的。

*如果你不清楚修改这一项的后果，请不要手动修改它。修改Transform.position来代替。

# Returns

Vector3

• set position(v): void

直接获取或修改刚体在物理系统中的位置。物理系统中的位置是独立于Transform组件的。

*如果你不清楚修改这一项的后果，请不要手动修改它。修改Transform.position来代替。

# Parameters

Name	Type
`v`	`Vector3`

# Returns

void

# positionConstraints

• get positionConstraints(): boolean[]

限制物体的位移（X轴，Y轴，Z轴）。

default [false, false, false]

# Returns

boolean[]

• set positionConstraints(v): void

限制物体的位移（X轴，Y轴，Z轴）。

# Parameters

Name	Type
`v`	`boolean`[]

# Returns

void

# rotation

• get rotation(): Quaternion

直接获取或修改刚体在物理系统中的旋转（以四元数表示）。物理系统中的旋转是独立于节点系统中的Transform的，详见{@link //TODO}。

*如果你不清楚修改这一项的后果，请不要手动修改它。修改{@link Transform3D.euler}或{@link Transform3D.quaternion}来代替。

# Returns

Quaternion

• set rotation(v): void

直接获取或修改刚体在物理系统中的旋转（以四元数表示）。物理系统中的旋转是独立于节点系统中的Transform的，详见{@link //TODO}。

*如果你不清楚修改这一项的后果，请不要手动修改它。修改{@link Transform3D.euler}或{@link Transform3D.quaternion}来代替。

# Parameters

Name	Type
`v`	`Quaternion`

# Returns

void

# rotationConstraints

• get rotationConstraints(): boolean[]

限制物体的旋转（X轴，Y轴，Z轴）。

default [false, false, false]

# Returns

boolean[]

• set rotationConstraints(v): void

限制物体的旋转（X轴，Y轴，Z轴）。

# Parameters

Name	Type
`v`	`boolean`[]

# Returns

void

# scene

• get scene(): Scene

当前场景。

# Returns

Scene

# sleepThreshold

• get sleepThreshold(): number

设置刚体进入休眠的动能阈值。

default 0.005

# Returns

number

• set sleepThreshold(v): void

设置刚体进入休眠的动能阈值。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# solverIterations

• get solverIterations(): number

设置物理模拟过程中解决碰撞的迭代次数。更高的迭代次数，会消耗更多性能，产生更自然的物理碰撞效果。如果发现静息状态的刚体（比如说放在地面上），会发生抖动，可以考虑提高这项数值。

limit solverIterations > 0

default 6

# Returns

number

• set solverIterations(v): void

# Parameters

Name	Type
`v`	`number`

# Returns

void

# solverVelocityIterations

• get solverVelocityIterations(): number

设置物理模拟过程中计算碰撞后速度的迭代次数。更高的迭代次数，会消耗更多性能，产生更准确的分离速度。

limit solverVelocityIterations > 0

default 1

# Returns

number

• set solverVelocityIterations(v): void

设置物理模拟过程中计算碰撞后速度的迭代次数。更高的迭代次数，会消耗更多性能，产生更准确的分离速度。

# Parameters

Name	Type
`v`	`number`

# Returns

void

# useGravity

• get useGravity(): boolean

刚体是否受重力影响。

default true

# Returns

boolean

• set useGravity(v): void

刚体是否受重力影响。

# Parameters

Name	Type
`v`	`boolean`

# Returns

void

# velocity

• get velocity(): Vector3

刚体的线性速度。

*修改这一项会造成速度突变，一般情况下可以使用addForce来代替。

# Returns

Vector3

• set velocity(v): void

刚体的线性速度。

*修改这一项会造成速度突变，一般情况下可以使用addForce来代替。

# Parameters

Name	Type
`v`	`Vector3`

# Returns

void

# version

• get version(): number

当前版本，每次有数据更新都会增加，可以用作和其他组件合作的依据。

# Returns

number

# Methods

# AddExplosionForce

▸ AddExplosionForce(explosionForce, explosionPosition, explosionRadius, upwardsModifier, mode): void

生成一次模拟爆炸的力。爆炸范围可以视作一个球状物体，如果球体和刚体产生相交，则会在刚体上产生推力。推力的大小和相交点与球心的距离有关，推力的方向从球心指向相交点，推力作用位于相交点。

视刚体有无附着的轮廓，分为两种情况：

无轮廓（或爆炸球心在刚体轮廓内）相交的判定使用刚体的质心；相交点也取刚体的质心。
有轮廓相交的判定使用刚体的所有轮廓；相交点取轮廓距离球心最近的那一点。

limit explosionForce > 0

# Parameters

Name	Type	Description
`explosionForce`	`number`	爆炸力的大小。
`explosionPosition`	`Vector3`	爆炸球体的球心位置。
`explosionRadius`	`number`	爆炸球体的半径。
`upwardsModifier`	`number`	使用相对数值来修改推力的作用位置的y坐标。
`mode`	`ForceMode`	力的类型。

# Returns

void

# AddForceAtPosition

▸ AddForceAtPosition(force, position, mode): void

为刚体施加力，会影响刚体的线性速度和角速度。

# Parameters

Name	Type	Description
`force`	`Vector3`	世界坐标下矢量形式的力，作用在position位置上。
`position`	`Vector3`	力的作用位置。
`mode`	`ForceMode`	力的类型。

# Returns

void

# addForce

▸ addForce(force, mode): void

为刚体施加力，会影响刚体的线性速度。

# Parameters

Name	Type	Description
`force`	`Vector3`	世界坐标下矢量形式的力，作用在物体质心上。
`mode`	`ForceMode`	力的类型。

# Returns

void

# addRelativeForce

▸ addRelativeForce(force, mode): void

为刚体施加力，会影响刚体的线性速度。

# Parameters

Name	Type	Description
`force`	`Vector3`	局部坐标下矢量形式的力，作用在物体质心上。
`mode`	`ForceMode`	力的类型。

# Returns

void

# addRelativeTorque

▸ addRelativeTorque(torque, mode): void

为刚体施加力矩，会影响刚体的角速度。

# Parameters

Name	Type	Description
`torque`	`Vector3`	局部坐标下矢量形式的力矩。
`mode`	`ForceMode`	力矩的类型。

# Returns

void

# addTorque

▸ addTorque(torque, mode): void

为刚体施加力矩，会影响刚体的角速度。

# Parameters

Name	Type	Description
`torque`	`Vector3`	世界坐标下矢量形式的力矩。
`mode`	`ForceMode`	力矩的类型。

# Returns

void

# applyData

▸ applyData(data): void

# Parameters

Name	Type
`data`	`IRigidbodyData`

# Returns

void

# closestPointOnBounds

▸ closestPointOnBounds(position): Vector3

测试刚体表面上距离某点最近的位置。如果给予的position在刚体内部，会返回position。如果刚体无附着的轮廓，会返回[Infinity, Infinity, Infinity]。

# Parameters

Name	Type
`position`	`Vector3`

# Returns

Vector3

# disable

▸ disable(): void

# Returns

void

# enable

▸ enable(): void

# Returns

void

# getData

▸ getData<T>(key): IRigidbodyData[T]

获取一个当前值。

# Type parameters

Name	Type
`T`	extends keyof `IRigidbodyData`

# Parameters

Name	Type
`key`	`T`

# Returns

IRigidbodyData[T]

# Inherited from

Component.getData

# getPointVelocity

▸ getPointVelocity(worldPoint): Vector3

获取刚体内某一点在世界坐标下的速度。

# Parameters

Name	Type	Description
`worldPoint`	`Vector3`	世界坐标下的位置（其实在刚体外也可以）。

# Returns

Vector3

# getRelativePointVelocity

▸ getRelativePointVelocity(relativePoint): Vector3

获取刚体内某一点在局部坐标下的速度。

# Parameters

Name	Type	Description
`relativePoint`	`Vector3`	局部坐标下的位置（其实在刚体外也可以）。

# Returns

Vector3

# getWorldCenterOfMass

▸ getWorldCenterOfMass(): Vector3

# Returns

Vector3

刚体质心在世界坐标中的位置。

# isSleeping

▸ isSleeping(): boolean

see sleep

# Returns

boolean

刚体是否处于休眠状态。

# movePosition

▸ movePosition(position): void

对于非运动学刚体来说，等于直接修改position；对于运动学刚体来说，位置变化会在下一帧生效。可以视作物体在这一帧的物理模拟中沿直线路径移动到了目的地。

see isKinematic

# Parameters

Name	Type	Description
`position`	`Vector3`	位移的终点

# Returns

void

# moveRotation

▸ moveRotation(rotation): void

unimplemented 暂未支持，请使用rotation属性或{@link Transform3D.quaternion}代替。

# Parameters

Name	Type
`rotation`	`Quaternion`

# Returns

void

# resetCenterOfMass

▸ resetCenterOfMass(): void

手动触发，根据刚体附着的轮廓重新计算刚体的质心。

see centerOfMass

# Returns

void

# resetInertiaTensor

▸ resetInertiaTensor(): void

手动触发，根据刚体附着的轮廓重新计算刚体的转动惯量。

see inertiaTensor

# Returns

void

# setData

▸ setData(data): void

不通过xml而是直接设置data，注意值的类型需要和schema中一致。

# Parameters

Name	Type
`data`	`Partial`<`IRigidbodyData`>

# Returns

void

# Inherited from

Component.setData

# setDataOne

▸ setDataOne<T>(key, value): void

设置一个数据。

# Type parameters

Name	Type
`T`	extends keyof `IRigidbodyData`

# Parameters

Name	Type
`key`	`T`
`value`	`IRigidbodyData`[`T`]

# Returns

void

# Inherited from

Component.setDataOne

# setDensity

▸ setDensity(density): void

根据给定的密度和刚体附着的轮廓，来计算刚体的质量。

see mass

# Parameters

Name	Type
`density`	`number`

# Returns

void

# sleep

▸ sleep(): void

强迫刚体进入休眠状态（至少一帧），休眠状态详见{@link //todo}。 *如果下一帧发生碰撞则会立刻醒来。

# Returns

void

# wakeUp

▸ wakeUp(): void

强制唤醒刚体（离开休眠状态）。

see sleep

# Returns

void