### Beginner permission setup example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Permissions

Example permissions for a default rank player to use GadgetsMenu smoothly. Includes optional permissions for premium features.

```text
gadgetsmenu.menuselector
gadgetsmenu.mysteryboxes.open.*
gadgetsmenu.animations.normal
gadgetsmenu.summonpet (Optional) - for premium version only
gadgetsmenu.discount.default (Optional)
```

--------------------------------

### /gmenu settings command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Examples of modifying personal plugin settings.

```text
/gmenu settings bypasscooldown true
```

```text
/gmenu settings selfmorphview false
```

--------------------------------

### /gmenu menu command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Examples of opening specific cosmetic menus.

```text
/gmenu menu Particles 1
```

```text
/gmenu menu Hats 3
```

--------------------------------

### /gmenu equip command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Examples of equipping a cosmetic with or without specifying a player.

```text
/gmenu equip Gadget MobGun
```

```text
/gmenu equip Gadget MobGun Notch
```

--------------------------------

### /gmenu reset command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Examples of resetting active cosmetics for players.

```text
/gmenu reset all all
```

```text
/gmenu reset Hat Notch
```

--------------------------------

### /gmenu permission command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Examples of listing permissions for specific cosmetic categories.

```text
/gmenu permission Hats
```

```text
/gmenu permission Hats 2
```

--------------------------------

### /gmenu petitems command usage and examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Usage syntax and examples for managing player pet items.

```text
/gmenu petitems add <item> <player> <amount>
/gmenu petitems check <player>
/gmenu petitems remove <item> <player> <amount>
/gmenu petitems set <item> <player> <amount>
```

```text
/gmenu petitems add Apple Notch 10
/gmenu petitems check Notch
/gmenu petitems remove Water Notch 3
/gmenu petitems set Stick Notch 25
```

--------------------------------

### Sound Configuration Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Configuration

Example configuration for enabling a play sound with a specific sound name. The sound name must be from the list of valid sound names (linked in the documentation).

```yaml
Play-Sound:
  Enabled: true
  Sound: ENTITY_ENDERMAN_TELEPORT
```

--------------------------------

### /gmenu namepet command example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Example of naming a pet using the /gmenu namepet command.

```text
/gmenu namepet &cWosh
```

--------------------------------

### /gmenu removeperm command example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Example of removing a cosmetic permission from a player.

```text
/gmenu removeperm Emote RIP Notch
```

--------------------------------

### Custom-Loot1 configuration example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Mystery-Boxes-Loot

A minimal example demonstrating how to define a single custom loot entry named Custom-Loot1.

```yaml
Custom-Loot1:
    Name: '&aCustom Loot 1'
    Rarity: Common
    Category: '&cLoot'
    CanBeFound: true
    Execute-Command:
      Enabled: true
      Commands:
      - eco give {PLAYER} 10
```

--------------------------------

### /gmenu purge command example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Example of using the purge command to remove inactive player data.

```text
/gmenu purge t:1y
```

--------------------------------

### /gmenu addperm command example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Example usage of the /gmenu addperm command to grant a player permission for a specific cosmetic.

```text
/gmenu addperm Gadget MobGun Notch
```

--------------------------------

### Custom Miniatures Configuration Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Miniatures

An example configuration for defining miniatures in custom-miniatures.yml. Each entry requires a unique name for caching and mystery box functionality.

```yaml
# Please do not change this.
Custom-Miniatures:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the following miniature is 'gadgetsmenu.miniatures.fisherman'.
  Fisherman:

    # The name of the miniature.
    Name: '&9Fisherman Miniature'

    # The material of the miniature.
    Material: head:528da0e5b26eac1c4fbc562cd7a41bc7a644be00231cd2c23dd278f3c6861ca6

    # The price of the miniature.
    Mystery Dust: 32

    # The rarity of the miniature.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Rare

    # Set to true to show this miniature to player.
    Enabled: false

    # Can this miniature be found in mystery boxes?
    CanBeFound: true

    # Can player get this miniature by purchasing it using mystery dust?
    Purchasable: true

    # The lore of the miniature.
    Lore:
      Locked:
      - '&7Select a Fisherman Miniature'
      - '&7to follow you.'
      Unlocked:
      - '&7Select a Fisherman Miniature'
      - '&7to follow you.'

    # Set to true to hide the armor stand
    Invisible: false

    # Should this miniature be rotated?
    Rotate: false

    # Armor stand equipments.
    Equipments:
      Main-Hand:
        Enabled: true
        Material: FISHING_ROD
      Helmet:
        Enabled: true
        Material: head:528da0e5b26eac1c4fbc562cd7a41bc7a644be00231cd2c23dd278f3c6861ca6
      Chestplate:
        Enabled: true
        Material: LEATHER_CHESTPLATE:#455B93
      Leggings:
        Enabled: true
        Material: LEATHER_LEGGINGS:#455B93
      Boots:
        Enabled: true
        Material: LEATHER_BOOTS:#455B93

  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the following miniature is 'gadgetsmenu.miniatures.soul-o-lantern'.
  Soul-O-Lantern:

    # The name of the miniature.
    Name: '&5Soul Jack O''Lantern Miniature'

    # The material of the miniature.
    Material: head:b81c14a4df2a65135673211dd55dc9c577b8500143ec1293eda8e05009c851a8

    # The price of the miniature.
    Mystery Dust: 58

    # The rarity of the miniature.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Epic

    # Set to true to show this miniature to player.
    Enabled: false

    # Can this miniature be found in mystery boxes?
    CanBeFound: true

    # Can player get this miniature by purchasing it using mystery dust?
    Purchasable: true

    # The lore of the miniature.
    Lore:
      Locked:
      - '&7Select a Soul Jack O''Lantern'
      - '&7Miniature to follow you.'
      Unlocked:
      - '&7Select a Soul Jack O''Lantern'
      - '&7Miniature to follow you.'

    # Set to true to hide the armor stand
    Invisible: true

    # Should this miniature be rotated?
    Rotate: true

    # Armor stand equipments.
    Equipments:
      Helmet:
        Enabled: true
        Material: head:b81c14a4df2a65135673211dd55dc9c577b8500143ec1293eda8e05009c851a8
```

--------------------------------

### Cosmetic Item Settings Example (Hamburger Hat)

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Configuration

Sample configuration for a cosmetic item, using 'Hamburger Hat' as an example. Shows all available settings: name, mystery dust cost, rarity, enabled status, mystery box availability, purchasability, and locked/unlocked lore. The comment 'Don't change this!' indicates the item key should remain unchanged.

```yaml
# Don't change this!
Hamburger:
    
  # The name of the item.
  Name: '&aHamburger Hat'

  # How much mystery dust does it cost to craft it
  Mystery Dust: 12
  
  # The rarity of the item.
  # Rarity: Common, Rare, Epic, Legendary
  Rarity: Common

  # Is it enabled?
  Enabled: true
    
  # Can this item be found in mystery box?
  CanBeFound: true

  # Can player purchase this item?
  Purchasable: true

  # The lore of the item.
  Lore:
    Locked:
    - 'Display this lore if'
    - 'player have not unlock'
    - 'this item.'
    Unlocked:
    - 'Display this lore if'
    - 'player unlocked this item.'
```

--------------------------------

### Hex Color Usage Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Configuration

Example of using hex color syntax in a display name. The syntax is {#<hex color>} and works on server versions 1.16 and later. This example sets the name to 'GadgetsMenu' with a pink color.

```yaml
Name: '{#FC5383}GadgetsMenu'
```

--------------------------------

### /gmysteryboxes gift command example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Gives mystery gifts to a player. Example: /gmysteryboxes gift Notch 1

```text
/gmysteryboxes gift Notch 1
```

--------------------------------

### Custom particle configuration example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Particles

Example YAML configuration for a custom particle named 'End Rod'. The permission is 'gadgetsmenu.particles.endrod'. The particle is disabled by default and can be found in mystery boxes and purchased with mystery dust.

```yaml
# Please do not change this.
Custom-Particles:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the particle is 'gadgetsmenu.particles.endrod'.
  End Rod:

    # The name of particle.
    Name: '&5End Rod Particle'
    
    # The material of particle that will show in gui menu.
    # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
    # Material Format: [Material]:[Material Data]
    Material: END_ROD

    # The price of particle.
    Mystery Dust: 32

    # The rarity of the particle.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Epic

    # Particle Effects: https://github.com/OnlyNoobDied/GadgetsMenu/wiki/Particle-Effects
    Effect: END_ROD

    # Set to true will able player's to equip it.
    Enabled: false

    # Can this particle found in mystery boxes?
    CanBeFound: true

    # Can player get this hat by purchasing it using mystery dust?
    Purchasable: true

    # The lore of particle.
    Lore:
      Locked: ''
      Unlocked: ''
```

--------------------------------

### /gmysteryboxes give command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Gives mystery boxes to a player with various options: quality, expiry date (ex), require permission (reqperm), and chances (c). The chances syntax requires all qualities 1-5.

```text
/gmysteryboxes give Notch 1
```

```text
/gmysteryboxes give Notch 1 5
```

```text
/gmysteryboxes give Notch 1 5 ex=1d
```

```text
/gmysteryboxes give Notch 1 5 ex=1d reqperm=false
```

```text
/gmysteryboxes give Notch 1 c:(1:40,2:30,3:25,4:15,5:10)
```

--------------------------------

### Example custom banner configuration

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Banners

A template for defining a new banner in custom banners.yml, including settings for permissions, mystery box availability, and visual patterns.

```yaml
# Please do not change this.
Custom-Banners:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the banner is 'gadgetsmenu.banners.wolf'.
  Wolf:

    # The name of banner.
    Name: '&5Wolf Banner'

    # The price of banner.
    Mystery Dust: 15

    # The rarity of the banner.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Epic

    # Set to true will able player's to equip it.
    Enabled: false

    # Can this banner found in mystery boxes?
    CanBeFound: true

    # Can player get this hat by purchasing it using mystery dust?
    Purchasable: true

    # The base color of banner.
    # Base Color: https://github.com/OnlyNoobDied/GadgetsMenu/wiki/Banner-Patterns#color
    Base-Color: WHITE

    # The patterns of banner.
    # Banner Patterns: https://github.com/OnlyNoobDied/GadgetsMenu/wiki/Banner-Patterns
    # Pattern syntax: <color>:<pattern>
    Patterns:
    - BLACK:RHOMBUS_MIDDLE
    - BLACK:RHOMBUS_MIDDLE
    - LIGHT_BLUE:CURLY_BORDER
    - LIGHT_BLUE:CIRCLE_MIDDLE
    - LIGHT_BLUE:CREEPER
    - LIGHT_BLUE:TRIANGLE_TOP

    # The lore of banner.
    Lore:
      Locked: ''
      Unlocked: ''
```

--------------------------------

### Custom Animated Hats YAML Configuration Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Animated-Hats

Full YAML configuration for a custom animated hat named 'Slimes'. Includes name, price, rarity, texture, enabled, can be found, purchasable, ticks per frame, frames list, and lore. The permission is 'gadgetsmenu.animatedhats.slimes'.

```yaml
# Please do not change this.
Custom-Animated-Hats:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the emote is 'gadgetsmenu.animatedhats.slimes'.
  Slimes:

    # The name of animated hat.
    Name: '&aSmiles Animated Hat'

    # The price of animated hat.
    Mystery Dust: 12

    # The rarity of the animated hat.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Common 

    # This is the texture of the head that are stored in Mojang's database.
    # Simply paste the url right here.
    Texture: 41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235

    # Set to true will able player to equip it.
    Enabled: false

    # Can this animated hat found in mystery boxes?
    CanBeFound: true

    # Can player get this animated hat by purchasing it using mystery dust?
    Purchasable: true

    # How many ticks should wait before shows the next frame?
    # 20 ticks = 1 second
    TicksPerFrame: 5

    # The frames of animated hat.
    # Frames syntax: '<The amount of the frames>:<texture>'
    Frames:
    - 11:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235
    - 1:4168b716281635ceafc3268dfa7d5f46466c8032e11c1cfb7db711a9f647d
    - 11:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235
    - 1:4168b716281635ceafc3268dfa7d5f46466c8032e11c1cfb7db711a9f647d
    - 3:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235

    # The lore of animated hat.
    Lore: 
      Locked: ''
      Unlocked: ''
```

--------------------------------

### Custom Emotes Configuration Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Emotes

An example of the structure required in custom emotes.yml to define a new emote. Ensure the emote name is unique as it is used for caching and mystery box integration.

```yaml
# Please do not change this.
Custom-Emotes:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the emote is 'gadgetsmenu.emotes.slimes'.
  Slimes:

    # The name of emote.
    Name: '&aSmiles Emote'

    # The price of emote.
    Mystery Dust: 10

    # The cooldown timer of using emote once.
    Cooldown: 10

    # The rarity of the emote.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Common 

    # Shows a hologram on the top of the player.
    Hologram:
      Enabled: false
      Text: ''

    # This is the texture of the head that are stored in Mojang's database.
    # Simply paste the url right here.
    Texture: 60c432cbc490a8af6e9dfeb28095c0a0ec79fff705fb184674d1e743bd05baa

    # Set to true will able player's to equip it.
    Enabled: false

    # Can this emote found in mystery boxes?
    CanBeFound: true

    # Can player get this emote by purchasing it using mystery dust?
    Purchasable: true

    # How many ticks should wait before shows the next frame?
    # 20 ticks = 1 second
    TicksPerFrame: 5

    # The frames of emote.
    # Frames syntax: '<The amount of the frames>:<texture>'
    Frames:
    - 5:264614ad4bb2eb61b06b1a8b5d57f02448a975a8217ec16571f87c49227cbd
    - 1:60c432cbc490a8af6e9dfeb28095c0a0ec79fff705fb184674d1e743bd05baa
    - 11:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235
    - 1:4168b716281635ceafc3268dfa7d5f46466c8032e11c1cfb7db711a9f647d
    - 11:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235
    - 1:4168b716281635ceafc3268dfa7d5f46466c8032e11c1cfb7db711a9f647d
    - 3:41ac21d93ce17f2b7ee2e0e07a983eeb4a539e341ce5c77c36c722f77a2235

    # The lore of emote.
    Lore:
      Locked: ''
      Unlocked: ''
```

--------------------------------

### Custom Hats YAML Configuration Example

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Hats

Example configuration for defining custom hats in 'custom hats.yml'. Shows two hats (Steve and Sponge) with options for name, price, rarity, texture or material, and flags like Enabled, CanBeFound, and Purchasable. The permission for each hat is 'gadgetsmenu.hats.<name>'. Note that the 'Texture' field expects a URL from Mojang's database, while 'Material' uses Spigot material names with optional data.

```yaml
# Please do not change this.
Custom-Hats:
  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the hat is 'gadgetsmenu.hats.steve'.
  Steve:

    # The name of hat.
    Name: '&aSteve Hat'

    # The price of hat.
    Mystery Dust: 12

    # The rarity of the hat.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Common

    # This is the texture of the head that are stored in Mojang's database.
    # Simply paste the url right here.
    Texture: http://textures.minecraft.net/texture/eb7af9e4411217c7de9c60acbd3c3fd6519783332a1b3bc56fbfce90721ef35

    # Set to true will able player to equip it.
    Enabled: false

    # Can this hat found in mystery boxes?
    CanBeFound: true

    # Can player get this hat by purchasing it using mystery dust?
    Purchasable: true

    # The lore of hat.
    Lore:
      Locked: ''
      Unlocked: ''

  # This name will store in GadgetsMenu cache and use for mystery boxes, 
  # so do not use the same name!
  # The permission of the hat is 'gadgetsmenu.hats.sponge'.
  Sponge:

    # The name of hat.
    Name: '&aSponge Hat'

    # The price of hat.
    Mystery Dust: 12

    # The rarity of the hat.
    # Rarity: Common, Rare, Epic, Legendary
    Rarity: Common

    # The material of hat.
    # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
    # Material Format: [Material]:[Material Data]
    Material: SPONGE

    # Set to true will able player's to equip it.
    Enabled: false

    # Can this hat found in mystery boxes?
    CanBeFound: true

    # Can player get this hat by purchasing it using mystery dust?
    Purchasable: true

    # The lore of hat.
    Lore: 
      Locked: ''
      Unlocked: ''
```

--------------------------------

### custom loots.yml configuration sample

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Mystery-Boxes-Loot

A comprehensive example showing the structure of the custom loots.yml file, including definitions for money and diamond armor rewards.

```yaml
Custom-Loots:
  # The name that saved in database.
  10-Money:
    # The name of custom loot.
    Name: '&a10$'
    # The rarity of custom loot.
    Rarity: Common
    # The category of custom loot.
    Category: '&cMoney'
    # Can this item can be found in mystery boxes.
    CanBeFound: true
    Execute-Command:
      # Set to true will execute the command when player found loot.
      Enabled: true
      # The command that execute when player found loot.
      # Placeholder: {PLAYER}
      Commands:
      - eco give {PLAYER} 10
  Diamond-Suit:
    Name: '&6Diamond Armor'
    Rarity: Legendary
    Category: '&cArmor'
    CanBeFound: true
    Execute-Command:
      Enabled: true
      Commands:
      - give {PLAYER} minecraft:diamond_helmet 1
      - give {PLAYER} minecraft:diamond_chestplate 1
      - give {PLAYER} minecraft:diamond_leggings 1
      - give {PLAYER} minecraft:diamond_boots 1
```

--------------------------------

### /mysterydust add command argument

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Example of the msg argument for the mystery dust command.

```text
msg=false
```

--------------------------------

### /mysterydust add command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Adds mystery dust to a player. The optional msg=false argument suppresses notification messages.

```text
/mysterydust add Notch 100
```

```text
/mysterydust add Notch 100 msg=false
```

--------------------------------

### /mysterydust pay command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Transfers mystery dust to a player. The optional msg=false argument suppresses notification messages.

```text
/mysterydust pay Notch 100
```

```text
/mysterydust pay Notch 100 msg=false
```

--------------------------------

### Get PlayerManager from GadgetsMenuAPI

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Required first step for using the API. Obtains the PlayerManager instance for a player, which is needed for all subsequent API calls.

```java
public static void doSomeAction(Player player) {
    PlayerManager playerManager = GadgetsMenuAPI.getPlayerManager(player);
    // Add some code here.
}
```

--------------------------------

### Enable MySQL Database Configuration

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Frequently-Asked-Questions.org

To enable MySQL, set the storage type to 'mysql' and provide the database connection details in the config.yml file.

```yaml
Player-Data:
  Storage: mysql <-- set to 'mysql'
  MySQL:
    hostname: localhost
    username: root
    database: minecraft
    port: '3306'
    password: ''
```

--------------------------------

### Get player's mystery gifts

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Retrieves the player's mystery gifts.

```java
playerManager.getGiftPacks();
```

--------------------------------

### Economy_CustomEconomy extends GEconomyProvider

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Economy-Storage

Creates a class extending GEconomyProvider with a constructor and unimplemented methods for mystery dust operations. The constructor passes the plugin and a storage name to the superclass. Methods return true on success and false on failure.

```java
import com.yapzhenyie.GadgetsMenu.economy.GEconomyProvider;
import com.yapzhenyie.GadgetsMenu.economy.GStorage;
import com.yapzhenyie.GadgetsMenu.player.OfflinePlayerManager;

public class Economy_CustomEconomy extends GEconomyProvider {

	public Economy_CustomEconomy(CustomEconomyMain yourPlugin) {
                //Plugin plugin, your storage name
		super(yourPlugin, "Custom-Storage");
	}

	@Override
	public int getMysteryDust(OfflinePlayerManager pManager) {
		return 0;
	}

	@Override
	public boolean addMysteryDust(OfflinePlayerManager pManager, int amount) {
               // Add your code here.
               return true; // Return true when the transaction is successful, otherwise return false.
	}

	@Override
	public boolean setMysteryDust(OfflinePlayerManager pManager, int amount) {
               // Add your code here.
               return true; // Return true when the transaction is successful, otherwise return false.
	}

	@Override
	public boolean removeMysteryDust(OfflinePlayerManager pManager, int amount) {
               // Add your code here.
               return true; // Return true when the transaction is successful, otherwise return false.
	}
}

```

--------------------------------

### Get player's Mystery Boxes

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Retrieves the player's Mystery Boxes.

```java
playerManager.getMysteryBoxes();
```

--------------------------------

### Open main menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.goBackToMainMenu() to return to the main menu.

```java
playerManager.goBackToMainMenu();
```

--------------------------------

### Get player's Mystery Dust

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Retrieves the player's current Mystery Dust amount.

```java
playerManager.getMysteryDust();
```

--------------------------------

### /mysterydust remove command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Removes mystery dust from a player. The optional msg=false argument suppresses notification messages.

```text
/mysterydust remove Notch 100
```

```text
/mysterydust remove Notch 100 msg=false
```

--------------------------------

### Item-Cost-Discount YAML configuration

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Item-Cost-Discount

Configuration block for enabling and defining item cost discounts. Includes discount rates for VIP and MVP groups with priority, permission, rate, and lore messages using placeholders like {COST}, {VIP_COST}, {MVP_COST}, and {COST_LEFT}.

```yaml
# Discount the cost of an item when player purchase.
Item-Cost-Discount:
  # Set to true will enable item cost discount.
  Enabled: true
  # Which item do you want to enable item cost discount?
  Discount:
    Cosmetic-Item: true
    Crafting-Mystery-Box: true
  # You can add more discount rate by reference example.
  Discount-Rates:
    # The name of the discount group.
    # The name is use for placeholder to get the cost after discount.
    # Placeholder Syntax: {<name>_COST}
    # Get the cost of that discount rate.
    VIP:
      # Higher numbers override.
      Priority: 1
      # The permission to granted discount.
      Permission: gadgetsmenu.discount.VIP
      # Discount rates.
      Rate: 20
      Lore:
        Enough-Mystery-Dust:
        - ''
        - '&8&mRegular: {COST} Mystery Dust!'
        - "&aVIP&7: &a{VIP_COST} &7Mystery Dust (&a20% &7OFF!) &e\u25C0"
        - '&cMVP: {MVP_COST} Mystery Dust (40% OFF!)'
        - ''
        - '&7Your Cost: &a{VIP_COST} &7Mystery Dust'
        - '&eClick to craft!'
        Not-Enough-Mystery-Dust:
        - ''
        - '&8&mRegular: {COST} Mystery Dust!'
        - "&aVIP&7: &a{VIP_COST} &7Mystery Dust (&a20% &7OFF!) &e\u25C0"
        - '&cMVP: {MVP_COST} Mystery Dust (40% OFF!)'
        - ''
        - '&7Your Cost: &c{VIP_COST} &7Mystery Dust'
        - '&cYou need &b{COST_LEFT} &cmore mystery dust!'
    MVP:
      Priority: 2
      Permission: gadgetsmenu.discount.MVP
      Rate: 40
      Lore:
        Enough-Mystery-Dust:
        - ''
        - '&8&mRegular: {COST} Mystery Dust!'
        - '&8&mVIP: {VIP_COST} Mystery Dust (20% OFF!)'
        - "&bMVP&7: &a{MVP_COST} &7Mystery Dust (&a40% &7OFF!) &e\u25C0"
        - ''
        - '&7Your Cost: &a{MVP_COST} &7Mystery Dust'
        - '&eClick to craft!'
        Not-Enough-Mystery-Dust:
        - ''
        - '&8&mRegular: {COST} Mystery Dust!'
        - '&8&mVIP: {VIP_COST} Mystery Dust (20% OFF!)'
        - "&bMVP&7: &a{MVP_COST} &7Mystery Dust (&a40% &7OFF!) &e\u25C0"
        - ''
        - '&7Your Cost: &a{MVP_COST} &7Mystery Dust'
        - '&cYou need &b{COST_LEFT} &cmore mystery dust!'
```

--------------------------------

### Configure Cosmetic Item Purchase Commands

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Frequently-Asked-Questions.org

Update the Execute-Command settings in config.yml and mystery boxes.yml to match your server's permission plugin syntax for granting permissions.

```yaml
1) Cosmetic-Item-Purchase:(Can be found in 'config.yml' file)
     # This is the command when player purchase cosmetic items.
     # This command is depends on your permission plugin.
     Execute-Command: pex user {PLAYER} add {PERMISSION}

2) Mystery-Boxes: (Can be found in 'mystery boxes.yml' file)
     Execute-Command: pex user {PLAYER} add {PERMISSION}
```

--------------------------------

### /mysterydust set command examples

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Commands.org

Sets a player's mystery dust. The optional msg=false argument suppresses notification messages.

```text
/mysterydust set Notch 100
```

```text
/mysterydust set Notch 100 msg=false
```

--------------------------------

### Open Specific Menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Methods to open various cosmetic menus.

```APIDOC
## playerManager.goBackToMainMenu()

### Description
Opens the main menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

## playerManager.openHatsMenu(page)

### Description
Opens the hats menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openAnimatedHatsMenu(page)

### Description
Opens the animated hats menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openParticlesMenu(page)

### Description
Opens the particles menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openSuitsMenu()

### Description
Opens the suits menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

## playerManager.openSuitEquipmentMenu(type)

### Description
Opens the specific suit equipment menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **type** (SuitType) - Required - The SuitType.

### Request Example
N/A

### Response
N/A

## playerManager.openCategoryGadgetsMenu()

### Description
Opens the category gadgets menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

## playerManager.openGadgetTypesMenu(type, page)

### Description
Opens the specific gadget type menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **type** (GadgetCategoryType) - Required - The GadgetCategoryType.
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openCategoryPetsMenu()

### Description
Opens the category pets menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

## playerManager.openPetTypesMenu(type, page)

### Description
Opens the specific pet type menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **type** (PetCategoryType) - Required - The PetCategoryType.
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openMorphsMenu()

### Description
Opens the morphs menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

## playerManager.openBannersMenu(page)

### Description
Opens the banners menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openMorphsMenu(page)

### Description
Opens the emotes menu. (Note: The source lists this as openMorphsMenu(page) but the description says emotes menu.)

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
- **page** (type not specified) - Required - The page of the menu.

### Request Example
N/A

### Response
N/A

## playerManager.openCloaksMenu()

### Description
Opens the cloaks menu.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Commands permissions list

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Permissions

List of all command permissions under gadgetsmenu.commands.*.

```text
 gadgetsmenu.commands.about
 gadgetsmenu.commands.addpermission
 gadgetsmenu.commands.admin
 gadgetsmenu.commands.checkupdate
 gadgetsmenu.commands.equip
 gadgetsmenu.commands.help
 gadgetsmenu.commands.namepet
 gadgetsmenu.commands.migrate
 gadgetsmenu.commands.permission
 gadgetsmenu.commands.purge
 gadgetsmenu.commands.reload
 gadgetsmenu.commands.removepermission
 gadgetsmenu.commands.reset
 gadgetsmenu.commands.settings
 gadgetsmenu.commands.status
 gadgetsmenu.mysterydust.add
 gadgetsmenu.mysterydust.check
 gadgetsmenu.mysterydust.pay
 gadgetsmenu.mysterydust.remove
 gadgetsmenu.mysterydust.set
 gadgetsmenu.mysteryboxes.check
 gadgetsmenu.mysteryboxes.gift
 gadgetsmenu.mysteryboxes.give
 gadgetsmenu.mysteryboxes.giveall
 gadgetsmenu.mysteryboxes.mode
```

--------------------------------

### Cosmetic-Item-Purchase Configuration

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Cosmetic-Item-Purchase

YAML configuration for the Cosmetic-Item-Purchase feature. Set 'Enabled' to true to allow purchases, choose the mystery dust storage from 'default', 'coinsapi', 'playerpoints', or 'vault', and enable specific cosmetic types. The 'Execute-Command' is run when a player purchases an item, using placeholders {PLAYER} and {PERMISSION}.

```yaml
Cosmetic-Item-Purchase:

  # Set to true allows player to purchase cosmetic items.
  Enabled: true

  # Set the storage where do you want to save mystery dust.
  # Available storages: 'default', 'coinsapi', 'playerpoints', 'vault'.
  # 'default' represent follow player data storage.
  Mystery-Dust-Storage: default

  # Set to true will allows player to purchase specified cosmetic.
  Enabled-Cosmetics:
    Hats: true
    Animated Hats: true
    Particles: true
    Suits: true
    Gadgets: true
    Pets: true
    Morphs: true
    Banners: true
    Emotes: true
    Cloaks: true

  # Reopen GUI menu after player purchase item.
  Reopen-GUI-Menu-After-Purchase: true

  # This is the command when player purchase cosmetic items.
  # This command is depends on your permission plugin.
  Execute-Command: pex user {PLAYER} add {PERMISSION}
```

--------------------------------

### Equip and unequip pet

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Provides methods to equip a pet with a PetType parameter and to unequip the current pet.

```java
  /**
   * Equip pet.
   * @param type The PetType.
   */
   playerManager.equipPet(type);

  /**
   * Unequip pet.
   */
   playerManager.unequipPet();
```

--------------------------------

### Give player's Mystery Boxes

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Gives mystery boxes to a player. Parameters include MysteryBoxType, expiryDate (null for no expiry), requirePerm, details (always null), and amount. Example uses NORMAL_MYSTERY_BOX_3 with a 1-day expiry.

```java
/**
 * Give player mystery boxes.
 * 
 * @param MysteryBoxType
 *   The type of mystery boxes.
 * @param expiryDate
 *   The expiry date of mystery boxes.
 *   Set to null won't expire.
 * @param requirePerm
 *   Does player need to require permission to open it.
 * @param details
 *   The details of gifted mystery box(sender) and crafted mystery
 *   box(craft date).
 * @param amount
 *   The amount of the mystery boxes will give to player.
 */
playerManager.giveMysteryBoxes(MysteryBoxType mysteryBoxType, Long expiryDate, boolean requirePerm, String details, int amount);

/**
 * MysteryBox Types: NORMAL_MYSTERY_BOX_1, NORMAL_MYSTERY_BOX_2, NORMAL_MYSTERY_BOX_3, NORMAL_MYSTERY_BOX_4, 
 *                   NORMAL_MYSTERY_BOX_5
 * expiryDate: System.currentTimeMillis() + (24 * 3600 * 1000) // 1 day; Set to null, the mystery box won't expire.
 * requirePerm: true or false
 * details: always set to null
 * amount: How many mystery boxes should be given.
Ex: playerManager.giveMysteryBoxes(MysteryBoxType.NORMAL_MYSTERY_BOX_3, (System.currentTimeMillis() + (24 * 3600 * 1000)), true, null, 1);
```

--------------------------------

### Open cloaks menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openCloaksMenu() to open the cloaks menu.

```java
playerManager.openCloaksMenu();
```

--------------------------------

### Mystery Boxes Reward configuration in mystery boxes.yml

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Frequently-Asked-Questions.org

Configuration section from 'mystery boxes.yml' that enables the hourly mystery box reward system. It defines the chance to get a box, quality distribution, expiry date, play time required, enabled worlds, and reward messages.

```yaml
  Mystery-Boxes-Reward:
    Enabled: true
    # Chances that a player will gain a Mystery Box when achieve certain play time.
    Chance-To-Get-Mystery-Box: 60
    # What quality of Mystery Box the player will get.
    Chance:
      One-Star: 5
      Two-Star: 10
      Three-Star: 60
      Four-Star: 20
      Five-Star: 5
    # How long the Mystery Box will expired?
    Expiry-Date-In-Days: 7
    Play-Time:
      Hours: 0
      Minutes: 60
      Seconds: 0
    # Which world you want player's play time to be count.
    Enabled-Worlds:
    - '*'
    Message:
      One-Star: '&fYou found a &e✰&7✰✰✰✰ &fMystery Box!'
      Two-Star: '&fYou found a &e✰✰&7✰✰✰ &fMystery Box!'
      Three-Star: '&fYou found a &e✰✰✰&7✰✰ &fMystery Box!'
      Four-Star: '&fYou found a &e✰✰✰✰&7✰ &fMystery Box!'
      Five-Star: '&fYou found a &e✰✰✰✰✰ &fMystery Box!'
```

--------------------------------

### Cosmetics permissions list

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Permissions

List of all cosmetic category permissions under gadgetsmenu.cosmetics.*.

```text
 gadgetsmenu.hats.*
 gadgetsmenu.animatedhats.*
 gadgetsmenu.particles.*
 gadgetsmenu.suits.*
 gadgetsmenu.gadgets.*
 gadgetsmenu.pets.*
 gadgetsmenu.miniatures.*
 gadgetsmenu.morphs.*
 gadgetsmenu.banners.*
 gadgetsmenu.emotes.*
 gadgetsmenu.cloaks.*
```

--------------------------------

### Open suits menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openSuitsMenu() to open the suits menu.

```java
playerManager.openSuitsMenu();
```

--------------------------------

### plugin.yml with softdepend on GadgetsMenu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Economy-Storage

Adds a softdepend entry so the server knows your plugin depends on GadgetsMenu. This is the first step in the integration.

```yaml
name: CustomEconomy
main: com.yapzhenyie.customeconomy.CustomEconomyMain
version: 1.0.0
author: yapzhenyie
softdepend: [GadgetsMenu]

```

--------------------------------

### Open hats menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openHatsMenu(page) to open the hats menu with the specified page.

```java
playerManager.openHatsMenu(page);
```

--------------------------------

### Banner pattern syntax

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Custom-Banners

The required syntax format for defining banner patterns in the configuration file.

```text
 Pattern syntax: <color>:<pattern>
```

--------------------------------

### Open specific suit equipment menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openSuitEquipmentMenu(type) with a SuitType parameter to open the equipment menu for a specific suit.

```java
 /**
  * @param type The SuitType.
  */
  playerManager.openSuitEquipmentMenu(type);
```

--------------------------------

### Give a player random quality Mystery Boxes command

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Frequently-Asked-Questions.org

Gives a player Mystery Boxes with random qualities based on specified chances. The syntax c:(<quality>:<chances>) requires all qualities 1 to 5 to be filled; missing any will cause an error.

```text
/gmysteryboxes give <player> <amount> c:(1:40,2:30,3:25,4:15,5:10)
```

--------------------------------

### Equip and unequip gadget

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Provides methods to equip a gadget with a GadgetType parameter and to unequip the current gadget.

```java
  /**
   * Equip gadget.
   * @param type The GadgetType.
   */
   playerManager.equipGadget(type);

  /**
   * Unequip gadget.
   */
   playerManager.unequipGadget();
```

--------------------------------

### Open category pets menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openCategoryPetsMenu() to open the category pets menu.

```java
playerManager.openCategoryPetsMenu();
```

--------------------------------

### Open particles menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openParticlesMenu(page) to open the particles menu with the specified page.

```java
playerManager.openParticlesMenu(page);
```

--------------------------------

### Equip and unequip cloak

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Provides methods to equip a cloak with a CloakType parameter and to unequip the current cloak.

```java
  /**
   * Equip cloak.
   * @param type The CloakType.
   */
   playerManager.equipCloak(type);

  /**
   * Unequip cloak.
   */
   playerManager.unequipCloak();
```

--------------------------------

### Open morphs menu

Source: https://github.com/yapzhenyie/gadgetsmenu/wiki/Developer-API

Calls playerManager.openMorphsMenu() to open the morphs menu.

```java
playerManager.openMorphsMenu();
```