Alternate Realities

Alternative Realities

Alternative Realities gives server owners control over what players carry between dimensions.

Dimensions can share one player inventory or behave as completely separate realities. Inventories, equipment, experience, Ender Chests, accessories, and first-entry commands can all follow the player’s current dimension group.

Health, hunger, status effects, burning, and developer-defined player attributes can also be saved and restored for each dimension group.

By default, every dimension belongs to the normal group. Install the mod and play normally, or separate individual dimensions through the generated configuration.

Compatibility

Alternative Realities currently supports Forge on Minecraft 1.20.1; Fabric on 1.20.1, 1.21.1, 26.1, 26.2, and 26.3; and NeoForge on 1.21.1, 1.21.11, 26.1.2, 26.2, and 26.3.

Fabric uses one JAR for Minecraft 26.1, 26.2, and 26.3. NeoForge uses one JAR for Minecraft 26.1.2, 26.2, and 26.3. Seven JARs cover all eleven supported loader and Minecraft combinations, with separate files for the 1.20.1, 1.21.1, and 1.21.11 targets.

Fabric installations require Fabric API.

Curios and Trinkets are optional. When present, supported accessory slots are saved as part of each dimension group.

Getting Started

Install the correct file for your Minecraft version and mod loader, then start the server once.

Alternative Realities creates these files in the server’s config folder:

alternative-realities.toml

alternative-realities-dimensions.toml

The main file controls global behavior. The dimensions file controls dimension groups and first-entry commands.

The dimensions file also supports per-dimension player attribute selections through a [player_attributes] section.

If every dimension should share the same inventory, no changes are required. All detected dimensions use the normal group automatically.

After editing either file, restart the server or run:

/altreal reload

Creating Dimension Groups

Dimensions with the same group name share player state.

This configuration keeps the Overworld, Nether, End, and a custom orbit dimension together:

[dimension_groups]

“minecraft:overworld” = “normal”

“minecraft:the_nether” = “normal”

“minecraft:the_end” = “normal”

“example:orbit” = “normal”

To give a dimension its own inventory, assign it a different group:

[dimension_groups]

“minecraft:overworld” = “normal”

“minecraft:the_nether” = “normal”

“minecraft:the_end” = “normal”

“example:moon” = “moon”

Players entering example:moon use the moon inventory group. Returning to a dimension in the normal group restores their normal inventory.

Several dimensions can share a custom group:

[dimension_groups]

“example:moon” = “space”

“example:mars” = “space”

“example:station” = “space”

All three dimensions share the space player state.

Explicit server configuration always takes priority over automatic settings supplied by another mod.

What Changes Between Groups

Alternative Realities stores the player’s main inventory, hotbar, armor, offhand equipment, experience, and supported accessories for each group.

Ender Chests can either remain global like vanilla Minecraft or be stored separately for each group.

Dropped items and mobs can be prevented from traveling between dimensions. Projectile blocking is also available when stricter separation is needed.

Player data is written safely with backup recovery. Interrupted dimension changes are detected and recovered without discarding the source inventory.

Health, Hunger, Status Effects, and Burning

Each of these features can be enabled or disabled independently in alternative-realities.toml:

[player_state]

group_specific_health = true

group_specific_hunger = true

group_specific_status_effects = true

group_specific_fire = true

The example above enables all four options. Group-specific health, hunger, and status effects are disabled by default. Group-specific burning is enabled by default.

Health saving includes absorption. Hunger saving includes food level, saturation, exhaustion, and the regeneration or starvation timer.

Status effects retain their duration, strength, visibility settings, and hidden weaker effects. Saved effect durations pause while their group is inactive.

Burning is saved as each group’s remaining fire timer. Entering a new group clears burning, and returning restores that group’s own saved timer. The timer pauses while the group is inactive. Moving between dimensions in the same group preserves the current fire state.

Server owners can also select built-in or registered custom player attributes for specific dimensions. Dimensions sharing a group share the selected player state. Global player-state options still apply to every group when enabled.

First-Entry Commands

Commands can run when a player enters a group for the first time.

[entry_commands]

“normal” = []

“space” = [

“give @s minecraft:bread 16”,

“give @s minecraft:stone_pickaxe”

]

“default” = []

Do not include a leading slash.

{player} inserts the player’s name.

{uuid} inserts the player’s UUID.

{group} inserts the destination group.

{dimension} inserts the destination dimension ID.

Commands can run once or on every entry. The main configuration also controls operator permission and whether player state is saved immediately afterward.

Death and Respawning

Dying clears the carried inventory and accessories stored for the active group.

Ender Chest contents remain intact. Experience follows the configured experience setting. If the player respawns in another dimension group, Alternative Realities loads that group instead of restoring items from the dimension where the death occurred.

When health, hunger, status effects, or burning are localized, respawning in another group restores that destination group’s saved values, including partial health or hunger and its own effects or fire timer.

The enabled player state stored for the group where the player died resets to first-visit defaults. New groups start with full health, 20 food, 5 saturation, zero exhaustion, no effects, and no burning for the selected built-in attributes.

Living-player respawns, including returns from the End, also preserve the source group and restore the destination group correctly.

Commands

/altreal help displays the available commands.

/altreal list displays the current dimension, current group, saved groups, and first-entry status.

/altreal reload reloads both configuration files.

/altreal save saves the player’s current group.

/altreal restore restores the saved state for the current group.

/altreal reset_kits resets the player’s first-entry markers.

/altreal run_kit manually runs the current group’s entry commands.

/altreal group <dimension> <group> assigns or reassigns a dimension to a group.

/altreal group list displays the loaded dimension groups.

/altreal group reset <dimension> restores the dimension’s default group.

/altreal config list displays the available boolean configuration options.

/altreal config get <option> displays an option’s current value.

/altreal config set <option> <true|false> changes an option immediately and saves it to the configuration file.

For example, /altreal config set player_state.group_specific_health true enables group-specific health saving. The same command supports player_state.group_specific_hunger, player_state.group_specific_status_effects, and player_state.group_specific_fire.

Dimension-group commands accept bare or quoted dimension IDs and can reassign dimensions that already belong to a group. Quote group names that contain spaces. Group and configuration commands include autocomplete.

/altreal skyblock enter opens the isolated skyblock test dimension and teleports the player onto its safety island.

/altreal skyblock leave returns the player to the dimension and coordinates where the test began.

The island’s chunks load before teleporting. Repeated visits preserve player-built blocks. These commands are available to operators for checking group separation.

Integration for Dimension Developers

Dimension developers can request a separate default group without requiring server owners to edit their Alternative Realities configuration.

Create this file in the dimension mod:

data/alternative_realities/tags/dimension/separate_group.json

{

“replace”: false,

“values”: [

“example:moon”

]

}

Code-driven registration is also supported:

AlternativeRealitiesApi.registerSeparateGroup(“example:moon”);

Several dimensions can be assigned to the same default group:

AlternativeRealitiesApi.registerDimensionGroup(“example:moon”, “space”);

AlternativeRealitiesApi.registerDimensionGroup(“example:mars”, “space”);

Registrations should occur during mod initialization before the server starts. Server configuration remains authoritative and can override developer defaults.

Player Attribute Integration

Dimension developers can select built-in player attributes for their dimensions:

AlternativeRealitiesApi.registerDimensionAttributes(“example:moon”, java.util.List.of(

AlternativeRealitiesApi.HEALTH,

AlternativeRealitiesApi.HUNGER,

AlternativeRealitiesApi.STATUS_EFFECTS,

AlternativeRealitiesApi.FIRE

));

Custom player state can be registered under a namespaced identifier:

AlternativeRealitiesApi.registerPlayerAttribute(“example:mana”, yourAttributeHandler);

yourAttributeHandler is an implementation of PlayerAttributeHandler. Its capture method saves the attribute as a string, restore applies its saved value, and reset establishes its first-visit and post-death default. Handlers run on the server thread and must synchronize their own client state when needed.

Registered custom identifiers can be included in registerDimensionAttributes alongside the built-in attributes.

Attribute selections do not assign an inventory group. Use registerSeparateGroup or registerDimensionGroup when a dimension also needs its own group. Dimensions sharing a group use the combined attribute selections of those dimensions. Outside selected groups, custom attributes use a shared value.

Server owners can override a developer’s selections in alternative-realities-dimensions.toml:

[player_attributes]

“example:moon” = [“alternative_realities:health”, “alternative_realities:hunger”, “example:mana”]

The example:mana attribute requires a registered handler from an installed mod. Explicit server lists override developer attribute selections; globally enabled built-in player-state options continue to apply.

 

Planned Features

Configurable attribute defaults

Configuration support for defining default player attributes in each dimension or group without relying on first-entry commands. This may include health, movement speed, attack attributes, hunger, saturation, flight, and other player properties.

Complete feature control

Configuration support for enabling or disabling individual Alternative Realities features at will. Inventory, armor, offhand equipment, experience, Ender Chests, accessories, travel restrictions, death handling, and entry commands will be independently configurable.

Expanded modding API

Planned API additions include attribute profiles, entry behavior, and other defaults for dimensions.

Per-group rules

Per-group configuration for separating inventory, equipment, experience, Ender Chests, and accessories independently.

Datapack profiles

Reusable dimension profiles that modpack developers can define and distribute through datapacks.

Administration and recovery tools

Improved commands for inspecting, resetting, migrating, exporting, and repairing individual player groups.

Additional compatibility

More integration hooks for custom inventories, equipment systems, accessory providers, and other player-data mods.