想在Godot里做银河恶魔城？这个插件把最难的地图与存档全包了

【免费下载链接】Metroidvania-SystemGeneral-purpose framework for creating metroidvania games in Godot.项目地址: https://gitcode.com/gh_mirrors/me/Metroidvania-System

你是否想过在 Godot 里做一款银河恶魔城游戏，却被"几十个房间如何串联""玩家探索进度怎么记录""小地图从哪下手"这些现实问题劝退过？Metroidvania-System（以下简称 MetSys）正是为此而生的 Godot 地图编辑器插件——它用一个可视化的网格地图数据库，把房间布局、场景跳转、探索记录、收集物追踪和存档机制打包成一套开箱即用的解决方案。也就是说，你不需要自己从零写房间管理代码，也不用为每个道具手工维护一长串事件标志。它适用于 Godot 4.2 及以上版本，核心代码全部开源，而且各个组件可以独立取用，哪怕你做的不是银河恶魔城，也能从中获益。

一个真实到扎心的场景：开发者的"房间地狱"

假设你正在做一个俯视角探索游戏，已经画好了 20 个房间的场景，然后问题来了：

• 每个房间需要定义四面的边界：哪边是墙，哪边是通道；
• 房间之间要互相知道邻居是谁，切换场景时玩家该出现在哪个坐标；
• 玩家走过哪些区域、捡了哪些道具，全部要存下来，否则一退出游戏就前功尽弃；
• 还想给玩家一张小地图，显示探索过的地方、未收集的道具……

如果手写，你会得到几百行硬编码的坐标数组、状态字典和"if 事件已触发"判断。而 MetSys 把这一整套东西抽象成了几个概念：单元格（Cell）、地图数据（MapData）、主题（MapTheme）和存档数据（SaveData）。接下来我们就沿着"从一张空白地图到跑起来的游戏"这条线，看看每个环节它替你做了什么。

第一站：像画画一样搭世界——地图编辑器的设计思路

MetSys 的地图是基于网格的：整个游戏世界被拆成一个个规则排列的房间格子，就像在坐标纸上画地图。打开插件自带的 Database 编辑器，你就能看到核心的 Map Editor 界面：

这个界面把"设计世界"变成了点几下鼠标的事：

• Room Layout 模式：放置或删除单元格，随意拼出任何网格形状的世界——横版、俯视、不规则结构都行；
• Cell Color / Cell Symbol：给格子涂色、贴符号，用于标记 Boss 房、传送点、存档点等特殊房间；
• Border Type / Border Color：定义每个单元格四边的类型和颜色，也就是房间之间的通道与墙壁；
• Scene Assign 模式：把真实场景文件绑定到房间上，这一步是"地图"与"游戏"结合的桥梁；
• 图层系统：支持多个独立图层，可以做出地下层、平行世界这类结构，还能给图层命名。

你可能会担心："这些配置难道不会变成一堆难维护的二进制数据吗？"恰好相反，MetSys 的地图数据保存在一个为版本控制设计的文本格式中（见MapData.txt，序列化逻辑在addons/MetroidvaniaSystem/Scripts/MapData.gd），体积小、diff 友好，可以放心交给 Git 管理，还支持导出 JSON 与其他工具对接。

第二站：让地图"活"起来——房间与场景如何互相认亲

光有格子图还不够，真正的游戏需要真实场景。MetSys 的做法是给每个房间关联一个.tscn场景，然后你在每个场景里放一个RoomInstance节点（模板场景是addons/MetroidvaniaSystem/Nodes/RoomInstance.tscn）。这个节点的作用非常贴心：

• 编辑器里：它会在 2D 视图中画出当前房间的边界线，哪边是墙、哪边是通道一目了然；
• 邻居预览：如果相邻格子属于另一个场景，编辑器会直接在边界处渲染那个场景的半透明预览图，你甚至可以直接点击预览跳转到对应场景去编辑；
• 运行时代码辅助：它提供了get_neighbor_rooms()（拿到所有相邻房间名，方便预加载）、get_room_position_offset()（算好场景切换后玩家的落点）和adjust_camera_limits()（自动限制相机范围）等方法。

房间切换本身也几乎被封装完了：模板脚本MetSysGame.gd提供load_room()异步加载房间，当RoomInstance进入场景树时自动接管，配合room_changed信号，你只需要处理玩家出生位置这类细节，不用再操心"我该卸载哪个场景、加载哪个场景"。

第三站：存档不再噩梦——每个道具都自动拥有唯一ID

银河恶魔城最"磨人"的工程，是追踪那些"捡了就不会再出现"的东西。常规做法是维护一串事件 ID，比如if not "chest_01_opened" in events。MetSys 把这件事做成了自动化：

每个可存储对象（收集物、开关、可破坏墙壁等）都会被分配一个全局唯一 ID。这个 ID 的生成逻辑在MetroidvaniaSystem.gd的get_object_id()中：优先读取你手动指定的object_id元数据，否则基于"当前场景路径 + 节点路径"自动推导。也就是说，你在场景里摆一个收集物，它天然拥有一个稳定 ID，无需手工配置。

使用方式简洁到只用两个方法：

• register_storable_object(object)：把对象注册为可存储状态，若它之前已被存储，会自动触发回调（默认queue_free()，即不重新生成）；
• store_object(object)：把对象标记为"已取得"，地图上对应的未收集图标会自动变成已收集图标。

结合SaveData.gd的get_data()/set_data()，探索过的格子、存储对象、自定义标记、运行时的格子覆盖统统被打包成一个Dictionary，你只要负责序列化保存即可。示例项目SampleProject/Scripts/Game.gd演示了配合模板SaveManager.gd完成的完整存档读写流程。

第四站：地图的"皮肤"随心换——主题系统里藏着十套现成方案

银河恶魔城游戏各有各的视觉气质，小地图也应该跟游戏风格统一。MetSys 把所有视觉属性集中到一个MapTheme资源（MapTheme.gd）里：单元格中心贴图、四面边界贴图、角落贴图、符号列表、玩家位置标记场景、颜色方案……全部可配。

更棒的是，插件仓库自带了 12 套风格迥异的主题，放在addons/MetroidvaniaSystem/Themes/下：

因为主题是普通Resource，你可以在运行时随时切换，同一张地图在不同区域用不同皮肤也完全可行；单元格还支持正方形 / 长方形两种形态、共享边框模式，以及"房间分隔符"这类细节（在同一房间内画出柔和分格，强化网格感）。编辑器还内置了主题校验工具，能提前发现贴图尺寸不匹配之类的隐患。

第五站：运行时也有魔法——探索追踪、小地图与随机地图

MetSys 不止是个编辑器，它在运行时同样给力，核心入口是名为MetSys的单例：

• 一行代码追踪玩家位置：set_player_position(position)会在玩家跨过格子边界时自动记录探索状态，并发出cell_changed和room_changed信号。可选"整间房间一次点亮"模式，还能控制小地图是"只显示已探索区域"还是"显示见过但未探索的灰色区域"；
• 自动玩家标记：add_player_location()把主题里配好的玩家位置节点放到地图上，支持精确到像素级定位，不可见时自动暂停动画、不浪费性能；
• 收集物全地图可视化：编辑器里可以登记一份"收集物清单"并扫描所有场景，总数一目了然，在地图上以符号展示未收集 / 已收集状态；
• 运行时改地图：通过get_cell_override()可临时改写任意格子的颜色、边框、符号甚至关联场景，还能用MapBuilder创建全新的临时格子——这意味着随机生成地图这件事，MetSys 提供了完整骨架，你只需要写生成算法，不用碰渲染和存档。

第六站：想加自己的功能？插件留好了扩展口

MetSys 在设计上刻意留了几处"插槽"，让高级玩家不费力地加入自定义逻辑：

• 自定义地图元素（CustomElementManager）：地图上要画电梯井、区域名称这类"非格子"元素时，继承CustomElementManager注册一个绘制回调即可。示例项目CustomElements.gd里就有一个画电梯的演示，电梯上下两端都探索过时才会显示——非常有银河战士味；
• 功能模块（MetSysModule）：模板自带了RoomTransitions（房间切换）和PassageAutomapper（通道自动映射）两个模块，用add_module()挂载到MetSysGame上即可。你自己写的模块也能像它们一样，定义自己的保存/加载逻辑，自动并入存档体系。

怎么上手？给新手的行动路线图

从克隆到跑通，推荐按这个顺序来：

1. 克隆并导入：执行git clone https://gitcode.com/gh_mirrors/me/Metroidvania-System，用 Godot 4.2+ 导入项目，两个插件会自动启用（addons/MetroidvaniaSystem/plugin.cfg已在project.godot中注册）；
2. 先跑示例：直接运行项目，主场景是SampleProject/Game.tscn，你马上就能感受到房间切换、小地图、收集物、传送点和存档点这些功能"活"在一起的样子；
3. 读懂示例代码：对照SampleProject/Scripts/Game.gd和模板的MetSysGame.gd，看它如何初始化、加载房间、保存进度；
4. 打开数据库编辑器：通过编辑器菜单打开 Database，把示例地图删掉，从第一格开始画你自己的世界，反复练习"布局 → 设边界 → 关联场景"三步循环；
5. 换主题：依次加载Themes/下的资源，找到最贴合你美术风格的皮。

最后提醒一个新手最容易忽略的细节：MetSys 不会替你把地图数据和玩家状态一起写进磁盘文件——它提供的是格式化的Dictionary和辅助的SaveManager，但"何时存档、何时读档、存到哪个文件"这些流程需要你在游戏里自己编排。好在示例项目已经把一整套标准写法摆在了那里，照着它做，你就能少踩很多坑。

现在，打开编辑器，从第一格房间开始画吧——你的银河恶魔城世界，离跑起来只差一次git clone。

【免费下载链接】Metroidvania-SystemGeneral-purpose framework for creating metroidvania games in Godot.项目地址: https://gitcode.com/gh_mirrors/me/Metroidvania-System