head-vault

✨ Почему HeadVault?

Кастомные головы оживляют постройки — но выдавать их по одной команде за раз утомительно. HeadVault превращает весь каталог minecraft-heads.com в игровой магазин, который ваши игроки могут просматривать и покупать так, как удобно вам: командой, установленным NPC или жителем, которому вы дали имя. Он работает только на сервере, так что никому не нужно ничего устанавливать.

🎯 Возможности кратко

• 🛒 Настоящий магазинный GUI — категории → постраничная сетка голов → клик для покупки. Отрисовывается нативно на ванильных клиентах.
• 🌍 Весь каталог — около 90 тыс. голов в 10 категориях, загружается в реальном времени и кэшируется на диск. Обновляется в фоне; сервер никогда не лагает.
• 🔌 Всегда работает офлайн — API недоступен? Он отдаёт последний кэш, а затем снимок, вшитый в jar.
• 🔎 Поиск — находите головы по имени или тегу по всему каталогу.
• 🙂 Головы игроков — введите любой ник и получите голову этого игрока как кликабельный результат.
• 🚪 Три способа входа — команда /heads, постоянные NPC-торговцы и именованные жители. Комбинируйте как угодно.
• 🧟 Любой моб может быть торговцем (с 1.1.0) — не только жители. Дайте имя зомби, корове, кому угодно — и сделайте из него магазин. Выбирайте, какие типы мобов подходят, через режим «все», белый или чёрный список.
• 🧊 Заморозка именованных торговцев (с 1.1.0) — опционально: когда бирка с именем превращает моба в торговца, зафиксируйте его на месте (отключает AI), чтобы он не ушёл, как у заспавненного NPC. Возвращается в норму, как только вы переименуете его обратно.
• 💰 Гибкая экономика — бесплатно, за предметы или за опыт (уровни/очки), с ценой для каждой категории. Покупки атомарные.
• 📦 Головы стакаются — одинаковые головы складываются до 64.
• ♻️ Горячая перезагрузка — измените конфиг и выполните /headvault reload. Без перезапуска.
• 🔐 Права — совместимо с LuckPerms, с разумными ванильными OP-фолбэками, когда мода на права нет.
• 🪝 Расширяемость — событие PurchaseEvent, которое могут слушать другие моды.

🚀 Начало работы

1. Требования: сервер на Fabric 26.1.2 или новее с Java 25 или новее и установленным Fabric API.
2. Поместите `head-vault-.jarв папкуmods/` вашего сервера. (sgui и fabric-permissions-api встроены внутрь — больше ничего устанавливать не нужно.)
3. Запустите сервер. HeadVault запишет конфиг в config/headvault/config.json и начнёт скачивать каталог голов в фоне.
4. Выполните /heads — и вы в магазине. 🎉

При первом запуске показывается небольшая встроенная выборка, пока полный каталог не докачается (несколько секунд).

🚪 Режимы доступа

Включайте любую комбинацию в конфиге.

💰 Экономика

Выберите один глобальный режим (с необязательными переопределениями для отдельных категорий):

Каждая покупка заново проверяет стоимость в момент клика и списывает атомарно — с игрока никогда не спишут плату, не выдав его голову. Головы с ником игрока используют глобальную цену. Выдайте headvault.free-bypass, чтобы кто-то мог покупать бесплатно.

⌨️ Команды

🔐 Права

Нет мода на права? Ноды команд откатываются к ванильному уровню OP, а режимы NPC / именованного жителя работают для всех без каких-либо прав. С LuckPerms (или любым провайдером) выдавайте ноды как обычно:

/lp group default permission set headvault.command.use true

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

Конфиг лежит в config/headvault/config.json и перезагружается на лету командой /headvault reload. (Это JSON, а не YAML — под капотом Gson.) Вот полный файл со всеми опциями:

{
  "_schemaVersion": 1,

  "catalog": {
    "source": "v1",                 // откуда берутся головы: "v1" | "v2" | "bundled"
    "refreshIntervalHours": 24,      // как часто заново скачивать каталог
    "requestTimeoutSeconds": 15,     // таймаут сети на запрос
    "maxRetries": 2,                 // повторы на категорию перед сдачей
    "v2AppUuid": "",                 // только v2: ваш зарегистрированный App UUID
    "v2UrlTemplate": "",             // только v2: свой эндпоинт; плейсхолдеры {category}, {appUuid}
    "userAgent": "Mozilla/5.0 ... Chrome/126.0.0.0 Safari/537.36"  // отправляется с запросами (см. примечание)
  },

  "economy": {
    "mode": "FREE",                  // "FREE" | "ITEM" | "XP_LEVELS" | "XP_POINTS"
    "item": { "id": "minecraft:diamond", "amountPerHead": 1 },
    "xp":   { "amountPerHead": 1 },
    "categoryOverrides": {
      // переопределить цену для категории (ключ = слаг категории):
      // "monsters": { "mode": "ITEM", "item": { "id": "minecraft:netherite_ingot", "amountPerHead": 1 } }
    }
  },

  "access": {
    "command":  { "enabled": true, "permissionLevel": 2 },
    "npc":      { "enabled": true },
    "villager": {
      "enabled": true,
      "name": "Head Trader",
      "caseInsensitive": true,
      // ── начиная с 1.1.0 ──
      "mode": "ONLY_VILLAGER",        // какие мобы могут быть именованным торговцем: "ONLY_VILLAGER" | "ALL" | "MOB_WHITELIST" | "MOB_BLACKLIST"
      "entityWhitelist": [],          // id типов сущностей, разрешённых при mode = "MOB_WHITELIST", например ["minecraft:zombie"]
      "entityBlacklist": [],          // id типов сущностей, запрещённых при mode = "MOB_BLACKLIST"
      "freeze": false                 // заморозить торговца с именованным тегом на месте (отключает ИИ)
    }
  },

  "ui": {
    "title": "HeadVault",            // заголовок окна магазина
    "showPriceInLore": true,         // показывать цену на каждой голове
    "headsPerPage": 45               // 9–45 голов на страницу
  },

  "logging": { "purchaseVerbosity": "INFO" }   // "OFF" | "INFO" | "DEBUG"
}

### Справочник по полям

| Ключ | По умолчанию | Что делает |
|---|---|---|
| `catalog.source` | `"v1"` | `v1` = эндпоинт без токена, отдающий весь каталог (рекомендуется). `v2` = лицензированный REST API (нужен App UUID). `bundled` = только офлайн-снимок. |
| `catalog.refreshIntervalHours` | `24` | Интервал фонового обновления. Каталог скачивается заново, только если он старше этого срока. |
| `catalog.requestTimeoutSeconds` / `maxRetries` | `15` / `2` | Настройки устойчивости к сетевым сбоям. |
| `catalog.v2AppUuid` / `v2UrlTemplate` | `""` | Используются только когда `source` равен `v2`. Зарегистрируйтесь на minecraft-heads.com, затем укажите UUID; при необходимости поправьте шаблон под официальную документацию v2. |
| `catalog.userAgent` | строка браузера | minecraft-heads.com **отклоняет не-браузерные агенты (HTTP 403)**, поэтому по умолчанию используется браузерная строка. Оставьте как есть, если не уверены, что API примет ваш агент. |
| `economy.mode` | `"FREE"` | Глобальный режим оплаты. |
| `economy.item` / `economy.xp` | diamond×1 / 1 | Глобальная цена для режимов `ITEM` / `XP_*`. |
| `economy.categoryOverrides` | `{}` | Переопределение цен по категориям, ключ — слаг (`alphabet`, `animals`, `blocks`, `decoration`, `food-drinks`, `humanoid`, `humans`, `miscellaneous`, `monsters`, `plants`). |
| `access.command.enabled` / `permissionLevel` | `true` / `2` | Включает магазин `/heads` и его уровень OP по умолчанию. |
| `access.npc.enabled` | `true` | Включает NPC-торговцев. |
| `access.villager.enabled` / `name` / `caseInsensitive` | `true` / `Head Trader` / `true` | Включает режим именованного торговца, имя-триггер и учёт регистра при совпадении имени. |
| `access.villager.mode` *(с 1.1.0)* | `"ONLY_VILLAGER"` | Какие типы сущностей могут быть именованным торговцем: `ONLY_VILLAGER` (только жители — по умолчанию, поведение не меняется), `ALL` (любой моб), `MOB_WHITELIST` (только id из `entityWhitelist`), `MOB_BLACKLIST` (любой моб, кроме id из `entityBlacklist`). |
| `access.villager.entityWhitelist` / `entityBlacklist` *(с 1.1.0)* | `[]` / `[]` | Id типов сущностей (например, `"minecraft:zombie"`; голый `"zombie"` подразумевает пространство имён `minecraft`, совпадение без учёта регистра), используемые режимами `MOB_WHITELIST` / `MOB_BLACKLIST`. |
| `access.villager.freeze` *(с 1.1.0)* | `false` | Когда табличка с именем превращает моба в торговца, заморозить его на месте — отключает AI, чтобы он перестал бродить, как заспавненный NPC. Автоматически отменяется, когда моба переименовывают так, что он больше не подходит. Выкл. (по умолчанию) = поведение не меняется. |
| `ui.title` / `showPriceInLore` / `headsPerPage` | `HeadVault` / `true` / `45` | Косметические настройки магазина. |
| `logging.purchaseVerbosity` | `"INFO"` | Насколько подробно покупки пишутся в консоль. |

### О источнике каталога

minecraft-heads.com предлагает два API:

- **`v1`** *(по умолчанию)* — эндпоинт `scripts/api.php`. **Без токена**, отдаёт весь каталог. Официально «устарел», но работает по состоянию на 2026; сайт блокирует не-браузерные User-Agent, поэтому стандартный `userAgent` выглядит как браузерный.
- **`v2`** — текущий лицензированный REST API. Требует бесплатный **зарегистрированный App UUID** и видимую атрибуцию Minecraft-Heads.com; коммерческое распространение без одобрения запрещено. Переключайтесь на него, если v1 когда-нибудь отключат.
- **`bundled`** — вообще не обращается к сети; отдаёт небольшой снимок, вшитый в jar.

Если живой источник недоступен, HeadVault автоматически переключается на последний кэш, затем на вшитый снимок — магазин никогда не гаснет.

## 🙌 Благодарности

- Данные голов с [minecraft-heads.com](https://minecraft-heads.com).
- [sgui](https://github.com/Patbox/sgui) и [fabric-permissions-api](https://github.com/lucko/fabric-permissions-api) за GUI и права.
- Вдохновлено [HeadIndex](https://github.com/PotatoPresident/HeadIndex).

## 📄 Лицензия

Распространяется под лицензией MIT.