VRTK_RotateTransformGrabAttach

extends VRTK_BaseGrabAttach

Overview

Rotates the Transform of the Interactable Object around a specified transform local axis within the given limits.

To allow unrestricted movement, set the angle limits minimum to -infinity and the angle limits maximum to infinity.

Script Usage:

• Place the VRTK_RotateTransformGrabAttach script on either:
  • The GameObject of the Interactable Object to detect interactions on.
  • Any other scene GameObject and then link that GameObject to the Interactable Objects Grab Attach Mechanic Script parameter to denote use of the grab mechanic.

Inspector Parameters

• Detach Distance: The maximum distance the grabbing object is away from the Interactable Object before it is automatically dropped.
• Origin Deadzone: The distance between grabbing object and the centre of Interactable Object that is considered to be non grabbable. If the grabbing object is within the Origin Deadzone distance then it will be automatically ungrabbed.
• Rotate Around: The local axis in which to rotate the object around.
• Rotation Action: Determines how the rotation of the object is calculated based on the action of the grabbing object.
• Rotation Friction: The amount of friction to apply when rotating, simulates a tougher rotation.
• Release Deceleration Damper: The damper in which to slow the Interactable Object's rotation down when released to simulate continued momentum. The higher the number, the faster the Interactable Object will come to a complete stop on release.
• Reset To Orign On Release Speed: The speed in which the Interactable Object returns to it's origin rotation when released. If the Reset To Orign On Release Speed is 0f then the rotation will not be reset.
• Angle Limits: The negative and positive limits the axis can be rotated to.
• Min Max Threshold: The threshold the rotation value needs to be within to register a min or max rotation value.
• Min Max Normalized Threshold: The threshold the normalized rotation value needs to be within to register a min or max normalized rotation value.

Class Variables

• public enum RotationAxis - The local axis for rotation.
  • xAxis - The local X Axis of the transform.
  • yAxis - The local Y Axis of the transform.
  • zAxis - The local Z Axis of the transform.
• public enum RotationType - The way in which rotation from the grabbing object is applied.
  • FollowAttachPoint - The angle between the Interactable Object origin and the grabbing object attach point.
  • FollowLongitudinalAxis - The angular velocity across the grabbing object's longitudinal axis (the roll axis).
  • FollowLateralAxis - The angular velocity across the grabbing object's lateral axis (the pitch axis).
  • FollowPerpendicularAxis - The angular velocity across the grabbing object's perpendicular axis (the yaw axis).
• public Quaternion originRotation - The default local rotation of the Interactable Object.

Class Events

• AngleChanged - Emitted when the angle changes.
• MinAngleReached - Emitted when the angle reaches the minimum angle.
• MinAngleExited - Emitted when the angle exits the minimum angle state.
• MaxAngleReached - Emitted when the angle reaches the maximum angle.
• MaxAngleExited - Emitted when the angle exits the maximum angle state.

Unity Events

Adding the VRTK_RotateTransformGrabAttach_UnityEvents component to VRTK_RotateTransformGrabAttach 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 interactingObject - The GameObject that is performing the interaction (e.g. a controller).
• float currentAngle - The current angle the Interactable Object is rotated to.
• float normalizedAngle - The normalized angle (between 0f and 1f) the Interactable Object is rotated to.
• Vector3 rotationSpeed - The speed in which the rotation is occuring.

Class Methods

StartGrab/3

public override bool StartGrab(GameObject grabbingObject, GameObject givenGrabbedObject, Rigidbody givenControllerAttachPoint)

• Parameters
  • GameObject grabbingObject - The GameObject that is doing the grabbing.
  • GameObject givenGrabbedObject - The GameObject that is being grabbed.
  • Rigidbody givenControllerAttachPoint - The point on the grabbing object that the grabbed object should be attached to after grab occurs.
• Returns
  • bool - Returns true if the grab is successful, false if the grab is unsuccessful.

The StartGrab method sets up the grab attach mechanic as soon as an Interactable Object is grabbed.

StopGrab/1

public override void StopGrab(bool applyGrabbingObjectVelocity)

• Parameters
  • bool applyGrabbingObjectVelocity - If true will apply the current velocity of the grabbing object to the grabbed object on release.
• Returns
  • none

The StopGrab method ends the grab of the current Interactable Object and cleans up the state.

ProcessUpdate/0

public override void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method is run in every Update method on the Interactable Object.

SetRotation/2

public virtual void SetRotation(float newAngle, float transitionTime = 0f)

• Parameters
  • float newAngle - The angle to rotate to through the current rotation axis.
  • float transitionTime - The time in which the entire rotation operation will take place.
• Returns
  • none

The SetRotation method sets the rotation on the Interactable Object to the given angle over the desired time.

ResetRotation/1

public virtual void ResetRotation(bool ignoreTransition = false)

• Parameters
  • bool ignoreTransition - If this is true then the Reset To Origin On Release Speed will be ignored and the reset will occur instantly.
• Returns
  • none

The ResetRotation method will rotate the Interactable Object back to the origin rotation.

GetAngle/0

public virtual float GetAngle()

• Parameters
  • none
• Returns
  • float - The current rotated angle.

The GetAngle method returns the current angle the Interactable Object is rotated to.

GetNormalizedAngle/0

public virtual float GetNormalizedAngle()

• Parameters
  • none
• Returns
  • float - The normalized rotated angle. Will return 0f if either limit is set to infinity.

The GetNormalizedAngle returns the normalized current angle between the minimum and maximum angle limits.

GetRotationSpeed/0

public virtual Vector3 GetRotationSpeed()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 containing the speed each axis is rotating in.

The GetRotationSpeed returns the current speed in which the Interactable Object is rotating.