04 Commands and Unlocking

Commands & Unlocking

Registering a skin (datapack) and giving it art (resource pack) makes it exist. This page is about how a specific player actually comes to own it, and what they can do with ownership once they have it.

Ownership, in short

Every player has a personal, persistent set of unlocked skin IDs (it survives death, and syncs to their client automatically whenever it changes, or whenever they log in, respawn, or change dimension). A skin ID being in that set is the only thing that makes a skin "owned" — there's no other requirement. The automatic default:<base_gun> entry for every weapon (see the datapack page) is always treated as owned by everyone, with no entry needed.

Server commands — /mcpskins

These require operator permission (specifically, permission level ≥ the adminCommandPermissionLevel setting — default 4, i.e. full op; configurable, see Configuration).

Command	Effect
/mcpskins give skin <player> <skinId>	Directly unlocks one skin for a player. Nothing physical changes hands — it just flips the ownership flag.
/mcpskins give item <player> <skinId>	Gives the player one physical unlock item pre-configured for that skin (see below), instead of unlocking it directly.
/mcpskins give all <player>	Unlocks every registered skin (across every weapon) for a player in one go. Handy for testing, or VIP/admin players.
/mcpskins take skin <player> <skinId>	Revokes one specific skin.
/mcpskins take skins <player>	Wipes a player's entire unlocked-skins list back to nothing (they keep every weapon's default: skin, since that's never actually "in" the list).

Naming quirk worth knowing about. The give skin command's argument is internally called gunId in the mod's code, but functionally it expects a skin ID (the same value you wrote as "id" in your datapack file) — not the weapon's own GunId. This doesn't affect how you use it, just don't let the parameter name in tab-completion throw you off.

All three commands that take a skin/gun ID argument tab-complete against every currently known skin ID, so you rarely need to type one out by hand.

The unlock item

Rather than editing a player's ownership list directly, you can hand out a physical, tradeable item that unlocks a specific skin when used. Get one via /mcpskins give item <player> <skinId> — this is strongly preferred over spawning the item in by hand (e.g. via /give with raw NBT), since the command validates that the skin ID actually exists and fills in the correct data for you.

Using the item (right-click):

• If the player doesn't already own that skin: it's unlocked, a small chat message announces it (with the skin name in its label color, and a hover-preview of the weapon wearing it), and the item is consumed (unless the player is in creative-mode instant-build).
• If they already own it: nothing happens, and they're told so — the item is not consumed on a failed/duplicate unlock.

Hovering over an un-used item in an inventory shows which skin it unlocks (or a warning if its skin ID doesn't match anything currently loaded — this can happen if a datapack was removed after the item was given out).

Fusing — turning duplicates into something better

Shift + right-click on an unlock item instead fuses it: it scans the player's entire inventory (not just the item in hand) for unlock items whose target skin is the same rarity tier as the one in hand, consumes a configurable number of them (default 3, see Configuration), and grants back one random unlock item of the next rarity tier up (COMMON → UNCOMMON → RARE → EPIC → LEGENDARY).

A few behaviors worth knowing:

• The reward is rolled preferring a skin the player doesn't already own; only once every skin of the target rarity is already owned does it start rolling duplicates.
• LEGENDARY is a dead end — trying to fuse a legendary-tier item tells the player there's nowhere higher to go, and nothing is consumed.
• If no skin exists yet at the next rarity tier at all (e.g. you haven't registered any EPIC skins), the same "nothing to fuse into" message is shown and nothing is consumed.
• Creative-mode players with instant-build don't need to actually hold the items — the inventory-scan/consumption step is skipped entirely for them, so it's a fast way to preview higher-rarity skins while building a pack, without needing a real inventory full of duplicates.
• The whole feature can be turned off server-wide (fusion.enabled, see Configuration).

The client-side Armory command

/mcpskins armory opens the full-screen Armory catalog (see In-Game UI) — this one needs no permission at all and runs entirely on the player's own client, since it's just opening a menu, not changing any data. /mcpskins armory <skinId> opens it pre-focused on a specific skin — this is what the clickable skin name in unlock/fuse chat messages actually uses under the hood, not something players typically type by hand.

Next: what all of this actually looks like from inside the game — In-Game UI.