Multi Theft Auto: Wiki - User contributions [en]

HU/Resource Web Access

2017-04-18T06:06:59Z

Kevin:

The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.

==Overview==
There are two key parts that make up this system. The first is a standard web server that allows web browsers to request pages and files you have in a resource. The second is a system for allowing web browsers to call functions you have exported from your resource.

==Pages==
===Specifying a file in the meta===
You can specify in your resource's meta file that certain files are accessible through the web server. To do this, you add a line:
<syntaxhighlight lang="xml">
<html src="filename.ext" />
</syntaxhighlight>
You can then access this file from your web browser by visiting: http://host:port/resourcename/filename.ext<br/>
For example, on a locally hosted server using default http port with webmap started: http://127.0.0.1:22005/webmap/map.htm

===Binary files===
Despite the misleading name, files specified using the html node can be of any type. If they are binary files (like images, zip files) then you need to specify this in the meta file, by adding ''raw="true"'' to the ''html'' node. This means that the files are not preprocessed before being sent to the web browser.

For example:
<syntaxhighlight lang="xml">
<html src="image.gif" raw="true" />
</syntaxhighlight>

===Parsed files===
If a file is not specified in the meta file as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP, but uses LUA. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.

For example:
<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
</body>
<html>
</syntaxhighlight>

There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:

<syntaxhighlight lang="html4strict">
<html>
<body>
This resource is called <* = getResourceName(getThisResource()) *>
</body>
<html>
</syntaxhighlight>

Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''url''': This is the URL of the page.
* account '''user''': This is the account of the current user.

It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.

==Calls==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.

To specify an exported http-accessible function, add the following to your meta.xml file:
<syntaxhighlight lang="xml">
<export function='functionName' http='true' />
</syntaxhighlight>

You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most importantly elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.

===Protocol===
{{note_box|You don't need to know this unless you're writing your own HTTP request code. You can just use one of the [[#SDK|SDKs listed below]].}}

Calls are done by requesting ''<nowiki>http://<your IP>:<your port>/<resource_name>/call/<exported_function_name></nowiki>'' using HTTP POST. The body of the request should be a JSON array of the arguments for the function.

The request will return a JSON array of the value(s) returned from the function as the HTTP response.

The server supports HTTP Basic authentication and you can configure access via the ACL and the built-in accounts system.

===Calls from the HTTP web interface===
Using calls is probably easiest from the web interface and can be done almost seamlessly.

First, add this to your meta.xml file:
<syntaxhighlight lang="xml">
<include resource="ajax" />
</syntaxhighlight>

Secondly, add the following to the <head> section of the page you want to call from:
<syntaxhighlight lang="lua">
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>

Finally, you can create a javascript block in your page and call your functions almost as if they were local. The only difference is that the calls are aysnchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.

Here's a simple example.

'''meta.xml'''
<syntaxhighlight lang="xml">
<meta>
<include resource="ajax" />
<script src='code.lua' />
<html src='page.htm' default='true' />
<export function='showChatMessage' http='true' />
</meta>
</syntaxhighlight>

'''code.lua'''
<syntaxhighlight lang="lua">
function showChatMessage ( message )
outputChatBox ( message )
return 5;
end
</syntaxhighlight>

'''page.htm'''
<syntaxhighlight lang="html4strict">
<html>
<head>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
<script type='text/javascript'>
function say() {
var message = document.getElementById('message')
showChatMessage ( message.value,
function ( number ) {
// the function has been called and returned something
message.value = "The function returned " + number;
}
);
}
</script>
</head>
<body>
<input type='text' id='message' /><input type='button' value='say' onclick='say();' />
</body>
</html>
</syntaxhighlight>

You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.

==Securing the web interface==
The [[ACL]] has a number of rights that can affect what files can be accessed.
{{Deprecated feature|3.0139|1.3.1|
* general.http: If disabled, none of the http files can be accessed (except by game clients)
** '''Important Note''': ''If 'general.http' is enabled, http access to all resources (for that ACL) is enabled by default. To disable http access you have to explicitly block access to resources that contain exported http functions.''
** '''Important Note''': ''If 'general.http' is enabled on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported http functions.''
* resource.'''ResourceName''': If disabled, none of the files in the resource can be accessed
* resource.'''ResourceName'''.file.'''FileName''': If disabled, the file named cannot be accessed
* resource.'''ResourceName'''.function.'''FunctionName''': If disabled, the function cannot be called
These work as with other ACL rights - you can disable them for normal users and just enable them for Admin users, or any other group of users you wish.
}}
{{New_feature|3.0139|1.3.1|
* '''resource.ResourceName.http''': If enabled, the resource will be accessible from http://server_ip:22005/ResourceName/
This works as with other ACL rights - You can enable it just for Admin users, or any other group of users you wish.
}}

==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these you could (in theory) write whole gamemodes. In practice this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.

* [[JavaSDK|Java SDK]]
* [[Javascript SDK]]
* [[Perl SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]

==See Also==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[Category:Scripting Concepts]]
[[ru:Resource Web Access]]
[[Category:Tutorials]]

HU/Resources

2017-04-18T06:06:22Z

Kevin:

Resources are a key part of MTA. A resource is essentially a folder or zip file that contains a collection of files - including script files, plus a ''meta'' file that describes how the resource should be loaded. 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. Its worth remember though, that unlike programs on an operating system, there is no multi-tasking between resources.

==Terminology==
* '''Resource''' - A zip file or folder containing a meta.xml file and a number of resource items. These are placed in the ''mods/deathmatch/resources'' folder in the server directory.
* '''Resource item''' - A file contained within a resource, currently this can be a map, script, images etc.

==The Meta File==
''See main article [[Meta.xml]] for details''

The Meta file is the core of each the resource. It describes exactly what files in the resource should be used, and how. The following is an example that covers every option there is, your meta files can have as many or as few of these tags as you require:

<syntaxhighlight lang="xml">
<meta>
<info author="eAi" description="This is a basic CTF script" version="4"/>

<include resource="radarblips"/>
<include resource="markermanagement" />

<script src="ctf.lua" />
<script src="flag.lua" />
<script src="ctf_client.lua" type="client" />

<file src="model.dff" />
<file src="quitbutton.png" />
<file src="killed.png" />

<html src="test.htm" default="true"/>
<html src="logo.png" raw="true" />

<export function="multiply" http="true" />
<export function="getPlayerList" />
<export function="getElementOwner" type="client"/>

<config src="vehicle-list.xml" type="client" />
<config src="markerconfig.xml" type="server" />

<map src="somestuff.map" dimension="99" />
</meta>
</syntaxhighlight>
While a CTF map may have a meta.xml that looks like:
<syntaxhighlight lang="xml">
<meta>
<include resource="ctf" />
<map src="myuberl33tctfmap.map" />

<info author="Tom" instructions="this is uber l33t !!!!!1111111" type="map" />
</meta>
</syntaxhighlight>

Script/type, Config/type and File/type attributes specify if the script/resource should be sent to clients or not, and defaults to "server".

The include tag specifies other resources that should be started before this resoucre is started. In other words, if your resource is dependent on another, you can include it so that the other resource is started first,

Each resource has its own virtual machine (VM). This contains every script in the resource. This means that variables are not shared with other resources. The best way to communictate with other resources is by using the ''export'' tag and exporting a function. This will enable other resources to fire this function using the [[call]] scripting function.

Scripts sent to clients are started as soon as all the scripts have been downloaded.

Scripts are able to read and write to their own resource folder with functions such as [[xmlCreateFile]] and [[fileCreate]]. They can also read and write to other resources, but must have [[Access_Control_List|ACL]] access.

Each resource can only be loaded once, the server will ensure this. If a resource is included more than once, the same instance will be used by each resource that includes it.

==File storage==
Resource files can either be stored in a zip or a directory. This is located in:

server/mods/deathmatch/resources/ (if you've installed your server with the client)

or

mods/deathmatch/resources/ (for dedicated server installations)

Each resource can have a zip file, a directory or both. In the case of both existing, the directory has precedence over the zip file, as such files can be placed in the directory to over-ride the files in the zip file. This allows directories to be used for testing and developing of maps/scripts while zip files used by end-users.

==Other things to note==
*Resource names can't have dots in.
*If the resource does any file saving, the file names used should not be listed in the meta.xml
*Files listed in the meta.xml should be considered read only by your scripts. Do not modify them with xmlSaveFile, FileSave etc.
*When making a zip file of your resource, do not include save files. If your resource uses save files, they must be created by your resource when needed.
*When making a zip file of your resource, only include files that are listed in the meta.xml. Do not include 'example' save files, otherwise bad things will happen.
*We recommend avoiding spaces and exotic characters from resources names.

==Script functions==
The resource system can be manipulated by script. As such, the following Serverside scripting functions are provided:
{{Resource functions}}

The following events are also provided:
{{Resource_events}}

[[it:Introduzione alle Risorse]]
[[pt-br:Recursos]]
[[ru:Resources]]

Talk:HU/Hibakeresés

2017-04-18T06:05:45Z

Kevin: Created page with "A szkriptekben gyakran előfordulnak kisebb nagyobb problémák, amelyeket nem veszünk észre!Ez a leírás segít abban hogy gyorsan megtaláld őket! ==Hibakereső konzol=..."

A szkriptekben gyakran előfordulnak kisebb nagyobb problémák, amelyeket nem veszünk észre!Ez a leírás segít abban hogy gyorsan megtaláld őket!

==Hibakereső konzol==
Az MTA tartalmaz beépített hibakereső konzolt!Hasznos mivel ha elgépelünk valamit és nem vesszük észre ő segítségünkre lehet.Ahhoz hogy tudjuk aktiválni ezt a jogusultságot Adminisztrátor rangot kell viselnünk{ACL}.Ha ez rendben van akkor a "debugscript x" parancsal tudjuk változtatni a visszajelzési szintet!

----
Lehetőségek:
* '''1:''' Csak a '''Hibákat''' jelzi
* '''2:''' A '''Hibákat''' és a '''Figyelmeztetéseket''' is jelzi
* '''3:''' A '''Hibákat''' és a '''Figyelmeztetéseket''' is jelzi illetve az '''Információkat''' amelyeket elrejtünk a szkriptekben!
Ha begépeljük a "debugscript 3" parancsot akkor a fent leírt paramétereket fogja megmutatni.Ez a legcélszerűbb funkció, sokkal egyszerűbb vele a fejlesztés

===Példa===
Ebben a kódban elrejtettünk két darab hibát:
<syntaxhighlight lang="lua">
function Koszones(message, player)
if (getPlayerName(player) == "Józsika")
outputChatbox("Szia Józsika")
end
end
addEventHandler("onChatMessage", root, Koszones)
</syntaxhighlight>
Ha ezt a kódot lefuttatjuk akkor ezt a hibaüzenetet fogjuk kapni:
:{{Debug info|Loading script failed: myResource\script.lua:2: 'then' expected near ´outputChatbox'}}[Ezt nem fordítom le]
Itt láthatjuk a hiba pozícióját!(heyle,hibás sor, hiba)
<syntaxhighlight lang="lua">
function Koszones(message, player)
if (getPlayerName(player) == "Józsika") then
outputChatbox("Szia Józsika")
end
end
addEventHandler("onChatMessage", root, Koszones)
</syntaxhighlight>
Ezzel nincs semmi gond, működik annak rendje és módja szerint DE ha a játékos neve nem "Józsika" akkor ezt láthatjuk:
:{{Debug error|myResource\script.lua:2: attempt to call global 'outputChatbox' (a nil value)}}
This error means that the function '''outputChatbox''' is a nil value, that is - it doesn't exist! This is because the function is actually called [[outputChatBox]], not [[outputChatbox]] - take care of that capital B.:
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Józsika") then
outputChatBox("Szia Józsika")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>

Ez csak egy kis része a rendszernek.Nagyon sokoldalú illetve érdekes visszajelzéseket tud adni vissza nekünk.

==Szerver & Cliens hibakeresési napló=
====Szerver====
Menj be a: ''(MTA mappa)>server>mods>deathmatch'' mappába

Van itt két majdnem azonos fájl.

* A local.conf a beállításokat tartalmazza a „host játék” menüpont beállításait a főmenübe. Ez egy gyors módja a szerver indításának. Ha a host lecsatlakozik akkor a szerver is kikapcsol!
*A mtaserver.conf akkor használjuk, amikor „MTA SERVER.EXE” fájlal indítjuk a szervert!(MTA mappája)> server. Ez a saját szerver konzol, szóval ha a host lecsatlakozik akkor nem kapcsol le. Ez akkor lehet hasznos, ha érdekel a szerver hosting hosszabb ideig.

Itt be lehet állítani a logok mentési helyét!

<syntaxhighlight lang="xml">
<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>


<scriptdebugloglevel>0</scriptdebugloglevel></syntaxhighlight>

Te biztos akarsz lenni hogy van egy file a megadott néven. Meg tudod határozni, hogy milyen szintű hibák kerüljene knaplózásra . Ha ez 0 akkor semmi nem lesz rögzítve. A szintek magyarázata a cikk tetején található. Ha a naplózási szint megváltozott 3-ra, akkor ebben az esetben minden „” „szerveroldalon” „” lévő szkripthibákat elnaplóz.
(MTA mappa)>server>mods>deathmatch>logs>scripts.log

====Kliens====
Menj a: ''(MTA mappa)>server>clientscript.log''

Ez a file az összes '''kliensoldali''' szkript hibákat naplózza. Ő alapértelmezés szerint fent van, nincs szükség telepítésre!

==Hibakeresési stratégiák==
Számos stratégia létezik, amelyek támogatják a hibakeresést. Legtöbbjük közé tartozik a kimenő Hibaüzenetek, a különböző információktól függően helyezkednek el.

===Hasznos funkciók===
Vannak olyan funkciók, amelyek jól jöhetnek a hibakereséshez.
* [[outputDebugString]] vagy [[outputChatBox]] ([[outputDebugString]] a műszaki kimenet)
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] Hasznos, ha az érték nem szám vagy string.

* [[getElementType]] ellenőrizni, hogy milyen típusú az MTA elem.
* [[isElement]] ellenőrizni, hogy a MTA elem létezik.

===Add debugmessages to check ''if'', ''when'' or ''how often'' a section of code is executed===
A typical example would be verify whether an ''if''-section is executed or not. To do that, just add any message you will recognize later within the ''if''-section.
<syntaxhighlight lang="lua">
if (variable1 == variable2) then
outputDebugString("variable1 is the same as variable2!")
-- do anything
end
</syntaxhighlight>

Another application would be to check when variable values are modified. First search for all occurences of the variable being edited and add a message just beside it.

===Add debugmessages to check the ''value'' of a variable===
Let's say you want to create a marker, but it doesn't appear at the position you expect it to be. The first thing you might want to do is check if the [[createMarker]] function is executed. But while doing this, you can also check the values being used in the [[createMarker]] function in one run.
<syntaxhighlight lang="lua">
outputChatBox("posX is: "..x.." posY is: "..y.." posZ is: "..z)
createMarker(x,y,z)
</syntaxhighlight>
This would output all three variables that are used as coordinates for the marker. Assuming you read those from a map file, you can now compare the debug output to the desired values. The [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] will ensure that the values of the variables can be concatenated (put together) as a string, even if it's a boolean value.

==Example==
Imagine you created a [[Colshape|collision shape]] somewhere and you want an action to perform after the player stays for ten seconds inside it, you would do this:
<syntaxhighlight lang="lua">
function colShapeHit(player)
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave", root, colShapeLeave)
</syntaxhighlight>
When a player enters the colshape, debugscript outputs the following message:
:{{Debug error|..[path]: attempt to index global 'colshapeTimer' (a nil value)}}
This means you tried to index a table that does not exist (because the table is a nil value, it doesn't exist). In the example above, this is done when storing the timer id in the table. We need to add a check if the table exists and if it does not exist we should create it.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",root,colShapeLeave)
</syntaxhighlight>

Now we will still receive a warning when a player enters the colshape, waits for the message and leaves it again:

:{{Debug warning|[..]: Bad argument @ 'killTimer' Line: ..}}

Except for that (we will talk about that later) everything seems to work fine. A player enters the colshape, the timer is started, if he stays the message occurs, if he leaves the timer is killed.

===A more inconspicuous error===
But for some reason the message gets outputted twice when you stay in the colcircle while in a vehicle. Since it would appear some code is executed twice, we add debug messages to check this.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message
outputDebugString("colShapeHit")
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message
outputDebugString("colShapeLeave")
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now we notice that both handler functions get executed twice when we are in a vehicle, but only once when we are on-foot. It would appear the vehicle triggers the colshape as well. To confirm this theory, we ensure that the ''player'' variable actually holds a reference to a player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

The debug messages tell us that one of the ''player'' variables is a player and that the other one is a vehicle element. Since we only want to react when a player enters the colshape, we add an ''if'' that will end the execution of the function if it's '''not''' an player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now the script should work as desired, but it will still output the warning mentioned above. This happens because the timer we try to kill when a player leaves the colshape will not exist anymore when it has reached the 10 seconds (and therefore executed after the 10th second has completed). There are different ways to get rid of that warning (since you know that the timer might not exist anymore and you only want to kill it if it exists). One way would be to check if the timer referenced in the table really exists. To do this, we need to use [[isTimer]], which we will use when we kill the timer:
<syntaxhighlight lang="lua">
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
</syntaxhighlight>

So the complete working code would be:
<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

==Debugging Performance Issues==

If your server is using up more resources than it should or you just want to make sure your scripts are efficient, you can find the source of the issue by using a great tool that comes with the default resource package called [[Resource:Performancebrowser|performancebrowser]]. You can start it with ''''start performancebrowser''''. If it doesn't exist then you can get the latest resources from the [https://github.com/multitheftauto/mtasa-resources GitHub repository]. This tool provides an incredible amount of information for performance debugging. Memory leaks, element leaks and CPU intensive scripts are all easily findable via performancebrowser. If you use the ''''d'''' option in Lua timing you can see which functions are using up the CPU.

To access performancebrowser you will need to go to your web browser and enter the address: http://serverIPHere:serverHTTPPortHere/performancebrowser/ Note that the / at the end is required. So for example: http://127.0.0.1:22005/performancebrowser/ You will then need to login with an in-game admin account or any account that has access to ''''resource.performancebrowser.http'''' and ''''resource.ajax.http''''. Most of the information you will need are in the categories Lua timing and Lua memory, look for values that are much higher than other values.

===Examples of scripts that could cause performance problems===

Adding data to a table but never removing it. This would take months/years before it causes a problem though.
<syntaxhighlight lang="lua">
local someData = {}

function storeData()
someData[source] = true
-- There is no handling for when a player quits, this is considered a memory leak
-- Using the Lua timing tab you can detect the RAM usage of each resource.
end
addEventHandler("onPlayerJoin", root, storeData)
</syntaxhighlight>

Element leaking is possible if you use temporary colshapes for whatever reason and may not destroy them. This would cause bandwidth, CPU and memory performance issues over time.
<syntaxhighlight lang="lua">
function useTemporaryCol()
local col = createColCircle(some code here)
if (normally this should happen) then
destroyElement(col)
end
-- But sometimes it didn't so the script ended but the collision area remained and over time
-- you may end up with hundreds to thousands of pointless collision areas.
-- The Lua timing tab allows you to see the amount of elements each script has created.
end
</syntaxhighlight>

High CPU usage resulting in the server FPS dropping so much that the server is unplayable. In under 24 hours this can create havoc on a very busy server. The amount of "refs" in the Lua timing detect this type of build up, surprisingly the Lua timing tab didn't help in this case but Lua memory did.
<syntaxhighlight lang="lua">
addEventHandler("onPlayerJoin", root, function()
-- Code for joiner
addEventHandler("onPlayerQuit", root, function()
-- Code for when they have quit
-- See the problem? It's bound to root which the event handler is being added again and again and again
end)
end)
</syntaxhighlight>

A function uses up a lot of your CPU because whatever it does takes a long time. This is just some function that takes a long time to complete. Without performancebrowser you'd have no idea its the cause but with performancebrowser you can see that a resource is using lots of CPU in the Lua timing tab. If you then enter: ''''d'''' into the options edit box it will even tell you what file name and first line of the function that is using up so much CPU.
<syntaxhighlight lang="lua">
function someDodgyCode()
for i=1, 100000 do
-- some code
end
end
</syntaxhighlight>

==Fordító==

'''Fordította: Kevin'''

[[Category:Scripting Concepts]]
[[en:Debugging]]
[[it:Guida al Debug]]
[[ru:Debugging]]
[[zh-cn:脚本调试教程]]
[[hu:Hibakeresés]]
[[Category:Tutorials]]

2017-04-15T13:59:47Z

Kevin: Kevin moved page Debugging to Hibakeresés

When scripting you will often come across problems that are not immediately apparent. This page tries to point out some basic strategies to locate the error.

==Debug console==
MTA features a built-in debug console that shows debug messages output from MTA functions or from scripts. Keeping it mind that you should have administrator access (unless you modify the ACL to change this), you can open the debug console by typing ''debugscript *x*'' in the console, where ''x'' is the debug level:
* '''1:''' only errors
* '''2:''' errors and warnings
* '''3:''' errors, warnings and info messages
By typing ''debugscript 3'' all messages are visible. Level 3 and level 2 are recommended for most occasions. You should have ''debugscript'' enabled whenever you are testing your scripts as it will help you easily detect and solve typos and other issues.

===Example===
This example code has two errors:
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor")
outputChatbox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>
When the script this piece of code is in is tried to be loaded, debugscript will output something similiar to this:
:{{Debug info|Loading script failed: myResource\script.lua:2: 'then' expected near ´outputChatbox'}}
This means the script could not be parsed because there was a syntax error. It shows the script path relative to the resource directory so you can identify to script where the error originated from. After the filename it shows a colon and a number, this number presents the line number - this is so you can find out where in your script the error is - it is very helpful for large scripts. After that is the error message, which varies depending on the error made. Looking at the error message, we can easily determine that the error originated from the resource '''myResource''' and line two of the script file '''script.lua'''. The error message is very clear, we forgot the "then"! We can easily fix that!
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor") then
outputChatbox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>
Now the script will load fine and won't output any errors until a player with the name 'Fedor' says something in the chat. At that moment, the debug console will output:
:{{Debug error|myResource\script.lua:2: attempt to call global 'outputChatbox' (a nil value)}}
This error means that the function '''outputChatbox''' is a nil value, that is - it doesn't exist! This is because the function is actually called [[outputChatBox]], not [[outputChatbox]] - take care of that capital B.:
<syntaxhighlight lang="lua">
function SayHello(message, player)
if (getPlayerName(player) == "Fedor") then
outputChatBox("Hello Fedor")
end
end
addEventHandler("onChatMessage", root, SayHello)
</syntaxhighlight>

Of course, this is just an example and I've only skimmed the surface of error messages. There are plenty of other messages and scenarios, but you should get the general idea.

==Server & client debug logging==
====Server====
Navigate to: ''(MTA root folder)>server>mods>deathmatch''

There are two nearly identical files:

*The local.conf is the settings for the "host game" menu item in the main menu of MTA. This is a quick and easy way of starting a temporary server from inside the client. When the client is turned off the server will also turn off.

*The mtaserver.conf is used when "MTA Server.exe" is executed from (MTA root folder)>server. This runs the server in its own console window which does not need the client to exist or to be run. This is can be useful if you're interested in hosting servers for a longer time period or if you want to experiment with a real world console.

Depending on which way you host, you will want to edit those files. The settings in question are:

<syntaxhighlight lang="xml">
<scriptdebuglogfile>logs/scripts.log</scriptdebuglogfile>


<scriptdebugloglevel>0</scriptdebugloglevel></syntaxhighlight>

You want to make sure you have a log name specified. Also you want to specify what level of errors will be logged. If it is 0 nothing will be logged. The levels were explained at the top of this article. If the logging level was changed to 3, then in this case all '''serverside''' script errors log to (MTA root folder)>server>mods>deathmatch>logs>scripts.log

====Client====
Navigate to: ''(MTA root folder)>server>clientscript.log''

This file logs all '''clientside''' script errors. This is set to log by default, no setup required.

==Debug strategies==
There are several strategies that support finding errors, apart from going through the code. Most of them include outputting debug messages, with have different information depending on the situtation.

===Useful functions===
There are some functions that may come in handy for debugging.
* [[outputDebugString]] or [[outputChatBox]] for outputting any information (use outputDebugString for technical output)
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] on a variable to turn the value into a string. Useful if the value is not a number or string.
* [[getElementType]] to check the type of the MTA element.
* [[isElement]] to check if the MTA element exists.

===Add debugmessages to check ''if'', ''when'' or ''how often'' a section of code is executed===
A typical example would be verify whether an ''if''-section is executed or not. To do that, just add any message you will recognize later within the ''if''-section.
<syntaxhighlight lang="lua">
if (variable1 == variable2) then
outputDebugString("variable1 is the same as variable2!")
-- do anything
end
</syntaxhighlight>

Another application would be to check when variable values are modified. First search for all occurences of the variable being edited and add a message just beside it.

===Add debugmessages to check the ''value'' of a variable===
Let's say you want to create a marker, but it doesn't appear at the position you expect it to be. The first thing you might want to do is check if the [[createMarker]] function is executed. But while doing this, you can also check the values being used in the [[createMarker]] function in one run.
<syntaxhighlight lang="lua">
outputChatBox("posX is: "..x.." posY is: "..y.." posZ is: "..z)
createMarker(x,y,z)
</syntaxhighlight>
This would output all three variables that are used as coordinates for the marker. Assuming you read those from a map file, you can now compare the debug output to the desired values. The [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] will ensure that the values of the variables can be concatenated (put together) as a string, even if it's a boolean value.

==Example==
Imagine you created a [[Colshape|collision shape]] somewhere and you want an action to perform after the player stays for ten seconds inside it, you would do this:
<syntaxhighlight lang="lua">
function colShapeHit(player)
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave", root, colShapeLeave)
</syntaxhighlight>
When a player enters the colshape, debugscript outputs the following message:
:{{Debug error|..[path]: attempt to index global 'colshapeTimer' (a nil value)}}
This means you tried to index a table that does not exist (because the table is a nil value, it doesn't exist). In the example above, this is done when storing the timer id in the table. We need to add a check if the table exists and if it does not exist we should create it.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit", root, colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",root,colShapeLeave)
</syntaxhighlight>

Now we will still receive a warning when a player enters the colshape, waits for the message and leaves it again:

:{{Debug warning|[..]: Bad argument @ 'killTimer' Line: ..}}

Except for that (we will talk about that later) everything seems to work fine. A player enters the colshape, the timer is started, if he stays the message occurs, if he leaves the timer is killed.

===A more inconspicuous error===
But for some reason the message gets outputted twice when you stay in the colcircle while in a vehicle. Since it would appear some code is executed twice, we add debug messages to check this.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message
outputDebugString("colShapeHit")
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message
outputDebugString("colShapeLeave")
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now we notice that both handler functions get executed twice when we are in a vehicle, but only once when we are on-foot. It would appear the vehicle triggers the colshape as well. To confirm this theory, we ensure that the ''player'' variable actually holds a reference to a player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

The debug messages tell us that one of the ''player'' variables is a player and that the other one is a vehicle element. Since we only want to react when a player enters the colshape, we add an ''if'' that will end the execution of the function if it's '''not''' an player element.

<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

Now the script should work as desired, but it will still output the warning mentioned above. This happens because the timer we try to kill when a player leaves the colshape will not exist anymore when it has reached the 10 seconds (and therefore executed after the 10th second has completed). There are different ways to get rid of that warning (since you know that the timer might not exist anymore and you only want to kill it if it exists). One way would be to check if the timer referenced in the table really exists. To do this, we need to use [[isTimer]], which we will use when we kill the timer:
<syntaxhighlight lang="lua">
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
</syntaxhighlight>

So the complete working code would be:
<syntaxhighlight lang="lua">
function colShapeHit(player)
if (colshapeTimer == nil) then
colshapeTimer = {}
end
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeHit "..getElementType(player))
-- set a timer to output a message (could as well execute another function)
-- store the timer id in a table, using the player as index
colshapeTimer[player] = setTimer(outputChatBox,10000,1,"The player stayed 10 seconds in the colshape!")
end
addEventHandler("onColShapeHit",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- add a check for the element type
if (getElementType(player) ~= "player") then return end
-- add a debug message, with the element type
outputDebugString("colShapeLeave "..getElementType(player))
-- kill the timer when the player leaves the colshape
if (isTimer(colshapeTimer[player])) then
killTimer(colshapeTimer[player])
end
end
addEventHandler("onColShapeLeave",getRootElement(),colShapeLeave)
</syntaxhighlight>

==Debugging Performance Issues==

If your server is using up more resources than it should or you just want to make sure your scripts are efficient, you can find the source of the issue by using a great tool that comes with the default resource package called [[Resource:Performancebrowser|performancebrowser]]. You can start it with ''''start performancebrowser''''. If it doesn't exist then you can get the latest resources from the [https://github.com/multitheftauto/mtasa-resources GitHub repository]. This tool provides an incredible amount of information for performance debugging. Memory leaks, element leaks and CPU intensive scripts are all easily findable via performancebrowser. If you use the ''''d'''' option in Lua timing you can see which functions are using up the CPU.

To access performancebrowser you will need to go to your web browser and enter the address: http://serverIPHere:serverHTTPPortHere/performancebrowser/ Note that the / at the end is required. So for example: http://127.0.0.1:22005/performancebrowser/ You will then need to login with an in-game admin account or any account that has access to ''''resource.performancebrowser.http'''' and ''''resource.ajax.http''''. Most of the information you will need are in the categories Lua timing and Lua memory, look for values that are much higher than other values.

===Examples of scripts that could cause performance problems===

Adding data to a table but never removing it. This would take months/years before it causes a problem though.
<syntaxhighlight lang="lua">
local someData = {}

function storeData()
someData[source] = true
-- There is no handling for when a player quits, this is considered a memory leak
-- Using the Lua timing tab you can detect the RAM usage of each resource.
end
addEventHandler("onPlayerJoin", root, storeData)
</syntaxhighlight>

Element leaking is possible if you use temporary colshapes for whatever reason and may not destroy them. This would cause bandwidth, CPU and memory performance issues over time.
<syntaxhighlight lang="lua">
function useTemporaryCol()
local col = createColCircle(some code here)
if (normally this should happen) then
destroyElement(col)
end
-- But sometimes it didn't so the script ended but the collision area remained and over time
-- you may end up with hundreds to thousands of pointless collision areas.
-- The Lua timing tab allows you to see the amount of elements each script has created.
end
</syntaxhighlight>

High CPU usage resulting in the server FPS dropping so much that the server is unplayable. In under 24 hours this can create havoc on a very busy server. The amount of "refs" in the Lua timing detect this type of build up, surprisingly the Lua timing tab didn't help in this case but Lua memory did.
<syntaxhighlight lang="lua">
addEventHandler("onPlayerJoin", root, function()
-- Code for joiner
addEventHandler("onPlayerQuit", root, function()
-- Code for when they have quit
-- See the problem? It's bound to root which the event handler is being added again and again and again
end)
end)
</syntaxhighlight>

A function uses up a lot of your CPU because whatever it does takes a long time. This is just some function that takes a long time to complete. Without performancebrowser you'd have no idea its the cause but with performancebrowser you can see that a resource is using lots of CPU in the Lua timing tab. If you then enter: ''''d'''' into the options edit box it will even tell you what file name and first line of the function that is using up so much CPU.
<syntaxhighlight lang="lua">
function someDodgyCode()
for i=1, 100000 do
-- some code
end
end
</syntaxhighlight>

[[it:Guida al Debug]]
[[Category:Scripting Concepts]]
[[ru:Debugging]]
[[zh-cn:脚本调试教程]]
[[Category:Tutorials]]