entitlements and badges

Entitlements and badges

Entitlements turn persistent player facts into permissions and visible badges. Definitions live under entitlements in config.yml.

Lifecycle

• A definition without when is manual and is only changed by an administrator.
• A definition with when, but no condition duration, is permanently retained after it is first earned.
• A definition containing a duration such as 28d is recalculated as a rolling entitlement and removed when its conditions are no longer met.
• Every configured condition must be true. An administrator grant overrides calculation until it is explicitly revoked.
• An administrator revocation is persisted and suppresses future automatic grants until an administrator grants it again.

Supported conditions include a singular when.stat, a when.stats list, when.quest-completed, when.quests, when.quests-completed.at-least, and when.permissions.

entitlements:
  definitions:
    bridge-hot-streak:
      when:
        stat:
          key: minigame_bridge_wins
          at-least: 10
          duration: 28d
      grants:
        permissions: [stemcraft.bridge.hot-streak]
        badges: [bridge-hot-streak]

Badge display

{badge} displays every applied badge in descending priority order. {badge-3} displays at most the three highest-priority badges. Badge placeholders work in the STEMCraft TAB name format. PlaceholderAPI exposes %stemcraft_badge% and %stemcraft_badge:3%. Bundled badges render directly beside one another; entitlements.badge-display.separator can add a custom separator.

/badges [player] displays only badges currently applied to that player and their descriptions. It does not reveal locked or potentially earnable badges. Bundled badge displays use resource-pack glyph tokens such as :trophy: rather than Unicode emoji. Custom badge displays may use any registered glyph token; legacy bundled symbols are translated at runtime without replacing administrator-customized displays.

Administration

The administrative command requires stemcraft.entitlements.admin.

/entitlements list
/entitlements reload
/entitlements recalculate <player>
/entitlements grant <player> <entitlement>
/entitlements revoke <player> <entitlement>
/entitlements create <id>
/entitlements delete <id>
/entitlements set <id> <field> <value>
/entitlements badge grant <player> <badge>
/entitlements badge revoke <player> <badge>
/entitlements badge create <id>
/entitlements badge delete <id>
/entitlements badge set <id> <field> <value>

Convenience entitlement fields are stat, at-least, duration, quest, quests-at-least, badges, permissions, and manual. Use manual true to remove the complete when block, - to remove an individual field, or none to clear a badges/permissions list. Badge fields correspond directly to configuration keys: display, description, permission, and priority.

Generated permissions are placed in LuckPerms groups named stemcraft-entitlement-<id>. This keeps STEMCraft reconciliation separate from rank and permission nodes managed directly by administrators.

Manual-only award repair

Definitions without effective requirements are manual-only, including an empty when section. Reading an optional stat condition no longer creates when.stat. Previously, that read could turn the manual event-winner definition into an unconditional automatic award and write its badge permission directly to each player's LuckPerms data.

On enable and reload, STEMCraft removes saved entitlements whose source is exactly calculated when their current definition is manual-only. It retains manual and other explicit grant sources, direct badge awards, and calculated awards with actual conditions. The repair does not add revocations, so an affected player can legitimately earn a manual award later. A server log entry reports the number of removed entitlement rows.

Tracked plugin-managed LuckPerms permissions are reconciled with the remaining awards. Permissions still needed by a direct badge or another entitlement remain; external grants not recorded as plugin-managed are not removed. Cleanup also retries tracked permissions on subsequent enable/reload if LuckPerms was unavailable previously.

A later external grant of the exact same permission cannot be distinguished from an existing plugin-managed node. For legitimate winners, record an explicit manual badge or entitlement award through STEMCraft rather than relying on that accidental node. This repair does not change OP-based badge visibility; OP must still be disabled if admins should only display earned or explicitly granted badges.