REPENTOGON ChallengeMenu 全局类解析:挑战菜单 Lua 接口的调用方式与源码实现
REPENTOGON ChallengeMenu 全局类解析:挑战菜单 Lua 接口的调用方式与源码实现
本篇指南围绕 REPENTOGON(《以撒的结合:忏悔》脚本扩展)提供的 ChallengeMenu 全局类展开,系统讲解其三个公开 Lua 函数(GetSprite、GetSelectedChallengeID、SetSelectedChallengeID)的签名、用法与底层实现。读完你将掌握在主菜单挑战界面下通过 Lua 读取当前选中挑战、操控菜单精灵的完整方案,并能结合原生结构 Menu_Challenge 与渲染钩子理解其运行机制。
ChallengeMenu 是什么
ChallengeMenu 是 REPENTOGON 向 Lua 脚本暴露的全局类(Global Class),对应游戏主菜单中的挑战选择界面(Challenge Menu)。它的身份是一个全局表(global table),而非对象实例,因此文档与源码均强调:
调用其函数必须使用 .(句点)而不是 :(冒号)!
-- 正确写法:使用句点
local sprite = ChallengeMenu.GetSprite()
-- 错误写法:冒号会被当作方法调用,在全局表上会失败
-- local sprite = ChallengeMenu:GetSprite()
从注册流程看,这个全局表是在 LuaEngine::RegisterClasses 钩子回调中,由 RegisterChallengeMenuGame 通过 lua_setglobal(L, lua::metatables::ChallengeMenuMT) 挂载到 Lua 全局环境的(见 LuaChallengeMenu.cpp),也就是说它随 REPENTOGON 的 Lua 引擎初始化而自动可用,无需 mod 手动 require。
函数总览
ChallengeMenu 共暴露 3 个函数,全部为无参或有单参的轻量读写接口:
| 函数 | 签名 | 返回类型 | 作用 |
|---|---|---|---|
GetSprite |
GetSprite() |
Sprite | 获取挑战菜单的 ANM2 精灵对象 |
GetSelectedChallengeID |
GetSelectedChallengeID() |
int |
获取当前选中的挑战 ID |
SetSelectedChallengeID |
SetSelectedChallengeID(int ChallengeID) |
void |
将菜单选中项切换到指定挑战 ID |
下面逐一结合源码展开。
GetSprite:获取挑战菜单精灵
签名: Sprite GetSprite()
该函数返回挑战菜单当前使用的 Sprite(ANM2 精灵)。典型用法是配合 Sprite 类 API 做自定义渲染、读取菜单动画帧或叠加 mod 自己的 UI。
对应实现见 LuaChallengeMenu.cpp:
LUA_FUNCTION(Lua_ChallengeMenu_GetChallengeMenuSprite)
{
lua::LuaCheckMainMenuExists(L, lua::metatables::ChallengeMenuMT);
Menu_Challenge* menu = g_MenuManager->GetMenuChallenge();
ANM2* anm2 = menu->GetChallengeMenuSprite();
lua::luabridge::UserdataPtr::push(L, anm2, lua::GetMetatableKey(lua::Metatables::SPRITE));
return 1;
}
关键点:
- 通过
g_MenuManager->GetMenuChallenge()取到原生菜单对象Menu_Challenge*; GetChallengeMenuSprite()直接返回结构内嵌ANM2 ChallengeMenuSprite字段的指针(见 MenuChallenge.zhl);- 该指针以 SPRITE 元表(
Metatables::SPRITE)压栈,因此在 Lua 侧表现为一个完整的 Sprite 对象,可调用 Sprite 的既有方法(如Play、Update、Render、GetFrame等)。
注意生命周期: 返回的是原生 ANM2 的指针封装,并非复制品——它指向挑战菜单实际正在使用的精灵。若你在菜单渲染帧中修改它的层状态,会直接影响屏幕上可见的菜单画面。
GetSelectedChallengeID:读取当前选中挑战
签名: int GetSelectedChallengeID()
返回挑战列表中当前高亮选中的挑战 ID。实现极其简洁(LuaChallengeMenu.cpp):
LUA_FUNCTION(Lua_ChallengeMenu_GetSelectedChallengeID)
{
lua::LuaCheckMainMenuExists(L, lua::metatables::ChallengeMenuMT);
Menu_Challenge* menu = g_MenuManager->GetMenuChallenge();
lua_pushinteger(L, menu->SelectedChallengeID);
return 1;
}
即直接读取原生结构成员 SelectedChallengeID。从 MenuChallenge.zhl 可知它是位于偏移 0x4 的 int 字段,紧随其后的是 HoldInputTimer(偏移 0x8,方向键连按的输入节流计时器)。
这个 ID 在渲染中的实际作用
在 ChallengesStuff.cpp 中,REPENTOGON 挂钩了 Menu_Challenge::Render,用该字段驱动挑战列表的滚动动画:
HOOK_METHOD(Menu_Challenge, Render, () -> void) {
LayerState* frame = this->ChallengeMenuSprite.GetLayer(26);
LayerState* frame2 = this->ChallengeMenuSprite.GetLayer(27);
LayerState* frame3 = this->ChallengeMenuSprite.GetLayer(28);
int sel = this->SelectedChallengeID;
float targetyoffset = 0;
if (sel > 4) { targetyoffset = (float)((sel - 4) * 22); }
frame->_pos.y = lerp(frame->_pos.y, targetyoffset, 0.05f);
frame2->_pos.y = frame->_pos.y;
frame3->_pos.y = frame->_pos.y;
super();
}
也就是说:当选中 ID 大于 4 时,列表会以每项 22 像素的步进向上偏移,并通过 lerp(插值因子 0.05)做平滑过渡。因此对 SelectedChallengeID 的写入,会直接影响挑战列表的可视滚动位置——这为 mod 提供了"程序化翻页/定位挑战"的能力。
SetSelectedChallengeID:切换选中挑战
签名: void SetSelectedChallengeID(int ChallengeID)
将挑战菜单的选中项设置为指定 ID,返回空。实现(LuaChallengeMenu.cpp):
LUA_FUNCTION(Lua_ChallengeMenu_SetSelectedChallengeID)
{
lua::LuaCheckMainMenuExists(L, lua::metatables::ChallengeMenuMT);
Menu_Challenge* menu = g_MenuManager->GetMenuChallenge();
menu->SelectedChallengeID = (int)luaL_checkinteger(L, 1);
return 0;
}
要点:
- 入参经过
luaL_checkinteger严格校验,非整数会触发 Lua 类型错误; - 赋值直接写回原生字段
SelectedChallengeID,随后Menu_Challenge::Render钩子会在下一帧据此重算滚动偏移(见上文),实现平滑定位; - 该接口与
GetSelectedChallengeID互为读写对,是 mod 实现"记住上次选中的挑战""按键直达指定挑战"等交互的入口。
完整示例
-- 读取当前选中挑战
local currentID = ChallengeMenu.GetSelectedChallengeID()
print("Currently selected challenge: " .. currentID)
-- 切换到指定挑战(例如 ID 为 5 的挑战)
ChallengeMenu.SetSelectedChallengeID(5)
-- 获取菜单精灵并驱动其动画
local sprite = ChallengeMenu.GetSprite()
if sprite ~= nil then
sprite:Play("Idle", true)
end
背后的原生结构:Menu_Challenge
所有三个函数最终都作用于同一个原生结构 Menu_Challenge,其内存布局由 ZHL 声明(MenuChallenge.zhl):
| 成员 | 偏移 | 类型 | 说明 |
|---|---|---|---|
SelectedChallengeID |
0x4 |
int |
当前选中的挑战 ID |
HoldInputTimer |
0x8 |
int |
方向键按住时的连选计时器 |
PositionX |
0xc |
float |
菜单位置 X |
PositionY |
0x10 |
float |
菜单位置 Y |
ChallengeMenuSprite |
0x14 |
ANM2 |
菜单使用的 ANM2 精灵 |
| (对齐填充) | 0x128 |
char[8] |
未知保留字段 |
| 结构总大小 | 0x130 |
— | — |
同时该文件给出了原生渲染入口的签名:__thiscall void Menu_Challenge::Render()。REPENTOGON 正是通过 HookSystem 拦截此函数(见 ChallengesStuff.cpp),在调用 super() 之前改写 3 个层的 Y 坐标来实现列表滚动。
与 CustomChallengeMenu 及自定义挑战系统的联动
值得说明的是,REPENTOGON 还提供平行的 CustomChallengeMenu 全局类,对应原生类 Menu_CustomChallenge,二者 API 形状完全一致(同为 GetSprite / GetSelectedChallengeID / SetSelectedChallengeID,实现见 LuaCustomChallengeMenu.cpp)。区别在于:
ChallengeMenu对应主菜单的标准挑战标签页;CustomChallengeMenu对应自定义挑战标签页,其选中项存储于Menu_CustomChallenge::SelectedElement。
从 ChallengesStuff.cpp 的实现看,自定义挑战列表的可见项(visiblechallenges)会遍历 XMLStuff.ChallengeData 中 ID 从 46 起的挑战条目,并依据 XML 中的 hidden 属性与 achievements 解锁条件过滤、锁定;而 ID 1–45 的原生挑战仍走游戏原生路径。Manager::StartNewGame 的钩子(同文件第 161–175 行)则在自定义挑战菜单(_selectedMenuID == 15)下把 SelectedElement 映射为真实挑战 ID 后再启动游戏。
此外,挑战菜单的渲染钩子(ChallengesStuff.cpp)会以 g_MenuManager->GetMenuChallenge()->ChallengeMenuSprite 为模板复制一份 Streak 精灵(加载 gfx/ui/challengesmenustuff.anm2),在已完成的挑战行尾绘制连胜标记——这意味着 ChallengeMenu.GetSprite() 返回的精灵同样承载着这一渲染链路所依赖的基础画面。
使用注意事项
- 仅限主菜单状态调用:每个函数入口都先执行
lua::LuaCheckMainMenuExists(L, ...)检查。从命名与所有菜单类(MenuManager、CharacterMenu、DailyChallengeMenu等,见 LuaMenuManager.cpp)的相同调用模式可以推断:若游戏当前不在主菜单状态(例如处于局内),调用会抛出错误。因此请将相关逻辑限定在菜单阶段(如MC_PRE_MAIN_MENU等回调)内使用。 - 句点调用:
ChallengeMenu是全局表而非实例,必须用.调用其函数,否则 Lua 会把第一个实参(表自身)误当作参数传入。 - 返回值引用语义:
GetSprite返回的是原生ANM2的指针封装,不是深拷贝,修改它会直接影响真实菜单画面。 - ID 语义:
SelectedChallengeID对应挑战数据表中的 ID(1–45 为原生挑战,46 起为自定义/Mod 挑战),并非列表序号;写入超出范围的 ID 不会做边界钳制,需自行保证有效性。
以上三点接口配合原生结构 Menu_Challenge 与 ChallengesStuff.cpp 中的渲染、启动钩子,构成了 REPENTOGON 挑战菜单在 Lua 侧完整的可编程入口,适用于自定义挑战选择 UI、挑战速选、连胜展示等 Mod 场景。