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

# /worlds

The main command for creating and managing worlds.

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

Where a subcommand takes `[world]`, leaving it out uses the world you are standing in.

A world in another namespace can be typed as `maps:lobby`, or as `lobby` while no other world has that name. See [World Namespaces](https://buildsystem.eintosti.de/getting-started/creating-a-world.md#world-namespaces).

Only one of delete, rename, unimport, backup, backup restore, download packing and saving a template runs on a world at a time. While one runs, the others are refused with `worlds_world_busy`, and so is a teleport that would have to load the world. If a world cannot be unloaded, delete, rename, restore and unimport stop and change nothing (`worlds_world_unload_failed`).

***

## 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. The world must be loaded. 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 to the target world's spawn location, or its custom spawn if one is set. The player must be allowed to enter the world (see [World Access](https://buildsystem.eintosti.de/permissions-and-access/restricting-worlds.md)).

***

## 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. On Paper, `maps:lobby` imports `dimensions/maps/lobby`; a name without a namespace is looked for in `world.default-namespace`. The optional `-g` flag specifies the generator (`NORMAL`, `FLAT`, `VOID`, or the name of a custom chunk generator plugin), defaulting to `VOID`; `-c` takes a player name and registers that player as the world's creator; `-t` sets the world type (`NORMAL`, `FLAT`, `NETHER`, `END`, `VOID`, `TEMPLATE`, `IMPORTED`, `CUSTOM`), defaulting to `IMPORTED`. Only words starting with `-` count as flags, and flags ignore case.
* **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, on Paper including those of every namespace. Execution is throttled via the config delay to prevent lag spikes. Accepts the same `-g` and `-c` flags as `/worlds import`, each at most once and in either order. 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` (supports `.self` / `.other` suffixes)
* **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` (supports `.self` / `.other` suffixes)
* **Description**: Opens a confirmation menu, then unloads the world and permanently deletes its directory from the server disk. Worlds listed in `world.deletion-blacklist` in `config.yml` cannot be deleted.

### `/worlds download [world]` (New in 4.0.0)

* **Syntax**: `/worlds download [world]`
* **Permission**: `buildsystem.download` (supports `.self` / `.other` suffixes)
* **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](https://buildsystem.eintosti.de/managing-worlds/downloading-a-world.md).

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

* **Syntax**: `/worlds saveTemplate [world] [templateName]`
* **Permission**: `buildsystem.savetemplate` (supports `.self` / `.other` suffixes)
* **Description**: Saves a copy of the target world directory into `plugins/BuildSystem/templates/` to make it selectable during new world creation. The template is named after the world, without its namespace, unless a name is given, and an existing template is never overwritten. The world's autosave is paused while it is copied.

### `/worlds backup [create]`

* **Syntax**: `/worlds backup` or `/worlds backup create`
* **Permission**: `buildsystem.backup` (supports `.self` / `.other` suffixes); `create` also needs `buildsystem.backup.create`
* **Description**: Opens the backup menu of the world you are in, where its backups are listed and can be restored. `create` starts a backup right away. See [World Backups](https://buildsystem.eintosti.de/managing-worlds/world-backups.md).

***

## Property & Access Mutation

### `/worlds setCreator [world]`

* **Syntax**: `/worlds setCreator [world]`
* **Permission**: `buildsystem.setcreator` (supports `.self` / `.other` suffixes)
* **Description**: Sets the registered owner/creator of the world. The plugin asks for the player name in chat; enter `-` to remove the creator.

### `/worlds setProject [world]`

* **Syntax**: `/worlds setProject [world]`
* **Permission**: `buildsystem.setproject` (supports `.self` / `.other` suffixes)
* **Description**: Sets the project tag metadata for the world. The plugin asks for the project in chat. If the world sits in a folder and `folder.override-projects` is on, the folder's project is shown instead, and the plugin says so.

### `/worlds setPermission [world]`

* **Syntax**: `/worlds setPermission [world]`
* **Permission**: `buildsystem.setpermission` (supports `.self` / `.other` suffixes)
* **Description**: Sets the permission node required for players to join the world. The plugin asks for the node in chat. Use `-` to clear permission locks. Checks against `world-permission-whitelist` if configured. If the world sits in a folder and `folder.override-permissions` is on, the folder's permission applies instead, and the plugin says so.

### `/worlds setStatus [world]`

* **Syntax**: `/worlds setStatus [world]`
* **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**: Opens the status picker to set 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` (supports `.self` / `.other` suffixes)
* **Description**: Sets the spawn point of the world you are in to your current position.

### `/worlds removeSpawn`

* **Syntax**: `/worlds removeSpawn`
* **Permission**: `buildsystem.removespawn` (supports `.self` / `.other` suffixes)
* **Description**: Deletes the custom spawn point of the world you are in.

***

## Whitelist Management

### `/worlds addBuilder [player]`

* **Syntax**: `/worlds addBuilder [player]`
* **Permission**: `buildsystem.addbuilder` (supports `.self` / `.other` suffixes)
* **Description**: Adds a player to the builder list of the world you are in. Without a name, the plugin asks for it in chat. With the bare node or `.self`, only the creator can manage the list; `.other` or `buildsystem.admin` allows it on any world.

### `/worlds removeBuilder [player]`

* **Syntax**: `/worlds removeBuilder [player]`
* **Permission**: `buildsystem.removebuilder` (supports `.self` / `.other` suffixes)
* **Description**: Removes a player from the builder list of the world you are in. Without a name, the plugin asks for it in chat.

### `/worlds builders [world]`

* **Syntax**: `/worlds builders [world]`
* **Permission**: `buildsystem.builders` (supports `.self` / `.other` suffixes)
* **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. The world must belong to the folder's navigator category and must not already be in another 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 folder. A folder that still holds worlds or subfolders is refused.

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

* **Syntax**: `/worlds folder <folder> setPermission`
* **Permission**: `buildsystem.folder.setpermission`
* **Description**: Configures an access permission for the folder. The plugin asks for the node in chat.

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

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

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

* **Syntax**: `/worlds folder <folder> setItem`
* **Permission**: `buildsystem.folder.setitem`
* **Description**: Sets the display material representing the folder in menus to the item held in the player's main hand.

***

## Utility Commands

### `/worlds help`

* **Syntax**: `/worlds help [page]`
* **Permission**: `buildsystem.help.worlds` (Default: `TRUE`)
* **Description**: Displays the paginated list of `/worlds` subcommands.

### `/worlds info [world]`

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

![Worlds Info Chat](https://2366875379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtdJcIoBgnlLEZoCMTDD%2Fuploads%2Fgit-blob-5daa72625430f49dacc7d7653f795d2259aeb77f%2Fworlds_info_chat.png?alt=media)

### `/worlds rename [world]`

* **Syntax**: `/worlds rename [world]`
* **Permission**: `buildsystem.rename` (supports `.self` / `.other` suffixes)
* **Description**: Renames the specified world. The plugin prompts for the new name via chat input. A name typed without a namespace keeps the world's namespace, so renaming `maps:lobby` to `arena` gives `maps:arena`.

### `/worlds setItem [world]`

* **Syntax**: `/worlds setItem [world]`
* **Permission**: `buildsystem.setitem` (supports `.self` / `.other` suffixes)
* **Description**: Sets the display icon for the specified world to the item currently held in the player's main hand. A held player head also sets the icon's skull texture.

### `/worlds item`

* **Syntax**: `/worlds item`
* **Permission**: `buildsystem.navigator.item`
* **Description**: Puts the navigator item (a clock by default, set by `settings.navigator.item`) in the sender's inventory.
