wc3-map-ts-template: Skill for Cursor

wc3-map-ts-template 项目认知

技术栈与目标版本

• 游戏：魔兽争霸 III 1.27a。
• 语言：TypeScript → typescript-to-lua (TSTL) → Lua 5.3。
• 运行时：YDWE / KKWE 提供的 Lua 环境与 JAPI（通过 jass.* 模块 require）。
• API 封装：@eiriksgata/wc3ts（类型与 WC3 API 绑定）。
• 地图工程：w3x2lni LNI 目录（maps/）。KKWE 原生打开/保存 LNI，保存时直接写回 maps/map/ 与 maps/table/*.ini。本仓库日常只用 w2l.exe 打包（maps/ → dist/map.w3x），不要在 KKWE 保存后再解包 .w3x。

核心载入链路

1. JASS 入口：maps/map/war3map.j 的 main 末尾应包含
   call Cheat("exec-lua:bootstrap")
   构建脚本 scripts/common.ts 的 injectLuaExecutionCall() 会在未注入时自动写入（或把旧的 exec-lua:main 升级为 bootstrap）。

2. 引导脚本：lua/bootstrap.lua 在构建时复制到 maps/map/bootstrap.lua，随地图进 MPQ。

3. bootstrap.lua 行为：

   • 将 jass.common、jass.japi 注册进 _G。
   • 开发模式：若存在全局 PROJECT_PATH（handleBootstrapLua(true) 注入），则 require("src.main")，并从 dist/ 通过 package.path 加载多文件 Lua。
   • 生产模式：无 PROJECT_PATH 时 require("main")，对应 tsconfig.prod.json 单文件打包输出。

4. TS 入口：src/main.ts 导出供 Lua 调用的初始化逻辑（如 initialize），与 bootstrap.lua 中 main.initialize 一致。

构建与命令（package.json）

w2l 路径：config.json 中 w2l.path（默认 dev_lib/w3x2lni）。实际打包命令与 scripts/common.ts 中一致：w2l.exe obj ./maps ./dist/map.w3x。

目录约定

• src/：TypeScript 源码；TSTL 输出到 dist/（开发多文件，生产见 tsconfig.prod.json 的 bundle）。
• maps/：w3x2lni LNI 工程根（含 map/、resource/、table/，以及作为 LNI 标记的空文件 .w3x）。KKWE 直接打开这个目录。
• maps/map/：war3map.j、bootstrap.lua、地形/触发相关文件等。KKWE 保存地形时写这里。
• maps/table/*.ini：物编等数据以 w3x2lni 的 INI 文本 维护（如 unit.ini、imp.ini、w3i.ini）。KKWE 保存物编/地图信息时会自动更新这些 ini。手改或 KKWE 改完后，只有进游戏测图才需要 yarn build / yarn build:map 把 LNI 打包进 dist/map.w3x。
• dist/map.w3x：构建产物（打包后的 MPQ）。不要用它当地形/物编编辑源，也不要再解包回 maps/。测图必须经 KKWE 启动；原版 Warcraft III.exe / 双击 .w3x 没有 KKWE 的 Lua/JAPI，地图脚本不会工作。
• lua/：仓库中的 bootstrap 源，构建时同步到 maps/map/bootstrap.lua。