> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/v4/developer-portal/world-management.md). # World Management API Programmatically create, import, and manage worlds using the `WorldService` and fluent builders. *** ## 1. World Creation & Import (Fluent API) ### Generating a Fresh World To generate a new world, use `WorldService#newWorld(String)` which returns a `WorldBuilder` instance. Chain options and execute `.build()` synchronously: ```java import de.eintosti.buildsystem.api.BuildSystem; import de.eintosti.buildsystem.api.BuildSystemProvider; import de.eintosti.buildsystem.api.world.BuildWorld; import de.eintosti.buildsystem.api.world.WorldService; import de.eintosti.buildsystem.api.world.data.BuildWorldType; import de.eintosti.buildsystem.api.world.data.Visibility; import org.bukkit.Difficulty; WorldService worldService = BuildSystemProvider.get().getWorldService(); BuildWorld lobbyWorld = worldService.newWorld("Lobby_01") .type(BuildWorldType.NORMAL) .difficulty(Difficulty.PEACEFUL) .time(6000) // Noon .worldBorderSize(5000) .visibility(Visibility.EVERYONE) .build(); // Synchronous. Must run on Bukkit's main thread. ``` ### Importing an Existing Directory To register an existing world folder present in the server container: ```java import de.eintosti.buildsystem.api.world.creation.WorldImporter; import de.eintosti.buildsystem.api.world.data.Visibility; BuildWorld importedWorld = worldService.importWorld("legacy_lobby") .visibility(Visibility.ADDED_PLAYERS) .build(); // Synchronous. Must run on Bukkit's main thread. ``` ### Async Operations (Bulk Import, Delete, and Unimport) Bulk imports, unimports, and deletion tasks operate asynchronously to protect tick timing. ```java import de.eintosti.buildsystem.api.world.lifecycle.SaveBehavior; // Bulk-import unregistered world directories (spread across ticks to prevent lag) worldService.importWorlds().thenAccept(importedCount -> { getLogger().info("Successfully imported " + importedCount + " worlds."); }); // Unimport (unload registry entries without deleting directory files) worldService.unimportWorld(buildWorld, SaveBehavior.SAVE).thenRun(() -> { getLogger().info("Unimported world successfully."); }); // Delete (unload registry entries and permanently delete directory) worldService.deleteWorld(buildWorld).thenRun(() -> { getLogger().info("Deleted world directory from disk."); }); ``` *** ## 2. Accessing & Mutating World Data `BuildWorld` represents the metadata of a world. You can access the live Bukkit `World` handle (if loaded) or mutate properties directly through the flat `WorldData` interface. ### Resolving the Bukkit World ```java // Returns Optional.empty() if the world is currently unloaded Optional bukkitWorldOpt = buildWorld.getWorld(); if (bukkitWorldOpt.isPresent()) { org.bukkit.World world = bukkitWorldOpt.get(); } ``` ### Flat Properties Mutation (`WorldData`) Version 4.0.0 simplified property mutations by placing direct getters and setters directly on `WorldData` instead of resolving nested wrapper objects: ```java import de.eintosti.buildsystem.api.world.data.WorldData; import de.eintosti.buildsystem.api.world.data.BuildWorldStatus; import de.eintosti.buildsystem.api.world.data.WorldStatusRegistry; import com.cryptomorin.xseries.XMaterial; WorldData data = buildWorld.getData(); // Read properties boolean physicsEnabled = data.isPhysics(); BuildWorldStatus status = data.getStatus(); boolean canBuild = data.isBlockBreaking(); // Mutate properties (saves to database configuration immediately) data.setPhysics(false); // Statuses are interfaces resolved via the registry WorldStatusRegistry registry = BuildSystemProvider.get().getStatusRegistry(); BuildWorldStatus finishedStatus = registry.getStatus("finished"); if (finishedStatus != null) { data.setStatus(finishedStatus); } data.setMaterial(XMaterial.GRASS_BLOCK); data.setCustomSpawn("0.0;64.0;0.0;90.0;0.0"); // x;y;z;yaw;pitch ``` *** ## 3. Save Behavior Configuration When unloading or unimporting worlds, specify saving guidelines using the `SaveBehavior` enum: * `SaveBehavior.SAVE`: Saves modified chunks and database properties to disk before unloading. * `SaveBehavior.DISCARD`: Discards block changes from memory (rolled back) before unloading the world. *** ## 4. API Enumerations Directory ### `BuildWorldType` Exposed by `BuildWorld#getType()` and `BuildWorldCreateEvent#getType()`. Defines the dimension or generator layout: | Enum Constant | Description | | ------------- | ------------------------------------------------------------- | | `NORMAL` | Standard vanilla terrain generation. | | `FLAT` | Flatworld grid generation. | | `NETHER` | Nether dimension dimension layout. | | `END` | End dimension dimension layout. | | `VOID` | Void chunk generation (empty space). | | `CUSTOM` | Chunk generation controlled by third-party generator plugins. | | `IMPORTED` | World directory adopted from an existing server folder. | | `TEMPLATE` | World copied from a template source directory. | ### `BuildWorldStatus` An interface representing the progress state of a world, resolved and managed via `WorldStatusRegistry` (`BuildSystemProvider.get().getStatusRegistry()`). The built-in default status IDs are: | ID | Description | | ----------------- | ------------------------------------------------------- | | `not_started` | Default status upon world generation. | | `in_progress` | Builder actions are underway. | | `almost_finished` | Final detailing is active. | | `finished` | Project completed. | | `archive` | Enforces adventure mode and blocks block modifications. | | `hidden` | Hides the world from default navigator listings. | ### `Visibility` An enum defining the access restrictions on a world: * `Visibility.EVERYONE`: Visible to all players (public). * `Visibility.ADDED_PLAYERS`: Restricted to the creator and added builders (private). ### `NavigatorCategory` An interface representing navigator tab groupings, resolved and managed via `NavigatorCategoryRegistry` (`BuildSystemProvider.get().getNavigatorCategoryRegistry()`). Built-in defaults include `public`, `private`, and `archive`. ### `WorldSetting` Evaluated in custom code via `WorldPermissions#canModify(Player, WorldSetting)` to check permission guards: * `WorldSetting.BLOCK_BREAKING`: Restricts block breaks. * `WorldSetting.BLOCK_PLACEMENT`: Restricts block placements. * `WorldSetting.BLOCK_INTERACTIONS`: Restricts door/trapdoor opening and container interactions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://buildsystem.eintosti.de/v4/developer-portal/world-management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.