Multi Theft Auto: Wiki - User contributions [en]

Resource:Runcode

2015-03-14T11:19:42Z

Johan van Tiel:

{{Resource page}}
'''runcode''' is a resource that allows dynamic execution of Lua code input from the in-game console, server console or the web interface. This should, in principle, be restricted to server admins.

==Console commands==
There are three runcode commands that can be used:

'''/run <lua code>''': executes a chunk of server-side code and notifies all players.

'''/srun <lua code>''': executes a chunk of server-side code silently (only outputs the command's results to the player who input it).

'''/crun <lua code>''': executes a chunk of client-side code for the player who input the command.

Please note that, more often that not, we want to get the value returned by our code, and due to this, the value of the input expression is automatically returned by runcode for all of these commands (this is, "return " is appended to the beginning of the code). While this saves constant typing of the "return" expression, it will produce an error when the code consists in a language construct that does not yield a value (e.g an assignment or a for statement). For these cases, you can input the following statement:
<syntaxhighlight lang="lua">
loadstring("your code here as a string")()
</syntaxhighlight>

This will load your code chunk as a new function and calls it, so returning its value is possible.

==Web interface==
A http interface page is also provided where admins can run server side snippets in a more convenient way. It uses [http://codepress.sourceforge.net/ CodePress] for syntax highlighting, including all available Lua and MTA functions.
[[ru:Resource:Runcode]]

DxCreateTexture

2015-03-13T16:29:51Z

Johan van Tiel: Woops, undo ^^

{{Client function}}
__NOTOC__
This function creates a [[texture]] element that can be used in the dxDraw functions.

It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
==Syntax==
<syntaxhighlight lang="lua">
element dxCreateTexture ( string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( string pixels [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )
</syntaxhighlight>
{{OOP||[[Texture|DxTexture]]}}
===Required Arguments===
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
or
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
or
*'''width:''' Desired width (Must be a power of two. e.g. 128, 256)
*'''height :''' Desired height (Must be a power of two. e.g. 128, 256)

===Optional Arguments===
*'''textureFormat :''' A string representing the desired texture format, which can be one of:
**'''"argb"''' : ARGB uncompressed 32 bit color (default)
**'''"dxt1"''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and can '''speed up drawing'''. Quality not as good as ARGB and does not support alpha blending.
**'''"dxt3"''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports smooth alpha blending.
**'''"dxt5"''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports crisp alpha blending.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
*'''textureEdge :''' A string representing the desired texture edge handling, which can be one of:
**'''"wrap"''' : Wrap the texture at the edges (default)
**'''"clamp"''' : Clamp the texture at the edges. This may help avoid edge artifacts.
*'''textureType :''' A string representing the desired texture type, which can be one of:
**'''"2d"''' : Standard texture (default)
**'''"3d"''' : Volume texture
**'''"cube"''' : Cube map
*'''depth:''' Desired number of slices when creating a volume texture

==Returns==
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
addEventHandler( "onClientRender", root,
function()
if myImage then
dxDrawImage( 100, 350, 300, 350, myImage )
end
end
)

-- Use 'toggle' command to switch image on and off
addCommandHandler( "toggle",
function()
if not myImage then
myImage = dxCreateTexture( "moonpig.png" ) -- Create texture
else
destroyElement( myImage ) -- Destroy texture
myImage = nil
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04021|Added textureType and depth argument}}
{{ChangelogItem|1.3.0-9.04035|Added textureEdge argument}}

==See Also==
{{Drawing_functions}}

DxCreateTexture

2015-03-13T15:48:55Z

Johan van Tiel:

{{Client function}}
__NOTOC__
This function creates a [[texture]] element that can be used in the dxDraw functions.

It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
==Syntax==
<syntaxhighlight lang="lua">
element dxCreateTexture ( string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( string pixels [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
</syntaxhighlight>
<syntaxhighlight lang="lua">
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )
</syntaxhighlight>
{{OOP||[[Texture|DxTexture]]}}
===Required Arguments===
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
or
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
or
*'''width:''' Desired width (Must be a power of two. e.g. 128, 256)
*'''height :''' Desired height (Must be a power of two. e.g. 128, 256)

===Optional Arguments===
*'''textureFormat :''' A string representing the desired texture format, which can be one of:
**'''"argb"''' : ARGB uncompressed 32 bit color (default)
**'''"dxt1"''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and can '''speed up drawing'''. Quality not as good as ARGB and does not support alpha blending.
**'''"dxt3"''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports smooth alpha blending.
**'''"dxt5"''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and can '''speed up drawing'''. Quality slightly better than DXT1 and supports crisp alpha blending.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
*'''textureEdge :''' A string representing the desired texture edge handling, which can be one of:
**'''"wrap"''' : Wrap the texture at the edges (default)
**'''"clamp"''' : Clamp the texture at the edges. This may help avoid edge artifacts.
*'''textureType :''' A string representing the desired texture type, which can be one of:
**'''"2d"''' : Standard texture (default)
**'''"3d"''' : Volume texture
**'''"cube"''' : Cube map
*'''depth:''' Desired number of slices when creating a volume texture

==Returns==
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<syntaxhighlight lang="lua">
addEventHandler( "onClientRender", root,
function()
if myImage then
dxDrawImage( 100, 350, 300, 350, myImage )
end
end
)

-- Use 'toggle' command to switch image on and off
addCommandHandler( "toggle",
function()
if not myImage then
myImage = dxCreateTexture( "moonpig.png" ) -- Create texture
else
destroyElement( myImage ) -- Destroy texture
myImage = nil
end
end
)
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04021|Added textureType and depth argument}}
{{ChangelogItem|1.3.0-9.04035|Added textureEdge argument}}

==See Also==
{{Drawing_functions}}

Talk:ConvertTextToSpeech

2015-03-09T00:19:04Z

Johan van Tiel: Created page with "When using non-standard/Latin characters (e.g. é,ô,ø,か,Д), it is required to URL Encode the given string and add "&ie=UTF-8" to the URL. Else Google TTS will return an o..."

When using non-standard/Latin characters (e.g. é,ô,ø,か,Д), it is required to URL Encode the given string and add "&ie=UTF-8" to the URL. Else Google TTS will return an odd speech result. --[[User:Johan van Tiel|Jockie]] ([[User talk:Johan van Tiel|talk]]) 00:19, 9 March 2015 (UTC)

DownloadFile

2012-04-15T10:12:02Z

Johan van Tiel: Undo revision 29959 by Erdem kilic (talk)

{{Client function}}
__NOTOC__
This function downloads a file from the HTTP server. This can only be used on files on the HTTP server associated with the MTA server and will only download files from within the folder of the resource that is calling it. The '''file''' should also be included in meta.xml with the '''download''' attribute set to "false", see [[meta.xml]] for more details. If the file has been previously downloaded and the CRC matches, the file will not be downloaded again but [[onClientFileDownloadComplete]] will still run.

==Syntax==
<syntaxhighlight lang="lua">
bool downloadFile ( string fileName )
</syntaxhighlight>

===Required Arguments===
* '''fileName''': A string referencing the name of the file to download

===Returns===
Returns ''true'' if file download has been queued, ''false'' otherwise.

==Example==
'''Example 1:''' This client side event downloads a file when the resource has started.
<syntaxhighlight lang="lua">
-- the function is called, since the local player never changes)
function onStart ( )
downloadFile ( "test.txt" )
end
addEventHandler ( "onClientResourceStart", getRootElement(), onStart )
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}

DownloadFile

2012-04-15T10:11:48Z

Johan van Tiel: Undo revision 29960 by Erdem kilic (talk)

{{Client function}}
__NOTOC__
This function downloads a file from the HTTP server. This can only be used on files on the HTTP server associated with the MTA server and will only download files from within the folder of the resource that is calling it. The '''file''' should also be included in meta.xml with the '''download''' attribute set to "false", see [[meta.xml]] for more details. If the file has been previously downloaded and the CRC matches, the file will not be downloaded again but [[onClientFileDownloadComplete]] will still run.

==Syntax==
<syntaxhighlight lang="lua">
bool downloadFile ( string fileName )
</syntaxhighlight>

===Required Arguments===
* '''fileName''': Indirmek için dosyanın adını başvuran bir dize

===Returns===
Returns ''true'' if file download has been queued, ''false'' otherwise.

==Example==
'''Example 1:''' This client side event downloads a file when the resource has started.
<syntaxhighlight lang="lua">
-- the function is called, since the local player never changes)
function onStart ( )
downloadFile ( "test.txt" )
end
addEventHandler ( "onClientResourceStart", getRootElement(), onStart )
</syntaxhighlight>

==See Also==
{{Client_utility_functions}}

DxCreateFont

2012-04-10T18:51:39Z

Johan van Tiel:

{{Client function}}
__NOTOC__
This function creates a [[DX font]] element that can be used in [[dxDrawText]]. Successful font creation is not guaranteed, and may fail due to hardware or memory limitations.

To see if creation is likely to fail, use [[dxGetStatus]]. (When '''VideoMemoryFreeForMTA''' is zero, failure ''is'' guaranteed.)
=====It is highly recommended that [[dxSetTestMode]] is used when writing and testing scripts using dxCreateFont.=====

==Syntax==
<syntaxhighlight lang="lua">
element dxCreateFont ( string filepath[, int size=9, bool bold=false ] )
</syntaxhighlight>

===Required Arguments===
*'''filepath:''' the name of the file containing the font

===Optional Arguments===
*'''size:''' size of the font
*'''bold:''' flag to indicate if the font should be bold

===Returns===
Returns a [[DX font]] element if successful, ''false'' if invalid arguments were passed to the function, or there is insufficient resources available.

'''You should always check to see if this function has returned false.'''

==Example==
<syntaxhighlight lang="lua">
-- Display text using dxDrawText
addEventHandler( "onClientRender", root,
function()
dxDrawText( "dxDrawText", 100, 350, 300, 350, tocolor(255,255,0), 1, myFont )
end
)

-- Use 'toggle' command to switch custom font on and off
addCommandHandler( "toggle",
function()
if not myFont then
myFont = dxCreateFont( "segoeui.ttf", 20 ) -- Create custom font
else
destroyElement( myFont ) -- Destroy custom font
myFont = nil
end
end
)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}

Scripting Introduction

2012-04-01T01:23:17Z

Johan van Tiel:

Resources are a key part of MTA. A resource is essentially a folder or zip file that contains a collection of files, plus a meta file that describes to the server how the resource should be loaded and what files it does contain. A resource can be seen as being partly equivalent to a program running in an operating system - it can be started and stopped, and multiple resources can run at once.

Everything that has to do with scripting happens in resources, what a resource does defines if it is a gamemode, a map or anything else. MTA comes with resources that you can optionally use in your gamemodes, such as maplimits to keep playings within a playing area or deathpickups to create weapon pickups.

'''Your first step to begin Lua scripting should be using an Lua editor. This makes scripting much easier. We recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] or [http://luaedit.sourceforge.net/ LuaEdit]. There is also an unofficial [[MTASE|MTA Script Editor]] (in work-in-progress state) that you can test out.'''

==Creating a working script==
We will first learn how to make a basic script that lets the player walk around in the city, step by step.
===Where are all the scripts?===
Let's take a look at the script's file structure. Go to your MTA Server folder, and follow the path below:

/Your MTA Server/mods/deathmatch/resources/

You will see a lot of .zip files, which are the packaged sample scripts shipped with MTA DM. Each file is a "resource", and they will all be unzipped and loaded by the server when it starts. To create your own resource, simply make a folder with your preferred name. We'll use "myserver" for this tutorial.

Now you should be under this directory:

/Your MTA Server/mods/deathmatch/resources/myserver/

===Identifying your resource===
In order to let the server know what's in the resource, a ''meta.xml'' file must be created to list the resource's content. It must be located in the resource's root directory, which is the "myserver" folder in our case. So create a text file and name it "meta.xml", and open it with notepad.

Enter the following codes in the ''meta.xml'' file:
<syntaxhighlight lang="xml">
<meta>
<info author="YourName" type="gamemode" name="My Server" description="My first MTA DM server" />
<script src="script.lua" />
</meta>
</syntaxhighlight>
In the ''<info />'' tag, there's a "type" field which indicates that the resource is a ''gamemode'' instead of a regular include or a ''map'', which will be explained later. A gamemode is what you need to make a stand-alone server.

The ''<script />'' tag indicates the script files contained in the resource, which we will create next.
===Creating a simple script===
Note that in the ''<script />'' tag above, the .lua file is not under another directory. Therefore we'll create the file in the same folder as meta.xml. Now you can copy and paste the following code into script.lua:
<syntaxhighlight lang="lua">
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10
function joinHandler()
spawnPlayer(source, spawnX, spawnY, spawnZ)
fadeCamera(source, true)
setCameraTarget(source, source)
outputChatBox("Welcome to My Server", source)
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)
</syntaxhighlight>
The script will spawn you at the coordinate (x, y, z) specified above, when you join the game. Note that the ''fadeCamera'' function must be used or the screen will be black. Also, in releases after DP2, you need to set the camera target (otherwise all the player will see is blue sky).

The '''source''' variable indicates who triggered the event. Since a player has joined when the code is triggered, you use this variable to look which has joined. So it'll spawn that player instead of everyone or a random person.

If we have a closer look on [[addEventHandler]], you can see 3 things: 'onPlayerJoin', which indicates when it's triggered. getRootElement(), which shows by what/who it can be triggered. (getRootElement() is everything/everyone) And joinHandler, which indicates the function that has to be triggered after the event is triggered. Other details will be explained later in another example, now let's just run the server and try it out!

===Running the script===
To get the server started, simply run the executable under the MTA DM directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the /resource/ directory, and then "ready to accept connections!"

Before you connect to the server, you must run the gamemode. Type "gamemode myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA DM client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.

Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA:DM is drawn and scripted.

==Creating a simple command==
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.

<syntaxhighlight lang="lua">
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- create a vehicle and stuff
end

-- create a command handler
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''

====About command handlers====
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.

If you have already experience in scripting, you will know that you call a function like this:
<syntaxhighlight lang="lua">
functionName(argument1, argument2, argument3, ..)
</syntaxhighlight>
<syntaxhighlight lang="lua">
functionName(thePlayer, commandName, argument3, ..)
</syntaxhighlight>
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.

We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:
<syntaxhighlight lang="lua">
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command
</syntaxhighlight>
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).

''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''

====Writing the function====
In order to fill the function we created, we need to think about what we have to do:
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
* Spawn the vehicle
* Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For [[getElementPosition]], the syntax is:
<syntaxhighlight lang="lua">
float, float, float getElementPosition ( element theElement )
</syntaxhighlight>

The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- get the position and put it in the x,y,z variables
-- (local means, the variables only exist in the current scope, in this case, the function)
local x,y,z = getElementPosition(thePlayer)
end
</syntaxhighlight>

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
end
</syntaxhighlight>

Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end
</syntaxhighlight>

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.

Now we have our complete script:
<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
-- check if the return value was ''false''
if (createdVehicle == false) then
-- if so, output a message to the chatbox, but only to this player.
outputChatBox("Failed to create vehicle.",thePlayer)
end
end
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>

As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].

==What you need to know==
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.
===Clientside and Serverside scripts===
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.

Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:
<syntaxhighlight lang="xml">
<script src="client.lua" type="client" />
</syntaxhighlight>
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].

===More complex resources===
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:

====First example - A utility script====
<syntaxhighlight lang="xml">
/admin_commands
/meta.xml
/commands.lua
/client.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="admin commands" />
<script src="commands.lua" />
<script src="client.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily

This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.

====Second example - A gamemode====
<syntaxhighlight lang="xml">
/counterstrike
/meta.xml
/counterstrike.lua
/buymenu.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike remake" type="gamemode" />
<script src="counterstrike.lua" />
<script src="buymenu.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''counterstrike.lua'' contains similiar to the following features:
** Let players choose their team and spawn them
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)
** Define the game's rules, e.g. when does the round end, what happens when a player dies
** .. and maybe some more
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons

This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.

This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.

====Third example - A Map====
<syntaxhighlight lang="xml">
/cs-airport
/meta.xml
/airport.map
/airport.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
<map src="airport.map" />
<script src="airport.lua" />
</meta>
</syntaxhighlight>

* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:
** Where the players should spawn, with what weapons, what teams there are
** What the targets are
** Weather, World Time, Timelimit
** Provide vehicles
* The ''airport.lua'' might contain map-specific features, that may include:
** Opening some door/make something explode when something specific happens
** Create or move some custom objects, or manipulate objects that are created through the .map file
** .. anything else map-specific you can think of

As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.

The ''airport.map'' file might look similiar to this:
<syntaxhighlight lang="xml">
<map mode="deathmatch" version="1.0">
<terrorists>
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" />
</terrorists>
<counterterrorists>
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" />
</counterterrorists>

<bomb posX="23342.23" posY="" posZ="" />

<vehicle posX="" posY="" posZ="" model="602" />
<vehicle posX="" posY="" posZ="" model="603" />
</map>
</syntaxhighlight>

When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.

===Events===
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].

This example will output a message with the name of the player who died:
<syntaxhighlight lang="lua">
function playerDied(totalAmmo, killer, killerWeapon, bodypart)
outputChatBox(getPlayerName(source).." died!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)
</syntaxhighlight>

Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.

From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.

[[ru:Scripting Introduction]]
[[it:Introduzione allo scripting]]
[[es:Introducción a la Programación]]
[[nl:Scripting_introductie]]

NL/Scripting introductie

2012-04-01T01:14:39Z

Johan van Tiel: Translation to Dutch: Part done till the "Running the script" paragraph

Resources(Hulpmiddelen) zijn een groot belang voor MTA. Een resource is voornamelijk een map of zip bestand dat uit een collectie van bestanden bestaat, plus een meta bestand dat de server beschrijft hoe de resource geladen moet worden en wat voor bestanden het bevat. Een resource is vergelijkbaar met een programma op een operating system - het kan gestart en gestopt worden, en meerdere resources kunnen tegelijkertijd werken

Alles wat met scripten heeft te maken gebeuren in resources, wat een resource doet is het definiëren of het een gamemode is, een map, wat dan ook. MTA komt met resources dat je optioneel kan gebruiken in jouw gamemodes, zoals maplimieten om door te kunnen spelen in een bepaald gebied of pick-ups bij dood om wapen pick-ups te maken.

'''Jou eerste stap met het beginnen van Lua scripting zou het gebruiken van een Lua editor kunnen zijn. Dit maakt het scripten makkelijker. Wij raden [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] of [http://luaedit.sourceforge.net/ LuaEdit] aan. Er is ook een onofficiële [[MTASE|MTA Script Editor]] (nog niet klaar) dat je uit kan proberen.'''

==Het maken van een werkende script==
Eerst gaan we beginnen met het maken van een basis script waarbij spelers door de stad kunnen lopen, stap bij stap.
===Waar zijn alle scripts?===
Laten we een kijkje nemen naar de structuur van de scripts. Ga naar je MTA map en volg deze pad:

/Jouw MTA Server/mods/deathmatch/resources/

Je zal een groot aantal .zip folders zien, dit zijn de verpakte probeersels die meegekomen zijn met MTA 1.0. Elk bestand is een "resource", en ze zullen allemaal uitgepakt worden door de server wanneer het start. Om een eigen resource te maken, Maak simpelweg een map met de gewenste naam. We gebruiken "myserver" als naam bij deze begeleiding.

Nu zou de map op deze locatie staan:

/Jouw MTA Server/mods/deathmatch/resources/myserver/

===Jouw resource identificeren===
Om de server te laten weten wat in de resource zit moet er een ''meta.xml'' bestand aangemaakt worden om inhoud op een lijstje te zetten. Het moet geplaatst worden in het map van de resource, dus de map "myserver". Dus maak een tekstbestand aan, noem het "meta.xml" en open het met Kladblok.

Zet de volgende codes in het ''meta.xml'' bestand:
<syntaxhighlight lang="xml">
<meta>
<info author="JouwNaam" type="gamemode" name="Mijn Server" description="Mijn eerste MTA 1.0 server" />
<script src="script.lua" />
</meta>
</syntaxhighlight>
In de ''<info />'' label, is er een "type" veld dat de resource aangeeft het te identificeren als een ''gamemode'' inplaats van een toevoeging of een ''map'', dit zal later uitgelegd worden. Een gamemode is wat je nodig hebt op een alleen staand server.

De ''<script />'' label geeft de scripts die toebehoren tot de resource, die we zojuist nu gaan maken.
===Een simpele script maken===
Let op dat er een ''<script />'' label er boven zit, de .lua bestand moet niet in een andere map. Dus daarbij maken wij een bestand aan in de zelfde map als de meta.xml. Nu kan je de volgende code kopiëren en plakken naar de script.lua:
<syntaxhighlight lang="lua">
local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10
function joinHandeling()
spawnPlayer(source, spawnX, spawnY, spawnZ)
fadeCamera(source, true)
setCameraTarget(source, source)
outputChatBox("Welkom op mijn server", source)
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandeling)
</syntaxhighlight>
Het script zal je spawnen op de coördinaten (x, y, z) als boven aangegeven, wanneer je in het spel gaat spelen. Let op dat de ''fadeCamera'' functie gebruikt moet worden anders blijft het scherm zwart. Ook moet je de camera doel zetten voor oudere releases na DP2 (anders zullen de spelers alleen maar een zwart scherm zien).

De '''source''' variabel geeft aan wie de event veroorzaakte. Wanneer een speler de code afspeelt, gebruik je deze variabel om te zien wie verbond met de server. Zodat de speler zelf in het spel wordt gezet in plaats van iedereen of een willekeurig iemand.

Als we een kijkje nemen bij [[addEventHandler]], kan je drie dingen zien: 'onPlayerJoin', dit geeft aan wanneer het af moet spelen. getRootElement(), dit geeft aan wie of wat het kan veroorzaken. (getRootElement() is alles/iedereen) En joinHandler, dat aangeeft welke functie afgespeeld moet worden nadat de event is veroorzaakt. Andere details zullen later uitgelegd worden, laten we voor nu snel een kijkje nemen door de server te starten en het uit te proberen!

===Running the script===
To get the server started, simply run the executable under the MTA DM directory. A list of server stats will be shown first; note the port number, which you'll need when joining the game. Then the server loads all the resources under the /resource/ directory, and then "ready to accept connections!"

Before you connect to the server, you must run the gamemode. Type "gamemode myserver" and press Enter. The server will start the gamemode you just created, and will also show any errors and warnings from this point on. Now you can start the MTA DM client, and "Quick Connect" using the IP address of your server and the port number you saw earlier. If all goes well, after a few seconds your character will be walking on the streets of Los Santos.

Next we'll add a command to your script that players can use to spawn a vehicle beside their position. You may skip it and check out more advanced scripting with the [[Map manager|Map Manager]], which continues this tutorial. Another branch from this tutorial is [[Introduction to Scripting GUI]], you may follow it to see how Graphical User Interface in MTA:DM is drawn and scripted.

==Creating a simple command==
Let's go back to the content of the ''script.lua'' file. As mentioned above, we want to provide a command to create a vehicle beside your current position in the game. Firstly we need to create a function we want to call and a command handler that creates the command the player will be able to enter in the console.

<syntaxhighlight lang="lua">
-- create the function the command handler calls, with the arguments: thePlayer, command, vehicleModel
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- create a vehicle and stuff
end

-- create a command handler
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>
''Note: Function names are clickable in code examples on the wiki and linked to the functions' documentation.''

====About command handlers====
The first argument of [[addCommandHandler]] is the name of the command the player will be able to enter, the second argument is the function this will call, in this case ''createVehicleForPlayer''.

If you have already experience in scripting, you will know that you call a function like this:
<syntaxhighlight lang="lua">
functionName(argument1, argument2, argument3, ..)
</syntaxhighlight>
<syntaxhighlight lang="lua">
functionName(thePlayer, commandName, argument3, ..)
</syntaxhighlight>
If we have a closer look on the lower example above, we can see argument1 is thePlayer and argument2 the commandName. thePlayer is simply the one who typed the command, so whatever you call it, the variable will contain the player who activated the command. commandName is simply the command they typed. So if they typed "/greet", this argument will contain "greet". Argument 3 is something extra the player typed, you'll learn it a little bit further in the tutorial. Never forget that the first 2 arguments are standard arguments, but you can name them to anything you want.

We called the [[addCommandHandler]] function this way already and since ''createVehicleForPlayer'' is a function too, it can be called that way as well. But we are using a command handler for that, which calls it in a similiar manner, internally.

For example: Someone types "createvehicle 468" ingame in the console to spawn a Sanchez, the command handler calls the createVehicleForPlayer function, as '''if''' we would have this line of code in the script:
<syntaxhighlight lang="lua">
createVehicleForPlayer(thePlayer,"createvehicle","468") -- thePlayer is the player element of the player who entered the command
</syntaxhighlight>
As we can see, it provides several parameters: the player who called the command, the command he entered and whatever text he had after that, in this case "468" as vehicle id for the Sanchez. The first two parameters are the same with all command handlers, which you can read on the [[addEventHandler]] page. For this fact, you always have to define at least those two parameters to use any after that (for example to process text that was entered after the command, like in our example the vehicle model id).

''Note: You have to add the command handler AFTER you defined the handler function, else it can't find it. The order of execution matters.''

====Writing the function====
In order to fill the function we created, we need to think about what we have to do:
* Get the players position, so we know where to spawn the vehicle (we want it to appear right beside the player)
* Calculate the position we want to spawn the vehicle at (we don't want it to appear in the player)
* Spawn the vehicle
* Check if it has been spawned successfully, or output a message

In order to achieve our goals, we have to use several functions. To find function we need to use, we should visit the [[Scripting Functions|Server Functions List]]. First we need a function to get the players position. Since players are Elements, we first jump to the '''Element functions''' where we find the [[getElementPosition]] function. By clicking on the function name in the list, you get to the function description. There we can see the syntax, what it returns and usually an example. The syntax shows us what arguments we can or have to submit.

For [[getElementPosition]], the syntax is:
<syntaxhighlight lang="lua">
float, float, float getElementPosition ( element theElement )
</syntaxhighlight>

The three ''float'' in front of the function name are the return type. In this case it means the function returns three floating point numbers. (x, y and z) Within the parentheses, you can see what arguments you have to submit. In this case only the element whose position you want to get, which is the player in our example.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
-- get the position and put it in the x,y,z variables
-- (local means, the variables only exist in the current scope, in this case, the function)
local x,y,z = getElementPosition(thePlayer)
end
</syntaxhighlight>

Next we want to ensure that the vehicle won't spawn directly in the player, so we add a few units to the ''x'' variable, which will make it spawn east from the player.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
end
</syntaxhighlight>

Now we need another function, one to spawn a vehicle. We once again search for it on the [[Scripting Functions|Server Functions List]], this time - since we are talking about vehicles - in the '''Vehicle functions''' section, where we will choose [[createVehicle]]. In this function's syntax, we only have one return type (which is more common), a vehicle element that points to the vehicle we just created. Also, we see that some arguments are enclosed within [ ] which means that those are optional.

We already have all arguments we need for [[createVehicle]] in our function: The position we just calculated in the ''x,y,z'' variables and the model id that we provided through the command ("createvehicle 468") and can access in the function as ''vehicleModel'' variable.

<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
-- create the vehicle and store the returned vehicle element in the ''createdVehicle'' variable
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
end
</syntaxhighlight>

Of course this code can be improved in many ways, but at least we want to add a check whether the vehicle was created successfully or not. As we can read on the [[createVehicle]] page under '''Returns''', the function returns ''false'' when it was unable to create the vehicle. Thus, we check the value of the ''createVehicle'' variable.

Now we have our complete script:
<syntaxhighlight lang="lua">
function createVehicleForPlayer(thePlayer, command, vehicleModel)
local x,y,z = getElementPosition(thePlayer) -- get the position of the player
x = x + 5 -- add 5 units to the x position
local createdVehicle = createVehicle(tonumber(vehicleModel),x,y,z)
-- check if the return value was ''false''
if (createdVehicle == false) then
-- if so, output a message to the chatbox, but only to this player.
outputChatBox("Failed to create vehicle.",thePlayer)
end
end
addCommandHandler("createvehicle", createVehicleForPlayer)
</syntaxhighlight>

As you can see, we introduced another function with [[outputChatBox]]. By now, you should be able to explore the function's documentation page yourself. For more advanced scripting, please check out the [[Map manager|Map Manager]].

==What you need to know==
You already read some things about resources, command handlers and finding functions in the documentation in the first paragraph, but there is much more to learn. This section will give you a rather short overview over some of these things, while linking to related pages if possible.
===Clientside and Serverside scripts===
You may have already noticed these or similiar terms (Server/Client) somewhere on this wiki, mostly in conjunction with functions. MTA not only supports scripts that run on the server and provide commands (like the one we wrote above) or other features, but also scripts that run on the MTA client the players use to connect to the server. The reason for this is, that some features MTA provides have to be clientside (like a GUI - Graphical User Interface), others should be because they work better and still others are better off to be serverside or just don't work clientside.

Most scripts you will make (gamemodes, maps) will probably be serverside, like the one we wrote in the first section. If you run into something that can't be solved serverside, you will probably have to make it clientside. For a clientside script for example, you would create a ordinary script file (for example called ''client.lua'') and specify it in the meta.xml, like this:
<syntaxhighlight lang="xml">
<script src="client.lua" type="client" />
</syntaxhighlight>
The ''type'' attribute defaults to 'server', so you only need to specify it for clientside scripts. When you do this, the clientside script will be downloaded to the player's computer once he connects to the server. Read more about [[Client side scripts]].

===More complex resources===
The previous section showed briefly how to add clientside scripts to the resource, but there is also much more possible. As mentioned at the very top of this page, resources can be pretty much everything. Their purpose is defined by what they do. Let's have some theoretical resources, by looking at the files it contains, the ''meta.xml'' and what they might do:

====First example - A utility script====
<syntaxhighlight lang="xml">
/admin_commands
/meta.xml
/commands.lua
/client.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="admin commands" />
<script src="commands.lua" />
<script src="client.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''commands.lua'' provides some admin commands, like banning a player, muting or something else that can be used to admin the server
* The ''client.lua'' provides a GUI to be able to perform the mentioned actions easily

This example might be running all the time (maybe even auto-started when the server starts) as it's useful during the whole gaming experience and also wont interfere with the gameplay, unless an admin decides to take some action of course.

====Second example - A gamemode====
<syntaxhighlight lang="xml">
/counterstrike
/meta.xml
/counterstrike.lua
/buymenu.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike remake" type="gamemode" />
<script src="counterstrike.lua" />
<script src="buymenu.lua" type="client" />
</meta>
</syntaxhighlight>

* The ''counterstrike.lua'' contains similiar to the following features:
** Let players choose their team and spawn them
** Provide them with weapons, targets and instructions (maybe read from a Map, see below)
** Define the game's rules, e.g. when does the round end, what happens when a player dies
** .. and maybe some more
* The ''buymenu.lua'' is a clientside script and creates a menu to buy weapons

This example can be called a gamemode, since it not only intereferes with the gameplay, but actually defines the rules of it. The ''type'' attribute indicates that this example works with the [[Map manager]], yet another resource that was written by the QA Team to manage gamemodes and map loading. It is highly recommended that you base your gamemodes on the techniques it provides.

This also means that the gamemode probably won't run without a map. Gamemodes should always be as generic as possible. An example for a map is stated in the next example.

====Third example - A Map====
<syntaxhighlight lang="xml">
/cs-airport
/meta.xml
/airport.map
/airport.lua
</syntaxhighlight>
<syntaxhighlight lang="xml">
<meta>
<info author="Someguy" description="Counterstrike airport map" type="map" gamemodes="counterstrike" />
<map src="airport.map" />
<script src="airport.lua" />
</meta>
</syntaxhighlight>

* The ''airport.map'' in a XML file that provides information about the map to the gamemode, these may include:
** Where the players should spawn, with what weapons, what teams there are
** What the targets are
** Weather, World Time, Timelimit
** Provide vehicles
* The ''airport.lua'' might contain map-specific features, that may include:
** Opening some door/make something explode when something specific happens
** Create or move some custom objects, or manipulate objects that are created through the .map file
** .. anything else map-specific you can think of

As you can see, the ''type'' attribute changed to 'map', telling the [[Map manager]] that this resource is a map, while the ''gamemodes'' attribute tells it for which gamemodes this map is valid, in this case the gamemode from the above example.
What may come as a surprise is that there is also a script in the Map resource. Of course this is not necessarily needed in a map, but opens a wide range of possibilities for map makers to create their own world within the rules of the gamemode they create it for.

The ''airport.map'' file might look similiar to this:
<syntaxhighlight lang="xml">
<map mode="deathmatch" version="1.0">
<terrorists>
<spawnpoint posX="2332.23" posY="-12232.33" posZ="4.42223" skins="23-40" />
</terrorists>
<counterterrorists>
<spawnpoint posX="2334.23443" posY="-12300.233" posZ="10.2344" skins="40-50" />
</counterterrorists>

<bomb posX="23342.23" posY="" posZ="" />

<vehicle posX="" posY="" posZ="" model="602" />
<vehicle posX="" posY="" posZ="" model="603" />
</map>
</syntaxhighlight>

When a gamemode is started with a map, the map resources is automatically started by the mapmanager and the information it contains can be read by the gamemode resource. When the map changes, the current map resource is stopped and the next map resource is started. For a more in-depth explanation and examples of how map resources are utilized in the main script, please visit the [[Writing Gamemodes]] page.

===Events===
Events are the way MTA tells scripts about things that happen. For example when a player dies, the [[onPlayerWasted]] event is triggered. In order to perform any actions when a player dies, you have to prepare yourself similiar to adding a command handler, as shown in [[#Writing_the_script|the first chapter]].

This example will output a message with the name of the player who died:
<syntaxhighlight lang="lua">
function playerDied(totalAmmo, killer, killerWeapon, bodypart)
outputChatBox(getPlayerName(source).." died!")
end
addEventHandler("onPlayerWasted",getRootElement(),playerDied)
</syntaxhighlight>

Instead of showing what arguments are needed, the documentation page for Events shows what parameters are passed to the handler function, similiar to the way a [[#About_command_handlers|command handler]] does, just that it is different from event to event. Another important point is the ''source'' variable, that exists in handler functions. It doesn't have to be added to the parameter list of the function, but it still exists. It has a different value from event to event, for player events (as in the example above) it is the player element. As another example, you can take a look at the basic spawning player script in the first section to get an idea how ''source'' is used.

==Where to go from here==
You should now be familiar with the most basic aspects of MTA scripting and also a bit with the documentation. The [[Main Page]] provides you with links to more information, Tutorials and References that allow a deeper look into the topics you desire to learn about.

From here we recommend reading the [[debugging]] tutorial. Good debugging skills are an absolute necessity when you are making scripts. We also recommend you to use the [[predefined variables list]] to help you with certain tasks and make scripting easier and faster.

[[ru:Scripting Introduction]]
[[it:Introduzione allo scripting]]
[[es:Introducción a la Programación]]

DxCreateRenderTarget

2012-03-30T18:25:06Z

Johan van Tiel:

{{Client function}}
__NOTOC__
This function creates a render target element, which is a special type of [[texture]] that can be draw on with the dx functions. Successful render target creation is not guaranteed, and may fail due to hardware or memory limitations.

To see if creation is likely to fail, use [[dxGetStatus]]. (When '''VideoMemoryFreeForMTA''' is zero, failure ''is'' guaranteed.)
=====It is highly recommended that [[dxSetTestMode]] is used when writing and testing scripts using dxCreateRenderTarget.=====

==Syntax==
<syntaxhighlight lang="lua">
element dxCreateRenderTarget ( int width, int height [, bool withAlpha = false ] )
</syntaxhighlight>

===Required Arguments===
*'''width :''' The width of the texture in pixels.
*'''height :''' The height of the texture in pixels.
*'''withAlpha:''' The render target will be created with an alpha channel.

===Returns===
Returns a [[texture]] element if successful, ''false'' if the system is unable to create a render target.

'''You should always check to see if this function has returned false.'''

==Example==
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", resourceRoot,
function()
myRenderTarget = dxCreateRenderTarget( 80, 100 ) -- Create a render target texture which is 80 x 100 pixels
end
)

addEventHandler( "onClientRender", root,
function()
if myRenderTarget then
dxSetRenderTarget( myRenderTarget ) -- Start drawing on myRenderTarget
dxDrawText ( "Hello", 10, 20 ) -- Draw a message
dxSetRenderTarget() -- Stop drawing on myRenderTarget

dxDrawImage( 50, 50, 100, 100, myRenderTarget ) -- Now use myRenderTarget as a material and draw it lots of times
dxDrawImage( 150, 350, 150, 100, myRenderTarget )
dxDrawImage( 250, 250, 100, 150, myRenderTarget )
dxDrawImage( 350, 30, 150, 150, myRenderTarget )
end
end
)
</syntaxhighlight>

==See Also==
{{Drawing_functions}}