Debug · LuaDebug

Where runtime files come from

The extension’s luadebug folder contains the runtime files. After updating the extension, copy them again and confirm the runtime actually loads this copy (especially Unity — avoid running an old AssetBundle).

LuaDebug.lua — standard Lua
LuaDebugjit.lua — LuaJIT
OpenResty build — see Frameworks · OpenResty

Setting luadebug.automaticDownloadingDebugFile is deprecated: the extension no longer prompts to download debug files.

Connection order

Start the editor debug session (listens on the launch port).
Start the game / client and run StartDebug(host, port).
Ports must match; on a device, host is the PC’s LAN IP.

How to add launch configs

Open the Run and Debug panel.
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 debug extensions are installed, keep only LuaDebug — otherwise type=lua may be claimed by another extension.

{
  "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
    }
  ]
}

Common launch fields

Field	Description
`name`	Label shown in the debug dropdown
`type`	Always `lua` (UI shows LuaDebug)
`request`	`launch` starts a process from the editor; `attach` waits for a connection
`runtimeType`	Cocos2 / Cocos3 / Unity / OpenResty / LuaTest, etc.
`localRoot`	Local script root for stack path mapping; wrong values cause wrong files / jumps
`port`	Debug port (default 7003); must match StartDebug
`exePath`	Executable path in launch mode (simulator / player)
`commandLine`	Args passed to the simulator (common for Cocos)
`mainFile`	Entry script name in some configs
`fileExtNames`	Suffixes the engine may use for Lua
`printType`	1 console+system; 2 console only; 3 system only

Full engine samples: Frameworks.

LuaTest

Pick LuaTest in launch to debug the current / a given 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, if you see Permission denied, check execute permission on the extension folder and temp scripts, or allow the program under Privacy & Security.

Multiple game folders

With several similar directories, the debugger may guess the wrong file from package.path / chunkname. Use a separate 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, then F5. Non-Cocos projects likewise only need a correct localRoot.