增强对话框

加强对话框（custom.dialog）

一个不依赖 SDK 内置对话框的、可复用的自建对话框控件库。采用 混合架构：
Lua 负责对话框的渲染与交互（api.ui.mount），一个 C++ 原生插件（Native ABI v2）负责原生数据/持久化/命令。

本 mod 是完全自建的一套控件，不使用 SDK 自带的 DialogShow（那个只有标题/正文/按钮）。
当前清单为 native = false（纯 Lua 运行）；C++ 原生插件源码已就绪，构建后把清单改回 native 即可启用。

功能

• 打字框（真实键盘，聚焦限定）：演示页提供N 个输入框（FIELD_COUNT 可调，默认 3），点击其中一个聚焦后即可用物理键盘打字；点击另一个框切换聚焦，点击其它控件自动取消聚焦——避免抢游戏快捷键。通过 api.widgets 的 key_char/key_down 事件实现，同时保留屏幕虚拟按键作备用。
• 列表：分页显示条目。
• 多选框：每条目一个复选框，可选中/取消，底部显示“已选 N 项/共 M 项”。
• 翻页：上一页/下一页按钮 + “第 x/y 页”指示。
• 关闭 / 确定 按钮（确定会回调并返回所选与文本）。
• 窗口固定位置：窗口由 api.ui 挂载，固定在初始位置（该 UI 系统不支持移动面板，见下方限制）。

架构

mods/加强对话框/
├── .tao/project.json       工程模型（apiVersion 3，entry=main.lua；native 当前为 false）
├── mod.lua                 运行时清单
├── main.lua                入口：注册命令 dialog/showcase、主菜单按钮、单一 UI 轮询器、
│                           键盘打字订阅（key_char/key_down）、共享配置持久化、清理
├── dialog.lua              可复用控件库（dialog.show/close/get/tick/...）
├── showcase.lua            分页功能演示（页1 说明 / 页2 多输入框(聚焦) / 页3 列表翻页 / 页4 多选）
├── native/                 C++ 原生插件源码（构建后才加载）
│   ├── plugin.cpp          C++ 原生后端（ABI v2）
│   ├── CMakeLists.txt      原生构建（输出 native/plugin.dll）
│   ├── include/tao/        完整公开 SDK 头文件
│   └── licenses/           LGPL-3.0 / GPL-3.0
└── README.md

职责划分

侧	职责
Lua	dialog.lua 用 api.ui.mount 构建窗口/标题/列表行/键盘/翻页；main.lua 用单一 host:update 轮询器统一 poll_events 并把事件分发给 showcase 与 dialog库；通过 api.widgets 的键盘事件把物理按键喂给打字框；用共享 registry 配置记住窗口几何/文本。
C++	plugin.cpp：注册原生命令 dialog.native；Hook Lawn.Board.MouseDownWithPlant 检测标题栏按下发 dialog:drag_start；订阅 dialog:geom 跟踪对话框区域；读写共享 registry 配置实现几何持久化；OnReady 发 dialog:native_ready。

Lua 与 C++ 通过 公开事件 与 共享 registry 配置 通信，不共享裸指针或对象所有权。
所有原生能力均优雅降级：缺失时仅记录日志，Lua 控件库仍可独立工作。

在游戏内使用

1. 将本目录放入 mods 后，进入游戏。
2. 打开对话框有两种方式：
   • 主菜单按钮：在主菜单界面右上角会出现「打开功能展示（加强对话框）」按钮，点击即可打开（进入其他场景会自动隐藏）。
   • 命令：在游戏内输入 showcase 或 dialog 回车。
3. showcase 是分页演示：页1 说明 / 页2 多输入框 / 页3 列表翻页 / 页4 多选（顶部 < > 切换）。
4. dialog 打开一个多功能对话框（打字框+列表+多选+翻页+关闭/确定在同一窗口）。
5. 打字框（页2 有 N 个输入框，FIELD_COUNT 可调）：点击其中一个聚焦后，用物理键盘输入；也可用下方虚拟按键点击输入——都只进当前聚焦的那个框。

关于原生插件：当前 native = false，纯 Lua 即可运行全部控件。要启用原生增强（dialog.native 自检命令、几何持久化等），先构建 native/plugin.dll：

cmake -S native -B build/native -A x64
cmake --build build/native --config Release

再把 .tao/project.json 与 mod.lua 的 native 改回 "native/plugin.dll" 重新进入游戏。

复用给其他 mod（通用控件库）

dialog.lua 是自包含的通用控件库。其他 mod 依赖它的步骤（注意：本游戏 poll_events 在一个 mod 里只能由一个轮询器调用，务必遵守"单轮询器"）：

-- ① 把 dialog.lua 复制到你的 mod 目录
-- ② 加载
local D = assert(api.include("dialog.lua") or MOD_DIALOG, "加载 dialog.lua 失败")
-- ③ 用你唯一的主循环轮询器驱动它
local tick = api.events.on("host:update", function()
  local events = api.ui.poll_events(64)
  if events then D.tick(events) end   -- 把你自己的 UI 事件也在这里处理
end)
-- ④ 打开对话框
local h = D.show{
  title = "修改器设置",
  items = { {label="无限阳光", selected=true}, {label="无冷却"} },
  on_ok = function(snap) api.log("已选 "..tostring(#snap.selected).." 项，文本="..snap.text) end,
}
-- ⑤ 停用清理
D.close_all()          -- 或 D.stop()
if tick then api.events.off(tick) end

关键：一个 mod 只放一个 host:update 轮询器，poll_events 只调一次，再分发给自己的 UI 和 D.tick(events)。不要让对话库再自轮询，也不要再加第二个轮询器，否则事件会被先注册的轮询器抢占。

构建原生 DLL（可选）

在 VS Code 中按 Ctrl+Shift+B，或终端：

cmake -S native -B build/native -A x64
cmake --build build/native --config Release

产物输出为 native/plugin.dll。架构为 Windows x64（与游戏一致）。需要 CMake 3.20+ 与 Visual Studio C++ 工具链。

离线校验

py -3 <技能目录>/scripts/validate_mod.py <本目录>

符合 SDK 2.0 公开契约的校验（工程 schema、清单一致性、Hook 名称、资源路径等）。

API 一览（dialog.lua, 供其他 mod 复用）

local D = assert(api.include("dialog.lua") or MOD_DIALOG)
local h = D.show{
  title = "标题",
  items = { {label="阳光", selected=true}, {label="金币"} },
  text = "初始文本",
  pageSize = 6,
  x = 80, y = 60,
  on_ok  = function(snap) print(snap.text, #snap.selected) end,
  on_close = function(snap) end,
}
-- D.tick(events) 每帧驱动；D.close(h)/D.close_all()/D.get(h)/D.find(h)/D.stop()
-- snap: { id,title,text,page,pageCount,x,y,w,h, selected={ {index,label}, ... } }

SDK 限制（实机验证结论）

• 窗口无法拖动：api.ui 面板节点只有 set_visible/set_text 等方法，没有任何改位置/布局的方法（set_layout/set_pos/set_position/set_geometry/set_size 等均不存在），挂载后的窗口不能重新定位。拖拽坐标其实能取到（api.widgets 的 mouse_drag 事件带 x,y），但面板动不了，故窗口固定位置。真正拖动需未来接入原生插件用底层 widget 层驱动。
• 键盘打字：通过 api.widgets 的 key_char（字符码，第 6 参）/key_down（按键码）事件实现，真实键盘可用。已做聚焦限定：点击输入框聚焦后物理键盘才输入，点击翻页/列表/多选/关闭自动取消聚焦，避免抢游戏快捷键。只接受可打印 ASCII（32–126）；中文输入需按需扩展。
• C++ 文字渲染：公开的 C++ 服务没有画文字原语（无 DrawString/resource_draw_text），因此文字渲染全部放在 Lua 侧 api.ui.mount。

游戏内验证清单（需在本机游戏运行）

• 主菜单按钮能打开 showcase；或 showcase/dialog 命令能打开。
• 顶部 < > 能切换功能页，页码指示正确。
• 打字框：点击任一输入框能聚焦并输入；未聚焦时物理键盘不输入；切换聚焦互不串字；退格能删；虚拟按键也能输入。
• 列表分页正确，页码指示正确。
• 复选框能勾选/取消，底部“已选 N/M”正确。
• 点“×”/“取消”关闭；点“确定”回调并关闭。
• 关闭后再打开，窗口位置/文本被记住（共享配置）。
• dialog.native 自检命令返回“已处理”（需构建原生插件）。
• 停用/重载 mod 后无残留 UI 树或事件。

离线校验与 C++ 编译通过不等于游戏内行为正确；请以上述清单为准逐项测试。native/ 文件夹装的是 C++ 插件源码（plugin.cpp、CMakeLists、SDK 头文件、许可），为开发者编译所用。