y3-lualib-types

Y3 原生引擎接口的 TypeScript 声明，用于 TypeScriptToLua 项目。 上游 y3-editor/y3-lualib 子模块只是引擎元数据来源，地图不需要安装、初始化或加载这个 Lua 库。

生成边界

| 输入 | 输出 | | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | meta/gameapi*.lua、meta/globalapi.lua 的空函数声明 | 全局 GameAPI、GlobalAPI | | meta/pytype.lua 和单位、技能、玩家等原生对象元数据 | py.Unit、py.Ability、py.Role 等句柄及原生方法 | | meta/manually.lua、double.lua、KKNetwork.lua 的原生补充声明 | Fix32、regist_object_event、xdouble、KKNetwork 等引擎入口 | | meta/event.lua 中的 key、event_params.name/type | EngineEventMap，使用 ET_* 名称和 __unit_id 等原始字段 | | meta/enum.lua 的原生数值 | 编译时内联的 Enum.* 常量枚举 |

不扫描 game/、object/、tools/、util/ 等 Lua 实现目录，不生成全局 y3、 封装类 Unit / Timer / Point 或 y3.math 等工具接口。 meta/editor_object.lua 的封装数据结构和 must_sync.lua 的运行库配置也不进入声明。 事件中的 lua_name、lua_type、lua_code 属于封装转换，全部忽略，绝不执行。

meta/manually.lua 中两个引用封装命名的注解被替换为类型定义： y3.Number 对应 EngineNumber，y3.Const.EventType 对应原生 EngineEventName。 这不会声明任何运行时 y3 对象。引擎对 Lua 虚拟机的扩展，例如 os.clock_banned， 仍属于原生接口；普通 Lua 标准库的完整声明可单独使用 Lua typings。

未来需要新增工具方法时，应以 TypeScript 源码实现并独立编译，不能仅生成一个依赖 lualib 实现的 .d.ts，也不能把工具方法混入原生接口。

开发命令

维护此项目需要 Node.js 22+、Git、Yarn Classic 1.22.22；声明包本身没有 Node 运行时要求。

yarn
yarn build
yarn verify

• yarn build：初始化/更新元数据子模块，生成原生声明并严格检查。 上游 SHA、生成脚本、依赖和产物都未变化时跳过；网络失败会报错。
• yarn build:offline：使用本地锁定的上游提交，不查询 GitHub。
• yarn build --force：强制重新生成。
• yarn verify：解析与范围回归、接口逐项对账、严格 TypeScript 检查、TSTL 编译及格式检查。
• yarn pack:types --bump=minor：验证并打包预演，不发布。
• yarn publish:types --bump=minor：发布原生引擎版本。后续同范围版本可使用 yarn publish:types。

使用 publish:types，不要用 Yarn 内置的 yarn publish 绕过验证。 发布脚本检查组织权限、文件白名单、内容变化和 tarball 完整性。 从原来的 lualib 封装声明切换到原生接口属于破坏性变更，脚本禁止以 patch 发布这次迁移。

地图使用方式

当前分支是原生引擎版，与原来发布的 0.1.0 封装版不兼容。 新版发布后安装对应版本；发布前可通过 pack:types 生成的本地 tarball 验证。

yarn add -D @sunlight_xlz/y3-lualib-types

{
  "compilerOptions": {
    "strict": true,
    "types": ["@sunlight_xlz/y3-lualib-types"]
  },
  "tstl": { "luaTarget": "5.4" }
}

const unit: py.Unit = GameAPI.get_unit_by_id(1);
unit.api_set_name('原生单位');

regist_object_event(unit, 'ET_UNIT_DIE', (data) => {
  const id: py.UnitID = data.__unit_id;
  const damage: py.Fixed = data.__damage;
  const source: py.Unit = data.__source_unit;
});

这里的 ID 和对象必须在实际地图中有效。生成的 Lua 直接调用引擎： GameAPI.get_unit_by_id(1)、unit:api_set_name(...)，没有 require 'y3'。

可使用 import type { py, EngineEventMap } from '@sunlight_xlz/y3-lualib-types'， 不能通过运行时 import 加载声明包。Enum.UnitCommandTypeEnum.ATTACK_TARGET 会内联为数字 3，无需在地图中定义 Enum 表；项目不要启用 preserveConstEnums。

原生事件回调只提供原始字段。未列入元数据的自定义事件允许使用字符串名称， 其回调数据为 unknown，由项目自行定义类型。py.Fixed、XDouble 等保留原生对象类型， 不会被包装层自动转换成 JavaScript 的 number。原生对象的方法和可空返回值按元数据保留。

项目结构

vendor/y3-lualib/       引擎元数据来源；不随 npm 包发布
scripts/metadata.mjs    明确选择输入，解析原生空函数及原始事件/枚举
scripts/lua-types.mjs   LuaLS 类型语法
scripts/generate.mjs    输出引擎声明和来源清单
scripts/build.mjs       上游更新、增量缓存、验证后同步
scripts/verify.mjs      统一测试入口，发布时也执行
scripts/publish.mjs     打包、版本和发布
test/                  原生消费者与范围/解析回归
types/index.d.ts       声明包入口
types/api/             GameAPI 和 GlobalAPI 分片
types/objects/         原生句柄上的方法
types/handles.d.ts     引擎类型及继承关系
types/globals.d.ts     原生全局函数与对象
types/events.d.ts      原始事件载荷
types/enums.d.ts       编译时常量枚举
generation.json        输入范围、接口逐项清单和元数据诊断

所有 types/ 文件都由脚本生成，应修改生成逻辑或元数据适配后重新构建。 新增未分类元数据、未知类型、无法归属的函数，以及声明文件中出现实际 Lua 函数实现时， 构建会停止。generation.json 对每个原生空函数保留来源位置，测试将其与输入逐项对账。

上游少量手写元数据缺少规范参数或返回注解，相关签名保留 any / unknown 并列入诊断， 不靠猜测补类型。元数据与当前地图使用的引擎版本需要匹配；TypeScript 和 TSTL 检查 不能代替 Y3 编辑器内的运行验证。

MIT 许可证，上游许可保留在 UPSTREAM-LICENSE。