Multi Theft Auto: Wiki - User contributions [en]

Resource:Race

2010-03-02T21:44:02Z

Driver2: /* Events for version 0.8.3 */

{{Resource page}}
__NOTOC__
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 [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.

==Map syntax==
You can create race maps using the new MTA:SA [[Resource:editor|map editor]]. The map syntax is given here for reference.

===.map file===
<syntaxhighlight lang="xml">
<map mod="deathmatch">

<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" ] />


<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" ] />


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


<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>
</syntaxhighlight>

===meta.xml===
<syntaxhighlight lang="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>
</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.

==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===

{| 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>
|}

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

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

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

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

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

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

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

===Client===

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

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

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

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

{| 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==
'''Note:''' You may have to add the events in your script using addEvent() if you want to use them.
===onPlayerReachCheckpoint===
Triggered when a player reaches any checkpoint but the last one.
====Parameters====
<syntaxhighlight lang="lua">int checkpoint, int time</syntaxhighlight>
*'''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====
<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===
====Parameters====
<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.
*'''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:
<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>
|-
|}

Resource:Race

2010-02-26T03:18:42Z

Driver2: /* Events for version 0.8.3 in detail */

{{Resource page}}
__NOTOC__
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 [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.

==Map syntax==
You can create race maps using the new MTA:SA [[Resource:editor|map editor]]. The map syntax is given here for reference.

===.map file===
<syntaxhighlight lang="xml">
<map mod="deathmatch">

<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" ] />


<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" ] />


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


<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>
</syntaxhighlight>

===meta.xml===
<syntaxhighlight lang="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>
</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.

==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==

===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>
|}

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

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

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

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

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

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

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

===Client===

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

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

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

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

{| 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==
'''Note:''' You may have to add the events in your script using addEvent() if you want to use them.
===onPlayerReachCheckpoint===
Triggered when a player reaches any checkpoint but the last one.
====Parameters====
<syntaxhighlight lang="lua">int checkpoint, int time</syntaxhighlight>
*'''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====
<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===
====Parameters====
<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.
*'''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:
<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>
|-
|}

Var dump

2009-11-05T20:53:40Z

Driver2:

{{Useful Function}}
<lowercasetitle>var_dump</lowercasetitle>
__NOTOC__
This function outputs information about one or more variables using outputConsole().

==Syntax==
<syntaxhighlight lang="lua">string/table var_dump( ... )</syntaxhighlight>

===Arguments===
The function can have a variable number of arguments. Those arguments can be of three types:
* '''Modifiers:''' A ''string'' that begins with a "-" (minus) and that is followed by at least another parameter is a modifier. A modifier can change the behaviour of the function. Modifiers don't have to be the first argument, they always work on all arguments after it (see examples).
* '''Names:''' A ''string'' that is followed by at least another parameter and isn't preceeded by another ''string'' (that is not a modifier), is a name. A name is output before the variable output, to make it recognizable (basicially a description of the variable that is being output, e.g. the name).
* '''Values:''' Any value that is not one of the two above will generate an output with information about the variable:
** For ''strings'': string(''lengthOfString'') "''value''"
** For ''userdata'': userdata(''MTA element type'') "''value''"
** For ''tables'': table(''numerOfElements'') "''value''"
*** If the table contains any elements, they will also be output if the appropriate modifiers are set. This will always be in the form [''key''] => ''value'', while ''key'' and ''value'' are formatted by var_dump.

===Modifiers===
* '''v''' (verbose): Dumps more data than usual (for now it outputs whole tables including subtables)
* '''n''' (normal): Switches back into 'normal' non-verbose mode.
* '''s''' (silent): With this activated, it outputs nothing at all, however it still returns the output, so you can use it yourself (also used internally for recursion).
* '''u''' (unnamed): Don't use names. Every ''string'' that is not a modifier will be output as a value, not a decription.
* '''d[number]''' (depth): Output nested tables up to this depth (e.g. "d1" means output all values of the initial table, but not the values of the values, if they are also tables).

===Returns===
Returns a string with all the output in one line and a table with several lines of output.

==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua" lang="lua">
-- modifiers: v - verbose (all subtables), n - normal, s - silent (no output), dx - up to depth x, u - unnamed
function var_dump(...)
-- default options
local verbose = false
local firstLevel = true
local outputDirectly = true
local noNames = false
local indentation = "\t\t\t\t\t\t"
local depth = nil

local name = nil
local output = {}
for k,v in ipairs(arg) do
-- check for modifiers
if type(v) == "string" and k < #arg and v:sub(1,1) == "-" then
local modifiers = v:sub(2)
if modifiers:find("v") ~= nil then
verbose = true
end
if modifiers:find("s") ~= nil then
outputDirectly = false
end
if modifiers:find("n") ~= nil then
verbose = false
end
if modifiers:find("u") ~= nil then
noNames = true
end
local s,e = modifiers:find("d%d+")
if s ~= nil then
depth = tonumber(string.sub(modifiers,s+1,e))
end
-- set name if appropriate
elseif type(v) == "string" and k < #arg and name == nil and not noNames then
name = v
else
if name ~= nil then
name = ""..name..": "
else
name = ""
end

local o = ""
if type(v) == "string" then
table.insert(output,name..type(v).."("..v:len()..") \""..v.."\"")
elseif type(v) == "userdata" then
local elementType = "no valid MTA element"
if isElement(v) then
elementType = getElementType(v)
end
table.insert(output,name..type(v).."("..elementType..") \""..tostring(v).."\"")
elseif type(v) == "table" then
local count = 0
for key,value in pairs(v) do
count = count + 1
end
table.insert(output,name..type(v).."("..count..") \""..tostring(v).."\"")
if verbose and count > 0 and (depth == nil or depth > 0) then
table.insert(output,"\t{")
for key,value in pairs(v) do
-- calls itself, so be careful when you change anything
local newModifiers = "-s"
if depth == nil then
newModifiers = "-sv"
elseif depth > 1 then
local newDepth = depth - 1
newModifiers = "-svd"..newDepth
end
local keyString, keyTable = var_dump(newModifiers,key)
local valueString, valueTable = var_dump(newModifiers,value)

if #keyTable == 1 and #valueTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>\t"..valueString)
elseif #keyTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>")
for k,v in ipairs(valueTable) do
table.insert(output,indentation..v)
end
elseif #valueTable == 1 then
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
table.insert(output,indentation.."\t=>\t"..valueString)
else
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
for k,v in ipairs(valueTable) do
if k == 1 then
table.insert(output,indentation.." => "..v)
else
table.insert(output,indentation..v)
end
end
end
end
table.insert(output,"\t}")
end
else
table.insert(output,name..type(v).." \""..tostring(v).."\"")
end
name = nil
end
end
local string = ""
for k,v in ipairs(output) do
if outputDirectly then
outputConsole(v)
end
string = string..v
end
return string, output
end
</syntaxhighlight>
</section>

==Example==
<section name="Serverside Example" class="server" show="true">
Get a table of all players on the server (if there are 4 players).
<syntaxhighlight lang="lua" lang="lua">
var_dump(getElementsByType("player"))
</syntaxhighlight>
Output:
<syntaxhighlight lang="lua">
table(4) "table: 02998058"
</syntaxhighlight>
With 'verbose' modifier.
<syntaxhighlight lang="lua">
var_dump("-v",getElementsByType("player"))
</syntaxhighlight>
<syntaxhighlight lang="lua">
table(1) "table: 043C6900"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
</syntaxhighlight>

Now another table we created before (please not that the table 'test2' is both key and value in this example):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 020B7838"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 021770A0"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}]
=> table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}
}
</syntaxhighlight>

The same as before, but now with a modifier to output the second table 'normal':
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-n",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 01BB9030"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 0223B2D8"
</syntaxhighlight>

The same as before, but now with a modifier to output the second table only to depth 1 (the verbose is still active from the first argument):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-d1",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 029BE6E8"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 01E2CDF8"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 021C6378"] => table(2) "table: 021C6378"
}
</syntaxhighlight>

The same as before, but now with names to make clear which output belongs to which variable (of course in this small example, it's not really needed):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v","players",getElementsByType("player"),"-d1","test tables",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
players: table(1) "table: 0219F4D0"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
test tables: table(2) "table: 0219DB20"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 01B68048"] => table(2) "table: 01B68048"
}
</syntaxhighlight>

The same as before, but now 'unnamed', meaning all values that are not modifiers will be output as values. However, the last two arguments were also removed, which leaves the last modifier as last argument, which will output the modifier as a normal value:
<syntaxhighlight lang="lua">
var_dump("-u","players",getElementsByType("player"),"-d1")
</syntaxhighlight>

<syntaxhighlight lang="lua">
string(7) "players"
table(1) "table: 028B8A10"
string(3) "-d1"
</syntaxhighlight>

</section>

==See Also==
{{Useful_Functions}}

Var dump

2009-11-05T20:51:49Z

Driver2: Created page with '{{Useful Function}} <lowercasetitle>var_dump</lowercasetitle> __NOTOC__ This function outputs information about one or more variables. ==Syntax== <syntaxhighlight lang="lua">string/table var_d…'

{{Useful Function}}
<lowercasetitle>var_dump</lowercasetitle>
__NOTOC__
This function outputs information about one or more variables.

==Syntax==
<syntaxhighlight lang="lua">string/table var_dump( ... )</syntaxhighlight>

===Arguments===
The function can have a variable number of arguments. Those arguments can be of three types:
* '''Modifiers:''' A ''string'' that begins with a "-" (minus) and that is followed by at least another parameter is a modifier. A modifier can change the behaviour of the function. Modifiers don't have to be the first argument, they always work on all arguments after it (see examples).
* '''Names:''' A ''string'' that is followed by at least another parameter and isn't preceeded by another ''string'' (that is not a modifier), is a name. A name is output before the variable output, to make it recognizable (basicially a description of the variable that is being output, e.g. the name).
* '''Values:''' Any value that is not one of the two above will generate an output with information about the variable:
** For ''strings'': string(''lengthOfString'') "''value''"
** For ''userdata'': userdata(''MTA element type'') "''value''"
** For ''tables'': table(''numerOfElements'') "''value''"
*** If the table contains any elements, they will also be output if the appropriate modifiers are set. This will always be in the form [''key''] => ''value'', while ''key'' and ''value'' are formatted by var_dump.

===Modifiers===
* '''v''' (verbose): Dumps more data than usual (for now it outputs whole tables including subtables)
* '''n''' (normal): Switches back into 'normal' non-verbose mode.
* '''s''' (silent): With this activated, it outputs nothing at all, however it still returns the output, so you can use it yourself (also used internally for recursion).
* '''u''' (unnamed): Don't use names. Every ''string'' that is not a modifier will be output as a value, not a decription.
* '''d[number]''' (depth): Output nested tables up to this depth (e.g. "d1" means output all values of the initial table, but not the values of the values, if they are also tables).

===Returns===
Returns a string with all the output in one line and a table with several lines of output.

==Code==
<section name="Server- and/or clientside Script" class="both" show="true">
<syntaxhighlight lang="lua" lang="lua">
-- modifiers: v - verbose (all subtables), n - normal, s - silent (no output), dx - up to depth x, u - unnamed
function var_dump(...)
-- default options
local verbose = false
local firstLevel = true
local outputDirectly = true
local noNames = false
local indentation = "\t\t\t\t\t\t"
local depth = nil

local name = nil
local output = {}
for k,v in ipairs(arg) do
-- check for modifiers
if type(v) == "string" and k < #arg and v:sub(1,1) == "-" then
local modifiers = v:sub(2)
if modifiers:find("v") ~= nil then
verbose = true
end
if modifiers:find("s") ~= nil then
outputDirectly = false
end
if modifiers:find("n") ~= nil then
verbose = false
end
if modifiers:find("u") ~= nil then
noNames = true
end
local s,e = modifiers:find("d%d+")
if s ~= nil then
depth = tonumber(string.sub(modifiers,s+1,e))
end
-- set name if appropriate
elseif type(v) == "string" and k < #arg and name == nil and not noNames then
name = v
else
if name ~= nil then
name = ""..name..": "
else
name = ""
end

local o = ""
if type(v) == "string" then
table.insert(output,name..type(v).."("..v:len()..") \""..v.."\"")
elseif type(v) == "userdata" then
local elementType = "no valid MTA element"
if isElement(v) then
elementType = getElementType(v)
end
table.insert(output,name..type(v).."("..elementType..") \""..tostring(v).."\"")
elseif type(v) == "table" then
local count = 0
for key,value in pairs(v) do
count = count + 1
end
table.insert(output,name..type(v).."("..count..") \""..tostring(v).."\"")
if verbose and count > 0 and (depth == nil or depth > 0) then
table.insert(output,"\t{")
for key,value in pairs(v) do
-- calls itself, so be careful when you change anything
local newModifiers = "-s"
if depth == nil then
newModifiers = "-sv"
elseif depth > 1 then
local newDepth = depth - 1
newModifiers = "-svd"..newDepth
end
local keyString, keyTable = var_dump(newModifiers,key)
local valueString, valueTable = var_dump(newModifiers,value)

if #keyTable == 1 and #valueTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>\t"..valueString)
elseif #keyTable == 1 then
table.insert(output,indentation.."["..keyString.."]\t=>")
for k,v in ipairs(valueTable) do
table.insert(output,indentation..v)
end
elseif #valueTable == 1 then
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
table.insert(output,indentation.."\t=>\t"..valueString)
else
for k,v in ipairs(keyTable) do
if k == 1 then
table.insert(output,indentation.."["..v)
elseif k == #keyTable then
table.insert(output,indentation..v.."]")
else
table.insert(output,indentation..v)
end
end
for k,v in ipairs(valueTable) do
if k == 1 then
table.insert(output,indentation.." => "..v)
else
table.insert(output,indentation..v)
end
end
end
end
table.insert(output,"\t}")
end
else
table.insert(output,name..type(v).." \""..tostring(v).."\"")
end
name = nil
end
end
local string = ""
for k,v in ipairs(output) do
if outputDirectly then
outputConsole(v)
end
string = string..v
end
return string, output
end
</syntaxhighlight>
</section>

==Example==
<section name="Serverside Example" class="server" show="true">
Get a table of all players on the server (if there are 4 players).
<syntaxhighlight lang="lua" lang="lua">
var_dump(getElementsByType("player"))
</syntaxhighlight>
Output:
<syntaxhighlight lang="lua">
table(4) "table: 02998058"
</syntaxhighlight>
With 'verbose' modifier.
<syntaxhighlight lang="lua">
var_dump("-v",getElementsByType("player"))
</syntaxhighlight>
<syntaxhighlight lang="lua">
table(1) "table: 043C6900"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
</syntaxhighlight>

Now another table we created before (please not that the table 'test2' is both key and value in this example):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 020B7838"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 021770A0"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}]
=> table(2) "table: 02313070"
{
[number "1"] => string(4) "haha"
[number "2"] => string(4) "naja"
}
}
</syntaxhighlight>

The same as before, but now with a modifier to output the second table 'normal':
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-n",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 01BB9030"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 0223B2D8"
</syntaxhighlight>

The same as before, but now with a modifier to output the second table only to depth 1 (the verbose is still active from the first argument):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-d1",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
table(1) "table: 029BE6E8"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
table(2) "table: 01E2CDF8"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 021C6378"] => table(2) "table: 021C6378"
}
</syntaxhighlight>

The same as before, but now with names to make clear which output belongs to which variable (of course in this small example, it's not really needed):
<syntaxhighlight lang="lua">
test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v","players",getElementsByType("player"),"-d1","test tables",test)
</syntaxhighlight>

<syntaxhighlight lang="lua">
players: table(1) "table: 0219F4D0"
{
[number "1"] => userdata(player) "userdata: 00000134"
}
test tables: table(2) "table: 0219DB20"
{
[string(5) "hello"] => string(4) "test"
[table(2) "table: 01B68048"] => table(2) "table: 01B68048"
}
</syntaxhighlight>

The same as before, but now 'unnamed', meaning all values that are not modifiers will be output as values. However, the last two arguments were also removed, which leaves the last modifier as last argument, which will output the modifier as a normal value:
<syntaxhighlight lang="lua">
var_dump("-u","players",getElementsByType("player"),"-d1")
</syntaxhighlight>

<syntaxhighlight lang="lua">
string(7) "players"
table(1) "table: 028B8A10"
string(3) "-d1"
</syntaxhighlight>

</section>

==See Also==
{{Useful_Functions}}

Resource:Assault

2008-01-11T21:49:29Z

Driver2: /* Optional Attributes */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
'''(as of version 1.1)'''

These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory.

==General Map Settings==
'''(as of version 1.1, in version 1.0 only some settings can be set in the meta.xml)'''

All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
''none''

====Optional Attributes====
* '''finishObjective:''' Specifies the objective (id) that has to be reached by the attackers in order to finish the round. If left empty, all objectives have to be reached.
* '''finishType:''' You ''can'' specify the '''finishType''' in addition to the '''finishObjective''' (''in version 1.0 this is required'')
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element (version 1.0)
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-11T21:44:43Z

Driver2: /* Required Attributes */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
'''(as of version 1.1)'''

These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory.

==General Map Settings==
'''(as of version 1.1, in version 1.0 only some settings can be set in the meta.xml)'''

All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
''none''

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element (version 1.0)
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T18:05:37Z

Driver2: /* Map Elements */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
'''(as of version 1.1)'''

These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory.

==General Map Settings==
'''(as of version 1.1, in version 1.0 only some settings can be set in the meta.xml)'''

All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element (version 1.0)
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T18:03:18Z

Driver2: /* General Map Settings */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
'''(as of version 1.1)'''

These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
'''(as of version 1.1, in version 1.0 only some settings can be set in the meta.xml)'''

All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element (version 1.0)
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T18:01:54Z

Driver2: /* General Assault Settings */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
'''(as of version 1.1)'''

These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T16:23:22Z

Driver2: /* General Assault Settings */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].
* '''teamBalance''': Defines how many more players can be in either team respectively. For example when you set it to '1' while Team Blue has 2 players and Team Red has 1 player, new players couldn't join Team Blue. If you had set it to '2' in the same situtation, one more player could join Team Blue. (''default: 1'')

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T16:15:38Z

Driver2: /* Assault Settings */

{{Resource page}}
Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=General Assault Settings=
These settings can be specified in Assault's ''meta.xml'' [[Settings system|settings]].

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T14:52:02Z

Driver2: /* Map Elements */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Assault Settings=
=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T14:51:23Z

Driver2: /* General Settings */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Map Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T14:50:46Z

Driver2: /* Assault Settings */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==General Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2008-01-06T14:44:59Z

Driver2: /* Assault Settings */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
All these settings can be specified in the ''meta.xml'' [[Settings system|settings]] or the ''assaultSettings'' element in the mapfile. The ''meta.xml'' settings will always overrule the mapfile settings.

To specifiy the settings in the ''meta.xml'' file, it may look like this:
<syntaxhighlight lang="xml">
<meta>
<info author="driver2" type="map" gamemodes="assault" />
<map src="as-area51.map" />
<script src="as-area51.lua" />

<settings>
<setting name="#author" value="driver2" />
<setting name="#timelimit" value="300" />

</settings>
</meta>
</syntaxhighlight>
To specifiy the settings in the mapfile, put the ''assaultSettings'' in your mapfile:
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

IRC Channel

2008-01-03T19:22:59Z

Driver2: New page: There is an IRC Channel available for help with MTA Scripting. You can find it at #mta.scripting on GTAnet. ==How to get help== * Try to find your Answer on the Main Page, especially t...

There is an IRC Channel available for help with MTA Scripting. You can find it at #mta.scripting on GTAnet.
==How to get help==
* Try to find your Answer on the [[Main Page]], especially the ''Getting Started'' section
* Ask your question once and only repeat it after a reasonable amount of time, given the channel is busy and people just coming online won't see your question else (like 10 minutes). NOT after 10 seconds.
* Your question should at least contain:
** What are you trying to do.
** What have you done so far.
** What exactly doesn't work/is your problem. What errors are occuring.
** Maybe a code snippet with an explanation using [http://mta.pastebin.com mta.pastebin.com] (''code snippet means the relevant parts, NOT the whole script'')

Resource:Assault

2008-01-01T04:15:05Z

Driver2: /* Example map */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Gamemode Assault

2007-12-31T20:30:02Z

Driver2: Gamemode Assault moved to Resource:Assault: New Resource Namespace

#REDIRECT [[Resource:Assault]]

Resource:Assault

2007-12-31T20:30:02Z

Driver2: Gamemode Assault moved to Resource:Assault: New Resource Namespace

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Writing Gamemodes

2007-12-31T18:10:41Z

Driver2: New page: This Guide tries to outline the process of how to write a proper gamemode. If you just started with scripting for MTA, you may want to check the other tutorials at the [[Scripting|Scriptin...

This Guide tries to outline the process of how to write a proper gamemode. If you just started with scripting for MTA, you may want to check the other tutorials at the [[Scripting|Scripting Page]] first.
==Introduction==
A Gamemode is a resource that, once started, controls all of the gameplay. This may include telling the players what to do, spawning players, creating teams, defining what the players have to do to win or to get points and much more. For some of the functionality a gamemode has to provide, there are other resources that can help it to do that.

==What does "proper gamemode" mean?==
To put it simply, a proper gamemode is one that makes full use of MTA's .map file system. This means that you can have the gamemode, but change the .map file of key parts of the gamemode so that there can be lots of maps for this gamemode.

An obvious example of what i define as a "proper gamemode" is that of Race mod - MTA:Race. It allows usermade maps with lots of possibilities within the .map file. To alter spawnpoints, or objects etc, the user does not need to look at editing the gamemode itself.

Examples of what i dont consider gamemodes, are ones that have everything hardcoded within the script. This goes for vehicles, spawnpoints, objects.

===Map Files===
So what kind of things should the map maker have access to in the .map file? Obviously you dont want them changing key parts of your gamemode. You should stick to obvious things - spawnpoints, vehicles etc. In other words, the user should be able to move everything that happens in your gamemode to another location. It should be fairly obvious to you what kind of things the user should or should not have access to.

====Example====
For example, in a Capture the Flag gamemode, you will have important things defined in .map - vehicles, spawnpoints, objects. You will also need to allow the user to define where the flag goes - so they should be able to place a flag element in the .map. As the scripter, you can decide the syntax of the flag element in the .map file (i will come onto how to use custom elements later on). E.g.
<syntaxhighlight lang="xml"><spawnpoint name="spawnpoint1" posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" rot="63.350006103516" model="0"/>
<pickup name="Armor 1" posX="1911.083984375" posY="-1658.8798828125" posZ="885.40216064453" type="armor" health="50" respawn="60000"/>
<flag posX="1959.5487060547" posY="-1714.4613037109" posZ="877.25219726563" team="blue" />
</syntaxhighlight>

Here you can see two MTA elements - spawnpoint and a pickup. More importantly, this .map has a 'flag' element. This means the user can easilly create their own maps by altering these elements. Again, as the scripter you can make up whatever element name you like.

To summarise - we want mass mapper input as we saw in MTA:Race. Users should NOT even have to touch the script file itself at all.

====Example of getting the .map information====
So how would you retrieve information about these "custom elements" from the map file? It is actually very simple(this assumes you have at least some knowledge on Lua and tables).
<syntaxhighlight lang="lua">
--retrieve a table of flag elements
local flagElements = getElementsByType ( "flag" )
--loop through the flag elements
for key, value in pairs(flagElements) do
--get our info
local posX = getElementData ( value, "posX" )
local posY = getElementData ( value, "posY" )
local posZ = getElementData ( value, "posZ" )
local team = getElementData ( value, "team" )
--create an object according to the flag position
createObject ( 1337, posX, posY, posZ )
--output the team that we created a base for
outputChatBox ( "Base for team "..team.." created" )
end</syntaxhighlight>
The getElementsByType function retrieves a table of all the elements of a certain type. This works for custom elements or real MTA elements.
getElementData can be used to retrieve the xml attributes set in the .map file.
In this example, all im doing is creating an object at that position, and outputting the team. In reality, you will be creating the real base or doing whatever is necessary.

==Map manager==
Having read the section above it should be clear that a gamemode should always consist of two parts:
* The gamemode resource that stays always the same
* Many different maps resources that give the gamemode map-specific information

Now instead of writing a map-loader for every single gamemode, the [[Map manager]] provides functions to load gamemodes and maps. Simply put, when you enter the correct command (for example 'gamemode ctf ctf-italy') it will start both resources 'ctf' and 'ctf-italy' while triggering an event to tell the 'ctf' resource that a map was loaded. The 'ctf' resource can then access the information 'ctf-italy' contains and start spawning players etc.

===How to use the mapmanager===
To use the mapmanager service, your gamemode resource has to be tagged as such first. You'll be setting type attribute to "gamemode" in its <info> tag, inside meta.xml. Also, you can set the name attribute to set a friendly name that will be shown on ASE instead of the resource name.
<syntaxhighlight lang="xml">

<meta>
<info type="gamemode" name="Cow catapulting 2.0"/>
</meta>
</syntaxhighlight>

If your gamemode is going to load custom maps, you should add handlers for
* onGamemodeMapStart( resource startedMap )
* onGamemodeMapStop ( resource stoppedMap ) (if any unloading is necessary)
These are fired when a map for your gamemode is started or stopped, and pass the map resource as a parameter.
Within that handler, you can extract all info you need from this resource's map files and configs.

====Example====
<syntaxhighlight lang="lua">
function startCtfMap( startedMap ) -- startedMap contains a reference to the resource of the map
mapRoot = getResourceRootElement( startedMap ) -- get the root node of the started map
local flagElements = getElementsByType ( "flag" , mapRoot ) -- get all flags in the map and store them in a table
-- go on loading information like in the example above

-- spawn players etc.
end

addEventHandler("onGamemodeMapStart", getRootElement(), startCtfMap)
</syntaxhighlight>

===Making maps compatible===
Maps are separate resources. This is done so no editing of the gamemode resource is ever necessary in order to create a custom map, and also allows you to pack map-specific scripts/config files with them.

To make a map compatible with your gamemode, open its resource's meta.xml and tag it as well:
type attribute must be set to "map", and gamemodes attribute must be a comma-separated list of gamemode resource names (without spaces).
<syntaxhighlight lang="xml">
<meta>
<info type="map" gamemodes="cowcatapult,assault,tdm"/>
</meta>
</syntaxhighlight>

Once you have everything set up, admins will use these two commands to start/stop gamemodes:
/gamemode gamemodeName [mapName] (optional parameter allows picking an initial map, defaults to none)
/changemap mapName [gamemodeName] (optional parameter specifies the gamemode to start the map with, defaults to the current one)

[[Map manager]] exports a few more access functions which you don't have to use, but may be useful.

==What else should you do==
There are several other resources that gamemodes should use/be compliant with.

===Helpmanager===
The helpmanager is ought to be the standard interface for players when they need help. If you use the helpmanager to display your gamemode's help, every player that used helpmanager before (e.g. in other gamemodes) will immediately know how to get there. It also displays help for different resources running resources in one window, if necessary.

There are basicially two ways to use the helpmanager:
* Provide a simple text that explains how to use your gamemode
* Request a GUI element from the helpmanager that will be displayed in it's own tab in the helpmanager window and lets you add any GUI elements to it. This is the recommended way for gamemodes that need to display more complex information that requires to be in it's own GUI.

Read the helpmanager page for details on how to do it.

===Scoreboard===
Scoreboard displays players and teams currently ingame. You add custom columns to it to provide map specific information. For example the column 'points' in the 'ctf' gamemode could represent the players points gained through kills or captures. As usual, see the scoreboard help page for more information.

===Map cycler===
The map cycler controls what gamemodes and maps are played on a server. You can specifiy for example how many times in a row a map will be played until it switches to the next. To achieve this, you need to tell the map cycler when your gamemode finished (e.g. when a round ends).

Resource:Assault

2007-12-30T17:33:22Z

Driver2: /* Optional Attributes */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
** ''default:'' Objective '''name''' reached
** If '''name''' and '''successText''' are both not given, no message at all will appear when the objective is reached
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2007-12-30T11:58:54Z

Driver2: /* Additional Information */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends or when it is destroyed, you have to respawn it yourself.

Resource:Assault

2007-12-30T11:58:35Z

Driver2: /* Additional Information */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile. Remember that it will never be automatically respawned then, so if you want to have it return to it's original place, for example after the round ends, you have to respawn it yourself.

Resource:Assault

2007-12-30T11:49:07Z

Driver2: /* Additional Information */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==
* If you don't want a specific vehicle to be respawned by assault, set it's Elementdata item 'noRespawn' to ''true'' by script or add the attribute noRespawn="1" to the element in the mapfile.

Resource:Assault

2007-12-30T11:46:56Z

Driver2: /* Example map */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

==Additional Information==

Resource:Assault

2007-12-29T23:34:13Z

Driver2: /* Optional Attributes */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''finishObjective:''' used when finishType is set to objective
If there is a '''timelimit''', '''time''', '''weather''', '''author''' or '''description''' [[Settings system|setting]] specified in the meta file, it will overule the attribute in this element
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

Resource:Assault

2007-12-29T00:50:28Z

Driver2: /* Cameras */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''finishObjective:''' used when finishType is set to objective
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
You need to define one camera of each type in a valid assault map.
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

Resource:Assault

2007-12-27T13:54:47Z

Driver2: /* Optional Attributes */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''finishObjective:''' used when finishType is set to objective
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#Assault Settings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

Resource:Assault

2007-12-27T13:54:12Z

Driver2: /* Optional Attributes */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''finishObjective:''' used when finishType is set to objective
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows and is displayed at the bottom of the screen to tell the attacker what to do
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective
* '''defenderDescription:''' This text is shown at the bottom of the screen to tell the defenders what to do ''(default: the '''defenderText''' attribute of the [[#assaultSettings]] element)''
* '''successTextForDefender:''' This attribute can overwrite the '''successText''' attribute for defenders

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

Resource:Assault

2007-12-27T13:46:48Z

Driver2: /* Optional Attributes */

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''finishObjective:''' used when finishType is set to objective
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''
* '''defenderText:''' The text that is displayed at the bottom of the screen, telling the defenders what to do. If this text is defined here, it will be set as default for the map, but can be overwritten by single objectives by specifying the according attribute in its element. ''(default: "Prevent attackers from reaching their objectives!")''
* '''attackMessage:''' The message that is shown once an attacker spawns ''(default: "Assault the base!")''
* '''defendMessage:''' The message that is shown once a defender spawns ''(default: "Defend the base!")''
* '''conqueredMessage:''' This message replaces a part of the message that is shown when the attackers successfully reached their objectives ''(default: "conquered the base")''
** This messages replaces the following part enclosed by brackets (example): "Red [conquered the base] in 4:39"
* '''defendedMessage:''' This message replaces a part of the message that is shown when the defenders successfully defended the objectives ''(default: "defended the base")''
** This messages replaces the following part enclosed by brackets (example): "Blue [defended the base]. Blue wins."

It is recommended that you change the above messages only if the default messages make no or little sense for your map, in order to keep the messages (almost) the same for all maps.

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

Resource:Assault

2007-09-13T11:01:46Z

Driver2:

Assault is an objective-based team gamemode that should be similiar to Unreal Tournament's Assault. One team attacks, while the other defends. When the attacking team reached the final objective or the time runs out, the round ends and sides are switched. The team that reaches the final objective faster wins the game, if both can't reach it in the timelimit, the game ends tied.

You can easily create your own Assault maps by placing spawnareas and objectives, and of course objects, vehicles and pickups like on any other map. The default objectives are simple checkpoints you have to enter, but the exported functions allow scripters to create whole new types of objectives. See the documentation for details.

=How does a game work=
* Waiting for players before each new round for a certain amount of seconds or if enough players have joined
** Let players select their team
* Spawn players according to their team
* team1 has to attack and reach one or more objectives (marker), while team2 defends the objectives
** if team1 reached an objective, teamspawns may be at another location, according to the next objective
* if the final objective is reached, the first round ends and team2 has to attack (on the same map)
** the timelimit for the second round should be the time team1 needed to reach the final objective

===Winning===
* If team2 doesn't reach the objective in the timelimit, meaning team1 was faster, team1 wins.
* If team2 is able to reach the objective in the timelimit, meaning team2 was faster, team2 wins.
* If team1 and team2 aren't able to reach the objective within the timelimit, game ends tied.

=Creating an Assault map=
Assault should work with the mapmanager, so additional maps can easily be created. It also triggers events for map specific scripts and provides functions to trigger custom objectives.

If you want to create a simple map without additional code or custom objectives, you may want to skip to the [[#Map Elements]].

=Events/Functions=

<syntaxhighlight lang="lua">onAssaultObjectiveReached ( table objectiveReached, table players )</syntaxhighlight>
Triggers when an objective is successful (when it turns red).
* '''objectiveReached:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])
* '''players:''' A table of all players that were in the marker when it was activated

<syntaxhighlight lang="lua">onAssaultStartRound ( team attacker )</syntaxhighlight>
Triggers when a round actually starts (player spawns), 'attacker' is the team that attacks.
* '''attacker:''' A team element consisting the attacking team

<syntaxhighlight lang="lua">onAssaultCreateObjective ( table objectiveToCreate )</syntaxhighlight>
Triggers when a objective is created or should be created if it's a custom objective, instead of creating the marker when it would be a normal one
* '''objectiveToCreate:''' A table with all the attributes supplied in the map file (see [[#Objectives|Map Elements]])

<syntaxhighlight lang="lua">onAssaultEndRound( bool conquered )</syntaxhighlight>
Triggers when the round ends (time up or base conquered)
* '''conquered:''' If the attacker was successful in completing the objectives, true otherwise false.

<syntaxhighlight lang="lua">bool triggerObjective( string objectiveId, [table players] )</syntaxhighlight>
Used to trigger an objective. Returns ''true'' if it can be triggered, ''false'' otherwise.
* '''objectiveId:''' ''(required)'' The id (like defined in the .map file) of the objective.
* '''players:''' A table of all players that were reponsible for activating the objective

''Please note that you have to use [[Call]] with exported functions.''

=Map Elements=
To create an Assault map, all of these elements are obligatory. ''Note that these elements may change during early stages of development.''

==Assault Settings==
<syntaxhighlight lang="xml">
<assaultSettings timelimit="(int=300)"
finishType="(string)" finishObjective="(string)"
time="(time=12:00)" weather="(int=0)"
author="{string=''}" description="{string=''}" />
</syntaxhighlight>

====Required Attributes====
* '''finishType:''' when will a team have conquered the base/reached the objective
** '''"objective":''' when a certain objective is reached
** '''"all":''' when all objectives are reached

====Optional Attributes====
* '''timelimit:''' duration of one round in seconds ''(default: 300)''
* '''finishObjective:''' used when finishType is set to objective
* '''time:''' time hours:minutes ''(default: 12:00)''
* '''weather:''' weather id ''(default: 0)''
* '''author:''' the map author ''(default: "")''
* '''description:''' map description ''(default: "")''

==Objectives==
<syntaxhighlight lang="xml"><objective name="(string)" description="(string)" successText="(string)" id="(string)" req="(string)"
posX="(float)" posY="(float)" posZ="(float)" stay="{int=0}"
forcedRespawn="{string=none}" markerType="{string=cylinder}" captureType="{string=foot}" /></syntaxhighlight>

The order of the objectives in the .map file matters. It is responsible for the order the objectives are displayed on the hud, as well as in the GUI.

====Required Attributes====
* '''posX, posY, posZ: (required)''' position of the objective

====Optional Attributes====
* '''name:''' the name of the objective, used for the objective list on the screen
* '''description:''' may be used in the help windows
* '''successText:''' shown when the objective is reached, use ~team~ as a variable for the attacker's team name
* '''id:''' unique identification for the objective
* '''req:''' objectives required for this objective, ids seperated by comma, e.g. req="door,room1,room2"
* '''type:''' the type of the objective
** '''"checkpoint":''' ''(default)'' assault creates a checkpoint at the location, which has to be activated by the attacker by walking into it
** '''"custom":''' assault does nothing about it except waiting for another script to trigger it (see other assault maps for how it's done)
* '''forcedRespawn'''
** '''"both":''' make all players respawn, as soon as the objective is created
** other values may come
* '''markerType:''' defines the type of the marker used to mark the objective (see [[CreateMarker]] for details on the values)
* '''captureType:''' defines how the objective can be activated
** '''"both":''' on foot and in a vehicle
** '''"foot":''' only while on foot
** '''"vehicle":''' only while in a vehicle
* '''stay:''' number of seconds the player needs to stay in the objective
* '''stayText:''' the text that is shown above the progress bar while being in the objective

==Spawngroups==
<syntaxhighlight lang="xml">
<spawngroup type="(string)" req="(string)">
- put spawnareas here -
</spawngroup>
</syntaxhighlight>

A spawngroup is a collection of one or several spawnareas. One of the spawnareas will be randomly selected on spawn. You can use this to let attacking players attack from different sides or to let some players spawn with different weapons for example. Always the last spawngroup (from the order in the mapfile) that meets the 'req' requirements is used to spawn players.

====Required Attributes====
* '''type:'''
** '''"attacker":''' a spawngroup for the attacking team
** '''"defender":''' a spawngroup for the defending team

====Optional Attributes====
* '''req:''' objective ids seperated by comma required for this checkpoint to work

==Spawnareas==
<syntaxhighlight lang="xml">
<spawnarea posX="(float)" posY="(float)" posZ="(float)" sizeX="(int=2)" sizeY="(int=2)" skins="{int,int=0}" weapons="{int,int;int,int=''}" radius="{int=2}" shape="{string=circle}" />
</syntaxhighlight>

A spawnarea is a rectangle or circle in which players are spawned randomly. It is defined by one point and two size values or the radius.

====Required Attributes====
* '''posX, posY, posZ:''' position

====Optional Attributes====
* '''skins:''' list of skins of which one is randomly chosen, seperated by comma, range of skins seperated by hyphen (e.g. 10,14,20-24 would be 10,14,20,21,22,23,24)
* '''weapons:''' weapon1,ammo1;weapon2,ammo2;weapon3,ammo3..
* '''shape'''
** '''"circle": (default)''' a circle
** '''"rectangle":''' a rectangle
* '''sizeX, sizeY:''' if shape="rectangle", the maximum number that will be added to the X or Y coordinate
* '''radius:''' if shape="circle", radius of the circle

==Cameras==
<syntaxhighlight lang="xml"><camera type="(string)" posX="(float)" posY="(float)" posZ="(float)" targetX="(float)" targetY="(float)" targetZ="(float)" /></syntaxhighlight>

====Required Attributes====
* '''posX, posY, posZ, targetX, targetY, targetZ:''' position and look at
* '''type:''' defines the type of the camera, when it will be used
** '''"spawn":''' after selecting the team and before spawning
** '''"selectTeam":''' select Team screen
** '''"finish":''' when the last objective is reached

====Optional Attributes====
(none)

==Example map==
Check out /resources/as-area51/ on the ftp.

GetPickupWeapon

2007-08-26T14:42:12Z

Driver2: /* Example */

{{Server client function}}
__NOTOC__
This function retrieves the weapon ID of a weapon pickup.
==Syntax==
<syntaxhighlight lang="lua">
int getPickupWeapon ( pickup thePickup )
</syntaxhighlight>

===Required Arguments===
*'''thePickup:''' The pickup of which you wish to retrieve the weapon

===Returns===
Returns the [[Weapons|Weapon ID]] of the pickup, or ''false'' if the pickup is invalid.

==Example==
This example gives extra ammo to a player if a pickup only has a small amount of ammo.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function onPickupHitFunc ( thePlayer ) -- when a pickup is hit
if getPickupType ( source ) == 2 then -- check if it's a weapon pickup
local ammo = getPickupAmmo ( source ) -- get the pickup ammo
if ammo < 50 then -- if ammo is less than 50
local weapon = getPickupWeapon ( source ) -- store pickup weapon
giveWeaponAmmo ( thePlayer, weapon, 50 ) -- give an extra 50 ammo
end
end
end
addEventHandler ( "onPickupHit", getRootElement(), onPickupHitFunc ) -- add the function as handler for onPickupHit
</syntaxhighlight>
</section>

==See Also==
{{IDs}}

{{Pickup functions}}

Element

2007-08-08T18:39:32Z

Driver2:

{{Needs_Checking|Need to make sure all elements are listed --[[User:Erorr404|Erorr404]] 21:44, 8 December 2006 (CST)}}

An element is a generic class that represents almost all in-game items. These include:
* [[Element/Player|Players]]
* [[Element/Vehicle|Vehicles]]
* [[Element/Object|Objects]]
* [[Element/Pickup|Pickups]]
* [[Element/Marker|Markers]]
* [[Element/Collision shape|Collision shapes]]
* [[Element/Blip|Blips]]
* [[Element/Radar area|Radar areas]]
* [[Element/Team|Teams]]
* [[Element/Remote client|Remote clients]]
* [[Element/Server console|Server console]]

These are all stored internally in a [[Element tree|"tree" structure]], as such every element has a parent element, be in the ''root'' element, ''map'' or another element. This is purely for declaring the scope of function calls.

There are various functions for manipulating the layout of this element tree.

Element tree

2007-08-08T18:34:45Z

Driver2: /* Map manager */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
* 'root': This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* 'resource': These are direct children of the root element - with one for each ''running'' resource.
* 'map': Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).
** Map files can contain a number of other [[element]] types as well as an unlimited number of custom element types.

==Example==
This in an example of a tree of a running server. ''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
* root
o console
o player {dontRespawn = false}
o player {dontRespawn = false, lastSpawnarea = [object Object]}
+ resourcebrowser: resource
+ ajax: resource
+ resourcemanager: resource
+ spawnmanager: resource
+ echobot: resource
+ mapmanager: resource
+ runcode: resource
- fr: resource
- dynamic: map
# vehicle
+ elementbrowser: resource
- assault: resource
- dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
- as-farm: resource
o dynamic: map
- as-farm.map: map
- meta
* author
* version
* name
* description
- spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
- spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
- spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
- spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
* first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
* pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==
Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

===Setting data for elements===
If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

===Map manager===
The [[#Example|example above]] shows the way the mapmanger uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives the id of the started resource - in this case 'as-farm' - from which you can retrieve the root element of the resource and store it in a variable. Using this element in conjunction with functions like [[getElementsByType]], [[getElementData]] and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you '''do''' have to remove elements that are created within the gamemode resource, '''if''' they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).

Element tree

2007-08-08T18:31:11Z

Driver2: /* Example */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
* 'root': This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* 'resource': These are direct children of the root element - with one for each ''running'' resource.
* 'map': Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).
** Map files can contain a number of other [[element]] types as well as an unlimited number of custom element types.

==Example==
This in an example of a tree of a running server. ''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
* root
o console
o player {dontRespawn = false}
o player {dontRespawn = false, lastSpawnarea = [object Object]}
+ resourcebrowser: resource
+ ajax: resource
+ resourcemanager: resource
+ spawnmanager: resource
+ echobot: resource
+ mapmanager: resource
+ runcode: resource
- fr: resource
- dynamic: map
# vehicle
+ elementbrowser: resource
- assault: resource
- dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
- as-farm: resource
o dynamic: map
- as-farm.map: map
- meta
* author
* version
* name
* description
- spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
- spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
- spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
- spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
* first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
* pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==
Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

===Setting data for elements===
If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

===Map manager===
The example above shows the way the mapmanger uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives the id of the started resource - in this case 'as-farm' - from which you can retrieve the root element of the resource and store it in a variable. Using this element in conjunction with functions like [[getElementsByType]], [[getElementData]] and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you '''do''' have to remove elements that are created within the gamemode resource, '''if''' they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).

Element tree

2007-08-08T18:25:20Z

Driver2: /* Tree Elements */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
* 'root': This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* 'resource': These are direct children of the root element - with one for each ''running'' resource.
* 'map': Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).
** Map files can contain a number of other [[element]] types as well as an unlimited number of custom element types.

==Example==
This in an example of a tree of a running server. ''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
* root
o console
+ resourcebrowser: resource
+ ajax: resource
+ resourcemanager: resource
+ spawnmanager: resource
+ echobot: resource
+ mapmanager: resource
+ playerblips: resource
+ runcode: resource
- fr: resource
- dynamic: map
# vehicle
+ player {dontRespawn = false, lastSpawnarea = [object Object]}
+ elementbrowser: resource
o player {dontRespawn = false}
- assault: resource
- dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
- as-farm: resource
o dynamic: map
- as-farm.map: map
- meta
* author
* version
* name
* description
- spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
- spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
- spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
- spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
* first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
* pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==
Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

===Setting data for elements===
If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

===Map manager===
The example above shows the way the mapmanger uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives the id of the started resource - in this case 'as-farm' - from which you can retrieve the root element of the resource and store it in a variable. Using this element in conjunction with functions like [[getElementsByType]], [[getElementData]] and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you '''do''' have to remove elements that are created within the gamemode resource, '''if''' they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).

Element tree

2007-08-08T18:20:44Z

Driver2: /* Pratical Application */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
When this map is loaded, it is placed within the server's element tree. This tree has a number of "special" elements.

* A root element. This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* Resource elements. These are direct children of the root element - with one for each ''running'' resource.
* Map elements. Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).

==Example==
This in an example of a tree of a running server. ''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
* root
o console
+ resourcebrowser: resource
+ ajax: resource
+ resourcemanager: resource
+ spawnmanager: resource
+ echobot: resource
+ mapmanager: resource
+ playerblips: resource
+ runcode: resource
- fr: resource
- dynamic: map
# vehicle
+ player {dontRespawn = false, lastSpawnarea = [object Object]}
+ elementbrowser: resource
o player {dontRespawn = false}
- assault: resource
- dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
- as-farm: resource
o dynamic: map
- as-farm.map: map
- meta
* author
* version
* name
* description
- spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
- spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
- spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
- spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
* first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
* pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==
Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

===Setting data for elements===
If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

===Map manager===
The example above shows the way the mapmanger uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives the id of the started resource - in this case 'as-farm' - from which you can retrieve the root element of the resource and store it in a variable. Using this element in conjunction with functions like [[getElementsByType]], [[getElementData]] and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you '''do''' have to remove elements that are created within the gamemode resource, '''if''' they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).

Element tree

2007-08-08T18:07:03Z

Driver2: /* Example */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
When this map is loaded, it is placed within the server's element tree. This tree has a number of "special" elements.

* A root element. This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* Resource elements. These are direct children of the root element - with one for each ''running'' resource.
* Map elements. Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).

==Example==
This in an example of a tree of a running server. ''Please note that it is shortened on some places for the sake of overview.''
<syntaxhighlight lang="xml">
* root
o console
+ resourcebrowser: resource
+ ajax: resource
+ resourcemanager: resource
+ spawnmanager: resource
+ echobot: resource
+ mapmanager: resource
+ playerblips: resource
+ runcode: resource
- fr: resource
- dynamic: map
# vehicle
+ player {dontRespawn = false, lastSpawnarea = [object Object]}
+ elementbrowser: resource
o player {dontRespawn = false}
- assault: resource
- dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
- as-farm: resource
o dynamic: map
- as-farm.map: map
- meta
* author
* version
* name
* description
- spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
- spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
- spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
- spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
* first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
* pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==

Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

Element tree

2007-08-08T18:00:42Z

Driver2: /* Explaination */

MTA uses a so-called ''element tree'' to store all the elements that exist on the server. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

==Tree Elements==
When this map is loaded, it is placed within the server's element tree. This tree has a number of "special" elements.

* A root element. This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* Resource elements. These are direct children of the root element - with one for each ''running'' resource.
* Map elements. Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).

==Example==
<syntaxhighlight lang="xml">
* root
o console
o resourcebrowser: resource
o ajax: resource
o resourcemanager: resource
o spawnmanager: resource
o echobot: resource
o mapmanager: resource
o playerblips: resource
o runcode: resource
o fr: resource
+ dynamic: map
# vehicle
o player {dontRespawn = false, lastSpawnarea = [object Object]}
o elementbrowser: resource
o player {dontRespawn = false}
o assault: resource
+ dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
o as-farm: resource
+ dynamic: map
+ as-farm.map: map
# meta
* author
* version
* name
* description
# spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
# spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
# spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
# spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
# first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
# pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

===Explanation===
This tree consists of a number of resources and 2 [[player]] elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a [[vehicle]]. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with [[setElementData]] and [[getElementData]].

==Pratical Application==

Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

Element tree

2007-08-08T17:43:58Z

Driver2:

Element tree

2007-08-08T17:37:50Z

Driver2:

MTA uses a so-called ''element tree'' to store the elements that make up the map. This is directly related to the XML [[map file]]'s layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of ''trees'' in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every [[element]] has a ''parent'' element. This element is the element that it is contained within in the [[map file]]. For example:

<syntaxhighlight lang="xml">
<map>
<marker>
<vehicle/>
</marker>
</map>
</syntaxhighlight>

==Example==
<syntaxhighlight lang="xml">
* root
o console
o resourcebrowser: resource
o ajax: resource
o resourcemanager: resource
o spawnmanager: resource
o echobot: resource
o mapmanager: resource
o playerblips: resource
o runcode: resource
o fr: resource
+ dynamic: map
# vehicle
o player {dontRespawn = false, lastSpawnarea = [object Object]}
o elementbrowser: resource
o player {dontRespawn = false}
o assault: resource
+ dynamic: map
# team
# team
# blip
# marker
# colshape
# blip
# blip
o as-farm: resource
+ dynamic: map
+ as-farm.map: map
# meta
* author
* version
* name
* description
# spawngroup {req = , type = attacker}
* spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..}
# spawngroup {req = first, type = attacker}
* spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
# spawngroup {req = , type = defender}
* spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..}
# spawngroup {req = first, type = defender}
* spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..}
# first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
# pickup {posY = 37.083660125732, type = weapon, ..}
</syntaxhighlight>

In this example, the ''vehicle'' element's parent is the ''marker'' element. As such, we call the vehicle element a ''child'' element of the ''marker'' element.

When this map is loaded, it is placed within the server's element tree. This tree has a number of "special" elements.

* A root element. This is at the very base of the tree - all elements are children (or grand children etc) of this element.
* Resource elements. These are direct children of the root element - with one for each ''running'' resource.
* Map elements. Each resource element contains at least 1 map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).

Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to ''2.5''.
<syntaxhighlight lang="lua">
setMarkerSize ( getRootElement(), 2.5 )
</syntaxhighlight>

The same can be done on any element, it is not restricted to the root element.

Local

2007-08-07T19:27:32Z

Driver2:

A local variable only exists within the scope it is specified. The scope is the 'level' it is visible for the script and thus readable and editable.

==Usage==
You should use local variables anytime it is possible, when you don't need to access them globally. This saves you from having troubles with duplicate variable names.

==Examples==
<syntaxhighlight lang="lua">
function showMoney(source)
local playermoney = getPlayerMoney ( source )
outputChatBox(playermoney)
end
</syntaxhighlight>

The ''playermoney'' variable only exists within the 'showMoney' function.

<syntaxhighlight lang="lua">
outputChatBox("This is your status:",player)
if (showHealth == true) then
local health = getPlayerHealth(player)
outputChatBox("Heahlth: "..health,player)
end
</syntaxhighlight>

The ''health'' variable only exists within the ''if''-condition block, that is between the 'then' and the 'end'.

IsPlayerOnGround

2007-08-07T12:04:10Z

Driver2:

__NOTOC__
{{Server client function}}
This function is used to determine whether or not a player is on the ground. This is for on-foot usage only.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerOnGround ( player thePlayer )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': The [[player]] you are checking.

===Returns===
Returns ''true'' if the player is on the ground, ''false'' otherwise and if he is in a vehicle capable of flying.

==Example==
This examle checks if the player who enters the 'amiflying' command is on the ground and outputs a message
<syntaxhighlight lang="lua"> [lua]
function isHeFlying ( source, key )
if ( isPlayerOnGround ( source ) ) then
outputChatBox ( "no, you're not flying, you're just stoned!" )
else
outputChatBox ( "is it a bird, is it a plane.. no its " .. getClientName ( source ) )
end
end
addCommandHandler ( "amiflying", isHeFlying )
</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerNametagShowing

2007-08-07T12:03:43Z

Driver2:

__NOTOC__
{{Server function}}

This function will allow you to determine if a player's name tag is currently showing.

==Syntax==

<syntaxhighlight lang="lua">
bool isPlayerNametagShowing ( player thePlayer )
</syntaxhighlight>

===Required Arguments===

*'''thePlayer:''' The player whose current name tag condition you want to check

===Returns===

Returns ''true'' if successful, ''false'' otherwise.

==Example==

This example toggles a player's nametag. If no playername is given, it toggles the nametag of the player who entered the command.

<syntaxhighlight lang="lua">
function toggleNametag(player,command,who)
local tplayer = player -- define 'tplayer' as the player who called the command
if (who ~= nil) then -- if there was a nick entered in the command
tplayer = getPlayerFromNick(who) -- search for the player
else
who = getClientName(player)
end
if (tplayer ~= false) then -- if the player was found (or no playername was entered)
if (isPlayerNametagShowing(tplayer) == true) then -- if the nametag is shown
setPlayerNametagShowing(tplayer,false) -- hide it
outputChatBox("Nametag is now hidden for "..who,player) -- output a message to the player who entered the command
else -- if the nametag is not shown
setPlayerNametagShowing(tplayer,true) -- show it
outputChatBox("Nametag is now showing for "..who,player) -- output a message to the player who entered the command
end
else
outputChatBox("Player not found.",player)
end
end
addCommandHandler("toggleNametag",toggleNametag)
</syntaxhighlight>

==See Also==

{{Player_functions}}

IsPlayerMuted

2007-08-07T12:03:26Z

Driver2:

__NOTOC__
{{Server client function}}
This function returns true if a player has been muted and false otherwise.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerMuted ( player thePlayer )</syntaxhighlight>

===Required Arguments===
*'''player''': The [[player]] you are checking.

===Returns===
Returns true if a player has been muted and false otherwise.

==Example==
<syntaxhighlight lang="lua">if ( isPlayerMuted ( findPlayer ( "someGuy" ) ) then
outputChatBox ( "It seems Someguy can't speak to you.", player )
end</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerMapForced

2007-08-07T12:03:11Z

Driver2:

__NOTOC__
{{Server function}}
This function checks if the specified player's radar-map has been forced on or not.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerMapForced ( player thePlayer )</syntaxhighlight>

===Required Arguments===
* '''thePlayer''': A [[player]] object referencing the specified player

===Returns===
Returns ''true'' if the player's radar-map is forced on, ''false'' otherwise.

==Example==
This example forces a players radar-map on for 10seconds if it hasnt been already
<syntaxhighlight lang="lua">
function forceMapForPlayer(callingPlayer,command,who)
player = getPlayerFromNick ( who ) -- do we have a player named "dave"
if ( player ) then
if ( isPlayerMapForced ( player ) == false ) then -- if his radar-map isn't already forced on
forcePlayerMap ( player, true ) -- force it on
setTimer ( forcePlayerMap, 10000, 1, player, false ) -- force it off in 10secs
outputChatBox("Forcing Map for "..who,callingPlayer) -- output a message to the one who entered the command
else
outputChatBox("Map already forced for "..who,callingPlayer) -- if the map is already forced, output a message
end
else
outputChatBox("Couldn't find "..who,callingPlayer) -- if the player wasn't found, output a message
end
end
addCommandHandler("forceMap", forceMapForPlayer) -- add a command handler
</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerInVehicle

2007-08-07T12:03:01Z

Driver2:

__NOTOC__
{{Server client function}}
This function checks if a player is in a vehicle.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerInVehicle ( player thePlayer )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': The [[player]] element you are checking.

===Returns===
Returns ''true'' if the player is inside a vehicle, ''false'' if he isn't or an invalid player was passed.

==Example==
This code defines an ''isinvehicle'' command which tells a player whether another player is in a vehicle or not.
<syntaxhighlight lang="lua">
-- we create our handler function, where sourcePlayer is the player who sent the command,
-- and checkedPlayerName is the player name specified.
function outputIsInVehicle ( sourcePlayer, commandName, checkedPlayerName )
-- we get the player element from the nick specified
local checkedPlayer = getPlayerFromNick ( checkedPlayerName )
-- if it exists,
if ( checkedPlayer ) then
-- if it's in a vehicle,
if isPlayerInVehicle ( checkedPlayer ) then
-- tell the source player
outputChatBox ( checkedPlayerName .. " is in a vehicle.", sourcePlayer )
-- if it's not in a vehicle,
else
-- tell the source player
outputChatBox ( checkedPlayerName .. " is not in a vehicle.", sourcePlayer )
end
-- if it doesn't exist,
else
-- tell the source player
outputChatBox ( "Invalid player name.", sourcePlayer )
end
end

-- define a handler for the isinvehicle command
addCommandHandler ( "isinvehicle", outputIsInVehicle )
</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerDucked

2007-08-07T12:02:43Z

Driver2:

__NOTOC__
{{Server client function}}
This function checks if the specified [[player]] is ducked (crouched) or not.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerDucked ( player thePlayer )</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': A [[player]] object referencing the specified player

===Returns===
Returns ''true'' if the player is ducked, ''false'' otherwise.

==Example==
This example checks if a random player is ducked or not, and if so displays a message in the chat box.
<syntaxhighlight lang="lua">
aPlayer = getRandomPlayer ( )
if ( isPlayerDucked ( aPlayer ) ) then
outputChatBox ( getClientName ( aPlayer ) .. " is currently crouching." )
end
</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerDoingTask

2007-08-07T12:02:12Z

Driver2:

__NOTOC__
{{Client function}}
This function checks if the specified player is carrying out a certain [[List of player tasks|task]].

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerDoingTask ( player thePlayer, string taskName )</syntaxhighlight>

===Required Arguments===
* '''thePlayer''': A [[player]] object referencing the specified player.
* '''taskName''': A string containing the name of the [[List of player tasks|task]] you're checking for.

===Returns===
Returns ''true'' if the player is currently doing the task, ''false'' otherwise.

==Example==
This example checks if the player who entered the 'doingdriveby' command is doing a drive-by (clientside).
<syntaxhighlight lang="lua">
function amIDoingADriveby ()
if ( isPlayerDoingTask ( getLocalPlayer(), "TASK_SIMPLE_GANG_DRIVEBY" ) ) then
outputChatBox ( getPlayerName ( getLocalPlayer() ) .. " is doing a driveby!!!" )
else
outputChatBox ( getPlayerName ( getLocalPlayer() ) .. " is not doing a driveby" )
end
end
addCommandHandler ( "doingdriveby", amIDoingADriveby )
</syntaxhighlight>

==See Also==
{{Player functions}}

IsPlayerDead

2007-08-07T12:01:57Z

Driver2:

__NOTOC__
{{Server client function}}
This function checks if the specified [[player]] is dead or not.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerDead ( player thePlayer )</syntaxhighlight>

===Required Arguments===
* '''thePlayer''': A [[player]] object referencing the specified player

===Returns===
Returns ''true'' if the player is dead, ''false'' otherwise.

==Example==
This example checks if a random player is dead, and if so displays a message in the chat.
<syntaxhighlight lang="lua">
player = getRandomPlayer ( )
if ( isPlayerDead ( player ) ) then
outputChatBox ( getClientName ( player ) .. " has bitten the dust." )
end
</syntaxhighlight>

==See Also==
{{Player functions}}