1.0 Overview

Driving Simulator (aka DS) is a plug-and-play development kit for creating four-wheel-drivable vehicle physics simulations.

Its main goal is to reproduce the most popular vehicle simulation style used in the game industry.

DS provides a simple yet robust solution for creating semi-arcade vehicle physics.

What problem does it solve?

Implementing vehicle physics from scratch can be extremely complex and time-consuming.

Developers often face challenges in stability, performance, and physical accuracy.

DS eliminates these obstacles by providing a ready-to-use solution that delivers high-fidelity vehicle physics with stable behavior and efficient resource usage.

1.1 Key Features

• High performance — core simulation is implemented in C++ for fast computation;
• Highly configurable — parameters are based on real-world vehicle data, allowing you to create everything from production cars to racing prototypes;
• Stable and detailed physics — supports realistic behaviors such as drifting, donuts, and high-speed driving.

1.2 Physics Features:

Engine

• Inertia
• Rev limiter frequency
• Engine braking torque
• Idle behavior
• Auto-blip
• Torque curve support
• Turbo kit supports with parameters such as maximum boost, wastegate level, and reference RPM

Differentials

• Inter-axle and inter-wheel limited-slip differentials
• Acceleration and deceleration sensitivity settings
• Inter-wheel differential preload torque

Clutch

• Maximum clutch torque
• Minimum and maximum reference engine RPM for smooth engine–transmission coupling
• Special clutch profiles to smooth gear shifting

Simulation Stability

• Sub-stepping support for improved stability at low frame rates
• Predictable behaviour at high speed

Suspension

• Camber angle
• Toe angle
• Spring length and attachment points
• Spring stiffness and damping
• Caster angle, kingpin angle, and stub length for realistic nonlinear wheel movement
• Bump stop implementation prevents excessive wheel penetration into the vehicle body and improves weight distribution behavior
• Anti-dive controls how much the vehicle’s front end compresses during braking
• Anti-squat controls rear suspension compression during acceleration

Tires

• Friction circle
• Pneumatic trail (self-aligning torque)
• Tire relaxation simulation

Aerodynamics

• Two points lift sources(the front and rear of the car)
• Drag force
• Relative world wind source

Assistances

• Input assistance system for enjoying power slides
• ABS and TCS implementation

1.3 Demo/Lite/PRO

There are two versions of the plugin - PRO and Lite. Both of these versions use the same physics model and settings.

The Demo was made entirely on the Lite version of the plugin without using any additional features. The Demo has a time limit of 15 minutes, after which you need to restart it.

2.0. Quick Start

QuickStart scene contains 4 cars ready to use. To select them use F1-F4.

To control cars we use the NslDemo_CarController script.

2.1. QuickStart scene hierarchy

QuickStart scene hierarchy (Pic.1):

• Launcher - contains the NslDemo_QuickStartLauncher component, the main controller of the demo scene. Activates one of 4 cars;
• Main Camera - will follow the target car;
• EventSystem - contains a new InputSystem component;
• Directional Light - a standard scene Light;
• C++ GameObject contains 2 NslDemo components:
• NslGlobalAerodynamics - mandatory component containing global aerodynamic settings;
• NslRuntimeDebug prints c++ log messages to Unity’s debug console.
• RiodeJaneiroDay - 3d models of the scene;
• HUD_ROOT - UI canvas;
• Azura_Race, Toyama_Export, Cheetah_Race, SUV_Race - 4 demo cars.

2.2. Car Creation

General phases:

• Create GameObject (root) with a specific hierarchy or instantiate DummyCar;
• Put and properly locate 3d model of the car, body collider, wheels;
• Link all Transforms to NslCarRoot;
• Create CarUnits Settings or use predefined;
• Link all CarUnits Settings to NslCarRoot;
• Create scripts to control NslCarRoot. As an example, see the predefined NslDemo_CarController script

2.3. Initial Car Adjusting

GameObject structure

Properly structured Transformers are necessary for normal operation of DS-Asset. We need 3 parts:

• Root GameObject that has NslCarRoot component;
• 4 Transforms for wheel mounting. The front axle will be controlled using the steering wheel (rotation around the Y-axis). The rear axle cannot rotate. Wheel_FL/FR/RL/RR in Pic.1;
• 4 Transforms for disk mounting (rotation around the X-axis). SpinningDisk_FL/FR/RL/RR in Pic.1.

Quick start

To speed up the process of creating GameObjects, you can create a pre-structured GameObject (DummyCar) (Pic.1) using the HierarchyMenu ➡ NSL ➡ “Create‌‌‌‌ Dummy Car” button (see ).

DummyCar contains:

• NslCarRoot and Rigidbody components in the root GameObject;
• GroundPlane – Temporary plane at the point (0,0,0) that can be deleted and is used to determine the position of the car body relative to the ground;
• Body – GameObject represents a solid car body. It has a BoxCollider component. Instead of this GameObject, you should put your own 3D model of the car and position the Collider correctly (see Using own 3D-model section);
• Wheel_FL/FR/RL/RR – GameObjects represent the position of the wheel attachment relative to the car body (Pic.2);
• SpinningDisk_FL/FR/RL/RR – GameObjects under corresponding Wheel_FL/FR/RL/RR GameObjects represent the spinning disks. They must be placed at the point (0,0,0).

Be aware that the NslCarRoot component must be correctly linked with the wheel Transforms (Pic.3).

Be aware that by default the NslCarRoot doesn’t have any linked Settings (Pic.4). How to set up CarUnit Settings please see the Car Settings section.

For more information see the NslCarRoot section.

2.4 Using own 3D-model

• First of all, your 3D model must be adapted to Unity's 3D coordinate system. This means that the direction of the right axis of your 3D model must match the direction of the right axis in Unity 3D, and the same applies to the other axes.



• Drag your model prefab into the scene. Let's replace the body of your car.
• Unfold the gameobject “DummyCar”.



• “GroundPlane” - a temporary plane at the point (0,0,0) that can be deleted and is used to determine the position of the car body relative to the ground.
• Instead of the “Body”, you should place your 3D car model.
• Delete the “GroundPlane” and ‘Body’ game objects from “DummyCar” (optionally).
• Unpack the model prefab completely so that it becomes editable. To do this: right-click on the finished model ➡ Prefab ➡ Unpack Completely.



• Drag the unpacked gameobject under the “DummyCar” hierarchy.
• Select the “Body” gameobject in the “Azure” hierarchy and add a ‘MeshCollider’ to it. Enable the “Convex” option. Now we have a primary collider for the car.



• The next step is to attach the wheels. Expand the original wheel gameobjects and delete the wheel templates from them. In the following screenshot, game objects have been selected for deletion.





• As you can see, the wheel transforms are already binded. We will use the existing transforms, simply adjusting their origin positions to match our new model. To do this, we will simply copy the model's wheel positions to the corresponding wheel initial transforms.
• The wheel placeholders have been set up. Now we need to properly put the wheels from our 3D model. The wheel rim and tire should be placed under the transformation that was set in the “U_Spinning Disk Transform XX” field. And the brake disc should be placed under the transformation that was set in the “U_Steering Transform XX” field.
• After rearrangement, the hierarchy will look as follows:

2.5. Configuring the inertia tensor

• Select the created “Substep Physics” setting. Here we use two specific fields, “Rigidbody Size” and “U_Rigidbody_Size_Gizmos_Offset” to configure the inertia tensor.

“Rigidbody Size” is used to determine the dimensions of the virtual cube, which should replicate the shape of the vehicle body.

“U_Rigidbody_Size_Gizmos_Offset” is used to adjust the display of the cube volume. This field is not used in physical calculations; it is only used for virtual display to align the cube volume with the vehicle body volume.

• Let's take a look at the suspension settings. They include a field called “RightWheelMountOffset,” which has a default value of zero. This value determines the mirrored position of the wheels relative to the x-axis. The easiest way to adjust the position of the wheels is to copy the position of the right front and rear wheels to the corresponding suspension settings.



• Now the wheels are attached correctly.
• If necessary, you can adjust the wheel radius in the wheel settings.

2.6 Assign Car Settings

One of the purposes of NslCarRoot is to be a CarUnits settings container (Pic.1). Each CarUnit is responsible for a specific logic and has the corresponding settings (ScriptableObject file) (Pic.2).

CarUnit settings can be created individually or all at once with a single click (see ).

CarUnit settings can be grouped into a container - NslCarSettingsContainer.Quick start: We can assign all CarUnits Settings with a single click NslCarRoot ➡ Settings section ➡ “Load Settings Container”. The window contains all possible SettingsContainers in the project (see ).

2.7 Before Launch

Simply, NslCarRoot has several purposes:

• Container of CarUnits settings that will be transferred to the C++ level;
• Container of data that are used between Unity and the C++ level (the DataStructs section contains all data structs used for communication).
• Contains methods for communication between Unity and the C++ level.

Be aware that NslCarRoot doesn’t implement Unity’s FixedUpdate method. For this we have the NslCarRoot::ExecuteFixedUpdate method that is called outside.

• Add the NslDemo_CarController component to the same GameObject as the NslCarRoot (Pic.1). It enables/disables CarBrain, passes Unity’s FixedUpdate event, implements simple manual/automatic transmission logic and passes input data. Check the “Auto start car” box.
• Add the NslDemo_CarCamera to camera GameObject. This script follows the target car (Pic.2).

3.0 Tuning Tips

3.1 Understeering and Oversteering

To describe the approach to quick and effective car tuning, we will use two basic terms: understeer and oversteer. These two terms describe a tendency toward excessive maneuverability or, conversely. These characteristics can manifest themselves during various driving conditions: braking, acceleration, or cornering.

But what does it mean indeed?

In fact, it is simply the balance of traction between the front and rear axles. When the front wheels lose traction, it is called understeer, and when the rear wheels lose traction, it is called oversteer.

When the tires generate lateral (side) forces, these forces act on the car’s center of mass through a lever arm, creating a rotational torque. This torque causes the car to rotate, aligning one end of the vehicle toward the direction of the force generated by the tires.

If the dominant torque is produced at the front axle, the car tends to rotate more sharply than intended, resulting in oversteer. Conversely, if the dominant torque is generated at the rear axle, the effect is opposite, leading to understeer.

Listed below are the most common factors that affect a vehicle's handling:

3.2 Slip Length

Slip length is the key value of the tire settings. It defines the maximum of normalized slip length. By default it equals 1.0.

What does this mean in practice? A tire cannot withstand both longitudinal and lateral slip at the same time. The weaker direction of slip will be suppressed by the stronger one. This directly affects how the tire generates longitudinal and lateral forces.

Let's look at a few examples:

• When accelerating from a standstill, the tyre experiences significant longitudinal slip. In this case, the longitudinal slip almost completely suppresses the lateral slip and, as a result, reduces the lateral force. This can lead to excessive oversteer in powerful rear-wheel-drive cars.

• The car is drifting sideways. In this case tires are experienced by a huge lateral slip, which almost completely suppresses a longitude slip. It leads to a non responsive braking or accelerating during the power slide.

• The vehicle is driving in normal conditions. Longitudinal and lateral slip do not exceed their peak values. In this case, the slip does not normalize, and the tyre can simultaneously generate maximum longitudinal and lateral forces.

Increasing or decreasing the slip length allows you to widen or narrow the range within which normalisation will be performed.

3.3 Nominal Load

The main feature of the tire is that it cannot sustain the same load when the load is increased. In tire settings are used two parameters: nominal load and load friction factor for longitude and lateral force. These two parameters determine how the tire will respond to the load.

Pic. 4 shows how the tire responds to a linear increase in load. It can be observed that the load does not increase in line with the net load. At some point, the tire will no longer be able to withstand the load, which corresponds to the net load.

4.0 Gizmos

The suspension system is one of the key elements of a car's handling. Depending on how you set it up, the car will behave differently.

Gizmos is a visual assistant that allows you to immediately see the current Suspension Settings (Pic.1).

To change the color of the Gizmos, open the menu: TopMenu ➡ Edit ➡ Preferences ➡ Nsl (see ).

To enable/disable specific Gizmos drawing open the menu: #Scene ➡ ⋮ ➡ ”Overlay Menu” ➡ ”Show Nsl Gizmos” (see).

Tip: Press the backtick key (`) anywhere in the scene viewport to open the “Overlays Menu”.

5.0 Rigidbody

The Rigidbody component will be automatically added to the same GameObject where the NslCarRoot component is located.

Be aware that the UseGravity field must be unchecked. All gravity logic is calculated at the C++ level by the DS plugin.

Be aware that for the car to behave correctly, the “Drag” and “Angular Drag” fields must have a value of 0.

6.0 Scripts

6.1 NslCarRoot

NslCarRoot is the main component that must be placed on the root GameObject.

On the same layer also must be Rigidbody (it will be automatically added via RequireComponent attribute).

NslCarRoot is a CarUnits Settings container and a bridge between C# and C++ levels (that are linked via DataIn/Out).

Debug

Enable passing regular messages from the C++ level to C#.

NOTE: NslRuntimeDebug component must be added to any GameObject to see.

Physics

Substeps

Number of physical sub-steps. Increasing the number of sub-steps breaks down the main physics cycle into sub-cycles with shorter time periods. One sub-step means that physics is performed in one cycle.

This approach improves the stability and accuracy of physics performance, especially at low frame rates or during high-speed movement.

Raycast

This block contains settings for wheel raycasts. The specified settings apply to all wheels equally.

Query Trigger Interaction

Controls whether the wheel's raycast will detect triggers or not.

Layer Mask

The layer mask is used to filter colliders that the wheel raycast can hit.

Settings

This block contains serializable fields with vehicle settings. Each field must contain the appropriate setting for initialization and physics startup.

Load Settings Container

A functional button that allows you to apply all car settings from CarSettingsContainer. Pressing the button opens a drop-down menu with a list of all CarSettingsContainers contained in the project.

Wheels

This block contains serializable fields with transforms to synchronize the visual movement of the wheels with the simulation results.

Steering Transform XX

For the assigned transform, the world position and world rotation of the steering movement are applied.

Spinning Disk Transform XX

Only local rotation of the spinning disc is used for the assigned transform.

💡The tip: The same transforms cannot be assigned as both a “Steering” and “Spinning Disk” transform. The most appropriate way to assign transforms is when the parent transform is “Steering" and the child transform is “Spinning Disk”.

6.2 Data structures

Data structures are the communication layer between your Unity code and the Driving Simulator native physics engine. Use this section to identify when each value is written or read, then refer to the grouped field reference for detailed telemetry.

Inputs — write before the physics update

InDataContainer

Contains fields that must be filled with current input data before each NslCarRoot::ExecuteFixedUpdate call.

Outputs — read after the physics update

OutData_Container

This container holds runtime telemetry. It is updated during every substep; after the update, read the values recorded in the final substep.

Position labels: FL = front-left, FR = front-right, RL = rear-left, RR = rear-right. Structures marked Front / Rear are available per axle.

Powertrain

OutData_Axle (Front / Rear)

OutData_Chassis

OutData_Engine

OutData_Clutch

OutData_Gearbox

OutData_Input

OutData_InterWheelDifferential (Front / Rear)

OutData_RootDifferential

Vehicle body

OutData_Rigidbody

Wheels, steering and suspension

OutData_Steering

OutData_Suspension (Front / Rear)

OutData_Tire (FL/FR/RL/RR)

OutData_Transmission

OutData_Wheel (FL/FR/RL/RR)

Environment and driver assistance

OutData_Aerodynamic

OutData_ElectronicAssistance

Unity physics bridge

InRaycasterData

Contains data from C++ for UnityEngine.Physics.Raycast(Ray). It is automatically pinned and filled before calling Raycast().

OutRaycasterData

Contains the Unity raycast result. You can modify these values before the native simulation processes them.

Rigidbody configuration

OutData_CarRootRigidbodyData

Contains the current status of the car Rigidbody.

Automatically filled in NslCarRoot.ExecuteFixedUpdate.

Transmission commands

TransmissionRequest

Request object used to change the gearbox state.

6.3 NslDLL

NslDllBridge is a method container for interacting with the C++ layer.

Depending on the plugin version (Demo, Lite, PRO), the methods are different.

Most of the methods return NslResultCode.

NslDllApi is a method container with a more user-friendly interface. Mostly you should work with it.

If the method cannot process the command correctly, C++ returns an error that is automatically displayed in the console.

6.4 NslCarSettingsContainer

CarSettingsContainer is a base class for grouping CarUnit settings.

Additional logic may also be invoked when applying settings.

When the LoadSettings window is open, it displays all existing settings groups in the project.

CarSettingsContainer_All

SettingsContainer that groups all CarUnit settings. It can be useful for instantly applying all vehicle settings in CarRoot without having to do so separately.

To create new SettingsContainer: ProjectContextMenu ➡ Create ➡ Nsl ➡ Scriptable ➡ Settings Container ->CarSettingsContainer_All (see ).

By pressing the “Create all settings” button in the created SettingsContainer, a corresponding CarUnit Settings ScriptableObject file will be created and linked for each field.

Create All Settings

A functional button that allows you to immediately create all default settings for the car in the currently open project folder and automatically link them in the current container.

6.5 PhysicsCaster

PhysicsCaster is a class that does communication between Unity and c++ level.

This class is responsible for:

• Recognizing wheels position every FixedUpdate relative to the ground.
• Receives the start pose for ray casting, performs it and puts the result into OutRaycasterData.

📝Tips:

You can modify the data before putting it into OutRaycasterData. For example, you can add a noise/bounce effect from small stones.

6.6 NslRuntimeDebug

To receive messages from C++, the NslRuntimeDebug component must be added to any GameObject.

C++ communicate with C# via log file. NslRuntimeDebug reads the log file and broadcasts messages to the Unity console.

💡Keep in mind that all error messages are automatically transferred to the log file. If you also want to see regular informational messages, you need to enable them in CarRoot (NslCarRoot/DebugData - P00_ShowNativeLogs).

6.7 Errors

NslErrorCode

Contains all error codes that may occur at the C++ level.

7.0 Settings

Car-unit settings define how each simulator system behaves. Configure them before starting the physics simulation, then tune one subsystem at a time.

7.1 GlobalAerodynamics

Scene requirement: add this component to every scene that creates vehicle instances; otherwise the native simulation cannot start.

7.2 CarUnits

Each CarUnit owns a focused group of settings. Fields below are grouped by the simulator system they configure.

Aerodynamics

Axle

Clutch — main settings

Controls engine-to-transmission coupling. The auto-clutch smoothly starts the car and prevents excessive engine-speed drops.

Clutch — shifting time profile

Defines the three phases used for a smooth gear change: press, hold, then release the clutch.

Differential — inter-axle

Limited-slip differential that distributes torque between the front and rear axles.

Differential — inter-wheel

Limited-slip differential between the left and right wheels on one axle. It uses the same core behaviour as the inter-axle differential.

Electronic assistance

Engine — boost settings

Each array element describes one turbo/boost unit.

Engine — main settings

Engine — auto blip

Auto blip operates separately for downshifts, upshifts, and reverse. Each action reaches a target throttle, holds it, then releases it.

Engine — torque curve

Gearbox

Input

Steering

Substep physics

Suspension

Controls wheel placement, ride comfort, stability, weight transfer, and steering response.

Tire — general data

Tire — lateral friction

Tire — longitudinal friction

Wheel

8.0 Demo

8.1 Car Presets

The demo scene features four cars, each with its own unique characteristics.

Azure

Key Features:

• Entry-to-mid-level sport car.
• FWD Drive Type.
• Fully Open Differential
• Moderately soft suspension.
• Has no aerodynamic down force.
• Tends to understeering
• Equipped by one turbo

Toyama

Key Features:

• Performance sports car.
• RWD Drive Type.
• Limited Slip Differential
• Rigid suspension.
• Has no aerodynamic down force.
• Tends to oversteering
• Equipped by one turbo

Cheetah

Key Features:

• Supercar.
• RWD Drive Type.
• Limited Slip Differential
• Suspension with a high stiffness.
• Aerodynamic down force impact on the rear end car.
• Tends to oversteering
• Equipped by twin turbo

SUV

Key Features:

• SUV.
• AWD Drive Type.
• Limited-slip differential, including an inter-axle differential.
• Soft suspension.
• Has no aerodynamic down force.
• Tends to understeering
• Natural aspired engine.

8.2 NslDemo_Scripts

Here are some examples of scripts that interact with the plugin core. It is very helpful to review them before creating your own scripts.

NslDemo_CarController

This is the most important script. Without it, the car won't run.

This script is responsible for:

• Interaction with the native plugin (creating an instance, applying settings, running dedicated physics, stopping physics execution, and disposing the instance)
• Binds the vehicle controls to the input schema(“NslDemo_InputScheme”)
• Performs the implementation of manual or automatic transmission.

Serialized Properties:

IsGearboxManual

Selects the drive mode for a manual or automatic transmission.

AutoStartCar

This option allows you to launch a car instance from "Start()" callback.

NslDemo_CarCamera

Simple implementation of target-following logic.

NslDemo_InputScheme

It is an input action asset of Unity “Input System”. Here is a stored keymap which is used in the demo.

SkidMarkFx

Implementation of an algorithm for producing skid marks based on tyre slip length.

Car Sfx

The scripts below demonstrate how to create various sound effects. You can look into applying these scripts on the demo scene. They are applied on the "Car SFX" prefab which is attached to the car.

UnitTest_CarSfx_Engine

A simple implementation of engine sound that uses only a single sound loop. The sound dynamic response is achieved by tracking engine RPM and predefined engine settings.

UnitTest_CarSfx_Wind

In this implementation, the wind noise level is determined based on the current speed of the vehicle.

UnitTest_CarSfx_Gearbox

This script simply plays sound effects that indicate gear shifts.

UnitTest_CarSfx_TireSkid

It reproduces the sound of wheels rolling by using the highest slip length among the wheels.

SensorInputDevice

In the demo version, data entry from the screen is implemented using the Input System. As part of this approach, a custom input device was implemented with specific controls that can be bound in the Action Asset.

SensorInputDevice

Custom input control layout.

SensorInputDeviceState

Specific struct which contains the state of controls.

SensorInputDeviceHud

The MonoBehaviour class, which handles callbacks from user interface elements and propagates signals to the control layout.