This tutorial details how to add a new vehicle to CARLA. There are two sections, one for 4 wheeled vehicles and one for 2 wheeled vehicles. There is an outline of the basic requirements that must be fulfilled when modeling your vehicle to ensure that it works well in CARLA and instructions on configurations required after the vehicle has been imported into Unreal Engine.
Vehicles added to CARLA need to use a __common base skeleton__ which is found [__here__](https://carla-assets.s3.eu-west-3.amazonaws.com/fbx/VehicleSkeleton.rar). This link will download a folder called `VehicleSkeleton.rar` which contains the base skeleton in two different `.fbx` formats, one in ASCII and the other in binary. The format you use will depend on your 3D modeling software requirements.
__The positions of the skeleton bones can be changed but any other manipulation such as rotation, addition of new bones, or changing the current hierarchy will lead to errors. __
This section details the minimum requirements in the modeling stage of your vehicle to make sure it can be used successfully in CARLA. The process involves binding the skeleton correctly to the base and wheels of the vehicle, creating Physical Asset and Collision meshes, and exporting to the correct format.
Bind the bones to the corresponding portions of the vehicle mesh according to the nomenclature below. Make sure to center the wheels' bones within the mesh.
>1. __Bodywork__: The metallic part of the vehicle. This material is changed to Unreal Engine material. Logos and details can be added but, to be visible, they must be painted in a different color by using the alpha channels in the Unreal Engine editor.
- __Glass_Ext__: A layer of glass that allows visibility from the outside to the inside of the vehicle.
- __Glass_Int__: A layer of glass that allows visibility from the inside to the outside of the vehicle.
- __Lights__: Headlights, indicator lights, etc.
- __LightGlass_Ext__: A layer of glass that allows visibility from the outside to the inside of the light.
- __LightGlass_Int__: A layer of glass that allows visibility from the inside to the outside of the light.
- __LicensePlate__: A rectangular plane of 29x12 cm. The texture will be assigned automatically in Unreal Engine.
- __Interior__: Any other details that don't fit in the above sections can go into _Interior_.
Unreal Engine automatically creates LODs but you can also create them manually in your 3D editor. Tri counts are as follows:
- __LOD 0__: 100,000 tris
- __LOD 1__: 80,000 tris
- __LOD 2__: 60,000 tris
- __LOD 3__: 30,000 tris
__4. Create the Physical Asset mesh.__
The Physical Asset mesh is an additional mesh that allows Unreal Engine to calculate the vehicle's physics. It should be as simple as possible, with a reduced number of polygons, and should cover the whole vehicle except for the wheels. See the image below for an example.
The Physical Asset mesh should be exported as a separate `.fbx` file. The final file should fulfill the following requirements:
- Have a base mesh. This should be a copy of the Physical Asset mesh. It should have the same name as the original vehicle.
- The Physical Asset mesh must be named using the format `UCX_<vehicle_name>_<number_of_mesh>`, __otherwise it will not be recognized by Unreal Engine.__
- The mesh must not extend beyond the boundaries of the original model.
- The mesh should have the same position as the original model.
>>
Export the final mesh as an `.fbx` file with the name `SMC_<vehicle_name>.fbx`.
__5. Create the Collision mesh.__
The Collision mesh allows Unreal Engine to identify the vehicle's shape and use that to calculate collisions. This mesh should have a slightly more defined geometry than the Physical Asset mesh.
Consider the following points when creating the Collision mesh:
- The mesh should cover all aspects of the vehicle, including wheels, side mirrors, and grilles.
- The wheels should be cylinders of no more than 16 loops.
- Various meshes can be joined together if required.
- The mesh(es) must not extend beyond the boundaries of the original model.
- The mesh(es) should have the same position as the original.
>>
Export the final mesh as an `.fbx` file with the name `SM_sc_<vehicle_name>.fbx`.
__5. Export the vehicle mesh(es).__
Select all the main vehicle mesh(es) and the skeleton base and export as `.fbx`.
---
### Import and configure the vehicle
This section details the process of importing the vehicle into Unreal Engine for use in CARLA. Perform these steps in the Unreal Engine editor.
__1. Create the vehicle folder.__
Create a new folder named `<vehicle_name>` in `Content/Carla/Static/Vehicles/4Wheeled`.
Inside the new vehicle folder, import your main vehicle skeleton `.fbx` by right-clicking in the **_Content Browser_** and selecting **_Import into Game/Carla/Static/Vehicles/4Wheeled/<vehicle_name\>_**.
>1. In the **_Content Browser_**, right-click inside your vehicle folder and select **_Animation -> Animation Blueprint_**.
- In **_Parent Class_** search for and select `VehicleAnimInstance`.
- In **_Target Skeleton_** search for and select `<vehicle_name>_Skeleton`.
- Press **_OK_** and rename the blueprint as `AnimBP_<vehicle_name>`.
__5. Configure the Animation Blueprint.__
To ease the process of configuring the animation blueprint, we will copy an existing one from a native CARLA vehicle:
>1. Go to `Content/Carla/Static/Vehicle` and choose any CARLA vehicle folder. Open its Animation Blueprint.
- In the **_My Blueprint_** panel, double click on **_AnimGraph_**. You will see the graph come up in the viewport.
- Click and drag to select the **_Mesh Space Ref Pose_**, **_Wheel Handler_**, and **_Component To Local_** components. Right-click and select **_Copy_**.
- Go back to your own vehicle Animation Blueprint and paste the copied contents into the graph area.
- Click and drag from the standing figure in the **_Component To Local_** component to the figure in **_Output Pose_** to join the components together.
- Click **_Compile_** in the top left corner. You should now see a pulsating line flowing through the entire sequence.
>1. In the **_Content Browser_**, go to `Content/Carla/Blueprints/Vehicles` and create a new folder `<vehicle_name>`.
- Inside the folder, right-click and go to **_Blueprint Class_**. Open the **_All Classes_** section in the pop-up.
- Search for `BaseVehiclePawn` and press **_Select_**.
- Rename the file as `BP_<vehicle_name>`.
- Go to the folder of any of the native CARLA vehicles in `Carla/Blueprints/Vehicles`. From the **_Content Browser_**, copy the four wheel blueprints into the blueprint folder for your own vehicle. Rename the files to replace the old vehicle name with your own vehicle name.
>1. In your vehicle blueprint folder, open all four of the wheel blueprints.
- In the **_Class Defaults_** panel, set **_Collision Mesh_** to `Wheel_Shape`.
- Adjust the values for wheel shape radius, width, mass, and damping rate according to your vehicle specifications.
- Set **_Tire Config_** to `CommonTireConfig`
- On the front wheels set **_Steer Angle_** according to your preferences (default is `70`). Uncheck **_Affected by Handbrake_**.
- On the rear wheels set **_Steer Angle_** to `0`. Check **_Affected by Handbrake_**.
- When setting the suspension values, you can use the values [here](tuto_D_customize_vehicle_suspension.md) as a guide.
- Compile and save.
>>
__8. Configure vehicle blueprint.__
>1. From the **_Content Browser_**, open your `BP_<vehicle_name>`.
- In the **_Components_** panel, select **_Mesh (VehicleMesh) (Inherited)_**.
- In the **_Details_** panel, go to **_Skeletal Mesh_** and search for and select the base skeleton file of your vehicle (located in the `Carla/Static/Vehicles/4Wheeled/<vehicle_name>` folder).
- Go to **_Anim Class_** in the **_Details_** panel. Search for and select your `AnimBP_<vehicle_name>` file.
- In the **_Components_** panel, select **_Custom Collision (Inherited)_**.
- Select **_Static Mesh_** in the **_Details_** panel and search for your `SM_sc_<vehicle_name>` collision mesh.
- In the **_Components_** panel, select **_VehicleMovement (MovementComp) (Inherited)_**.
- In the **_Details_** panel, search for `wheel`. You will find settings for each of the wheels. For each one, click on **_Wheel Class_** and search for the `BP_<vehicle_name>_<wheel_name>` file that corresponds to the correct wheel position.
Adding 2 wheeled vehicles is similar to adding a 4 wheeled one but due to the complexity of the animation you'll need to set up aditional bones to guide the driver's animation. [Here](https://carla-assets.s3.eu-west-3.amazonaws.com/fbx/BikeSkeleton.rar) is the link to the reference skeleton for 2 wheeled vehicles.
As with the 4 wheeled vehicles, orient the model towards positive "x" and every bone axis towards
positive x and with the z axis facing upwards.
```yaml
Bone Setup:
- Bike_Rig: # The origin point of the mesh. Place it in the point 0 of the scenecomment
- BikeBody: # The model's body centre.
- Pedals: # If the vehicle is a bike bind the pedalier to this bone, will rotate with the bike acceleration.
- RightPedal: # Sets the driver's feet position and rotates with the pedalier if the vehicle is a bike.
- LeftPedal: # ^
- RearWheel: # Rear Wheel of the vehicle
- Handler: # Rotates with the frontal wheel of the vehicle bind the vehicle handler to it.
- HandlerMidBone: # Positioned over the front wheel bone to orient the handler with the wheel
- HandlerRight: # Sets the position of the driver's hand, no need to bind it to anything.
- HandlerLeft: # ^
- Frontwheel: # Frontal wheel of the vehicle.
- RightHelperRotator: # This four additional bones are here for an obsolete system of making the bike stable by using aditional invisible wheels
- RightHelprWheel: # ^
- LeftHelperRotator: # ^
- LeftHelperWheel: # ^
- Seat: # Sets the position of the drivers hip bone. No need to bind it to anything but place it carefully.
```
__1.__ Import fbx as Skelletal Mesh to its own folder inside `Content/Carla/Static/Vehicles/2Wheeled`. When importing select "General2WheeledVehicleSkeleton" as skelleton A Physics asset should be automatically created and linked.
__2.__ Tune the Physics asset. Delete the automatically created ones and add boxes to the `BikeBody` bone trying to match the shape as possible, make sure generate hit events is enabled.
Add a sphere for each wheel and set their "Physics Type" to "Kinematic".
__4.__ Inside that folder create two blueprint classes derived from "VehicleWheel" class. Call them `<vehicle-model>_FrontWheel` and `<vehicle-model>_RearWheel`. Set their "Shape Radius" to exactly match the mesh wheel radius (careful, radius not diameter). Set their "Tire Config" to "CommonTireConfig". On the front wheel uncheck "Affected by Handbrake" and on the rear wheel set "Steer Angle" to zero.
__5.__ Inside the same folder create a blueprint class derived from `Base2WheeledVehicle` call it `<vehicle-model>`. Open it for edit and select component "Mesh", setup the "Skeletal Mesh"
and the "Anim Class" to the corresponding ones. Then select the VehicleBounds component and set the size to cover vehicle's area as seen from above.
__6.__ Select component "VehicleMovement", under "Vehicle Setup" expand "Wheel Setups", setup each wheel.
*__0:__ Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
*__1:__ Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
*__2:__ Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
*__3:__ Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
(You'll notice that we are basically placing two wheels in each bone. The vehicle class unreal provides does not support vehicles with wheel numbers different from 4 so we had to make it believe the vehicle has 4 wheels)
__7.__ Select the variable "is bike" and tick it if your model is a bike. This will activate the
pedalier rotation. Leave unmarked if you are setting up a motorbike.
__8.__ Find the variable back Rotation and set it as it fit better select the component SkeletalMesh
(The driver) and move it along x axis until its in the seat position.
__9.__ Test it, go to CarlaGameMode blueprint and change "Default Pawn Class" to the newly
