REPENTOGON 的 ImGuiCallback 枚举详解:为 ImGui 界面元素绑定交互回调的完整指南

原创2026-10-15 22:42:58485 阅读
文章标签:游戏开发插件系统

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;
}

这段源码揭示了三条重要的使用规则:

  1. 第二个参数是整数:type 通过 luaL_checkinteger 读取,因此既可以传 ImGuiCallback.Clicked 这种具名常量,也可以直接传数字 0。
  2. 第三个参数必须是函数:如果不是函数,会直接抛出 Lua 错误 Argument 3 is not a function。
  3. 元素必须已存在:如果 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 回调就会执行一次。它适合两类典型用途:

  1. 每帧动态更新文本内容:例如显示实时鼠标坐标、玩家状态、帧率等。
  2. 每帧同步窗口位置:例如让窗口跟随游戏内角色移动。

仓库的测试脚本 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 界面保持稳定运行——这正是模组开发者调试自定义界面时最常用的一条反馈链路。

九、常见陷阱与最佳实践

基于以上源码分析,总结以下几点实战建议:

  1. 先创建元素,再绑定回调:AddCallback 依赖元素已存在,顺序颠倒会直接报 No element '<id>' found.。
  2. 每种回调类型只能绑定一个函数:这是 std::map<IMGUI_CALLBACK, int> 映射结构决定的;如需替换逻辑,直接用新的 AddCallback 覆盖即可。
  3. 区分 Hovered 与 Clicked 的触发频率:Hovered 在悬停期间每帧都会触发,适合做"悬停时更新 tooltip / 高亮"等轻量操作;Clicked 只在点击瞬间触发,适合做一次性动作(开窗、复制、执行命令)。
  4. 善用 Render 做每帧动态更新:文本跟随、窗口跟随角色、实时数据显示都应挂在 Render 上;但注意它每帧执行,内部应只做轻量计算,避免每帧创建大表或进行重 IO。
  5. 回调参数因元素类型而异:从 PropagateCallbackData 的实现可见,同一个 ImGuiCallback.Clicked 绑在不同类型元素上收到的参数数量和含义不同,编写回调前先确认元素类型。
  6. 让回调保持"可失败":由于 REPENTOGON 会捕获回调内的错误并打印到控制台,回调内可以放心调用可能失败的 API,配合 docs/docs/ImGui.md 中的函数文档逐步排查。

十、相关参考

登录后查看全文
REPENTOGON