chore: improve project documentation

* rename some methods to be more intuitive
* bump version to 0.7
* remove some config options
  * should be decided by library users instead

Author: marcus8448

README.md

@@ -1,2 +1,142 @@
 # DynamicDimensions
-Library to facilitate the runtime addition and removal of minecraft dimensions.
+Library to facilitate the runtime addition and removal of Minecraft dimensions.
+
+## Adding DynamicDimensions to your project
+Add the Galacticraft maven to your project
+```groovy
+repositories {
+    maven {
+        url = "https://maven.galacticraft.net/repository/maven-releases"
+    }
+}
+```
+
+Then add the appropriate dependency:
+### Fabric
+```groovy
+dependencies {
+    modImplementation("dev.galacticraft.dynamicdimensions-fabric:$dynDims")
+}
+```
+
+### NeoForge
+```groovy
+dependencies {
+    implementation(fg.deobf("dev.galacticraft.dynamicdimensions-neoforge:$dynDims"))
+}
+```
+
+### Multiplatform
+```groovy
+// Common
+dependencies {
+    implementation("dev.galacticraft.dynamicdimensions-common:$dynDims")
+}
+// Fabric
+dependencies {
+    modRuntimeOnly("dev.galacticraft.dynamicdimensions-fabric:$dynDims")
+}
+
+// NeoForge
+dependencies {
+    runtimeOnly(fg.deobf("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](#loading-a-dimension-reads-or-creates-new-level-data)
+again.
+
+### Creating a *new* dimension (overwrites level data)
+Call 
+`DynamicDimensionRegistry::createDynamicDimension`
+with the ID of your dimension, a chunk generator, and a dimension type.
+
+```java
+ChunkGenerator generator;
+DimensionType type;
+
+// ... initialize chunk generator and dimension type ...
+
+DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
+ServerLevel level = registry.createDynamicDimension(new ResourceLocation("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](#loading-a-dimension-reads-or-creates-new-level-data)
+.
+
+#### 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.
+```java
+ChunkGenerator generator;
+DimensionType type;
+
+// ... initialize chunk generator and dimension type ...
+
+DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
+ServerLevel level = registry.loadDynamicDimension(new ResourceLocation("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.
+```java
+DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
+registry.unloadDynamicDimension(new ResourceLocation("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.
+```java
+DynamicDimensionRegistry registry = DynamicDimensionRegistry.from(server);
+registry.deleteDynamicDimension(new ResourceLocation("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

build.gradle.kts

@@ -1,8 +1,8 @@
 plugins {
-    id("org.ajoberstar.grgit.service") version ("5.2.1")
+    id("org.ajoberstar.grgit.service") version("5.2.1")
     id("org.cadixdev.licenser") version("0.6.1") apply(false)
-    id("fabric-loom") version ("1.5-SNAPSHOT") apply (false)
-    id("org.jetbrains.gradle.plugin.idea-ext") version ("1.1.7") // required for neoforge
+    id("fabric-loom") version("1.5-SNAPSHOT") apply(false)
+    id("org.jetbrains.gradle.plugin.idea-ext") version("1.1.7") // required for neoforge
 }
 
 val minecraft = project.property("minecraft.version").toString()

common/src/main/java/dev/galacticraft/dynamicdimensions/api/DynamicDimensionRegistry.java

@@ -24,6 +24,7 @@
 
 import net.minecraft.resources.ResourceLocation;
 import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerLevel;
 import net.minecraft.world.level.chunk.ChunkGenerator;
 import net.minecraft.world.level.dimension.DimensionType;
 import org.jetbrains.annotations.Contract;
@@ -35,7 +36,7 @@
  * It is not possible to access the registry from the client.
  *
  * @since 0.1.0
- * @see #from(MinecraftServer) to get an instance.
+ * @see #from(MinecraftServer)
  */
 public interface DynamicDimensionRegistry {
     /**
@@ -69,8 +70,8 @@ public interface DynamicDimensionRegistry {
     /**
      * Returns whether a level and dimension with the given ID can be deleted.
      *
-     * @param id The ID of the level/dimension.
-     * @return {@code true} if the level and dimension are dynamic and can be deleted, {@code false} otherwise.
+     * @param id The ID of the dimension.
+     * @return {@code true} if the dimension is dynamic and can be deleted, {@code false} otherwise.
      * @since 0.1.0
      */
     boolean canDeleteDimension(@NotNull ResourceLocation id);
@@ -79,48 +80,63 @@ public interface DynamicDimensionRegistry {
      * Returns whether a level and dimension with the given ID can be created.
      *
      * @param id The ID of the level/dimension.
-     * @return {@code true} if the level and dimension are dynamic and can be created, {@code false} otherwise.
+     * @return {@code true} if a dynamic dimension can be created with the given id, {@code false} otherwise.
      * @since 0.6.0
      */
     boolean canCreateDimension(@NotNull ResourceLocation id);
 
     /**
      * Registers a new dimension and updates all clients with the new dimension.
-     * If world data already exists for this dimension it may be deleted
-     * NOTE: The dimension may not be loaded until the next tick.
+     * If world data already exists for this dimension it will be overwritten.
      *
      * @param chunkGenerator The chunk generator.
      * @param id             The ID of the dimension.
      *                       This ID must be unique and unused in the {@link net.minecraft.core.registries.Registries#DIMENSION_TYPE} registry and the {@link net.minecraft.world.level.levelgen.WorldDimensions#dimensions()} registry.
      * @param type           The dimension type.
-     * @return whether a dimension with the given id was created
+     * @return the server level of the new dimension if successful, {@code null} otherwise.
+     * @see #loadDynamicDimension(ResourceLocation, ChunkGenerator, DimensionType) if you want to load previous data
+     * @implNote The dimension may not be loaded until the next tick.
      * @since 0.6.0
      */
-    boolean createDynamicDimension(@NotNull ResourceLocation id, @NotNull ChunkGenerator chunkGenerator, @NotNull DimensionType type);
+    @Nullable ServerLevel createDynamicDimension(@NotNull ResourceLocation id, @NotNull ChunkGenerator chunkGenerator, @NotNull DimensionType type);
 
     /**
      * Registers a new dimension and updates all clients with the new dimension.
-     * If world data already exists for this dimension it will be used, otherwise it will be generated
-     * NOTE: The dimension will not be loaded until the next tick.
+     * If world data already exists for this dimension it will be used, otherwise it will be created.
      *
      * @param chunkGenerator The chunk generator.
      * @param id             The ID of the dimension.
-     *                       This ID must be unique and unused in the {@link net.minecraft.core.registries.Registries#DIMENSION_TYPE} registry and the {@link net.minecraft.world.level.levelgen.WorldDimensions#dimensions()} registry.
+     *                       This ID must be unique and unused in the {@link net.minecraft.core.registries.Registries#DIMENSION_TYPE dimension type} registry
+     *                       and the {@link net.minecraft.world.level.levelgen.WorldDimensions#dimensions() dimensions} registry.
      * @param type           The dimension type.
-     * @return whether a dimension with the given id was created
+     * @return the server level of the new dimension if successful, {@code null} otherwise.
+     * @implNote The dimension may not be loaded until the next tick.
      * @since 0.6.0
      */
-    boolean loadDynamicDimension(@NotNull ResourceLocation id, @NotNull ChunkGenerator chunkGenerator, @NotNull DimensionType type);
+    @Nullable ServerLevel loadDynamicDimension(@NotNull ResourceLocation id, @NotNull ChunkGenerator chunkGenerator, @NotNull DimensionType type);
 
     /**
-     * Removes a dynamic dimension from the server.
+     * Deletes a dynamic dimension from the server.
      * This may delete the dimension files permanently.
-     * Players will be removed from the dimension using the provided player remover.
+     * Remaining players will be removed from the dimension using the provided player remover.
      *
      * @param id      The ID of the dimension.
      * @param remover The method to remove players from the dimension.
-     * @return whether a dimension with the given id was removed
-     * @since 0.1.0
+     * @return whether a dimension with the given id was deleted
+     * @implNote The dimension may not be deleted until the next tick.
+     * @since 0.7.0
+     */
+    boolean deleteDynamicDimension(@NotNull ResourceLocation id, @Nullable PlayerRemover remover);
+
+    /**
+     * Removes a dynamic dimension from the server, saving the level to disk.
+     * Remaining players will be removed from the dimension using the provided player remover.
+     *
+     * @param id      The ID of the dimension.
+     * @param remover The method to remove players from the dimension.
+     * @return whether a dimension with the given id was unloaded
+     * @implNote The dimension may not be unloaded until the next tick.
+     * @since 0.7.0
      */
-    boolean removeDynamicDimension(@NotNull ResourceLocation id, @Nullable PlayerRemover remover);
+    boolean unloadDynamicDimension(@NotNull ResourceLocation id, @Nullable PlayerRemover remover);
 }

common/src/main/java/dev/galacticraft/dynamicdimensions/api/PlayerRemover.java

@@ -22,14 +22,40 @@
 
 package dev.galacticraft.dynamicdimensions.api;
 
+import net.minecraft.core.BlockPos;
+import net.minecraft.network.chat.Component;
 import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.level.storage.LevelData;
 
 /**
  * Removes players from a {@link net.minecraft.world.level.Level}.
  */
 @FunctionalInterface
 public interface PlayerRemover {
+    /**
+     * Attempts to bring players to their personal spawn point, otherwise to the default (overworld) spawn point.
+     */
+    PlayerRemover DEFAULT = (server, player) -> {
+        player.sendSystemMessage(Component.translatable("command.dynamicdimensions.delete.removed", player.serverLevel().dimension().location()), true);
+        ServerLevel level = server.getLevel(player.getRespawnDimension());
+        if (level != null && level != player.serverLevel()) {
+            BlockPos pos = player.getRespawnPosition();
+            if (pos != null) {
+                player.teleportTo(level, pos.getX() + 0.5, pos.getY(), pos.getZ() + 0.5, player.getYRot(), player.getXRot());
+            } else {
+                LevelData levelData = level.getLevelData();
+                player.teleportTo(level, levelData.getXSpawn() + 0.5, levelData.getYSpawn(), levelData.getZSpawn() + 0.5, player.getYRot(), player.getXRot());
+            }
+        } else {
+            level = server.overworld();
+            LevelData levelData = level.getLevelData();
+            player.teleportTo(level, levelData.getXSpawn() + 0.5, levelData.getYSpawn(), levelData.getZSpawn() + 0.5, player.getYRot(), player.getXRot());
+        }
+        player.setDeltaMovement(0.0, 0.0, 0.0);
+    };
+
     /**
      * Called when a player must be removed from the level.
      * May cause unexpected behaviour if the player is not actually removed from the level.

common/src/main/java/dev/galacticraft/dynamicdimensions/impl/Constants.java

@@ -33,6 +33,6 @@ public interface Constants {
     Logger LOGGER = LoggerFactory.getLogger(MOD_ID);
     DynamicDimensionsConfig CONFIG = Services.PLATFORM.getConfig();
 
-    ResourceLocation CREATE_WORLD_PACKET = new ResourceLocation(MOD_ID, "create_world");
-    ResourceLocation DELETE_WORLD_PACKET = new ResourceLocation(MOD_ID, "delete_world");
+    ResourceLocation CREATE_DIMENSION_PACKET = new ResourceLocation(MOD_ID, "create_dimension");
+    ResourceLocation REMOVE_DIMENSION_PACKET = new ResourceLocation(MOD_ID, "remove_dimension");
 }

common/src/main/java/dev/galacticraft/dynamicdimensions/impl/accessor/PrimaryLevelDataAccessor.java

@@ -34,5 +34,5 @@
  */
 @ApiStatus.Internal
 public interface PrimaryLevelDataAccessor {
-    void setDynamicList(@NotNull List<ResourceKey<Level>> dynamicDimensions);
+    void dynamicDimensions$setDynamicList(@NotNull List<ResourceKey<Level>> dynamicDimensions);
 }

common/src/main/java/dev/galacticraft/dynamicdimensions/impl/client/network/DynamicDimensionsS2CPacketReceivers.java

@@ -37,11 +37,11 @@
 
 public final class DynamicDimensionsS2CPacketReceivers {
     public static void registerReceivers() {
-        PlayPackets.registerClientReceiver(Constants.CREATE_WORLD_PACKET, (client, handler, buf, responseSender) -> createDynamicWorld(client, handler, buf));
-        PlayPackets.registerClientReceiver(Constants.DELETE_WORLD_PACKET, (client, handler, buf, responseSender) -> deleteDynamicWorld(client, handler, buf));
+        PlayPackets.registerClientReceiver(Constants.CREATE_DIMENSION_PACKET, (client, handler, buf, responseSender) -> createDynamicDimension(client, handler, buf));
+        PlayPackets.registerClientReceiver(Constants.REMOVE_DIMENSION_PACKET, (client, handler, buf, responseSender) -> removeDynamicDimension(client, handler, buf));
     }
 
-    private static void createDynamicWorld(@NotNull Minecraft client, @NotNull ClientPacketListener handler, @NotNull FriendlyByteBuf buf) {
+    private static void createDynamicDimension(@NotNull Minecraft client, @NotNull ClientPacketListener handler, @NotNull FriendlyByteBuf buf) {
         ResourceLocation id = buf.readResourceLocation();
         int rawId = buf.readInt();
         DimensionType type = DimensionType.DIRECT_CODEC.decode(NbtOps.INSTANCE, buf.readNbt()).get().orThrow().getFirst();
@@ -51,7 +51,7 @@ private static void createDynamicWorld(@NotNull Minecraft client, @NotNull Clien
         });
     }
 
-    private static void deleteDynamicWorld(@NotNull Minecraft client, @NotNull ClientPacketListener handler, @NotNull FriendlyByteBuf buf) {
+    private static void removeDynamicDimension(@NotNull Minecraft client, @NotNull ClientPacketListener handler, @NotNull FriendlyByteBuf buf) {
         ResourceLocation id = buf.readResourceLocation();
         client.execute(() -> {
             RegistryUtil.unregister(handler.registryAccess().registryOrThrow(Registries.DIMENSION_TYPE), id);