The LocomotionTeleport class controls and centralizes functionality for the various types of teleports. The system is designed to work as a set of components that are each responsible for different aspects of the teleport process. This makes it possible for different kinds of teleport behaviors to be occur by simply enabling different combinations of components. More...
Classes | |
| class | AimData |
| The AimData contains data provided by the Aim Handler which represents the final set of points that were used for aiming the teleport. This is provided to the AimVisual for rendering an aim effect. Note that the set of points provided here can be different from the points used by the Aim Handler to determine the teleport destination. For instance, the aim handler might use a very long line segment for an aim laser but would provide a shorter line segment in the AimData representing the line from the player to the teleport destination. More... | |
Public Types | |
| enum | States { States.Ready, States.Aim, States.CancelAim, States.PreTeleport, States.CancelTeleport, States.Teleporting, States.PostTeleport } |
| The process of teleporting is represented by a simple state machine, and each of the possible states are represented by this enum. More... | |
| enum | TeleportIntentions { TeleportIntentions.None, TeleportIntentions.Aim, TeleportIntentions.PreTeleport, TeleportIntentions.Teleport } |
| TeleportIntentions track what the TeleportState should attempt to transition to. More... | |
| enum | AimCollisionTypes { AimCollisionTypes.Point, AimCollisionTypes.Sphere, AimCollisionTypes.Capsule } |
| The aiming system uses a common function for testing collision with the world, which can be configured to use different shapes for testing. More... | |
Public Member Functions | |
| void | EnableMovement (bool ready, bool aim, bool pre, bool post) |
| Helper function to enable linear movement during the various teleport states. Movement may not be desired at all states, for instance during aiming it may be preferred to prevent movement to allow a thumbstick to be used for choosing the landing orientation. More... | |
| void | EnableRotation (bool ready, bool aim, bool pre, bool post) |
| Helper function to enable rotation movement during the various teleport states. Rotation may not be desired at all states, for instance during aiming it may be preferred to prevent rotation (snap turn or linear) to prevent the camera from being rotated while preparing to teleport. More... | |
| void | OnUpdateTeleportDestination (bool isValidDestination, Vector3? position, Quaternion? rotation, Quaternion? landingRotation) |
| When the active aim and orientation handler finishes preparing the data for the teleport destination, this method will be called in order to raise the UpdateTeleportDestination event, which will in turn give any active teleport destination objects an opportunity to update their visual state accordingly. More... | |
| bool | AimCollisionTest (Vector3 start, Vector3 end, LayerMask aimCollisionLayerMask, out RaycastHit hitInfo) |
| AimCollisionTest is used by many of the aim handlers to standardize the testing of aiming beams. By choosing between the increasingly restrictive point, sphere and capsule tests, the aiming system can limit targeting to routes which are not physically blocked. For example, a sphere test is good for ensuring the player can't teleport through bars to get out of a jail cell. More... | |
| void | RecycleTeleportDestination (TeleportDestination oldDestination) |
| virtual void | OnEnable () |
| Start the state machine coroutines. More... | |
| virtual void | OnDisable () |
| void | OnUpdateAimData (AimData aimData) |
| The target handler will call this method when the aim data has been updated and is ready to be processed by anything that needs to be aware of any changes. This generally includes a visual indicator for the aiming and the active orientation handler. More... | |
| void | DoTeleport () |
| Perform the actual teleport. Note that warp transitions do not call this function and instead moves the game object during the transition time time. More... | |
| Vector3 | GetCharacterPosition () |
| Convenience method for finding the character's position. More... | |
| Quaternion | GetHeadRotationY () |
| Return a quaternion for the Y axis of the HMD's orientation. Used by orientation handlers to track the current heading before processing user input to adjust it. More... | |
| void | DoWarp (Vector3 startPos, float positionPercent) |
| Warp just the position towards the destination. More... | |
Public Attributes | |
| bool | EnableMovementDuringReady = true |
| Allow linear movement prior to the teleport system being activated. More... | |
| bool | EnableMovementDuringAim = true |
| Allow linear movement while the teleport system is in the process of aiming for a teleport target. More... | |
| bool | EnableMovementDuringPreTeleport = true |
| Allow linear movement while the teleport system is in the process of configuring the landing orientation. More... | |
| bool | EnableMovementDuringPostTeleport = true |
| Allow linear movement after the teleport has occurred but before the system has returned to the ready state. More... | |
| bool | EnableRotationDuringReady = true |
| Allow rotation prior to the teleport system being activated. More... | |
| bool | EnableRotationDuringAim = true |
| Allow rotation while the teleport system is in the process of aiming for a teleport target. More... | |
| bool | EnableRotationDuringPreTeleport = true |
| Allow rotation while the teleport system is in the process of configuring the landing orientation. More... | |
| bool | EnableRotationDuringPostTeleport = true |
| Allow rotation after the teleport has occurred but before the system has returned to the ready state. More... | |
| TeleportAimHandler | AimHandler |
| Aiming is handled by one specific aim handler at a time. When the aim handler component is enabled, it will set this reference to the AimHandler so that other parts of the system which need access to the current aim handler can be sure to use the correct component. More... | |
| TeleportDestination | TeleportDestinationPrefab |
| This prefab will be instantiated as needed and updated to match the current aim target. More... | |
| int | TeleportDestinationLayer = 0 |
| TeleportInputHandler | InputHandler |
| The TeleportInputHandler is responsible for converting input events to TeleportIntentions. More... | |
| TeleportIntentions | CurrentIntention |
| The CurrentIntention is used by the state machine to know when it is time to switch to a new state. More... | |
| bool | IsPreTeleportRequested |
| The state machine will not exit the PreTeleport state while IsPreTeleportRequested is true. The sample doesn't currently use this, however this provides new components the ability to delay exiting the PreTeleport state until game logic is ready for it. More... | |
| bool | IsTransitioning |
| The state machine will not exit the Teleporting state while IsTransitioning is true. This is how the BlinkTransition and WarpTransition force the system to remain in the Teleporting state until the transition is complete. More... | |
| bool | IsPostTeleportRequested |
| The state machine will not exit the PostTeleport state while IsPostTeleportRequested is true. The sample doesn't currently use this, however this provides new components the ability to delay exiting the PostTeleport state until game logic is ready for it. More... | |
| AimCollisionTypes | AimCollisionType |
| When aiming at possible destinations, the aim collision type determines which shape to use for collision tests. More... | |
| bool | UseCharacterCollisionData |
| Use the character collision radius/height/skinwidth for sphere/capsule collision tests. More... | |
| float | AimCollisionRadius |
| Radius of the sphere or capsule used for collision testing when aiming to possible teleport destinations. Ignored if UseCharacterCollisionData is true. More... | |
| float | AimCollisionHeight |
| Height of the capsule used for collision testing when aiming to possible teleport destinations. Ignored if UseCharacterCollisionData is true. More... | |
Protected Member Functions | |
| void | LogState (string msg) |
| Internal logging function that is conditionally enabled via DEBUG_TELEPORT_STATES More... | |
| void | CreateNewTeleportDestination () |
| This is called whenever a new teleport destination is required. This might occur when rapidly switching between targets, or when teleporting multiple times in quick succession when the teleport destination requires additional time to complete any animations that are triggered by these actions. More... | |
| IEnumerator | ReadyStateCoroutine () |
| This coroutine will be running while the component is in the Ready state. More... | |
| IEnumerator | AimStateCoroutine () |
| This coroutine will be running while the aim state is active. The teleport destination will become active, and depending on the target and current intention of the user it might enter the CancelAim state or PreTeleport state when it is done. More... | |
| IEnumerator | CancelAimStateCoroutine () |
| This coroutine will be executed when the aim state is cancelled. More... | |
| IEnumerator | PreTeleportStateCoroutine () |
| This coroutine will be active while the system is in the PreTeleport state. At this point, the user has indicated they want to teleport however there is a possibility that the target they have chosen might be or become invalid so the next state will be either Teleporting or CancelTeleporting. More... | |
| IEnumerator | CancelTeleportStateCoroutine () |
| This coroutine will be executed when the pre-teleport state is unabled to transition to the teleporting state. More... | |
| IEnumerator | TeleportingStateCoroutine () |
| This coroutine will yield until IsTransitioning back to false, which will be immediately unless there is a transition handler that needs to take some time to move the player to the new location. This allows transition handlers to take as much (or little) time as they need to complete their task of moving the player to the teleport destination. More... | |
| IEnumerator | PostTeleportStateCoroutine () |
| The PostTeleport coroutine is typically just a single frame state that deactivates the destination indicator and raises the EnterStatePostTeleport event which could be used for any number of gameplay purposes such as triggering a character animation, sound effect or possibly delaying the exit of the PostTeleport state for some gameplay reason such as a cooldown on teleports. More... | |
Properties | |
| States | CurrentState [get] |
| The current state of the teleport state machine. More... | |
| Quaternion | DestinationRotation [get] |
| Returns the orientation of the current teleport destination's orientation indicator. More... | |
| LocomotionController | LocomotionController [get] |
| The LocomotionController that is used by object to discover shared references. More... | |
Events | |
| Action< bool, Vector3?, Quaternion?, Quaternion?> | UpdateTeleportDestination |
| This event is raised when the teleport destination is in the process of being updated. It is used by the active TeleportDestination to update it's visual state, position and orientation indicator to match the results of the teleport aim and targeting system. More... | |
| Action | EnterStateReady |
| This event is raised when entering the Ready state. The initial use for this is for the input handler to start processing input in order to eventually set the TeleportIntention to Aim when the user requests it. More... | |
| Action | EnterStateAim |
| This event is raised when the user begins aiming for a target location for a teleport. More... | |
| Action< AimData > | UpdateAimData |
| Aim and Target handlers are responsible for populating the AimData with the relevant aim data, which is used for a number of purposes within the teleport system. More... | |
| Action | ExitStateAim |
| This event is raised when the aim state is exited. This is typically used by aim visualizers to deactivate any visual effects related to aiming. More... | |
| Action | EnterStateCancelAim |
| This event is raised when aiming for a teleport destination is aborted. It can be useful for cleaning up effects that may have been triggered when entering the Aim state. More... | |
| Action | EnterStatePreTeleport |
| This event is raised when the system enteres the PreTeleport state. More... | |
| Action | EnterStateCancelTeleport |
| This event will occur if the user cancels the teleport after the destination has been selected. Typically not much different than cancelling an aim state, however there may be some effect triggered by the target selection which needs to be cleaned up, or perhaps a different visual effect needs to be triggered when a teleport is aborted. More... | |
| Action | EnterStateTeleporting |
| This event will occur when the teleport actually occurs. There should be one Transition Handler enabled and attached to this event. There may be other handlers attached to this event to trigger sound effects or gameplay logic to respond to the teleport event. More... | |
| Action | EnterStatePostTeleport |
| This event will occur after the teleport has completed. More... | |
| Action< Transform, Vector3, Quaternion > | Teleported |
| This event is raised when the character actually teleports, which is typically triggered by the transition handler. More... | |
Detailed Description
The LocomotionTeleport class controls and centralizes functionality for the various types of teleports. The system is designed to work as a set of components that are each responsible for different aspects of the teleport process. This makes it possible for different kinds of teleport behaviors to be occur by simply enabling different combinations of components.
Member Enumeration Documentation
◆ AimCollisionTypes
|
strong |
◆ States
|
strong |
◆ TeleportIntentions
|
strong |
Member Function Documentation
◆ AimCollisionTest()
| bool LocomotionTeleport.AimCollisionTest | ( | Vector3 | start, |
| Vector3 | end, | ||
| LayerMask | aimCollisionLayerMask, | ||
| out RaycastHit | hitInfo | ||
| ) |
AimCollisionTest is used by many of the aim handlers to standardize the testing of aiming beams. By choosing between the increasingly restrictive point, sphere and capsule tests, the aiming system can limit targeting to routes which are not physically blocked. For example, a sphere test is good for ensuring the player can't teleport through bars to get out of a jail cell.
- Parameters
-
start end aimCollisionLayerMask hitInfo
- Returns
◆ AimStateCoroutine()
|
protected |
This coroutine will be running while the aim state is active. The teleport destination will become active, and depending on the target and current intention of the user it might enter the CancelAim state or PreTeleport state when it is done.
- Returns
◆ CancelAimStateCoroutine()
|
protected |
This coroutine will be executed when the aim state is cancelled.
- Returns
◆ CancelTeleportStateCoroutine()
|
protected |
This coroutine will be executed when the pre-teleport state is unabled to transition to the teleporting state.
- Returns
◆ CreateNewTeleportDestination()
|
protected |
This is called whenever a new teleport destination is required. This might occur when rapidly switching between targets, or when teleporting multiple times in quick succession when the teleport destination requires additional time to complete any animations that are triggered by these actions.
◆ DoTeleport()
| void LocomotionTeleport.DoTeleport | ( | ) |
Perform the actual teleport. Note that warp transitions do not call this function and instead moves the game object during the transition time time.
◆ DoWarp()
| void LocomotionTeleport.DoWarp | ( | Vector3 | startPos, |
| float | positionPercent | ||
| ) |
Warp just the position towards the destination.
- Parameters
-
startPos positionPercent
◆ EnableMovement()
| void LocomotionTeleport.EnableMovement | ( | bool | ready, |
| bool | aim, | ||
| bool | pre, | ||
| bool | post | ||
| ) |
Helper function to enable linear movement during the various teleport states. Movement may not be desired at all states, for instance during aiming it may be preferred to prevent movement to allow a thumbstick to be used for choosing the landing orientation.
- Parameters
-
ready aim pre post
◆ EnableRotation()
| void LocomotionTeleport.EnableRotation | ( | bool | ready, |
| bool | aim, | ||
| bool | pre, | ||
| bool | post | ||
| ) |
Helper function to enable rotation movement during the various teleport states. Rotation may not be desired at all states, for instance during aiming it may be preferred to prevent rotation (snap turn or linear) to prevent the camera from being rotated while preparing to teleport.
- Parameters
-
ready aim pre post
◆ GetCharacterPosition()
| Vector3 LocomotionTeleport.GetCharacterPosition | ( | ) |
Convenience method for finding the character's position.
- Returns
◆ GetHeadRotationY()
| Quaternion LocomotionTeleport.GetHeadRotationY | ( | ) |
Return a quaternion for the Y axis of the HMD's orientation. Used by orientation handlers to track the current heading before processing user input to adjust it.
- Returns
◆ LogState()
|
protected |
Internal logging function that is conditionally enabled via DEBUG_TELEPORT_STATES
- Parameters
-
msg
◆ OnDisable()
|
virtual |
◆ OnEnable()
|
virtual |
Start the state machine coroutines.
◆ OnUpdateAimData()
| void LocomotionTeleport.OnUpdateAimData | ( | AimData | aimData | ) |
The target handler will call this method when the aim data has been updated and is ready to be processed by anything that needs to be aware of any changes. This generally includes a visual indicator for the aiming and the active orientation handler.
- Parameters
-
aimData
◆ OnUpdateTeleportDestination()
| void LocomotionTeleport.OnUpdateTeleportDestination | ( | bool | isValidDestination, |
| Vector3? | position, | ||
| Quaternion? | rotation, | ||
| Quaternion? | landingRotation | ||
| ) |
When the active aim and orientation handler finishes preparing the data for the teleport destination, this method will be called in order to raise the UpdateTeleportDestination event, which will in turn give any active teleport destination objects an opportunity to update their visual state accordingly.
- Parameters
-
isValidDestination position rotation
◆ PostTeleportStateCoroutine()
|
protected |
The PostTeleport coroutine is typically just a single frame state that deactivates the destination indicator and raises the EnterStatePostTeleport event which could be used for any number of gameplay purposes such as triggering a character animation, sound effect or possibly delaying the exit of the PostTeleport state for some gameplay reason such as a cooldown on teleports.
- Returns
◆ PreTeleportStateCoroutine()
|
protected |
This coroutine will be active while the system is in the PreTeleport state. At this point, the user has indicated they want to teleport however there is a possibility that the target they have chosen might be or become invalid so the next state will be either Teleporting or CancelTeleporting.
- Returns
◆ ReadyStateCoroutine()
|
protected |
This coroutine will be running while the component is in the Ready state.
- Returns
◆ RecycleTeleportDestination()
| void LocomotionTeleport.RecycleTeleportDestination | ( | TeleportDestination | oldDestination | ) |
◆ TeleportingStateCoroutine()
|
protected |
This coroutine will yield until IsTransitioning back to false, which will be immediately unless there is a transition handler that needs to take some time to move the player to the new location. This allows transition handlers to take as much (or little) time as they need to complete their task of moving the player to the teleport destination.
Member Data Documentation
◆ AimCollisionHeight
| float LocomotionTeleport.AimCollisionHeight |
Height of the capsule used for collision testing when aiming to possible teleport destinations. Ignored if UseCharacterCollisionData is true.
◆ AimCollisionRadius
| float LocomotionTeleport.AimCollisionRadius |
Radius of the sphere or capsule used for collision testing when aiming to possible teleport destinations. Ignored if UseCharacterCollisionData is true.
◆ AimCollisionType
| AimCollisionTypes LocomotionTeleport.AimCollisionType |
When aiming at possible destinations, the aim collision type determines which shape to use for collision tests.
◆ AimHandler
| TeleportAimHandler LocomotionTeleport.AimHandler |
Aiming is handled by one specific aim handler at a time. When the aim handler component is enabled, it will set this reference to the AimHandler so that other parts of the system which need access to the current aim handler can be sure to use the correct component.
◆ CurrentIntention
| TeleportIntentions LocomotionTeleport.CurrentIntention |
The CurrentIntention is used by the state machine to know when it is time to switch to a new state.
◆ EnableMovementDuringAim
| bool LocomotionTeleport.EnableMovementDuringAim = true |
Allow linear movement while the teleport system is in the process of aiming for a teleport target.
◆ EnableMovementDuringPostTeleport
| bool LocomotionTeleport.EnableMovementDuringPostTeleport = true |
Allow linear movement after the teleport has occurred but before the system has returned to the ready state.
◆ EnableMovementDuringPreTeleport
| bool LocomotionTeleport.EnableMovementDuringPreTeleport = true |
Allow linear movement while the teleport system is in the process of configuring the landing orientation.
◆ EnableMovementDuringReady
| bool LocomotionTeleport.EnableMovementDuringReady = true |
Allow linear movement prior to the teleport system being activated.
◆ EnableRotationDuringAim
| bool LocomotionTeleport.EnableRotationDuringAim = true |
Allow rotation while the teleport system is in the process of aiming for a teleport target.
◆ EnableRotationDuringPostTeleport
| bool LocomotionTeleport.EnableRotationDuringPostTeleport = true |
Allow rotation after the teleport has occurred but before the system has returned to the ready state.
◆ EnableRotationDuringPreTeleport
| bool LocomotionTeleport.EnableRotationDuringPreTeleport = true |
Allow rotation while the teleport system is in the process of configuring the landing orientation.
◆ EnableRotationDuringReady
| bool LocomotionTeleport.EnableRotationDuringReady = true |
Allow rotation prior to the teleport system being activated.
◆ InputHandler
| TeleportInputHandler LocomotionTeleport.InputHandler |
The TeleportInputHandler is responsible for converting input events to TeleportIntentions.
◆ IsPostTeleportRequested
| bool LocomotionTeleport.IsPostTeleportRequested |
The state machine will not exit the PostTeleport state while IsPostTeleportRequested is true. The sample doesn't currently use this, however this provides new components the ability to delay exiting the PostTeleport state until game logic is ready for it.
◆ IsPreTeleportRequested
| bool LocomotionTeleport.IsPreTeleportRequested |
The state machine will not exit the PreTeleport state while IsPreTeleportRequested is true. The sample doesn't currently use this, however this provides new components the ability to delay exiting the PreTeleport state until game logic is ready for it.
◆ IsTransitioning
| bool LocomotionTeleport.IsTransitioning |
The state machine will not exit the Teleporting state while IsTransitioning is true. This is how the BlinkTransition and WarpTransition force the system to remain in the Teleporting state until the transition is complete.
◆ TeleportDestinationLayer
| int LocomotionTeleport.TeleportDestinationLayer = 0 |
◆ TeleportDestinationPrefab
| TeleportDestination LocomotionTeleport.TeleportDestinationPrefab |
This prefab will be instantiated as needed and updated to match the current aim target.
◆ UseCharacterCollisionData
| bool LocomotionTeleport.UseCharacterCollisionData |
Use the character collision radius/height/skinwidth for sphere/capsule collision tests.
Property Documentation
◆ CurrentState
|
get |
The current state of the teleport state machine.
◆ DestinationRotation
|
get |
Returns the orientation of the current teleport destination's orientation indicator.
◆ LocomotionController
|
get |
The LocomotionController that is used by object to discover shared references.
Event Documentation
◆ EnterStateAim
| Action LocomotionTeleport.EnterStateAim |
This event is raised when the user begins aiming for a target location for a teleport.
◆ EnterStateCancelAim
| Action LocomotionTeleport.EnterStateCancelAim |
This event is raised when aiming for a teleport destination is aborted. It can be useful for cleaning up effects that may have been triggered when entering the Aim state.
◆ EnterStateCancelTeleport
| Action LocomotionTeleport.EnterStateCancelTeleport |
This event will occur if the user cancels the teleport after the destination has been selected. Typically not much different than cancelling an aim state, however there may be some effect triggered by the target selection which needs to be cleaned up, or perhaps a different visual effect needs to be triggered when a teleport is aborted.
◆ EnterStatePostTeleport
| Action LocomotionTeleport.EnterStatePostTeleport |
This event will occur after the teleport has completed.
◆ EnterStatePreTeleport
| Action LocomotionTeleport.EnterStatePreTeleport |
This event is raised when the system enteres the PreTeleport state.
◆ EnterStateReady
| Action LocomotionTeleport.EnterStateReady |
This event is raised when entering the Ready state. The initial use for this is for the input handler to start processing input in order to eventually set the TeleportIntention to Aim when the user requests it.
◆ EnterStateTeleporting
| Action LocomotionTeleport.EnterStateTeleporting |
This event will occur when the teleport actually occurs. There should be one Transition Handler enabled and attached to this event. There may be other handlers attached to this event to trigger sound effects or gameplay logic to respond to the teleport event.
The transition handler is responsible for actually moving the player to the destination, and can achieve this goal however it wants. Example teleport transition handlers include:
- Instant - Just move the player with no delay or effect.
- Blink - Fade the camera to black, teleport, then fade back up.
- Warp - Translate the camera over some fixed amount of time to the new destination.
◆ ExitStateAim
| Action LocomotionTeleport.ExitStateAim |
This event is raised when the aim state is exited. This is typically used by aim visualizers to deactivate any visual effects related to aiming.
◆ Teleported
| Action<Transform, Vector3, Quaternion> LocomotionTeleport.Teleported |
This event is raised when the character actually teleports, which is typically triggered by the transition handler.
The first parameter is the character controller's transform. The second and third are the position and rotation, respectively, which the character controller will be assigned immediately after the event is raised.
◆ UpdateAimData
| Action<AimData> LocomotionTeleport.UpdateAimData |
Aim and Target handlers are responsible for populating the AimData with the relevant aim data, which is used for a number of purposes within the teleport system.
◆ UpdateTeleportDestination
| Action<bool, Vector3?, Quaternion?, Quaternion?> LocomotionTeleport.UpdateTeleportDestination |
This event is raised when the teleport destination is in the process of being updated. It is used by the active TeleportDestination to update it's visual state, position and orientation indicator to match the results of the teleport aim and targeting system.
The documentation for this class was generated from the following file:
- Oculus/SampleFramework/Core/Locomotion/Scripts/LocomotionTeleport.cs
