DimSwap

DimSwap

适用于 NeoForge 的按维度玩家状态隔离模组。
当玩家在可配置的维度组之间切换时，自动保存并恢复背包、末影箱、经验值、药水效果、饥饿值、游戏模式、位置以及 Curios 饰品栏。

构建一个不会泄漏到生存模式的创造测试世界 —— 或是拥有独立进度的硬核区域，亦或是自带专属装备的小游戏维度 —— 完全服务端运行，无需客户端模组，无需数据包修改。

---

为何存在

NeoForge 在 1.21.1 版本中缺少一个维护中的“按维度背包”模组。Fabric/Paper 生态中有此类工具（Multiverse-Inventories、类似 EasyAuth 的插件），但在 NeoForge 上，你只能要么启动第二个服务端进程，要么接受创造模式玩家可能会意外将创造物品带入生存世界。

DimSwap 解决了第二个问题：它监听 EntityTravelToDimensionEvent 在跨维度前原子化保存玩家完整状态，再监听 PlayerChangedDimensionEvent 原子化恢复目标维度组对应的状态。首次进入某个维度组时，状态会被清空，确保不会遗留任何物品。

功能

• 原版状态：主背包 + 护甲 + 副手、末影箱、经验等级、活跃的药水效果、食物、氧气值、火焰燃烧时间、游戏模式、位置
• Curios 饰品栏（可选依赖）：喷气背包、背包、戒指等所有饰品种类均可保存和恢复
• 可配置：选择要交换的领域、维度分组方式、暴露哪些指令
• 原子化与防御机制：失败时防御性地清空状态以防泄漏；基于玩家 NBT 的快照隔离保存
• 自定义别名：定义 /creative 和 /survival（或任意名称）作为一键传送并切换状态的指令
• 管理工具：/dimswap status、/dimswap reset <玩家> <维度组>、/dimswap reload

安装

1. 将 dimswap-X.Y.Z.jar 放入服务端的 mods/ 文件夹。
2. 可选：同时在客户端安装（仅当需要指令在客户端自动补全时需要；游戏玩法仅服务端即可）。
3. 启动服务端一次以生成 config/dimswap.json。
4. 编辑配置文件定义你的维度组（见下文）。
5. 使用 /dimswap reload 重载配置，或重启服务端。

依赖

• 必要：NeoForge 21.1+、Minecraft 1.21.1
• 可选：Curios 9.5+ —— 用于保存和恢复 Curios 饰品栏。未安装 Curios 时，模组仍可处理原版状态。

配置

config/dimswap.json：

{
  "groups": {
    "default":  ["minecraft:overworld", "minecraft:the_nether", "minecraft:the_end"],
    "creative": ["dimswap_creative:flat"]
  },
  "save": {
    "enderChest": true,
    "xp": true,
    "effects": true,
    "food": true,
    "air": true,
    "fire": true,
    "health": false,
    "gamemode": true,
    "position": true,
    "curios": true
  },
  "aliases": [
    {"name": "creative", "dimension": "dimswap_creative:flat", "gamemode": "creative", "permissionLevel": 0},
    {"name": "survival", "dimension": "minecraft:overworld",   "gamemode": "survival", "permissionLevel": 0}
  ]
}

groups

维度组名称到维度 ID 列表的映射。同一组内的维度共享状态。不同组的维度具有隔离的状态。未列出的维度会归入 default 组。

save

控制要交换哪些玩家状态字段。health: false（默认值）使玩家在跨维度时保持当前生命值 —— 若希望每个世界独立管理生命值，可设为 true。

aliases

定义快捷指令。每个别名会注册为顶级指令（例如 /creative），将玩家传送到目标维度并切换为目标游戏模式。permissionLevel: 0 表示所有人都可使用；2 表示仅管理员可用。

注意：别名在服务端启动时注册。添加或移除别名需要重启服务端。groups 和 save 的更改可通过 /dimswap reload 应用。

指令

指令	权限等级	描述
/dimswap go <维度> [游戏模式]	op (2)	传送到指定维度，可选设置游戏模式
/dimswap reload	op (2)	从磁盘重载配置
/dimswap status [玩家]	op (2)	显示某个玩家已保存快照的维度组
/dimswap reset <玩家> <维度组>	op (2)	清除某个玩家在指定维度组的快照
/<别名>	可配置	执行已配置的别名指令（例如 /creative、/survival）

注意事项与已知限制

• 玩家必须是 ServerPlayer —— 不支持仅客户端或仅集成服务端的流程。
• 骑乘实体：当玩家骑乘时跨维度，原版会在传送前将其释放。DimSwap 不保留“骑乘的实体”。
• 除 Curios 外的模组附加内容：如果第三方模组通过自己的数据附件或能力存储玩家状态，DimSwap 无法捕获。欢迎提交 PR 以添加逐个模组的兼容层。
• 位置记忆：仅在保存的维度与目标维度匹配时才会恢复位置（安全性检查）。跨维度传送门旅行时保持一致性。
• 首次访问维度组时始终清空状态 —— 没有为每组定义“初始装备”的概念。如需首次访问装备，请使用单独的套装模组或原版战利品表。

从源码构建

./gradlew build
# 输出: build/libs/dimswap-1.0.0.jar

需要 JDK 21。

许可证

MIT —— 参见 LICENSE。

鸣谢

本模组为一个小型 Create 模组生存服务器而生，该服务器需要一个不会污染背包的创造测试世界。架构故意保持简单：一个保存事件、一个恢复事件、以及基于玩家的 NBT 存储。