DimSwap

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

1. Drop dimswap-X.Y.Z.jar into your server's mods/ folder.
2. Optional: also drop on the client (only required if you want commands to autocomplete client-side; gameplay works server-only).
3. Start the server once to generate config/dimswap.json.
4. Edit the config to define your dimension groups (see below).
5. 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

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.