Multi Theft Auto: Wiki - User contributions [en]

RU/Debugging

2009-08-24T17:33:58Z

Hawk82:

При написании скриптов вы обязательно столкнетесь с проблемами, которые не сможете решить немедленно. Цель этой страницы - показать вам основные способыы нахождения ошибок.

==Консоль отладки==
MTA включает консоль, которая показывает отладочные сообщения, выводимые функциями MTA и скриптами. Вы можете открыть ее введя ''debugscript x'' в консоли, где ''x'' уровень отладки:
* '''1:''' только ошибки
* '''2:''' ошибки и предупреждения
* '''3:''' ошибки, предупреждения и информационные сообщения
Так, введя ''debugscript 3'', вы будете видеть все сообщения, этот или 2 уровень рекомендуется в большинстве случаев. Рекомендуем держать debugscript включенным всё время, пока вы тестируете свой скрипт, это поможет вам обнаружить мелкие ошибки и исправить их.

===Пример===
Этот участок кода содержит две ошибки:
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor")
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
При попытке запуска скрипта, содержащего этот участо кода, debugscript выведет что-то похожее на:
{{Debug info|Loading script failed: C:\<server path>\mods\deathmatch\resources\myResource\script.lua:15: 'then' expected near ´outputChatbox'}}
Это означает, что скрипт не может быть обработан из-за синтаксической ошибки. Показывается путь к скрипту, поэтому вы можете увидеть, какому ресурсу он принадлежит, ('myResource' в данном случае) и, конечно же, имя скрипта. После имени файла показан номер строки и информация об ошибке. Теперь проблема легко решается, мы просто забыли написать ключевое слово 'then':
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor") then
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
Теперь скрипт загрузится нормально и не будет выводить ошибок пока не выполнится для игрока с ником 'Fedor'. Тогда debugscript выведет:
{{Debug error|C:\<server path>\mods\deathmatch\resources\d\script.lua:15: attempt to call global 'outputChatbox' (a nil value)}}
Это значит, вызванная вами функция не существует, оно и понятно, ведь правильное название этой функции ''outputChatBox'' (с заглавной буквы ''B''):
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor") then
outputChatBox("Hello Fedor")
end
</syntaxhighlight>

Конечно, это просто пример, есть множество других сообщений и сценариев.

==Debug logging==
Можно также включить режим дебаггера, отредактировав ''coreconfig.xml'' в папке GTA\MTA. Найдите в нем следующий тэг:
<syntaxhighlight lang="xml"><debugfile/></syntaxhighlight>

И впишите туда адрес будущего лог-файла (путь указывайте, начиная с папки GTA):
<syntaxhighlight lang="xml"><debugfile>MTA\debugscript.log</debugfile></syntaxhighlight>

И теперь все сообщения дебаггера будут записываться в этот файл. Если хотите выключить ведение лога, оставьте содержимое тэга пустым:
<syntaxhighlight lang="xml"><debugfile/></syntaxhighlight>

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

===Useful functions===
First of all some functions that may come in handy for debugging.
* [[outputDebugString]] or [[outputChatBox]] for outputting any information
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] on a variable to turn it into a string, for example when it contains a boolean value
* [[getElementType]] to check an MTA Element for its type

===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("entered if")
-- 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(tostring(x).." "..tostring(y).." "..tostring(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 variables' value can be put together as a string, even if it's a boolean value for example.

==Example==
Imagine you created a colshape (collision shape) somewhere and you want a player to stay 10 seconds in it, then perform some action.
<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",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),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. 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 not 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",getRootElement(),colShapeHit)

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

Now we still get 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 check the ''player'' variable that '''should''' contain 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, the other one 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 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 reached the 10 seconds and is executed. 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 is there). One way would be to check if the timer referenced in the table really exists. To do this, we need a little help function:
<syntaxhighlight lang="lua">
function isTimer(timer)
local timers = getTimers()
for k,v in ipairs(timers) do
if (v == timer) then
return true
end
end
return false
end
</syntaxhighlight>
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)

function isTimer(timer)
local timers = getTimers()
for k,v in ipairs(timers) do
if (v == timer) then
return true
end
end
return false
end
</syntaxhighlight>

[[Category:Scripting Concepts]]
[[en:Debugging]]
[[it:Guida al Debug]]

RU/Debugging

2009-08-24T17:33:20Z

Hawk82:

При написании скриптов вы обязательно столкнетесь с проблемами, которые не сможете решить немедленно. Цель этой страницы - показать вам основные способыы нахождения ошибок.

==Консоль отладки==
MTA включает консоль, которая показывает отладочные сообщения, выводимые функциями MTA и скриптами. Вы можете открыть ее введя ''debugscript x'' в консоли, где ''x'' уровень отладки:
* '''1:''' только ошибки
* '''2:''' ошибки и предупреждения
* '''3:''' ошибки, предупреждения и информационные сообщения
Так, введя ''debugscript 3'', вы будете видеть все сообщения, этот или 2 уровень рекомендуется в большинстве случаев. Рекомендуем держать debugscript включенным всё время, пока вы тестируете свой скрипт, это поможет вам обнаружить мелкие ошибки и исправить их.

===Пример===
Этот участок кода содержит две ошибки:
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor")
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
При попытке запуска скрипта, содержащего этот участо кода, debugscript выведет что-то похожее на:
{{Debug info|Loading script failed: C:\<server path>\mods\deathmatch\resources\myResource\script.lua:15: 'then' expected near ´outputChatbox'}}
Это означает, что скрипт не может быть обработан из-за синтаксической ошибки. Показывается путь к скрипту, поэтому вы можете увидеть, какому ресурсу он принадлежит, ('myResource' в данном случае) и, конечно же, имя скрипта. После имени файла показан номер строки и информация об ошибке. Теперь проблема легко решается, мы просто забыли написать ключевое слово 'then':
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor") then
outputChatbox("Hello Fedor")
end
</syntaxhighlight>
Теперь скрипт загрузится нормально и не будет выводить ошибок пока не выполнится для игрока с ником 'Fedor'. Тогда debugscript выведет:
{{Debug error|C:\<server path>\mods\deathmatch\resources\d\script.lua:15: attempt to call global 'outputChatbox' (a nil value)}}
Это значит, вызванная вами функция не существует, оно и понятно, ведь правильное название этой функции ''outputChatBox'' (с заглавной буквы ''B''):
<syntaxhighlight lang="lua">
if (getClientName(player) == "Fedor") then
outputChatBox("Hello Fedor")
end
</syntaxhighlight>

Конечно, это просто пример, есть множество других сообщений и сценариев.

==Debug logging==
{{translate}}
Можно также включить режим дебаггера, отредактировав ''coreconfig.xml'' в папке GTA\MTA. Найдите в нем следующий тэг:
<syntaxhighlight lang="xml"><debugfile/></syntaxhighlight>

И впишите туда адрес будущего лог-файла (путь указывайте, начиная с папки GTA):
<syntaxhighlight lang="xml"><debugfile>MTA\debugscript.log</debugfile></syntaxhighlight>

И теперь все сообщения дебаггера будут записываться в этот файл. Если хотите выключить ведение лога, оставьте содержимое тэга пустым:
<syntaxhighlight lang="xml"><debugfile/></syntaxhighlight>

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

===Useful functions===
First of all some functions that may come in handy for debugging.
* [[outputDebugString]] or [[outputChatBox]] for outputting any information
* [http://www.lua.org/manual/5.1/manual.html#pdf-tostring tostring()] on a variable to turn it into a string, for example when it contains a boolean value
* [[getElementType]] to check an MTA Element for its type

===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("entered if")
-- 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(tostring(x).." "..tostring(y).." "..tostring(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 variables' value can be put together as a string, even if it's a boolean value for example.

==Example==
Imagine you created a colshape (collision shape) somewhere and you want a player to stay 10 seconds in it, then perform some action.
<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",getRootElement(),colShapeHit)

function colShapeLeave(player)
-- kill the timer when the player leaves the colshape
killTimer(colshapeTimer[player])
end
addEventHandler("onColShapeLeave",getRootElement(),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. 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 not 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",getRootElement(),colShapeHit)

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

Now we still get 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 check the ''player'' variable that '''should''' contain 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, the other one 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 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 reached the 10 seconds and is executed. 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 is there). One way would be to check if the timer referenced in the table really exists. To do this, we need a little help function:
<syntaxhighlight lang="lua">
function isTimer(timer)
local timers = getTimers()
for k,v in ipairs(timers) do
if (v == timer) then
return true
end
end
return false
end
</syntaxhighlight>
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)

function isTimer(timer)
local timers = getTimers()
for k,v in ipairs(timers) do
if (v == timer) then
return true
end
end
return false
end
</syntaxhighlight>

[[Category:Scripting Concepts]]
[[en:Debugging]]
[[it:Guida al Debug]]