CommandItem2

# **CommandItem2 Plugin** ## **English** *I am not a native English Speaker, sorry for possible mistakes, please refer to Chinese version using translator or check source code.* ### **Overview** 2026.5.23 **Versions 2.0.0 and later are no longer compatible with versions 1.X.X. Items already in world will nolonger work.** No impacts to configuration. Major changes: - The PDC key namespace has been changed to "ci". - Item commands are now stored as a list of strings within the PDC. - Fixed a bug in the enchanting logic. - Removed unused item components. --- **CommandItem2** is a powerful and highly customizable Minecraft plugin for Purpur servers that allows administrators to create unique items with special abilities. These items can execute commands, have cooldowns, require specific permissions, and more, with all their properties stored directly on the item itself using Persistent Data Containers (PDC). This ensures that items retain their unique characteristics even when traded or stored. ### **Features** * **Custom Item Creation**: Define items with custom names (using MiniMessage), lore, enchantments, and materials. * **Command Execution**: Assign a list of commands to be executed from the console when the item is used. * **Persistent Data**: All special properties are saved to the item's NBT data, making them permanent. * **Cooldown System**: Set a per-player, per-item cooldown to prevent spam. * **Permission Control**: Require players to have a specific permission node (commanditem.use.\<id\>) to use an item. * **Configurable Behavior**: * **Strict Mode**: Choose whether to always pull item data from the config (for consistency) or from the item's data first (for legacy/modified items). * **Consumable Items**: Decide if an item should be consumed upon use. * **Live Reload**: Reload the configuration and all item definitions without restarting the server. * **PlaceholderAPI Support**: Display item cooldowns and other information via placeholders. * **Dynamic Permissions**: Permissions are automatically registered and unregistered on reload based on the items in your config. ### **Dependencies** * **Server**: (https://papermc.io) or its fork like (https://purpurmc.org/) for Minecraft 1.21.3 or later. * **Required Plugin**: (https://www.spigotmc.org/resources/placeholderapi.6245/) (for placeholder support). ### **Installation** 1. Download the latest version of the plugin from the releases page. 2. Make sure you have Purpur 1.21+ and PlaceholderAPI installed on your server. 3. Place the CommandItem2-vX.X.X.jar file into your server's /plugins directory. 4. Start or restart your server. A CommandItem2 folder containing the config.yml file will be generated. 5. Customize the config.yml to define your own special items. 6. Use the /si reload command in-game or from the console to apply your changes. ### **Configuration (config.yml)** Strict mode can be used for compatibility with older versions or special items modified by administrators. **If this mode is disabled, ensure that players do not have permission to modify the item's NBT data; otherwise, serious consequences may occur.** ### **Commands & Permissions** | Command | Description | Permission | | :---- | :---- | :---- | | /ci reload | Reloads the plugin's configuration. | commanditem.admin | | /ci get \<id\> \ | Gives the player a specified special item. | commanditem.admin | | /ci | Shows the help message. | commanditem.admin | **Player Permissions:** * commanditem.use.\<item\_id\>: Allows a player to use the special item with the corresponding ID. For example, commanditem.use.fire\_sword. * commanditem.use.\*: Allows a player to use all special items. ### **Placeholders (PlaceholderAPI)** Use these placeholders in any other plugin that supports PlaceholderAPI. | Placeholder | Description | Example Output | | :---- | :---- | :---- | | %commanditem\_cooldown\_\<item\_id\>% | Shows the formatted remaining cooldown for an item. | 1m 15s / Ready | | %commanditem\_cooldown\_s\_\<item\_id\>% | Shows the remaining cooldown in seconds. | 75 / 0 | | %commanditem\_name\_\<item\_id\>% | Shows the MiniMessage-formatted name of the item. | Infernal Blade | ### **Building from Source** If you want to compile the plugin yourself, follow these steps: 1. **Clone the repository:** git clone \<repository\_url\> cd CommandItem2 2. **Ensure** you **have JDK 17 or newer installed.** 3. **Build the JAR using Gradle:** * On Windows: gradlew build * On Linux/macOS: ./gradlew build 4. The compiled JAR file will be located in build/libs/. ## **简体中文** ### **项目简介** 2026.5.23 **2.0.0及以后的版本将不再兼容1.X.X的版本,此前已经存在的物品会失效**，对配置文件没有影响 主要变化： - PDC键的命名空间改为“ci" - 物品的命令改为使用字符串列表存储在PDC内 - 修正了错误的附魔逻辑 - 移除未使用的物品组件 **CommandItem2** 是一款功能强大、高度可定制的 Minecraft 插件，专为 Paper 服务端设计。它允许服主创建拥有特殊能力的独特物品。这些物品可以执行指令、拥有冷却时间、需要特定权限等。所有特殊属性都通过持久化数据容器（PDC）直接存储在物品本身，确