rojo/.cursor/rules/roblox/reference/engine/libraries/debug.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: debug
type: library
summary: |
  This library provides functions useful for debugging and profiling code.
description: |
  Provides a few basic functions for debugging code in Roblox. Unlike the
  `Library.debug` library found in Lua natively, this version has been heavily
  sandboxed.
tags: []
code_samples: []
properties: []
functions:
  - name: debug.traceback
    summary: |
      Returns a string of undefined format that describes the current function
      call stack.
    description: |
      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. During debugging, this behaves like an error stack trace but
      does not stop execution of the script.

      The `level` parameter specifies what level of the call stack to consider,
      with `1` being the call of `Library.debug.traceback()` itself, `2` being
      the call of the function calling `Library.debug.traceback()`, and so on.
      See the code sample below for an example of sequential function calls.

      Note that this function will often return inaccurate results (compared to
      the original source code) and that the format of the returned traceback
      may change at any time. You should **not** parse the return value for
      specific information such as script names or line numbers.

      The following example includes sequential function calls; `fnB()` is
      called, and it calls `fnA()` which then calls `Library.debug.traceback()`.

      ```lua
      local function fnA()
      	print(debug.traceback("Specific moment during fnA()"))
      end

      local function fnB()
      	fnA()
      end

      -- Call function fnB() to begin traceback
      fnB()
      ```
    parameters:
      - name: message
        type: string
        default: ''
        summary: |
          The first line of the returned string.
      - name: level
        type: number
        default: 1
        summary: |
          The number of calls "up" the call stack to return.
    returns:
      - type: string
        summary: |
          Traceback of the current function call stack.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.traceback
    summary: |
      Returns a string of undefined format that describes the current function
      call stack.
    description: |
      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. During debugging, this behaves like an error stack trace but
      does not stop execution of the script.

      The `level` parameter specifies what level of the call stack to consider,
      with `1` being the call of `Library.debug.traceback()` itself, `2` being
      the call of the function calling `Library.debug.traceback()`, and so on.
      See the code sample below for an example of sequential function calls.

      Note that this function will often return inaccurate results (compared to
      the original source code) and that the format of the returned traceback
      may change at any time. You should **not** parse the return value for
      specific information such as script names or line numbers.

      The following example includes sequential function calls; `fnB()` is
      called, and it calls `fnA()` which then calls `Library.debug.traceback()`.

      ```lua
      local function fnA()
      	print(debug.traceback("Specific moment during fnA()"))
      end

      local function fnB()
      	fnA()
      end

      -- Call function fnB() to begin traceback
      fnB()
      ```
    parameters:
      - name: thread
        type: thread
        default:
        summary: |
          A thread as returned by `Library.coroutine.create()`.
      - name: message
        type: string
        default: ''
        summary: |
          The first line of the returned string.
      - name: level
        type: number
        default: 1
        summary: |
          The number of calls "up" the call stack to return.
    returns:
      - type: string
        summary: |
          Traceback of the current function call stack.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.info
    summary: |
      Traverses the entire stack of current thread and returns a string
      containing the call stack of target level details.
    description: |
      Allows programmatic inspection of the call stack. This function differs
      from `Library.debug.traceback()` in that it guarantees the format of the
      data it returns. This is useful for general logging and filtering purposes
      as well as for sending the data to systems expecting structured input,
      such as crash aggregation.

      ```lua
      local function fnA()
      	-- Output source identifier ("s") and line ("l") at levels 1 and 2
      	print(debug.info(1, "sl"))  --> fnA() 3
      	print(debug.info(2, "sl"))  --> fnA() 7
      end

      fnA()
      ```

      Note that this function is similar to
      [debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
      the standard Lua library which serves a similar purpose.
    parameters:
      - name: level
        type: number
        default:
        summary: |
          Determines at what level of the call stack the information returned
          should describe. A value of `1` represents the function which is
          calling `Library.debug.info()`, a value of `2` represents the function
          that called that function, and so on.
      - name: options
        type: string
        default:
        summary: |
          A string that describes what the returned information should
          represent. It must only contain 0 or 1 instances of the characters
          `slnaf`, each representing a piece of information:

          - `s` ([string](/luau/strings.md)) — The function source identifier,
            equal to the full name of the script the function is defined in.
          - `l` ([number](/luau/numbers.md)) — The line number of the function
            call represented by `level`.
          - `n` ([string](/luau/strings.md)) — The name of the function; may be
            `nil` for anonymous functions and C functions without an assigned
            debug name.
          - `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
            Arity of the function, which refers to the parameter count and
            whether the function is variadic.
          - `f` ([function](/luau/functions.md)) — The function which was
            inspected.
    returns:
      - type: Tuple
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.info
    summary: |
      Traverses the entire stack of current thread and returns a string
      containing the call stack of target function details.
    description: |
      Allows programmatic inspection of the call stack. This function differs
      from `Library.debug.traceback()` in that it guarantees the format of the
      data it returns. This is useful for general logging and filtering purposes
      as well as for sending the data to systems expecting structured input,
      such as crash aggregation.

      ```lua
      local function fnA()

      end

      local function fnB()

      end

      -- Output line ("l"), name ("n"), and identifier ("f") for both fnA() and fnB()
      print(debug.info(fnA, "lnf"))  --> 1 fnA function: 0x75e3d3c398a81252
      print(debug.info(fnB, "lnf"))  --> 5 fnB function: 0x6022a6dc5ccf4ab2
      ```

      Note that this function is similar to
      [debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
      the standard Lua library which serves a similar purpose.
    parameters:
      - name: function
        type: function
        default:
        summary: |
          The function of the call stack which the information returned should
          describe.
      - name: options
        type: string
        default:
        summary: |
          A string that describes what the returned information should
          represent. It must only contain 0 or 1 instances of the characters
          `slnaf`, each representing a piece of information:

          - `s` ([string](/luau/strings.md)) — The function source identifier,
            equal to the full name of the script the function is defined in.
          - `l` ([number](/luau/numbers.md)) — The line that `function` is
            defined on.
          - `n` ([string](/luau/strings.md)) — The name of the function; may be
            `nil` for anonymous functions and C functions without an assigned
            debug name.
          - `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
            Arity of the function, which refers to the parameter count and
            whether the function is variadic.
          - `f` ([function](/luau/functions.md)) — The function which was
            inspected.
    returns:
      - type: Tuple
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.info
    summary: |
      Traverses the entire stack of target thread and returns a string
      containing the call stack of target level details.
    description: |
      Allows programmatic inspection of the call stack. This function differs
      from `Library.debug.traceback()` in that it guarantees the format of the
      data it returns. This is useful for general logging and filtering purposes
      as well as for sending the data to systems expecting structured input,
      such as crash aggregation.

      ```lua
      local function fnA()
      	-- Output source identifier ("s") and line ("l") at levels 1 and 2
      	print(debug.info(1, "sl"))  --> fnA() 3
      	print(debug.info(2, "sl"))  --> fnA() 7
      end

      fnA()
      ```

      Note that this function is similar to
      [debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
      the standard Lua library which serves a similar purpose.
    parameters:
      - name: thread
        type: thread
        default:
        summary: |
          A thread as returned by `Library.coroutine.create()`.
      - name: level
        type: number
        default:
        summary: |
          Determines at what level of the call stack the information returned
          should describe. A value of `1` represents the function which is
          calling `Library.debug.info()`, a value of `2` represents the function
          that called that function, and so on.
      - name: options
        type: string
        default:
        summary: |
          A string that describes what the returned information should
          represent. It must only contain 0 or 1 instances of the characters
          `slnaf`, each representing a piece of information:

          - `s` ([string](/luau/strings.md)) — The function source identifier,
            equal to the full name of the script the function is defined in.
          - `l` ([number](/luau/numbers.md)) — The line number of the function
            call represented by `level`.
          - `n` ([string](/luau/strings.md)) — The name of the function; may be
            `nil` for anonymous functions and C functions without an assigned
            debug name.
          - `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
            Arity of the function, which refers to the parameter count and
            whether the function is variadic.
          - `f` ([function](/luau/functions.md)) — The function which was
            inspected.
    returns:
      - type: Tuple
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.profilebegin
    summary: |
      Starts profiling for a label.
    description: |
      Starts profiling for a
      [MicroProfiler](../../../studio/microprofiler/index.md) label.
    parameters:
      - name: label
        type: string
        default:
        summary: |
          The text that this
          [MicroProfiler](../../../studio/microprofiler/index.md) label
          displays.
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.profileend
    summary: |
      Stops profiling for the most recent label that
      `Library.debug.profilebegin()` opened.
    description: |
      Stops profiling for the most recent
      [MicroProfiler](../../../studio/microprofiler/index.md) label that
      `Library.debug.profilebegin()` opened.
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.getmemorycategory
    summary: |
      Returns the name of the current thread's active memory category.
    description: |
      Returns the name of the current thread's active memory category.
    parameters: []
    returns:
      - type: string
        summary: |
          The current thread's active memory category.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.setmemorycategory
    summary: |
      Assigns a custom tag to the current thread's memory category.
    description: |
      Assigns a custom tag name to the current thread's memory category in the
      [Developer Console](../../../studio/developer-console.md). Useful for
      analyzing memory usage of multiple threads in the same script which would
      otherwise be grouped together under the same tag/name. Returns the name of
      the current thread's previous memory category.
    parameters:
      - name: tag
        type: string
        default:
        summary: ''
    returns:
      - type: string
        summary: |
          The current thread's previous memory category.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.resetmemorycategory
    summary: |
      Resets the tag assigned by `Library.debug.setmemorycategory()` to the
      automatically assigned value (typically, the script name).
    description: |
      Resets the tag assigned by `Library.debug.setmemorycategory()` to the
      automatically assigned value (typically, the script name).
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: debug.dumpcodesize
    summary: |
      Displays a table of native code size of individual functions and scripts.
    description: |
      Displays a table of native code size of individual functions and scripts.
      This function is only available in the Command Bar in Studio. More details
      can be found on the
      [Native Code Generation](../../../luau/native-code-gen.md) page.
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''