debug
Last updated
Was this helpful?
Last updated
Was this helpful?
This library provides a few basic functions for debugging code in BrickVerse. Unlike the debug library found in Lua natively, this version has been heavily sandboxed. BrickVerse does, however, have debugging functionality similar to Lua’s native debugging functionality (see the DebuggerManager class).
debug.traceback ( message, level = 1 )
Returns a traceback of the current function call stack as a string. In other words, a description of the functions that have been called up to this point. The level parameter specifies what level of the call stack to consider, with 1 being the call of debug.traceback itself, 2 being the call of the function calling debug.traceback (if there is one) and so on.
During debugging, debug.traceback answers the question “how did my code get here?” much like an error stack trace, but without stopping the execution of the script. See the example below with several function calls: c() calls b(), b() calls a(), and a() calls debug.traceback.
The above code would produce an output similar to (but not guaranteed to be exactly like) the following:
The format of the returned traceback is not defined and may change at any time; use only for debug diagnostics and error analytics. It’s recommended that you never parse the return value of this function for specific information, such as script names or line numbers.
debug.traceback ( thread, message, level = 1 )
‘’
debug.info ( thread, level, options )
Allows programmatic inspection of the call stack.
thread (thread) - A thread as returned by coroutine.create.
level - A number to describe the point at which information from the call stack information should be returned.
A value of 1 represents the function which is calling debug.info. 2 represents the function that called that function, and so on. Out-of-bounds values will result in no values returned.
options - A string that represents the information to be returned. It must contain exactly 0 or 1 of each of the following characters and no others: slnaf
s - string. The function source identifier, equal to the full name of the script the function is defined in
l - number. If functionOrLevel is a function, the line the function is defined on. If functionOrLevel is a number (examining a stack frame), the line number of the function call
n - string. The name of the function, may be nil for anonymous functions and C functions without an assigned debug name.
a - number, boolean. Arity of the function, which refers to the parameter count and whether the function is variadic.
f - function. The function which was inspected.
This function differs from debug.traceback in that it guarantees the format of the data it returns. This is useful not only for general logging and filtering purposes, but also for sending the data to systems expecting structured input, such as crash aggregation.
This function is similar to debug.getinfo, an unavailable part of the standard Lua library which serves a similar purpose.
debug.info ( function, options )
Allows programmatic inspection of the call stack.
function - A function to describe the point at which information from the call stack information should be returned.
options - A string that represents the information to be returned. It must contain exactly 0 or 1 of each of the following characters and no others: slnaf
s - string. The function source identifier, equal to the full name of the script the function is defined in
l - number. If functionOrLevel is a function, the line the function is defined on. If functionOrLevel is a number (examining a stack frame), the line number of the function call
n - string. The name of the function, may be nil for anonymous functions and C functions without an assigned debug name.
a - number, boolean. Arity of the function, which refers to the parameter count and whether the function is variadic.
f - function. The function which was inspected.
This function differs from debug.traceback in that it guarantees the format of the data it returns. This is useful not only for general logging and filtering purposes, but also for sending the data to systems expecting structured input, such as crash aggregation.
This function is similar to debug.getinfo, an unavailable part of the standard Lua library which serves a similar purpose.
debug.info ( level, options )
Allows programmatic inspection of the call stack.
level - A number to describe the point at which information from the call stack information should be returned.
A value of 1 represents the function which is calling debug.info. 2 represents the function that called that function, and so on. Out-of-bounds values will result in no values returned.
options - A string that represents the information to be returned. It must contain exactly 0 or 1 of each of the following characters and no others: slnaf
s - string. The function source identifier, equal to the full name of the script the function is defined in
l - number. If functionOrLevel is a function, the line the function is defined on. If functionOrLevel is a number (examining a stack frame), the line number of the function call
n - string. The name of the function, may be nil for anonymous functions and C functions without an assigned debug name.
a - number, boolean. Arity of the function, which refers to the parameter count and whether the function is variadic.
f - function. The function which was inspected.
This function differs from debug.traceback in that it guarantees the format of the data it returns. This is useful not only for general logging and filtering purposes, but also for sending the data to systems expecting structured input, such as crash aggregation.
This function is similar to debug.getinfo, an unavailable part of the standard Lua library which serves a similar purpose.
debug.profilebegin ( label )
Opens a microprofiler label.
debug.profileend ( )
Closes the top microprofiler label.
debug.setmemorycategory ( tag )
Assigns a custom tag name to the current thread’s memory category in the Developer Console. Useful for analyzing memory usage of multiple threads in the same script which would otherwise be grouped together under the same tag/name.
debug.resetmemorycategory ( )
Resets the tag assigned by debug.setmemorycategory to the automatically assigned value (typically, the script name).