Genshin UGC Lua API

📖 简介

《原神》「千星奇域」UGC 玩法支持使用 Lua 编写客户端脚本（客户端控件脚本），但官方未提供本地开发工具，编写脚本时只能反复查阅网页版 API 文档。

本扩展将官方文档中的 全部 API 整理为 LuaCATS/EmmyLua 注解定义文件，注入 Lua Language Server，让你在 VSCode 中获得接近官方语言服务的开发体验：

• 无需手动配置，安装即用
• 定义数据整理自官方文档，随版本可重新生成

✨ 功能

智能补全

悬浮文档

悬停任意 API 可查看官方中文说明、参数与返回值类型：

local t = game.Tween(control, {anchoredPositionX = 100}, 0.3)
--  ^^^^^^^^^^ 悬浮显示：
--  game.Tween(object: any, tweenDataTable: table, duration: number) -> Tween
--  按目标字段和持续时间为对象创建补间动画……

类型检查

参数类型错误实时标红：

local c = game.FindClientUIRoot("HUD")
c:SetActive(1)          -- ⚠ 报错：期望 boolean，实际 number
c:SetActive(true)       -- ✔ 正确

继承与链式调用

-- ClientUI 子控件类自动继承基类全部方法
local btn: ClientUIPresetButtonControl = --[[ ... ]]
btn:GetChildren()              -- 来自 ClientUIBaseControl ✔

-- Tween 链式调用补全
game.Tween(c, {localScaleX = 2}, 0.5)
    :SetEase(Enum.EaseType.OutBack)   -- 补全 31 种缓动
    :SetLoops(-1)
    :Play()

代码片段

📦 覆盖的 API 范围

数据整理自官方综合指南·客户端控件API文档，覆盖：

• 脚本生命周期：OnInit / OnStart / OnEnable / OnDisable / OnUpdate / OnLevelUpdate / OnDestroy
• 全局 API：print、printerr、typeof、math.isnan/isinf
• 全局对象：script（Script 类）、game（26 个函数）、Enum（27 种枚举 / 394 个枚举值）、Color
• 类：Script、Tween、TweenSequence、ServerSignal、CursorEventData、EnumItem
• 客户端控件：ClientUIBaseControl 及 11 个子控件类（图片、文本框、文本视窗、预设按钮、光标检测区域、网格视窗、按键提示、界面动效、全屏动效、容器节点、模板引用），共 24 个 @class 定义

🚀 使用

安装要求

• VSCode ^1.103.0
• 本扩展会自动安装依赖扩展 Lua by sumneko（extensionDependencies 机制；个别 VSCode 分支若未自动安装，请手动安装）

快速开始

1. 安装本扩展；
2. 打开任意包含 .lua 文件的工作区；
3. 首次激活时如提示 “API 定义已注入，需要重启 Lua Server 生效”，点击 立即重启；
4. 新建 .lua 文件，输入 game. 体验补全。

验证安装

-- test.lua
local control = game.FindClientUIRoot("MyUI")

function OnStart()
    print("脚本启动，画布尺寸：", game.GetUICanvasSize())
    control:SetActive(true)
end

function OnUpdate(dt)
    -- dt: number，每帧调用
end

• game.、control:、Enum. 均有补全 → 安装成功
• 悬停 FindClientUIRoot 显示中文文档 → 文档注入成功

⚙️ 配置项

命令

🔧 工作原理

官方 API 文档 (HTML)
      │  parse_api.py（BeautifulSoup 解析）
      ▼
   api.json（259 条结构化条目 + 27 种枚举）
      │  gen_library.py（LuaCATS 注解生成）
      ▼
  ugc_api.lua（---@meta 定义文件）
      │  扩展激活时注入
      ▼
Lua.workspace.library ──► lua-language-server 读取
      ▼
补全 / 悬浮文档 / 类型检查 / 跳转定义

扩展激活时（onLanguage:lua）将自带的 library/ugc_api.lua 目录写入全局 Lua.workspace.library 设置。该文件以 ---@meta 开头，仅供语言服务使用，不影响用户项目的诊断。注入不修改用户项目根目录的 .luarc.json。

❓ 常见问题

📋 已知限制

• 官方文档中少数参数未标注类型（记为 any），这类参数暂无类型检查；
• 枚举定义以字符串字面量生成，与运行时行为一致但仅用于提示；
• 定义数据为快照版本，官方 API 变更后需等待更新。

🙏 致谢

• Lua Language Server — sumneko
• API 文档版权归 米哈游 所有，本项目仅为社区开发辅助工具，与官方无关

注意：本扩展为社区项目，与米哈游/HoYoverse 无关联。《原神》及相关名称为米哈游注册商标。