Timed award modifier keys

Award modifier keys are configured, signed items that activate a temporary XP multiplier for one player. Templates are empty by default, so the feature has no effect until a server configures and issues a key. Issued keys contain a snapshot of the template and remain redeemable with that snapshot even if the server later edits or disables the template.

Configure a key template

Add an entry under award-modifiers.keys in config.yml:

award-modifiers:
  keys:
    miner-boost:
      enabled: true
      material: AMETHYST_SHARD
      name: "&bMiner's Surge"
      lore:
        - "&7A temporary Mining XP boost."
        - "&7Right-click to activate."
      duration-seconds: 1800
      duration-clock: wall-clock
      multiplier: 1.5
      minimum-global-rank-score: 0
      minimum-global-rank-tier: ""
      maximum-global-rank-tier: ""
      scope:
        general: false
        skills: [mining]
        activities: []

Key IDs are stable identifiers used in commands and reward config. Use lowercase letters, digits, _, or -, beginning with a letter or digit. Validate templates at startup: invalid values, unknown scope IDs, or invalid rank-tier bounds disable that template and produce a warning. Keep IDs and Global Rank tier IDs stable once configured in rewards or issued.

duration-seconds must be a whole number from 1 to 2,592,000 (30 days). The multiplier must be greater than 1× and at most 10×. The only supported duration-clock is wall-clock: time continues to pass while the player is offline and through server restarts. Key definitions are validated at startup; restart Paper after editing config.yml.

The optional Global Rank gates are inclusive. minimum-global-rank-score requires at least the configured score. minimum-global-rank-tier and maximum-global-rank-tier use IDs under global-rank.tiers; the player must be at or above the minimum tier and at or below the maximum tier. The bounds are checked when the key is activated and do not change the effect after activation. A key can combine a score bound with either or both tier bounds.

Scope selects which positive XP awards are multiplied:

• scope.general: true includes General XP; this is independent of skill scope.
• scope.skills selects skill IDs. Omitting it selects all skills; [] selects none; [all] selects all skills by itself.
• scope.activities optionally filters Skill XP to activity IDs under the selected skills. An empty list includes all activities in those skills. It does not filter General XP.

Multipliers apply before existing per-award and daily caps. They compose multiplicatively with the tool-tier modifier. They do not multiply XP losses or penalties. Test reward loops and Global Rank thresholds together if boosts also reward players with more keys.

The server generates a signing secret in its key-store metadata. Back up progression-keys.yml when using YAML storage, or the key-store database table when using SQL, together with the rest of the progression data. Losing or replacing this secret invalidates previously issued keys; do not copy signed keys or the signing metadata between independent server stores unless the stores represent the same server.

Issue, claim, and activate

Staff can issue keys to an online recipient:

/mcpadmin keys give <player> <id> [amount]

The optional amount is 1–64. The command creates durable mailbox deliveries; it does not drop items into the world. The player claims pending items with /mcp keys claim; any entries that do not fit remain in the mailbox for a later claim. Staff need mcprogression.admin.keys.give. The current command requires the target to be online; there is no offline-target grant command. Mailbox entries persist while their recipient is offline, and claiming requires the player to be online and run the command.

Rank rewards of type: key also create mailbox deliveries, so a full inventory does not lose the reward. The player claims them using the same command. A rank reward claim and its mailbox issuance are committed together and are idempotent per player, tier ID, and reward ID. If the store is unavailable during a reward transition, the plugin retries while the player is online and rechecks eligible key rewards on their next join. Keep both IDs stable after players can cross the tier.

Right-click a key to activate it. The effect snapshots the issued name, scope, multiplier, rank gates, and duration. A player can have one active effect; another key is rejected without being spent. Rank gates are checked at activation. /mcp keys shows the active effect and remaining time.

The key store commits the spent nonce, active effect, and audit event before the plugin removes the item. If that commit fails, activation fails and the item remains. If the server crashes after the commit but before item removal, the item may remain, but its signed nonce is already spent and cannot activate again. The plugin checks the player's inventory after activation and on join, and removes signed items whose nonce is already spent. Repeated signed copies can deliver at most one activation.

Mailbox delivery inserts items into inventory and then acknowledges the mailbox entries. If acknowledgement fails or the server crashes in that interval, a later claim may issue a duplicate signed item. Duplicate copies share the same nonce, so only one can ever activate. Inventory overflow is retained in the mailbox rather than dropped.

Staff inspection and recovery

Staff with mcprogression.admin.keys.status can inspect an online player's active effect:

/mcpadmin keys status <player>

Staff with mcprogression.admin.keys.revoke can clear an active effect:

/mcpadmin keys revoke <player>

Revocation stops future boosted XP; it does not restore the spent item or remove unclaimed keys from the mailbox or player inventories. To address an accidental issue, revoke the active effect if appropriate, then coordinate a separate reissue. There is no command to recall issued items or refund spent nonces.

Staff with mcprogression.admin.keys.audit can read the latest key events:

/mcpadmin keys audit [page]

The audit retains the latest 500 events. It records grants, activations, expiry, and revocation, including the player UUID and name where available, actor, key ID, time, expiry, and activation multiplier/rank score where applicable. Expiry follows wall-clock time; the expiry audit is written when the service observes the ended effect, usually during its periodic refresh or a status/award check, so the event may be recorded shortly after the displayed timer reaches zero. The audit is for staff investigation; XP history remains aggregated and does not record every boosted award or identify which key affected it. Audit entries and spent nonces are separate from player profile resets.

Resetting a player's profile clears their active modifier and records the reason in the key audit. It does not delete spent-token records, mailbox deliveries, key audit events, or rank reward claims. This prevents replay and duplicate rank rewards after a reset. Reset is not a way to reclaim a key or re-earn its reward.

Persistence and limits

Key active state, mailbox deliveries, spent-token hashes, signing metadata, reward claims, and the bounded audit use a dedicated key store, separate from resettable XP/profile snapshots. SQL backends create dedicated prefixed key tables; YAML uses progression-keys.yml. Key-store operations run asynchronously. Spent nonce records and reward claim IDs are retained indefinitely; mailbox entries remain until delivered and acknowledged; the audit retains only the latest 500 events. There is no in-plugin purge or signing-secret rotation command. Keep backups of the key store and progression data, and monitor database failures in server logs.

The store and Minecraft inventory cannot participate in one shared transaction. The commit and acknowledgement rules above make interruption outcomes replay-safe, but a crash can still leave a duplicate unusable item in inventory or a duplicate signed item after mailbox acknowledgement failure. Keep the key store and its signing secret in the same backup/restore set; restoring only one side can invalidate keys or lose mailbox/activation state.

Permissions

Key actions have separate permissions, all defaulting to false, including for operators:

mcprogression.admin opens the admin menu but does not grant these actions. Players can check their own status and claim their own mailbox items without staff permissions. See permissions and command UX for role examples.