DimSwap
NeoForge 的按维度玩家状态隔离。
当玩家在可配置的维度组之间穿梭时,自动保存和恢复物品栏、末影箱、经验值、药水效果、饥饿度、游戏模式、位置以及 Curios 槽位。
构建一个无法泄漏到生存模式的创造模式测试世界——或者拥有独立进度的硬核区域,又或拥有独立装备库的小游戏维度——完全在服务器端实现,无需客户端模组,也无需数据包黑客操作。
为什么存在这个模组
NeoForge 在 1.21.1 版本中缺乏维护良好的“按维度库存”模组。Fabric/Paper 生态系统中有此类工具(如 Multiverse-Inventories、EasyAuth 相关工具),但在 NeoForge 上,你要么不得不启动第二个服务器进程,要么只能接受创造模式玩家会意外将创造物品掉落至生存世界的事实。
DimSwap 解决了第二种情况:它钩入 EntityTravelToDimensionEvent 以在跨维度前原子性地保存玩家的完整状态,并钩入 PlayerChangedDimensionEvent 以原子性地恢复分配给目标维度组的狀態。首次访问时会进行彻底清理,确保没有任何内容残留。
功能特性
- 原版状态:主物品栏 + 护甲 + 副手、末影箱、经验等级、活跃药水效果、食物、空气量、火焰刻度、游戏模式、位置
- Curios 槽位(可选依赖):喷气背包、背包、戒指等所有 Curios 槽位的保存与恢复
- 可配置:哪些字段需要交换、维度如何分组、暴露哪些命令
- 原子性与防御性:保存/恢复失败时会防御性地清除状态以防止泄漏;每个玩家的 NBT 数据使快照范围限定在个人层面
- 自定义别名:定义
/creative 和 /survival(或任何名称)为一次性传送并切换状态的命令
- 管理工具:
/dimswap status、/dimswap reset <player> <group>、/dimswap reload
安装方法
- 将
dimswap-X.Y.Z.jar 放入服务器的 mods/ 文件夹中。
- 可选:同时放入客户端(仅当你希望命令在客户端侧自动补全时才需要;游戏玩法仅需服务器端即可运行)。
- 启动服务器一次以生成
config/dimswap.json。
- 编辑配置文件以定义你的维度组(见下文)。
- 通过
/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 仅限 OP 使用。
注意:别名在服务器启动时注册。添加/删除别名需要重启服务器。对 groups 和 save 的更改可通过 /dimswap reload 应用。
命令列表
| 命令 |
权限 |
描述 |
/dimswap go <dim> [gamemode] |
op (2) |
传送到指定维度,可选设置游戏模式 |
/dimswap reload |
op (2) |
从磁盘重新加载配置 |
/dimswap status [player] |
op (2) |
显示某玩家有哪些组的已保存快照 |
/dimswap reset <player> <group> |
op (2) |
清除某玩家在某个组的快照 |
/<alias> |
可配置 |
运行已配置的别名(例如 /creative、/survival) |
注意事项与已知限制
- 玩家必须是
ServerPlayer —— 不支持纯客户端/集成服务器流程。
- 骑乘实体:当玩家骑乘实体改变维度时,原版会在传输前使其下车。DimSwap 不会保留“他们当时骑乘的是什么”。
- Curios 之外的模组附加数据:如果第三方模组将其玩家状态存储在其自己的 Data Attachment 或能力中,DimSwap 不会捕获这些数据。欢迎提交 PR 以添加针对特定模组的兼容层。
- 位置记忆:仅在保存的维度与目标维度匹配时才会恢复位置(安全检查)。在交换期间通过传送门进行的跨维度旅行保持一致性。
- 首次访问:对组的每次首次访问都会进行清除——没有按组“起始装备”的概念。请使用单独的 Kit 模组或原版战利品表来处理首次访问装备。
从源码构建
./gradlew build
# 输出: build/libs/dimswap-1.0.0.jar
需要 JDK 21。
许可证
MIT —— 请参阅 LICENSE。
致谢
出于为一个小型 Create-mod 生存服务器创建创意测试世界的需求而开发,该服务器希望在不污染库存的情况下进行测试。架构故意保持简单:一个保存事件、一个恢复事件以及基于每个玩家的 NBT 存储。
DimSwap
Per-dimension player state isolation for NeoForge.
Save and restore inventory, ender chest, XP, potion effects, hunger, gamemode, position, and Curios slots automatically when a player crosses between configurable dimension groups.
Build a creative test world that can't leak into survival — or a hardcore zone with its own progression, or a minigame dimension with its own loadout — entirely server-side, no client mods required, no datapack hacks.
Why this exists
NeoForge has no maintained "per-dimension inventory" mod for 1.21.1. The Fabric/Paper ecosystems do (Multiverse-Inventories, EasyAuth-adjacent tools), but on NeoForge you're stuck either spinning up a second server process or accepting that creative-mode players will accidentally drop creative items into the survival world.
DimSwap solves the second case: it hooks EntityTravelToDimensionEvent to atomically save the player's full state before the cross, and PlayerChangedDimensionEvent to atomically restore the state assigned to the destination's group. First-time visits get a clean wipe so nothing carries over.
Features
- Vanilla state: main inventory + armor + offhand, ender chest, XP levels, active potion effects, food, air supply, fire ticks, gamemode, position
- Curios slots (optional dep): jetpacks, backpacks, rings, all curio slots saved and restored
- Configurable: which fields to swap, how dimensions are grouped, what commands to expose
- Atomic & defensive: failed save/restore wipes state defensively to prevent leaks; per-player NBT keeps snapshots scoped
- Custom aliases: define
/creative and /survival (or any name) as one-shot teleport-and-swap commands
- Admin tools:
/dimswap status, /dimswap reset <player> <group>, /dimswap reload
Installation
- Drop
dimswap-X.Y.Z.jar into your server's mods/ folder.
- Optional: also drop on the client (only required if you want commands to autocomplete client-side; gameplay works server-only).
- Start the server once to generate
config/dimswap.json.
- Edit the config to define your dimension groups (see below).
- Reload with
/dimswap reload or restart the server.
Dependencies
- Required: NeoForge 21.1+, Minecraft 1.21.1
- Optional: Curios 9.5+ — for saving/restoring Curios slots. Without Curios installed, the mod still works for vanilla state.
Configuration
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
A map of group name → list of dimension IDs. Dimensions in the same group share state. Dimensions in different groups have isolated state. Any dimension not listed falls into the default group.
save
Toggles for which player state fields to swap. health: false (default) leaves the player at their current health when crossing — flip to true if you want hardcore-style health-per-world.
aliases
Define shortcut commands. Each alias becomes a top-level command (e.g. /creative) that teleports the player to the target dimension at the target gamemode. permissionLevel: 0 means anyone can use it; 2 is op-only.
Note: aliases are registered at server startup. Adding/removing aliases requires a server restart. Changes to groups and save apply via /dimswap reload.
Commands
| Command |
Permission |
Description |
/dimswap go <dim> [gamemode] |
op (2) |
Teleport to a dimension, optionally set gamemode |
/dimswap reload |
op (2) |
Reload config from disk |
/dimswap status [player] |
op (2) |
Show which groups have saved snapshots for a player |
/dimswap reset <player> <group> |
op (2) |
Wipe a player's snapshot for a group |
/<alias> |
configurable |
Run a configured alias (e.g. /creative, /survival) |
Caveats and known limitations
- Player must be a
ServerPlayer — client-only/integrated-server-only flows are not supported.
- Riding entities: when a player changes dimensions while riding, vanilla dismounts them before the transfer. DimSwap doesn't preserve "what they were riding."
- Mod-added attachments outside Curios: if a third-party mod stores player state in its own Data Attachment or capability, DimSwap does not capture it. PRs welcome to add per-mod compat layers.
- Position memory only restores if the saved-dim matches the destination dim (sanity check). Cross-dim portal travel during a swap stays consistent.
- First visit to a group always wipes — there's no concept of "starting equipment" per group. Use a separate kit mod or vanilla loot table for first-visit gear.
Building from source
./gradlew build
# Output: build/libs/dimswap-1.0.0.jar
Requires JDK 21.
License
MIT — see LICENSE.
Credits
Created out of necessity for a small Create-mod survival server that wanted a creative testing world without inventory contamination. The architecture is intentionally simple: a save event, a restore event, and per-player NBT storage.
评论 0
登录后参与评分
还没有评论,来抢沙发吧