Skip to main content

Debugger

Attaches a Debugger to the Matter instance, allowing you to create debug widgets in your systems.

local debugger = Matter.Debugger.new(Plasma)

local widgets = debugger:getWidgets()
local loop = Matter.Loop.new(world, widgets) -- pass the widgets to your systems

debugger:autoInitialize(loop)

if IS_CLIENT then
	debugger:show()
end

When the debugger is not open, the widgets do not render.

Properties​

authorize​

</>
Debugger.authorize: (player: Player) → boolean

Create this property in Debugger to specify a function that will be called to determine if a player should be allowed to connect to the server-side debugger. In Studio, this property is ignored.

If not specified, the default behavior is to allow anyone in Studio and disallow everyone in a live game.

debugger.authorize = function(player)
	if player:GetRankInGroup(372) > 250 then -- etc
		return true
	end
end

findInstanceFromEntity​

</>
Debugger.findInstanceFromEntity: (entityId: number) → Instance?

Create this property in Debugger to specify a function that will be called to determine what Instance is associated with an entity. This is used for the in-world highlight in the World inspector.

If not specified, the in-world highlight will not work.

debugger.findInstanceFromEntity = function(id)
	if not world:contains(id) then
		return
	end

	local model = world:get(id, components.Model)

	return model and model.model or nil
end

raycastParams​

</>
Debugger.raycastParams: RaycastParams

Create this property in Debugger to specify the RaycastParams used for the mouse highlight. For example, you may want to specify a different collision group.

local raycastParams = RaycastParams.new()
raycastParams.CollisionGroup = "SomeGroup"
debugger.raycastParams = raycastParams

componentRefreshFrequency​

</>
Debugger.componentRefreshFrequency: number

Create this property in Debugger to specify the frequency (in seconds) that the unique component list will refresh.

If not specified, it will use a default time of 3 seconds.

debugger.componentRefreshFrequency = 1

loopParameterNames​

</>
Debugger.loopParameterNames: {string}

Create this property in Debugger to specify the names of the parameters to your Loop constructor. This is used to display a more accurate name in the debugger.

If not specified, the default behavior is to label Worlds as "World" and tables as "table", followed by its index.

debugger.loopParameterNames = {"World", "State", "Widgets"}

Functions​

new​

</>
Debugger.new(
plasma: Plasma--

The instance of Plasma used in your game.

) → Debugger

Creates a new Debugger.

You need to depend on Plasma in your project and pass a handle to it here.

show​

This item only works when running on the client. Client
</>
Debugger:show() → ()

Shows the debugger panel

hide​

This item only works when running on the client. Client
</>
Debugger:hide() → ()

Hides the debugger panel

toggle​

This item only works when running on the client. Client
</>
Debugger:toggle() → ()

Toggles visibility of the debugger panel

autoInitialize​

</>
Debugger:autoInitialize(loop: Loop) → ()

Adds middleware to your Loop to set up the debugger every frame.

TIP

The debugger must also be shown on a client with Debugger:show or Debugger:toggle to be used.

CAUTION

Debugger:autoInitialize should be called before Loop:begin to function as expected.

If you also want to use Plasma for more than just the debugger, you can opt to not call this function and instead do what it does yourself.

replaceSystem​

</>
Debugger:replaceSystem(
old: System,
new: System
) → ()

Alert the debugger when a system is hot reloaded.

switchToServerView​

This item only works when running on the client. Client
</>
Debugger:switchToServerView() → ()

Switch the client to server view. This starts the server debugger if it isn't already started.

switchToClientView​

</>
Debugger:switchToClientView() → ()

Switch the client to client view. This stops the server debugger if there are no other players connected.

update​

</>
Debugger:update() → ()

This should be called to draw the debugger UI.

This is automatically set up when you call Debugger:autoInitialize, so you don't need to call this yourself unless you didn't call autoInitialize.

getWidgets​

</>
Debugger:getWidgets() → {[string]: Widget}

Returns a handle to the debug widgets you can pass to your systems.

All plasma widgets are available under this namespace.

-- ...
local debugger = Debugger.new(Plasma)

local loop = Loop.new(world, state, debugger:getWidgets())

When the Debugger is not open, calls to widgets are no-ops.

If the widget normally returns a handle (e.g., button returns a table with clicked), it returns a static dummy handle that always returns a default value:

  • checkbox
    • clicked: false
    • checked: false
  • button
    • clicked: false
  • slider: 0
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new Debugger.\n\nYou need to depend on [Plasma](https://matter-ecs.github.io/plasma/) in your project and pass a handle to it here.",
            "params": [
                {
                    "name": "plasma",
                    "desc": "The instance of Plasma used in your game.",
                    "lua_type": "Plasma"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Debugger"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 152,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "show",
            "desc": "Shows the debugger panel",
            "params": [],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 239,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "hide",
            "desc": "Hides the debugger panel",
            "params": [],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 252,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "toggle",
            "desc": "Toggles visibility of the debugger panel",
            "params": [],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 269,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "autoInitialize",
            "desc": "Adds middleware to your Loop to set up the debugger every frame.\n\n:::tip\nThe debugger must also be shown on a client with [Debugger:show] or [Debugger:toggle] to be used.\n:::\n\n:::caution\n[Debugger:autoInitialize] should be called before [Loop:begin] to function as expected.\n:::\n\nIf you also want to use Plasma for more than just the debugger, you can opt to not call this function and instead\ndo what it does yourself.",
            "params": [
                {
                    "name": "loop",
                    "desc": "",
                    "lua_type": "Loop"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 348,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "replaceSystem",
            "desc": "Alert the debugger when a system is hot reloaded.",
            "params": [
                {
                    "name": "old",
                    "desc": "",
                    "lua_type": "System"
                },
                {
                    "name": "new",
                    "desc": "",
                    "lua_type": "System"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 419,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "switchToServerView",
            "desc": "Switch the client to server view. This starts the server debugger if it isn't already started.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 430,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "switchToClientView",
            "desc": "Switch the client to client view. This stops the server debugger if there are no other players connected.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 451,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "update",
            "desc": "This should be called to draw the debugger UI.\n\nThis is automatically set up when you call [Debugger:autoInitialize], so you don't need to call this yourself unless\nyou didn't call `autoInitialize`.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 475,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "getWidgets",
            "desc": "Returns a handle to the debug widgets you can pass to your systems.\n\nAll [plasma widgets](https://matter-ecs.github.io/plasma/api/Plasma#widgets) are available under this namespace.\n\n```lua\n-- ...\nlocal debugger = Debugger.new(Plasma)\n\nlocal loop = Loop.new(world, state, debugger:getWidgets())\n```\n\nWhen the Debugger is not open, calls to widgets are no-ops.\n\nIf the widget normally returns a handle (e.g., button returns a table with `clicked`), it returns a static dummy\nhandle that always returns a default value:\n\n- `checkbox`\n\t- `clicked`: false\n\t- `checked`: false\n- `button`\n\t- `clicked`: false\n- `slider`: 0",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{[string]: Widget}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 511,
                "path": "lib/debugger/debugger.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "authorize",
            "desc": "Create this property in Debugger to specify a function that will be called to determine if a player should be\nallowed to connect to the server-side debugger. In Studio, this property is ignored.\n\nIf not specified, the default behavior is to allow anyone in Studio and disallow everyone in a live game.\n\n```lua\ndebugger.authorize = function(player)\n\tif player:GetRankInGroup(372) > 250 then -- etc\n\t\treturn true\n\tend\nend\n```",
            "lua_type": "(player: Player) -> boolean",
            "source": {
                "line": 81,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "findInstanceFromEntity",
            "desc": "Create this property in Debugger to specify a function that will be called to determine what Instance is associated\nwith an entity. This is used for the in-world highlight in the World inspector.\n\nIf not specified, the in-world highlight will not work.\n\n```lua\ndebugger.findInstanceFromEntity = function(id)\n\tif not world:contains(id) then\n\t\treturn\n\tend\n\n\tlocal model = world:get(id, components.Model)\n\n\treturn model and model.model or nil\nend\n```",
            "lua_type": "(entityId: number) -> Instance?",
            "source": {
                "line": 103,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "raycastParams",
            "desc": "Create this property in Debugger to specify the RaycastParams used for the mouse highlight. For example, you may want to specify a different collision group.\n\n```lua\nlocal raycastParams = RaycastParams.new()\nraycastParams.CollisionGroup = \"SomeGroup\"\ndebugger.raycastParams = raycastParams\n```",
            "lua_type": "RaycastParams",
            "source": {
                "line": 116,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "componentRefreshFrequency",
            "desc": "Create this property in Debugger to specify the frequency (in seconds) that the unique component list will refresh.\n\nIf not specified, it will use a default time of 3 seconds.\n\n```lua\ndebugger.componentRefreshFrequency = 1\n```",
            "lua_type": "number",
            "source": {
                "line": 129,
                "path": "lib/debugger/debugger.luau"
            }
        },
        {
            "name": "loopParameterNames",
            "desc": "Create this property in Debugger to specify the names of the parameters to your Loop constructor. This is used to\ndisplay a more accurate name in the debugger.\n\nIf not specified, the default behavior is to label Worlds as \"World\" and tables as \"table\", followed by its index.\n\n```lua\ndebugger.loopParameterNames = {\"World\", \"State\", \"Widgets\"}\n```",
            "lua_type": "{string}",
            "source": {
                "line": 143,
                "path": "lib/debugger/debugger.luau"
            }
        }
    ],
    "types": [],
    "name": "Debugger",
    "desc": "Attaches a Debugger to the Matter instance, allowing you to create debug widgets in your systems.\n\n```lua\nlocal debugger = Matter.Debugger.new(Plasma)\n\nlocal widgets = debugger:getWidgets()\nlocal loop = Matter.Loop.new(world, widgets) -- pass the widgets to your systems\n\ndebugger:autoInitialize(loop)\n\nif IS_CLIENT then\n\tdebugger:show()\nend\n```\n\nWhen the debugger is not open, the widgets do not render.",
    "source": {
        "line": 61,
        "path": "lib/debugger/debugger.luau"
    }
}