Unwrap Commands transforms the simple act of unwrapping gifts into powerful server events. When a player unwraps an item (such as a Christmas present), the plugin can execute any server, chat, or client commands you define. With profile-based configuration, you can create completely different behavior for different wrapped items, skins, and player permissions. This opens possibilities for custom reward systems, event triggers, announcements, and more.
Common use cases include:
Example:
Placeholders
The key format is
Example:
Example:
Example: A custom client command defined by another plugin
Common use cases include:
- Custom rewards - Give players specific items when unwrapping presents instead of random loot
- Event triggers - Run special commands when key items are unwrapped
- Economy integration - Give currency or points for unwrapping achievements
Permissions
unwrapcommands.use-- Allows players to use the unwrap commands feature (required if "Require Permission To Use" is enabled in config)unwrapcommands.bypass.cooldown-- Allows players to bypass cooldown restrictions
unwrapcommands.vip)Configuration
JSON:
{
"Version": "1.0.0",
"Log Executed Commands To Server Console": true,
"Require Permission To Use (unwrapcommands.use)": false,
"Unwrap Profiles": [...]
}Log Executed Commands To Server Console-- When enabled, all executed commands are logged to the server console with the player name. Useful for debugging and auditing.Require Permission To Use (unwrapcommands.use)-- When enabled, only players with the unwrapcommands.use permission can trigger unwrap commands. Disabled players will trigger default unwrap behavior instead.
Unwrap Profiles
Each profile controls behavior for a specific item or item variant. Profiles are matched in order by item shortname, optional skin ID, and optional display name.
JSON:
{
"Enable This Profile": true,
"Item Shortname": "xmas.present.small",
"Match Skin ID (0 = Any Skin)": 0,
"Match Display Name (Empty = Any Name)": "",
"Required Permission (Empty = None)": "",
"Cooldown Between Uses (Seconds, 0 = None)": 0,
"Block Unwrap While On Cooldown": false,
"Command Selection Mode (All, Random, Weighted)": "Weighted",
"Block Default Loot (Only Give Custom Rewards)": false,
"Commands To Execute": [...],
"Send Notification To Player": true,
"Notification Message (Supports Placeholders)": "You unwrapped a {itemname}!"
}Enable This Profile-- Toggle this profile on/off without removing it from config. Default: trueItem Shortname-- The item identifier (e.g.,xmas.present.small,xmas.present.medium). Profiles are matched by shortname first. Required field.Match Skin ID (0 = Any Skin)-- Optionally match a specific item skin. Use 0 to match any skin. Allows you to create different behaviors for different skins of the same item.Match Display Name (Empty = Any Name)-- Optionally match a specific custom display name. Leave empty to match any name. Case-insensitive matching.Required Permission (Empty = None)-- Optional permission required for players to trigger this profile (e.g.,unwrapcommands.vip,unwrapcommands.exclusive.gift). Leave empty for no permission requirement. If a player lacks this permission, the default unwrap behavior occurs.Cooldown Between Uses (Seconds, 0 = None)-- Cooldown duration in seconds between unwraps for the same profile per player. Set to 0 for no cooldown. Cooldowns are tracked per profile per player and persist across server restarts.Block Unwrap While On Cooldown-- When enabled, blocks the unwrap action completely while on cooldown (returns true to prevent default loot). When disabled, allows the unwrap but shows an error message.Command Selection Mode-- How to select which commands to execute:All-- Execute every command in the list sequentiallyRandom-- Execute one random command from the listWeighted-- Execute one command selected by weighted probability (higher weight = more likely)
Block Default Loot (Only Give Custom Rewards)-- When enabled, prevents default item loot from being given. Combined with your custom commands, this lets you completely replace the default unwrap behavior. When disabled, default loot is given in addition to your custom commands.Commands To Execute-- Array of command entries to execute. See section below for details.
Send Notification To Player-- When enabled, sends a message to the player after successfully unwrapping.Notification Message (Supports Placeholders)-- Message sent to the player. Supports all placeholders listed in the Placeholders section.
Command Entries
Each command in the Commands To Execute array has these properties:
JSON:
{
"Command (Supports Placeholders)": "inventory.giveto {steamid} scrap 50",
"Command Type (Server, Chat, Client)": "Server",
"Weight (Higher = More Likely To Be Picked)": 70,
"Execute Chance (0-100 Percent)": 100
}Command-- The command to execute. Supports all placeholders listed in the Placeholders section. The command is sanitized to remove dangerous characters before execution.Command Type-- How the command is executed:Server-- Executed as a server commandChat-- Executed as a chat command from the player (with/prefix)Client-- Executed as a client console command on the player
Weight-- Used only inWeightedselection mode. Higher weight = more likely to be selected. Actual probability is weight / total_weight. Minimum weight of 1 is applied even if set to 0.Execute Chance-- Probability (0-100) that this command executes. Set to 50 for a 50% chance, 100 for guaranteed execution. Useful for creating variable rewards.
Profile Matching Priority
When an item is unwrapped, profiles are matched in order of specificity:- Item shortname (required)
- Skin ID match (2 points if specified and matched, 0 if not applicable)
- Display name match (1 point if specified and matched, 0 if not applicable)
Example:
- Profile A:
xmas.present.small, any skin, any name → score 0 - Profile B:
xmas.present.small, skin 12345, any name → score 2 - Profile C:
xmas.present.small, any skin, "Special Gift" → score 1
xmas.present.small with skin 12345, Profile B is selected (highest score).Placeholders
Placeholders
Commands and notification messages support dynamic placeholders that are replaced at runtime. All placeholders are case-sensitive.Player Placeholders
{playername}-- Player's display name (sanitized){playerid}-- Player's ID (same as Steam ID)
Position Placeholders
{position}-- Player position as "X Y Z" (e.g., "150.50 100.25 200.75"){position.x}-- X coordinate{position.y}-- Y coordinate{position.z}-- Z coordinate{grid}-- Grid position on the map (e.g., "J5")
Item Placeholders
{itemname}-- Item's display name (sanitized){itemshortname}-- Item's shortname (e.g., "xmas.present.small"){itemid}-- Item's definition ID{itemamount}-- Quantity of items unwrapped{itemuid}-- Item's unique ID{skinid}-- Item's skin ID
Random Placeholders
{random:MIN:MAX}-- Random integer between MIN and MAX (inclusive)
{random:1:10} generates a random number between 1 and 10Stored Data
JSON:
{
"Player Cooldowns": {
"76561198000000000": {
"xmas.present.small_0_": 1703123456.0,
"xmas.present.medium_0_": 1703123400.0
}
}
}ItemShortname_SkinId_DisplayName. Each value is a Unix timestamp of when the player last unwrapped that item. When a cooldown expires (current time exceeds stored time plus cooldown duration), the player can unwrap again.Localization
JSON:
{
"Error.Cooldown": "You must wait {0} seconds before unwrapping another {1}."
}Command Execution Types
Server Commands
Commands executed directly on the server. Most common for giving items, managing resources, or calling other plugin functionality.Example:
inventory.giveto {steamid} scrap 100Chat Commands
Commands executed as if the player typed them in chat with a / prefix. Useful for triggering player-facing commands or chat-based functionality.Example:
home (executed as /home)Client Commands
Commands sent to the player's client console. Less common, but useful for client-side operations.Example: A custom client command defined by another plugin
