Template Car Generator

Vehicles in BeamNG are made using JBeam files for defining a physical skeleton using mass points (nodes) and flexible spring-damper connections (beams). The visual skin is defined using DAE files and is connected to this physical skeleton. It can be challenging and time-consuming for new users to create a vehicle using this bottom-up approach.

The Template Car Generator is a tool that helps users to get started quickly by creating simple vehicles based on high-level vehicle parameters, such as total mass, basic geometry like wheelbase, track width and height, as well as suspension type and body shape. The user can make multiple vehicle configurations (user input). These user inputs are used by the tool to automatically generate a set of JBeam and DAE files (output files) that meet the user-defined requirements. The generated output files are saved in the user’s mod directory and can directly be used in BeamNG.

The generated JBeam files are kept as simple as possible, so that more experienced users can also use them as a starting point to modify the vehicle further and adjust its physical behavior in detail.

The Template Car Generator is the parameterizable enhancement of the Template Car available since BeamNG.tech v0.36. You can still use this car if you don’t need parameter adjustments.

Installation

The Template Car Generator is shipped with BeamNGpy . Note that Python 3.9 or newer must be installed on your system. The simplest way to install BeamNGpy is by opening a terminal and running the following command:

pip install beamngpy

For more installation options, refer to the BeamNGpy documentation .

Starting the application

Make sure that you have started BeamNG.tech at least once before starting the application. Close BeamNG.tech if it is running.

It is recommended to create a Desktop shortcut to the application by running:

python -m beamngpy.tools.template_car --create-shortcut

Then you can launch the application by double-clicking on the shortcut on the Desktop. Note that this will only work if beamngpy is installed in the global Python environment.

Alternatively, you can always start the application by running:

python -m beamngpy.tools.template_car

This works in any Python environment.

After starting the application, a window like the one shown below will open.

Template Car Generator welcome screen

Settings

You can change general application settings by clicking on Settings in the lower left corner.

• If you want to use a custom BeamNG user folder to store the generated vehicle JBeam files, change the BeamNG user folder path setting to your custom user folder path (to use the default folder leave it blank).
• You can also use a custom folder to store your template vehicle configuration files by setting the Template vehicles folder path to any custom folder. By default these are stored in %LOCALAPPDATA%/BeamNG/TemplateCarGenerator/vehicles.
• If you want to use a custom installation path for BeamNG.tech, change the BeamNG installation path accordingly.

By default those application settings are stored in the %LOCALAPPDATA%/BeamNG/TemplateCarGenerator/settings.json file. If you want to start the application using a different settings file, you can start it with python -m beamngpy.tools.template_car --settings-file path/to/settings.json.

The settings screen

On the settings screen you can also find a few convenience links to open the settings file, vehicle configurations folder and mods folder.

How to use

The vehicle screen

Use the section numbers (1–8) to follow along with the UI layout in the tool.

1. Creating a new vehicle

Click on Create vehicle to create a new vehicle. Enter the vehicle name in the popup screen and click on Create vehicle. This initial name will be used to generate the vehicle ID.

2. Vehicle name

You can change the name of your vehicle here.

3. Structure and Parameters

Configure vehicle structure and parameters:

• Select body shape, front, and rear suspension from the dropdown.
• Set values for: wheelbase, track width, front/rear overhang, body width, and body height.

4. Target value optimization

Controls for:

• Mass
• Center of gravity longitudinal (y)
• Center of gravity height (z)

Toggle these between:

• Factor for instant generation.
• Target to start an optimization loop that adjusts factors to match the target value you define.

Limitations:

• Very high or low mass/CG targets may cause instability or crashes due to inherent limits of JBeam from large node mass differences at either end of a beam.

When optimization is required, a log shows progress on the optimization loop, giving information on how many iterations have been done and how far away from the target the loop is currently at.

5. Generate or Optimize

• Press Generate when all optimization values are set to Factor. This will result in an instant generation of the vehicle.
• Press Optimize when at least one is set to Target. This will result in the optimization loop starting, which will take a while to satisfy the targets.

6. Play

Spawns the car in Grid Small Pure in BeamNG for quick testing. Alternatively, you can also launch BeamNG yourself and select the vehicle in the Vehicle Selector.

7. Open file and Reload file

• Open file: Edit the vehicle configuration JSON file in a text editor.
• Reload file: Reload the currently selected vehicle configuration JSON file from disk.

The generated files are designed in a manner that are easy to modify for beginners. Some modification will be necessary to fine tune the suspension if the centre of gravity location has been moved or if the mass has changed significantly.

8. Delete vehicle

Removes the selected vehicle configuration from the sidebar and moves the corresponding JSON file to the trash bin.

How optimization works

The generation algorithm to generate the JBeam files has several scalar tuning factors that influence node mass and node mass distribution:

• a mass factor scales the mass of all body nodes, which influences the total vehicle mass
• a longitudinal (y) factor influences how node masses are distributed along the y-axis, influencing the center of gravity location in y-direction
• a height (z) factor influences how node masses are distributed along the z-axis, influencing the center of gravity location in z-direction

The user can set these factors directly when choosing Factor. In this case the factor is applied directly to the generation algorithm, but the outcome (actual vehicle mass and center of gravity) is not directly settable by the user.

If the user chooses Target, then then a physical value (in meters or kilograms) is entered and the generation algorithm is run iteratively, adjusting the scaling factors until the target value is reached. Note that BeamNG is launched during this process because the physics engine is needed to calculate the actual values of mass and center of gravity. For the center of gravity the vehicle is spawned and then settles to its equilibrium position before the actual value is measured.

Advanced topics

Duplicate a vehicle

Go to the Settings page and click on Open vehicles folder. Then you can duplicate a JSON file and rename it to the desired name. It will show up in the application and you can start modifying it.

Change the ID of a vehicle

Go to the Settings page and click on Open vehicles folder. Then you can rename the corresponding JSON file. Note that only A-Z, a-z, 0-9 and _ are allowed in the vehicle ID.

Use Python scripts to generate vehicles

Read the BeamNGpy documentation of the Template Car Generator API for more information on how to use Python scripts to generate vehicles.

For example, the following script generates all template cars you have defined in the application:

"""Example script to generate all template cars."""
from beamngpy.tools.template_car import TemplateCarGenerator

generator = TemplateCarGenerator()

for vehicle_id in generator.get_vehicle_list():
    vehicle = generator.get_vehicle(vehicle_id)
    generator.generate(vehicle_id, vehicle)
    print(f"Generated {vehicle_id}")
print("All vehicles generated.")

JBeam file conventions

The JBeam files of the template car are designed to follow the following conventions:

• The origin (0, 0, 0) is at the vertical position of the body lower point below the (initial position of the) front axle centerpoint.
• The front axle is the line between nodes fw1r and fw1l and the front axle centerpoint is the middle point between these two nodes.
• The direction of the x-axis (1, 0, 0) is towards the left of the car (when looking at the car from the back). The front axle direction is parallel to the x-axis and the rear axle is parallel to the x-axis at the same z position.
• The direction of the y-axis (0, 1, 0) is towards the back of the car.
• The direction of the z-axis (0, 0, 1) is towards the top of the car.

Note: For the center of gravity (COG) the actual equilibrium position of the front axle centerpoint is used as reference.

Notes for Linux users

On Linux, %LOCALAPPDATA% is replaced by ~/.local/share.

If you get an error message like You must have either QT or GTK with Python extensions installed in order to use pywebview on Linux, please try one of the following:

pip install pywebview[qt]

or

pip install pywebview[gtk]

This should install the necessary dependencies.