> 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/managing-worlds/custom-generators.md).

# Custom Generators

BuildSystem ships four generator types: `NORMAL`, `FLAT`, `VOID`, and `CUSTOM`. `CUSTOM` hands terrain generation to another plugin, so you can create worlds from Terra, Iris, TerraformGenerator, or anything else that exposes a Bukkit chunk generator.

***

## Referring to a Generator

A custom generator is named `PluginName:generatorId`.

```
Terra:OVERWORLD
Iris:overworld
```

If the plugin only provides one generator, or its default is the one you want, the plugin name on its own is enough. BuildSystem then uses that name for both halves.

```
Terra
```

The plugin must be installed and enabled. BuildSystem resolves the name against Bukkit's plugin manager at creation time, so a typo or a missing plugin fails the creation rather than quietly producing an empty world.

***

## Creating a World

{% tabs %}
{% tab title="In the GUI" %}

1. Open `/worlds` and click the create item.
2. Choose **Custom** as the world type.
3. Type the generator name when prompted.

The prompt accepts either form, `PluginName` or `PluginName:generatorId`.
{% endtab %}

{% tab title="From chat" %}
Importing an existing directory and telling BuildSystem which generator produced it:

```
/worlds import my_terra_world -g Terra:OVERWORLD
```

This matters for imports. If BuildSystem does not know the generator, unexplored chunks are generated by the default one, and you get a visible seam where the terrain style changes.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Use the same generator the world was originally created with. Changing it later, or importing with the wrong one, does not rewrite existing chunks. It only affects chunks generated from then on, which leaves a permanent border in the terrain.
{% endhint %}

***

## Restricting Who Uses Which

Every generator has its own permission, resolved from its name:

```
buildsystem.create.generator.<name>
```

These are **granted by default**, so generators work out of the box and you restrict by denying. Deny `buildsystem.create.generator.terra` and that generator disappears from the options for that player.

{% hint style="info" %}
This is deny-to-restrict, the opposite of most nodes in the plugin. The reason is that generator names are only known at runtime, so they cannot be declared up front in `plugin.yml` the way a fixed permission can.
{% endhint %}

The same model applies to [templates](/v4/getting-started/creating-a-world.md) through `buildsystem.create.template.<name>`.

***

## Void Worlds Without a Plugin

If you want an empty world to build in, you do not need a generator plugin. Choose the built-in **Void** type. BuildSystem places a single block at the spawn so the first player to join does not fall, which you can configure or switch off:

```yaml
world:
  void-block:
    enabled: true
    material: GOLD_BLOCK
```

The block is only placed when the world is first generated. It is never re-placed on later loads, imports, or renames, and it never replaces a block that is already there.

***

## Troubleshooting

**"Unknown generator" when creating.** The plugin name does not match an installed, enabled plugin. Check `/plugins` for the exact spelling, which is case-sensitive.

**The world generates as normal terrain.** The generator resolved to nothing and BuildSystem fell back. Confirm the generator plugin loaded without errors before BuildSystem did.

**A visible line where terrain style changes.** The world was generated by one generator and later loaded with a different one, or with none. Existing chunks keep their original terrain; only new chunks use the current generator.