> 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/getting-started/creating-a-world.md).

# Creating Worlds

Generate a new world or import one that already exists on disk.

BuildSystem supports generating fresh worlds or importing existing directories via in-game menus or direct command execution.

***

## Creating a World via the GUI

1. Open the main menu using:

   ```
   /worlds
   ```
2. Click the Chest icon to open the **World Navigator**.
3. Click the `+` Player Head icon at the bottom of the navigator to open the creation panel.
4. Select a world type category:
   * **Predefined Worlds**: Normal, Flat, Nether, End, or Void.
   * **Templates**: Pre-existing world folders loaded as templates.
   * **Generators**: Custom generators supplied by external plugins.
5. A chat prompt will request a world name. Type the name directly into the server chat and press Enter.

{% hint style="info" %}
**Custom seed (predefined worlds):** shift-click a predefined world type instead of left-clicking it to be prompted for a seed after the name. Numeric input is used as the literal seed, any other text hashes to a long, and leaving it blank falls through to a random seed.
{% endhint %}

![World Creation Panel](https://2366875379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtdJcIoBgnlLEZoCMTDD%2Fuploads%2Fgit-blob-6cb7de24ad757cedd3d138d65ecddb4befed4317%2Fworld_creation_panel.png?alt=media)

{% hint style="warning" %}
World names may only contain letters, digits, `_` and `-`. Any other character, and anything matching the `invalid-characters` regex in `config.yml`, is removed from the name. The one exception is the `:` that separates a [namespace](#world-namespaces).
{% endhint %}

***

## World Namespaces

On Paper, worlds can be grouped into namespaces, the same way Minecraft ids like `minecraft:stone` work. Write the name as `namespace:name`, for example `maps:lobby`, when creating, importing or renaming a world, and in any command that takes a world. The world is stored in `world/dimensions/maps/lobby` (with the default `level-name` of `world`).

A world without a namespace is in `minecraft`. That is where every world created before 4.1.0 lives, so existing worlds keep their names and folders, and nothing is migrated.

### New Names

A new name typed without a namespace goes into `world.default-namespace` from `config.yml`, which is `minecraft` unless you change it. This applies when creating a world and to the name given to `/worlds import`. Renaming is different: a new name without a namespace keeps the world in the namespace it is already in, so renaming `maps:lobby` to `arena` gives `maps:arena`. Type a namespace to move the world into another one.

### Finding Existing Worlds

Commands that take an existing world accept the bare name as well as the full one:

1. `maps:lobby` (or `minecraft:lobby`) always means exactly that world.
2. `lobby` finds the world called `lobby` in whichever namespace it is in, as long as only one world has that name.
3. If several worlds are called `lobby`, the one in `world.default-namespace` wins, then the one in `minecraft`. If neither has one, the command lists the full names to choose from (`worlds_world_ambiguous`), showing only the worlds you may use it on.

So changing `default-namespace` never cuts you off from old worlds; it only decides where new ones go. Tab completion suggests the shortest name that still finds the world: `lobby` while it is the only world with that name, `maps:lobby` once another namespace has a `lobby` too.

### Name Clashes

Paper gives the world `maps:lobby` the internal name `maps_lobby`. A world in `minecraft` that is really called `maps_lobby` would get the same internal name, so the two cannot exist side by side. Creating, importing or renaming a world to a name like that is refused with `worlds_world_name_clash`, which names the world it clashes with.

{% hint style="warning" %}
Spigot cannot create worlds outside `minecraft`, so any other namespace requires Paper. On Spigot, a namespaced name is refused, and `default-namespace` falls back to `minecraft` with a warning in the console. A namespace may only contain lowercase letters, digits, `_`, `-` and `.`, and cannot start with `.`.
{% endhint %}

Other places where namespaced worlds are written as `maps:lobby`:

* The default private-world permission `worlds.%world%` becomes `worlds.maps:lobby`.
* In `world.deletion-blacklist` and `world.unload.blacklisted-worlds`, an entry without a namespace always means `minecraft`, whatever `default-namespace` says, so changing the default cannot unprotect the main worlds. Both lists ignore case.
* `/worlds saveTemplate` without a template name names the template after the world without its namespace, so `maps:lobby` becomes the template `lobby`.

***

## Importing an Existing World Directory

If you have a world directory already present under the server root or container, you can adopt it as a BuildWorld:

* **Command**: `/worlds import <directory_name> [-g <generator>] [-c <creator>] [-t <type>]`. On Paper, `/worlds import maps:lobby` imports `world/dimensions/maps/lobby`. A name without a namespace is looked for in `world.default-namespace`.
  * `-g`: specify a custom chunk generator plugin for loading the world.
  * `-c`: register a player as the world's creator.
  * `-t`: set the world type, `IMPORTED` by default.

To import all unregistered directories at once, run `/worlds importAll [-g <generator>] [-c <creator>]`; the two flags can come in either order. On Paper this includes the worlds of every namespace under `dimensions/`, such as a datapack's dimensions. Imports are spread across ticks using the `import-all-delay` config option to avoid lag spikes.

***

## Configuring World Templates

Templates allow builders to spawn identical starting worlds quickly (e.g., standard layout grids).

### Method A: Runtime Command Export (New in 4.0.0)

You can convert any active world into a template directly in-game:

```
/worlds saveTemplate <world> [templateName]
```

This copies the target world's region files and database configuration into the `plugins/BuildSystem/templates/` folder under the specified `templateName`. The world's autosave is paused during the copy, and deleting, renaming or restoring the world is refused until it is done (`worlds_world_busy`).

### Method B: Manual File Placement

1. Stop the server.
2. Navigate to `plugins/BuildSystem/templates/`.
3. Paste your template world directory inside.
4. Start the server; the folder name will automatically register as an selectable template.

### Creating a World from a Template

A world created from a template in game is copied in the background, so a large template does not freeze the server. The player is teleported once the world is ready, if they are still online. While the copy runs, the new world's name is taken: it is left out of `/worlds import` and `/worlds importAll`, and importing it is refused with `worlds_world_exists`. If the copy fails, the partly copied folder is deleted. If the server stops during the copy, the half-copied folder stays behind and has to be deleted by hand.
