🌌 Custom Dimensions: The Multiverse Engine

Custom Dimensions is a fully server-side Fabric mod that lets server administrators create custom dimensions, define physical portal frames, and connect worlds with persistent two-way gateways.

Players can join with an unmodified vanilla client—only the server needs the mod and Fabric API.

🎮 Supported Minecraft versions

• Minecraft 1.21 through 1.21.11
• Minecraft 26.1 through 26.1.2
• Minecraft 26.2

Use the JAR made for your Minecraft version. All releases use Fabric Loader.

✨ Features

🌍 Create custom dimensions

Create void, Overworld-style, Nether-style, or End-style dimensions directly from the server. The mod writes the datapack definition and creates the dimension folder immediately.

A full server restart is required after creation so Minecraft can load the new dimension into the live world registry.

🔄 Persistent two-way portals

The first time a player enters an activated portal, the mod:

1. Finds or creates a safe destination portal.
2. Creates a safety platform when necessary.
3. Gives both physical portals unique UUIDs.
4. Stores a reciprocal link between the source and destination.
5. Uses that exact portal pair for return travel.

After arriving, step completely out of the destination portal, wait for the configured cooldown, and enter it again to return. The cooldown prevents the player from instantly bouncing between dimensions while still standing inside the portal.

Portal pairs are saved per world and survive server restarts.

🧱 Flexible physical frames

• Build an empty vertical rectangular frame from the configured frame block.
• The default allowed interior is 2×3 through 21×21 blocks.
• The top, bottom, left side, and right side must be complete.
• The four corner blocks are optional.
• Use the configured igniter on any frame block.
• Frames may face either the X or Z direction.

One portal definition can activate multiple physical frames. Every activated frame receives its own UUID and its own reciprocal destination portal.

📐 Coordinate scaling

Each portal definition supports a coordinate multiplier from 0.001 through 1000.0.

• 1.0 keeps the same coordinates.
• 0.125 converts Overworld coordinates to Nether-style 1:8 coordinates.
• 8.0 performs the inverse conversion.

The generated return portal automatically uses the inverse scale.

🌈 Server-side particles

Active portal interiors are filled with colored vanilla dust particles. The particle color comes from the RGB value supplied to /portal link.

Particle density, interval, and spread are configurable. Because particles are sent by the server, players do not need a client mod.

⌨️ Live command suggestions

TAB completion includes:

• Registered block IDs
• Registered item IDs
• Every dimension currently loaded by the server
• Dimensions supplied by vanilla, datapacks, other mods, and Custom Dimensions

🛠️ Enhance your server setup! Check out my other server-side mods over at : Fabric Server Essentials

🛠️ Commands

Command Description /dimension create <name> <void|overworld|nether|end> Creates a dimension definition and its folder /portal link <id> <frame_block> <igniter_item> <target_dimension> <RRGGBB> <light_level> [scale] Creates or updates a portal definition /portal activate <id> <x> <y> <z> Activates a completed frame from the console or command line /portal list Lists saved portal definitions /portal instances Lists activated physical portals and their linked UUIDs /portal delete <id> Deletes a definition and deactivates its physical portals

/dimension create

/dimension create <name> <void|overworld|nether|end>

Example:

/dimension create pvp_arena void

This creates customdimensions:pvp_arena. Restart the server before using it as a portal target.

/portal link

/portal link <id> <frame_block> <igniter_item> <target_dimension> <RRGGBB> <light_level> [scale] Argument Meaning Example id Unique definition name arena_gate frame_block Namespaced frame block ID minecraft:obsidian igniter_item Namespaced item ID used to ignite it minecraft:flint_and_steel target_dimension Loaded destination dimension customdimensions:pvp_arena RRGGBB Six-digit particle color FF0000 light_level Saved portal light value from 0–15 15 scale Optional coordinate multiplier; default 1.0 0.125

Example:

/portal link arena_gate minecraft:obsidian minecraft:flint_and_steel customdimensions:pvp_arena FF0000 15 1.0

Then build the matching frame and use flint and steel on any frame block.

If several definitions use the same frame block and igniter, physical ignition selects the alphabetically first definition. Use /portal activate when you need to select a specific definition.

⚙️ Server configuration

The mod generates:

config/custom_dimensions.json

Default configuration:

{ "schemaVersion": 1, "commandPermissionLevel": 4, "portalIgnitionPermissionLevel": 0, "particlesPerSample": 8, "particleIntervalTicks": 5, "particleSpread": 0.32, "frameDetectionRange": 21, "frameValidationIntervalTicks": 40, "portalCooldownTicks": 80, "destinationSearchRadius": 16 }

Configuration options

Setting Range Usage schemaVersion 1 Configuration format version; do not change commandPermissionLevel 0–4 Required operator level for /dimension and /portal commands portalIgnitionPermissionLevel 0–4 Required operator level to ignite a frame physically particlesPerSample 1–32 Number of server particles emitted for each sampled portal cell particleIntervalTicks 1–20 Delay between particle bursts; lower values update more often particleSpread 0.0–1.0 Random particle spread around each sampled position frameDetectionRange 3–32 Maximum detected portal interior width and height frameValidationIntervalTicks 20–1200 How often active frames are checked for broken blocks portalCooldownTicks 0–600 Delay before the same player can teleport again; 20 ticks = 1 second destinationSearchRadius 0–128 Radius used to find or place a reusable destination portal

Permission level 0 allows everyone. Permission level 4 requires a server owner or operator level 4.

Restart the server after editing this file. Invalid configuration files are backed up and replaced with safe defaults.

💾 Data files

File Purpose config/custom_dimensions.json Server permissions, particles, frame detection, cooldown, and placement settings config/portal_links.json Portal definitions created with /portal link world/data/custom_dimensions_portals.json Activated physical portal UUIDs and reciprocal source/destination links

Use the commands to manage portal definitions. Manual edits to portal_links.json or the per-world portal-instance file are not recommended while the server is running.

🧪 Examples

🔴 PvP arena

/dimension create pvp_arena void

Restart the server, then run:

/portal link arena_gate minecraft:obsidian minecraft:flint_and_steel customdimensions:pvp_arena FF0000 15 1.0

🟢 Resource world with Nether-style scaling

/dimension create resource_world overworld

Restart the server, then run:

/portal link resource_gate minecraft:iron_block minecraft:stick customdimensions:resource_world 00FF00 10 0.125

🟣 Purple gateway to the Nether

/portal link nether_gate minecraft:crying_obsidian minecraft:amethyst_shard minecraft:the_nether A020F0 15 0.125

📦 Installation

1. Install the correct Fabric Loader version for your server.
2. Install the matching Fabric API.
3. Put the correct Custom Dimensions JAR in the server's mods/ folder.
4. Start the server once to generate the configuration files.
5. Create a dimension, restart the server, define a portal, and build its frame.

Only install one Custom Dimensions JAR. Use the build matching your exact Minecraft version.

🧊 Notes

• The mod is server-side; vanilla clients can connect.
• A newly created dimension requires one full server restart before portal use.
• The portal interior must be empty when activated.
• Breaking a required frame block deactivates that physical portal.
• To use the return side, leave the portal interior and re-enter after the cooldown.