REPENTOGON 的 ImGuiCallback 枚举详解:为 ImGui 界面元素绑定交互回调的完整指南
REPENTOGON 的 ImGuiCallback 枚举详解:为 ImGui 界面元素绑定交互回调的完整指南
本篇技术指南面向《以撒的结合:忏悔》模组开发者,系统讲解 REPENTOGON 脚本扩展器所提供的 ImGuiCallback 枚举。通过阅读本文,你将掌握 ImGui.AddCallback 与 ImGui.RemoveCallback 的完整用法、11 种回调类型的触发时机与底层实现原理,并能结合仓库中的官方测试脚本,为自己的自定义 ImGui 菜单、按钮、输入框等界面元素编写健壮且实用的交互逻辑。
一、ImGuiCallback 是什么
在 REPENTOGON 中,模组开发者可以通过 ImGui 全局表在游戏内创建自定义界面(菜单、窗口、按钮、输入框等)。而 ImGuiCallback 是一个枚举类型,它定义了这些界面元素在特定交互状态下可以触发的回调事件类型——也就是"什么时候调用你绑定的 Lua 函数"。
官方定义位于 docs/docs/enums/ImGuiCallback.md,共包含 11 个成员,对应数值 0 到 10:
| Value | Enumerator | 说明 |
|---|---|---|
| 0 | Clicked |
元素被点击时触发 |
| 1 | Hovered |
鼠标悬停在元素上时触发 |
| 2 | Active |
元素处于激活状态时触发 |
| 3 | Focused |
元素获得焦点时触发 |
| 4 | Visible |
元素可见时触发 |
| 5 | Edited |
元素内容被编辑时触发 |
| 6 | Activated |
元素被激活时触发 |
| 7 | Deactivated |
元素被停用时触发 |
| 8 | DeactivatedAfterEdit |
元素在编辑结束后被停用时触发 |
| 9 | ToggledOpen |
可折叠元素被展开/收起切换时触发 |
| 10 | Render |
在对象被渲染之前执行 |
其中唯一带官方注释的是 Render:"Gets executed before an object gets rendered"(在对象被渲染之前执行),这是一个常用于动态更新界面内容的特殊回调。
二、Lua 侧的定义与 C++ 侧的映射
ImGuiCallback 在仓库的 Lua 脚本中有一个直接的镜像定义,位于 repentogon/resources/scripts/enums_ex.lua:
ImGuiCallback = {
Clicked = 0,
Hovered = 1,
Active = 2,
Focused = 3,
Visible = 4,
Edited = 5,
Activated = 6,
Deactivated = 7,
DeactivatedAfterEdit = 8,
ToggledOpen = 9,
Render = 10 -- Gets executed before an object gets rendered
}
在 C++ 实现侧,REPENTOGON 使用了一个一一对应的内部枚举 IMGUI_CALLBACK,定义于 repentogon/ImGuiFeatures/CustomImGui.h,并通过 IMGUI_CALLBACK_TO_STRING 字符串数组(同文件 L73-L85)将回调类型映射为可读名称,用于错误信息的格式化输出。因此,你在 Lua 中传的 ImGuiCallback.Clicked(值为 0)与 C++ 内部 IMGUI_CALLBACK::Clicked 是完全一致的。
三、如何绑定与移除回调:AddCallback / RemoveCallback
3.1 AddCallback
将回调绑定到界面元素上,函数签名见 docs/docs/ImGui.md:
ImGui.AddCallback ( string ElementId, ImGuiCallback Type, Function func )
三个参数分别是:目标元素的 ID、回调类型(即本枚举的成员)、以及要执行的 Lua 函数。官方说明明确指出:一个元素每种回调类型最多只能绑定一个回调("An element can have one callback per type.")。如果需要更改行为,再次调用 AddCallback 覆盖即可。
底层实现位于 repentogon/ImGuiFeatures/LuaImGui.cpp:
LUA_FUNCTION(Lua_ImGui_AddCallback)
{
const char* parentId = luaL_checkstring(L, 1);
int type = (int)luaL_checkinteger(L, 2);
if (!lua_isfunction(L, 3)) {
return luaL_error(L, "Argument %d is not a function", 3);
}
int stackID = CheckAndSetCallback(L, 3);
bool success = customImGui.AddCallback(parentId, type, stackID);
if (!success) {
return luaL_error(L, "No element '%s' found.", parentId);
}
return 1;
}
这段源码揭示了三条重要的使用规则:
- 第二个参数是整数:
type通过luaL_checkinteger读取,因此既可以传ImGuiCallback.Clicked这种具名常量,也可以直接传数字0。 - 第三个参数必须是函数:如果不是函数,会直接抛出 Lua 错误
Argument 3 is not a function。 - 元素必须已存在:如果
ElementId对应的元素尚未创建,会抛出No element '<id>' found.错误。因此必须先通过ImGui.AddElement、ImGui.AddButton等函数创建元素,再绑定回调。
3.2 RemoveCallback
如需解除某个元素上指定类型的回调,使用:
ImGui.RemoveCallback ( string ElementId, ImGuiCallback type )
其底层实现(LuaImGui.cpp)同样会在元素不存在时抛出 No element '<id>' found.。从 CustomImGui.h 的结构体定义可以看出,每个元素内部使用 std::map<IMGUI_CALLBACK, int> 存储"回调类型 → Lua 函数引用"的映射,这正是"每种类型只能有一个回调"这一规则的来源。
四、11 种回调的触发时机与底层判定
每种回调在 C++ 侧都会映射到 ImGui 自身的一个状态查询函数,实现在 repentogon/ImGuiFeatures/CustomImGui.h 的 RunCallbacks 中:
| 回调类型 | 底层判定函数 | 触发条件 |
|---|---|---|
Clicked |
ImGui::IsItemClicked() |
本帧内鼠标点击了该元素 |
Hovered |
ImGui::IsItemHovered() |
鼠标悬停在该元素上(悬停期间每一帧都会触发) |
Active |
ImGui::IsItemActive() |
元素处于交互激活状态(如按住拖动) |
Focused |
ImGui::IsItemFocused() |
元素持有输入焦点 |
Visible |
ImGui::IsItemVisible() |
元素当前可见(未被裁剪或隐藏) |
Edited |
ImGui::IsItemEdited() |
元素的值在本帧被用户修改(如输入框内容变化) |
Activated |
ImGui::IsItemActivated() |
元素从非激活变为激活的瞬间 |
Deactivated |
ImGui::IsItemDeactivated() |
元素从激活变为非激活的瞬间 |
DeactivatedAfterEdit |
ImGui::IsItemDeactivatedAfterEdit() |
元素在值被编辑后停用(典型如输入框编辑完毕失焦) |
ToggledOpen |
ImGui::IsItemToggledOpen() |
可展开元素(如 TreeNode、CollapsingHeader)被展开/折叠切换 |
Render |
特殊处理(见下文) | 元素被渲染之前 |
值得注意的是 Clicked 处理的细节:命中后不仅调用回调,还会递增内部 clickCounter、切换元素的 isActive 状态,并且如果该元素关联了 Popup(通过 LinkWindowToElement),会自动打开该弹出窗口——这意味着"点击一个按钮弹出子菜单"这类常见交互无需在回调里手写任何窗口控制代码。
另外两个激活相关的回调(Activated / Deactivated)命中时会同步维护元素的 isActive 布尔状态,便于后续通过 ImGui.GetVisible 等函数查询元素状态。
五、Render 回调:渲染前执行的特殊类型
Render 是唯一一个不基于 ImGui 状态查询的回调,它在元素渲染管线中被单独处理。看 CustomImGui.h 的实现:
void RunPreRenderCallbacks(Element* element) IM_FMTARGS(2)
{
for (auto callback = element->callbacks.begin(); callback != element->callbacks.end(); ++callback) {
if (callback->first == IMGUI_CALLBACK::Render) {
RunCallback(element, callback->second, callback->first);
}
}
}
从函数名 RunPreRenderCallbacks 与枚举注释 "Gets executed before an object gets rendered" 可以确认:每当元素即将被绘制到屏幕之前,Render 回调就会执行一次。它适合两类典型用途:
- 每帧动态更新文本内容:例如显示实时鼠标坐标、玩家状态、帧率等。
- 每帧同步窗口位置:例如让窗口跟随游戏内角色移动。
仓库的测试脚本 repentogon/resources/scripts/repentogon_tests/test_imgui.lua 提供了两个非常典型的 Render 用例:
-- 用例 1:每帧更新文本,显示 ImGui 坐标系下的鼠标位置
ImGui.AddText("testWindow3", "", true, "mousePosText")
ImGui.AddCallback("mousePosText", ImGuiCallback.Render, function(val)
local mousePos = ImGui.GetMousePosition() -- this is already in imgui coordinates
ImGui.UpdateText("mousePosText", "ImGui MousePos:\t" .. mousePos.X .. "\t" .. mousePos.Y)
ImGui.SetWindowPosition("testWindow3", mousePos.X, mousePos.Y)
end)
-- 用例 2:让窗口每帧跟随玩家角色(窗口被"钉住"显示在游戏世界中)
ImGui.AddText("testWindowFollowPlayer", "<-- Player")
ImGui.AddCallback("testWindowFollowPlayer", ImGuiCallback.Render, function(val)
local playerPos = ImGui.WorldToImGui(Isaac.GetPlayer().Position)
ImGui.SetWindowPosition("testWindowFollowPlayer", playerPos.X, playerPos.Y)
end)
注意第二个用例中用到了 ImGui.WorldToImGui 进行世界坐标到 ImGui 坐标的换算(该函数同样记录在 docs/docs/ImGui.md 中),这是实现"窗口跟随角色"这类沉浸式 HUD 效果的关键。
六、回调函数的参数:元素数据如何传递
回调函数并非无参调用。在 CustomImGui.h 的 PropagateCallbackData 中,REPENTOGON 会根据元素的类型向 Lua 回调推送对应的数据参数:
| 元素类型 | 回调收到的参数 |
|---|---|
InputInt / DragInt / SliderInt |
当前整数值(currentIntVal) |
InputFloat / DragFloat / SliderFloat |
当前浮点值(currentFloatVal) |
ColorEdit(RGB) |
r, g, b 三个浮点值 |
ColorEdit(RGBA) |
r, g, b, a 四个浮点值 |
Checkbox |
勾选状态(boolean) |
RadioButton / Combobox |
选中索引 + 选中项文本 |
InputText 系列 |
当前输入的字符串 |
这一点对编写回调函数至关重要。例如测试脚本中绑定到 menuElem2(MenuItem 元素)的 Clicked 回调就收到了点击计数器:
ImGui.AddCallback("menuElem2", ImGuiCallback.Clicked, function(i) print("Clicked Counter " .. i) end)
而绑定到 Combobox 的回调则可以同时拿到索引和文本(见 docs/docs/ImGui.md 中的 AddCombobox 示例):
ImGui.AddCombobox("catInput", "combobox1", "Combobox", function(index, val) print(index, val) end, { "Item 1", "Item 2", "Item 3" }, 1)
七、完整实战示例:从菜单项到带错误演示的按钮
测试脚本 repentogon/resources/scripts/repentogon_tests/test_imgui.lua 是一份几乎覆盖全部回调类型的"活教材",下面摘取其核心片段组合成一个完整可运行的示例:
-- 1. 创建菜单与窗口
ImGui.CreateMenu("testMenu", "Test Menu")
ImGui.AddElement("testMenu", "menuElem2", ImGuiElement.MenuItem, "Menu Item Callback test")
ImGui.CreateWindow("testWindow2", "Awesome Test Window")
ImGui.LinkWindowToElement("testWindow2", "menuElem3") -- 菜单项点击后切换窗口显示
-- 2. 给 MenuItem 绑定 Clicked 回调
ImGui.AddCallback("menuElem2", ImGuiCallback.Clicked, function(i) print("Clicked Counter " .. i) end)
-- 3. 给按钮绑定 Hovered 回调(悬停即打印)
ImGui.AddElement("testWindow2", "cat1", ImGuiElement.CollapsingHeader, "Test Category")
ImGui.AddElement("cat1", "button1", ImGuiElement.Button, "A funky button")
ImGui.AddCallback("button1", ImGuiCallback.Hovered, function(_) print("Hover") end)
-- 4. 通过 Clicked 回调控制其他元素的可见性(弹出窗口)
ImGui.AddElement("catWindows", "button_popup3", ImGuiElement.Button, "open a popup via SetVisible()")
ImGui.AddCallback("button_popup3", ImGuiCallback.Clicked, function(val) ImGui.SetVisible("popup", true) end)
7.1 在项目源码中的应用实例
ImGuiCallback.Clicked 在 REPENTOGON 自身的脚本中被大量使用,是观察"真实生产环境用法"的最佳范本:
- 错误展示窗口的"复制到剪贴板"按钮(repentogon/resources/scripts/main_ex.lua):当游戏运行中出现 Lua 错误时,REPENTOGON 会弹出 Error Display 窗口,其
ErrorDisplayCopyToClipboard按钮绑定了 Clicked 回调,一键将完整错误文本写入系统剪贴板:
ImGui.AddElement(windowId, "ErrorDisplayCopyToClipboard", ImGuiElement.Button, "Copy to Clipboard")
ImGui.AddCallback("ErrorDisplayCopyToClipboard", ImGuiCallback.Clicked, function() Isaac.SetClipboard(errortext) end)
- 联机 stub 脚本的确认对话框(repentogon/resources/scripts/repentogon_extras/onlinestub.lua):在"重置 Lua"与"联机不同步"两个警告窗口中,
luareset-okay、desync-rewind、desync-restart三个按钮均通过 Clicked 回调执行确认后的动作,例如执行Isaac.ExecuteCommand("rewind")回滚:
imgui:AddCallback("desync-rewind", _ImGuiCallback.Clicked, function()
imgui:RemoveWindow("desync-warning")
imgui:Hide()
Isaac.ExecuteCommand("rewind")
end)
八、回调中的错误处理与调试
当回调函数在运行时抛出 Lua 错误时,REPENTOGON 并不会让游戏崩溃,而是会捕获异常并输出一条格式化的错误信息。底层逻辑位于 CustomImGui.h 的 RunCallback:
ImGui encountered an error in the '<CallbackTypeName>' callback of element '<ElementId>': <errorMsg>
其中 <CallbackTypeName> 正是前面提到的 IMGUI_CALLBACK_TO_STRING 映射,例如 Clicked、Hovered、Render,方便开发者快速定位是哪个元素的哪类回调出了问题。错误信息会通过控制台(Console->PrintError)输出。
测试脚本中也"故意"埋了一个演示错误回调(test_imgui.lua 中的 button3):
ImGui.AddElement("cat1", "button3", ImGuiElement.Button, "A button causing an error")
ImGui.AddCallback("button3", ImGuiCallback.Clicked, function(_) VARIABLE_DOESNT_EXIST:Test() end)
ImGui.SetColor("button3", ImGuiColor.Button, 1, 0, 0, 1) -- 用红色按钮标识"危险操作"
点击该按钮后,控制台会输出包含 Clicked 与 button3 的错误信息,而游戏与 ImGui 界面保持稳定运行——这正是模组开发者调试自定义界面时最常用的一条反馈链路。
九、常见陷阱与最佳实践
基于以上源码分析,总结以下几点实战建议:
- 先创建元素,再绑定回调:
AddCallback依赖元素已存在,顺序颠倒会直接报No element '<id>' found.。 - 每种回调类型只能绑定一个函数:这是
std::map<IMGUI_CALLBACK, int>映射结构决定的;如需替换逻辑,直接用新的AddCallback覆盖即可。 - 区分
Hovered与Clicked的触发频率:Hovered在悬停期间每帧都会触发,适合做"悬停时更新 tooltip / 高亮"等轻量操作;Clicked只在点击瞬间触发,适合做一次性动作(开窗、复制、执行命令)。 - 善用
Render做每帧动态更新:文本跟随、窗口跟随角色、实时数据显示都应挂在Render上;但注意它每帧执行,内部应只做轻量计算,避免每帧创建大表或进行重 IO。 - 回调参数因元素类型而异:从
PropagateCallbackData的实现可见,同一个ImGuiCallback.Clicked绑在不同类型元素上收到的参数数量和含义不同,编写回调前先确认元素类型。 - 让回调保持"可失败":由于 REPENTOGON 会捕获回调内的错误并打印到控制台,回调内可以放心调用可能失败的 API,配合 docs/docs/ImGui.md 中的函数文档逐步排查。
十、相关参考
- 枚举官方定义:docs/docs/enums/ImGuiCallback.md
ImGui类完整函数文档(含AddCallback/RemoveCallback签名):docs/docs/ImGui.md- Lua 侧枚举镜像定义:repentogon/resources/scripts/enums_ex.lua
- C++ 内部枚举与字符串映射:repentogon/ImGuiFeatures/CustomImGui.h
- 回调触发判定与参数传递实现:repentogon/ImGuiFeatures/CustomImGui.h
- Lua 绑定层实现:repentogon/ImGuiFeatures/LuaImGui.cpp
- 覆盖各回调类型的官方测试脚本:repentogon/resources/scripts/repentogon_tests/test_imgui.lua
- 元素类型枚举
ImGuiElement:docs/docs/enums/ImGuiElement.md