Конфигурация FreeMinecraftModels

registerCraftingRecipes в config.yml по умолчанию равно true. Для экономики только с покупками установите false и перезапустите сервер: рецепты останутся в меню и магазине, но рецепты крафта Bukkit будут удалены. Инструкции по крафту на этой странице требуют true.

На этой странице описаны текущие настройки config.yml и shop_config.yml, существенно влияющие на настройку, отрисовку, взаимодействие с игроком и опциональный магазин мебели.

Расположение файлов

plugins/FreeMinecraftModels/config.yml
plugins/FreeMinecraftModels/shop_config.yml

shop_config.yml создаётся при первом запуске; сам магазин остаётся отключённым, пока вы его не включите.

Минимальная версия сервера

В plugin.yml объявлено api-version: 1.21.4, поэтому Minecraft 1.21.4 — минимальная поддерживаемая версия сервера. Поддержка более старых линеек прекращена; устаревшие ветки отрисовки/вывода всё ещё есть в коде, но на сервере, способном загрузить плагин, они больше недостижимы.

Настройки config.yml

setupDone

• По умолчанию: false
• Управляет тем, считается ли подсказка по первичной настройке завершённой
• Игроки с широкими правами FreeMinecraftModels получают напоминание о запуске /fmm setup, пока значение остаётся false
• Процесс настройки переключает это значение за вас; редактировать вручную при обычной настройке не нужно

nightbreak.autoDownloadPluginUpdates

• По умолчанию: false
• Общая настройка MagmaCore (находится в секции nightbreak: файла config.yml)
• Когда true, FreeMinecraftModels автоматически скачивает при запуске доступные обновления jar плагина и файлы обновлений контента
• Скачанные обновления плагина и контента применяются только после перезапуска сервера
• Это эквивалент в виде ключа конфига для запуска /fmm downloadpluginupdate / /fmm downloadall при каждом старте; переключайте его из меню /fmm setup или вручную

useDisplayEntitiesWhenPossible

• По умолчанию: true
• Указывает FreeMinecraftModels предпочитать рендеринг через display-сущности, когда это поддерживают сервер и клиент
• Плагин при необходимости откатывается на отображение через armor stand, если display-сущности недоступны (версии старше 1.19.4 или Bedrock)
• Bedrock-клиенты — особый случай, поэтому не стоит считать, что этот параметр форсирует один и тот же путь отрисовки для всех игроков

maxModelViewDistance

• По умолчанию: 60
• Ограничивает, на какое расстояние моделированные сущности отправляются зрителям
• Более низкие значения снижают нагрузку на пакеты и клиентскую отрисовку в плотно заставленных моделями зонах
• Отдельные сущности могут переопределить это значение во время выполнения через ModeledEntity.setViewDistanceOverride(int) — см. руководство по API

maxInteractionAndAttackDistance

• По умолчанию: 3
• Применяется к статическим и динамическим моделированным сущностям
• Используется проверками взаимодействия и попадания во время выполнения

maxInteractionAndAttackDistanceForProps

• По умолчанию: 6
• Применяется к сущностям-реквизитам
• Это значение отделено от дистанции взаимодействия для статических/динамических сущностей

sendCustomModelsToBedrockClientsV2

• По умолчанию: true
• Управляет тем, пытается ли FreeMinecraftModels отправлять пользовательские модели Bedrock-клиентам
• Этот ключ заменяет более старый sendCustomModelsToBedrockClients (у которого по умолчанию было false). Переименование в V2 переворачивает значение по умолчанию, так что Bedrock-игроки видят модели по умолчанию; если вы ранее явно задавали старый ключ, можете удалить его — новый ключ V2 возьмёт верх
• Если отключено, Bedrock-игроки видят базовую ванильную сущность, если она есть (и маскировки для них не отображаются)
• Если вы это включаете, убедитесь, что ваш путь ресурс-пака для Bedrock/Geyser/Floodgate действительно готов для таких клиентов
• Диагностическое логирование во время выполнения для пайплайна отображения Bedrock не является ключом конфига — оно переключается во время выполнения через /fmm debug bedrock on|off, чтобы случайно не остаться включённым в продакшене. См. Команды

skipUnchangedBoneUpdates

• По умолчанию: true
• Когда true, кость модели отправляет зрителям свои потиковые пакеты перемещения/метаданных, только если её позиция, поворот или масштаб действительно изменились с прошлого тика
• Совершенно неподвижные кости (статичные реквизиты, простаивающие части модели) не отправляют ничего, что сильно снижает пакетную нагрузку на клиента в плотных зонах вроде хабов NPC и городов
• Периодическая полная ресинхронизация по-прежнему выполняется, поэтому редкие рассинхронизации клиента самоустраняются
• Ставьте false, только чтобы вернуть старое поведение «всегда пересылать каждую кость каждый тик» для отладки

useDeltaMetadataPackets

• По умолчанию: true
• Когда true, потиковый пакет метаданных для костей модели на display-сущностях отправляет только изменившиеся значения (трансформацию кости), а не сериализует заново весь блоб item-display (модель предмета + custom model data) каждый тик
• Полное состояние по-прежнему отправляется, когда игрок впервые видит модель, и при периодической ресинхронизации
• Ставьте false, чтобы вернуть старое поведение с полным снимком каждый тик для отладки или сравнения

maxModelsForProximityOverride

• По умолчанию: 25
• Псевдо-балансировщик нагрузки для переопределения видимости на ближней дистанции
• Обычно модель в пределах 10 блоков от игрока показывается всегда, минуя рейтрейс линии видимости, чтобы модели, рядом с которыми вы стоите, не «выскакивали»
• В плотной зоне (например, многоэтажный хаб NPC) это переопределение превращает десятки моделей, которых игрок на самом деле не видит — на других этажах, за стенами, — в зрителей, отправляющих пакеты каждый тик
• Когда в мире загружено хотя бы столько моделей, переопределение ближней дистанции отключается в этом мире, поэтому рейтрейс перекрытия выполняется даже вблизи и отсекает модели, до которых у игрока нет линии видимости. В разреженных мирах переопределение сохраняется, поэтому там остаётся поведение без «выскакивания»
• Решение принимается для каждого мира, а не глобально, поэтому переполненный мир-хаб не наказывает тихие
• Поднимите значение очень высоко, чтобы фактически вернуть поведение с постоянным переопределением; задайте 0, чтобы всегда требовать линию видимости
• /fmm packetdebug — предназначенный для этого инструмент измерения эффекта — см. Команды

preventPropPlacementInProtectedRegions

• По умолчанию: true
• Когда true, FreeMinecraftModels спрашивает у зарегистрированных в MagmaCore провайдеров защиты, может ли именно этот игрок строить в ячейке, которую займёт реквизит, и отклоняет размещение, если ответ отрицательный
• Игроки с правом freeminecraftmodels.bypassregionprotection (по умолчанию: op) полностью пропускают проверку и никогда не блокируются
• Встроенные провайдеры, учитывающие игрока, сейчас покрывают WorldGuard и GriefPrevention. Любой другой плагин может зарегистрировать провайдер защиты MagmaCore и будет учитываться так же. Если провайдер не зарегистрирован, проверка не имеет эффекта
• Сообщение об отказе: You don't have permission to place a model here!

Проверка учитывает игрока, а не только регион. Более ранние версии спрашивали «находится ли эта локация внутри какого-либо защищённого региона?» и блокировали всех. Текущая проверка спрашивает «может ли этот игрок здесь строить?», поэтому игрок, который законно владеет приватом, или является его доверенным участником, или находится внутри собственного региона WorldGuard, может нормально размещать там реквизиты. Отклоняются только те игроки, которые не смогли бы поставить в этой ячейке ванильный блок.

Каждое размещение получает проверку одной ячейки; воксельные реквизиты получают вторую, по всему объёму:

Тип реквизита	Проверяемые ячейки
Обычный (свободной формы) реквизит	Одна ячейка, примыкающая к грани блока, по которой кликнули, — та ячейка, которую займёт реквизит
Реквизит с voxelize: true	Сначала та же примыкающая ячейка, затем каждая ячейка в повёрнутом footprint реквизита (ширина x высота x глубина) вокруг точки размещения, выровненной по сетке. Если любая ячейка в этом объёме недоступна, отклоняется всё размещение

Проверка по объёму существует потому, что воксельный реквизит может быть шириной в несколько блоков, и проверка только кликнутой ячейки позволила бы игроку встать на границе привата и уронить большой реквизит в чужую постройку. Она выполняется после проверки свободного места, поэтому Not enough space to place this model! по-прежнему имеет приоритет, когда footprint физически перекрыт.

примечание

Право обхода проверяется до запроса к провайдеру, поэтому выдача freeminecraftmodels.bypassregionprotection — поддерживаемый способ разрешить персоналу размещать реквизиты где угодно без отключения этого ключа на всём сервере.

shop_config.yml

Опциональный магазин мебели на базе Vault живёт в собственном конфиге, чтобы его можно было включать и настраивать независимо от основного поведения плагина. Магазин отказывается регистрироваться, если отсутствует Vault или экономический провайдер.

Ключи верхнего уровня

Ключ	По умолчанию	Описание
enabled	false	Главный переключатель /fmm shop. Команда регистрируется только когда значение true, а также присутствуют Vault и экономический провайдер
defaultPrice	100.0	Цена, записываемая в файлы рецептов, у которых при следующей загрузке не указано собственное shopPrice
menuTitle	&8FMM - Furniture Shop	Заголовок, отображаемый в верхней части инвентаря магазина (поддерживает цветовые коды &)
priceLoreFormat	&7Price: &e{price}	Строка lore, добавляемая к каждому товару в магазине с указанием цены. Плейсхолдер: {price}
clickToBuyLoreFormat	&aClick to purchase	Строка lore, добавляемая к каждому товару в магазине с предложением о покупке

Ключи сообщений (messages.*)

Все строки сообщений поддерживают цветовые коды &.

Ключ	По умолчанию	Плейсхолдеры
messages.purchaseSuccess	&aPurchased &f{item} &afor &e{price}&a. Balance: &e{balance}&a.	{item}, {price}, {balance}
messages.insufficientFunds	&cYou need &e{price} &cto buy &f{item}&c. Balance: &e{balance}&c.	{item}, {price}, {balance}
messages.shopDisabled	&cThe furniture shop is currently unavailable.	нет
messages.itemNotForSale	&cThat item is not currently for sale.	{item}
messages.inventoryFull	&eYour inventory was full; &f{item} &ehas been dropped at your feet.	{item}

Поля магазина в рецептах

Каждый файл рецепта в plugins/FreeMinecraftModels/recipes/<model_id>.yml получает два дополнительных поля:

Поле	По умолчанию	Описание
shopEnabled	true	Виден ли этот рецепт в /fmm shop. Рецепты с shopEnabled: false по-прежнему доступны в крафте, но никогда не выставляются на продажу
shopPrice	defaultPrice из shop_config.yml	Стоимость в валюте Vault для этого конкретного предмета

Конструктор рецептов (/fmm craftify) записывает оба поля при сохранении, поэтому настройка цены — это просто правка в тексте.

Права доступа

Зарегистрированы в plugin.yml

Право	По умолчанию	Описание
freeminecraftmodels.*	op	Wildcard, дающий права admin, deleteall, маскировку себя/других и обход защиты регионов
freeminecraftmodels.admin	op	Доступ к /fmm admin (админский браузер контента) и /fmm giveitem. Остальные админ/отладочные команды (/fmm location, /fmm spawn, /fmm mount, /fmm itemify, /fmm craftify, /fmm reload, /fmm stats, /fmm hitbox visualize, /fmm debug, /fmm packetdebug, /fmm setup, /fmm initialize, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent, /fmm downloadpluginupdate, /fmm forcereinstallcontent) вместо этого проверяют wildcard freeminecraftmodels.*
freeminecraftmodels.deleteall	op	Потомок wildcard; доступ к /fmm deleteall
freeminecraftmodels.disguise.self	op	Разрешает /fmm disguise / /fmm undisguise для отправителя
freeminecraftmodels.disguise.others	op	Разрешает целевую маскировку/снятие маскировки, а также /fmm disguiselist
freeminecraftmodels.bypassregionprotection	op	Размещение реквизитов и взаимодействие с ними где угодно, где другой плагин заблокировал бы обычную установку блоков, даже когда включён preventPropPlacementInProtectedRegions
freeminecraftmodels.menu	true	Доступ к меню крафтящихся предметов /fmm
freeminecraftmodels.shop	true	Доступ к /fmm shop
nightbreak.login	op	Регистрируется MagmaCore, а не через plugin.yml. Требуется для общих команд /nightbreaklogin и /nightbreaklogout

Конфигурация YML модели

У каждого файла .bbmodel может быть сопутствующий файл .yml (с тем же именем в той же папке), управляющий настройками конкретной модели. Унифицированный формат YML поддерживает следующие поля:

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
  - "&7Deals frost damage"
enchantments:
  - SHARPNESS,3
  - UNBREAKING,2

Поле	Тип	Описание
isEnabled	boolean	Загружена ли модель (по умолчанию: true)
scripts	список строк	Имена файлов Lua-скриптов, которые нужно прицепить из plugins/FreeMinecraftModels/scripts/. Указывайте .lua для ясности; записи в конфиге без .lua принимаются и разрешаются в файлы .lua.
voxelize	boolean	Когда true, реквизит привязывается к шагам поворота 90 градусов и при размещении выравнивается по сетке блоков. Размер основания рассчитывается из размеров хитбокса модели (округлённых до целых блоков). При размещении проверяется, что все блоки основания не являются твёрдыми.
solidify	boolean	Когда true (требует voxelize: true), в каждом блоке основания реквизита размещаются барьерные блоки только в пакетах, что даёт ему коллизию на стороне клиента. Эти барьеры невидимы и существуют только в пакетах — в мир они не помещаются. Барьеры автоматически удаляются, когда реквизит подбирают или уничтожают.
material	string	Имя материала Bukkit (например, DIAMOND_SWORD, PAPER). При установке модель становится пользовательским предметом, который игроки могут держать и экипировать
name	string	Отображаемое имя пользовательского предмета (поддерживает цветовые коды &)
lore	список строк	Строки lore для пользовательского предмета (поддерживает цветовые коды &)
enchantments	список строк	Зачарования в формате ENCHANTMENT_NAME,LEVEL (например, SHARPNESS,3)

Когда задан material, модель регистрируется как пользовательский предмет. Игроки могут получить его через /fmm giveitem, скрафтить, если настроен рецепт, и он получает доступ ко всем 22 Lua-хукам предметов.

Реквизиты выполняют каждый скрипт, перечисленный в scripts:, как независимые экземпляры. Пользовательские предметы сейчас используют только первый валидный скрипт из списка; дополнительные записи после первого игнорируются при привязке к среде выполнения предмета.

Эксплуатационные заметки

• /fmm reload повторно импортирует контент и перегенерирует выходной пак, поэтому изменения конфигурации, влияющие на поведение отрисовки, легче всего проверить после перезагрузки. При каждой перезагрузке рассылается FmmReloadedEvent, чтобы зависимые плагины могли переподключить свои привязки к моделям.
• Сгенерированный пак побайтово стабилен, поэтому его перегенерация из неизменного набора моделей даёт идентичный zip и SHA1. Именно это позволяет ResourcePackManager пропускать лишнюю повторную загрузку. См. Вывод ресурс-пака.
• FreeMinecraftModels только генерирует ресурс-пак; сам он его не хостит.
• ResourcePackManager по-прежнему является рекомендуемым способом доставки для Java-клиентов и самым безопасным задокументированным путём для смешанных конфигураций.
• WorldGuard, WorldEdit, GriefPrevention, Vault, floodgate и Geyser-Spigot объявлены как softdepend в plugin.yml — ни один из них не требуется для запуска плагина, но при наличии они открывают конкретные функции: WorldGuard/WorldEdit/GriefPrevention питают и Lua-предикаты, учитывающие защиту, и проверку размещения реквизитов с учётом игрока, Vault включает магазин мебели, а floodgate/Geyser-Spigot включают бэкенд отрисовки для Bedrock.

Когда менять эти значения

Используйте этот конфиг для настройки поведения во время выполнения, а не для управления пакетами контента.

• Для работы с жизненным циклом официальных пакетов используйте /fmm setup, /fmm downloadall и /fmm updatecontent
• Используйте папку imports для ручного импорта .bbmodel или другого локального контента
• Используйте config.yml, когда нужно подкрутить режим отрисовки, дальность видимости, дистанцию взаимодействия, поведение Bedrock, применение защиты регионов или автоматическое скачивание обновлений
• Используйте skipUnchangedBoneUpdates, useDeltaMetadataPackets и maxModelsForProximityOverride для настройки пакетов/трафика в мирах с плотной застройкой моделями. Все три по умолчанию уже настроены на оптимизированное поведение; значения false / очень высокие существуют для отладки и A/B-сравнения, а не как рекомендуемые продакшн-значения
• Используйте shop_config.yml (и поля shopEnabled/shopPrice в рецептах), чтобы настраивать магазин мебели без правок кода

Известные особенности

• Поведение на Bedrock зависит и от sendCustomModelsToBedrockClientsV2, и от вашей более широкой настройки Floodgate/Geyser/ресурс-пака, поэтому делайте осторожные выводы, если не тестировали конкретно свой стек.
• Магазин молча отключается, если отсутствует Vault или экономический провайдер. Если /fmm shop неожиданно недоступен, используйте /fmm version и проверьте консоль при запуске.