From BeamNG

Revision as of 20:09, 20 December 2016 by TStabbert (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Creating a track for the Quick Play system is actually quite similar to creating a scenario, but all the files are placed in the quickrace/ folder inside the level instead of the scenario/ folder. All the files share a single identifier. This could for example be industrial_rc_eight,skycurve2 or something similar. In all the examples on this page, the identifier qrfile is used. A single quickrace consists of multiple files:

  • qrfile.json: The main file, storing general info about the track.
  • qrfile.jpg: The preview that will be shown in the menu for this track.
  • qrfile_reverse.jpg: Same as above, but only shown when the track is set to reverse mode. This file is optional.
  • qrfile.prefab: This file contains in-game objects, like waypoints and decoration, as well as the starting positions.
  • qrfile_reverse.prefab: Same as above, those objects are additionally loaded when the track is reversed. This file is optional.
  • qrfile_forward.prefab: Same as above, those objects are additionally loaded when the track is not reversed. This file is optional.
  • qrfile.html: If this file exists, the player will see this HTML-content before starting the race in-game. This file is optional.

Some Terms

For clarification, some terms explained:

  • Closed Track: A closed track is like a circle, it has no beginning and no end. The finish line is placed somewhere along its path, as well as some checkpoint, and you can complete any number of laps around.
  • Open Track: An open track is like a line with a beginning and an end and checkpoints in between, thus allowing only a single 'lap' for this kind of track.
  • Standing Start: The 'regular' kind of timing. The vehicle is placed at the start line, and after the countdown the timer ticks and the driver starts. This is usually used if the time for the whole race, e.g. all lap times combined, matters.
  • Rolling Start: In this kind of timing, the vehicle is placed some distance before the start line, and is allowed to accelerate, until they reach the start line, at which point the timer starts. This kind of timing is used, if the individual lap time matters, as the first lap in a standing start configuration will always have the penalty of having to accelerate first.

The JSON-File

This is an example .json

The main part of a quickrace is the JSON-file. It stores general information about the track, like the name, description and author, as well as information about the track itself. Most important probably is the lapConfig-field, which stores the waypoints of the track, similar to regular scenarios. Also, you can allow or disable reversing the track, rolling start or changing of the lap count. Furthermore, you can specify a list of prefab-files which are loaded, as well as custom spawning positions.

  • name: The name of the track.
  • description: The description of the track.
  • authors: Who made the track. This field is optional.
  • date: Time of creation as UNIX-timestamp. This field is optional.
  • prefabs: A list of all the prefabs that should be loaded, see below. This field is optional.
  • reversePrefabs: A list of all the prefabs that should be loaded only in reverse mode, see below. This field is optional.
  • forwardPrefabs: A list of all the prefabs that should be loaded only in forward mode, see below. This field is optional.
  • lapConfig: The name of the checkpoints of your course, see below.
  • finishLineCheckpoint: The checkpoint directly on the finish line goes here, see below.
  • startLineCheckpoint: The checkpoint directly on the starting line goes here, see below. This field is only sometimes needed, see below.
  • lapCount: The amount of laps for this track. This field is optional and defaults to 1.
  • closed: If true, the player can change the amount of laps when configuring the track. Also indicates if the track is a open or closed. This field is optional and defaults to false.
  • reversible: If true, the player can drive the track in reverse. This field is optional and defaults to false.
  • allowRollingStart: If true, the player can also start the track with a rolling start. This field is optional and defaults to false.
  • tod: This number indicates the default time of day for this track, see below. This field is optional and defaults to Early Noon.
  • spawnSpheres: This table contains the name of custom starting positions, see below. This field is optional.


This is an example .prefab

The prefabs that should be loaded are divided into three fields:

  • prefabs contains a list of all the prefabs that should always be loaded, regardless of configuration. If there is a file named qrfile.prefab in the quickrace/ folder, it will automatically be loaded and does not need to be put in this list. Thus, if all your game objects are in this one file, the prefabs-field can be skipped.
  • reversePrefabs is a list of prefabs, that will only be loaded when the game is in reverse mode, alongside the qrfile_reverse.prefab file in the quickrace/ folder, if it exists, similar to the case above. If the only prefab-file you need for reverse is this file_reverse.prefab, you can skip this entry.
  • forwardPrefabs functions the same as reversePrefabs, but will only be loaded in forward mode and includes qrfile_forward.prefab.

What goes where?

When organizing your prefabs, follow these guidelines as to where to put the different objects:

  • prefabs: Spawn Spheres, waypoints, barriers, general decoration, ambient objects
  • reverse/forwardPrefabs: checkpoint markers, Starting Platform, finish line decoration, signs/turn markers

Lap Config

The field lapConfig is a list, that should contain the name of all the waypoints specified in the prefabs, in the order that they have to be traversed in order to complete one lap, except for the waypoint directly on the finish line, which should be put into the field finishLineCheckpoint. Both of these fields are required.

If the track is not closed, but a rally, lapConfig should contain neither the waypoints on the start-, nor the finish line. Those are then placed in their separate fields named startLineCheckpoint and finishLineCheckpoint. See the example images below.

Closed Track.png OpenTrack.png

Time of Day

When configuring the track in the menu, you can chose from several options for the position of the sun. You can set default option though a number in the field tod in the JSON-file. The default value is 3 / Early Noon.

  • 0 Night
  • 1 Sunrise
  • 2 Morning
  • 3 Early Noon
  • 4 Noon
  • 5 Late Noon
  • 6 Afternoon
  • 7 Evening
  • 8 Sunset

Spawn Spheres

The starting position of the vehicle is defined via a SpawnSphere-Object in the prefabs. Whether you enable reverse and/or rolling start, you need up to 4 of those objects, one for each combination. Each of those spawns needs to have a specific name, as defined below:

  • Standing Forward: qrfile_standing_spawn
  • Standing Reverse: qrfile_standingReverse_spawn
  • Rolling Forward: qrfile_rolling_spawn
  • Rolling Reverse: qrfile_rollingReverse_spawn

Custom Names

Those are the default names for the spawns. You can also define custom names for one or more spawns in the field spawnSpheres in the JSON-File. See below for an example.

  • Standing Forward: standing
  • Standing Reverse: standingReverse
  • Rolling Forward: rolling
  • Rolling Reverse: rollingReverse

SpawnSpheres in JSON.png

Placement of the Spawn Spheres

To ensure maximum enjoyment of your track, the spawn spheres should be placed with these guidelines in mind:

  • Standing Forward: This is the regular spawning position. For any kind of race, it should be placed directly in front of the start-/finish line.
  • Standing Reverse: This spawn sphere should be placed directly behind the finish line, and also face the other way of course.
  • Rolling Forward: The rolling spawn sphere should be placed some distance before the finish line, preferably directly before the last corner of the circuit. This ensures, that the player will have a about the same velocity as if they just completed a lap once they pass the finish line. For an open track, you can place it at a reasonable distance before the start line, since there will be only one 'lap' anyway.
  • Rolling Reverse: Same as above, but behind the finish line, and also just around the first corner of the track.

Title Images

You can put a qrfile.jpg next to the JSON-File, which will then be shown in the track selector in the menu. Additionally, you can add a qrfile_reverse.jpg, which will be shown in the overview menu when the user selects the reverse option.

HTML Intro

You can put a qrfile.html next to the JSON-File, and put any HTML-content in there, which will then be displayed before the race.

HTML example.png