Custom Dimensions

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: 1.21 through 1.21.11, 26.1 through 26.1.2, 26.2, and 26.3. Use the JAR made for your exact Minecraft version. All releases use Fabric Loader, not NeoForge.

What the mod does

• Creates 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.
• Provides persistent two-way portals. The first time a player enters an activated portal, the mod finds or creates a safe destination portal, creates a safety platform when necessary, gives both physical portals unique UUIDs, stores a reciprocal link between source and destination, and reuses 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 instant bouncing while still standing inside the portal. Portal pairs are saved per world and survive server restarts.
• Supports flexible physical frames. Build an empty vertical rectangular frame from the configured frame block. The default allowed interior is 2x3 through 21x21 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, and every activated frame receives its own UUID and reciprocal destination.
• Supports per-portal coordinate scaling from 0.001 through 1000.0. A scale of 1.0 keeps the same coordinates, 0.125 converts Overworld coordinates to Nether-style 1:8 coordinates, and 8.0 performs the inverse conversion. The generated return portal automatically uses the inverse scale.
• Emits colored server-side dust particles inside active portal interiors. 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.
• Offers live command suggestions with TAB completion for registered block IDs, registered item IDs, every dimension currently loaded by the server, and dimensions supplied by vanilla, datapacks, other mods, and Custom Dimensions.
• Validates portal frames on a schedule and deactivates physical portals whose frame blocks were broken.

Commands

Command	Description
/dimension create <name> <void|overworld|nether|end>	Creates a dimension definition and its folder, then requires a server restart
/dimension list	Shows every dimension currently loaded by the server, marking custom ones
/dimension help	Shows dimension command help with examples
/portal link <id> <frame_block> <igniter_item> <target_dimension> <RRGGBB> <light_level> [scale]	Creates or updates a portal definition
/portal info <id>	Shows target, frame, igniter, color, light level, scale, and active instance count for one definition
/portal list	Lists all saved portal definitions with their targets and settings
/portal instances	Lists activated physical portals with their UUIDs, dimensions, and linked portal UUIDs
/portal activate <id> <x> <y> <z>	Activates a completed frame from the console or command line
/portal delete <id>	Deletes a definition and deactivates its physical portals
/portal help	Shows portal command help with usage and examples

/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	Description
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 equals 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 and 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 mods folder. Use the build matching your exact Minecraft version and install only one Custom Dimensions JAR.
4. Start the server once to generate the configuration files.
5. Create a dimension, restart the server, define a portal, and build its frame.

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.
• Version 1.3.0 adds Minecraft 26.3 support, new /dimension list, /dimension help, /portal info, and /portal help commands, clearer colored command output, and detailed multi-line listings for definitions and instances.