Key Serialization

Key Serialization

Add-on

Give every physical crate key its own hidden serial and remove duplicated copies wherever they turn up.

View as Markdown ·

On this page

#Information

The Key Serialization add-on stamps every physical crate key with a unique serial stored in the item's hidden data. Players never see it. Once a key opens a crate, its serial is spent, and any other copy carrying that serial is deleted the moment it is found. Duplication glitches, creative copies and NBT-edited keys stop being worth anything.

Because every key is unique, serialized keys no longer stack. Giving 10 keys fills 10 slots, and anything that does not fit is dropped at the player's feet the same way a full inventory always is.

You can buy this add-on on Phoenix Plugins

#Installation

To install this add-on, you can either:

  • Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server.
  • Download the plugin with the add-on selected during the downloading.

circle-exclamation

The add-on requires the Premium edition. Virtual keys are not affected, since they never exist as items.

#How It Works

  • Giving keys. Every physical key handed out by a command, a reward, a refund or an offline delivery gets a fresh serial, which is saved to the plugin's database.
  • Opening a crate. The serial of the key used is marked as spent before any reward is given. If that serial was already spent, for example by a copy used a moment earlier, the opening gives no rewards.
  • Finding copies. A copy whose serial is spent, revoked or was never handed out is removed when a player joins, clicks it, moves it, drags it, swaps it to the hotbar, drops it, picks it up, opens a chest holding it, or a hopper tries to move it. Two copies of the same serial found together, including a stack of two, are cut down to one.
  • Old keys. Keys given out before the add-on was installed get a serial the first time they show up in a player's inventory, so nothing a player already owns is lost.

When a copy is removed, the player is told, staff with the alert permission get a message naming the player, the key, the serial and where it was found, the console logs it, and a Discord webhook can receive it as an embed.

#Networks

On MySQL, MariaDB or PostgreSQL every server sharing the database also shares the serials. A key used on one server dies on all of them within the sync interval, and the database itself refuses to spend the same serial twice, so two servers can never both pay out for one key. On SQLite the serials stay on the one server.

#Commands

Command Description Permission
/crates serial check Shows the history of the key you are holding: who it was given to and when, and who used it, when and on which crate. phoenixcrates.command.serial
/crates serial lookup <serial> Shows the same history for any serial. phoenixcrates.command.serial
/crates serial revoke <serial> Spends a serial by hand, so every copy of that key is removed when found. phoenixcrates.command.serial

Taking keys with /crates takeKey revokes their serials too, so copies of the taken keys die as well.

#Permissions

Permission Description
phoenixcrates.keyserialization.alerts Receive a message whenever a duplicated or invalid key is removed.

#Settings

circle-info

The settings live in PhoenixCrates/key-serialization.yml. The switches, the checks and the Discord webhook can also be changed in game from Editor > Add-ons > Key Serialization.

Setting Default Description
enabled true Turns every check off without uninstalling the add-on.
serialize-old-keys true Gives a serial to keys handed out before the add-on was installed.
notify-player true Tells a player when a duplicated key is removed from them.
alert-staff true Sends removals to staff with the alert permission.
checks.containers true Checks chests, barrels, shulker boxes and other containers when they are opened.
checks.hoppers true Stops hoppers from picking up or moving dead copies.
checks.dropped-items true Stops dead copies from appearing as dropped items.
checks.ender-chest-on-join true Also checks the ender chest when a player joins.
discord.webhook-url empty A Discord webhook that receives an embed for every key caught: the player, key, serial, where it was found, who it was given to and who used it first. Empty turns it off.
discord.username PhoenixCrates The name the webhook posts under.
discord.server-name Server Shown in the footer, so a network can tell its servers apart.
discord.color 12131840 The embed color as a decimal number.
discord.batch-seconds 5 Alerts are collected and posted together this often, up to 10 per message.
discord.per-minute 20 The most messages posted in one minute. Alerts over the limit wait for the next slot.
discord.max-queued 200 The most alerts kept waiting. Older ones are skipped beyond this, and the next message says how many.
performance.network-sync-interval-seconds 5 How often a server reads serials used or given out on other servers.
performance.network-sync-clock-margin-seconds 30 How far back each sync looks, to cover clocks that differ between servers.
performance.unknown-serial-recheck-seconds 10 How long a serial the database does not know is given before it is treated as forged, so a key given out on another server a moment ago is never removed by mistake.
performance.dead-serial-cache-size 10000 How many spent serials each server remembers before it has to ask the database again.
performance.lookup-batch-size 500 How many serials are looked up in one database query.
performance.write-retry-seconds 30 How long a database write is retried before giving up.
performance.key-material-refresh-seconds 30 How often the add-on rereads which materials your keys use.
performance.join-scan-delay-ticks 40 How long after joining the player's inventory is checked, so inventory sync plugins finish first.

circle-info

Only items made of a material one of your keys uses are ever read, so the checks cost almost nothing for every other item.

My Cart
Spider

Your cart is empty

Looks like the spiders padded through here. Pick a plugin and it will show up here. Continue shopping