Package net.thenextlvl.worlds.api.view

Interface LevelView

@NullMarked public interface LevelView
Interface representing a view for managing levels in a server environment. It provides methods for reading, validating, and managing world directories and data.
Since:
2.0.0

  • Method Details

    • getBackupFolder

      @Contract(pure=true) Path getBackupFolder()
      Retrieves the path to the backup folder.
      Returns:
      the Path representing the backup folder
      Since:
      3.0.0

    • getWorldContainer

      @Contract(pure=true) Path getWorldContainer()
      Retrieves the path to the world container directory.
      Returns:
      the Path representing the world container directory
      Since:
      3.0.0

    • read

      @Contract(value="_ -> new", pure=true) Optional<Level.Builder> read(Path directory)
      Reads a level from the specified directory path.
      Parameters:
      directory - the directory containing the level data to be read
      Returns:
      an Optional containing the Level.Builder if the directory represents a valid level, or Optional.empty() if the directory is invalid
      Since:
      3.0.0

    • getGenerator

      @Contract(pure=true) Optional<org.bukkit.plugin.java.JavaPlugin> getGenerator(org.bukkit.World world)
      Retrieves the plugin associated with the world generator for the given world, if it exists.
      Parameters:
      world - the world whose generator plugin is to be retrieved
      Returns:
      an Optional containing the associated JavaPlugin, or Optional.empty() if the world does not have a generator or if the generator is not associated with a plugin
      Since:
      3.0.0

    • listLevels

      @Contract(pure=true) @Unmodifiable Set<Path> listLevels()
      Returns an unmodifiable set of paths representing the directories of all levels available in the server's world container. These directories are determined to be valid levels using specific validation criteria.
      Returns:
      an unmodifiable set of Path objects representing valid level directories, or an empty set if no valid levels are found or if an error occurs while accessing the filesystem.
      Since:
      3.0.0

    • canLoad

      @Contract(pure=true) boolean canLoad(Path level)
      Determines if a level located at the specified path can be loaded. A level can be loaded if there is no other world loaded with the same path.
      Parameters:
      level - the path to the level directory to be checked
      Returns:
      true if the level can be loaded, otherwise false
      Since:
      3.0.0

    • hasEndDimension

      @Contract(pure=true) boolean hasEndDimension(Path level)
      Determines whether the specified directory contains an End dimension folder.
      Parameters:
      level - the path to the directory to be checked
      Returns:
      true if the level directory contains a DIM1 folder, otherwise false
      Since:
      3.0.0

    • hasNetherDimension

      @Contract(pure=true) boolean hasNetherDimension(Path level)
      Determines whether the specified directory contains a Nether dimension folder.
      Parameters:
      level - the path to the directory to be checked
      Returns:
      true if the level directory contains a DIM-1 folder, otherwise false
      Since:
      3.0.0

    • isLevel

      @Contract(pure=true) boolean isLevel(Path path)
      Determines whether the specified directory represents a valid world folder.
      Parameters:
      path - the path to the directory being checked
      Returns:
      true if the directory contains a level.dat or level.dat_old, otherwise false
      Since:
      3.0.0

    • unload

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default boolean unload(org.bukkit.World world, boolean save)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use unloadAsync(World, boolean)
      Unloads the specified world from the server.
      Parameters:
      world - the world to be unloaded
      save - whether changes to the world should be saved before unloading
      Returns:
      true if the world was successfully unloaded, otherwise false
      Since:
      3.0.0

    • unloadAsync

      @Contract(mutates="io,param1") CompletableFuture<Boolean> unloadAsync(org.bukkit.World world, boolean save)
      Unloads the specified world from the server.
      Parameters:
      world - the world to be unloaded
      save - whether changes to the world should be saved before unloading
      Returns:
      A CompletableFuture completing with true if the world was successfully unloaded, otherwise false
      Since:
      3.2.0

    • save

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default void save(org.bukkit.World world, boolean flush)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use saveAsync(World, boolean)
      Saves the specified world, with an option to flush pending changes immediately.
      Parameters:
      world - the world to be saved
      flush - whether to flush pending changes to disk immediately
      Since:
      3.0.0

    • saveAsync

      @Contract(mutates="io,param1") CompletableFuture<Void> saveAsync(org.bukkit.World world, boolean flush)
      Saves the specified world, with an option to flush pending changes immediately.
      Parameters:
      world - the world to be saved
      flush - whether to flush pending changes to disk immediately
      Returns:
      A CompletableFuture that might complete exceptionally
      Since:
      3.2.0

    • saveLevelData

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default void saveLevelData(org.bukkit.World world, boolean async)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use saveLevelDataAsync(World)
      Saves the level.dat of the specified world to disk.
      Parameters:
      world - the world whose level data should be saved
      async - whether the save operation should be performed asynchronously

    • saveLevelDataAsync

      @Contract(mutates="io,param1") CompletableFuture<Void> saveLevelDataAsync(org.bukkit.World world)
      Saves the level.dat of the specified world to disk.
      Parameters:
      world - the world whose level data should be saved
      Since:
      3.2.0

    • isEnabled

      @Contract(pure=true) boolean isEnabled(org.bukkit.World world)
      Determines if the specified world is enabled and will be loaded on startup.
      Parameters:
      world - the world to check
      Returns:
      true if the world is enabled, false otherwise
      Since:
      3.2.0

    • setEnabled

      @Contract(mutates="param1") void setEnabled(org.bukkit.World world, boolean enabled)
      Sets whether the specified world is enabled and will be loaded on startup.
      Parameters:
      world - the world to enable or disable
      enabled - true to enable the world, false to disable it
      Since:
      3.2.0

    • backup

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.3.1") default long backup(org.bukkit.World world) throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      use backupAsync(World)
      Creates a backup for the given world and returns the size of the backup in bytes.
      Parameters:
      world - the world to back up
      Returns:
      the size of the created backup in bytes
      Throws:
      IOException - if an I/O error occurs while creating the backup
      Since:
      3.0.0

    • backupAsync

      @Contract(mutates="io,param1") CompletableFuture<Long> backupAsync(org.bukkit.World world)
      Creates a backup for the given world and returns the size of the backup in bytes.

      Completes with an IOException if an I/O error occurs while creating the backup

      Parameters:
      world - the world to back up
      Returns:
      A CompletableFuture completing with the size of the created backup in bytes
      Since:
      3.2.0

    • clone

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default Optional<org.bukkit.World> clone(org.bukkit.World world, Consumer<Level.Builder> builder, boolean full) throws IllegalArgumentException, IllegalStateException, IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      use cloneAsync(World, Consumer, boolean)
      Clones the specified world with the possibility to modify its properties through a builder. If a full clone is invoked, the entire world directory is duplicated, except for specific files and folders: advancements, datapacks, playerdata, stats, uid.dat, and session.lock.

      By default, if a name or key is not provided, they are automatically generated using the pattern OriginalName (#), and the key is a lowercased version of the generated name, replacing spaces with underscores and removing invalid namespace characters.

      Throws an IllegalArgumentException if the world name or key is already in use. Throws an IllegalStateException if the target directory already exists.

      Parameters:
      world - the world to be cloned
      builder - a consumer that modifies the Level.Builder properties of the cloned world
      full - whether to fully clone including regions, entities..., or only the level.dat
      Returns:
      an Optional containing the cloned world, or Optional.empty() if the cloning fails
      Throws:
      IllegalArgumentException - if the world name or key are already in use
      IllegalStateException - if the target directory already exists
      IOException - if an I/O error occurs during the cloning process
      Since:
      3.0.0
      See Also:

    • cloneAsync

      @Contract(mutates="io,param1") CompletableFuture<org.bukkit.World> cloneAsync(org.bukkit.World world, Consumer<Level.Builder> builder, boolean full)
      Clones the specified world with the possibility to modify its properties through a builder. If a full clone is invoked, the entire world directory is duplicated, except for specific files and folders: advancements, datapacks, playerdata, stats, uid.dat, and session.lock.

      By default, if a name or key is not provided, they are automatically generated using the pattern OriginalName (#), and the key is a lowercased version of the generated name, replacing spaces with underscores and removing invalid namespace characters.

      Completes with an IllegalArgumentException if the world name or key is already in use.
      Completes with an IllegalStateException if the target directory already exists.
      Completes with an IOException if an I/O error occurs during the cloning process.

      Parameters:
      world - the world to be cloned
      builder - a consumer that modifies the Level.Builder properties of the cloned world
      full - whether to fully clone including regions, entities..., or only the level.dat
      Returns:
      A CompletableFuture completing with the cloned world
      Since:
      3.2.0
      See Also:

    • delete

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default LevelView.DeletionResult delete(org.bukkit.World world, boolean schedule)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use deleteAsync(World, boolean)
      Deletes the specified world from the server and disk. The deletion can be executed immediately or scheduled for later, depending on the provided parameters.
      Parameters:
      world - the world to be deleted
      schedule - if true, the deletion process will be scheduled for a later operation (e.g., during server shutdown); if false, the deletion will be attempted immediately
      Returns:
      a DeletionResult indicating the outcome of the deletion process.
      Since:
      3.0.0

    • deleteAsync

      @Contract(mutates="io,param1") CompletableFuture<LevelView.DeletionResult> deleteAsync(org.bukkit.World world, boolean schedule)
      Deletes the specified world from the server and disk. The deletion can be executed immediately or scheduled for later, depending on the provided parameters.
      Parameters:
      world - the world to be deleted
      schedule - if true, the deletion process will be scheduled for a later operation (e.g., during server shutdown); if false, the deletion will be attempted immediately
      Returns:
      A CompletableFuture completing with a DeletionResult indicating the outcome of the deletion process.
      Since:
      3.2.0

    • cancelScheduledDeletion

      @Contract(mutates="this") boolean cancelScheduledDeletion(org.bukkit.World world)
      Cancels the deletion process for the specified world, if scheduled.
      Parameters:
      world - the world for which the scheduled deletion should be canceled
      Returns:
      true if the scheduled deletion was successfully canceled, false if no deletion was scheduled
      Since:
      3.0.0

    • isDeletionScheduled

      @Contract(pure=true) boolean isDeletionScheduled(org.bukkit.World world)
      Checks whether a deletion process is scheduled for the specified world.
      Parameters:
      world - the world to check for a scheduled deletion
      Returns:
      true if a deletion process is scheduled for the world, otherwise false
      Since:
      3.0.0

    • regenerate

      @Contract(mutates="io,param1") @Deprecated(forRemoval=true, since="3.2.0") default LevelView.DeletionResult regenerate(org.bukkit.World world, boolean schedule)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use regenerateAsync(World, boolean)
      Regenerates the specified world, either immediately or scheduled, based on the provided parameters.
      Parameters:
      world - the world to be regenerated
      schedule - if true, the regeneration will be scheduled for later execution; if false, the regeneration will be attempted immediately
      Returns:
      a DeletionResult indicating the outcome of the regeneration process.
      Since:
      3.0.0

    • regenerateAsync

      @Contract(mutates="io,param1") CompletableFuture<LevelView.DeletionResult> regenerateAsync(org.bukkit.World world, boolean schedule)
      Regenerates the specified world, either immediately or scheduled, based on the provided parameters.
      Parameters:
      world - the world to be regenerated
      schedule - if true, the regeneration will be scheduled for later execution; if false, the regeneration will be attempted immediately
      Returns:
      a CompletableFuture completing with a DeletionResult indicating the outcome of the regeneration process.
      Since:
      3.2.0

    • cancelScheduledRegeneration

      @Contract(mutates="this") boolean cancelScheduledRegeneration(org.bukkit.World world)
      Cancels the regeneration process for the specified world, if scheduled.
      Parameters:
      world - the world for which the scheduled regeneration should be canceled
      Returns:
      true if the scheduled regeneration was successfully canceled, false if no regeneration was scheduled
      Since:
      3.0.0

    • isRegenerationScheduled

      @Contract(pure=true) boolean isRegenerationScheduled(org.bukkit.World world)
      Checks whether a regeneration process is scheduled for the specified world.
      Parameters:
      world - the world to check for a scheduled regeneration
      Returns:
      true if a regeneration process is scheduled for the world, otherwise false
      Since:
      3.0.0