千星奇域 Lua LSP

简体中文 | English

为原神千星奇域Lua脚本开发打造的 Visual Studio Code 扩展，提供补全、悬停提示、跳转、诊断等完整的代码智能功能，并内置千星奇域运行时 API。

功能

安装

在 VS Code 中打开扩展面板，点击右上角 ... → 从 VSIX 安装...，选择 miliastraLsp-0.0.3.vsix。

也可以使用命令行：

code --install-extension miliastraLsp-0.0.3.vsix

环境要求

• VS Code 1.60.0 或更高版本
• 扩展 Lua（sumneko.lua） 必须处于禁用状态，两者同时启用会弹出冲突提示

快速上手

1. 用 VS Code 打开你的《千星奇域》脚本目录（不要只打开单个文件）。
2. 打开任意 .lua / .luau 文件，扩展会自动为每个工作区启动一个语言服务。
3. 状态栏左下角会出现扩展状态，鼠标悬停可以看到已解析文件数、内存占用等信息。

常见的几个操作：

• Ctrl + 空格：手动触发补全
• F2：重命名符号
• F12：转到定义
• Shift + F12：查找引用

配置

所有配置项均以 miliastraLsp. 为前缀，在 VS Code 设置界面搜索 miliastraLsp 即可逐项调整，也可以直接写进 settings.json：

{
    "miliastraLsp.color.mode": "Semantic",
    "miliastraLsp.completion.enable": true,
    "miliastraLsp.diagnostics.enable": true,
    "miliastraLsp.hint.enable": true,
    "miliastraLsp.workspace.ignoreDir": [
        ".vscode",
        "**/_Index/**"
    ]
}

常用配置项

全部 54 项配置的说明都可以在 VS Code 设置界面中直接看到。

诊断规则

内置 30 条诊断规则，可以逐条设置等级或关闭。按用途大致分为：

• 文档注释相关：undefined-doc-class、undefined-doc-name、undefined-doc-param、undefined-doc-module、doc-field-no-class、circle-doc-class、duplicate-doc-class、duplicate-doc-field、duplicate-doc-param
• 类型与赋值相关：no-implicit-any、unbalanced-assignments、redundant-value、duplicate-index、duplicate-set-field
• 作用域与引用相关：undefined-global、undefined-env-child、global-in-nil-env、redefined-local、unused-local、unused-function、unused-vararg、deprecated
• 代码规范相关：empty-block、trailing-space、newfield-call、newline-call、redundant-parameter、unknown-diag-code

另外当 miliastraLsp.typeChecking.mode 不为 Disabled 时，会额外交互式地给出类型检查诊断，以及 undefined-type、redefined-type 两条类型相关诊断。

想要忽略某些规则，把它的等级设为 None（关闭检查），或写进 miliastraLsp.diagnostics.disable：

{
    "miliastraLsp.diagnostics.disable": [
        "undefined-global",
        "trailing-space"
    ],
    "miliastraLsp.diagnostics.severity": {
        "unused-local": "Information"
    }
}

千星奇域 API 支持

扩展内置了《千星奇域》运行时的类型定义，开箱即可补全，无需任何额外配置：

• 全局对象：script（当前脚本实例）、game（客户端运行时全局表）、Color（颜色构造与转换）
• 类型：Script、Game、ColorValue、Tween、TweenSequence、ServerSignal、EnumItem 等
• 控件：ClientUIBaseControl 及派生控件（ClientUIImageControl、ClientUITextBoxControl、ClientUITextWindowControl、ClientUIPresetButtonControl、ClientUICursorEventAreaControl、ClientUIGridScrollerControl、ClientUIKeyHintControl、ClientUIAnimationControl、ClientUIFullscreenAnimationControl、ClientUIContainerControl、ClientUIReferenceControl），子类会自动继承父类成员
• 枚举：EaseType、Device、StageMode、LanguageType、ParamType、CustomVariableEntityType 等

同时内置了 Lua 语言基础环境（string、table、math、utf8、debug 等标准库）与元表信息。

常见问题

扩展没有任何反应，补全和诊断都不工作

先确认 Lua（sumneko.lua） 已禁用。两者注册了同一个语言 ID，同时启用会冲突。

undefined-global 报错，但那个变量确实存在

这是本扩展不认识的自定义全局变量，把它加进配置即可：

{
    "miliastraLsp.diagnostics.globals": [
        "MyGlobal",
        "MyOtherGlobal"
    ]
}

状态栏一直显示加载中

首次打开较大的项目时需要建立索引，稍等片刻即可。如果长时间不结束，检查 server/log/service.log 中的日志。

扩展完全启动不起来，且 server/log/ 是空的

说明语言服务还没执行到 Lua 代码就退出了。最常见的原因是缺少 server/bin/<平台>/main.lua 引导器——可执行文件启动时会无条件加载它。详见 CONTRIBUTING.md。如果是通过 VSIX 安装的，重新安装扩展即可恢复。

只想让诊断检查当前打开的文件

把对应规则的 miliastraLsp.diagnostics.neededFileStatus 设为 Opened，可以减少后台开销：

{
    "miliastraLsp.diagnostics.neededFileStatus": {
        "unused-local": "Opened",
        "unused-function": "Opened"
    }
}

相关文档

完整的 API 参考文档位于 docs/，基于 VitePress 构建：

cd docs
npm install
npm run dev      # 本地预览 http://localhost:5173

参与开发

构建、调试与项目结构说明请见 CONTRIBUTING.md。

致谢

• RobloxLsp：本项目的直接来源
• sumneko/lua-language-server：底层 Lua 语言服务器