Traffic Car

How To Create
Vehicle Physics Types
Common Authoring Components
CullState Info
- States
Avoidance
Entity Selection
- Pure DOTS
- Hybrid Mono
Rail Movement
Obstacle Detection
- Raycast
Obstacle Avoidance
Left-hand Drive
Pathfinding
- Custom Point
- Custom Node

How To Create 

Create a vehicle using the Car Prefab Creator tool (for example Simple physics entity type, if you need traffic with controller based on MonoBehaviour, read this article).

Car Prefab Creator final step example.
Make sure, that the vehicle collection contains vehicle you have created.
Make sure, that the preset contains the vehicle.
Open the Traffic settings and select the Simple physics entity type (if you have created a Simple physics entity).
Open the Hub object in the scene and press the Copy To Subscene button.
Open the EntitySubScene, find the TrafficCarEntityPoolBakerRef gameobject on the main & subscene, make sure the correct preset is assigned to both scenes.
Adjust the traffic settings of the created vehicles.
- For Simple physics.
- For Custom physics.

Vehicle Physics Types 

Simple Physics 

Entities moved by the simple physical system (by simply adding the physics velocity to the physics body).
Settings.
Hybrid entity simple physics & Pure entity simple physics types refer to this.

Authoring components 

CarWheelAuthoring 

Wheel base : wheel radius.
All wheels : all wheels of the vehicle.
Steering wheels : wheels that can turn.

PhysicsShape 

Example

Optional components if the car moves with physics.

No Physics 

Pure entities that moved by transform system without physics.
Contains the same components as Simple Physics.
Settings.
Pure entity no physics type refer to this.

Hybrid Mono 

Before using this vehicle type, make sure that you selected World simulation type to Hybrid mono in the General settings.
Hybrid entities that moved by custom monobehaviour controller.
Hybrid entity mono physics type refer to this.

Arcade (built-in sample)

If you want to use Arcade’s built-in sample controller, follow these steps:

Open the Car Prefab Creator tool.
Select Prefab tab.
Set Car type to Traffic.
Drag & drop your prefabs into the prefabs field (make sure your source Prefabs don’t have any Colliders, Wheel colliders & Rigidbodies).
Press Scan button.
Select Save tab.
Set Entity type to Hybrid entity mono physics.
Set Controller type to Arcade.
Set desired preset. Also hull & save paths.
Select Prefab info tab.
Customize hull & wheel offsets.
Customize traffic related settings.
Press Create button.
In the ArcadeVehicleController, make sure the raycast layer matches your Ground layer.
Open the EntitySubScene, find the TrafficCarEntityPoolBakerRef gameobject on the main & subscene, make sure the correct preset is assigned to both scenes.

Custom user controller 

If you want to use your own custom solution, follow these steps:

Open the Car Prefab Creator tool.
Select Prefab tab.
Set Car type to Traffic.
Drag & drop your prefabs into the prefabs field.
Press Scan button.
Select Save tab.
Set Entity type to Hybrid entity mono physics.
Set Controller type to Custom user.
Create script that implements IVehicleInput interface to link traffic input & your vehicle controller input (code example below)
Assign created script into the Input script field.
Set desired preset. Also hull & save paths.
Select Prefab info tab.
Set the steering angle to match the steering of your custom car controller.
Customize traffic related settings.
Press Create button.
To set your own custom Car Controller parameters to handle the most common traffic situations, use the Traffic test scene.
Open the EntitySubScene, find the TrafficCarEntityPoolBakerRef gameobject on the main & subscene, make sure the correct preset is assigned to both scenes.

Input info 

Throttle [1] : forward motion.
Throttle [-1] : reverse motion.
Throttle [0] : hand brake.
Throttle [-0.9] : braking, for example, if the current speed is higher than permitted. (the value can be changed in the Traffic settings)
Steering [-1, 1]

VehicleInput example code 

public class UVC_adapter : MonoBehaviour, IVehicleInput
{
        // Replace by your custom controller script.
        // The example uses a "Universal Vehicle Controller".
        // https://assetstore.unity.com/packages/tools/physics/universal-vehicle-controller-plus-176314
        public UVC_AIControl carControllerInput;

        public float Throttle
        {
                get => carControllerInput.Acceleration;
                set
                {
                        if (value > 0)
                        {
                                carControllerInput.SetAcceleration(value);
                                carControllerInput.SetBrakeReverse(0);
                                carControllerInput.SetHandBrake(false);
                        }
                        else
                        {
                                carControllerInput.SetAcceleration(0);
                                carControllerInput.SetBrakeReverse(Mathf.Abs(value));

                                if (value == 0)
                                        carControllerInput.SetHandBrake(true);
                        }
                }
        }

        public float Steering { get => carControllerInput.Horizontal; set => carControllerInput.SetSteer(value); }
        public bool Handbrake { get => carControllerInput.HandBrake; set => carControllerInput.SetHandBrake(value); }

        public void SwitchEnabledState(bool isEnabled)
        {
                carControllerInput.enabled = isEnabled;
        }
}

Car Player Blocker 

The CarPlayerBlocker component is designed specifically for Hybrid Mono vehicles. It prevents a custom player physics controller from pushing or moving AI traffic vehicles upon collision.

It achieves this by dynamically creating an independent kinematic collider on a dedicated physics layer. This layer forces the player’s controller to recognize the traffic car as an immovable obstacle, while the traffic car itself ignores this internal blocker collider to prevent self-jittering.

Note

This component works only for vehicles with the Hybrid entity mono physics type. It does not affect Pure DOTS entities.

How It Works 

Editor Generation: The editor script copies the dimensions and center boundaries of your vehicle’s main source collider (supports BoxCollider or MeshCollider).
Layer Isolation: It places this newly generated box collider onto a custom physics layer (e.g., PlayerBlocker).
Kinematic Rigidbody: A kinematic Rigidbody is automatically attached to the blocker object, making it completely unyielding to the player’s physical forces.
Collision Filtering: At runtime (in Awake), the script automatically configures Unity’s physics engine to ignore collisions between the vehicle’s driving colliders and this blocker collider.

Inspector Parameters 

Source Collider : The main physical collider of the traffic vehicle.
Player Blocker Layer : The physics layer intended to collide exclusively with your Player Controller.
Size Offset : Additional padding added to the blocker collider dimensions to detect or block the player slightly outside the mesh bounds.
Physics Switcher : Reference to the PhysicsSwitcher component to properly reset and synchronize collider states during culling.
Created Collider : The automatically generated BoxCollider slot.

Step-by-Step Configuration 

Follow these steps to set up the blocker for your vehicles:

Create a New Layer: Open your Unity project settings and add a new layer (e.g., name it PlayerBlocker).
Attach the Component: Add the CarPlayerBlocker component to your vehicle’s hull prefab.
Configure the Blocker:
- Assign the Source Collider and the Physics Switcher.
- Set the Player Blocker Layer to the layer you created in Step 1.
- Click the Create button in the inspector. This will spawn a child GameObject named PlayerBlocker with a box collider and a kinematic rigidbody.
Configure the Layer Collision Matrix:
- Navigate to Project Settings -> Physics.
- Locate the Layer Collision Matrix grid.
- For the PlayerBlocker layer, untick all checkboxes except for the layer used by your Player character/vehicle controller.

Note

This matrix setup ensures the blocker collider interacts only with the player and remains completely invisible to traffic, NPCs, raycasts, and ground physics layers.

Components 

CarEntityAdapter

Component to syncronize gameobject & entity, also to switch physics & scripts of the vehicle when cull state changes with PhysicsSwitcher & ScriptSwitcher components.

Note

You can turn off traffic physics culling in the Traffic settings.

PhysicsSwitcher

Component to on/off physics of the vehicle.

ScriptSwitcher

Component to on/off scripts of the vehicle.

Common Authoring Components 

TrafficCarEntityAuthoring 

Main component of traffic entity [required].

Hull mesh renderer : vehicle hull mesh renderer reference.
Physics shape : vehicle entity PhysicsShape reference.
Faction type : selected faction type of vehicle.
Car type : selected car type of vehicle.
Bounds source type : selected bounds source for the entity bounds.
Traffic group : selected traffic group.

Shared Settings 

Each vehicle has a common set of settings that are described here

NavMeshObstacleAuthoring 

NavMeshObstacleData entity component for runtime loading of NavMeshObstacle objects for pedestrian navigation. Make sure, that option is enabled in the traffic settings [optional].

CarSoundAuthoring 

Component for vehicle sounds [optional].

HealthAuthoring 

Vehicle health component for damage system (DOTS only) [optional].

CarDamageEngineAuthoring 

Component for visual presentation of damage in the damage systems (DOTS only) [optional].

PlayerTargetAuthoring 

Component for player targeting systems [optional].

CullState Info 

States 

Culled : entity is destroyed.
CloseToCamera:
- Cull physics (if enabled) : custom physics & simple physics temporarily converted to no physics entity.
- Cull wheel (if enabled) : disabling wheel rotating.
InVisionOfCamera : entity fully enabled.

Avoidance 

Avoidance is used in the case of stuck vehicles.

Currently enabled in the following situations:

A cyclical obstacle where cars get stuck in each other (avoidance config).
A car has collided frontally with another car (collision config).

Cyclical obstacle example.

Avoiding cyclical obstacle example.

Note

Test scene example.

Entity Selection 

Entity can be retrieved using one of these methods:

Pure DOTS 

Create a new gameobject with EntitySelectionService component

Use world position to get the nearest entity for that position.

public Entity TryToSelectEntity(Vector3 worldPosition)
{
        return EntitySelectionService.Instance.SelectEntity(worldPosition, EntityType.Traffic, 1f);
}

Hybrid Mono 

Entity can be retrieved if the car has a collider:

private Entity GetEntity()
{
        Entity entity = Entity.Null;

    if (Physics.Raycast(transform.position, Vector3.forward, out hit, 1.0f))
        {
                var hybridEntityRef = hit.collider.GetComponent<IHybridEntityRef>();
                entity = hybridEntityRef.RelatedEntity;
        }

        return entity;
}

Rail Movement 

The Rail movement is used to drive the vehicle precisely along the path, which can be useful in small enclosed parking areas, for example. To enable rail movement, tick on the Rail parameter in the path settings. Open the rail config to adjust the Rail parameters (DOTS only).

Note

Enabled by default for trams.

Obstacle Detection 

Raycast 

Config

TrafficCarRaycastConfig.

Debugger

TrafficCarRaycastDebugger.

Modes

Hybrid mode : raycast is activated only when the selected targets are close to the car.
Raycast only : raycasts are sent constantly.

To define raycast targets for Hybrid or Raycast only modes, redefine the GetTargetQuery method in the TrafficCarRaycastObstacleTargetQueryProvider class, which returns the EntityQuery of the targets.

public static EntityQuery GetTargetQuery(
                   SystemBase sourceSystem,
                   TrafficCarDetectObstacleMode trafficCarDetectObstacleMode,
                   TrafficCarDetectNpcMode trafficCarDetectNpcMode,
                   out CollisionFilter tempRaycastCollisionFilter,
                   out CollisionFilter raycastAlwaysCollisionFilter);

TrafficCarDetectObstacleMode.
TrafficCarDetectNpcMode.
Hybrid Mode Filter : collision filter of hybrid raycast mode.
Raycast Only Filter : collision filter of raycast only mode.
Note
- You can also dynamically change the raycast target for Hybrid mode by adding or removing the TrafficCustomRaycastTargetTag component.
- Layer constants are stored in the ProjectConstants.cs file.

Obstacle Avoidance 

If you want the traffic to avoid obstacles, follow these steps:

Make sure that obstacle detection is set to either Hybrid or Raycast in the Traffic config.
Ensure that Advanced avoidance is enabled in the Collision config.
Make sure that the traffic Raycast config includes an obstacle layer.
Add components to the obstacle object from the example below, depending on the type of obstacle.

Player Character 

Note

Make sure that Player Npc Hybrid Component is removed.

Find & open ProjectConstants script.
Change the LaneHandDirection variable to -1.

Note

Changing this parameter will only affect newly created scenes. Old scenes with a different lane direction will not work.

Pathfinding 

Custom Point 

To set a custom destination for a specific traffic car, do the following:

Create a new gameobject with EntitySelectionService component.
Create a new gameobject with TrafficCustomPathService component.

Use this sample code:

private void Awake()
{
        PathHashMapSystem.Register();
}

public void SetEntity(Vector3 trafficPosition, Vector3 destination)
{
        var trafficEntity = EntitySelectionService.Instance.SelectEntity(trafficPosition, EntitySelectionService.EntityType.Traffic, 2f);
        TrafficCustomPathService.Instance.SetFollowPath(trafficEntity, destination);
}

Use the OnStatusUpdated callback in TrafficCustomPathService to listen to the current state of the traffic car’s pathfinding.

Custom Node 

To set a custom node destination for a specific traffic car, do the following:

Create a new gameobject with EntitySelectionService component.
Create a new gameobject with TrafficCustomPathService component.

Use this sample code:

private void Awake()
{
        PathHashMapSystem.Register();
}

public void SetEntity(Vector3 trafficPosition, Vector3 destination)
{
        var trafficEntity = EntitySelectionService.Instance.SelectEntity(trafficPosition, EntitySelectionService.EntityType.Traffic, 2f);
        var destinationPath = PathHashMapSystem.GetClosestPath(destination);

        TrafficCustomPathService.Instance.SetFollowPath(trafficEntity, destinationPath);
}

Use the OnStatusUpdated callback in TrafficCustomPathService to listen to the current state of the traffic car’s pathfinding.
As an alternative, you can check the TrafficPathSelector prefab for an interactive user-selected path used in the RuntimeTileRoad Demo scene (runtime sample should be imported & RUNTIME_ROAD scripting define added).