debug

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).

string debug.traceback ( string message, number 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. local function a() print(debug.traceback("Specific moment during a()"))end local function b() a()end local function c() b()end a() The above code would produce an output similar to (but not guaranteed to be exactly like) the following: Specific moment during a() ServerScript.Script:2 function a ServerScript.Script:6 function b ServerScript.Script:10 function c ServerScript.Script:13 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.

string debug.traceback ( thread thread, string message, number level = 1 )

‘’

Tuple debug.info ( thread thread, number level, string 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.

Tuple debug.info ( function function, string 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.

Tuple debug.info ( number level, string 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.

void debug.profilebegin ( string label )

Opens a microprofiler label.

void debug.profileend ( )

Closes the top microprofiler label.

debug.setmemorycategory ( string 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).