Debug · LuaDebug

Where runtime files come from

Runtime files live in the extension's luadebug folder. After updating the extension, copy them again and confirm the game actually loads that copy (Unity: avoid stale AssetBundles).

LuaDebug.lua — PUC-Rio Lua
LuaDebugjit.lua — LuaJIT
OpenResty build — see Frameworks · OpenResty

luadebug.automaticDownloadingDebugFile is deprecated; the extension no longer auto-downloads runtime files.

Connection order

Start the editor debugger (listens on the port in launch.json).
Start the game / client so StartDebug(host, port) runs.
Ports must match; on a real device, host is your PC's LAN IP.

How to add launch configs

Open Run and Debug.
No launch.json → Create launch.json → pick LuaDebug.
Existing launch.json → Add Configuration… → pick a LuaDebug: snippet.
Adjust fields per engine; port must match StartDebug.

If multiple Lua debugger extensions are installed, keep only LuaDebug or another extension may claim type=lua.

launch vs attach use different fields:

attach (Unity / OpenResty / Cocos remote): the editor listens; you start the game manually. Usually only localRoot and port are needed.
launch (Cocos local player): the editor spawns the simulator; you must set exePath and commandLine.

Unity attach example (no commandLine):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Unity-xlua",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Unity",
      "localRoot": "${workspaceFolder}",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    }
  ]
}

Cocos local launch example (requires exePath): see Frameworks · Cocos.

Common launch fields

Field	Description
`name`	Label in the debug configuration dropdown
`type`	Always `lua` (shown as LuaDebug)
`request`	`launch` spawns the app; `attach` waits for a connection
`runtimeType`	Cocos2 / Cocos3 / Unity / OpenResty / LuaTest, etc.
`localRoot`	Local script root for stack path mapping; wrong value → wrong file / jumping
`port`	Debug port (default 7003); must match StartDebug
`exePath`	Required for `launch`: simulator / player binary (macOS: `.app/Contents/MacOS/name`)
`commandLine`	Required for `launch`: args passed to the simulator (see commandLine table)
`mainFile`	Entry script in some configs
`fileExtNames`	Suffixes your engine uses for Lua sources
`printType`	1 console+system; 2 console only; 3 system only

Per-engine examples: Frameworks.

LuaTest: debug a single Lua file

Choose LuaTest in launch to debug the current / a specific Lua file without starting the full game.

{
  "name": "LuaTest",
  "type": "lua",
  "request": "launch",
  "runtimeType": "LuaTest",
  "mainFile": "${fileBasenameNoExtension}",
  "localRoot": "${fileDirname}",
  "curFileExtname": "${fileExtname}",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "port": 7003,
  "printType": 1
}

On macOS, Permission denied: check extension directory permissions or allow the app under Privacy & Security.

Multiple game folders in one workspace

With several similar trees, the debugger may pick the wrong file from package.path / chunkname. Use one config per game and set localRoot precisely:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug src1",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Cocos2",
      "localRoot": "${workspaceFolder}/src1",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    },
    {
      "name": "Debug src2",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Cocos2",
      "localRoot": "${workspaceFolder}/src2",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    }
  ]
}

Pick the matching config in the debug panel before F5. Same idea for non-Cocos projects.