Luau Debugger

A debugger for Luau with debug adapter protocol(DAP) support.

Usage

• Install luau-debugger extension
• There are three ways to use this extension:
  • Launch: Directly run the debugger installed with the extension.
  • Attach: Attach to the luau runtime running externally.
  • Advance: Integrate luau-debugger into your own project.

Launch

• Add a launch configuration in launch.json

  {
    "configurations": [
      {
        "type": "luau",
        "request": "launch",
        "name": "launch luau debugger",
        "program": "${workspaceFolder}/main.lua",
        "port": 58000
      },
    ]
  }
  

  • program: The path to the lua script you want to debug
  • port: The port number to communicate with the debugger
• Press F5 to start debugging, enjoy!

Attach

• Get a luaud executable from release which a luau runtime with debug support
• Open lua folders in VSCode
• Add a launch configuration in launch.json

  {
    "configurations": [
      {
        "type": "luau",
        "request": "attach",
        "name": "attach to luau debugger",
        "address": "localhost",
        "port": 58000
      }
    ]
  }
  

• Using luaud [PORT] [LUA_ENTRY] to execute lua script with debug support:

  luaud 58000 D:/my_lua_projects/hello_world.lua
  

• Press F5 to start debugging, enjoy!

Integrate with luau-debugger in your project

• Build luau-debugger from source
• Use the interface provided by luau-debugger library.
  • You can refer to the implementation of luaud which is a minimal luau runtime integrated with luau-debugger.
• Run your project and debug the luau code using a configuration similar to Attach.

Source File Mapping

• Source file mapping is used to map the source file path from remote debugger server to VSCode workspace. Example:

  {
    {
      "type": "luau",
      "request": "attach",
      "name": "attach with source map",
      "address": "localhost",
      "port": 58000,
      "sourceMap": {
        "D:/my_lua_projects": "${workspaceFolder}"
      }
    }
  }
  

  • The above configuration will map the source file path D:/my_lua_projects/hello_world.lua to ${workspaceFolder}/hello_world.lua.

Features

• [ ] Debugger features
  • [x] Attach
  • [x] Launch
  • [x] Stop on entry
  • [x] Breakpoints
    • [x] Add break points when running (Considering thread safety)
    • [x] Conditional breakpoints
    • [ ] Data breakpoints
    • [ ] Breakpoint hit count
  • [x] Continue
  • [x] Pause
  • [x] StackTrace
    • [x] StackTrace across coroutine boundary
    • [ ] Support switching stacktrace between different coroutines
  • [x] Scopes
  • [x] Get variables
    • [x] Locals
    • [x] Upvalues
  • [x] Display variables
    • [x] nil
    • [x] boolean
    • [x] number
    • [x] string
    • [x] table
      • [x] nested table
      • [x] table with cycle reference
    • [x] vector
    • [x] function
    • [x] userdata
  • [x] Set variables
  • [x] Repl
  • [x] Watch
  • [x] Hover
  • [x] Single step
    • [x] Step in
    • [x] Step over
    • [x] Step out
  • [x] Disconnect and reconnect
  • [x] Print to debug console
  • [x] Coroutine
  • [x] Multiple lua vm
  • [x] Source file mapping
  • [x] Break from lua code (Call debug.break_here())