Custom Statuses & Categories

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

---

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 — e.g. in_progress → buildsystem.setstatus.inprogress.

• Custom statuses use their full id — e.g. 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 — so creating a category adds its command and deleting one removes it. The dynamic permission buildsystem.navigator.<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	—
almost_finished	Almost Finished	&a (Green)	LIME_DYE	3	Allowed	—
finished	Finished	&2 (Dark Green)	GREEN_DYE	4	Allowed	—
archive	Archive	&3 (Aqua)	CYAN_DYE	5	Blocked	—
hidden	Hidden	&7 (Gray)	BONE_MEAL	6	Allowed	—

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 — 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.