REPENTOGON 全局类 ControllerSelectMenu:Lua 读写手柄选择菜单的完整指南

原创2026-10-15 10:38:001,607 阅读
文章标签:游戏开发插件系统

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。

两个实现细节值得注意:

  1. 没有范围校验。SetSelectedElement 不做任何 clamp 或合法性判断,写入什么值内存里就是什么值。条目含义(对应几号手柄、菜单共几个可选条目)由游戏菜单自身的 UI 逻辑决定,Mod 写入越界值时行为不由 REPENTOGON 保证,建议只写入与菜单条目一致的合理索引。
  2. 读写的都是同一份游戏内存。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
登录后查看全文
REPENTOGON