Skip to main content

debugger

this module implements logging and debug widgets.

Types​

log​

</>
interface log {
message: string--

the message logged.

status: "success" | "warn" | "error"--

the status of the log.

time: number--

when the message was logged.

count: number--

the amount of times the same message was sent. a value of 1 means the message isn't repeated.

}

represents a logged message.

Properties​

iris​

</>
debugger.iris: iris

a reference to the iris library, which implements immediate-mode ui. this is used for debugger windows.

see iris' documentation and api reference for more detail.

output​

</>
debugger.output: stack<log>

a stack of all messages logged, which is rendered in the output.

the maximum amount of logs that can be stored is determined by the MAX_LOGS constant. by default, this is set to 200.

Functions​

log​

</>
debugger.log(
message: string,--

the message to log.

status: "success" | "warn" | "error"--

the status of the message

) → ()

logs a message to the output. logs are categorized by status:

  • success
  • warn
  • error, although errors do not block execution

if the message is the same as the last message, the count is incremented instead of pushing a new log.

messages are automatically prefixed with the current time and status, and have richtext enabled.

add_debugger​

</>
debugger.add_debugger(
window: window,--

an Iris window. see window for more information.

callback: () → (),--

a callback which is called every frame to render the window.

priority: number--

the priority of the debugger widget.

) → ()

adds a new window to the debugger. the callback is called to render the window by debugger.render().

start​

</>
debugger.start(
validate: (() → boolean)?--

if specified, returns a boolean which determines if the debugger should be rendered.

) → ()

starts the debugger.

this can only be called once. if you want to call it again, call debugger.cleanup() first.

the validate parameter is passed to the debugger.render() function.

render​

</>
debugger.render(
validate: (() → boolean)?--

if specified, returns a boolean which determines if the debugger should be rendered.

) → ()

renders the debugger and its widgets.

cleanup​

</>
debugger.cleanup() → ()

cleans outputted logs and all debuggers.

this resets the started flag to false.

you must call this before calling debugger.start() more than one time.

Show raw api
{
    "functions": [
        {
            "name": "log",
            "desc": "logs a message to the output. logs are categorized by status:\n- `success`\n- `warn`\n- `error`, **although errors do not block execution**\n\nif the message is the same as the last message, the count is **incremented** instead of pushing a new log.\n\n*messages are automatically prefixed with the current time and status, and have richtext enabled.*",
            "params": [
                {
                    "name": "message",
                    "desc": "the message to log.",
                    "lua_type": "string"
                },
                {
                    "name": "status",
                    "desc": "the status of the message",
                    "lua_type": "\"success\" | \"warn\" | \"error\""
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 81,
                "path": "src/shared/debugger.luau"
            }
        },
        {
            "name": "add_debugger",
            "desc": "adds a new window to the debugger. the callback is called to render the window by `debugger.render()`.",
            "params": [
                {
                    "name": "window",
                    "desc": "an Iris window. see [window](https://sirmallard.github.io/Iris/api/Window#Window) for more information.",
                    "lua_type": "window"
                },
                {
                    "name": "callback",
                    "desc": "a callback which is called every frame to render the window.",
                    "lua_type": "() -> ()"
                },
                {
                    "name": "priority",
                    "desc": "the priority of the debugger widget.",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 110,
                "path": "src/shared/debugger.luau"
            }
        },
        {
            "name": "start",
            "desc": "starts the debugger.\n\n**this can only be called once. if you want to call it again, call `debugger.cleanup()` first.**\n\nthe validate parameter is passed to the `debugger.render()` function.",
            "params": [
                {
                    "name": "validate",
                    "desc": "if specified, returns a boolean which determines if the debugger should be rendered.",
                    "lua_type": "(() -> boolean)?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 134,
                "path": "src/shared/debugger.luau"
            }
        },
        {
            "name": "render",
            "desc": "renders the debugger and its widgets.",
            "params": [
                {
                    "name": "validate",
                    "desc": "if specified, returns a boolean which determines if the debugger should be rendered.",
                    "lua_type": "(() -> boolean)?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 154,
                "path": "src/shared/debugger.luau"
            }
        },
        {
            "name": "cleanup",
            "desc": "cleans outputted logs and all debuggers.\n\nthis resets the started flag to false.\n\n**you must call this before calling `debugger.start()` more than one time.**",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 182,
                "path": "src/shared/debugger.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "iris",
            "desc": "a reference to the iris library, which implements *immediate-mode ui*. this is used for *debugger windows*.\n\nsee iris' *[documentation](https://sirmallard.github.io/Iris/docs/intro)*\nand *[api reference](https://sirmallard.github.io/Iris/api/Iris)*\nfor more detail.",
            "lua_type": "iris",
            "source": {
                "line": 52,
                "path": "src/shared/debugger.luau"
            }
        },
        {
            "name": "output",
            "desc": "a stack of all messages logged, which is rendered in the output.\n\nthe maximum amount of logs that can be stored is determined by the `MAX_LOGS` constant.\n*by default, this is set to **200**.*",
            "lua_type": "stack<log>",
            "source": {
                "line": 63,
                "path": "src/shared/debugger.luau"
            }
        }
    ],
    "types": [
        {
            "name": "log",
            "desc": "represents a *logged message*.",
            "fields": [
                {
                    "name": "message",
                    "lua_type": "string",
                    "desc": "the message logged."
                },
                {
                    "name": "status",
                    "lua_type": "\"success\" | \"warn\" | \"error\"",
                    "desc": "the status of the log."
                },
                {
                    "name": "time",
                    "lua_type": "number",
                    "desc": "when the message was logged."
                },
                {
                    "name": "count",
                    "lua_type": "number",
                    "desc": "the amount of times the same message was sent. a value of 1 means the message isn't repeated."
                }
            ],
            "source": {
                "line": 18,
                "path": "src/shared/debugger.luau"
            }
        }
    ],
    "name": "debugger",
    "desc": "this module implements *logging* and *debug widgets*.",
    "external_types": [
        {
            "name": "iris",
            "url": "https://sirmallard.github.io/Iris/api/Iris"
        },
        {
            "name": "window",
            "url": "https://sirmallard.github.io/Iris/api/Window"
        }
    ],
    "source": {
        "line": 40,
        "path": "src/shared/debugger.luau"
    }
}