Race script generator

General
General Settings [Current setting: If the user drives through a (not start line) checkpoint of a race that isn't running, nothing will happen.]
[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.



[Note: Leave the object or message field empty to use the default. You can change the defaults below.]
[optional, the object that should be used for race abort points if no object (or [default]) is specified above.]
[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




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 specifiy 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!

Edit page on GitHub