Genshin UGC Lua API

English | 简体中文

A VSCode extension providing full IntelliSense support for client-side script development in Genshin Impact's UGC mode "Miliastra Wonderland"

Autocomplete · Hover Documentation · Type Checking · Code Snippets

📖 Introduction

The "Miliastra Wonderland" UGC mode of Genshin Impact supports writing client-side scripts (client UI control scripts) in Lua. However, no official local development tools are provided, so writing scripts meant repeatedly consulting the web-based API documentation.

This extension organizes all APIs from the official documentation into LuaCATS/EmmyLua annotation definition files and injects them into the Lua Language Server, giving you a development experience in VSCode close to that of an official language service:

Zero configuration — works right after installation
Definition data is compiled from the official documentation and can be regenerated for each version

✨ Features

Smart Completions

Input	Completions
`game.`	All 26 global functions (Tween, ServerSignal, FindClientUIRoot…)
`script:`	All 7 methods of the script instance (GetParam, Invoke, RegisterServerSignalHandler…)
`Enum.`	All 27 enum types (EaseType, KeyboardKeyCode, KeyEventType…)
`Enum.EaseType.`	Enum members (Linear, InSine, OutBack…)
`control:`	ClientUI control methods (GetChildren, SetActive, AddCursorEventListener…)
`Color.`	Color utility functions (FromRGB, FromRGBA, ToRGBA)

Hover Documentation

Hover over any API to view the official Chinese description, along with parameter and return value types:

local t = game.Tween(control, {anchoredPositionX = 100}, 0.3)
--  ^^^^^^^^^^ Hover shows:
--  game.Tween(object: any, tweenDataTable: table, duration: number) -> Tween
--  Creates a tween animation for the object based on the target fields and duration…

Type Checking

Parameter type errors are flagged in real time:

local c = game.FindClientUIRoot("HUD")
c:SetActive(1)          -- ⚠ Error: expected boolean, got number
c:SetActive(true)       -- ✔ Correct

Inheritance & Chained Calls

-- ClientUI control subclasses automatically inherit all methods of the base class
local btn: ClientUIPresetButtonControl = --[[ ... ]]
btn:GetChildren()              -- From ClientUIBaseControl ✔

-- Chained Tween call completion
game.Tween(c, {localScaleX = 2}, 0.5)
    :SetEase(Enum.EaseType.OutBack)   -- Completions for all 31 easing types
    :SetLoops(-1)
    :Play()

Code Snippets

Prefix	Description
`ugc-script`	Insert the script lifecycle template (OnStart / OnUpdate / OnDestroy)
`ugc-tween`	Insert the chained tween animation template
`ugc-signal`	Insert the server signal sending template

📦 API Coverage

Data is compiled from the official Comprehensive Guide · Client UI Control API documentation, covering:

Script lifecycle: OnInit / OnStart / OnEnable / OnDisable / OnUpdate / OnLevelUpdate / OnDestroy
Global APIs: print, printerr, typeof, math.isnan/isinf
Global objects: script (the Script class), game (26 functions), Enum (27 enum types / 394 enum values), Color
Classes: Script, Tween, TweenSequence, ServerSignal, CursorEventData, EnumItem
Client UI controls: ClientUIBaseControl and 11 subclasses (image, text box, text view, preset button, cursor detection area, grid view, key prompt, UI animation, full-screen animation, container node, and template reference) — 24 @class definitions in total

🚀 Usage

Requirements

VSCode ^1.103.0
The extension automatically installs its dependency Lua by sumneko (via the extensionDependencies mechanism; if it is not installed automatically in some VSCode forks, install it manually)

Quick Start

Install this extension;
Open any workspace containing .lua files;
On first activation, if prompted that "API definitions have been injected — restart the Lua Server to take effect", click Restart Now;
Create a new .lua file and type game. to try out the completions.

Verify the Installation

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

function OnStart()
    print("Script started, canvas size: ", game.GetUICanvasSize())
    control:SetActive(true)
end

function OnUpdate(dt)
    -- dt: number, called every frame
end

Completions show up for game., control:, and Enum. → installation succeeded
Hovering over FindClientUIRoot shows the Chinese documentation → documentation injected successfully

⚙️ Configuration

Setting	Type	Default	Description
`genshinUgc.injectLibrary`	`boolean`	`true`	Automatically inject the API definitions into the Lua Language Server (`Lua.workspace.library`)
`genshinUgc.promptRestart`	`boolean`	`true`	Prompt to restart the Lua Server after the first injection

Commands

Command	Description
`Genshin UGC: Restart Lua Server`	Manually restart the language service so the definitions are reloaded

🔧 How It Works

Official API documentation (HTML)
      │  parse_api.py (BeautifulSoup parsing)
      ▼
   api.json (259 structured entries + 27 enum types)
      │  gen_library.py (LuaCATS annotation generation)
      ▼
  ugc_api.lua (---@meta definition file)
      │  Injected on extension activation
      ▼
Lua.workspace.library ──► read by lua-language-server
      ▼
Completions / Hover documentation / Type checking / Go to definition

On activation (onLanguage:lua), the extension writes its bundled library/ugc_api.lua directory into the global Lua.workspace.library setting. The file begins with ---@meta, is used only by the language service, and does not affect diagnostics of user projects. The injection does not modify the .luarc.json in your project root.

❓ FAQ

No completions after typing game.?

Make sure the Lua by sumneko extension is installed and enabled;
Open the Output panel (Ctrl+Shift+U) → select the Genshin UGC Lua channel to check the injection logs;
Check that Lua.workspace.library in the global settings contains this extension's library path;
Run the command Genshin UGC: Restart Lua Server.

Hover documentation shows garbled text?

The definition file must be UTF-8 encoded. In rare cases the installation process may corrupt the file — just reinstall the extension.

"Unknown type" warnings (e.g., ColorValue)?

The type alias declarations at the end of the definition file have been corrupted; reinstall the extension.

Completion items conflict with another Lua extension (EmmyLua, etc.)?

This extension relies on the language service of sumneko. It is recommended to disable other Lua completion extensions to avoid duplicate items in the suggestion list.

📋 Known Limitations

A few parameters in the official documentation have no type annotations (recorded as any); type checking is not available for these parameters for now;
Enum definitions are generated as string literals — consistent with runtime behavior, but intended for hints only;
The definition data is a snapshot and needs to be updated after official API changes.

🙏 Acknowledgments

Lua Language Server — sumneko
The API documentation is copyrighted by miHoYo; this project is merely a community development aid and is not affiliated with the official team.

Note: This extension is a community project and is not affiliated with miHoYo/HoYoverse. Genshin Impact and related names are registered trademarks of miHoYo.

Genshin UGC Lua API（中文说明）

English | 简体中文

为《原神》千星奇域客户端脚本开发提供完整智能支持的 VSCode 扩展

自动补全 · 悬浮文档 · 类型检查 · 代码片段

基于 Lua Language Server (sumneko)

📖 简介

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

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

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

✨ 功能

智能补全

输入	补全内容
`game.`	全部 26 个全局函数（Tween、ServerSignal、FindClientUIRoot…）
`script:`	脚本实例的 7 个方法（GetParam、Invoke、RegisterServerSignalHandler…）
`Enum.`	27 种枚举类型（EaseType、KeyboardKeyCode、KeyEventType…）
`Enum.EaseType.`	枚举成员（Linear、InSine、OutBack…）
`control:`	ClientUI 控件方法（GetChildren、SetActive、AddCursorEventListener…）
`Color.`	颜色工具函数（FromRGB、FromRGBA、ToRGBA）

悬浮文档

悬停任意 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()

代码片段

前缀	功能
`ugc-script`	插入脚本生命周期模板（OnStart / OnUpdate / OnDestroy）
`ugc-tween`	插入补间动画链式调用模板
`ugc-signal`	插入服务器信号发送模板

📦 覆盖的 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 分支若未自动安装，请手动安装）

快速开始

安装本扩展；
打开任意包含 .lua 文件的工作区；
首次激活时如提示 "API 定义已注入，需要重启 Lua Server 生效"，点击 立即重启；
新建 .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 显示中文文档 → 文档注入成功

⚙️ 配置项

配置	类型	默认值	说明
`genshinUgc.injectLibrary`	`boolean`	`true`	自动将 API 定义注入 Lua Language Server（`Lua.workspace.library`）
`genshinUgc.promptRestart`	`boolean`	`true`	首次注入后提示重启 Lua Server

命令

命令	说明
`Genshin UGC: 重启 Lua Server`	手动重启语言服务，使定义重新加载

🔧 工作原理

官方 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。

❓ 常见问题

输入 game. 没有补全？

确认已安装并启用 Lua by sumneko 扩展；
打开输出面板（Ctrl+Shift+U）→ 选择 Genshin UGC Lua 通道，查看注入日志；
检查全局设置中 Lua.workspace.library 是否包含本扩展的 library 路径；
执行命令 Genshin UGC: 重启 Lua Server。

悬浮文档显示乱码？

定义文件需为 UTF-8 编码。极少情况下安装过程会损坏文件，重新安装扩展即可。

提示 unknown type（如 ColorValue）？

定义文件末尾的类型别名声明被损坏，重新安装扩展。

补全项与另一个 Lua 扩展（EmmyLua 等）冲突？

本扩展依赖 sumneko 的语言服务，建议禁用其它 Lua 补全类扩展，避免候选列表重复。

📋 已知限制

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

🙏 致谢

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

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

Genshin UGC Lua API

centralshadow

Genshin UGC Lua API

📖 Introduction

✨ Features

Smart Completions

Hover Documentation

Type Checking

Inheritance & Chained Calls

Code Snippets

📦 API Coverage

🚀 Usage

Requirements

Quick Start

Verify the Installation

⚙️ Configuration

Commands

🔧 How It Works

❓ FAQ

📋 Known Limitations

🙏 Acknowledgments

Genshin UGC Lua API（中文说明）

📖 简介

✨ 功能

智能补全

悬浮文档

类型检查

继承与链式调用

代码片段

📦 覆盖的 API 范围

🚀 使用

安装要求

快速开始

验证安装

⚙️ 配置项

命令

🔧 工作原理

❓ 常见问题

📋 已知限制

🙏 致谢