Class Rigidbody

A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.

Hierarchy (view full)

Implements

Properties

angularDrag autoMass centerOfMass collisionDetectionMode constraints detectCollisions dominanceGroup drag gameObject guid isKinematic sleepThreshold sourceId? useGravity

Accessors

activeAndEnabled context destroyed enabled forward gravityScale hideFlags isSleeping layer lockPositionX lockPositionY lockPositionZ lockRotationX lockRotationY lockRotationZ mass name right scene smoothedVelocity static tag up worldEuler worldPosition worldQuaternion worldRotation

Methods

addEventListener applyForce applyImpulse awake beforePhysics destroy dispatchEvent earlyUpdate? getAngularVelocity getVelocity lateUpdate? onAfterRender? onBeforeRender? onBeforeXR? onCollisionEnter? onCollisionExit? onCollisionStay? onDestroy onDisable onEnable onEnterXR? onLeaveXR? onPausedChanged? onPointerClick? onPointerDown? onPointerEnter? onPointerExit? onPointerMove? onPointerUp? onTriggerEnter? onTriggerExit? onTriggerStay? onUpdateXR? onValidate onXRControllerAdded? onXRControllerRemoved? removeEventListener resetForces resetForcesAndTorques resetTorques resetVelocities resolveGuids? setAngularVelocity setBodyFromGameObject setForce setTorque setVelocity setWorldPosition setWorldQuaternion setWorldRotation start? startCoroutine stopCoroutine supportsXR? teleport update? updateProperties wakeUp

Properties

angularDrag

angularDrag: number = 1

Angular drag is a force that resists the rotation of the rigid-body. It is applied to the center-of-mass of the rigid-body.

Link

https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping

autoMass

autoMass: boolean = true

When true the mass will be automatically calculated by the attached colliders

centerOfMass

centerOfMass: Vector3 = ...

The center of mass is the point around which the mass of the rigid-body is evenly distributed. It is used to compute the torque applied to the rigid-body when forces are applied to it.

collisionDetectionMode

collisionDetectionMode: CollisionDetectionMode = CollisionDetectionMode.Discrete

Link

https://rapier.rs/docs/user_guides/javascript/rigid_bodies#continuous-collision-detection

constraints

constraints: RigidbodyConstraints = RigidbodyConstraints.None

Constraints are used to lock the position or rotation of an object in a specific axis.

detectCollisions

detectCollisions: boolean = true

Detect collisions is a flag that can be set to false to disable collision detection for a specific rigid-body.

dominanceGroup

dominanceGroup: number = 0

Rigidbodies with higher dominance will be immune to forces originating from contacts with rigidbodies of lower dominance.

Link

https://rapier.rs/docs/user_guides/javascript/rigid_bodies#dominance

drag

drag: number = 0

Drag is a force that resists the motion of the rigid-body. It is applied to the center-of-mass of the rigid-body.

Link

https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping

gameObject

gameObject: GameObject

the object this component is attached to. Note that this is a threejs Object3D with some additional features

guid

guid: string = "invalid"

the unique identifier for this component

isKinematic

isKinematic: boolean = false

IsKinematic is a flag that can be set to true to make a rigid-body kinematic. Kinematic rigid-bodies are not affected by forces and collisions. They are meant to be animated by the user.

sleepThreshold

sleepThreshold: number = 0.01

The sleeping threshold is the minimum velocity below which a dynamic rigid-body will be put to sleep by the physics engine.

Link

https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping

OptionalsourceId

sourceId?: string

holds the source identifier this object was created with/from (e.g. if it was part of a glTF file the sourceId holds the url to the glTF)

useGravity

useGravity: boolean = true

Use gravity is a flag that can be set to false to disable gravity for a specific rigid-body.

Accessors

activeAndEnabled

  • get activeAndEnabled(): boolean

  • Returns boolean

    true if the object is enabled and active in the hierarchy

context

  • get context(): Context

  • Use the context to get access to many Needle Engine features and use physics, timing, access the camera or scene

    Returns Context

  • set context(context): void

  • Parameters

    Returns void

destroyed

  • get destroyed(): boolean

  • Returns boolean

    true if this component was destroyed (this.destroy()) or the whole object this component was part of

enabled

  • get enabled(): boolean

  • Returns boolean

  • set enabled(val): void

  • Parameters

    • val: boolean

    Returns void

forward

  • get forward(): Vector3

  • Forward (0,0,-1) vector in world space

    Returns Vector3

gravityScale

  • get gravityScale(): number

  • Returns number

  • set gravityScale(val): void

  • Gravity is such a common force that it is implemented as a special case (even if it could easily be implemented by the user using force application). Note however that a change of gravity won't automatically wake-up the sleeping bodies so keep in mind that you may want to wake them up manually before a gravity change.

    It is possible to change the way gravity affects a specific rigid-body by setting the rigid-body's gravity scale to a value other than 1.0. The magnitude of the gravity applied to this body will be multiplied by this scaling factor. Therefore, a gravity scale set to 0.0 will disable gravity for the rigid-body whereas a gravity scale set to 2.0 will make it twice as strong. A negative value will flip the direction of the gravity for this rigid-body.

    Parameters

    • val: number

    Returns void

    Link

    https://rapier.rs/docs/user_guides/javascript/rigid_bodies#gravity

hideFlags

  • get hideFlags(): HideFlags

  • Returns HideFlags

isSleeping

  • get isSleeping(): undefined | boolean

  • Returns undefined | boolean

layer

  • get layer(): number

  • Returns number

    the layer of the gameObject this component is attached to

lockPositionX

lockPositionY

lockPositionZ

lockRotationX

lockRotationY

lockRotationZ

mass

  • get mass(): number

  • Returns number

  • set mass(value): void

  • By default the mass will be automatically calculated (see autoMass) by the physics engine using the collider sizes
    To set the mass manually you can either set the mass value or set autoMass to false

    Parameters

    • value: number

    Returns void

name

  • get name(): string

  • Returns string

    the name of the gameObject this component is attached to

  • set name(str): void

  • Parameters

    • str: string

    Returns void

right

  • get right(): Vector3

  • Right (1,0,0) vector in world space

    Returns Vector3

scene

  • get scene(): Scene

  • shorthand for this.context.scene

    Returns Scene

    the scene of the context

smoothedVelocity

  • get smoothedVelocity(): Vector3

  • Returns the rigidbody velocity smoothed over ~ 10 frames

    Returns Vector3

static

  • get static(): boolean

  • Is the gameObject marked as static

    Returns boolean

  • set static(value): void

  • Parameters

    • value: boolean

    Returns void

tag

  • get tag(): string

  • Returns string

    the tag of the gameObject this component is attached to

  • set tag(str): void

  • Parameters

    • str: string

    Returns void

up

  • get up(): Vector3

  • Up (0,1,0) vector in world space

    Returns Vector3

worldEuler

  • get worldEuler(): Euler

  • Returns Euler

  • set worldEuler(val): void

  • Parameters

    Returns void

worldPosition

  • get worldPosition(): Vector3

  • Returns Vector3

  • set worldPosition(val): void

  • Parameters

    Returns void

worldQuaternion

  • get worldQuaternion(): Quaternion

  • Returns Quaternion

  • set worldQuaternion(val): void

  • Parameters

    Returns void

worldRotation

  • get worldRotation(): Vector3

  • Returns Vector3

  • set worldRotation(val): void

  • Parameters

    Returns void

Methods

addEventListener

  • addEventListener<T>(type, listener): void

  • Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

    The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

    When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

    When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

    When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

    If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

    The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: ((evt: T) => any)
        • (evt): any

        • Parameters

          • evt: T

          Returns any

    Returns void

applyForce

applyImpulse

awake

  • awake(): void

  • called once when the component becomes active for the first time (once per component)
    This is the first callback to be called

    Returns void

beforePhysics

  • beforePhysics(): Generator<undefined, void, unknown>

  • Returns Generator<undefined, void, unknown>

destroy

dispatchEvent

  • dispatchEvent(evt): boolean

  • Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    MDN Reference

    Parameters

    Returns boolean

OptionalearlyUpdate

getAngularVelocity

getVelocity

OptionallateUpdate

OptionalonAfterRender

OptionalonBeforeRender

OptionalonBeforeXR

  • onBeforeXR(mode, args): void

  • Called before the XR session is requested. Use this callback if you want to modify the session init features

    Parameters

    • mode: XRSessionMode
    • args: XRSessionInit

    Returns void

OptionalonCollisionEnter

OptionalonCollisionExit

OptionalonCollisionStay

onDestroy

onDisable

  • onDisable(): void

  • called every time the component gets disabled or if a parent object (or this.gameObject) gets set to invisible

    Returns void

onEnable

  • onEnable(): void

  • called every time when the component gets enabled (this is invoked after awake and before start)
    or when it becomes active in the hierarchy (e.g. if a parent object or this.gameObject gets set to visible)

    Returns void

OptionalonEnterXR

  • onEnterXR(args): void

  • Callback when this component joins a xr session (or becomes active in a running XR session)

    Parameters

    Returns void

OptionalonLeaveXR

  • onLeaveXR(args): void

  • Callback when this component exists a xr session (or when it becomes inactive in a running XR session)

    Parameters

    Returns void

OptionalonPausedChanged

  • onPausedChanged(isPaused, wasPaused): void

  • Called for all scripts when the context gets paused or unpaused

    Parameters

    • isPaused: boolean
    • wasPaused: boolean

    Returns void

OptionalonPointerClick

  • onPointerClick(args): any

  • Called when an object (or any child object) is clicked (needs a EventSystem in the scene)

    Parameters

    Returns any

OptionalonPointerDown

OptionalonPointerEnter

  • onPointerEnter(args): any

  • Called when a pointer (mouse, touch, xr controller) starts pointing on/hovering an object (or a child object)

    Parameters

    Returns any

OptionalonPointerExit

  • onPointerExit(args): any

  • Called when a pointer (mouse, touch, xr controller) exists an object (it was hovering the object before but now it's not anymore)

    Parameters

    Returns any

OptionalonPointerMove

  • onPointerMove(args): any

  • Called when a pointer (mouse, touch, xr controller) is moving over an object (or a child object)

    Parameters

    Returns any

OptionalonPointerUp

  • onPointerUp(args): any

  • Called when a button is released (which was previously pressed in onPointerDown)

    Parameters

    Returns any

OptionalonTriggerEnter

OptionalonTriggerExit

OptionalonTriggerStay

OptionalonUpdateXR

onValidate

OptionalonXRControllerAdded

  • onXRControllerAdded(args): void

  • Callback when a controller is connected/added while in a XR session
    OR when the component joins a running XR session that has already connected controllers
    OR when the component becomes active during a running XR session that has already connected controllers

    Parameters

    Returns void

OptionalonXRControllerRemoved

removeEventListener

  • removeEventListener<T>(type, listener): void

  • Removes the event listener in target's event listener list with the same type, callback, and options.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: ((arg: T) => any)
        • (arg): any

        • Parameters

          • arg: T

          Returns any

    Returns void

resetForces

  • resetForces(wakeup?): void

  • Parameters

    • wakeup: boolean = true

    Returns void

resetForcesAndTorques

  • resetForcesAndTorques(): void

  • Returns void

resetTorques

  • resetTorques(wakeup?): void

  • Parameters

    • wakeup: boolean = true

    Returns void

resetVelocities

  • resetVelocities(): void

  • Returns void

OptionalresolveGuids

  • resolveGuids(guidsMap): void

  • called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them)

    Parameters

    • guidsMap: GuidsMap

    Returns void

setAngularVelocity

  • setAngularVelocity(x, wakeup?): any

  • Parameters

    • x: Vec3
    • Optionalwakeup: boolean

    Returns any

  • setAngularVelocity(x, y, z, wakeup?): any

  • Parameters

    • x: number
    • y: number
    • z: number
    • Optionalwakeup: boolean

    Returns any

setBodyFromGameObject

  • setBodyFromGameObject(_velocity?): void

  • d

    Parameters

    • _velocity: null | Vector3 | {
          x: number;
          y: number;
          z: number;
      } = null

    Returns void

    Deprecated

    not used anymore and will be removed in a future update

setForce

setTorque

  • setTorque(x): any

  • Set the angular velocity of a rigidbody (equivalent to calling setAngularVelocity)

    Parameters

    • x: Vec3

    Returns any

  • setTorque(x, y, z): any

  • Parameters

    • x: number
    • y: number
    • z: number

    Returns any

setVelocity

  • setVelocity(x, y?, z?, wakeup?): void

  • Parameters

    • x: number | Vector3
    • Optionaly: number
    • Optionalz: number
    • wakeup: boolean = true

    Returns void

setWorldPosition

setWorldQuaternion

  • setWorldQuaternion(x, y, z, w): void

  • Parameters

    • x: number
    • y: number
    • z: number
    • w: number

    Returns void

setWorldRotation

  • setWorldRotation(x, y, z, degrees?): void

  • Parameters

    • x: number
    • y: number
    • z: number
    • degrees: boolean = true

    Returns void

Optionalstart

  • start(): void

  • called at the beginning of a frame (once per component)

    Returns void

startCoroutine

  • startCoroutine(routine, evt?): Generator<unknown, any, unknown>

  • starts a coroutine (javascript generator function)
    yield will wait for the next frame:

    • Use yield WaitForSeconds(1) to wait for 1 second.
    • Use yield WaitForFrames(10) to wait for 10 frames.
    • Use yield new Promise(...) to wait for a promise to resolve.

    Parameters

    • routine: Generator<unknown, any, unknown>

      generator function to start

    • evt: FrameEvent = FrameEvent.Update

      event to register the coroutine for (default: FrameEvent.Update). Note that all coroutine FrameEvent callbacks are invoked after the matching regular component callbacks. For example FrameEvent.Update will be called after regular component update() methods)

    Returns Generator<unknown, any, unknown>

    the generator function (use it to stop the coroutine with stopCoroutine)

    Example

    onEnable() { this.startCoroutine(this.myCoroutine()); }
    private *myCoroutine() {
       while(this.activeAndEnabled) {
          console.log("Hello World", this.context.time.frame);
          // wait for 5 frames
          for(let i = 0; i < 5; i++) yield;
       }
    }

stopCoroutine

  • stopCoroutine(routine, evt?): void

  • Stop a coroutine that was previously started with startCoroutine

    Parameters

    • routine: Generator<unknown, any, unknown>

      the routine to be stopped

    • evt: FrameEvent = FrameEvent.Update

      the frame event to unregister the routine from (default: FrameEvent.Update)

    Returns void

OptionalsupportsXR

  • supportsXR(mode): boolean

  • Optional callback, you can implement this to only get callbacks for VR or AR sessions if necessary.

    Parameters

    • mode: XRSessionMode

    Returns boolean

    true if the mode is supported (if false the mode is not supported by this component and it will not receive XR callbacks for this mode)

teleport

  • teleport(pt, localspace?): void

  • Teleport the rigidbody to a new position in the world.
    Will reset forces before setting the object world position

    Parameters

    • pt: {
          x: number;
          y: number;
          z: number;
      }

      The new position to teleport the object to (world space)

      • x: number
      • y: number
      • z: number
    • localspace: boolean = true

      When true the object will be teleported in local space, otherwise in world space

    Returns void

Optionalupdate

  • update(): void

  • regular callback in a frame (called every frame when implemented)

    Returns void

updateProperties

  • updateProperties(): any

  • Call to force an update of the rigidbody properties in the physics engine

    Returns any

wakeUp

  • wakeUp(): void

  • When a dynamic rigid-body doesn't move (or moves very slowly) during a few seconds, it will be marked as sleeping by the physics pipeline. Rigid-bodies marked as sleeping are no longer simulated by the physics engine until they are woken up. That way the physics engine doesn't waste any computational resources simulating objects that don't actually move. They are woken up automatically whenever another non-sleeping rigid-body starts interacting with them (either with a joint, or with one of its attached colliders generating contacts).

    Returns void

    Link

    https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping

Settings

Member Visibility

On This Page

Properties
Accessors
Methods