User Guide

Purpose

NsVehicles is a runtime plugin for physics vehicles: cars, karts, trucks, bikes, and hover vehicles. One physics body moves the vehicle. Suspension components trace the ground and push the body up. Module components on the vehicle add the drive, brake, steering, and other forces. You tune all of them in the Details panel, or call them from Blueprint and C++.

NsVehicles is not a full tire model, and it is not a Chaos Vehicles replacement. The wheels are traces, not colliders. The drive force acts on the body, not on each wheel. There is no clutch.

Setup

1. Copy the NsVehicles folder into the Plugins folder of your project.
2. For C++, add "NsVehicle" and "AsyncTickPhysics" to PublicDependencyModuleNames in the Build.cs file of your game module. ANsVehicle derives from AAsyncTickPawn, which is in AsyncTickPhysics.
3. Generate the project files and build the project.
4. In Edit > Plugins, enable NsVehicle. Restart the editor.
5. Recommended: enable Project Settings > Physics > Tick Physics Async. The vehicle step then runs on the physics thread.

The plugin runs on Win64, Mac, Linux, Android, and iOS.

Quick Start

Blueprint

1. Make a Blueprint class with NsVehicle as the parent.
2. Add a Static Mesh component as the root. Give it a mesh with simple collision.
3. On the root, enable Simulate Physics.
4. Add four NsVehicleSuspensionComponent components under the root. Put each one above a wheel position.
5. On each suspension component, set Wheel Mesh.
6. On the two front suspension components, enable Is Steering Wheel.
7. In the input events, call Get Controls, then Set Throttle Input, Set Brake Input, and Set Steering Input.
8. Place the vehicle in a level, possess it, and press Play.

The vehicle gets all modules automatically. The default Engine module uses the arcade powertrain, so the vehicle drives with no other setup.

C++

#include "Modules/Control/NsVehicleControlsComponent.h"
#include "Vehicle/NsVehicle.h"

void AMyPlayerController::DriveForward(ANsVehicle* Vehicle, const float Input)
{
    Vehicle->GetControls()->SetThrottleInput(Input);
}

Common Tasks

Find a setting

Each system is a module component on the vehicle. Select the module in the Components panel to see its settings. In Blueprint or C++, call the module getter on the vehicle, for example Get Engine, Get Brakes, or Get Steering.

Make a wheel mesh

1. Put the origin of the wheel mesh at the wheel center.
2. Put the axle on the Y axis. The wheel spins on its pitch axis.
3. Give the mesh simple collision if you want to detach the wheel.

The suspension uses half the mesh height as the wheel radius. With no wheel mesh, it uses Radius (33 cm).

Show the wheels in the editor

1. Add a Static Mesh component under each suspension component. Set the wheel mesh on it.
2. On the suspension component, enable Inherit Mesh From Component.

The suspension uses its first child as the wheel mesh. Keep the wheel mesh as the first child, and attach other components to the root.

Use the standard powertrain

1. On the Engine module, set Powertrain Type to Standard.
2. On the Transmission module, fill Gear Ratios with one ratio for each gear.
3. Set Differential Ratio and Wheel Radius. Wheel Radius is in meters.
4. Optional: set Torque Implementation to Curve, and set Engine Torque Curve.

The automatic gearbox shifts from the RPM. To shift from the speed, enable Use Speed Based Shifting and fill Speed Shifting Ratios. To shift by hand, disable Automatic and call Upshift and Downshift.

Set up the driven wheels

1. On the Engine module, set Powertrain Type to Standard. The slip power loss works only in the standard powertrain.
2. On the Drivetrain module, enable Use Drivetrain.
3. On each suspension component, enable Use With Drivetrain.
4. On each driven wheel, enable Driven Wheel.
5. On each driven wheel, set Torque Received. For RWD, use 0.5 on each rear wheel.

A driven wheel slips when its torque is above the traction limit. Then it loses grip and spins faster. With Use Drivetrain on, the vehicle is airborne when no driven wheel touches the ground. In Air Wheel Count then has no effect.

Detach a wheel

1. Give the wheel mesh simple collision.
2. Call Detach Wheel on the suspension component, after Begin Play. Impulse is a velocity change in cm/s.

FrontLeftWheel->DetachWheel(FVector(0.f, -600.f, 400.f));

The wheel mesh becomes a free physics body with the velocity of the vehicle at that point. The suspension stops all its forces. The vehicle ignores detached wheels when it counts airborne wheels.

Attach a detached wheel again

1. Call Reattach Wheel on the same suspension component.

The wheel mesh stops its physics, turns off its collision, and goes back under the suspension component. The suspension forces start again.

FrontLeftWheel->ReattachWheel();

Set up the handbrake

1. On the Brakes module, set Handbrake Strength.
2. On each suspension component that the handbrake holds, enable Handbrake Wheel.
3. Set Handbrake Wheel Type to Front or Rear.
4. Call Get Controls, then Apply Handbrake Input.

The handbrake wheels stop their spin while the handbrake is on. The handbrake does not change the grip. For a drift, set Lateral Force Scalar lower on the rear wheels while the handbrake is on.

Make a bike lean in turns

1. On the Body Dynamics module, enable Use Steer Lean.
2. In Begin Play, call Get Body Dynamics, then Initialize Lean Steer with one suspension component. A rear wheel gives the best result.
3. Tune Steer Lean Coefficient and Steer Lean Min Speed.

Drive on walls with anti gravity

1. Add a Scene component to the vehicle.
2. On the Anti Gravity module, enable Anti Gravity Enabled.
3. In Begin Play, call Get Anti Gravity, then Initialize Anti Gravity. Pass the Scene component and the root static mesh.
4. Tune Anti Gravity Z Strength first. Values from 1 to 2 work well.

The system stays on for Anti Gravity Off Contact Threshold seconds after the vehicle leaves the ground. Call Override Anti Gravity State with true to keep it on.

Animate the interior

1. Add one of these components under the vehicle.
2. Set its mesh.

The vehicle sets the rotation on one axis every frame. The other axes keep their values from Begin Play.

Each one has Input Range, Output Range, Rotation Axis, Use Smoothing, Smoothing Speed, and Invert.

Move a part, for example a forklift arm

1. Add an NsVehicle Articulated Component under the vehicle.
2. Set Axis, Min, Max, and Movement Speed.
3. Call Set Input. A positive value moves to Max. A negative value moves to Min.

Follow a spline with AI

1. Add an NsVehicleAI component to the vehicle.
2. Call Set Target Spline with a spline component.
3. In Event Tick, call Update with the frame time.
4. Send Out Steering to Set Steering Input.

Tune Kp first, then Kd and Kd2. Use Ki to remove a constant offset. Call Refresh when you change the spline.

Ignore some surfaces

1. In Project Settings > Collision, add a trace channel with the default response Block.
2. On each suspension component, set Collision Channel to the new channel.
3. On the objects that the wheels must ignore, set the response for the new channel to Ignore.

Replicate the vehicle

1. On the Network module, set Replication Method.
2. For Data Only, use another system to correct the client position, for example Replicate Movement on the actor.

With Full, Use Server Fast Sync also copies the server transform to the clients every Server Fast Sync Latency frames.

For many replicated vehicles, disable Auto Wake Rigid Bodies on the vehicle. Then call RT Wake Rigid Bodies often, for example from the input events.

Send custom input to the server

1. Call Get Controls, then Set Ext Replication Input with an index from 0 to 5 and a value from -1 to 1.
2. On the server, read it with Get Ext Replication Input, for example in Event Async Tick.

The value goes from the client to the server only. Other clients do not get it.

Record with the take recorder

1. On the Animation module, enable Enable Animation Mode.
2. Record the vehicle with the take recorder.
3. Disable Enable Animation Mode after the recording.

In animation mode, the wheels spin from the actor movement, not from the physics. For playback, add NsVehicleWheel components to the root. Then call Initialize Animation System one time and Simulate Internal Animation every frame.

Settings

Every value is the default in the code. Some settings show only when another setting enables them.

Vehicle

Engine

Transmission

Drivetrain

Brakes

Steering

Body Dynamics

Aerodynamics, Air Control, Anti Gravity, Idle Lock

Network and Animation

Suspension component

With Use With Drivetrain on:

Interior, articulated, AI, and wheel components

Debug

• On a suspension component, enable Debug. The sphere trace draws as a capsule. Its color goes from green to red with the compression. A line trace draws in orange. The impact point draws in yellow.
• On an NsVehicleAI component, enable Draw Debug. A blue sphere marks the vehicle, a red sphere marks the closest spline point, and a green line joins them.
• All messages use the log category LogTemp. Search the Output Log for NsVehicle.
• To show the state on screen, read Get Speed KPH, Is In Air, Get RPM, Get Current Gear, Is Slipping, or Is Idle Locked.

The plugin has no console commands and no console variables.

Troubleshooting

Limits

• Keep the actor scale at 1. The physics step ignores the actor scale, so a scaled vehicle puts the wheels in the wrong place.
• Wheel detach and reattach are local. They do not replicate.
• The vehicle finds its suspension, interior, and articulated components in Begin Play. It does not update components that you add later.
• Event Async Tick runs two times in each physics step. On a client in Full mode, it runs one time.
• The custom inputs go to the server only.
• The modules are fixed. You cannot remove a module or replace it with a subclass.
• There is no clutch simulation.

Contact

E-mail LinkedIn GitHub Bluesky