【前端接口】GUI:Win_Open：窗口系统的打开、关闭与层级管理

实战应用：用在哪里

前端的界面就是一个个窗口：GUI:Win_Open 按文件名打开窗口，窗口内部再Load导出的布局文件。窗口系统管着打开、关闭、层级、拖拽这一套界面基础设施，业务脚本只负责往窗口里填内容。

打开与关闭

---打开窗口 filename:窗口布局文件
function GUI:Win_Open(filename) end

-- 打开行会仓库窗口
local function openGuildRepo()
    GUI:Win_Open("guild_repo")
end

-- 关闭窗口
GUI:Win_Close("guild_repo")

Win_Open 的参数是窗口的布局文件名，引擎按文件名加载布局并创建窗口实例，窗口内的控件按布局文件的导出节点自动生成。关闭用 Win_Close 按同名关闭，窗口的 ESC 关闭、拖拽移动、右侧鼠标吞 Billy 这些行为用 Win_SetESCClose、Win_SetDrag、Win_SetSwallowRightMouseTouch 一组开关配置。

窗口与 NPC 的绑定

-- 窗口绑定 NPC：点击 NPC 打开、走远自动关
function bindNpcWindow(winID, npcIdx)
    GUI:Win_BindNPC(winID, npcIdx)
end

Win_BindNPC 把窗口的生命周期绑到 NPC 身上：绑定后窗口随 NPC 交互自动打开，玩家远离 NPC 窗口自动关闭，距离感知的窗口行为不需要业务写心跳判断。窗口的层级管理由引擎按打开顺序维护，置顶的强弹窗用层级接口调整。窗口的参数传递：Win_SetParam 与 Win_GetParam 组成窗口的入参通道，打开列表窗口时把数据源 ID 传进去，窗口内部取参加载数据。

验证与监控

窗口的打开与关闭配对监控，长期不关闭的窗口是交互流程的断点信号。

踩坑记录

窗口文件名的大小写敏感在安卓与 iOS 表现不一致，跨端的文件名规范统一小写。同一窗口的重复打开曾经叠出多层，Win_Open 的幂等语义（已打开则激活）在引擎版本里行为有差异，打开前的状态判断是兼容写法。

上线要点

窗口的布局文件由编辑器导出，导出节点的命名规范决定脚本取控件的效率，控件名的语义化命名是窗口脚本可读性的基础。窗口的打开频率统计埋点，高频打开的窗口是优化加载速度的优先对象。窗口的资源释放与引用计数（addRef/decRef）在引擎侧管理，业务侧避免长期持有窗口控件的引用。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。