MaskUI

MaskUI is a survival mask plugin for Paper servers. Players can purchase and equip masks that provide different effects for exploration, mining, combat, Nether travel, and general survival.

The plugin includes seven mask tiers, an inventory-based shop, Vault economy support, mask selling, and purchase tracking.

Features

• Seven masks with different effects and survival roles
• Inventory-based mask shop
• Right-click to equip masks from either hand
• Automatic effects while a mask is equipped
• Vault economy support
• Configurable prices and messages
• Mask selling with configurable refunds
• Purchase tracking to prevent duplicate refunds
• Persistent item tags for identifying real MaskUI masks
• Support for Minecraft 1.16.x–1.21.x

Masks

Every mask provides Night Vision I along with effects based on its intended role.

Tier	Mask	Default Price	Role
1	Skeleton	5,000	Exploration
2	Zombie	10,000	Durability and recovery
3	Creeper	15,000	Mobility and defense
4	Piglin	20,000	Nether exploration
5	Steve	25,000	Mining and building
6	Wither Skeleton	30,000	Combat
7	Dragon	35,000	All-round survival

Higher tiers provide greater overall power and utility, but each mask is designed around a specific role rather than simply inheriting every effect from the previous tier.

Use /mask wiki in-game to view the complete effect list.

Requirements

• Paper or Spigot 1.16.x–1.21.x
• Vault
• A Vault-compatible economy plugin, such as EssentialsX Economy

Mask purchases are disabled if Vault cannot find an economy provider. Other available commands and menus remain usable.

Installation

1. Download the latest MaskUI JAR.
2. Install Vault and a Vault-compatible economy plugin.
3. Place the plugin JARs in your server's plugins directory.
4. Start or restart the server.
5. Edit plugins/MaskUI/config.yml to customize the plugin.
6. Use /mask reload after changing the configuration.

Commands

Command	Description	Permission
/mask	Open the mask shop	maskui.command
/mask open	Open the mask shop	maskui.command
/mask shop	Open the mask shop	maskui.command
/mask wiki	View mask effects	maskui.command
/mask status	Show the equipped mask and its effects	maskui.command
/mask buy <mask>	Open purchase confirmation	maskui.command
/mask sell [mask]	Open the sell menu or preview an eligible mask	maskui.command
/mask help	Show available commands	maskui.command
/mask github	Show the source repository	maskui.command
/mask give <player> <mask>	Give a mask to an online player	maskui.admin
/mask reload	Reload prices and messages	maskui.admin

maskui.command is available to players by default. maskui.admin defaults to server operators.

Available mask IDs:

skeleton
zombie
creeper
piglin
steve
wither
dragon

Wearing Masks

Hold a MaskUI mask in your main hand or off-hand and right-click to equip it. The helmet slot must be empty.

One mask is moved into the helmet slot without duplicating the item, including in Creative mode. Masks can be removed normally through the armor slot.

Tagged MaskUI masks are not placed as blocks when right-clicked. Ordinary mob heads retain their normal vanilla behavior.

Mask effects are automatically applied while the mask is equipped. They are refreshed before expiring to prevent Night Vision flicker and are removed shortly after the mask is removed or replaced.

Existing external potion effects are not removed by MaskUI.

Selling Masks

Masks purchased through the MaskUI shop can be sold using:

/mask sell
/mask sell <mask>

By default, eligible masks receive a 50% refund based on the price originally paid.

For example, a Skeleton mask purchased for 5,000 will refund 2,500 even if its shop price changes later.

Selling can be configured in config.yml:

selling:
  enabled: true
  refund-percent: 50

The refund percentage must be greater than 0 and no greater than 100. Invalid values disable refunds.

Only masks with a valid purchase record are eligible for refunds. Free masks, masks obtained through /mask give, ordinary mob heads, and older untracked masks cannot be sold.

Any player holding a purchased mask may sell it. The seller does not need to be the original buyer.

Each purchase receives a unique receipt, so duplicated items with the same purchase ID cannot generate additional refunds.

Transaction Safety

MaskUI tracks purchases and sales to reduce the risk of duplicated items or refunds.

Purchase eligibility, balance, inventory space, price, item receipts, and refund values are checked again during confirmation.

If an economy provider normally rejects a refund, the mask and its selling rights are restored.

Transactions with an uncertain result, such as an interruption during an economy operation, are not automatically retried. This prevents the same receipt from being redeemed twice.

Detailed recovery procedures for server administrators are available in the project documentation.

Configuration

Mask prices can be configured individually:

masks:
  skeleton:
    price: 5000
  dragon:
    price: 35000

Messages and other plugin behavior can also be customized through config.yml.

Messages support legacy & color codes. Purchase messages support the {mask} and {price} placeholders.

Minecraft Compatibility

MaskUI is designed to support Minecraft 1.16.x–1.21.x from a single JAR.

The plugin uses:

• api-version: 1.16
• Spigot 1.16.1 as the baseline compile API
• Java 8-compatible plugin bytecode
• Compatibility handling for potion effect names across versions
• A Player Head fallback for the Piglin mask on versions without a native Piglin Head

Run the Java version required by your Minecraft server.

A complete runtime test matrix across every Paper and Spigot release in the supported range has not yet been completed. Compilation against the baseline API does not guarantee compatibility with every individual server build.

Credits

MaskUI is developed by SkulZOnTheYT and maintained under LEAP.

Based on the original MaskShop concept by misael38.