Control vehicles from code

For keyboard and gamepad configuration, use Controls. For a vehicle that follows a route without a driving script, use AI Vehicles.

•Use the RCCP namespace

Add using BoneCrackerGames; at the top of each script that calls the RCCP API, before the class declaration. The namespace lets your script find RCCP types. The class names and member names stay the same.

using BoneCrackerGames;
using UnityEngine;

public class MyVehicleScript : MonoBehaviour {
    public RCCP_CarController car;
}

If an existing script reports CS0246 for an RCCP type after the upgrade, add the namespace import first. Existing specialized namespaces, for example BoneCrackerGames.Prototypes, keep their names.

Scripts in an assembly definition

A namespace import does not add an assembly reference. RCCP core uses the predefined Assembly-CSharp assembly. An assembly definition cannot reference that predefined assembly. Keep the script that calls RCCP outside the folders that your .asmdef controls. Alternatively, use an adapter in the predefined assembly. Do not add an .asmdef to the RCCP core folder to fix a namespace error.

•Before you start

• Use a vehicle that drives correctly in Your First Drive.
• Keep the Inputs module of the vehicle enabled and Player can drive this car on. This flag also allows scripted driving.
• Test one scripted driver at a time. Disable AI, and stop recording, replay and other scripts that control this vehicle.
• Use a clear test area and an engine that already runs.

An input is a request, for example throttle or steering. An input handle is the object that your script receives when the script takes control. With the handle, RCCP can reject writes from a script that does not own the vehicle now.

1. Add a simple scripted driver

The example applies a small throttle input and drives straight. The example gives back control when you disable the example component. The example is a starting point for one driver only. A mission or network system must also manage its own vehicle handoffs.

1. Create RCCP_ScriptedDriveExample.cs in your own scripts folder.
2. Replace the contents of the file with the example below.
3. Attach the script to an empty GameObject.
4. Drag the vehicle root from the Hierarchy into the Car field of the component.

using BoneCrackerGames;
using UnityEngine;

[DefaultExecutionOrder(-11)]
public class RCCP_ScriptedDriveExample : MonoBehaviour {
    [Tooltip("The working player vehicle this example will drive.")]
    public RCCP_CarController car;

    private RCCP_Input.ControlHandle handle;
    private readonly RCCP_Inputs inputs = new RCCP_Inputs();

    private void OnEnable() {
        if (car == null || car.Inputs == null || !car.canControl) {
            Debug.LogWarning("Assign a working car with Inputs and player control enabled.", this);
            enabled = false;
            return;
        }

        if (car.externalControl || car.Inputs.IsControlled) {
            Debug.LogWarning("Another driver already controls this car.", this);
            enabled = false;
            return;
        }

        handle = car.Inputs.AcquireControl(this);
        RCCP.SetExternalControl(car, true);
        inputs.Clear();
        inputs.throttleInput = 0.25f;
    }

    private void Update() {
        if (handle == null || !handle.Set(inputs))
            enabled = false;
    }

    private void OnDisable() {
        if (handle != null && handle.IsValid) {
            handle.Release();
            if (car != null)
                RCCP.SetExternalControl(car, false);
        }
        handle = null;
    }
}

2. Test the example and return control

1. Wait until Unity compiles the script.
2. Examine the Console for errors.
3. Click Play. Do not touch the driving keys while the example runs.
4. Select the GameObject of the example and clear the enabled checkbox of the component.
5. Click in the Game view and try the usual driving controls again.
6. Stop Play Mode.

Check: The vehicle drives forward under script control. After you disable the example, the vehicle accepts player input. If another driver takes control, the example disables itself. The example does not release the handle of that driver.

•Troubleshoot the example

The remaining sections are reference information to extend the example. You do not have to change all flags or use all methods.

•Take control of a vehicle

Use AcquireControl to drive a vehicle from a script. One call takes the vehicle, and one call gives the vehicle back. The token that you get tells you if another system took the vehicle in the meantime.

Acquire control one time. Call handle.Set(inputs) in each update. Release control when you are done. Use the same RCCP_Inputs object, as the example does. Do not allocate a new object in each frame.

Pass this as the owner. If the owner is a UnityEngine.Object and is destroyed while it holds the vehicle, RCCP_Input releases the vehicle in its next Update. RCCP_Input also logs a warning with the vehicle name. Without this release, a destroyed mission script leaves the vehicle permanently without response.

A second AcquireControl call from a different owner is permitted. The call logs a warning with the names of the two owners. The first handle becomes invalid. Thus, the system that lost the vehicle can detect the loss.

The bypassInputProcessing parameter

The default value of bypassInputProcessing is true. This value enables Skip all input shaping (overrideExternalInputs). Then RCCP skips the steering curve, counter steering, auto-reverse, pedal swap in reverse and the throttle cut during a shift. The deadzones, cruise control and hill start assist still apply.

The wheel-level steering limit still applies to scripted vehicles, also to raw input. The limit acts on grounded wheels on steering axles. To disable the limit, disable Steering limiter (steeringLimiter) on the Inputs module of the vehicle. Alternatively, set car.Inputs.steeringLimiter = false.

If a global or custom behavior preset applies, disable Limit Steering (limitSteering) on that preset. The preset value overwrites the vehicle setting. Read the resulting wheel angle through the wheel facade.

To adjust the correction strength, set car.Inputs.steeringLimiterMultiplier to a value from 0f to 1f. The default 1f keeps the full correction. 0.5f applies half of the correction, and 0f removes the correction. If a behavior preset applies, set Steering Limiter Multiplier on the preset. The preset replaces the value on the vehicle.

Keep bypassInputProcessing set to true, unless you want input shaping. If you pass false, the current shaping flag does not change. The call does not enable shaping again.

If shaping is active, the gearbox is automatic and auto-reverse is on, a full brake input at low speed selects reverse. Then a test or a cutscene that brakes drives backward.

On release, Skip all input shaping gets back the value from before the first acquire. Thus, if two systems hand the vehicle over, the vehicle still goes back to its initial state.

•The older override protocol

OverrideInputs and DisableOverrideInputs are older than the token. RCCP still fully supports these methods.

OverrideInputs does not enable Skip all input shaping. To skip input shaping, enable this option yourself. The wheel-level steering limit still applies, as described above.

A direct OverrideInputs call takes control and makes all existing handles invalid. If a handle existed, the call logs a warning. The call also sets Skip all input shaping back to its value before token control.

The built-in AI uses this protocol. The AI sets externalControl itself and calls OverrideInputs in each tick.

•The inputs class

RCCP_Inputs is a plain serializable class. The default constructor sets all values to zero. A seven-argument constructor takes all the values below, in this order. The Clear() method sets all values of the object to zero.

•Input processing order

When no replay runs, RCCP_Input.Update processes device inputs and scripted inputs in this order:

1. If the token owner no longer exists, the component releases the vehicle.
2. If Player can drive this car (canControl) or Driven by a script or AI (externalControl) changed since the last frame, the component replaces the inputs object. The new object has all values at zero.
3. The component reads the device inputs. This step is skipped while Inputs come from a script is on.
4. The component applies the deadzone of each axis and copies the results into the live axis values.
5. The component applies input shaping. This step is skipped while Skip all input shaping is on.
6. The component applies cruise control and hill start assist.

Step 4 also applies to your values. Each axis has its own deadzone. The default of throttleDeadzone, steeringDeadzone and the other four deadzones is 0.05. RCCP remaps a value above the deadzone as (value - deadzone) / (1 - deadzone). Thus, at the default deadzone, a scripted throttle of 0.5 reaches the vehicle as 0.474. If you need exact values, write 0 and 1. Alternatively, set the deadzones to zero on vehicles that only a script controls.

Because of step 2, the vehicle stops its response for a short time when you change canControl or externalControl. In that frame, step 2 replaces your inputs object with an empty object. In the next frame, pass your object again with handle.Set or OverrideInputs.

•Lock the player out

Two flags on RCCP_CarController control if the device of the player reaches the vehicle. Set the flags through the facade: RCCP.SetControl(vehicle, bool) and RCCP.SetExternalControl(vehicle, bool).

Do not disable canControl to lock the player out of a scripted sequence. In each fixed step, the vehicle reads its inputs again. While canControl is off, the vehicle writes zeros over all six inputs before the drivetrain reads them. The engine reads throttleInput_P, which is one of these values.

The vehicle also applies Apply handbrake (applyHandBrakeOnDisable), which is on by default. If Apply brake (applyBrakeOnDisable) is on, the vehicle also applies the brake. This option is off by default. Thus, a cutscene that disables canControl and then sends throttle gets a vehicle with the handbrake applied. The vehicle does not move.

Use externalControl instead. This flag stops the device and the key events, but does not change your values. The built-in AI uses the same method. Keep canControl on for all vehicles that your script drives.

Neither flag sends your input to the vehicle. To make RCCP use your values, you still need a token or an override.

All device axes and key events go through IsControllableByPlayer(). This method returns true only if all these conditions are true:

• Player can drive this car is on.
• Driven by a script or AI is off.
• In Play Mode, if a player vehicle is registered, this vehicle is RCCP_SceneManager.activePlayerVehicle.

Because of the last condition, scripted vehicles in the scene do not toggle their indicators together with the player vehicle.

•Vehicle state readouts

The fields and properties below on RCCP_CarController are live readouts. Read them to monitor the vehicle. To control the vehicle, change its configuration or its inputs.

There are two families of input readbacks. A frequent mistake is to use the wrong family:

As the speed increases, the steering curve can decrease steerInput_P and steerInput_V. Neither value keeps the original full steering request. If your game needs that request, read the request from your driver before RCCP applies input shaping.

steerInput_V is the average of the angle of each steering axle divided by the maximum angle of that axle. For the resulting wheel angle, read SteerAngleDeg of each wheel after the solver step. Refer to wheel readouts and timing.

For per-wheel RPM, contact, physical slip and compatibility slip, use the wheel API.

•Change gear from code

The five shift methods are on RCCP_Gearbox. While shiftingNow is true, all five methods return immediately and do nothing. Thus, a call in each frame is safe, but a queued call is not. A shift takes Shift time (shiftingTime) seconds. The default is 0.2.

ShiftUp and ShiftDown also do nothing while forceToNGear is on. With the Automatic_DNRP transmission, these methods do nothing unless automaticGearSelector is D. With this transmission, ShiftReverse does nothing unless the selector is R.

Transmission (transmissionType) accepts Manual, Automatic or Automatic_DNRP. To set the transmission from the facade, use RCCP.SetAutomaticGear(vehicle, bool) or its TransmissionType overload. The high-level state is currentGearState.gearState. The value is Park, InReverseGear, Neutral or InForwardGear.

TargetSpeeds (the target speed of each gear) returns the same array on each read. RCCP fills the array again with the current values. If your code keeps the values, copy the array.

For full control, for example in a replay or a custom drivetrain, use OverrideGear(int targetGear, float targetGearInput, CurrentGearState.GearState gearState). This method sets Override gear (overrideGear) to on. Until you call DisableOverride(), the gearbox skips its automatic shifting, its gear-state updates and the rev-match blip. The shift methods do not examine Override gear. Thus, do not call the shift methods while the override is on.

•Scripted control during a replay

RCCP_ReplayDirector holds the input lock during a playback. During the lock, RCCP keeps your writes but does not apply them. This applies to OverrideInputs, DisableOverrideInputs, ResetInputs, AcquireControl, Release and ControlHandle.Set. The writes go to shadow copies and apply when the replay ends.

Thus, two systems never drive the vehicle at the same time. ControlHandle.Set still returns true. To know if a replay runs, read RCCP.IsReplayActive.

•Common mistakes

•Read next

• The Public API: the facade methods in this chapter, with their full signatures.
• Controls: the source of device input before this processing.
• AI Vehicles: the built-in waypoint AI, which drives vehicles through the same override path.
• Field Reference: all settings in this chapter, with their defaults and ranges.