Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Custom Statuses & Categories

Define your own workflow stages and navigator tabs.

In BuildSystem 4.0, world statuses and navigator categories are dynamic registries configured via /setup or configuration files.

Two ideas are worth getting straight first:

  • A status is the state a world is in, such as In Progress or Finished. Every world has exactly one.

  • A category is a tab in the /worlds navigator. A category does not own worlds, it selects them, by listing the statuses and visibilities it wants to show.

So you never put a world into a category. You give the world a status, and every category listing that status shows it.

Common Tasks

Recipes for what most servers want on day one. Everything here happens in /setup, which needs buildsystem.setup. The reference model starts at §1.

Say you want a Needs Review stage between Almost Finished and Finished.

  1. Run /setup and open World Statuses.

  2. Click the create button and type Needs Review. The id becomes needs_review.

  3. Shift-click the new status to open its editor. Set the colour, icon, and an order of 4 so it sorts before Finished.

  4. Drag it from the palette in your inventory into an empty slot in the preview grid above. That grid is the /worlds setStatus picker exactly as builders will see it.

Grant buildsystem.setstatus.needs_review to whoever should be able to assign it.

A new status joins the default category automatically, so it appears in the navigator right away. Edit that category's member statuses if you want it somewhere else.

Say you want an Events tab holding only event builds.

  1. Create a status for them first, for example event. A category with no statuses shows nothing.

  2. Run /setup and open Navigator Layout.

  3. Click the create category button and name it Events.

  4. Right-click the new category to open its editor. Under member statuses add event, and under visibilities pick who it covers, normally EVERYONE.

  5. Drag it from the palette into the navigator preview to choose its tab position.

The tab is now live, and so is a /worlds events shortcut generated from the category id.

There is no "hidden" flag on a world. A world disappears from the navigator when no category lists its status.

That is exactly how the built-in hidden status works. Nothing lists it, so setting a world to hidden takes it out of every tab while leaving it fully usable for anyone who teleports to it directly.

To hide a group of worlds, give them a status no category lists.

Turn off building allowed on the status, not on the world.

  1. /setup → World Statuses → shift-click the status.

  2. Toggle building allowed off.

Every world carrying that status is now read-only. The built-in archive status already works this way. buildsystem.bypass.archive lets staff build anyway, and it covers every status with building disabled, not only archive.

A status can move a world forward the first time someone edits it.

In the status editor, set progresses to. The built-in not_started points at in_progress, so a fresh world flips to In Progress the moment the first block changes and nobody has to remember to set it.

Leave it empty for a status that should not move on its own.

1. Core Concepts

1.1 Custom World Statuses (BuildWorldStatus)

Statuses define progress state and behavior. Each status object contains the following properties:

Property
Description

id

Unique lower-case key (e.g., in_progress). Persisted in configuration files.

displayName

Display name in menus and chat. Supports standard color codes.

color

Color prefix applied to the status.

icon

XMaterial shown in selection menus.

order

Sorting weight (lower numbers appear first in lists).

permission

Dynamic Permission: Node required to assign this status (see below).

buildingAllowed

Set false to block block place/break changes in carrying worlds.

progressesTo

Optional status ID target for auto-progression on first block edit.

statusSlot

Slot (0-26) the status occupies in the /worlds setStatus picker, set in the status editor.

shownInStatusMenu

Whether the status appears in the picker. Hidden statuses wait in the editor's palette.

builtIn

Identifies seeded default statuses. Built-ins can be edited or deleted; the flag controls default re-seeding on reset.

Dynamic Status Permissions

To change a world's status, a player requires a dynamic permission node derived from the status id:

  • Built-in statuses keep their legacy node with underscores removed. For example in_progress → buildsystem.setstatus.inprogress.

  • Custom statuses use their full id, so my_status → buildsystem.setstatus.my_status.

This keeps existing permission setups working while guaranteeing two custom statuses can never collapse onto the same node.

Universal Archive Bypass

A single bypass node covers all statuses where buildingAllowed is false: buildsystem.bypass.archive

1.2 World Visibility (Visibility)

  • EVERYONE: Public worlds visible to all players.

  • ADDED_PLAYERS: Restricted worlds visible only to the creator and whitelisted builders.

1.3 Navigator Categories (NavigatorCategory)

Categories define navigator menu tabs. They group worlds by visibility and status.

Property
Description

id

Unique lower-case key (e.g., public). Referenced by folders and layouts.

displayName

Title shown on the navigator tab item.

color / icon

Styling in menus.

visibilities

Allowed visibilities grouped (EVERYONE, ADDED_PLAYERS, or both).

statusIds

List of status IDs grouped in this category.

shownInNavigator

Set true to render this category as a tab in the /worlds menu.

navigatorSlot

Tab position (0-26) in the navigator GUI.

builtIn

Identifies seeded default categories. Built-ins can be edited or deleted; the flag controls default re-seeding on reset.

Per-Category Commands & Visibility

Every category gets a /worlds <id> command shortcut that opens its tab, generated from the navigator. Creating a category adds its command, and deleting one removes it. The dynamic permission buildsystem.navigator.category.<categoryId> controls both the shortcut and whether the tab shows in the navigator. It is granted by default, so denying it hides a category and disables its command together. If a category id matches a real subcommand (e.g. delete), the subcommand always wins the name and the shortcut is dropped.

2. Default Configurations

Built-in statuses and categories seeded on first plugin boot:

Built-in Statuses (statuses.yml)

ID
Display Name
Color
Icon
Order
Block Modify
Auto-Progress

not_started

Not Started

&c (Red)

RED_DYE

1

Allowed

in_progress

in_progress

In Progress

&6 (Gold)

ORANGE_DYE

2

Allowed

None

almost_finished

Almost Finished

&a (Green)

LIME_DYE

3

Allowed

None

finished

Finished

&2 (Dark Green)

GREEN_DYE

4

Allowed

None

archive

Archive

&3 (Aqua)

CYAN_DYE

5

Blocked

None

hidden

Hidden

&7 (Gray)

BONE_MEAL

6

Allowed

None

A status is shown in the navigator purely through category membership. There is no per-status visibility flag. The built-in hidden status stays out of the navigator simply because no built-in category lists it (see §3).

Built-in Categories (categories.yml)

ID
Display Name
Color
Icon
Visibilities
Grouped Statuses
Slot

public

Worlds

&b

PLAYER_HEAD

EVERYONE

not_started, in_progress, almost_finished, finished

11

archive

Archive

&3

PLAYER_HEAD

EVERYONE, ADDED_PLAYERS

archive

12

private

Private

&a

PLAYER_HEAD

ADDED_PLAYERS

not_started, in_progress, almost_finished, finished

13

public is the default category and not_started is the default status. The last remaining status can't be deleted, so a world always has a valid status to fall back to. Categories have no such guard, so you can delete every one, leaving the navigator empty until you reset to defaults.

3. World-to-Category Mapping Logic

When the /worlds navigator renders, it filters and groups worlds dynamically:

  • Inclusive Membership: A world is grouped by a category if its visibility and status ID are listed. A world appears in every category that groups it. If tabs overlap, the world is listed under all matching categories simultaneously.

  • Primary Category: If a world must resolve to a single category (e.g. choosing which folder a new world is saved under by default), the plugin assigns the first matching category based on the navigator slot layout, or falls back to the default public category.

If a world's status is not listed in any category, it is excluded from navigator listings. This is exactly how the built-in hidden status works. No category groups it, so worlds set to hidden never appear in the navigator.

4. Custom Skull Textures & %viewer%

Categories, worlds, and folders support custom player head skin textures when their icon material is set to PLAYER_HEAD.

  • Viewer's Head (%viewer%): Renders the head of the player viewing the menu.

  • Custom Skins: Renders specified base64 skin textures, UUIDs, or usernames.

  • Default Fallbacks: If blank or absent, heads resolve asynchronously:

    • Private Worlds: Renders the world creator's skin.

    • Public Worlds: Renders a head matching the world's folder name.

    • Categories: Renders the viewer's head for private groupings, or a standard navigator skin for public tabs.

5. Deleting & Resetting Safeguards

  • Deleting a Status: Drop it onto the delete target in the status editor. Worlds carrying it are reassigned to the default status (not_started), and the id is pruned from every category's status list. The last remaining status can't be deleted.

  • Deleting a Category: Drop it onto the delete target (textured skull) in the navigator editor. Because statuses are shared, worlds re-route to another matching tab (or the default) on the next render, and folders pinned to the category are re-homed to the default. Any category can be deleted, including the last. The navigator then stays empty until you reset to defaults.

  • Resetting to Defaults: Each layout editor has a reset control. Left-click resets only the layout (built-in entries return to their default slots; custom entries are kept but removed from the menu). Right-click resets everything, restoring any deleted built-in statuses or categories. Deleting statuses.yml and categories.yml and restarting achieves the same full reset.

6. The In-Game Setup Menu (/setup)

Administrators with buildsystem.setup permission can edit registries directly in-game. The hub branches into three configuration panels:

6.1 Default World Icons

Sets default item representation used for Normal, Flat, Nether, End, or Void worlds upon creation. Features a reset control.

Setup GUI Hub

6.2 World Statuses

The status editor is the drag-and-drop counterpart of the Navigator Layout Editor (§6.3): the top inventory is a live preview of the /worlds setStatus picker, and your own inventory holds the controls plus a palette of statuses not currently in the picker. This is where the picker's appearance is configured.

  • Arrange: Pick a status up from the preview or palette and drop it onto a slot to place it; drop it outside the preview to take it out of the picker.

  • Create / Edit / Delete: Click the create button to name a new status, shift-click a status to open its property editor, or drop a status onto the delete target to remove it.

  • Property editor: Name, color (dye picker), icon (item picker), order, the buildingAllowed toggle, and the auto-progression target a world advances to on first edit. Toggle items show their state in the lore (e.g. Currently: Enabled/Disabled) and glint when active.

6.3 Navigator Layout Editor (Drag & Drop)

Handles positioning, tab properties, category creation, and deletion in a single screen. The top inventory displays a live 27-slot preview of the navigator.

  • Category Creation & Edits: Click the create category button (textured skull) to register a new category. Right-click any category to open its property editor (name, color picker, skull textures, grouped visibilities, member statuses listed in order, and slot).

  • Inventory snapshotting: Player inventories are snapshotted and cleared, then replaced with menu controls (available categories, back button, delete category skull, and layout pins). Real inventories are restored when the GUI closes, the player disconnects, or the server stops.

  • Drag-and-Drop Placement: Click a category in the palette to pick it up, and click a preview slot above to place it. While held on the cursor, the category previews as a design-color glass pane. Dropping a category outside the preview removes it from the layout (returns it to the palette). Clicking is cancelled, protecting control items.

  • Settings Button: The settings gear button is part of the layout. It can be moved, dropped outside to remove it from the navigator, or re-added from the palette. A settings slot value of -1 hides it.

Navigator Layout Editor

7. Shared GUI Components

The /setup editors share the following GUI components:

  • 16-Color Dye Picker: Opens a panel of dye swatches sorted by color family, corresponding 1:1 to legacy chat codes. Selection carries an enchant glint. Click "Back" to return to the editor.

    Color Picker Panel

  • Item Picker Grid: Displays every obtainable Minecraft item. The left 8 columns show items, and the 9th column houses scrolling navigation arrows (scrolls one row at a time). The name filter searches both raw material keys (e.g. minecraft:stone) and display names. Item names in the grid are colorized.

  • Player Head Customizer: Right-click the icon control item to input a base64 texture, viewer, or none.

PreviousThe World EditorNextOrganizing Folders

Last updated