Race script generator¶

General

General Settings Show chp info? [Current setting: If the user drives through a (not start line) checkpoint of a race that isn't running, nothing will happen.]
Script filename: [optional, the extension of this file should be .as.]

General abort points (advanced) The race abort points defined here, will abort whichever race is running at that moment. General abort points:

[Note: Leave the object or message field empty to use the default. You can change the defaults below.]
Default abort object: [optional, the object that should be used for race abort points if no object (or [default]) is specified above.]
Default abort message: [optional, the message that should be shown when a race is aborted and the [default] message is used above.]

Add more races or generate the script [Start here. You can have multiple races on 1 terrain.]

[Generate the scripting file when you're finished adding all the races.]

Error log

Resulting script file

Race {RACE_NUMBER}

remove this race

General race info Race name:

Amount of laps:

Race version: [optional]

Race options (advanced) Finishing obligatory? [Current setting: If you drive through the start checkpoint of a race while already in another race, the current race will be aborted and the other race will start.]
Show time difference? [Current setting: Show + or - [best time minus current time] when passing a checkpoint.]
Show best lap time? [Current setting: If a race is started or a new best lap is set, the best lap will be shown.]
Show best race time? [Current setting: If a race is started or a new best race time is set, the best race time will be shown.]
Submit best time? [Current setting: If the user has a new best lap time or new best race time, then this time is submitted to the master server.]
Silent mode? [Current setting: The user will be informed about running races.]
Allow race restart? [Current setting: The race will be restarted when you pass the start line of the same race.]

Checkpoint locations and checkpoint objects Checkpoint coordinates:
[Note: Leave the object field empty to use the default. You can change the defaults below.]
Default start object: [optional, the start line object that should be used if it wasn't specified with in the checkpointlist above.]
Default chp object: [optional, the checkpoint object that should be used for all checkpoints that do not have an object specified in the checkpointlist above.]
Default finish object: [optional, the finish line object that should be used if it wasn't specified with in the checkpointlist above.]
Preview:

Race abort points (advanced) Race abort points:

[Note: Leave the object or message field empty to use the default. You can change the defaults below.]
Default abort object: [optional, the object that should be used for race abort points if no object (or [default] object) is specified above.]
Default abort message: [optional, the message that should be shown when a race is aborted and the [default] message is used above.]

Race penalty events (advanced) The settings in this box only apply if a 'race_penalty' box was triggered.
You can define 'race_penalty' points in the odef file of your checkpoint.
Penalty seconds: [the amount of seconds that should be added to the lap time when the penalty event is triggered.]
Message: [optional, the message that should be shown when a penalty event is triggered.]

What is this?¶

This is a generator for creating functional races (or timers) for terrains in Rigs of Rods, created by Neorej16 and ported to docs.rigsofrods.org by CuriousMike.

Instructions¶

Start by clicking "Add race". You can have multiple races on one terrain.

General race info¶

Race name¶

The name of your race, shown in the top left corner.

Amount of laps¶

The amount of laps your race will have. For point-to-point races, set "No laps".

Race version¶

The version number of your race. (e.g. authorName-1.0).

Race options¶

Finishing obligatory?¶

Disabled (Default): If you drive through the start checkpoint of a race while already in another race, the current race will be aborted and the other race will start.

Enabled: If you drive through the start checkpoint of a race while already in another race, the current race will continue and the other race start line will be ignored.

Show time difference?¶

Enabled (Default): Show + or - [best time minus current time] when passing a checkpoint.

Disabled: Only show the current time when you pass a checkpoint.

Show best lap time?¶

Enabled (Default): If a race is started or a new best lap is set, the best lap will be shown.

Disabled: Best lap times won't be shown to the user.

Show best race time?¶

Enabled (Default): If a race is started or a new best race time is set, the best race time will be shown.

Disabled: Best lap times won't be shown to the user.

Submit best time?¶

Enabled (Default): If the user has a new best lap time or new best race time, then this time is submitted to the master server.

Disabled: Race and lap times won't be sent to the master server.

Silent mode?¶

Disabled (Default): The user will be informed about running races.

Enabled: No info will be shown to the user, except for the timer.

Allow race restart?¶

Enabled (Default): The race will be restarted when you pass the start line of the same race.

Disabled: The race will continue to run without resetting the time when you pass the start line of the same race.

Checkpoint locations and objects¶

This section defines the locations of the checkpoints and what objects to use for the checkpoints.

Retrieving checkpoint coordinates¶

To easily get the checkpoint coordinates, do the following:

Open RoR and select your terrain
While not in a vehicle, walk to where you want your checkpoint to be, then press the H key. Repeat for all checkpoints you want to add.
When finished, exit RoR and open the RoR.log file, located at Documents\My Games\Rigs of Rods\logs.
Scroll to the end of the file, you should see position lines like the following:

00:58:49: Position:  486.504,    0.000,  512.000,    0.0,  360.0,    0.0
00:58:58: Position:  457.481,    0.000,  500.993,    0.0,  396.3,    0.0
00:59:05: Position:  470.764,    0.000,  464.283,    0.0,  484.1,    0.0
00:59:14: Position:  526.697,    0.000,  482.188,    0.0,  573.8,    0.0
00:59:20: Position:  564.749,    0.000,  465.543,    0.0,  512.7,    0.0
00:59:26: Position:  584.245,    0.000,  496.841,    0.0,  613.8,    0.0
00:59:32: Position:  550.343,    0.000,  511.211,    0.0,  716.8,    0.0

These are your checkpoint's position coordinates. Copy the lines to a new file as you'll need to edit it later.

Adding coordinates¶

To add the coordinates you retrieved from the log file, edit the lines to match the format below:

486.504,    0.000,  512.000,    0.0,  360.0,    0.0, [default]
457.481,    0.000,  500.993,    0.0,  396.3,    0.0, [default]
470.764,    0.000,  464.283,    0.0,  484.1,    0.0, [default]
526.697,    0.000,  482.188,    0.0,  573.8,    0.0, [default]
564.749,    0.000,  465.543,    0.0,  512.7,    0.0, [default]
584.245,    0.000,  496.841,    0.0,  613.8,    0.0, [default]
550.343,    0.000,  511.211,    0.0,  716.8,    0.0, [default]

Then paste the lines into the "Checkpoint coordinates" box. Example:

race-chp-example

A preview of the checkpoint layout will be shown.

Checkpoint objects¶

At the end of each coordinate line is the name of the checkpoint object. This defines the checkpoint visuals.

Each line can have a different checkpoint object. However, for simplicity's sake, you can set the default object names in the Default start / checkpoint / finish object sections. These objects will be used if you specify a checkpoint name in the coordinates list as [default].

By default, RoR includes these checkpoint models:

race-chp

The names for these objects are chp-start and chp-checkpoint.

You can also use a custom object. Here are a few checkpoints you can use, just extract the contents into your terrain's zip file:

F1 Test Track Checkpoint¶

race-chp-f1

These are the checkpoints from F1 Test Track, updated with fixed normals and new textures.

Object names: new-checkpoint-start and new-checkpoint.

Download: f1_checkpoint.zip

Empty Checkpoint¶

This checkpoint has no visuals. Useful for meshed terrains which have a clearly defined layout (such as tracks) or multiple races which share checkpoint locations.

Object name: empty-checkpoint.

Download: empty_checkpoint.zip

Race abort points¶

Optional, defines points which will abort the current race. Use the same coordinate format as above.

Race penalty events¶

Not used by any of the included checkpoints. Defines settings for the race_penalty box.

To add a race_penalty box, edit the odef file of your checkpoint. (See begin box section)

General settings¶

Show checkpoint info?¶

Disabled (Default): If the user drives through a (not start line) checkpoint of a race that isn't running, nothing will happen.

Enabled: If the user drives through a checkpoint of a race that isn't running, a message will be shown, saying "this is checkpoint X of race myRaceName".

Script filename¶

The file name of your race script with the .as file extension. Example: myTerrain.as

General abort points¶

Optional, defines points which will abort any current race. Use the same coordinate format as above.

Generating completed script¶

Once you're finally done setting up your race(s), click Generate script file! to generate the finished script.

Example completed script of a basic 2 lap race on Simple Test Terrain:

// Filename: TestRace.as
// This file was generated using the docs.rigsofrods.org race script generator.
#include "base.as";
#include "races.as";

racesManager races();


// GENERAL SECTION 0 START
int race_0_Simple_Test_Race_ID;
// GENERAL SECTION 0 END


// GENERAL SECTION GENERAL START

// GENERAL SECTION GENERAL END


void main()
{
    races.setCallback('RaceStart', on_RaceStart_event);
    races.setCallback('PenaltyEvent', on_PenaltyEvent_event);
    races.showCheckPointInfoWhenNotInRace = true;

    // MAIN SECTION 0 START
    race_0_Simple_Test_Race_ID = races.addNewEmptyRace();
    races.setRaceName(race_0_Simple_Test_Race_ID, "Simple Test Race");
    races.setLaps(race_0_Simple_Test_Race_ID, 2);
    array<array<double>> race_0_coords = {
        {486.504, 0.0, 512.0, 0.0, 360.0, 0.0},
        {457.481, 0.0, 500.993, 0.0, 396.3, 0.0},
        {470.764, 0.0, 464.283, 0.0, 484.1, 0.0},
        {526.697, 0.0, 482.188, 0.0, 573.8, 0.0},
        {564.749, 0.0, 465.543, 0.0, 512.7, 0.0},
        {584.245, 0.0, 496.841, 0.0, 613.8, 0.0},
        {550.343, 0.0, 511.211, 0.0, 716.8, 0.0}
    };
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 0, "chp-start", race_0_coords[0]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 1, "chp-checkpoint", race_0_coords[1]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 2, "chp-checkpoint", race_0_coords[2]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 3, "chp-checkpoint", race_0_coords[3]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 4, "chp-checkpoint", race_0_coords[4]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 5, "chp-checkpoint", race_0_coords[5]);
    races.addCheckpoint(race_0_Simple_Test_Race_ID, 6, "chp-checkpoint", race_0_coords[6]);
    races.setVersion(race_0_Simple_Test_Race_ID, "CuriousMike-1.0");
    races.setPenaltyTime(race_0_Simple_Test_Race_ID, 10);
    races.finalize(race_0_Simple_Test_Race_ID);
    // MAIN SECTION 0 END


}

void on_RaceStart_event(dictionary@ event)
{
    int raceID;
    event.get('raceID', raceID);


    // RACESTART SECTION 0 START
    if( raceID == race_0_Simple_Test_Race_ID )
    {
        races.obligatedFinish = false;
        races.showTimeDiff = true;
        races.showBestLap = true;
        races.showBestRace = true;
        races.submitScore = true;
        races.silentMode = false;
        races.restartRaceOnStart = true;
    }
    // RACESTART SECTION 0 END


}

void on_PenaltyEvent_event(dictionary@ event)
{
    int raceID;
    event.get('raceID', raceID);


    // PENALTYEVENT SECTION 0 START
    // PENALTYEVENT SECTION 0 END


}

void eventCallback(int eventnum, int value)
{
    races.eventCallback(eventnum, value);
}

Adding script to terrain¶

To add your generated script to the terrain, copy the script (CTRL+A to select all) into a text editor such as Notepad or Notepad++.

Save the file with the .as file extension: Make sure to set the file type to "All files"!

race-script-save

Place the file into your terrain's zip, then open the terrain's .terrn2 file.

At the end of the terrn2, add (or edit) the [Scripts] section:

[Scripts]
TestRace.as=

Save your changes and place the edited terrn2 back into the terrain zip if necessary.

In-game¶

If everything went well, you should now have your race in RoR!

race-ingame

Fine tuning checkpoint locations¶

When testing your race, your checkpoints may not be in the correct location or rotated correctly.

To adjust your checkpoint positions, use the in-game object editor.

Checkpoints are spawned first, so use CTRL+[ and CTRL+] keys to scroll through each one.

race-chp-adjust

Once you're done moving your checkpoints. exit editor mode (CTRL+Y) then exit the game.

In editor_out.cfg, the checkpoint locations will be at the top of the file:

 486.504,    0.000,  512.000,    0.0,   90.0,    0.0, chp-start
 457.481,    0.000,  500.993,    0.0,  396.3,    0.0, chp-checkpoint
 470.764,    0.000,  464.283,    0.0,  484.1,    0.0, chp-checkpoint
 526.697,    0.000,  482.188,    0.0,  573.8,    0.0, chp-checkpoint
 577.081,    0.000,  478.170,    0.0,  480.0,    0.0, chp-checkpoint
 596.938,    0.000,  494.067,    0.0,  718.4,    0.0, chp-checkpoint
 550.343,    0.000,  511.211,    0.0,   90.0,    0.0, chp-checkpoint

Edit the lines to match the following format:

{486.504,    0.000,  512.000,    0.0,   90.0,    0.0},
{457.481,    0.000,  500.993,    0.0,  396.3,    0.0},
{470.764,    0.000,  464.283,    0.0,  484.1,    0.0},
{526.697,    0.000,  482.188,    0.0,  573.8,    0.0},
{577.081,    0.000,  478.170,    0.0,  480.0,    0.0},
{596.938,    0.000,  494.067,    0.0,  718.4,    0.0},
{550.343,    0.000,  511.211,    0.0,   90.0,    0.0}

Paste the lines into your race script file, replacing the existing positions:

    array<array<double>> race_0_coords = {
        {486.504,    0.000,  512.000,    0.0,   90.0,    0.0},
        {457.481,    0.000,  500.993,    0.0,  396.3,    0.0},
        {470.764,    0.000,  464.283,    0.0,  484.1,    0.0},
        {526.697,    0.000,  482.188,    0.0,  573.8,    0.0},
        {577.081,    0.000,  478.170,    0.0,  480.0,    0.0},
        {596.938,    0.000,  494.067,    0.0,  718.4,    0.0},
        {550.343,    0.000,  511.211,    0.0,   90.0,    0.0}
    };

Save the script and try it in-game. Your checkpoints should now be in the correct place.

Troubleshooting¶

If your race doesn't appear in-game, check your terrain's .terrn2 file to make sure the [Scripts] section is correct and that your script is in the terrain zip.

Otherwise, your script may have a syntax error. Browse to Documents\My Games\Rigs of Rods\logs and open Angelscript.log with Notepad. Script errors will be shown there.

Look at the completed example script above for reference.

Conclusion¶

Congratulations, you now know the basics of adding races to Rigs of Rods using the race script generator!