Lua Addin

1. 插件简介

Lua Addin 是面向 Unity Lua 项目的 VS Code 语言服务与调试插件，适用于使用 xLua 或 tolua 的工程。

主要功能：

Lua 语法高亮、代码片段、代码补全、参数提示和悬浮提示。
定义跳转、查找引用、重命名、CodeLens 引用计数和语义高亮。
局部变量、全局变量、函数、Table、类型注解及跨文件 require 语义分析。
未定义全局变量、无效成员、参数数量和未使用局部变量等诊断。
C# Wrap 类型、方法、字段、属性、枚举及继承关系索引。
PB 配置表、协议头文件和项目特定类型传播规则支持。
SQLite 工作区索引、增量扫描和冷启动恢复。
Unity Lua 断点、单步、调用栈、变量查看和表达式求值。

插件配置统一写在工作区的 .vscode/settings.json。路径配置应使用相对工作区的路径，不能使用绝对路径。

2. 支持的版本

项目	支持范围
操作系统	Windows x64
VS Code	1.106.0 及以上兼容版本
Lua	Lua 5.3
Unity Lua 方案	xLua、tolua
调试方式	Unity 编辑器内 TCP Attach

插件发布包及 SQLite 原生模块均面向 Windows x64。当前 Unity 调试桥接默认适配提供 LuaInterface、LitJson 和 LuaScriptManager.GetMainState() 的 tolua 工程；其他接入方式需要根据工程实际的主 LuaState 获取方式调整桥接代码。

3. 配置字段说明

3.1 扫描与工程目录

配置字段	类型	默认值	说明
`luaaddin.sourceRoots`	`string[]`	`["Assets/Lua", "Lua"]`	Lua 源码根目录，也用于自动生成调试路径映射。
`luaaddin.libraries`	`string[]`	`[]`	参与补全、跳转和诊断的第三方 Lua 库目录。
`luaaddin.scanDirectories`	`string[]`	`[]`	额外的 Lua 扫描目录。
`luaaddin.ignoreDirectories`	`string[]`	`[]`	忽略的目录或单个 `.lua`、`.cs` 文件。
`luaaddin.unityProject`	`string`	`"."`	Unity 工程根目录。
`luaaddin.wrapScanPaths`	`string[]`	`["Assets/XLua/Gen", "Assets/ToLua/Generate"]`	xLua/tolua 生成代码或注册代码目录。
`luaaddin.csharpSourcePaths`	`string[]`	`[]`	C# 源码目录，用于匹配 Wrap 重载的参数名和源码注释。
`luaaddin.pbDirectories`	`string[]`	`[]`	PB 描述符目录。
`luaaddin.protocolDirectories`	`string[]`	`[]`	协议 `.h` 文件目录；可使用 `../` 指向工作区同级目录。

3.2 类型、诊断与分析

配置字段	类型	默认值	说明
`luaaddin.wrapTypeConversions`	`string[]`	`[]`	Wrap 回调参数类型、组合类型和字段类型映射；序号从 `arg0` 开始。
`luaaddin.typeGuards`	`object[]`	`[]`	自定义类型守卫规则。
`luaaddin.globals`	`string[]`	`[]`	项目全局变量白名单。
`luaaddin.diagnostics.undefinedGlobal`	`boolean`	`true`	是否报告未定义全局变量。
`luaaddin.analysis.largeFileLines`	`number`	`5000`	大文件行数阈值。
`luaaddin.analysis.largeFileExpressions`	`number`	`20000`	大文件表达式数量阈值。
`luaaddin.analysis.maxUnionMembers`	`number`	`8`	联合类型最大成员数。
`luaaddin.analysis.maxRelationExpansion`	`number`	`256`	类型及实例关系最大展开数量。

配置示例：

{
    "luaaddin.wrapTypeConversions": [
        "LuaCallCS.TryAsyncOpenUIScene:arg3 => function(LuaUIBaseExecutor:UIScene)",
        ".transform => UnityEngine.Transform"
    ],
    "luaaddin.typeGuards": [
        {
            "function": "Object.IsPlayer",
            "parameterIndex": 0,
            "trueType": "Player",
            "excludeOnFalse": true
        }
    ]
}

3.3 显示、引用与调试体验

配置字段	类型	默认值	说明
`luaaddin.highlightDecorations.enabled`	`boolean`	`false`	是否启用插件自定义字色装饰。
`luaaddin.highlightColors`	`object`	见设置界面	自定义各类语义元素的颜色。
`luaaddin.references.enabled`	`boolean`	`true`	是否启用查找引用。
`luaaddin.references.codeLens.enabled`	`boolean`	`true`	是否在方法和字段定义上方显示引用计数。
`luaaddin.debug.inlineValues.enabled`	`boolean`	`true`	调试暂停时是否显示内联变量值。
`luaaddin.trace.server`	`boolean`	`false`	是否在“Lua Addin”输出面板记录详细日志。

3.4 索引与内存

配置字段	类型	默认值	说明
`luaaddin.index.cachePath`	`string`	`".luaaddin/cache/index.sqlite"`	SQLite 索引文件路径，必须是工作区相对路径。
`luaaddin.index.mode`	`string`	`"sqlite"`	索引模式：`sqlite` 或 `memory`。
`luaaddin.memory.maxResidentFiles`	`number`	`128`	内存中保留完整语义详情的最大文件数。
`luaaddin.memory.maxResidentMb`	`number`	`256`	语义详情的目标内存上限，单位为 MB。

工作区配置示例：

{
    "luaaddin.sourceRoots": ["Assets/Code_Lua"],
    "luaaddin.libraries": ["Assets/LuaLib"],
    "luaaddin.ignoreDirectories": ["Assets/Code_Lua/Generated"],
    "luaaddin.unityProject": ".",
    "luaaddin.wrapScanPaths": ["Assets/Code/ToLua/Source/Generate"],
    "luaaddin.csharpSourcePaths": ["Assets/Scripts"],
    "luaaddin.pbDirectories": ["Assets/StreamingAssets/BinData/pb"],
    "luaaddin.protocolDirectories": ["../tools/NetProtor/msg"],
    "luaaddin.globals": ["Game", "Manager"]
}

4. VS Code 命令

在命令面板中输入 Lua Addin 可以使用以下命令：

命令	说明
`Lua Addin: 打开状态菜单`	打开插件常用操作菜单。
`Lua Addin: 停止插件`	停止语言服务、扫描和调试支持。
`Lua Addin: 重启插件`	重新加载配置并重建索引服务。
`Lua Addin: 全量扫描`	清除索引后扫描全部文件；大型工作区耗时较长。
`Lua Addin: 增量扫描`	只处理新增、修改或删除的文件。
`Lua Addin: 重启插件并刷新索引`	重启插件并刷新索引。
`Lua Addin: 打开索引数据库位置`	在文件管理器中定位 SQLite 索引。
`Lua Addin: 查看 Wrap 扫描结果`	在输出面板显示 C# Wrap 类型摘要。
`Lua Addin: 显示方法引用`	显示方法或字段的引用位置，通常由 CodeLens 调用。
`Lua Addin: 安装 Unity 调试运行时`	安装 Unity C# 调试桥接并补充 Attach 配置。

状态栏中的 Lua Addin 项也可以打开常用操作菜单。扫描进度、配置错误和运行信息会显示在状态栏、通知消息或“Lua Addin”输出面板中。

5. 调试说明及配置

5.1 安装调试运行时

使用 VS Code 从 Unity 工程目录打开工作区，不要只打开单个 Lua 文件。
执行 Lua Addin: 安装 Unity 调试运行时。
插件会识别包含 Assets 和 ProjectSettings/ProjectVersion.txt 的 Unity 工程；存在多个工程时选择目标工程。
调试桥接将安装到 Assets/Plugins/LuaAddin/LuaAddinDebugger.cs。
如果目标文件已是最新版本，插件不会重复写入；内容不同时会先请求确认再覆盖。

桥接代码仅在 Unity 编辑器中生效。进入 Play 模式前，它会取得主 LuaState 并启动内嵌调试运行时，业务 Lua 入口不需要手工调用启动、更新或关闭函数。

5.2 配置 Attach

在 Unity 工程的 .vscode/launch.json 中加入：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "luaaddin",
            "request": "attach",
            "name": "Attach Unity Lua",
            "host": "127.0.0.1",
            "port": 9966,
            "autoReconnect": true
        }
    ]
}

字段	类型	默认值	说明
`type`	`string`	`"luaaddin"`	调试器类型，固定为 `luaaddin`。
`request`	`string`	`"attach"`	Unity 调试推荐使用 Attach。
`name`	`string`	—	调试配置显示名称。
`host`	`string`	`"127.0.0.1"`	Unity Lua 调试服务地址。
`port`	`number`	`9966`	服务端口；多个 Unity 工程应使用不同端口。
`autoReconnect`	`boolean`	`true`	下次进入 Play 时自动重新附加。
`pathMappings`	`object[]`	自动生成	源码路径映射，每项包含 `localRoot` 和 `runtimeRoot`。

省略 pathMappings 时，插件会根据工作区和 luaaddin.sourceRoots 自动生成映射。需要手动映射时，可在调试配置中加入：

"pathMappings": [
    {
        "localRoot": "Assets/Code_Lua",
        "runtimeRoot": "Assets/Code_Lua"
    }
]

5.3 开始调试

启动 Unity 并进入 Play 模式。
确认 Unity 控制台出现“Lua Addin 调试服务已启动”。
在 Lua 文件中设置断点。
在 VS Code 的“运行和调试”视图选择 Attach Unity Lua 并开始调试。

当前支持断点暂停、继续、基础单步、调用栈、局部变量、upvalue、全局变量、Watch 求值和内联值。暂不支持向 Unity 进程注入式附加。

Lua Addin

zhangjunyu

Lua Addin

1. 插件简介

2. 支持的版本

3. 配置字段说明

3.1 扫描与工程目录

3.2 类型、诊断与分析

3.3 显示、引用与调试体验

3.4 索引与内存

4. VS Code 命令

5. 调试说明及配置

5.1 安装调试运行时

5.2 配置 Attach

5.3 开始调试