AddDebugHook: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(Remove obsolete Requirements section)
 
(18 intermediate revisions by 8 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{Server function}}
{{Server client function}}
{{New feature/item|3.0136|1.3|5939|
{{New feature/item|3.0136|1.3|5939|
This function allows tracing of MTA functions and events. It should only be used when debugging scripts as it may degrade script performance.
This function allows tracing of MTA functions and events. It should only be used when debugging scripts as it may degrade script performance.
Debug hooks are not recursive, so functions and events triggered inside the hook callback will not be traced.
}}
}}
==Syntax==
==Syntax==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool addDebugHook( string hookType, function callbackFunction )
bool addDebugHook ( string hookType, function callbackFunction [, table nameList ] )
</syntaxhighlight>
</syntaxhighlight>


Line 15: Line 18:
** preFunction
** preFunction
** postFunction
** postFunction
*'''callbackFunction :''' The function to call
{{New feature/item|3.0158|1.5.5|11856|
* preEventFunction
* postEventFunction
}}
*'''callbackFunction:''' The function to call
** Returning the string "skip" from the callback function will cause the original function/event to be skipped
 
===Optional Arguments===
*'''nameList:''' Table of strings for restricting which functions and events the hook will be triggered on
** addDebugHook and removeDebugHook will only be hooked if they are specified in the name list


===Returns===
===Returns===
Line 22: Line 34:
==Callback parameters==
==Callback parameters==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
pre/postEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, eventArguments )
string preFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
pre/postFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, functionArguments )
      postFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
string preEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
      postEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
</syntaxhighlight>
</syntaxhighlight>
{{New feature/item|3.0158|1.5.5|11856|
<syntaxhighlight lang="lua">
string preEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
      postEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
</syntaxhighlight>
}}


==Example==
==Example==
Line 31: Line 51:
function onPreEvent( sourceResource, eventName, eventSource, eventClient, luaFilename, luaLineNumber, ... )
function onPreEvent( sourceResource, eventName, eventSource, eventClient, luaFilename, luaLineNumber, ... )
     local args = { ... }
     local args = { ... }
     local resname
     local srctype = eventSource and getElementType(eventSource)
     if sourceResource then
     local resname = sourceResource and getResourceName(sourceResource)
        resname = getResourceName(sourceResource)
     local plrname = eventClient and getPlayerName(eventClient)
     else
        resname = "unknown"
    end
     outputDebugString( "preEvent"
     outputDebugString( "preEvent"
         .. " " .. tostring(resname)
         .. " " .. tostring(resname)
         .. " " .. tostring(eventName)
         .. " " .. tostring(eventName)
         .. " source:" .. tostring(eventSource)
         .. " source:" .. tostring(srctype)
         .. " player:" .. tostring(eventClient)
         .. " player:" .. tostring(plrname)
         .. " file:" .. tostring(luaFilename)
         .. " file:" .. tostring(luaFilename)
         .. ":" .. tostring(luaLineNumber)
         .. "(" .. tostring(luaLineNumber) .. ")"
         .. " #args:" .. tostring(#args)
         .. " numArgs:" .. tostring(#args)
         .. " args[1]:" .. tostring(args[1])
         .. " arg1:" .. tostring(args[1])
         )
         )
end
end
addDebugHook( "preEvent", onPreEvent )
addDebugHook( "preEvent", onPreEvent )
</syntaxhighlight>
</syntaxhighlight>
This example will dump info about all called MTA functions:
<syntaxhighlight lang="lua">
function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
    local args = { ... }
    local resname = sourceResource and getResourceName(sourceResource)
    outputDebugString( "preFunction"
        .. " " .. tostring(resname)
        .. " " .. tostring(functionName)
        .. " allowed:" .. tostring(isAllowedByACL)
        .. " file:" .. tostring(luaFilename)
        .. "(" .. tostring(luaLineNumber) .. ")"
        .. " numArgs:" .. tostring(#args)
        .. " arg1:" .. tostring(args[1])
        )
end
addDebugHook( "preFunction", onPreFunction)
</syntaxhighlight>
This example adds a hook which will only be triggered for the named functions
<syntaxhighlight lang="lua">
addDebugHook( "preFunction", onPreFunction, {"setElementPosition","loadstring"} )
</syntaxhighlight>
{{New feature/item|3.0152|1.5.2|7967|
This example shows how to disable addDebugHook
<syntaxhighlight lang="lua">
function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
    return "skip"
end
addDebugHook( "preFunction", onPreFunction, {"addDebugHook"} )
</syntaxhighlight>
}}


==Requirements==
==Changelog==
{{Requirements|1.3.4-9.05939|n/a}}
{{ChangelogHeader}}
{{ChangelogItem|1.3.5-9.06054|Added clientside}}
{{ChangelogItem|1.3.5-9.06142|Added option to restrict to specified functions and events }}
{{ChangelogItem|1.5.2-9.07957|Added option to skip original function/event <br/>Added ability to hook addDebugHook and removeDebugHook }}
{{ChangelogItem|1.5.5-9.11856|Added pre/postEventFunction hooks }}


==See Also==
==See Also==
{{Utility functions}}
{{Utility functions}}

Latest revision as of 17:12, 7 November 2024

This function allows tracing of MTA functions and events. It should only be used when debugging scripts as it may degrade script performance.

Debug hooks are not recursive, so functions and events triggered inside the hook callback will not be traced.

Syntax

bool addDebugHook ( string hookType, function callbackFunction [, table nameList ] )

Required Arguments

  • hookType: The type of hook to add. This can be:
    • preEvent
    • postEvent
    • preFunction
    • postFunction
  • preEventFunction
  • postEventFunction
  • callbackFunction: The function to call
    • Returning the string "skip" from the callback function will cause the original function/event to be skipped

Optional Arguments

  • nameList: Table of strings for restricting which functions and events the hook will be triggered on
    • addDebugHook and removeDebugHook will only be hooked if they are specified in the name list

Returns

Returns true if the hook was successfully added, or false otherwise.

Callback parameters

string preFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
       postFunction( resource sourceResource, string functionName, bool isAllowedByACL, string luaFilename, int luaLineNumber, ...functionArguments )
string preEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )
       postEvent( resource sourceResource, string eventName, element eventSource, element eventClient, string luaFilename, int luaLineNumber, ...eventArguments )

string preEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )
       postEventFunction ( resource eventResource, string eventName, element eventSource, element eventClient, string eventFilename, int eventLineNumber, resource functionResource, string functionFilename, int functionLineNumber, ...eventArgs )

Example

This example will dump info about all triggered events: 

function onPreEvent( sourceResource, eventName, eventSource, eventClient, luaFilename, luaLineNumber, ... )
    local args = { ... }
    local srctype = eventSource and getElementType(eventSource)
    local resname = sourceResource and getResourceName(sourceResource)
    local plrname = eventClient and getPlayerName(eventClient)
    outputDebugString( "preEvent"
        .. " " .. tostring(resname)
        .. " " .. tostring(eventName)
        .. " source:" .. tostring(srctype)
        .. " player:" .. tostring(plrname)
        .. " file:" .. tostring(luaFilename)
        .. "(" .. tostring(luaLineNumber) .. ")"
        .. " numArgs:" .. tostring(#args)
        .. " arg1:" .. tostring(args[1])
        )
end
addDebugHook( "preEvent", onPreEvent )

This example will dump info about all called MTA functions: 

function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
    local args = { ... }
    local resname = sourceResource and getResourceName(sourceResource)
    outputDebugString( "preFunction"
        .. " " .. tostring(resname)
        .. " " .. tostring(functionName)
        .. " allowed:" .. tostring(isAllowedByACL)
        .. " file:" .. tostring(luaFilename)
        .. "(" .. tostring(luaLineNumber) .. ")"
        .. " numArgs:" .. tostring(#args)
        .. " arg1:" .. tostring(args[1])
        )
end
addDebugHook( "preFunction", onPreFunction)

This example adds a hook which will only be triggered for the named functions 

addDebugHook( "preFunction", onPreFunction, {"setElementPosition","loadstring"} )

This example shows how to disable addDebugHook 

function onPreFunction( sourceResource, functionName, isAllowedByACL, luaFilename, luaLineNumber, ... )
    return "skip"
end
addDebugHook( "preFunction", onPreFunction, {"addDebugHook"} )

Changelog

Version Description
1.3.5-9.06054 Added clientside
1.3.5-9.06142 Added option to restrict to specified functions and events
1.5.2-9.07957 Added option to skip original function/event
Added ability to hook addDebugHook and removeDebugHook
1.5.5-9.11856 Added pre/postEventFunction hooks

See Also


Retrieved from "https://wiki.multitheftauto.com/wiki/AddDebugHook?oldid=81184"