World Module

The World Module is one of the built-in Studio Modules that allows you to create, load, save, and generate worlds dynamically in your project. With the World Module, you can do anything from per-player stored plot worlds, to massive persistent generated adventure worlds, to ephemeral worlds created from map templates. MineplexWorlds are totally configurable, from their persistence, to their generation, to whether they exist only in memory. They also contain keyed Data Points that can be used to dynamically load points of interest from varied map templates - the days of hard coding specific locations in your game are long gone.

Creating a MineplexWorld 🔗

In order to create a new MineplexWorld, the World Module method createMineplexWorld(MineplexWorldConfig) must be executed with a completed and valid MineplexWorldConfig.

MineplexWorldConfig 🔗

A MineplexWorldConfig is comprised of a few key options.

First, you have the option to specify a PersistentWorldConfig. By default, this is null, indicating that the MineplexWorld will not be persistent. Setting this value to a valid PersistentWorldConfig will cause the created MineplexWorld to be persistent.

PersistentWorldConfig 🔗

The only configuration needed in a PersistentWorldConfig is a String value for the worldBucket option. This value will determine the name of the data collection this persistent world will be stored within.

Next comes the significant portion of the configuration process for a new MineplexWorld. The WorldCreationConfig comprises almost all of the options that control the makeup of the new world. This config cannot be null, and must be filled out by you so as to be valid.

WorldCreationConfig 🔗

Within the WorldCreationConfig there are several configuration options, some of which conflict with each other. The first option is a String value for the worldTemplate, which defaults to null. If this is set to a value, any further options in the WorldCreationConfig will be ignored and the MineplexWorld will be initialized from the project map template named the same as the String value, if the template exists. If there is no such named template, then the world creation will fail. The next option is voidWorld, which can be true or false. This option defaults to true, in which case the created world will generate no terrain, and therefore all subsequent options in the WorldCreationConfig will be ignored. If this option is set to false, then the world will generate via the default generator, or a custom one if specified. A custom world generator can be defined for the new world via the following options:

• customChunkGenerator will accept a ChunkGenerator implementation from the Bukkit API. You should conduct further research on how this API section works before attempting it in your project. Defaults to null.
• customBlockPopulators will accept a Collection<BlockPopulator>, based on BlockPopulator implementations from the Bukkit API. This can be directly specified, or included in the above customChunkGenerator if one is set. You should conduct further research on how this API section works before attempting it in your project. Defaults to null.
• customBiomeProvider will accept a BiomeProvider implementation from the Bukkit API. This can be directly specified, or included in the above customChunkGenerator if one is set. You should conduct further research on how this API section works before attempting it in your project. Defaults to null.

Finally, the seed for the world generation can be specified by setting the customSeed option to a given Long value. Defaults to null, in which case a random seed is used.

After the WorldCreationConfig is complete, you need to make a determination as to what region format your new MineplexWorld should use, by setting the worldRegionType option to one of the WorldRegionFormatTypes. Defaults to WorldRegionFormatType.ANVIL.

WorldRegionFormatType 🔗

• ANVIL: The Minecraft Java Edition standard region format developed by Mojang. Regions are stored as .mca files.

Finally, you must specify whether your MineplexWorld should exist exclusively in memory via the inMemoryOnly option, or if it should instead utilize the storage of the container to load/unload chunks. By default this is set to true, in memory only, and this should work for most use cases. However, if your map template is significantly large, or if players are able to cause the world to generate without a sufficiently tight boundary, the world may grow to a size that cannot be retained in memory. If this is the case, electing to keep the inMemoryOnly option set to true may result in undefined behavior or container crashes.

Loading a MineplexWorld from Storage 🔗

There are two ways to load a persistent MineplexWorld from long-term storage. Your first option is the World Module method loadMineplexWorld(String, String, WorldCreationConfig), which attempts to asynchronously download and load in the MineplexWorld with the specified ID from the specified worldBucket. If no MineplexWorld matches the ID in that worldBucket, then no MineplexWorld is loaded. Alternatively, you can use the World Module method loadOrCreateMineplexWorld(String, String, MineplexWorldConfig), which also attempts to asynchronously download and load in the MineplexWorld with the specified ID from the specified worldBucket. However, in the case where this method does not find a matching MineplexWorld, it will create a new one using the provided MineplexWorldConfig.

Unloading a MineplexWorld 🔗

You are not able to force a MineplexWorld to unload, however you should not need to. Instead, you can use the World Module method releaseWorld(MineplexWorld) to indicate to the World Module that the world is no longer needed. At that point, the World Module will conduct save procedures for the MineplexWorld (if any are defined), then unload the world and free up any space.

Deleting a MineplexWorld 🔗

This functionality is specifically for unloaded persistent MineplexWorlds. This should not be called for a loaded or ephemeral world. To delete a stored persistent MineplexWorld, call the World Module method deleteWorld(String, String) with the MineplexWorld worldBucket and ID as the argument.

Getting a loaded MineplexWorld 🔗

In order to get a MineplexWorld that has already been loaded by the World Module, use the method getLoadedMineplexWorld(String). Note that this will require you to know the MineplexWorld ID.

Data Points 🔗

View full information on datapoints here

Examples 🔗

Creating a MineplexWorld from a Map Template 🔗

Let's say we have some map templates in our project. We can dynamically create new MineplexWorlds based on those templates at runtime.

public MineplexWorld createFromTemplate(final String template) {
    // Creates a new in-memory, ephemeral world from the given template using the ANVIL region format
    return worldModule.createMineplexWorld(MineplexWorldConfig.builder()
            .worldRegionType(MineplexWorldConfig.WorldRegionFormatType.ANVIL)
            .worldCreationConfig(WorldCreationConfig.builder()
                    .worldTemplate(template)
                    .build())
            .build());
}

Randomly Generating a MineplexWorld 🔗

Let's say we don't want to use a template. We can create a new MineplexWorld using the random world generation built into the game. We can also make it persistent.

public MineplexWorld generateNewPersistentWorld(final Long seed) {
    // Creates and generates a new persistent world cached on the filesystem
    // using the anvil region format and a seed
    return worldModule.createMineplexWorld(MineplexWorldConfig.builder()
            .persistentWorldConfig(PersistentWorldConfig.builder()
                    .worldBucket("Examples")
                    .build())
            .worldCreationConfig(WorldCreationConfig.builder()
                    .voidWorld(false)
                    .customSeed(seed)
                    .build())
            .build());
}