Skip to content

BiomeWarps

Config-driven warp menus: each menu gets its own command, a paged chest GUI, and direct teleports. On main it runs /biome and /biomes, a browser of 173 biome warps.

What it does

  • Opens a 6-row chest menu of warp icons. Click an icon to teleport there.
  • Lets a player skip the menu with /<command> <warp>. Tab completion lists that menu's warps.
  • Supports any number of menus in one jar. Each menu has its own commands, permission, sort order, look, and warp list. For example, /biome and /tutorial can both live here.
  • Lets staff add, move, re-icon, and remove warps in-game, with no file editing.
  • Reloads safely. If a new config is bad, the last good config stays active.

The plugin is still named BiomeWarps (and keeps its plugins/BiomeWarps/ folder) so upgrades are safe, but it is no longer biome-only. It does not need Essentials, DeluxeMenus, ChatControl, PlaceholderAPI, or LuckPerms.

How players use it

Command What happens
/biome or /biomes Opens the biome warp menu at page 1
/biome jungle Teleports straight to the Jungle warp
/biome <Tab> Lists every warp key in that menu

In the menu, the arrows at the bottom change pages and the barrier closes it. Each icon shows the direct command for that warp. Items cannot be taken out of the menu.

Players need the menu's permission. The biome menu uses biomewarps.use, which everyone has.

Staff guide

Admin commands work on the menu whose command you typed. /biome add edits the biome menu, /tutorial add edits the tutorial menu. All need biomewarps.admin (op by default).

Task Command
Add a warp where you stand /biome add <key> [display name]
Move a warp to where you stand /biome setpos <key>
Change a warp's icon to the item in your hand /biome seticon <key>
Delete a warp /biome remove <key>
Reload all menus from config.yml /biome reload (needs biomewarps.reload)

Examples:

/biome add cherry_grove Cherry Grove
/biome setpos cherry_grove
/biome seticon cherry_grove

Rules:

  • Keys use only lowercase letters, numbers, and underscores.
  • reload, add, remove, setpos, and seticon cannot be warp keys.
  • add uses the item in your main hand as the icon. With an empty hand it uses a grass block.
  • You cannot remove the last warp in a menu.
  • add, setpos, and seticon must be run in-game. remove and reload also work from console.
  • Each edit writes config.yml, checks it, and goes live at once. If the check fails, nothing changes and you see "Could not save config.yml".

Test as a non-op when you change a menu's permission.

Configuration

File: plugins/BiomeWarps/config.yml. Edit it, then run /biome reload (any menu's command works). A restart is not needed. A rejected reload keeps the old config and logs the reason.

messages: holds the chat text. menus: holds one block per menu:

menus:
  tutorial:
    commands: [tutorial, guide]   # first label is the main command, the rest are aliases
    permission: biomewarps.use    # node needed to open the menu
    sort: config-order
    menu:
      title: "&8&lServer Tutorial &7(%page%/%pages%)"
      entries-per-page: 28        # 1 to 28
      header:
        name: "&6&lTutorial"
        lore:
          - "&7Choose a tutorial stop."
      command-lore: "&7Command: &f/%command% %warp%"
      click-lore: "&eClick to teleport"
    warps:
      getting_started:
        display-name: "Getting Started"
        description: "Learn the basics of the server"
        material: BOOK
        world: world
        x: 0.5
        y: 64.0
        z: 0.5
        yaw: 0.0
        pitch: 0.0
  • sort can be config-order (YAML order), alphabetical or reverse-alphabetical (by display name), or key or reverse-key (by warp key).
  • If permission is left out, the menu uses biomewarps.menu.<id>. That node is not declared, so only ops have it until you grant it in LuckPerms.
  • Menu text can use %menu%, %command%, %page%, %pages%, and %count%. Warp text and messages can also use %warp%.
  • material must be a real server material. Modded blocks work, for example BIOMESOPLENTY_RED_MAPLE_LEAVES.
  • description is optional. biome-id is the old name for the same field. As of 2.0.2 the value is loaded but not shown in the menu.
  • The shipped config includes a commented /tutorial example at the end.

A reload is rejected if: the YAML is invalid, a command label is used by another plugin or by two menus, a warp is missing world, x, y, z, or material, a material is unknown, a key is illegal or reserved, a sort name is unknown, or a menu has no warps.

Old configs. Version 1.0 and 1.1 configs, with a top-level menu: and biomes: section, still load as a biome menu with /biome and /biomes. You can add new menus under menus: (such as menus.tutorial) without moving the old biome entries. Do not also define menus.biome until the old top-level biomes: section is gone. Having both is rejected.

Data and storage

Everything lives in plugins/BiomeWarps/config.yml. The admin commands rewrite that file. There is no database and no player data.

The 173 shipped biome warps are 142 overworld, 18 nether (DIM-1), 6 End (DIM1), and 7 Ultra Space. Three duplicate biome names are split as coniferous_forest_bwg, orchard_bwg, and prairie_bwg, next to their Biomes O' Plenty versions.

Troubleshooting

Symptom Cause Fix
"Reload failed; the previous configuration is still active" Bad config Read the BiomeWarps reload rejected line in the console, fix that key, reload again
Plugin disables at boot with Could not load config.yml Bad config at startup Fix the key named in the log and restart
configured command /x is already owned by ... Another plugin owns that label Pick a different label, or remove it from the other plugin
Command /x was registered only with the biomewarps: namespace Label collision Same as above. /biomewarps:x still works
"The destination world for X is not loaded" The warp's world name is wrong or the world is unloaded Fix world (overworld is world, nether DIM-1, End DIM1)
After a reload, an old label still opens the old menu The server would not drop the stale label (logged as Could not drop stale command label) Restart to clear it
Players get "no permission" They lack the menu's permission node Grant it in LuckPerms, or use biomewarps.use
ChatControl or DeluxeMenus answers /biome instead Old pre-plugin rules still present Remove the ChatControl biome rules and the old DeluxeMenus biomes* pages

A good boot logs:

Loaded 1 warp menus with 173 destinations and 2 command labels.

Maintainer notes

  • Commands are registered from config into the server command map at startup and on every reload. They are not in plugin.yml, so the generated Reference below lists none.
  • Youer's known-commands map does not support removing entries through an iterator. Version 2.0.0 failed every /biome reload with the error "remove" because of this. 2.0.1 and later collect stale labels first and remove them by key, and treat a failed removal as a warning.
  • Menu icons and buttons are tagged with persistent data keys biomewarps:destination and biomewarps:action. All clicks and drags into the menu are cancelled.
  • History: 1.0.0 replaced a ChatControl plus DeluxeMenus plus Essentials warp setup. 1.1.0 added the admin commands. 2.0.0 made it multi-menu. Design notes and migration steps: documentation/plugins/biomewarps.md in the ops repo.
  • Unit tests cover multiple menus and aliases, alphabetical sort, duplicate-command and bad-sort rejection, loading a 1.1 config, and adding a menu next to it.
  • The 173 biome entries can be rebuilt without undoing the multi-menu layout with python3 scripts/biome_warps/build_biomes_menu.py (ops repo).

Building

./gradlew clean test build

Java 21. Output: build/libs/BiomeWarps-<version>.jar. Ignore bin/, which is IDE output.

Full command, permission and config tables: Reference.