ExistentVehicle

Overview

An ExistentVehicle is the core system Existent provides for locomotion across the virtual world. Whenever you create an experience where Players can traverse an area larger than a single Space, we recommend using a Vehicle to 'drive' them between Spaces. From a design perspective, the Vehicle metaphor works well when combined with a mesh (e.g. a car or a lift) and RealityBridge interactions (e.g. fan wind or floor vibrations) to give Players a believable context for the locomotion.

In technical terms, however, a Vehicle is simply a special type of Space with built-in functionality for moving smoothly from one Space to another, ensuring that all its children are perfectly aligned with the source and destination Space at either end of the drive. A Vehicle exists in one of four states: 'stationary at source', 'driving', 'paused', and 'stationary at destination'; it also exposes a blueprint-accessible API for transitioning between these states while the game is running.

By default, a Vehicle moves in a straight-line linearly interpolated path between the source and destination Space over a developer-specified number of seconds, but also provides an optional SplineComponent which can be modified by hand to create a custom path to the destination.

In the Unreal editor (or in-game with backstage mode enabled), a Vehicle is visualised as a white Space with a gradient-coloured line going between the source and destination Spaces, with a car icon at either end. To prevent cluttering the UI, the Vehicle’s grid mesh (see the Space section) is only visible in-game while in the “driving” state.

How to use

You can drag and drop an instance of the ExistentVehicle Actor into your level or create your own blueprint class that extends the ExistentVehicle class. From there, assign values to the Source Space and Destination Space properties by linking them to Spaces that already exist in your level. Once this has been done, the Vehicle should automatically snap to align to the source Space.

To initiate driving while the game is running, you can invoke the Drive() function, which takes in a list of Players and props to take along for the ride, and automatically inserts them into the destination Space once the drive has completed.

If your Vehicle Actor contains a mesh, you can enable the Align to Mesh property, and select the relevant mesh in the Vehicle mesh property. This will align the Vehicle icon and connecting line to be centred on your mesh, to better visualise the start and end point of the Vehicle’s path.

Custom spline path

By default, a Vehicle will drive in a straight line at constant velocity from the source to the destination Space, over the time provided in the Driving Time Secs property (10 by default). If you would like to provide a custom path between the source and destination, however, enable the Use Spline property, and modify the Path Spline component to draw an Unreal spline for the Vehicle to follow.

Drawing a custom Spline path for the Vehicle to follow

Custom velocity curve

If you would like your Vehicle to accelerate and decelerate at specific points along its journey (i.e. travel with non-constant speed), disable the Constant Speed property. You will now be able to supply a custom FloatCurve in the Speed Curve property.

To create this curve, simply right-click anywhere in your content browser and select Miscellaneous->Curve, and select 'CurveFloat' in the dialogue box that appears. The y-value of each point along this curve determines the speed of the Vehicle at that point along its journey, multiplied by the Vehicle's Speed Scale. The horizontal axis represents the time elapsed during the drive, with the leftmost point being the start of the journey, and the rightmost point the end. Note that the Vehicle expects a curve with a time domain of [0, 1], and if the supplied curve does not match this, it is automatically adjusted at runtime.

Also note that when working with varying-speed Vehicles, since speed is fully customisable via the Speed Curve and Speed Scale properties, the Driving Time Secs variable is now automatically generated based on these speed parameters and the length of the path.

Once your custom speed curve has been set up, Existent will automatically render 'speed signs' when viewing the Vehicle in the editor (or in backstage mode), which indicate the speed and acceleration at regular points along the Vehicle's path.

Vehicle with custom speed curve and custom spline path, showing speed signs along the path

Additional Details

• Automatic Player and prop transfer: The Vehicle automatically handles transferring all desired Players (as well as any props they’re holding) smoothly from the source to the destination Space, placing them in the destination Space when the Vehicle arrives.

• Blueprint-accessible API:

  • Drive() initiates driving to the destination Space, and takes in a list of Players and props to take along for the ride.

  • SetIsPaused() pauses a driving Vehicle, or resumes driving for a Vehicle that's already paused.

  • ResetToSource() resets the Vehicle back to the 'stationary at source' state.

  • Reverse() swaps the source and destination Spaces. NB: Will not reverse the path of a custom spline.

  • The OnArrivedAtDesination event is fired when the Vehicle arrives at the destination Space.

• Smooth spline-based movement: If you’re building a custom path for the Vehicle to take when driving, Existent will automatically handle aligning the Vehicle smoothly with the source and destination Spaces at either end of the drive, even if the start and end points of your spline do not line up perfectly. We recommend enabling the Visualize Roll and Scale option when selecting the spline component in the Unreal editor to ensure there are no sudden jumps or rotations elsewhere in your path.

• Server-authoritative: For multiplayer experiences, all Vehicle functions only need to be invoked once on the server machine, and the Vehicle’s state and location (including which Players and props are attached) will automatically replicate to all other connected clients.