REPENTOGON ChallengeMenu 全局类解析:挑战菜单 Lua 接口的调用方式与源码实现

原创2026-10-15 13:36:221,891 阅读
文章标签:游戏开发插件系统

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() 返回的精灵同样承载着这一渲染链路所依赖的基础画面。

使用注意事项

  1. 仅限主菜单状态调用:每个函数入口都先执行 lua::LuaCheckMainMenuExists(L, ...) 检查。从命名与所有菜单类(MenuManager、CharacterMenu、DailyChallengeMenu 等,见 LuaMenuManager.cpp)的相同调用模式可以推断:若游戏当前不在主菜单状态(例如处于局内),调用会抛出错误。因此请将相关逻辑限定在菜单阶段(如 MC_PRE_MAIN_MENU 等回调)内使用。
  2. 句点调用:ChallengeMenu 是全局表而非实例,必须用 . 调用其函数,否则 Lua 会把第一个实参(表自身)误当作参数传入。
  3. 返回值引用语义:GetSprite 返回的是原生 ANM2 的指针封装,不是深拷贝,修改它会直接影响真实菜单画面。
  4. ID 语义:SelectedChallengeID 对应挑战数据表中的 ID(1–45 为原生挑战,46 起为自定义/Mod 挑战),并非列表序号;写入超出范围的 ID 不会做边界钳制,需自行保证有效性。

以上三点接口配合原生结构 Menu_Challenge 与 ChallengesStuff.cpp 中的渲染、启动钩子,构成了 REPENTOGON 挑战菜单在 Lua 侧完整的可编程入口,适用于自定义挑战选择 UI、挑战速选、连胜展示等 Mod 场景。

登录后查看全文
REPENTOGON