游戏开发插件系统【免费下载链接】REPENTOGONScript extender for The Binding of Isaac: Repentance项目地址https://gitcode.com/gh_mirrors/re/REPENTOGON点击查看免费下载本文面向 The Binding of Isaac: Repentance 的模组开发者系统讲解 REPENTOGON 脚本扩展器对GridEntityDoor网格实体门这一 Lua 类所做的全部改动。读完你将掌握PreviousState与PreviousVariant两个由 userdata 修正为整数的读写变量、GetExtraSprite()与PlayAnimation()两个新增函数以及它们背后的源码实现、相关门渲染/更新回调与门槽位DoorSlot/DoorMask联动用法。一、GridEntityDoor 是什么GridEntityDoor是 GridEntity 的派生类对应游戏网格中的门实体房间入口、出口、隐藏门等。在 REPENTOGON 中它被挂接到独立的 Lua metatableGRID_ENTITY_DOOR并在 LuaClasses.h 中通过LuaGridEntityDoor LuabridgeTypeGridEntity_Door, ...导出到 Lua 环境。原版 API 对门的控制能力有限门的关键内部状态变化前的状态暴露给 Lua 时是不透明的 userdata模组无法直接读取或写回同时缺少对附加精灵ExtraSprite与动画播放的原生访问接口。REPENTOGON 在 docs/docs/GridEntityDoor.md 中记录了两类修复Modified Variables修改变量与Functions新增函数。二、PreviousState / PreviousVariant从 userdata 修正为整数这是本文档最重要的改动。原版中GridEntityDoor.PreviousState与PreviousVariant返回的是 userdata指向内部结构模组拿不到可用的数值REPENTOGON 将其修复为返回真正的整数int并且支持读写。变量类型说明PreviousStateint与默认行为相同但现在返回正确的整数值而非 userdataPreviousVariantint与默认行为相同但现在返回正确的整数值而非 userdata重要更新时机根据 docs/docs/GridEntityDoor.md 的注记这两个字段只在初始化门的子类initializing a door subclass或播放动画playing an animation时才会被更新。也就是说门的前一个 State / 前一个 Variant并不在每次状态变更时都刷新模组若依赖这两个字段做状态机判断需要结合门的动画播放时机来理解其语义。底层实现验证修复由 LuaGridEntityDoor.cpp 完成两个RegisterVariable注册了 getter/setter读操作直接lua_pushinteger返回gridEnt-_previousState/gridEnt-_previousVariant均为unsigned int写操作通过luaL_checkinteger接收整数并回写lua::RegisterVariable(_state, lua::Metatables::GRID_ENTITY_DOOR, PreviousState, Lua_GridEntityDoor_GetPreviousState, Lua_GridEntityDoor_SetPreviousState); lua::RegisterVariable(_state, lua::Metatables::GRID_ENTITY_DOOR, PreviousVariant, Lua_GridEntityDoor_GetPreviousVarinat, Lua_GridEntityDoor_SetPreviousVariant);对应的内存布局在 GridEntityDoor.zhl 中定义_previousState位于偏移0x284、_previousVariant位于偏移0x288uint32_t。因为 getter/setter 直通原生字段Lua 侧读写即原生侧读写可用于检测门的类型/变体切换例如普通门与隐藏门之间的形态变化。三、GetExtraSprite()以函数形式访问附加精灵原版门对象持有变量ExtraSprite附加精灵例如门框装饰、谜题门特效但 REPENTOGON 以getter 函数GetExtraSprite()的方式暴露它---return Sprite local sprite door:GetExtraSprite()返回类型为 Sprite。实现上LuaGridEntityDoor.cpp 直接取出结构体偏移0x168处的ANM2 _extraSprite并作为 Sprite userdata 压栈返回因此你可以对返回的 Sprite 继续调用SetFrame、Play、ReplaceSpritesheet等常规 Sprite API实现自定义门的附加贴图与动画。四、PlayAnimation()播放门的动画door:PlayAnimation()该函数没有参数、没有返回值void用于主动播放门对象的动画。LuaGridEntityDoor.cpp 中的实现直接调用原生方法gridEnt-play_animation()LUA_FUNCTION(Lua_GridEntityDoor_PlayAnimation) { GridEntity_Door* gridEnt lua::GetLuabridgeUserdataGridEntity_Door*(L, 1, lua::Metatables::GRID_ENTITY_DOOR, GridEntityDoor); gridEnt-play_animation(); return 0; }play_animation()是游戏原生函数在 GridEntityDoor.zhl 中通过__thiscall签名定位。注意前面提到的PreviousState/PreviousVariant刷新时机之一就是播放动画所以调用PlayAnimation()后这两个字段会被重新计算模组可以在播放前后分别读取借此捕获门动画切换带来的形态变化。五、与门相关的回调GridEntity Door callbacks门是 REPENTOGON 网格渲染/更新回调体系的一等公民。在 CustomCallbacks.cpp 中GridEntity_Door的Render被挂接了HOOK_GRIDRENDER_CALLBACKS对应两个回调 ID在 CustomCallbacks.cpp 中Update被挂接了HOOK_GRIDUPDATE_CALLBACKS回调 ID名称参数返回1446MC_PRE_GRID_ENTITY_DOOR_RENDER(GridEntityDoor Door, Vector Offset)Vector或boolean1447MC_POST_GRID_ENTITY_DOOR_RENDER(GridEntityDoor Door)void1402MC_PRE_GRID_ENTITY_DOOR_UPDATE(GridEntityDoor Door)boolean1403MC_POST_GRID_ENTITY_DOOR_UPDATE(GridEntityDoor Door)void以上参数/返回信息来自 ModCallbacks 枚举文档。PRE 回调返回Vector可改写渲染偏移返回booleanfalse可取消默认渲染UPDATE 的 PRE 回调返回boolean可决定是否跳过原生更新逻辑。示例mod:AddCallback(ModCallbacks.MC_PRE_GRID_ENTITY_DOOR_UPDATE, function(_, door) if door.Variant SomeDoorVariant then return false -- 跳过原生日志执行自定义逻辑 end end)六、结合 DoorSlot / DoorMask 与门放置逻辑的实际应用要写出门相关的模组逻辑通常还需要理解门的槽位概念。门的槽位DoorSlot取值为 0~7左/上/右/下加上第二轮LEFT1/UP1/RIGHT1/DOWN1每个槽位对应一个位掩码定义在 DoorMask 枚举文档中值枚举值枚举1 0LEFT01 4LEFT11 1UP01 5UP11 2RIGHT01 6RIGHT11 3DOWN01 7DOWN1Lua 侧的同名枚举在 enums_ex.lua 中以1 DoorSlot.LEFT0的形式定义。C 侧 RoomPlacement.h 提供了DoorSlotToMask(doorSlot) 1 doorSlot的等价转换。实战把门补进现有房间Level 文档 给出了一段完整可用的示例遍历当前房间 0~7 的每个门槽位用位掩码判断该槽位是否允许放门roomDesc.Data.Doors (1 doorSlot) ~ 0若当前没有门not room:GetDoor(doorSlot)则随机生成一个 1x1 房间并通过TryPlaceRoomAtDoor把连接门补上mod:AddCallback(ModCallbacks.MC_USE_ITEM, function(_, id, rng, player, flags, slot) local level game:GetLevel() local room game:GetRoom() local roomDesc level:GetCurrentRoomDesc() local success false for doorSlot 0, 7 do local doorSlotAllowed roomDesc.Data.Doors (1 doorSlot) ~ 0 if doorSlotAllowed and not room:GetDoor(doorSlot) then local seed rng:Next() local requiredDoors 15 -- 要求新房间 4 个槽位都有门确保放得下 local roomConfig RoomConfig.GetRandomRoom(seed, true, Isaac.GetCurrentStageConfigId(), RoomType.ROOM_DEFAULT, RoomShape.ROOMSHAPE_1x1, nil, nil, nil, nil, requiredDoors) if roomConfig then local newRoom level:TryPlaceRoomAtDoor(roomConfig, roomDesc, doorSlot, seed, true, false) if newRoom then success true end end end end if success then return {ShowAnim true} else return {Discharge false} end end, MY_ACTIVE_ITEM_ID)这段代码在门生成成功后返回{ShowAnimtrue}播放门的动画——恰好对应本文第四节PlayAnimation()所触发的原生动画路径。底层门是如何被实体化的从源码结构可以推断门的生成由房间放置系统驱动。在 RoomPlacement.cpp 中当新房间与玩家当前房间相邻时通过currentRoom-MakeDoor(returnDoorSlot)创建门实体随后写入目标房间索引door-_targetRoomIdx、调用SetRoomTypes(CurrentRoomType, TargetRoomType)设置两侧房间类型并在房间帧数大于 0 时调用door-play_animation()播放开门动画currentRoom-MakeDoor(returnDoorSlot); GridEntity_Door* door currentRoom-GetDoor(returnDoorSlot); if (door) { door-_targetRoomIdx roomDesc-SafeGridIndex; door-SetRoomTypes(neighborDesc-Data-Type, roomDesc-Data-Type); if (currentRoom-GetFrameCount() 0) { door-play_animation(); } }GetDoor(slot)的原生签名__thiscall GridEntity_Door* Room::GetDoor(int slot)定义在 Room.zhl 中这与上面 Lua 示例里的room:GetDoor(doorSlot)一一对应。从这段实现可以看出SetRoomTypes与play_animation是门实例化过程中的关键步骤而_previousState/_previousVariant正是在这类初始化与动画播放的路径上被刷新。七、使用注意事项小结类型语义PreviousState/PreviousVariant现在是int不要再对它们做 userdata 解包setter 仅接受整数。更新时机这两个字段只在门子类初始化或播放动画时更新跨帧持续读取时值可能不变不应将其当作实时状态量。ExtraSprite 是共享引用GetExtraSprite()返回的是门对象内部的ANM2 _extraSprite引用偏移0x168修改它会直接影响门自身的附加精灵渲染谨慎用于全局替换。回调与放置联动门的渲染/更新回调1446/1447、1402/1403与DoorMask位掩码、TryPlaceRoomAtDoor等放置 API 配合使用可以做出动态开新门自定义门动画门不可见/不可通行等玩法效果。参考路径汇总类文档docs/docs/GridEntityDoor.md门枚举docs/docs/enums/DoorMask.md回调枚举docs/docs/enums/ModCallbacks.md门 Lua 绑定实现repentogon/LuaInterfaces/GridEntities/LuaGridEntityDoor.cpp门原生结构体与函数定位libzhl/functions/GridEntityDoor.zhl门渲染/更新回调挂接repentogon/LuaInterfaces/CustomCallbacks.cpp房间门生成逻辑repentogon/LuaInterfaces/Room/RoomPlacement.cppLua 侧 DoorMask 枚举repentogon/resources/scripts/enums_ex.lua赞分享游戏开发插件系统【免费下载链接】REPENTOGONScript extender for The Binding of Isaac: Repentance项目地址https://gitcode.com/gh_mirrors/re/REPENTOGON点击查看免费下载相关推荐REPENTOGON 扩展 API 实战指南EntityBomb 炸弹实体类完整解析REPENTOGON 扩展 API 实战指南EntityBomb 炸弹实体类完整解析 导读 本文聚焦 REPENTOGON 为《以撒的结合忏悔》Lua Mo游戏开发插件系统REPENTOGON Lua API 扩展全览800 新函数、200 新回调与 60 新枚举的文档导航与实践指南REPENTOGON Lua API 扩展全览800 新函数、200 新回调与 60 新枚举的文档导航与实践指南 本文面向《以撒的结合忏悔》The游戏开发插件系统如何 5 分钟给小爱音箱免费装上无限曲库XiaoMusic Docker 部署与语音点播指南如何 5 分钟给小爱音箱免费装上无限曲库XiaoMusic Docker 部署与语音点播指南 XiaoMusic 是一款开源音乐工具它接管小爱音箱的语音点播游戏开发插件系统上一篇Sunshine打造个人游戏串流服务器的终极指南下一篇Sunshine游戏串流完整指南5分钟搭建免费个人云游戏平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考