DynamicDimensions

Library to facilitate the runtime addition and removal of Minecraft dimensions.

Adding DynamicDimensions to your project

Add the Galacticraft maven to your project

repositories {
    maven {
        url = "https://maven.galacticraft.net/repository/maven-releases"
    }
}

Then add the appropriate dependency:

Fabric

dependencies {
    modImplementation("dev.galacticraft.dynamicdimensions-fabric:$dyndims")
}

NeoForge

dependencies {
    implementation("dev.galacticraft.dynamicdimensions-neoforge:$dyndims")
}

Multiplatform

// Common
dependencies {
    compileOnly("dev.galacticraft.dynamicdimensions-common:$dyndims")
}

// Fabric
dependencies {
    modRuntimeOnly("dev.galacticraft.dynamicdimensions-fabric:$dyndims")
}

// NeoForge
dependencies {
    runtimeOnly("dev.galacticraft.dynamicdimensions-neoforge:$dyndims")
}

Using the API

All APIs dealing with the addition and removal of dynamic dimensions go through the dev.galacticraft.dynamicdimensions.api.DynamicDimensionRegistry class.

To obtain an instance, simply call DynamicDimensionRegistry#from(MinecraftServer)

Note that this library does not keep track of what dynamic dimensions have been created when the server restarts. You will need to track this yourself and then load the dimension again.

Creating a new dimension (overwrites level data)

Call DynamicDimensionRegistry::createDynamicDimension with the ID of your dimension, a chunk generator, and a dimension type.

ChunkGenerator generator;
DimensionType type;

// ... initialize chunk generator and dimension type ...

DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
ServerLevel level = registry.createDynamicDimension(ResourceLocation.fromNamespaceAndPath("mymod", "dynamic"), generator, type);

if (level == null) {
    // failed to create level
} else { /*...*/ }

This will create a new dimension with the given ID, discarding data from any previous dimensions with the same ID. If you want world data to be loaded, see the next section .

Caveats

• createDynamicDimension will delete all previous dimension data.
• The DimensionType and ID of your dimension cannot already be in use.
• There may be a one-tick delay before the dimension is registered with the server.

Loading a dimension (reads or creates new level data)

Call DynamicDimensionRegistry::loadDynamicDimension with the ID of your dimension, a chunk generator, and a dimension type.

ChunkGenerator generator;
DimensionType type;

// ... initialize chunk generator and dimension type ...

DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
ServerLevel level = registry.loadDynamicDimension(ResourceLocation.fromNamespaceAndPath("mymod", "dynamic"), generator, type);

if (level == null) {
    // failed to create level
} else { /*...*/ }

This will create a dimension with the given ID, loading previous region/level data from disk.

Caveats

• The DimensionType and ID of your dimension cannot already be in use.
• There may be a one-tick delay before the dimension is registered with the server.

Unloading a dimension

Call DynamicDimensionRegistry::unloadDynamicDimension with the ID of your dimension and (optionally) a callback to move connected players off-world.

DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
registry.unloadDynamicDimension(ResourceLocation.fromNamespaceAndPath("mymod", "dynamic"), null);

The dimension will be saved to disk before being unloaded. You can use loadDynamicDimension to create the dimension again (loading the same world data).

Caveats

• There may be a one-tick delay before the dimension is removed from the server.

Deleting a dimension

Call DynamicDimensionRegistry::deleteDynamicDimension with the ID of your dimension and (optionally) a callback to move connected players off-world.

DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
registry.deleteDynamicDimension(ResourceLocation.fromNamespaceAndPath("mymod", "dynamic"), null);

The dimension will be unloaded, then all the dimension files will be deleted.

Caveats

• There may be a one-tick delay before the dimension is removed from the server.
• Once deleted, dimension files are not recoverable