Руководство
Как сделать кастомные предметы плагином
Обновлено: 18 октября 2026 г.
Кастомные мечи, посохи, ключи и инструменты входят в число самых востребованных функций плагинов. Плагин не может добавить в игру по-настоящему новый предмет, но может взять ванильный предмет, дать ему название, описание и скрытую метку и реагировать, когда игрок его использует. Игроки заходят с обычной игрой, моды не нужны.
Замените предметы на свои.
Сгенерировать это в CodexeШаг за шагом
1.Перечислите предметы
Для каждого предмета: базовый материал, отображаемое название, строки описания и что он делает. «Огненный стержень под названием Fire Wand, который выпускает огненный шар по правому клику, кулдаун 5 секунд» уже полностью описывает предмет.
2.Пометьте их через PersistentDataContainer
Сохраните идентификатор вроде
fire_wandвPersistentDataContainerпредмета с помощьюNamespacedKey. Плагин узнаёт предмет по этой метке, а не по названию, поэтому переименование на наковальне не создаёт копию.3.Напишите способности
Каждая способность это обработчик события:
PlayerInteractEventдля правого клика,EntityDamageByEntityEventдля ударов,BlockBreakEventдля инструментов. Добавьте кулдауны для каждого игрока и каждого предмета.4.Решите, как игроки их получают
Команда администратора
/give, рецепт крафта, магазин, дроп с мобов или награды из кейсов.5.Сделайте всё настраиваемым
Названия, описания, урон, кулдауны и рецепты в
config.yml, чтобы балансировать предметы без новой сборки.6.Соберите плагин и опробуйте каждый предмет
Дождитесь, пока Codexe скомпилирует плагин, зайдите на тестовый сервер через «Попробовать сейчас», выдайте себе каждый предмет и используйте его.
Почему метка, а не название
Проверять отображаемое название или описание это классическая ошибка: любой игрок с наковальней может переименовать палку в «Fire Wand». PersistentDataContainer (Minecraft 1.14 и новее) хранит на предмете данные, которые игроки не могут изменить, и они сохраняются после перезапусков, в сундуках и при обмене, потому что являются частью предмета.
В версиях с 1.8 по 1.13 PersistentDataContainer нет; плагины используют NBT через библиотеку или скрытую метку в описании. Укажите версию в запросе, и Codexe применит тот подход, который поддерживает эта версия.
Способности и события за ними
| Способность | Событие | Примечания |
|---|---|---|
| Сила по правому клику | PlayerInteractEvent | Проверяйте руку: событие срабатывает по разу для каждой руки |
| Дополнительный урон или эффекты при ударе | EntityDamageByEntityEvent | Проверяйте, что атакующий это игрок с этим предметом в руке |
| Инструмент для добычи по площади | BlockBreakEvent | Учитывайте плагины защиты, например WorldGuard |
| Пассивный эффект, пока предмет в руке | Повторяющаяся задача или PlayerItemHeldEvent | Снимайте эффект, когда предмет убирают |
| Лук или снаряд | EntityShootBowEvent, ProjectileHitEvent | Помечайте снаряд, чтобы знать, откуда он прилетел |
Текстуры и модели
Плагин меняет то, что предмет делает, а не то, как он выглядит. Для своего внешнего вида нужен ресурспак, который скачивают игроки: в старых версиях предмет несёт число CustomModelData, которое пак сопоставляет с моделью, а начиная с 1.21.2 предмет может указывать на собственную модель через компонент item_model. Без пака предмет выглядит как его базовый материал с особым названием, и для многих серверов этого достаточно.
Пример описания
«Плагин для Paper 1.21.4 под названием MagicItems. Три предмета, каждый с идентификатором в PersistentDataContainer: Fire Wand (огненный стержень, правый клик выпускает огненный шар, кулдаун 5 с), Frost Blade (железный меч, удары дают Замедление II на 3 с), Miner's Pick (алмазная кирка, ломает 3x3, но не в регионах WorldGuard, где игроку нельзя строить). /mi give <player> <item> для magicitems.admin. Рецепты с формой для каждого. Названия, описания, кулдауны и рецепты в config.yml.»
Вопросы
Плагин или мод для кастомных предметов?
Плагин, если игроки должны заходить с обычной игрой: предметы остаются ванильными, но с новым поведением. Мод, если нужны по-настоящему новые предметы или блоки со своей отрисовкой, и тогда его устанавливает каждый игрок. См. плагин или мод.
Можно ли использовать с ним ItemsAdder или Nexo?
Ваш плагин может зависеть от них, но это платные плагины: тестовый сервер Codexe не может их установить, поэтому плагин, которому нужен один из них, там не включится. Бесплатные зависимости из plugin.yml устанавливаются на тестовый сервер автоматически.
Перестанут ли предметы работать после обновления?
Предметы с меткой PersistentDataContainer сохраняют её при обновлениях Minecraft. Способностям может понадобиться новая сборка под новый API; см. обновление плагина.
Создайте свои кастомные предметы
Этот промпт откроется уже готовым к отправке:
“Плагин для Paper 1.21.4 под названием MagicItems с тремя предметами, помеченными через PersistentDataContainer: Fire Wand (огненный стержень, правый клик выпускает огненный шар, кулдаун 5 секунд), Frost Blade (железный меч, Замедление II на 3 секунды при ударе), Miner's Pick (алмазная кирка, копающая 3x3). /mi give для magicitems.admin, рецепт с формой для каждого предмета, названия, описания, кулдауны и рецепты в config.yml.”
Сгенерировать это в Codexe