Cocos / Unity / OpenResty

Common notes

• Before using LuaDebug, disable other Lua debug extensions.
• Start the editor debugger first, then the game.
• Copy runtime files from the extension luadebug folder to a path the project can require.
• Use LuaDebugjit.lua for LuaJIT; LuaDebug.lua for standard Lua.

Cocos (Creator / cocos2d-x Lua · 2.x / 3.x)

Preparation

1. Copy LuaDebug.lua or LuaDebugjit.lua into the script directory.
2. Require it early in the entry script (e.g. main.lua) and schedule the callback:

local breakSocketHandle, debugXpCall = require("LuaDebugjit")("127.0.0.1", 7003)
cc.Director:getInstance():getScheduler():scheduleScriptFunc(breakSocketHandle, 0.3, false)

Create / add debug configs

• No launch.json: create one and pick LuaDebug.
• Existing: Add Configuration → LuaDebug: Cocos2-launch or LuaDebug: Cocos remote.

Local launch sample

{
  "name": "Cocos2-launch",
  "type": "lua",
  "request": "launch",
  "runtimeType": "Cocos2",
  "localRoot": "${workspaceFolder}",
  "commandLine": "-workdir ${workspaceFolder}/../ -file src/main.lua",
  "port": 7003,
  "exePath": "",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "printType": 1
}

exePath is the absolute path to the simulator / player. On Windows use the .exe; on macOS use .app/Contents/MacOS/<executable>.

localRoot is the project workdir — where the debugger looks for scripts.

Remote / device attach sample

{
  "name": "COCOS(remote debugging)",
  "type": "lua",
  "request": "attach",
  "runtimeType": "Cocos2",
  "localRoot": "${workspaceFolder}",
  "port": 7003,
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "printType": 1
}

StartDebug IP: use 127.0.0.1 on the same machine; on a device use the PC’s LAN IP. If you see module 'socket.core' not found, see FAQ.

Common Cocos commandLine args

launch commandLine is passed to the simulator. Common options:

Cocos 4.0 notes

Cocos 4.0 changed the CLI: -file may no longer work. Follow the official 4.x launch flow and ensure the entry script includes debug code.

Tip: open only the script folder (e.g. src) in the editor and keep launch.json there.

local breakSocketHandle, debugXpCall = require("LuaDebugjit")("127.0.0.1", 7003)
cc.Director:getInstance():getScheduler():scheduleScriptFunc(breakSocketHandle, 0.3, false)

Unity · xLua

DoString / AddLoader

If you load scripts with luaEnv.DoString, the second argument (chunkname) must be the real file path/name. If a .txt suffix in chunkname breaks mapping, try stripping it. Custom AddLoader must likewise map chunk names to disk paths.

Wire up debugging

1. Put the runtime files in the Lua script directory.
2. Require and StartDebug in Lua startup.
3. Use launch LuaDebug: Unity-xlua with runtimeType Unity.

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

Order: editor F5 → Unity runs until StartDebug. For API hints set "luadebug.apiType": "xlua" (unrelated to whether breakpoints work).

Unity · sLua

Older sLua (e.g. before 1.5.1) may ship without LuaSocket — integrate socket first.

1. Copy runtime files and StartDebug at Lua startup.
2. Use launch LuaDebug: Unity-slua.
3. Confirm the runtime loads the same scripts as the editor (watch AssetBundles).

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

Unity · uLua / toLua

1. Copy the matching runtime files into the Lua directory.
2. Require + StartDebug in startup Lua.
3. launch may use Unity-ulua; toLua also uses runtimeType: Unity with localRoot at the real script root.
4. Custom loader / DoFile: chunkname must map to a real path.

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

Suggested order: set breakpoints and start debugging in the editor → run Unity → confirm hits.

OpenResty

1. Open the project; script root is often src (any name is fine).
2. Copy the OpenResty / JIT runtime from the extension into the script root and call StartDebug during init.
3. Add launch LuaDebug: OpenResty.
4. Worker model: enable only on workers you debug, and allow the port.

{
  "name": "OpenResty",
  "type": "lua",
  "request": "attach",
  "runtimeType": "OpenResty",
  "localRoot": "${workspaceFolder}",
  "port": 7003,
  "fileExtNames": [".lua"],
  "printType": 1
}

Standalone apps (not Cocos / Unity)

If the runtime can load Lua and supports LuaSocket, call StartDebug at entry. Use attach launch and point localRoot at the script root.

Device debugging

1. Phone and PC on the same LAN.
2. StartDebug host = PC LAN IP (not 127.0.0.1).
3. port matches launch; open the firewall for that port.
4. Editor F5 first, then start the app on the phone.

loxodon-framework-xlua cannot debug

Some frameworks wrap script loading deeply. If breakpoints never bind, check:

• DoString / loader chunkname is a real path;
• runtime reads packed bytecode / AB that is out of sync with editor sources;
• localRoot points at the directory that actually holds Lua.

Hook StartDebug where Lua text is actually executed, and ensure chunkname maps correctly.