# VextolyWorlds A simple but powerful multi-world plugin for [Paper](https://papermc.io). Create, import, teleport, manage and delete worlds with one easy command and extend it with your own world types from any plugin. Designed so that a first-time server owner can be productive in two minutes, while still offering flags, gamerules, teleport warmups, custom generators and a clean Java API when you need them. --- ## Features - **Multi-world management** — create, import, load, unload and delete worlds - **7 built-in world types** — normal, superflat, amplified, void, nether, end, plus any external generator - **Custom world types via API** — other plugins register types that instantly work with `/vw create` and `/vw types` - **Per-world flags** — pvp, fire-spread, mob-griefing, explosions, leaf-decay, autoload - **Per-world difficulty and gamerules** — set them from chat, no vanilla command juggling - **Teleports with warmup, cooldown and move-cancel** — safe cross-dimension teleporting - **Everything in plain YAML** — `config.yml`, `messages.yml` (fully translatable) and `worlds.yml` - **Safe deletes** — `/vw delete` requires a second confirmation before erasing anything - **Full tab completion** and a color-coded `/vw help` menu - **Fine grained permissions** with sensible defaults - No database, no extra dependencies, no worlds locked into a plugin format ## Requirements - Server: Paper (or a Paper fork) **1.21.11 – 26.3**, including the 25.x/26.x releases - Java 21 or newer The plugin targets `api-version: 1.21`, which every newer Paper build accepts, so one jar covers the whole version range. ## Installation 1. Download jar. 2. Drop `VextolyWorlds-1.0.0.jar` into your server's `plugins/` folder. 3. Start the server. `plugins/VextolyWorlds/` is created with `config.yml`, `messages.yml` and `worlds.yml`. 4. Run `/vw help` in game. ## Quick start (60 seconds) ```text /vw create parkour flat → a flat world for building /vw tp parkour → teleport to it /vw setspawn → stand where players should arrive, then run this /vw flag parkour pvp false → no fighting there /vw flag parkour leaf-decay false /vw spawn parkour → back to that world's spawn any time ``` Made a mistake? `/vw delete parkour` asks you to run it again within 30 seconds before anything is actually deleted. ## Commands All commands work from in-game chat and the console. Aliases: `/vw`, `/vworlds`, `/vextolyworlds`. | Command | Description | |---|---| | `/vw help` | Show the command menu | | `/vw create [type] [seed]` | Create a world (`/vw types` lists all types) | | `/vw import [type]` | Add an existing world folder on the server | | `/vw delete ` | Delete a world forever (asks for confirmation) | | `/vw load ` | Load an unloaded managed world | | `/vw unload ` | Unload a world (players inside are moved out safely) | | `/vw list` | Show all managed and server worlds | | `/vw types` | Show every registered world type, including API ones | | `/vw info [world]` | Type, environment, seed, difficulty, spawn, flags, players | | `/vw tp [player]` | Teleport yourself (or another player) to a world | | `/vw spawn [world]` | Teleport to a world's spawn | | `/vw setspawn` | Set the spawn of your current world to where you stand | | `/vw flag [value]` | Show or set a flag — omit the value to toggle | | `/vw difficulty ` | `peaceful`, `easy`, `normal` or `hard` | | `/vw gamerule [value]` | Show or set any vanilla gamerule || `/vw reload` | Reload `config.yml` and `messages.yml` | Examples: ```text /vw create survival normal 12345 /vw create creative flat /vw create darkness void /vw create mining generator:MyPlugin:cave /vw flag creative pvp off /vw gamerule survival keepInventory true /vw tp mining Notch ``` Gamerule names work in every style: `keepInventory`, `keep_inventory` and `minecraft:keep_inventory` are all accepted, so you can type them however you remember them on any supported server version. ## Permissions | Permission | Default | Allows | |---|---|---| | `vextolyworlds.help` | op | `/vw help` | | `vextolyworlds.create` | op | `/vw create` | | `vextolyworlds.delete` | op | `/vw delete` | | `vextolyworlds.import` | op | `/vw import` | | `vextolyworlds.load` | op | `/vw load` | | `vextolyworlds.unload` | op | `/vw unload` | | `vextolyworlds.list` | op | `/vw list` | | `vextolyworlds.info` | op | `/vw info` | | `vextolyworlds.types` | op | `/vw types` | | `vextolyworlds.tp` | op | `/vw tp` (self) | | `vextolyworlds.tp.others` | op | `/vw tp ` | | `vextolyworlds.spawn` | op | `/vw spawn` | | `vextolyworlds.setspawn` | op | `/vw setspawn` | | `vextolyworlds.flag` | op | `/vw flag` | | `vextolyworlds.difficulty` | op | `/vw difficulty` | | `vextolyworlds.gamerule` | op | `/vw gamerule` | | `vextolyworlds.reload` | op | `/vw reload` | | `vextolyworlds.bypass.teleport` | op | Skip teleport warmup and cooldown | | `vextolyworlds.admin` | op | All of the above | | `vextolyworlds.*` | op | Everything | Every single subcommand is permission-checked — even `/vw help` and tab completion only show the commands a player is actually allowed to use. Nothing works without an explicit grant, so players get access only through your permission setup (e.g. luckperms: give a player group `vextolyworlds.tp`, `vextolyworlds.spawn`, `vextolyworlds.list` and `vextolyworlds.help` to open up basic world travel). ## World types | Type | Aliases | What you get | |---|---|---| | `normal` | `overworld`, `default` | Vanilla terrain: biomes, caves, structures | | `flat` | `superflat` | Flat grass, great for building | | `amplified` | | Extreme mountains | | `void` | `empty` | Empty world with an optional obsidian spawn platform | | `nether` | `the_nether`, `hell` | The nether dimension | | `end` | `the_end` | The end dimension | | `generator::` | | Any chunk generator another plugin provides | External types registered through the API show up here automatically. ## Per-world flags Flags are enforced live and stored in `worlds.yml`. Omit the value to toggle. | Flag | Effect when `false` | |---|---| | `pvp` | Players cannot hurt each other (arrows included) | | `fire-spread` | Fire does not spread or burn blocks | | `mob-griefing` | Mobs cannot change blocks (endermen, zombie doors, sheep eating grass...) | | `explosions` | Explosions do not damage the world | | `leaf-decay` | Leaves never disappear | | `mob-spawning` | Mobs do not spawn (spawns triggered by other plugins still work) | | `hunger` | Players never lose hunger | | `weather` | Weather never changes | | `autoload` | World is (not) loaded on server start | Plugins can add their own flags through the API — see [Custom flags](#custom-flags-api) below. Unmanaged worlds (like your main `world`) use the defaults from `config.yml`. ## Configuration files All files live in `plugins/VextolyWorlds/`. ### config.yml ```yaml settings: teleport: warmup-seconds: 3 # stand still before a teleport finishes (0 = off) cooldown-seconds: 5 # wait between teleports (0 = off) cancel-on-move: true # moving cancels a running warmup join: teleport-to-spawn: false flags: defaults: # defaults for new + unmanaged worlds pvp: true fire-spread: true mob-griefing: true explosions: true leaf-decay: true void: spawn-platform: true # obsidian platform so players don't fall ``` ### messages.yml Every message the plugin sends, with `&` color codes and `&#RRGGBB` hex colors. Edit freely and run `/vw reload`. ### worlds.yml Written by the plugin. One entry per managed world with type, seed, environment, difficulty, flags, spawn point and autoload setting. You can edit it while the server is offline, but normally you never touch it. ## API for developers VextolyWorlds ships a small, stable API for external world types and world lifecycle events. Add it to your project: ```bash git clone https://github.com/vextoly/VextolyWorlds cd VextolyWorlds && mvn install ``` ```xml dev.vextoly vextolyworlds 1.0.0 provided ``` Remember `softdepend: [VextolyWorlds]` in your plugin.yml. ### Register a custom world type ```java public final class SkylandsType implements WorldType { @Override public String id() { return "skylands"; } @Override public String displayName() { return "Skylands"; } @Override public String description() { return "Floating island paradise."; } @Override public ChunkGenerator generator() { return new SkylandsGenerator(); } @Override public Location spawnLocation(World world) { return new Location(world, 0.5, 120, 0.5); } } ``` ```java @Override public void onEnable() { if (VextolyWorldsAPI.isEnabled()) { VextolyWorldsAPI.registerWorldType(new SkylandsType()); } } ``` That's it: `/vw create sky skylands` works, `/vw types` lists it, and it persists in `worlds.yml` like any built-in type. ### Events | Event | When | Cancellable | |---|---|---| | `PreWorldCreateEvent` | before a world is created | yes | | `WorldCreatedEvent` | after a world was created and registered | no | | `PreWorldDeleteEvent` | before a world is deleted | yes | | `WorldDeletedEvent` | after a world was deleted | no | ```java @EventHandler public void onCreate(WorldCreatedEvent event) { getLogger().info("World " + event.worldName() + " was created with type " + event.worldType().id()); } ``` ### Custom flags (API) Your plugin can register its own world flags. VextolyWorlds stores them in `worlds.yml`, shows them in `/vw flag `, tab-completes them, and lets admins toggle them like any built-in flag — your plugin just decides what they do. ```java import dev.vextoly.worlds.api.VextolyWorldsAPI; import dev.vextoly.worlds.api.flag.SimpleWorldFlag; import dev.vextoly.worlds.api.flag.WorldFlag; public final class MyPlugin extends JavaPlugin implements Listener { public static final WorldFlag DUELS = new SimpleWorldFlag("duels", true, "Allows players to duel."); @Override public void onEnable() { if (VextolyWorldsAPI.isEnabled()) { VextolyWorldsAPI.registerFlag(DUELS); } Bukkit.getPluginManager().registerEvents(this, this); } @EventHandler public void onDamage(EntityDamageByEntityEvent event) { if (event.getEntity() instanceof Player && event.getDamager() instanceof Player && !VextolyWorldsAPI.flag(event.getEntity().getWorld(), DUELS)) { event.setCancelled(true); } } } ``` That's the whole integration. With this registered: - `/vw flag arena duels false` turns duels off in the world `arena` - the value persists across restarts in `worlds.yml` - `/vw flag arena` lists `duels=false` next to the built-in flags - `VextolyWorldsAPI.flag(world, DUELS)` is your query at runtime Flag keys must be lowercase. If your plugin is absent, stored values are kept and simply show up again when it returns. You can also set flags programmatically with `VextolyWorldsAPI.worldManager().setFlag(...)`. ## FAQ **How do I add a world that already exists on the server?** Put its folder in the server root (next to `world/`), then `/vw import name`. VextolyWorlds remembers it from then on. **Can I use it together with Multiverse?** You can, but you shouldn't manage the same worlds with both. Pick one. **How do I reset a world?** `/vw delete name` then `/vw create name ...` with the same type and seed. **Where are the world files?** Wherever the server itself keeps them: in the server root on older versions, and under `/dimensions/minecraft/` on 26.x+ (Mojang moved dimension storage there). VextolyWorlds detects both layouts automatically — creating, importing and deleting works the same either way. No special folders, no locked-in format — delete the plugin and your worlds keep working. **Do teleport warmups apply to operators?** Operators with `vextolyworlds.bypass.teleport` skip warmup and cooldown. **A world failed to load after I removed its generator plugin.** The world entry stays in `worlds.yml`; reinstall the generator plugin or load the world as `normal`. Existing chunks are never touched by that. ## Version support Built and verified against the Paper API line used by 1.21.11 through 26.3, including the date-based 25.x/26.x versions. The plugin uses `api-version: 1.21`, which all of those builds accept, so the same jar runs everywhere in that range. Version differences the plugin already handles for you: snake_case and namespaced gamerule names, and both the old and the new dimension storage layout. If a future Paper change ever breaks something, a compatibility release will follow. ## License Apache License 2.0 — Copyright 2026 vextoly. See [LICENSE](LICENSE).