Resource:Race: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(18 intermediate revisions by 8 users not shown)
Line 13: Line 13:
Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.
Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.


==Installing maps==
==Converting MTA:Race maps==
===Installing maps in MTA:Race syntax===
Use the [http://files.mtasa.com/apps/1.0/raceconv.zip batch converter] to convert all your MTA:Race maps into MTA:SA maps in one go.
Adding MTA:Race maps to your DM server is easy. All you have to do is place the file in a folder and add a meta.xml. No conversion is necessary.
*Go to the "resources" folder of your server installation (<SERVER>\mods\deathmatch\resources) and create a new folder. In order to keep with conventions, the folder name should be in the format "race-<mapname>", so if the map file is called "Dirtring.map" you might call the folder "race-dirtring".
*Copy the .map file into the new folder
*Create a meta.xml file in the new folder and paste the following text into it:
<div style="padding-left: 20px">
<syntaxhighlight lang="xml">
<meta>
    <info type="map" gamemodes="race" name="" />
    <race src=".map" />
</meta>
</syntaxhighlight>
</div>
*Enter the name of the map, for example "Dirtring", in the "name" attribute of the <info> node.
*Enter the name of the .map file in the "src" attribute of the <race> node, for example "Dirtring.map".
*Save the meta.xml.
*Add more maps if you wish. When you're done, /refresh your server resources.
 
===Installing maps in DM syntax===
If you created the map yourself in the MTA:SA DM map editor (not released at this point), everything will be in place and you only need to /refresh. If you downloaded the map, place it in your server "resources" folder and /refresh.
 
===Converting maps from Race syntax to DM syntax===
The MTA:SA DM map editor can only edit maps in the DM syntax. If you want to edit maps that are in MTA:Race syntax, you need to convert them.
*Make sure the map you want to convert is not in a zip file. If it is, create a folder with the same name as the zip file and extract the zip contents into it.
*Make sure race is started. Either have a race map running, or do /start race.
*Enter the command /convrace <map resource name>.
*The conversion process should be very quick. Once conversion is complete a message will appear.
The map file is overwritten with the converted version. If you want to keep the original file, make sure you have a backup.


==Map syntax==
==Map syntax==
===MTA:Race style syntax===
You can create race maps using the new MTA:SA [[Resource:editor|map editor]]. The map syntax is given here for reference.
<syntaxhighlight lang="xml">
<map mod="race">
    <meta>
        <author>Author name</author>
        <description>Map description</description>
        <version>Map version number</version>
    </meta>
 
    <options>
        <weather>Weather ID</weather>
        <respawn>timelimit|none</respawn>    <!-- Default = timelimit -->
        <duration>Maximum race time in seconds. Default is 10 minutes</duration>
        <time>hour:minute</time>        <!-- Time of day at which the race starts -->
        <vehicleweapons>true|false</vehicleweapons>    <!-- Vehicle weapon firing allowed or not. Default is false -->
        <ghostmode>true|false</ghostmode>    <!-- Disables vehicle collision. Default is false. -->
        <skins>cj|random|rangelist></skins>    <!-- Skins for the players. See explanation below for rangelist -->
        <!-- if respawn == timelimit -->
        <respawntime>Time from death to respawn in seconds. Default is 5.</respawntime>
    </options>
 
    <!-- One or more -->
    <spawnpoint>
        <position>X Y Z</position>
        <rotation>Angle in degrees. 0 = north, higher values go counter clockwise.</rotation>
        <vehicle>Vehicle number</vehicle>
        <!-- optional -->
        <paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
        <upgrades>Space separated list of vehicle upgrade numbers</upgrades>
    </spawnpoint>
 
    <!-- Zero or more -->
    <checkpoint>
        <position>X Y Z</position>
        <size>Float. Higher values make the checkpoint marker bigger. Default is 1</size>
        <color>R G B</color>  <!-- R, G and B range from 0 to 255. Default color is 0 0 255 (blue) -->
        <!-- optional -->
        <vehicle>Vehicle ID to change into when passing through this checkpoint</vehicle>
        <paintjob>Paintjob ID, ranges from 0 to 3</paintjob>
        <upgrades>Space separated list of vehicle upgrade numbers</upgrades>
    </checkpoint>
 
    <!-- Zero or more -->
    <object>
        <position>X Y Z</position>
        <rotation>rotX rotY rotZ</rotation>  <!-- Each rotation is in radians. Rotations for X and Z are switched. -->
        <model>Model ID</model>
    </object>


    <!-- Zero or more -->
===.map file===
    <pickup>
        <position>X Y Z</position>
        <type>repair|nitro|vehiclechange</type>
        <!-- if type == vehiclechange -->
        <vehicle>Vehicle ID to change into</vehicle>
        <!-- optional -->
        <paintjob>paintjob ID</paintjob>
        <upgrades>Space separated upgrade list</upgrades>
    </pickup>
</map>
</syntaxhighlight>
 
The <skins> option can be "cj" (players are CJ in random clothes), "random" (players have random ped skins), or a range list. A range list is a space separated list of single numbers and ranges of numbers expressed as "start-end". For example:
 
<syntaxhighlight lang="lua">18 40-50 65-68 72 200</syntaxhighlight>
 
The skin of each player will be chosen at random from this list.
 
===MTA:SA DM style syntax===
====.map file====
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<map mod="deathmatch">
<map>
     <!-- One or more -->
     <!-- One or more -->
     <spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="*comma*-separated list of upgrades" ] />
     <spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />


     <!-- Zero or more -->
     <!-- Zero or more -->  
     <checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />
     <checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" type="checkpoint/ring/cylinder/arrow/corona" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />


     <!-- Zero or more -->
     <!-- Zero or more -->
Line 130: Line 36:
</syntaxhighlight>
</syntaxhighlight>


====meta.xml====
===meta.xml===
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<meta>
<meta>
Line 142: Line 48:
</syntaxhighlight>
</syntaxhighlight>
The <setting>s correspond to options in MTA:Race syntax. For example, <time>4:0</time> in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.
The <setting>s correspond to options in MTA:Race syntax. For example, <time>4:0</time> in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.
==Adding your scripts to Race==
If you want to add new features to Race, you can either modify the original Race resource files, or more preferably, add the features as a separate resource and communicate with Race via events.
Not hacking the Race core and is probably a good idea if you want to apply official updates and fixes for Race in the future. Choosing to use separate resources for your customization also means you can continue use customizations from other people, and if you so wish, share your customization with others.


==Addons==
==Addons==
Line 151: Line 53:


==Events for version 0.8.3==
==Events for version 0.8.3==
'''Note:''' You may have to add the events in your script using addEvent() if you want to use them.
===Server===
{| class="wikitable" border="0"
|-
|width="200pt"|'''Name'''
|width="60pt"|'''Source'''
|'''Parameters'''
|}
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPlayerReachCheckpoint'''
|width="60pt"|player
|<syntaxhighlight lang="lua">int checkpoint, int time_</syntaxhighlight>
|}


===Server===
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPlayerPickUpRacePickup'''
|width="60pt"|player
|<syntaxhighlight lang="lua">int/string pickupID, string pickupType, int vehicleModel</syntaxhighlight>
|}


'''onPlayerReachCheckpoint'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onMapStarting'''
|width="60pt"|
|<syntaxhighlight lang="lua">table mapInfo, table mapOptions, table gameOptions</syntaxhighlight>
|}


'''onPlayerPickUpRacePickup'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPlayerFinish'''
|width="60pt"|player
|height="20pt"|<syntaxhighlight lang="lua">int rank, int time</syntaxhighlight>
|}


'''onMapStarting'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPostFinish'''
|width="60pt"|
|height="38pt"|
|}


'''onPlayerFinish'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPollStarting'''
|width="60pt"|
|<syntaxhighlight lang="lua">table poll</syntaxhighlight>
|}


'''onPostFinish'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onRaceStateChanging'''
|width="60pt"|
|<syntaxhighlight lang="lua">string newStateName, string oldStateName</syntaxhighlight>
|-
|}


'''onPollStarting'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onPlayerRaceWasted'''
|width="60pt"|player
|<syntaxhighlight lang="lua">vehicle playersVehicle</syntaxhighlight>
|-
|}


===Client===
===Client===
'''onClientMapStarting'''


'''onClientPlayerFinish'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientMapStarting'''
|width="60pt"|
|<syntaxhighlight lang="lua">table mapinfo</syntaxhighlight>
|-
|}


'''onClientPlayerOutOfTime'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientPlayerFinish'''
|width="60pt"|player
|height="38pt"|
|-
|}


'''onClientMapStopping'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientPlayerOutOfTime'''
|width="60pt"|player
|height="38pt"|
|-
|}


'''onClientScreenFadedOut'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientMapStopping'''
|width="60pt"|
|height="38pt"|
|-
|}


'''onClientScreenFadedIn'''
{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientScreenFadedOut'''
|width="60pt"|
|height="38pt"|
|-
|}


{| class="wikitable" border="0"
|-
|width="200pt"|'''onClientScreenFadedIn'''
|width="60pt"|
|height="38pt"|
|-
|}


==Events for version 0.8.3 in detail==
==Events for version 0.8.3 in detail==
'''Note:''' You may have to add the events in your script using addEvent() if you want to use them.
===onRaceStateChanging===
Triggered when the race resource starts doing something else.
===Parameters===
<syntaxhighlight lang="lua">string newState, string oldState</syntaxhighlight>
*'''newState:''' the new state
*'''oldState:''' the old state
Possible states:
* undefined   
* NoMap     
* LoadingMap   
* PreGridCountdown
* GridCountdown
* Running   
* MidMapVote
* SomeoneWon
* TimesUp
* EveryoneFinished
* PostFinish
* NextMapSelect
* NextMapVote
* ResourceStopping
===Source===
The root element.
===onPlayerReachCheckpoint===
===onPlayerReachCheckpoint===
Triggered when a player reaches any checkpoint but the last one.
====Parameters====
====Parameters====
<syntaxhighlight lang="lua">int checkpoint</syntaxhighlight>
<syntaxhighlight lang="lua">int checkpoint, int time</syntaxhighlight>
*'''checkpoint:''' the number of the checkpoint the player went through. The first checkpoint has number 1.
*'''checkpoint:''' the number of the checkpoint the player went through. The first checkpoint has number 1.
*'''time:''' time since the race started, in milliseconds.


====Source====
====Source====
The source is the player that reached the checkpoint.
The source is the player that reached the checkpoint.
===onPlayerFinish===
Triggered when a player reaches the last checkpoint (i.e. has finished the race)
====Parameters====
<syntaxhighlight lang="lua">int rank, int time</syntaxhighlight>
*'''rank:''' the player's rank. 1 means he won the race, 2 that he came in second place, etc.
*'''time:''' time since the race started, in milliseconds.
====Source====
The source is the player that finished the race.


===onPlayerPickUpRacePickup===
===onPlayerPickUpRacePickup===
====Parameters====
====Parameters====
<syntaxhighlight lang="lua">int/string pickupID</syntaxhighlight>
<syntaxhighlight lang="lua">int/string pickupID, string pickupType, int vehicleModel</syntaxhighlight>
*'''pickupID:''' the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.
*'''pickupID:''' the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.
*'''pickupType:''' the pickup type. Can be "nitro", "repair" or "vehiclechange".
*'''vehicleModel:''' if the pickup is of type vehiclechange, this is the vehicle model that it sets.


====Source====
====Source====
Line 199: Line 231:
==Element data==
==Element data==
These element data are set on each player:
These element data are set on each player:
*'''Race rank:''' the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
*'''race rank:''' the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
*'''race.checkpoint:''' the number of the checkpoint the player is ''heading for''. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
*'''race.checkpoint:''' the number of the checkpoint the player is ''heading for''. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
*'''race.finished:''' ''true'' if the player has finished, ''false'' if he's still racing.
*'''race.finished:''' ''true'' if the player has finished, ''false'' if he's still racing.
This server only element data is set for the resource root element:
*'''info:''' which contains a table with these sub-tables: '''mapInfo''', '''mapOptions''' and '''gameOptions'''.
==Super Advanced Element data==
You can also set player element data to change the player collision status and render transparency:
<syntaxhighlight lang="lua">
e.g. setElementData( thePlayer, "overrideCollide.uniqueblah", 0, false ) -- Collide 'off' for this player
    setElementData( thePlayer, "overrideCollide.uniqueblah", nil, false ) -- Collide 'default' for this player
    setElementData( thePlayer, "overrideAlpha.uniqueblah", 120, false ) -- Alpha '120 maximum' for this player
    setElementData( thePlayer, "overrideAlpha.uniqueblah", nil, false ) -- Alpha 'default' for this player
</syntaxhighlight>
Set 'uniqueblah' to whatever you like (up to 15 characters long)
==Exported Server functions==
{| class="wikitable" border="0"
|-
|width="80pt"|<syntaxhighlight lang="lua">int</syntaxhighlight>
|width="110pt"|'''getTimePassed'''
|height="38pt"|
|-
|}
{| class="wikitable" border="0"
|-
|width="80pt"|<syntaxhighlight lang="lua">int</syntaxhighlight>
|width="110pt"|'''getPlayerRank'''
|<syntaxhighlight lang="lua">player thePlayer</syntaxhighlight>
|-
|}
{| class="wikitable" border="0"
|-
|width="80pt"|<syntaxhighlight lang="lua">boolean</syntaxhighlight>
|width="110pt"|'''isPlayerFinished'''
|<syntaxhighlight lang="lua">player thePlayer</syntaxhighlight>
|-
|}
{| class="wikitable" border="0"
|-
|width="80pt"|<syntaxhighlight lang="lua">vehicle</syntaxhighlight>
|width="110pt"|'''getPlayerVehicle'''
|<syntaxhighlight lang="lua">player thePlayer</syntaxhighlight>
|-
|}
[[hu:Resource:Race]]
[[ru:Resource:Race]]

Latest revision as of 13:22, 24 October 2018

The "race" gamemode organizes sprint or freeroam races for one or more players. It supports both maps from MTA:Race and maps in the MTA:SA DM map syntax that were created in the map editor.

Ingame

Playing race is quite straightforward. If there are checkpoints, drive from checkpoint to checkpoint and be the first to reach the finish line within the time. If there are no checkpoints, just drive around and have fun.

In races you may encounter three types of pickups which will have an effect on your vehicle:

  • Repair pickups: this pickup looks like a wrench. If you drive over it, your vehicle will be restored to full health.
  • Nitrous oxide pickups: a red NOS bottle. After you drive over one you can press the fire button (by default the left mouse button) to get a temporary speed boost.
  • Vehicle change pickups: these display the name of a vehicle above them. As soon as you drive over a pickup your vehicle will be changed.

Lastly, if you get stuck during a race, you can enter the /kill command in the chatbox to kill yourself and respawn at the previous checkpoint.

Converting MTA:Race maps

Use the batch converter to convert all your MTA:Race maps into MTA:SA maps in one go.

Map syntax

You can create race maps using the new MTA:SA map editor. The map syntax is given here for reference.

.map file

<map>
    <!-- One or more -->
    <spawnpoint posX="X" posY="Y" posZ="Z" rotation="Rotation in degrees" vehicle="Vehicle ID" id="spawnpointID" [ paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />

    <!-- Zero or more --> 
    <checkpoint posX="X" posY="Y" posZ="Z" color="#FF0000" id="textual or numeric checkpoint ID" nextid="ID of checkpoint after this one" [ size="checkpoint size" vehicle="vehicle ID to change into" type="checkpoint/ring/cylinder/arrow/corona" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />

    <!-- Zero or more -->
    <object posX="X" posY="Y" posZ="Z" rotX="in degrees" rotY="in degrees" rotZ="in degrees" model="model ID" id="objectID" />

    <!-- Zero or more -->
    <pickup posX="X" posY="Y" posZ="Z" type="repair|nitro|vehiclechange" id="pickupID" [ vehicle="vehicle ID" paintjob="paintjob ID" upgrades="comma-separated list of upgrades" ] />
</map>

meta.xml

<meta>
   <info type="map" gamemodes="race" name="Map name" author="Author name" description="Map description" version="Map version number"/>
   <race src="Map file.map"/>
   <settings>
      <setting name="#optionName" value="optionValue"/>
      ...
   </settings>
</meta>

The <setting>s correspond to options in MTA:Race syntax. For example, in MTA:Race syntax would correspond to <setting name="#time" value="4:0"/> in DM syntax.

Addons

A Race 'addon' is no different from any other script resource, except that is has addon="race" in the <info> section of it's meta.xml file. This is simply to allow Race to identify it and put it in the /config menu for you. Addons communicate with Race via events. The current list of Race events and what they do are here:

Events for version 0.8.3

Note: You may have to add the events in your script using addEvent() if you want to use them.

Server

Name Source Parameters
onPlayerReachCheckpoint player
int checkpoint, int time_
onPlayerPickUpRacePickup player
int/string pickupID, string pickupType, int vehicleModel
onMapStarting
table mapInfo, table mapOptions, table gameOptions
onPlayerFinish player
int rank, int time
onPostFinish
onPollStarting
table poll
onRaceStateChanging
string newStateName, string oldStateName
onPlayerRaceWasted player
vehicle playersVehicle

Client

onClientMapStarting
table mapinfo
onClientPlayerFinish player
onClientPlayerOutOfTime player
onClientMapStopping
onClientScreenFadedOut
onClientScreenFadedIn

Events for version 0.8.3 in detail

Note: You may have to add the events in your script using addEvent() if you want to use them.

onRaceStateChanging

Triggered when the race resource starts doing something else.

Parameters

string newState, string oldState
  • newState: the new state
  • oldState: the old state

Possible states:

  • undefined
  • NoMap
  • LoadingMap
  • PreGridCountdown
  • GridCountdown
  • Running
  • MidMapVote
  • SomeoneWon
  • TimesUp
  • EveryoneFinished
  • PostFinish
  • NextMapSelect
  • NextMapVote
  • ResourceStopping

Source

The root element.

onPlayerReachCheckpoint

Triggered when a player reaches any checkpoint but the last one.

Parameters

int checkpoint, int time
  • checkpoint: the number of the checkpoint the player went through. The first checkpoint has number 1.
  • time: time since the race started, in milliseconds.

Source

The source is the player that reached the checkpoint.

onPlayerFinish

Triggered when a player reaches the last checkpoint (i.e. has finished the race)

Parameters

int rank, int time
  • rank: the player's rank. 1 means he won the race, 2 that he came in second place, etc.
  • time: time since the race started, in milliseconds.

Source

The source is the player that finished the race.

onPlayerPickUpRacePickup

Parameters

int/string pickupID, string pickupType, int vehicleModel
  • pickupID: the number of the pickup in case of MTA:Race syntax (starting at 1), or the "id" attribute of the pickup in case of DM syntax.
  • pickupType: the pickup type. Can be "nitro", "repair" or "vehiclechange".
  • vehicleModel: if the pickup is of type vehiclechange, this is the vehicle model that it sets.

Source

The source is the player that picked up the pickup.

Element data

These element data are set on each player:

  • race rank: the current position of the player in the race. 1 = first, 2 = second etc. Updated on a 1 second interval.
  • race.checkpoint: the number of the checkpoint the player is heading for. When the player spawns this number is 1, after he passed the first checkpoint it's 2, etc.
  • race.finished: true if the player has finished, false if he's still racing.

This server only element data is set for the resource root element:

  • info: which contains a table with these sub-tables: mapInfo, mapOptions and gameOptions.

Super Advanced Element data

You can also set player element data to change the player collision status and render transparency:

e.g. setElementData( thePlayer, "overrideCollide.uniqueblah", 0, false )		-- Collide 'off' for this player
     setElementData( thePlayer, "overrideCollide.uniqueblah", nil, false )		-- Collide 'default' for this player
     setElementData( thePlayer, "overrideAlpha.uniqueblah", 120, false )		-- Alpha '120 maximum' for this player
     setElementData( thePlayer, "overrideAlpha.uniqueblah", nil, false )		-- Alpha 'default' for this player

Set 'uniqueblah' to whatever you like (up to 15 characters long)

Exported Server functions

int
getTimePassed
int
getPlayerRank
player thePlayer
boolean
isPlayerFinished
player thePlayer
vehicle
getPlayerVehicle
player thePlayer