# Developers (API) GWorld v2 offers a modern API for managing and creating worlds and changing settings (flags) programmatically. Version v2.0.1 # 1. Setup & Integration To use GWorld v2 in your plugin, you must add it as a dependency. ## 1. Maven Dependency Add the `core` module from GWorld to your `pom.xml`. Since the API is provided by the server at runtime, we use the `provided` scope. ```XML de.gilljan gworld-core 2.0.1-SNAPSHOT provided ``` We use the GitHub Maven Package Registry. To use it, please refer to the GitHub documentation: [https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package) ## 2. plugin.yml To ensure that your plugin can access GWorld, it must be loaded **after** GWorld. To do this, add the entry to your `plugin.yml`: ```YAML depend: [GWorld] # Alternatively, if GWorld is optional: # softdepend: [GWorld] ``` ## 3. Access to the API The main entry point is the `GWorldAPI` interface. You can obtain the instance using the static method of the main class. ```JAVA import de.gilljan.gworld.GWorld; import de.gilljan.gworld.api.GWorldAPI; import de.gilljan.gworld.api.IWorldManager; public class MyPlugin extends JavaPlugin { private IWorldManager worldManager; @Override public void onEnable() { if (Bukkit.getPluginManager().isPluginEnabled("GWorld")) { // Retrieve API instance GWorldAPI api = GWorld.getInstance(); // Load the manager for worlds this.worldManager = api.getWorldManager(); } } } ``` # 2. Create worlds (Builder) In GWorld v2, new worlds are created using the **builder pattern**. This separates the **configuration** (registration) from the **generation** (load). # Step 1: The Builder (Registration) With the `WorldCreationBuilder `you define all the properties of the world. Calling `.build()` registers the world in the database, but does not yet physically create it. ```java import de.gilljan.gworld.api.IManageableWorld; import de.gilljan.gworld.enums.WorldTypeMapping; // Start the builder IManageableWorld newWorld = worldManager.createBuilder("MeineEventWelt") .worldType(WorldTypeMapping.NORMAL) // Environent: Normal, Nether, End, Large Biomes, Amplified, Flat .generator("PlotSquared") // Optional: Custom Generator Name .seed(987654321L) // Optional: Set seed .build(); // -> Saves the world to Config/DB ```

**Note:** The `.build()` method internally calls `addWorldFromBuilder`. The world is then known (`registered`), but still `unloaded`.

## Step 2: Load (generation) ```java // Creates the bukkit world and loads chunks boolean success = newWorld.createMap(); if (success) { getLogger().info("World is ready!"); } ```

The same applies to imports. Use the folder name of the world and use the `importMap()` method instead of `createMap()`.

## Why two steps? 1. **Performance:** You can register worlds when the server starts, but only load them when a player starts a minigame. 2. **Security:** You can set flags (e.g., PvP off) before the first player enters the world. # 3. Management & Control The `IWorldManager` manages all worlds, while the `IManageableWorld` object allows control over a specific world. # Retrieve worlds ```java // Retrive a single world Optional worldOpt = worldManager.getWorld("Lobby"); // Retrive all worlds List allWorlds = worldManager.getWorlds(); ``` ## World actions Each `IManageableWorld` object provides methods for control:
**Method** **Description**
`loadMap()` Loads the world from the hard drive (Bukkit World Init).
`unloadMap()` Unloads the world and teleports players to the main spawn.
`deleteMap()` Irrevocably deletes the world (files & database entry).
`reCreate(boolean save)` Deletes the world and regenerates it (reset). Optionally with backup (true) or without (false).
`clone(String name)` Creates a copy of the world under a new name.
### Example: Performing a world reset ```java worldManager.getWorld(“Farmworld”).ifPresent(world -> { // Reset world and keep copy of old world world.reCreate(true); }); ``` ### Example: Remove world (from the system) If you want to remove a world from GWorld (including deleting the files): ```java // Option A: Directly via the object (recommended) world.deleteMap(); // Option B: Over the manager worldManager.removeWorld(world); ``` # 4. Flags & Properties GWorld allows you to change world settings (flags) programmatically. These settings are stored persistently. # Set flags You can change flags directly on the `IManageableWorld` object or set them during creation in the builder. ```java // Example: Disable PVP and set difficulty to hard world.setAllowPvP(false); world.setDifficulty(Difficulty.HARD); // IMPORTANT: Save changes to disk. Ensures data integrity after a restart. world.saveProperties(); ``` ## Available settings Here is an overview of the most important methods in `IManageableWorld` interface:
**Category** **Methods (Getter / Setter)** **Description**
**PVP** `isAllowPvP`, `setAllowPvP` Global PvP on/off.
**Spawning** `isMonsterSpawning`, `setMonsterSpawning` Spawning monsters.
`isAnimalSpawning`, `setAnimalSpawning` Spawning animals.
**Environment** `isWeatherCycle`, `setWeatherCycle` Whether the weather changes.
`isTimeCycle`, `setTimeCycle` Whether the time of day is advancing.
`getTime`, `setTime` Current time in ticks.
**Player** `getGameMode`, `setGameMode` Default game mode of the world.
**System** `isLoadOnStartup`, `setLoadOnStartup` Should the world be loaded when the server starts?
`isAllowPvP`, `setAllowPvP` Keep spawn chunks in RAM.
## Use in the Builder When creating a world, you can also set flags generically via `WorldProperty`: ```java import de.gilljan.gworld.data.properties.WorldProperty; manager.createBuilder("Lobby") .property(WorldProperty.PVP, false) .property(WorldProperty.ANIMALS, false) .build(); ```