Dex Cosmetics

Dex Cosmetics

Серверный мод на косметику для Fabric 1.21.1. Шляпы, предметы на спине (плащи, крылья, рюкзаки), скины для предметов и визуальные эффекты (частицы, светящиеся контуры, частицы в формате Bedrock). Устанавливается на 100% на сервере — ванильные клиенты видят всё благодаря автоматически раздаваемому ресурспаку Polymer.

Требования

• Minecraft: 1.21.1
• Загрузчик модов: Fabric 0.19.2 или новее
• Только на сервере — клиенты играют на ванилле; установка на клиент не нужна

Зависимости

Установка

1. Закиньте jar мода в папку mods/ вашего сервера вместе с обязательными зависимостями (Fabric API, Fabric Language Kotlin, все четыре модуля Polymer, sgui, placeholder-api).
2. Запустите сервер один раз — при первом запуске он создаст config/dex_cosmetics/ с файлом настроек по умолчанию, примерами косметики и структурой папок для добавления своей.
3. (Опционально) Установите LuckPerms, если хотите доступ к админ-командам по правам. Без него админ-команды требуют op-уровень 4.
4. (Опционально) Установите Cobblemon, если хотите эффекты частиц снежной бури. Без него эта косметика всё равно загружается, но ничего не отрисовывает.

Клиенты подключаются как обычно — Polymer-autohost автоматически раздаёт ресурспак при входе. По умолчанию пак помечен как обязательный; отказавшиеся игроки будут кикнуты. Это настраивается.

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

Глобальный конфиг — config/dex_cosmetics/config.json

{
  "require_resource_pack": true,
  "resource_pack_kick_message": "This server requires the Dex Cosmetics resource pack.",
  "autosave_interval_seconds": 300,
  "particle_tick_budget_per_player": 32,
  "admin_permission": "dexcosmetics.admin",
  "allow_item_skin_sharing": true,
  "rename_item_to_skin_name": false,
  "resource_pack_mode": "auto",
  "custom_model_data_start": 2000,
  "menu_categories": {
    "ITEM": true,
    "HAT": true,
    "BACK": true,
    "EFFECT": true,
    "BALLOON": false,
    "POKEMON": false
  },
  "menu_focus": "HAT"
}

• require_resource_pack — если true, отказавшиеся от пака клиенты кикаются с сообщением resource_pack_kick_message. Поставьте false, чтобы пускать игроков без него (они увидят всё ванильным).
• autosave_interval_seconds — сейчас носит информационный характер; данные игроков сохраняются при каждой выдаче/изъятии/надевании.
• particle_tick_budget_per_player — сейчас носит информационный характер; косметика с частицами ограничивается через interval_ticks для каждой косметики.
• admin_permission — нода прав LuckPerms, проверяемая для /cosmetics give/take/list/reload/generatepack. Без LuckPerms требуется op-уровень 4.
• allow_item_skin_sharing — если true (по умолчанию), предметы со скинами сохраняют скин при выбросе/обмене. Если false, компонент скина снимается в момент, когда предмет подбирает не владелец.
• rename_item_to_skin_name — если true, предметы с нанесённым скином показывают отображаемое имя косметики вместо ванильного имени предмета. Подмена имени происходит при синхронизации на клиентской копии, так что обмен не переименовывает сам стак навсегда.

Определения косметики — `config/dex_cosmetics/cosmetics//.json`

Один JSON-файл на косметику, сгруппированы в четыре подкаталога:

• hats/ — экипировка для головы (type: HAT)
• back/ — плащи, крылья, рюкзаки (type: BACK)
• items/ — скины для предметов в руке (type: ITEM)
• effects/ — частицы, свечение, снежная буря (type: EFFECT)

Каждый файл определяет:

{
  "id": "my_cosmetic",
  "type": "HAT",
  "display_name": "<gold>My Hat</gold>",
  "description": ["Lore line 1", "Lore line 2"],
  "model": "dex_cosmetics:hats/my_cosmetic",
  "texture": "dex_cosmetics:hats/my_cosmetic/my_cosmetic",
  "model_parent": "minecraft:item/generated",
  "transform": {
    "offset_x": 0, "offset_y": 0, "offset_z": 0,
    "scale_x": 1, "scale_y": 1, "scale_z": 1
  }
}

По типам:

• HAT — использует transform, чтобы запечь смещение/масштаб в перспективу display.head модели.
• BACK — читается только scale.x (равномерный масштаб через атрибут SCALE). Позиция задаётся ванильной логикой крепления на стойке для брони.
• ITEM — нужен item_skin: { compatible_items: [...] }. Каждая запись — это id предмета (minecraft:diamond_sword) или тег (#minecraft:swords).
• EFFECT — нужен effect: { kind: "particle" | "glow" | "snowstorm", ... }. Смотри примеры в комплекте в cosmetics/effects/.

Модели — `config/dex_cosmetics/model//.json`

Положи сюда экспорт из Blockbench с именем по id косметики; пак подхватит его автоматически. Если файла нет, создаётся простая модель {parent, layer0} из полей model_parent и texture косметики.

Для инструментов в руке (скины предметов и т.п.) убедись, что у модели есть "parent": "minecraft:item/handheld" и корректный display.

Текстуры — `config/dex_cosmetics/textures///`

Файл по пути textures/hats/my_hat/example.png попадает в пак как assets/dex_cosmetics/textures/hats/my_hat/example.png и доступен по ссылке dex_cosmetics:hats/my_hat/example. Файлы .mcmeta рядом с PNG проходят насквозь, так что анимированные текстуры работают.

Частицы снежной бури — `config/dex_cosmetics/snowstorm_particles/.particle.json`

Определения частиц в формате Bedrock. Поле description.identifier внутри JSON — это то, на что ссылается косметика EFFECT через effect.snowstorm.particle_id. BedrockParticleEffectRepository из Cobblemon подхватывает их во время сборки пака.

Возможности

Типы косметики

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

Предметы на спине — невидимая сущность-маркер, прикреплённая пассажиром к носителю, с косметическим предметом в слоте экипировки HEAD. Автоматически скрывается во время поз SWIMMING / FALL_FLYING / SLEEPING / SPIN_ATTACK и возвращается при выходе из позы.

Скины предметов — игроки применяют скины через GUI косметики, держа нужный предмет и кликая по иконке скина. Есть опциональная настройка, снимающая скин, когда предмет подбирает не владелец.

Эффекты — три вида через поле kind:

• Particle: ванильные частицы. Два режима создания — встроенные готовые формы (point / trail / halo / orbit / square) с параметрами тип частицы + количество + радиус, ИЛИ сырые ванильные команды, выполняемые в позиции носителя с op-уровнем и без вывода в чат.
• Glow: ванильный эффект статуса GLOWING, обновляемый каждый тик. Цвет контура для каждой косметики через членство в команде скорборда (одна команда `dex_glow_` на каждый цвет Formatting).
• Snowstorm: вспышка частиц в формате Bedrock через SpawnSnowstormParticlePacket из Cobblemon. Ограничивается по interval_ticks, рассылается в пределах broadcast_radius блоков от носителя.

Личная собственность для каждого игрока

Учёт косметики для каждого игрока на базе SQLite. Игроки видят весь каталог в GUI, но могут надеть только ту косметику, которой владеют. Админы выдают/забирают её через команды.

Хранилище лежит в `/dex_cosmetics/cosmetics.db. Две таблицы: player_owned (uuid, cosmetic_id)иplayer_equipped (uuid, type, cosmetic_id)`. Схема создаётся при первом запуске.

Интеграция с кейсами / магазином

Существующие плагины кейсов, магазины и таблицы лута выдают косметику, выполняя:

/cosmetics give <player> <cosmetic_id>

(или /cosmetics take, чтобы забрать). Это поддерживаемая точка интеграции — всё, что умеет выполнять консольную команду, может выдавать косметику.

Команды игрока

Сборка ресурспака происходит на SERVER_STARTING после загрузки тегов:

1. CosmeticItems.registerAll выделяет по одному CMD на каждую косметику + на каждый вариант (скин, предмет) через PolymerResourcePackUtils.requestModel.
2. DexCosmetics.buildResourcePack запускает RESOURCE_PACK_CREATION_EVENT от Polymer.
3. Обработчики события выполняют pipeUserTextures, pipeSnowstormParticles, PackModelGenerator.writeAll, GlowIconGenerator.writeAll и записывают переопределения атласа блоков + частиц.
4. polymer-autohost раздаёт получившийся polymer/resource_pack.zip при последующих заходах.

Создание косметики

1. Модель: в Blockbench сделайте косметику. Используйте тип проекта Java Block/Item, чтобы экспорт включал блоки parent и display.
2. Текстура: экспортируйте PNG и положите его в `config/dex_cosmetics/textures///.png`.
3. Конфиг косметики: напишите JSON-файл в `config/dex_cosmetics/cosmetics//.json` (по образцу приложенных примеров).
4. Файл модели (необязательно, но часто нужен): если у вас экспорт из Blockbench с несколькими текстурами, кастомными элементами и т. д., сохраните его как `config/dex_cosmetics/model//.json`.
5. Перезагрузка: /cosmetics reload или перезапуск сервера. Игрокам нужно переподключиться, чтобы заново скачать обновлённый пак.