# **CommandItem2 插件**
## **目录**
* [英文版本](https://www.google.com/search?q=%23english)
* [概述](https://www.google.com/search?q=%23overview)
* [功能](https://www.google.com/search?q=%23features)
* [依赖](https://www.google.com/search?q=%23dependencies)
* [安装](https://www.google.com/search?q=%23installation)
* [配置 (config.yml)](https://www.google.com/search?q=%23configuration-configyml)
* [指令 & 权限](https://www.google.com/search?q=%23commands--permissions)
* [变量 (PlaceholderAPI)](https://www.google.com/search?q=%23placeholders-placeholderapi)
* [从源码构建](https://www.google.com/search?q=%23building-from-source)
* [中文版本](https://www.google.com/search?q=%23%E4%B8%AD%E6%96%87%E7%89%88%E6%9C%AC)
* [项目简介](https://www.google.com/search?q=%23%E9%A1%B9%E7%9B%AE%E7%AE%80%E4%BB%8B)
* [功能特色](https://www.google.com/search?q=%23%E5%8A%9F%E8%83%BD%E7%89%B9%E8%89%B2)
* [前置依赖](https://www.google.com/search?q=%23%E5%89%8D%E7%BD%AE%E4%BE%9D%E8%B5%96)
* [安装方法](https://www.google.com/search?q=%23%E5%AE%89%E8%A3%85%E6%96%B9%E6%B3%95)
* [插件配置 (config.yml)](https://www.google.com/search?q=%23%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE-configyml)
* [指令 & 权限](https://www.google.com/search?q=%23%E6%8C%87%E4%BB%A4--%E6%9D%83%E9%99%90)
* [变量 (PlaceholderAPI)](https://www.google.com/search?q=%23%E5%8F%98%E9%87%8F-placeholderapi)
* [从源码编译](https://www.google.com/search?q=%23%E4%BB%8E%E6%BA%90%E7%A0%81%E7%BC%96%E8%AF%91)
## **英文**
*this readme file is generated by Gemini 2.5 Pro, if plugin behavior is inconsistent with the description, please refer to the source code.(or maybe i will update them later,for this is my first plugin uploaded to modrinth)*
### **Overview**
**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.\) 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**: [Purpur](https://purpurmc.org/) for Minecraft 1.21 or later.
* **Required Plugin**: [PlaceholderAPI](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)**
The configuration is split into two main parts: the strict mode setting and the items list.
\# Strict mode:
\# true: When a player uses an item, its properties (commands, cooldown, etc.)
\# are ALWAYS read from this file based on its internal ID.
\# false: When a player uses an item, its properties are first read from the
\# item's own data (PDC). If a property is missing, it falls back
\# to this configuration file.
strict: false
\# List of all special items. The key (e.g., 'fire\_sword') is the unique ID for the item.
items:
fire\_sword:
\# Material from Bukkit's Material enum.
material: "NETHERITE\_SWORD"
\# Name supports MiniMessage formatting.
name: "\Infernal Blade\"
\# Lore also supports MiniMessage.
lore:
\- "\A sword forged in dragon's breath."
\- "\Use to gain fire resistance."
\# Enchantments: ENCHANTMENT\_NAME: level ,use "minecraft:" when no namespace is specified. it should also support enchantments from datapacks or other plugins as soon as you put the full name with namespace.
enchantments:
FIRE\_ASPECT: 2
SHARPNESS: 7
\# Commands to run from the console. Use \ for the player's name.
commands:
\- "effect give \ fire\_resistance 30 0 true"
\- "msg \ \The blade protects you from fire\!"
\# If true, player needs 'commanditem.use.fire\_sword' permission.
permission-required: true
\# Cooldown in seconds.
cooldown: 60
\# If true, one item is removed on use.
consume: false
\# ... add more items here
### **Commands & Permissions**
| Command | Description | Permission |
| :---- | :---- | :---- |
| /ci reload | Reloads the plugin's configuration. | commanditem.admin |
| /ci get \ \[amount\] | Gives the player a specified special item. | commanditem.admin |
| /ci | Shows the help message. | commanditem.admin |
**Player Permissions:**
* commanditem.use.\: 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\_\% | Shows the formatted remaining cooldown for an item. | 1m 15s / Ready |
| %commanditem\_cooldown\_s\_\% | Shows the remaining cooldown in seconds. | 75 / 0 |
| %commanditem\_name\_\% | 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 \
cd CommandItem2
2. **Ensure** you **have JDK 17 or newer installed.**
3. **Build the JAR using Gradle:**
* On Windows:
gradlew shadowJar
* On Linux/macOS:
./gradlew shadowJar
4. The compiled JAR file will be located in build/libs/.
## **中文版本**
*readme由Gemini 2.5Pro生成,如发现插件行为与游戏内不一致,请以源码为准(或者我会稍后更新这个readme,因为这是我的发布到modrinth的第一个插件)*
### **项目简介**
**CommandItem2** 是一款功能强大、高度可定制的 Minecraft 插件，专为 Purpur 服务端设计。它允许服主创建拥有特殊能力的独特物品。这些物品可以执行指令、拥有冷却时间、需要特定权限等。所有特殊属性都通过持久化数据容器（PDC）直接存储在物品本身，确保物品在交易或存放后仍能保持其独特性。
### **功能特色**
* **自定义物品创建**: 定义具有自定义名称（支持 MiniMessage 格式）、Lore、附魔和材质的物品。
* **指令执行**: 为物品指定一组指令，在使用时由后台执行。
* **数据持久化**: 所有特殊属性都保存在物品的 NBT 数据中，使其永久生效。
* **冷却系统**: 为每个玩家和每种物品设置独立的冷却时间，防止滥用。
* **权限控制**: 可要求玩家拥有特定的权限节点 (commanditem.use.\) 才能使用物品。
* **可配置行为**:
* **严格模式**: 可选择始终从配置文件读取物品数据（保证一致性），或优先从物品自身读取（兼容旧版或被特殊修改的物品）。
* **消耗性物品**: 可设置物品在使用后是否被消耗。
* **实时重载**: 无需重启服务器即可重载配置和所有物品定义。
* **PlaceholderAPI 支持**: 通过变量显示物品的冷却时间和其他信息。
* **动态权限**: 插件会根据配置文件中的物品，在重载时自动注册和注销对应的使用权限。
### **前置依赖**
* **服务端**: [Purpur](https://purpurmc.org/) for Minecraft 1.21 或更高版本。
* **必需插件**: [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) (用于变量支持)。
### **安装方法**
1. 从发布页面下载最新版本的插件。
2. 确保你的服务器已安装 Purpur 1.21+ 和 PlaceholderAPI。
3. 将下载的 CommandItem2-vX.X.X.jar 文件放入服务器的 /plugins 文件夹中。
4. 启动或重启服务器。此时会自动生成一个 CommandItem2 文件夹，其中包含 config.yml 配置文件。
5. 编辑 config.yml 文件，定义你自己的特殊物品。
6. 在游戏内或后台使用 /si reload 指令来应用你的更改。
### **插件配置 (config.yml)**
配置文件主要分为两部分：strict 模式设置和 items 物品列表。
\# 严格模式 (strict mode):
\# true: 当玩家使用物品时，其属性（指令、冷却等）总是根据其ID从本文件中读取。
\# 这能确保全服的物品行为一致。
\# false: 当玩家使用物品时，其属性会优先从物品自身的PDC数据中读取。
\# 如果数据不完整，再从本文件中读取作为备用。这允许“旧版”或被特殊修改的物品存在。
strict: false
\# 特殊物品列表。这里的键（如 'fire\_sword'）是物品的唯一ID。
items:
fire\_sword:
\# 材质：必须是 Bukkit Material 中的有效名称。
material: "NETHERITE\_SWORD"
\# 名称：支持 MiniMessage 格式。
name: "\炼狱之刃\"
\# Lore：同样支持 MiniMessage。
lore:
\- "\一把在龙息中锻造的剑。"
\- "\使用它来获得火焰抗性。"
\# 附魔：附魔名称: 等级 ,当没有指定命名空间时 使用默认的"minecraft:"命名空间,它应该同样支持来自数据包或者其他插件的附魔,只要填入了正确的命名空间和完整名称
enchantments:
FIRE\_ASPECT: 2
SHARPNESS: 7
\# 由后台执行的指令列表。使用 \ 代表玩家名。
commands:
\- "effect give \ fire\_resistance 30 0 true"
\- "msg \ \剑刃保护你免受火焰伤害！"
\# 若为 true，玩家需要 'commanditem.use.fire\_sword' 权限才能使用。
permission-required: true
\# 冷却时间（秒）。
cooldown: 60
\# 若为 true，每次使用会消耗一个物品。
consume: false
\# ... 在这里添加更多物品
### **指令 & 权限**
| 指令 | 描述 | 权限 |
| :---- | :---- | :---- |
| /si reload | 重载插件的配置文件。 | commanditem.admin |
| /si get \ \[数量\] | 给予玩家一个指定的特殊物品。 | commanditem.admin |
| /si | 显示帮助信息。 | commanditem.admin |
**玩家权限:**
* commanditem.use.\: 允许玩家使用对应ID的特殊物品。例如 commanditem.use.fire\_sword。
* commanditem.use.\*: 允许玩家使用所有特殊物品。
### **变量 (PlaceholderAPI)**
你可以在任何支持 PlaceholderAPI 的插件中使用这些变量。
| 变量 | 描述 | 输出示例 |
| :---- | :---- | :---- |
| %commanditem\_cooldown\_\% | 显示一个物品格式化后的剩余冷却时间。 | 1m 15s / 可用 |
| %commanditem\_cooldown\_s\_\% | 显示剩余冷却时间的秒数。 | 75 / 0 |
| %commanditem\_name\_\% | 显示物品经过 MiniMessage 格式化后的名称。 | 炼狱之刃 |
### **从源码编译**
如果你想自己编译这个插件，请遵循以下步骤：
1. **克隆仓库:**
git clone \
cd CommandItem2
2. **确保你已安装 JDK 17 或更高版本。**
3. **使用 Gradle 构建 JAR 文件:**
* Windows 系统:
gradlew shadowJar
* Linux/macOS 系统:
./gradlew shadowJar
4. 编译好的 JAR 文件将会位于 build/libs/ 目录下。