permissions.md

Permissions

HeadDB provides broad permission bundles and granular command or GUI nodes.

Recommended setup

Players: headdb.basic
Staff:   headdb.admin

headdb.admin bypasses individual HeadDB permission checks and should only be granted to trusted administrators.

Top-level bundles

Permission	Purpose
headdb.admin	Grants complete HeadDB access.
headdb.basic	Grants normal player access, including GUI, browse, search, favorites, taking heads, category access, and language settings.
headdb.open	Opens the root GUI.
headdb.browse	Browses categories and result GUIs.
headdb.search	Uses search and browse-list commands.
headdb.head.take	Takes heads from GUIs.
headdb.give	Gives remote heads to yourself.
headdb.give.others	Gives remote heads to other players.
headdb.player-heads	Uses player-head functionality for yourself.
headdb.player-heads.others	Gives other players' heads or targets another recipient.
headdb.favorites	Uses favorites.
headdb.settings	Opens player settings and language selection.
headdb.admin-mode	Toggles Admin Mode.
headdb.head-edit	Edits local metadata overrides.
headdb.gui-admin	Uses GUI administration tools.
headdb.database	Uses database, diagnostics, reload, report, update, and item-cache administration.

Some existing bundle names retain the legacy more-heads and more-categories wording for compatibility:

Permission	Current feature
headdb.more-heads	Views Custom Heads.
headdb.more-heads.give	Gives Custom Heads to yourself.
headdb.more-heads.give.others	Gives Custom Heads to other players.
headdb.more-heads.admin	Creates, edits, publishes, and deletes Custom Heads.
headdb.more-categories	Views Custom Categories.
headdb.more-categories.admin	Creates, edits, publishes, and deletes Custom Categories.

Do not rename these permission nodes in a permissions plugin; the legacy identifiers remain the active compatibility contract.

Category permissions

headdb.category.*
headdb.category.<category-id>

Category permissions control visibility for remote and Custom Categories.

headdb.basic, headdb.admin, or headdb.category.* grants access to all categories. A category-specific node does not independently grant permission to open HeadDB, browse results, use commands, or take heads.

Example restricted setup:

headdb.open
headdb.browse
headdb.search
headdb.head.take
headdb.category.blocks
headdb.category.helmets

Command permissions

Permission	Command or capability
headdb.command.help	/hdb help
headdb.command.version	/hdb version
headdb.command.status	/hdb status
headdb.command.debug	/hdb debug
headdb.command.report	/hdb report
headdb.command.verify	/hdb verify
headdb.command.refresh	/hdb refresh
headdb.command.reload	/hdb reload
headdb.admin.update	/hdb update
headdb.command.search	/hdb search and search subcommands
headdb.command.info	/hdb info
headdb.command.give	/hdb give for yourself
headdb.command.give.others	/hdb give targeting others
headdb.command.open	/hdb open for yourself
headdb.command.open.others	/hdb open targeting others
headdb.command.player	/hdb player for yourself
headdb.command.player.others	Player-head operations involving others
headdb.command.itemcache	/hdb itemcache
headdb.command.custom.list	Lists Custom Heads
headdb.command.custom.info	Inspects Custom Heads
headdb.command.custom.create	Creates Custom Heads
headdb.command.custom.delete	Deletes Custom Heads
headdb.command.custom.rename	Renames Custom Heads
headdb.command.custom.give	Gives Custom Heads to yourself
headdb.command.custom.give.others	Gives Custom Heads to others
headdb.command.tags.create	Creates custom tags
headdb.command.tags.delete	Deletes custom tags
headdb.command.collections.create	Creates custom collections
headdb.command.collections.delete	Deletes custom collections

Metadata editing permissions

Permission	Capability
headdb.command.edit	Opens the editor.
headdb.command.edit.name	Changes a local head name.
headdb.command.edit.lore	Changes local lore.
headdb.command.edit.tags	Changes tags and collections.
headdb.command.edit.category	Changes the local category assignment.
headdb.command.edit.visibility	Hides or restores heads.
headdb.command.edit.reset	Resets local overrides.

GUI permissions

Permission	Capability
headdb.gui.main	Opens the main menu.
headdb.gui.browse	Opens head result menus.
headdb.gui.browse.menu	Opens the Browse menu.
headdb.gui.search	Uses GUI search.
headdb.gui.search.advanced	Uses Advanced Search.
headdb.gui.filter	Uses sort and filter menus.
headdb.gui.filter.ids	Filters by head IDs.
headdb.gui.filter.categories	Filters by categories.
headdb.gui.filter.tags	Filters by tags.
headdb.gui.filter.collections	Filters by collections.
headdb.gui.head.take	Takes heads from GUIs.
headdb.gui.category.view	Sees category entries.
headdb.gui.category.open	Opens categories.
headdb.gui.player-heads	Opens Player Heads.
headdb.gui.custom-heads	Opens local Custom Heads administration.
headdb.gui.favorites	Opens Favorites.
headdb.gui.favorites.toggle	Adds or removes favorites.
headdb.gui.collections	Opens Collections.
headdb.gui.tags	Opens Tags.
headdb.gui.create-head	Creates Custom Heads.
headdb.gui.create-tag	Creates custom tags.
headdb.gui.create-collection	Creates custom collections.
headdb.gui.more-categories	Views Custom Categories; legacy node name.
headdb.gui.more-categories.admin	Administers Custom Categories; legacy node name.
headdb.gui.hidden-heads	Opens Hidden Heads.
headdb.gui.edit	Uses the GUI head editor.
headdb.gui.button-config	Configures supported GUI buttons.
headdb.gui.settings	Opens Settings.
headdb.gui.settings.language	Changes language.
headdb.gui.admin-mode	Uses Admin Mode controls.