> 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/command-reference/worlds.md).

# /worlds

The `/worlds` command (aliases: `/w`) manages world navigation, folders, properties, and whitelists.

***

## Navigation & Editor UI

### `/worlds`

* **Syntax**: `/worlds` (or `/w`)
* **Permission**: `buildsystem.navigator`
* **Description**: Opens the World Navigator main dashboard.

### `/worlds <category>`

* **Syntax**: `/worlds <category>` (e.g. `/worlds public`, `/worlds private`, `/worlds archive`, or any custom category id)
* **Permission**: `buildsystem.navigator.category.<categoryId>` (granted by default)
* **Description**: Opens that category's worlds list directly. One shortcut exists per navigator category and is generated from the navigator, so a custom category gets its command automatically and a deleted one loses it. The same permission also controls whether the category appears in the navigator. If a category id matches a real subcommand (e.g. `delete`), the subcommand takes precedence and the shortcut is dropped.

### `/worlds edit [world]`

* **Syntax**: `/worlds edit [world]`
* **Permission**: `buildsystem.edit` (supports `.self` / `.other` suffixes)
* **Description**: Opens the interactive World Editor GUI to adjust settings like physics, difficulty, weather, time, and builders. Defaults to the player's current world if no argument is provided. Clicking the world item at the top opens an icon picker, where you choose a material, or right-click a player-head icon to set its skull texture (`buildsystem.edit.icon`). Right-clicking the physics toggle opens the physics exceptions menu (`buildsystem.edit.physics`), where individual behaviors (block updates, connections, falling blocks, fluid flow, leaf decay, growth, spreading, block forming, block fading) can keep running while the world's physics are disabled.

### `/worlds tp <world>`

* **Syntax**: `/worlds tp <world>`
* **Permission**: `buildsystem.worldtp`
* **Description**: Teleports the sender directly to the target world's spawn location.

***

## Directory Management

### `/worlds import <world> [-g generator] [-c creator] [-t type]`

* **Syntax**: `/worlds import <world> [-g <generator>] [-c <creator>] [-t <type>]`
* **Permission**: `buildsystem.import`
* **Description**: Imports a folder present under the server's root as an active build world. The optional `-g` flag specifies a custom chunk generator plugin; `-c` registers a player UUID as the world's creator; `-t` sets the world type (`NORMAL`, `FLAT`, `NETHER`, `END`, `VOID`, `TEMPLATE`, `IMPORTED`, `CUSTOM`), defaulting to `IMPORTED`.
* **Unknown values**: A `-g` value that is not a built-in generator is deliberately treated as the name of a *custom* generator. That is how third-party generators are selected. A `-t` value that is not a world type is an error: the import stops and says so, rather than silently falling back to `IMPORTED`.

### `/worlds importAll`

* **Syntax**: `/worlds importAll [-g <generator>] [-c <creator>]`
* **Permission**: `buildsystem.import.all`
* **Description**: Batch-imports all unregistered world folders in the server directory. Execution is throttled via the config delay to prevent lag spikes. Accepts the same `-g` and `-c` flags as `/worlds import`. Worlds skipped for an existing name or an invalid character are reported individually, as is any world that fails to import.
* **Unknown values**: Unlike `/worlds import`, an unrecognised `-g` is rejected here instead of being taken as a custom generator name, because a bulk import supplies no per-world generator data for that name to bind to.

### `/worlds unimport <world>`

* **Syntax**: `/worlds unimport <world>`
* **Permission**: `buildsystem.unimport`
* **Description**: Unloads the world from memory and deletes its BuildSystem registry entries without deleting the directory on disk.

### `/worlds delete <world>`

* **Syntax**: `/worlds delete <world>`
* **Permission**: `buildsystem.delete`
* **Description**: Unloads the world and permanently deletes its directory from the server disk.

### `/worlds download <world>` (New in 4.0.0)

* **Syntax**: `/worlds download <world>`
* **Permission**: `buildsystem.download`
* **Description**: Packs the world into a single-player save and sends a clickable download link. Since Paper 26.1 a server world is a dimension of the main level and has no `level.dat`, so the export rebuilds what the client needs: the world becomes the save's overworld and gets a `level.dat` named after it. Requires `world.download.enabled` in `config.yml`; the link is unguessable and expires (default 30 minutes), after which the archive is deleted. See [Downloading Worlds](/v4/managing-worlds/downloading-a-world.md).

### `/worlds saveTemplate <world> [templateName]` (New in 4.0.0)

* **Syntax**: `/worlds saveTemplate <world> [templateName]`
* **Permission**: `buildsystem.savetemplate`
* **Description**: Saves a copy of the target world directory into `plugins/BuildSystem/templates/` to make it selectable during new world creation.

***

## Property & Access Mutation

### `/worlds setCreator <world> <creator>`

* **Syntax**: `/worlds setCreator <world> <creator>`
* **Permission**: `buildsystem.setcreator`
* **Description**: Sets the registered owner/creator of the world.

### `/worlds setProject <world> <projectName>`

* **Syntax**: `/worlds setProject <world> <projectName>`
* **Permission**: `buildsystem.setproject` (supports `.self` / `.other` suffixes)
* **Description**: Sets the project tag metadata for the world.

### `/worlds setPermission <world> <permission>`

* **Syntax**: `/worlds setPermission <world> <permission>`
* **Permission**: `buildsystem.setpermission` (supports `.self` / `.other` suffixes)
* **Description**: Sets the permission node required for players to join the world. Use `-` to clear permission locks. Checks against `world-permission-whitelist` if configured.

### `/worlds setStatus <world> <status>`

* **Syntax**: `/worlds setStatus <world> <status>`
* **Permission**: `buildsystem.setstatus` (supports `.self` / `.other` suffixes, and requires the dynamic node `buildsystem.setstatus.<statusId>`, where built-in statuses strip underscores, e.g. `in_progress` → `buildsystem.setstatus.inprogress`; custom statuses use their full id)
* **Description**: Sets the progress state of the world (e.g., `not_started`, `in_progress`, `almost_finished`, `finished`, `archive`, `hidden` or any custom status).

***

## Spawn Management

### `/worlds setSpawn`

* **Syntax**: `/worlds setSpawn`
* **Permission**: `buildsystem.setspawn`
* **Description**: Sets the exact location of the target world's spawn point to the sender's current position.

### `/worlds removeSpawn`

* **Syntax**: `/worlds removeSpawn`
* **Permission**: `buildsystem.removespawn`
* **Description**: Deletes the custom spawn point set for the target world.

***

## Whitelist Management

### `/worlds addBuilder <world> <player>`

* **Syntax**: `/worlds addBuilder <world> <player>`
* **Permission**: `buildsystem.addbuilder`
* **Description**: Adds a player to the target world's builder list. Only the creator or an admin can manage this list.

### `/worlds removeBuilder <world> <player>`

* **Syntax**: `/worlds removeBuilder <world> <player>`
* **Permission**: `buildsystem.removebuilder`
* **Description**: Removes a player from the builder list.

### `/worlds builders [world]`

* **Syntax**: `/worlds builders [world]`
* **Permission**: `buildsystem.builders`
* **Description**: Opens a GUI displaying all whitelisted builders for the target world.

***

## Folder Management

### `/worlds folder <folder> add <world>`

* **Syntax**: `/worlds folder <folder> add <world>`
* **Permission**: `buildsystem.folder.add`
* **Description**: Adds the world to the specified folder.

### `/worlds folder <folder> remove <world>`

* **Syntax**: `/worlds folder <folder> remove <world>`
* **Permission**: `buildsystem.folder.remove`
* **Description**: Removes the world from the specified folder.

### `/worlds folder <folder> delete`

* **Syntax**: `/worlds folder <folder> delete`
* **Permission**: `buildsystem.folder.delete`
* **Description**: Deletes the empty folder directory.

### `/worlds folder <folder> setPermission <permission>`

* **Syntax**: `/worlds folder <folder> setPermission <permission>`
* **Permission**: `buildsystem.folder.setpermission`
* **Description**: Configures an access permission for the folder.

### `/worlds folder <folder> setProject <project>`

* **Syntax**: `/worlds folder <folder> setProject <project>`
* **Permission**: `buildsystem.folder.setproject`
* **Description**: Configures a project tag for the folder.

### `/worlds folder <folder> setItem <Material>`

* **Syntax**: `/worlds folder <folder> setItem <Material>`
* **Permission**: `buildsystem.folder.setitem`
* **Description**: Sets the display material representing the folder in menus.

***

## Utility Commands

### `/worlds help`

* **Syntax**: `/worlds help`
* **Permission**: `buildsystem.help.worlds`
* **Description**: Displays the help panel index.

### `/worlds info [world]`

* **Syntax**: `/worlds info [world]`
* **Permission**: `buildsystem.info`
* **Description**: Prints world metadata (creation date, physics, AI status, visibility) directly to chat.

![Worlds Info Chat](/files/eGhwimTe7ikF0xgZHaAI)

### `/worlds rename <world>`

* **Syntax**: `/worlds rename <world>`
* **Permission**: `buildsystem.rename`
* **Description**: Renames the specified world. The plugin prompts for the new name via chat input.

### `/worlds setItem <world>`

* **Syntax**: `/worlds setItem <world>`
* **Permission**: `buildsystem.setitem`
* **Description**: Sets the display icon for the specified world to the item currently held in the player's main hand.

### `/worlds item`

* **Syntax**: `/worlds item`
* **Permission**: `buildsystem.navigator.item`
* **Description**: Spawns the navigator clock item inside the sender's inventory.