• 游戏开发
• 插件系统

导读

TitleMenu是 REPENTOGON 暴露给 Lua 模组的全局类，用于从脚本侧访问游戏主菜单中"标题画面（Title Screen）"背后的Sprite对象。本文将围绕其唯一公开方法GetSprite()，完整讲解调用约定、返回类型、从 Lua 到 C++ 的底层调用链（涉及Menu_Title结构体与MenuManager），并结合仓库源码给出可实际运行的标题画面定制示例，帮助模组作者理解并善用这一菜单扩展能力。

类概览：通过TitleMenu全局表访问

根据 docs/docs/menus/TitleMenu.md 的定义，TitleMenu是一个Global Class（全局类），模组脚本可以直接使用TitleMenu这个全局表来获取它，无需实例化。

一个关键的调用约定需要特别注意：调用该类下的所有函数时必须使用.（点号）而不是:（冒号），即：

local sprite = TitleMenu.GetSprite() -- 正确：使用点号 -- local sprite = TitleMenu:GetSprite() -- 错误：冒号调用会传入多余的 self 参数

这与 REPENTOGON 中其他全局菜单类（如MenuManager、MainMenu，见 docs/docs/menus/MenuManager.md 与 docs/docs/menus/MainMenu.md）保持一致，属于 REPENTOGON 菜单 API 的统一风格。

核心函数：GetSprite()

TitleMenu类目前仅公开一个函数：

GetSprite ()

Sprite GetSprite()

• 返回值：一个 Sprite 对象，即标题画面当前正在使用的 ANM2 精灵实例。
• 官方示例（摘自原文档）：

local sprite = TitleMenu.GetSprite()

拿到该 Sprite 后，就可以调用 docs/docs/Sprite.md 中记载的任意 Sprite 方法对其进行读写，例如GetAnimation()、SetFrame()、GetAllLayers()、GetLayer()、GetRenderFlags()等，实现对标题画面视觉元素的控制。

底层原理：从 Lua 到 C++ 的完整调用链

GetSprite()虽然只有一行调用，但其背后是一条清晰的 C++ 实现链路。全部实现位于 repentogon/LuaInterfaces/Menus/LuaTitleMenu.cpp，关键代码如下（第 5–18 行）：

LUA_FUNCTION(Lua_TitleMenuTitleScreenSprite) { lua::LuaCheckMainMenuExists(L, lua::metatables::TitleMenuMT); Menu_Title* menu = g_MenuManager->GetMenuTitle(); ANM2* anm2 = menu->GetTitleScreenSprite(); lua::luabridge::UserdataPtr::push(L, anm2, lua::GetMetatableKey(lua::Metatables::SPRITE)); return 1; } static void RegisterTitleMenuGame(lua_State* L) { lua_newtable(L); lua::TableAssoc(L, "GetSprite", Lua_TitleMenuTitleScreenSprite); lua_setglobal(L, lua::metatables::TitleMenuMT); }

该调用链可以拆解为四步：

1. 注册全局表：RegisterTitleMenuGame创建一个新 Lua 表，把GetSprite键绑定到Lua_TitleMenuTitleScreenSprite函数，并通过lua_setglobal注册为名为TitleMenu的全局变量。TitleMenuMT这个元表键名定义在 libzhl/LuaCore.h（值为"TitleMenu"，见 libzhl/LuaCore.cpp）。整个注册过程挂接在LuaEngine::RegisterClasses钩子中（第 21–25 行），随 REPENTOGON 的 Lua 引擎初始化一并执行。

2. 主菜单存在性校验：LuaCheckMainMenuExists(L, "TitleMenu")检查全局g_MenuManager是否为NULL。如果为NULL，会直接抛出 Lua 错误"TitleMenu functions can only be used in the main menu"。该辅助函数的实现见 libzhl/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; }

也就是说，这些函数只能在主菜单状态下调用——这也是官方文档在类说明中强调限制条件的原因。

3. 获取Menu_Title实例：g_MenuManager->GetMenuTitle()从全局菜单管理器取出标题菜单对象。GetMenuTitle()的声明在 libzhl/functions/MenuManager.zhl，它返回Menu_Title*，实际是对MenuManager内部成员_menuTitle（偏移0x1d4）取地址：

inline Menu_Title* GetMenuTitle() {return &this->_menuTitle; }

4. 取出标题画面 Sprite 并推送到 Lua：menu->GetTitleScreenSprite()返回ANM2*，随后通过lua::luabridge::UserdataPtr::push以SPRITE元表包装后压入 Lua 栈，最终作为函数的返回值返回给脚本。Menu_Title的结构定义在 libzhl/functions/MenuTitle.zhl（第 7–14 行）：

struct Menu_Title depends (ANM2) { inline ANM2* GetTitleScreenSprite() { return &this->TitleScreenSprite; } float PositionX : 0x0; float PositionY : 0x4; ANM2 TitleScreenSprite : 0x8; } : 0x124;

从该结构可以推断：Menu_Title在内存中保存了标题画面的屏幕坐标（PositionX/PositionY）以及一个内嵌的ANM2精灵TitleScreenSprite，GetTitleScreenSprite()只是返回其地址，因此Lua 侧拿到的 Sprite 是游戏内部对象的直接引用，而非副本——对它的修改会立即反映到游戏标题画面上。

实战：定制标题画面的完整示例

将TitleMenu.GetSprite()与 REPENTOGON 提供的 Sprite API 结合，即可在标题画面绘制阶段插入自定义逻辑。一个常用的配合是MC_MAIN_MENU_RENDER回调——其 ID 为 1023，定义见 docs/docs/enums/ModCallbacks.md，在主菜单渲染时被调用，且不接受返回值。

-- 读取标题画面的当前动画与关键属性 local function onMainMenuRender() if not TitleMenu then return end local sprite = TitleMenu.GetSprite() if not sprite then return end local anim = sprite:GetAnimation() local frame = sprite:GetFrame() -- 可以在此处根据标题动画推进自定义特效、修改图层或叠加渲染 end mod:AddCallback(ModCallbacks.MC_MAIN_MENU_RENDER, onMainMenuRender)

需要注意：MC_MAIN_MENU_RENDER在标题画面的实际渲染回调（Menu_Title::Render，见 libzhl/functions/MenuTitle.zhl，为__thiscall签名）流程中触发，是控制标题画面视觉表现最自然的时机。

此外，TitleMenu只是 REPENTOGON 主菜单 API 体系中的一环。若要判断当前主菜单正处于哪个分区，可结合 MenuManager 的GetActiveMenu()与 MainMenuType 枚举（TITLE = 1，注意注释说明0存在但不可用）；而MainMenu.GetGameMenuSprite()（见 docs/docs/menus/MainMenu.md）则用于访问主菜单中"游戏菜单"分区（即所有子菜单所在的实际菜单）的 Sprite，与TitleMenu分工不同。

注意事项与最佳实践

1. 只能在主菜单调用：LuaCheckMainMenuExists会在g_MenuManager == NULL（不在主菜单状态）时抛出运行时错误。在模组中应先通过MenuManager.IsActive()（见 docs/docs/menus/MenuManager.md）或在MC_MAIN_MENU_RENDER回调内调用，以确保时机安全。
2. 必须使用点号调用：TitleMenu.GetSprite()，不要写成TitleMenu:GetSprite()，否则会传入多余的参数导致错误。
3. 返回的是内部对象的引用：从 libzhl/functions/MenuTitle.zhl 的结构定义可以确认，Lua 侧拿到的是Menu_Title::TitleScreenSprite的直接指针，操作会直接影响游戏标题画面；建议在回调内获取并短周期使用，避免长期持有影响对象生命周期。
4. 结合 Sprite API 使用：获取到 Sprite 后，GetAnimation()、SetFrame()、GetLayer()、GetRenderFlags()等 docs/docs/Sprite.md 中记载的方法均可直接调用，且该页面还记录了 REPENTOGON 对 Sprite 构造器与ReplaceSpritesheet()、Stop()等方法的扩展，为深度定制提供了更丰富的手段。
5. 与菜单系统的关系：标题画面只是MainMenuType.TITLE分区；REPENTOGON 的菜单扩展还包括 MenuManager（如SetActiveMenu、SetInputMask、SetColorModifier）以及 MainMenu 等全局类，组合使用可以构建完整的自定义主菜单体验。从 changelog 记录（changelog.txt）可以看到，菜单相关能力（如Isaac.StartNewGame、输入掩码等）是 REPENTOGON 持续维护的模块。

结束

• 游戏开发
• 插件系统