===== Racing =====

Worlds can have a 4 different race courses defined. You create these by setting up checkpoints along the course that the player must travel across, along with a starting region and finishing line.  Defining the course is done through the in-game World Editor.

Races can be run either by having one player (or admin) 'hosting' the race - i.e. they choose when it starts - or they can be fully automated.

Races can be initiated automatically through settings or can be triggered either manually or from script using the following commands:

<code>*raceinit [course_num] [entry_fee]
*racejoin [player_name] [course_num] [Spawn_Mode]
*racestart [course_num]
*raceleave [player_name] [course_num]</code>

''*raceinit'' initiates the race, the entry_fee is optional, if set the amount will be deducted automatically from the player when they join and is added to a pool that is given to the winner.

''*racejoin'' is used to add players to the race. Setting 'Spawn_Mode' to 1 automatically places the player in the start zone, facing in the right direction and sets them 'Ready' which locks their controls. (Otherwise it is up to the player themselves to 'Set Ready'.)

''*racestart'' triggers a countdown and starts the race.

Normally if you're scripting a race, you'll want to some mechanism to initiate a race (e.g. Using a particular item or selecting an option in a special building) and then players would be given the option to join the race, perhaps through a popup notification.  An example of how to do this is provided [[Scripting:Samples:Racing|here]]

==== Racing Script Events & Sys Function====

**RaceStart**  : Triggered once when the race starts.  ''$gTaskItem1'' will be set to the course number\\
**RaceEnd**\\
**RaceWinner** : Triggered with the details of the player who won the race.\\
\\
**sysRaceIsActive( [course_num] )** can be used in script to find out if a race course is currently active.\\


==== Automated Races through Settings ====

There are some settings that can be used to allow races to be created without script, and change the behaviour of races when they're created. It is recommended that if you're scripting your race you leave all these settings at 0 and handle any special behaviours in script code instead.

''Raw Settings'' -> ''Subgame'' -> ''Race Vehicle''\\
Determines the vehicle that the player is set to if they join a race (If ''Racing Mode'' is set to something other than 0). If ''Race Vehicle'' set to 0, the player's vehicle won't be changed automatically, even if the mode is set.


''Raw Settings'' -> ''Subgame'' -> ''Racing Mode''\\
**0**: No effect\\
**1**: Players are not allowed to join an automated race without a ''Racing License'' item. \\
**2**: Players are only allowed to join if they're in the vehicle set in ''Race Vehicle''\\
**3**: Mode for local-only races. Probably doesnt work.\\
**4**: Just sets the players vehicle to ''Race Vehicle''\\
**5**: Only sysops are allowed to use the 'Start Race' button *\\
\\
* (Note, how you get the 'Start Race' button to appear needs to be documented. Its somewhere in some weird menu settings :] )\\