REPENTOGON 全局类 ControllerSelectMenu:Lua 读写手柄选择菜单的完整指南
REPENTOGON 全局类 ControllerSelectMenu:Lua 读写手柄选择菜单的完整指南
本文基于 REPENTOGON 仓库的 API 文档 docs/docs/menus/ControllerSelectMenu.md 及其 C++ 实现源码展开,讲解如何通过 ControllerSelectMenu 全局表操作《以撒的结合:忏悔》手柄选择菜单(Controller Select Menu):获取其 ANM2 精灵、读取并设置当前选中的控制器条目。读完本文,你将掌握该类的调用约定(点号而非冒号)、运行前提(仅限主菜单环境)、三个函数的签名与底层内存结构,并能写出安全的 Mod 集成代码。
一、类概述与访问方式
ControllerSelectMenu 是 REPENTOGON 暴露给 Lua 的一个全局类(Global Class),对应游戏主菜单中的“选择手柄”界面——多人开局前由玩家选择本机手柄编号的那块 UI。文档要点如下:
- 通过 Lua 全局表
ControllerSelectMenu获取该类; - 调用函数时必须使用
.(点号),而不是:(冒号),因为这些实现函数在 C++ 侧不是以 self 表为参数调用的,而是直接定位到全局单例菜单; - 文档给出的示例:
local sprite = ControllerSelectMenu.GetSprite()
从源码注册逻辑看,这个全局表确实如此创建:LuaControllerSelectMenu.cpp 中 RegisterControllerSelectMenuGame() 新建一张 Lua 表,把 GetSprite、GetSelectedElement、SetSelectedElement 三个函数写入后,用 lua_setglobal(L, lua::metatables::ControllerSelectMenuMT) 挂到全局,而全局名即 LuaCore.h 中声明的 lua::metatables::ControllerSelectMenuMT。该注册通过 HOOK_METHOD(LuaEngine, RegisterClasses, ...)(LuaControllerSelectMenu.cpp)在引擎初始化阶段注入。
运行前提:只能在主菜单环境调用
三个函数的 Lua 入口第一步都会调用 lua::LuaCheckMainMenuExists(L, lua::metatables::ControllerSelectMenuMT)。其实现位于 LuaCore.cpp:
int LuaCheckMainMenuExists(lua_State* L, const char* className) {
if (g_MenuManager == NULL) { return luaL_error(L, "%s functions can only be used in the main menu", className); }
return 0;
}
也就是说:只要当前不在主菜单(g_MenuManager 为空),任何一次调用都会直接抛出 ControllerSelectMenu functions can only be used in the main menu 错误。写 Mod 时应当在菜单状态下再访问该表,避免在房间更新回调中误触发。
二、API 参考
以下为 ControllerSelectMenu.md 中列出的全部函数,签名保持文档原样:
| 函数 | 签名 | 说明 |
|---|---|---|
GetSprite |
<a href="https://link.gitcode.com/i/4c0167a3aae8f63fbf485c9a0d170aa3" target="_blank">Sprite</a> GetSprite() |
返回手柄选择菜单的 ANM2 动画精灵(以 Sprite 元表包装) |
GetSelectedElement |
int GetSelectedElement() |
返回当前选中的条目索引 |
SetSelectedElement |
void SetSelectedElement(int Element) |
设置选中的条目索引 |
2.1 GetSprite
local sprite = ControllerSelectMenu.GetSprite()
实现位于 LuaControllerSelectMenu.cpp:先通过 g_MenuManager->GetMenuControllerSelect() 拿到 Menu_ControllerSelect 结构体指针,再调用其内联辅助函数 GetControllerSelectSprite() 取出内嵌的 ANM2 ControllerSelectSprite 成员,最终以 SPRITE 元表的 UserdataPtr 压栈返回。因此返回值就是 REPENTOGON 的 Sprite 对象,可以调用 Sprite 类提供的 MoveTo、Show 等方法——常用于在自定义覆盖层中把原生菜单精灵挪走、隐藏或重定位。
2.2 GetSelectedElement / SetSelectedElement
local idx = ControllerSelectMenu.GetSelectedElement()
ControllerSelectMenu.SetSelectedElement(0)
对应实现分别为 LuaControllerSelectMenu.cpp 与 LuaControllerSelectMenu.cpp:前者把 menu->SelectedElement 以整数压栈;后者用 luaL_checkinteger(L, 1) 强转第一个参数后直接写回 menu->SelectedElement。
两个实现细节值得注意:
- 没有范围校验。
SetSelectedElement不做任何 clamp 或合法性判断,写入什么值内存里就是什么值。条目含义(对应几号手柄、菜单共几个可选条目)由游戏菜单自身的 UI 逻辑决定,Mod 写入越界值时行为不由 REPENTOGON 保证,建议只写入与菜单条目一致的合理索引。 - 读写的都是同一份游戏内存。
SelectedElement是Menu_ControllerSelect结构体中的一个int字段(偏移0x4),见下节;写入会即时反映到菜单的选中高亮逻辑中,无需任何"提交"步骤。
三、底层数据结构:Menu_ControllerSelect
REPENTOGON 用 ZHL 结构描述从反汇编中解析出的游戏内存布局,手柄选择菜单的定义在 MenuControllerSelect.zhl:
struct Menu_ControllerSelect depends (ANM2) {
{{
inline ANM2* GetControllerSelectSprite() { return &this->ControllerSelectSprite; }
}}
int HoldInputTimer : 0x0;
int SelectedElement : 0x4;
float PositionX : 0x8;
float PositionY : 0xc;
ANM2 ControllerSelectSprite : 0x10;
} : 0x130;
由此可知该结构体共 0x130 字节,包含:
| 字段 | 偏移 | 类型 | 说明 |
|---|---|---|---|
HoldInputTimer |
0x0 |
int |
输入保持计时器,推测用于输入防抖/连发 |
SelectedElement |
0x4 |
int |
当前选中条目,即 Get/SetSelectedElement 操作的字段 |
PositionX / PositionY |
0x8 / 0xc |
float |
菜单布局位置 |
ControllerSelectSprite |
0x10 |
ANM2 |
菜单动画精灵内嵌对象,GetSprite() 的返回来源 |
ZHL 中的 inline ANM2* GetControllerSelectSprite() 正是 Lua 侧 GetSprite() 所调用的 C++ 内联方法,这条链路把文档 API、Lua 绑定与游戏内存布局完整串了起来。
与 MenuManager 的关系
菜单实例本身是 MenuManager 全局单例的成员。从 MenuManager.zhl 可以看到:
inline Menu_ControllerSelect* GetMenuControllerSelect() {return &this->_menuControllerSelect; }
Menu_ControllerSelect _menuControllerSelect 位于 MenuManager 结构体偏移 0xd114(见 MenuManager.zhl),与 _menuKeyConfig、_menuCutscenes 等十几个菜单子结构并列。全局指针 g_MenuManager 由签名 "c745??ffffffff8bc8a3(????????)e8????????8b0d????????6a01" 定位(MenuManager.zhl)——这正是 LuaCheckMainMenuExists 判空的那个指针:进游戏后菜单系统析构,指针置空,全局表随之不可用。
四、实战示例
一个典型用途是在 Mod 的更新回调中干预手柄选择(例如联机 Mod 里自动预选本机手柄)。参考示例:
local function UpdateCallback()
-- 仅在主菜单状态下访问,避免触发 "can only be used in the main menu" 错误
if Isaac.GetGameState() ~= Isaac.STATE.MENU then return end
local idx = ControllerSelectMenu.GetSelectedElement()
-- 例如:把自己的手柄固定选到 1 号
ControllerSelectMenu.SetSelectedElement(0)
-- 拿到菜单精灵后可以自由操作,比如隐藏或挪动
local sprite = ControllerSelectMenu.GetSprite()
-- sprite:MoveTo(Vector.New(0, 0))
end
Callbacks.Update(UpdateCallback)
要点回顾:
- 使用
ControllerSelectMenu.XXX()点号调用,不要用冒号; - 调用前确保处于主菜单状态,底层依据是
g_MenuManager非空检查(LuaCore.cpp); SetSelectedElement直写内存、无边界保护,写入值需与菜单实际条目相符;GetSprite()返回的是可自由操作的标准Sprite对象,返回的是0x10处内嵌ANM2的引用而非拷贝,对其的修改会即时体现在原生菜单渲染上。
五、参考文件
| 内容 | 路径 |
|---|---|
| 本类 API 文档 | docs/docs/menus/ControllerSelectMenu.md |
| Lua 绑定实现 | repentogon/LuaInterfaces/Menus/LuaControllerSelectMenu.cpp |
| 菜单内存结构(ZHL) | libzhl/functions/MenuControllerSelect.zhl |
| 菜单管理器与全局指针 | libzhl/functions/MenuManager.zhl |
| 主菜单存在性检查 | libzhl/LuaCore.cpp |
| Sprite 类文档 | docs/docs/Sprite.md |