VRTK_BodyPhysics

extends VRTK_DestinationMarker

Overview

Allows the play area to be affected by physics and detect collisions with other valid geometry.

Optional Components:

• VRTK_BasicTeleport - A Teleporter script to use when snapping the play area to the nearest floor when releasing from grab.

Script Usage:

• Place the VRTK_BodyPhysics script on any active scene GameObject.

Inspector Parameters

• Enable Body Collisions: If checked then the body collider and rigidbody will be used to check for rigidbody collisions.
• Ignore Grabbed Collisions: If this is checked then any items that are grabbed with the controller will not collide with the body collider. This is very useful if the user is required to grab and wield objects because if the collider was active they would bounce off the collider.
• Ignore Collisions With: An array of GameObjects that will not collide with the body collider.
• Headset Y Offset: The collider which is created for the user is set at a height from the user's headset position. If the collider is required to be lower to allow for room between the play area collider and the headset then this offset value will shorten the height of the generated collider.
• Movement Threshold: The amount of movement of the headset between the headset's current position and the current standing position to determine if the user is walking in play space and to ignore the body physics collisions if the movement delta is above this threshold.
• Play Area Movement Threshold: The amount of movement of the play area between the play area's current position and the previous position to determine if the user is moving play space.
• Standing History Samples: The maximum number of samples to collect of headset position before determining if the current standing position within the play space has changed.
• Lean Y Threshold: The y distance between the headset and the object being leaned over, if object being leaned over is taller than this threshold then the current standing position won't be updated.
• Step Up Y Offset: The maximum height to consider when checking if an object can be stepped upon to.
• Step Thickness Multiplier: The width/depth of the foot collider in relation to the radius of the body collider.
• Step Drop Threshold: The distance between the current play area Y position and the new stepped up Y position to consider a valid step up. A higher number can help with juddering on slopes or small increases in collider heights.
• Custom Raycast: A custom raycaster to use when raycasting to find floors.
• Fall Restriction: A check to see if the drop to nearest floor should take place. If the selected restrictor is still over the current floor then the drop to nearest floor will not occur. Works well for being able to lean over ledges and look down. Only works for falling down not teleporting up.
• Gravity Fall Y Threshold: When the y distance between the floor and the headset exceeds this distance and Enable Body Collisions is true then the rigidbody gravity will be used instead of teleport to drop to nearest floor.
• Blink Y Threshold: The y distance between the floor and the headset that must change before a fade transition is initiated. If the new user location is at a higher distance than the threshold then the headset blink transition will activate on teleport. If the new user location is within the threshold then no blink transition will happen, which is useful for walking up slopes, meshes and terrains to prevent constant blinking.
• Floor Height Tolerance: The amount the y position needs to change by between the current floor y position and the previous floor y position before a change in floor height is considered to have occurred. A higher value here will mean that a Drop To Floor will be less likely to happen if the y of the floor beneath the user hasn't changed as much as the given threshold.
• Fall Check Precision: The amount of rounding on the play area Y position to be applied when checking if falling is occuring.
• Teleporter: The VRTK Teleport script to use when snapping to floor. If this is left blank then a Teleport script will need to be applied to the same GameObject.
• Custom Play Area Rigidbody: A custom Rigidbody to apply to the play area. If one is not provided, then if an existing rigidbody is found on the play area GameObject it will be used, otherwise a default one will be created.
• Custom Body Collider Container: A GameObject to represent a custom body collider container. It should contain a collider component that will be used for detecting body collisions. If one isn't provided then it will be auto generated.
• Custom Foot Collider Container: A GameObject to represent a custom foot collider container. It should contain a collider component that will be used for detecting step collisions. If one isn't provided then it will be auto generated.

Class Variables

• public enum FallingRestrictors - Options for testing if a play space fall is valid
  • NoRestriction - Always drop to nearest floor when the headset is no longer over the current standing object.
  • LeftController - Don't drop to nearest floor if the Left Controller is still over the current standing object even if the headset isn't.
  • RightController - Don't drop to nearest floor if the Right Controller is still over the current standing object even if the headset isn't.
  • EitherController - Don't drop to nearest floor if Either Controller is still over the current standing object even if the headset isn't.
  • BothControllers - Don't drop to nearest floor only if Both Controllers are still over the current standing object even if the headset isn't.
  • AlwaysRestrict - Never drop to nearest floor when the headset is no longer over the current standing object.

Class Events

• StartFalling - Emitted when a fall begins.
• StopFalling - Emitted when a fall ends.
• StartMoving - Emitted when movement in the play area begins.
• StopMoving - Emitted when movement in the play area ends.
• StartColliding - Emitted when the body collider starts colliding with another game object.
• StopColliding - Emitted when the body collider stops colliding with another game object.
• StartLeaning - Emitted when the body collider starts leaning over another game object.
• StopLeaning - Emitted when the body collider stops leaning over another game object.
• StartTouchingGround - Emitted when the body collider starts touching the ground.
• StopTouchingGround - Emitted when the body collider stops touching the ground.

Unity Events

Adding the VRTK_BodyPhysics_UnityEvents component to VRTK_BodyPhysics object allows access to UnityEvents that will react identically to the Class Events.

• All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Event Payload

• GameObject target - The target GameObject the event is dealing with.
• Collider collider - An optional collider that the body physics is colliding with.

Class Methods

ArePhysicsEnabled/0

public virtual bool ArePhysicsEnabled()

• Parameters
  • none
• Returns
  • bool - Returns true if the body physics will interact with other scene physics objects and false if the body physics will ignore other scene physics objects.

The ArePhysicsEnabled method determines whether the body physics are set to interact with other scene physics objects.

ApplyBodyVelocity/3

public virtual void ApplyBodyVelocity(Vector3 velocity, bool forcePhysicsOn = false, bool applyMomentum = false)

• Parameters
  • Vector3 velocity - The velocity to apply.
  • bool forcePhysicsOn - If true will toggle the body collision physics back on if enable body collisions is true.
  • bool applyMomentum - If true then the existing momentum of the play area will be applied as a force to the resulting velocity.
• Returns
  • none

The ApplyBodyVelocity method applies a given velocity to the rigidbody attached to the body physics.

ToggleOnGround/1

public virtual void ToggleOnGround(bool state)

• Parameters
  • bool state - If true then body physics are set to being on the ground.
• Returns
  • none

The ToggleOnGround method sets whether the body is considered on the ground or not.

TogglePreventSnapToFloor/1

public virtual void TogglePreventSnapToFloor(bool state)

• Parameters
  • bool state - If true the the snap to floor mechanic will not execute.
• Returns
  • none

The PreventSnapToFloor method sets whether the snap to floor mechanic should be used.

ForceSnapToFloor/0

public virtual void ForceSnapToFloor()

• Parameters
  • none
• Returns
  • none

The ForceSnapToFloor method disables the prevent snap to floor and forces the snap to nearest floor action.

IsFalling/0

public virtual bool IsFalling()

• Parameters
  • none
• Returns
  • bool - Returns true if the body is currently falling via gravity or via teleport.

The IsFalling method returns the falling state of the body.

IsMoving/0

public virtual bool IsMoving()

• Parameters
  • none
• Returns
  • bool - Returns true if the user is currently walking around their play area space.

The IsMoving method returns the moving within play area state of the body.

IsLeaning/0

public virtual bool IsLeaning()

• Parameters
  • none
• Returns
  • bool - Returns true if the user is considered to be leaning over an object.

The IsLeaning method returns the leaning state of the user.

OnGround/0

public virtual bool OnGround()

• Parameters
  • none
• Returns
  • bool - Returns true if the play area is on the ground and false if the play area is in the air.

The OnGround method returns whether the user is currently standing on the ground or not.

GetVelocity/0

public virtual Vector3 GetVelocity()

• Parameters
  • none
• Returns
  • Vector3 - The velocity of the body physics rigidbody.

The GetVelocity method returns the velocity of the body physics rigidbody.

GetAngularVelocity/0

public virtual Vector3 GetAngularVelocity()

• Parameters
  • none
• Returns
  • Vector3 - The angular velocity of the body physics rigidbody.

The GetAngularVelocity method returns the angular velocity of the body physics rigidbody.

ResetVelocities/0

public virtual void ResetVelocities()

• Parameters
  • none
• Returns
  • none

The ResetVelocities method sets the rigidbody velocity and angular velocity to zero to stop the Play Area rigidbody from continuing to move if it has a velocity already.

ResetFalling/0

public virtual void ResetFalling()

• Parameters
  • none
• Returns
  • none

The ResetFalling method force stops any falling states and conditions that might be set on this object.

GetBodyColliderContainer/0

public virtual GameObject GetBodyColliderContainer()

• Parameters
  • none
• Returns
  • GameObject - The auto generated body collider GameObject.
  • GameObject -

The GetBodyColliderContainer method returns the auto generated GameObject that contains the body colliders.

GetFootColliderContainer/0

public virtual GameObject GetFootColliderContainer()

• Parameters
  • none
• Returns
  • GameObject - The auto generated foot collider GameObject.
  • GameObject -

The GetFootColliderContainer method returns the auto generated GameObject that contains the foot colliders.

GetCurrentCollidingObject/0

public virtual GameObject GetCurrentCollidingObject()

• Parameters
  • none
• Returns
  • GameObject - The GameObject that is colliding with the body physics colliders.

The GetCurrentCollidingObject method returns the object that the body physics colliders are currently colliding with.

ResetIgnoredCollisions/0

public virtual void ResetIgnoredCollisions()

• Parameters
  • none
• Returns
  • none

The ResetIgnoredCollisions method is used to clear any stored ignored colliders in case the Ignore Collisions On array parameter is changed at runtime. This needs to be called manually if changes are made at runtime.

SweepCollision/2

public virtual bool SweepCollision(Vector3 direction, float maxDistance)

• Parameters
  • Vector3 direction - The direction to test for the potential collision.
  • float maxDistance - The maximum distance to check for a potential collision.
• Returns
  • bool - Returns true if a collision will occur on the given direction over the given maxium distance. Returns false if there is no collision about to happen.

The SweepCollision method tests to see if a collision will occur with the body collider in a given direction and distance.

Example

VRTK/Examples/017_CameraRig_TouchpadWalking has a collection of walls and slopes that can be traversed by the user with the touchpad but the user cannot pass through the objects as they are collidable and the rigidbody physics won't allow the intersection to occur.