VehicleBehaviour reference #

VehiclePhysics.VehicleBehaviour is the base class for components that belong to a vehicle in Vehicle Physics Pro. VehicleBehaviour inherits from MonoBehaviour so these add-on components are standard components in Unity.

VehicleBehaviours have these advantages:

VehicleBehaviours support these runtime situations:

Check out Creating add-on components for an example add-on with source code. Most components included in VPP are already VehicleBehaviours.

VehicleBehaviour events #

OnEnableVehicle #

Called right after the vehicle has been initialized.

OnDisableVehicle #

Called right before the vehicle is finalized.

UpdateVehicle #

Replacement for Update. Called each visual frame.

It's always called after OnEnableVehicle. There are no further calls after OnDisableVehicle.

FixedUpdateVehicle #

Replacement for FixedUpdate. Called right after each vehicle physics step. Use for stuff that depends on physics values from the vehicle.

It's always called after OnEnableVehicle. There are no further calls after OnDisableVehicle.

UpdateAfterFixedUpdate #

Called in the Update cycle, but only if at least one FixedUpdate call (physics update) has happened right before this Update.

UpdateAfterFixedUpdate allows efficient execution of visual updates that depend on physics under any combination of refresh rate and physics rate.

This event solves the problems that may arise when using UpdateVehicle or FixedUpdateVehicle in these cases:

UpdateVehicleInput #

Called in the FixedUpdate cycle right before the vehicle physics step. This is the place to read the state of the input devices and apply them to the vehicle, so the input has effect in the same simulation step.

GetUpdateOrder #

Execution order the event methods with respect to other VehicleBehaviours. Smaller order executes first. Default is 0 (default order).

This order does NOT affect the execution order for OnEnableVehicle, OnDisableVehicle, OnEnableComponent, or OnDisableComponent.

UpdateVehicleSuspension #

Specialized vehicle suspension update method. Allows the component to modify the suspension parameters in runtime. Called from inside the vehicle dynamics code at the proper time.

These values have been already updated and are available to read:

vehicle.speed
vehicle.speedAngle
vehicle.localAcceleration

wheelState.grounded
wheelState.hit
wheelState.contactDepth
wheelState.lastContactDepth
wheelState.contactSpeed
wheelState.suspensionCompression
wheelState.groundMaterial
wheelState.lastGroundHit

wheelState.wheelCol.lastRuntimeSpringRate
wheelState.wheelCol.lastRuntimeDamperRate

All other parameters contain the state from the previous physics step. The component should leave the new suspension parameters in these properties:

wheelState.wheelCol.runtimeSpringRate
wheelState.wheelCol.runtimeDamperRate
wheelState.wheelCol.runtimeExtraSuspensionForce

These properties are reset to their default values at the beginning of each dynamics step. Note that other components may have already modified them. It's up to the component to override the properties with its own values or add them to the existing ones.

OnEnableComponent
OnDisableComponent #

Use OnEnableComponent and OnDisableComponent if you need to trace whether this precise component gets enabled or disabled in Unity.

Do NOT override OnEnable or OnDisable! Always use OnEnableComponent and OnDisableComponent instead if you need to trace the initialization of this precise component in Unity.

OnReposition #

The vehicle has been repositioned (position & rotation) in a discontinuous way via VehicleBase.Reposition().

OnEnterPause
OnLeavePause #

Vehicle enters or leaves the paused state via VehicleBase.paused.

Within the pause state the vehicle solver doesn't run, and UpdateVehicle / FixedUpdateVehicle are not invoked regularly. Only they get invoked once when vehicle.SingleStep() is called. In this case, a single FixedUpdateVehicle call is followed by a single UpdateVehicle call.

OnEnterPause and OnLeavePause, if invoked, always occur after OnEnableVehicle and before OnDisableVehicle.

Gathering vehicle data #

You may access the vehicle with the vehicle property (VehicleBase) in VehicleBehaviour. VehicleBase exposes these properties among others:

VehicleBase.data
Access to the internal Data Bus, which provides a lot of internal information that may be read and modified.
VehicleBase.wheelState

Access to the individual WheelState data of each wheel. There's a lot of information per wheel available. For example, the VPAudio component reads the sliding state of each wheel here and produces the tire skid sound.

The number of wheels and the size of the wheelState array are guaranteed not to change between the OnEnableVehicle - OnDisableVehicle calls (both included).

VehicleBase.cachedTransform
VehicleBase.cachedRigidbody
Optimized access to the Transform and Rigidbody components in the vehicle.

Check out VehicleBase's Scripting Reference for a full list.

Scripting reference #

namespace VehiclePhysics
{
    public abstract class VehicleBehaviour : MonoBehaviour
}

Properties #

    // The vehicle that owns this component

    public VehicleBase vehicle { get; }

Methods #

    // Log messages to Unity's console including component and gameobject information

    public void DebugLogWarning (string message)
    public void DebugLogError (string message)

Virtual Methods #

    // OnEnableVehicle is called right after the vehicle has been initialized

    public virtual void OnEnableVehicle ()

    // OnDisableVehicle is called right before the vehicle is finalized

    public virtual void OnDisableVehicle ()

    // UpdateVehicle is a regular Update call invoked between OnEnableVehicle and OnDisableVehicle.
    // Use for visual stuff.

    public virtual void UpdateVehicle ()

    // FixedUpdateVehicle is called right after each vehicle physics step.
    // Use for stuff that depends on physics values from the vehicle.

    public virtual void FixedUpdateVehicle ()

    // Execution order for UpdateVehicle, FixedUpdateVehicle and the additional notification events.
    // Smaller order executes first. Default is 0 (default order).
    //
    // This order does NOT affect OnEnableVehicle or OnEnableComponent.

    public virtual int GetUpdateOrder ()

    // Specialized suspension update method
    //
    // Allows the component to modify the suspension parameters in runtime.
    // Called from inside the vehicle dynamics code at the proper time.
    //
    // Updated parameters available:
    //
    //      vehicle.speed
    //      vehicle.speedAngle
    //      vehicle.localAcceleration
    //
    //      wheelState.grounded
    //      wheelState.hit
    //      wheelState.contactDepth
    //      wheelState.lastContactDepth
    //      wheelState.suspensionCompression
    //
    //      wheelState.wheelCol.lastRuntimeSpringRate
    //      wheelState.wheelCol.lastRuntimeDamperRate
    //      wheelState.wheelCol.lastRuntimeSuspensionTravel
    //
    // All other parameters contain the state from the previous physics step.
    // Suspension parameters that may be modified within this method:
    //
    //      wheelState.wheelCol.runtimeSpringRate
    //      wheelState.wheelCol.runtimeDamperRate
    //      wheelState.wheelCol.runtimeSuspensionTravel

    public virtual void UpdateVehicleSuspension ()

    // Don't override OnEnable and OnDisable.
    //
    // Use OnEnableComponent and OnDisableComponent if you need to trace whether
    // this precise component gets enabled or disabled in Unity.
    //
    // - The vehicle might have been initialized or not at OnEnableComponent.
    // - OnEnableComponent will always be called before OnEnableVehicle.
    // - OnDisableComponent will always be called after OnDisableVehicle.

    // You may handle Update and FixedUpdate directly in your component.
    // They will be tied to this component's state, but not the vehicle's.

    public virtual void OnEnableComponent ()
    public virtual void OnDisableComponent ()

    // The vehicle has been repositioned (position & rotation) in a discontinuous way.
    //
    // - OnReposition gets invoked when VehicleBase.Reposition() is called.
    // - OnReposition doesn't happen on disabled vehicles.
    // - The new position and rotation are now in vehicle.cachedTransform.position & rotation.

    public virtual void OnReposition ()

    // Vehicle enters or leaves the Paused state.
    //
    // Within the pause state the vehicle solver doesn't run, and UpdateVehicle / FixedUpdateVehicle
    // are not invoked regularly. Only they get invoked once when vehicle.SingleStep() is called.
    // In this case, a single FixedUpdateVehicle call is followed by a single UpdateVehicle call.
    //
    // OnEnterPause and OnLeavePause, if invoked, always occur after OnEnableVehicle and before
    // OnDisableVehicle.

    public virtual void OnEnterPause ()
    public virtual void OnLeavePause ()

    // Virtual method for retrieving the vehicle component.
    // Searches the component in the ancestors by default, but it may be overridden.
    //
    // NOTE: if the VehicleBehaviour is not part of the hierarchy of its vehicle, then it must
    // monitor the vehicle's initialized flag from Update or FixedUpdate and register itself when
    // vehicle.initialized changes from false to true:
    //
    //      if (vehicle.initialized == true && m_lastInitialized == false)
    //          {
    //          vehicle.RegisterVehicleBehaviour(this);
    //          {
    //
    //      m_lastInitialized = vehicle.initialized;

    protected virtual VehicleBase GetVehicle()