✨ Why HeadVault?

Custom heads make builds come alive — but handing them out one command at a time is painful. HeadVault turns the entire minecraft-heads.com catalog into an in-game shop your players can browse and buy from, however you want to run it: a command, a placed-down NPC, or a villager you name. It’s server-side only, so nobody needs to install anything to use it.

🎯 Features at a glance

• 🛒 A real shop GUI — categories → paginated head grid → click to buy. Renders natively on vanilla clients.
• 🌍 The whole catalog — ~90k heads across 10 categories, fetched live and cached to disk. Refreshes in the background; never lags the server.
• 🔌 Always works offline — unreachable API? It serves the last cache, then a snapshot baked into the jar.
• 🔎 Search — find heads by name or tag across the entire catalog.
• 🙂 Player heads — type any username and get that player’s head as a clickable result.
• 🚪 Three ways in — /heads command, persistent shopkeeper NPCs, and named villagers. Mix and match.
• 🧟 Any mob can be a trader (since 1.1.0) — not just villagers. Name-tag a zombie, a cow, anything, and make it a shop. Choose which mob types qualify via an allow-all, whitelist, or blacklist mode.
• 🧊 Freeze named traders (since 1.1.0) — opt-in: when a name tag turns a mob into a trader, lock it in place (disables AI) so it can't wander off, just like a spawned NPC. Reverts the moment you rename it back.
• 💰 Flexible economy — free, item cost, or experience (levels/points), with per-category pricing. Purchases are atomic.
• 📦 Heads stack — identical heads stack to 64.
• ♻️ Hot reload — tweak the config and run /headvault reload. No restart.
• 🔐 Permissions — LuckPerms-compatible, with sane vanilla-OP fallbacks when no permission mod is present.
• 🪝 Extensible — a PurchaseEvent other mods can listen to.

🚀 Getting started

1. Requirements: a Fabric 26.1.2 or Greater server on Java 25 or Greater, with Fabric API installed.
2. Drop head-vault-<version>.jar into your server’s mods/ folder. (sgui and fabric-permissions-api are bundled inside — nothing else to install.)
3. Start the server. HeadVault writes its config to config/headvault/config.json and begins downloading the head catalog in the background.
4. Run /heads — and you’re shopping. 🎉

First launch shows a small built-in sample until the full catalog finishes downloading (a few seconds).

🚪 Access modes

Enable any combination in the config.

💰 Economy

Pick one global mode (with optional per-category overrides):

Every purchase re-checks the cost at click time and deducts atomically — players can never be charged without receiving their head. Player-name heads use the global price. Grant headvault.free-bypass to let someone shop for free.

⌨️ Commands

🔐 Permissions

No permission mod? Command nodes fall back to the vanilla OP level, and NPC / named-villager modes work for everyone without any permission. With LuckPerms (or any provider) grant nodes normally:

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

⚙️ Configuration

The config lives at config/headvault/config.json and hot-reloads with /headvault reload. (It’s JSON, not YAML — Gson under the hood.) Here’s the full file with every option:

{
  "_schemaVersion": 1,

  "catalog": {
    "source": "v1",                 // where heads come from: "v1" | "v2" | "bundled"
    "refreshIntervalHours": 24,      // how often to re-download the catalog
    "requestTimeoutSeconds": 15,     // per-request network timeout
    "maxRetries": 2,                 // retries per category before giving up
    "v2AppUuid": "",                 // v2 only: your registered App UUID
    "v2UrlTemplate": "",             // v2 only: custom endpoint; placeholders {category}, {appUuid}
    "userAgent": "Mozilla/5.0 ... Chrome/126.0.0.0 Safari/537.36"  // sent with requests (see note)
  },

  "economy": {
    "mode": "FREE",                  // "FREE" | "ITEM" | "XP_LEVELS" | "XP_POINTS"
    "item": { "id": "minecraft:diamond", "amountPerHead": 1 },
    "xp":   { "amountPerHead": 1 },
    "categoryOverrides": {
      // override price per category (key = category slug):
      // "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,
      // ── since 1.1.0 ──
      "mode": "ONLY_VILLAGER",        // which mobs may be a named trader: "ONLY_VILLAGER" | "ALL" | "MOB_WHITELIST" | "MOB_BLACKLIST"
      "entityWhitelist": [],          // entity type ids allowed when mode = "MOB_WHITELIST", e.g. ["minecraft:zombie"]
      "entityBlacklist": [],          // entity type ids blocked when mode = "MOB_BLACKLIST"
      "freeze": false                 // freeze a name-tagged trader in place (disables AI)
    }
  },

  "ui": {
    "title": "HeadVault",            // shop window title
    "showPriceInLore": true,         // show the price on each head
    "headsPerPage": 45               // 9–45 heads per page
  },

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

Field reference

About the catalog source

minecraft-heads.com offers two APIs:

• v1 (default) — the scripts/api.php endpoint. No token, serves the entire catalog. Officially “deprecated” but live as of 2026; the site blocks non-browser User-Agents, which is why the default userAgent looks like a browser.
• v2 — the current licensed REST API. Requires a free registered App UUID and a visible Minecraft-Heads.com attribution; commercial redistribution isn’t allowed without approval. Switch to this if v1 is ever retired.
• bundled — never touches the network; serves the small snapshot baked into the jar.

If the live source is unreachable, HeadVault automatically falls back to the last cache, then the bundled snapshot — the shop never goes dark.

🙌 Credits

• Head data from minecraft-heads.com.
• sgui & fabric-permissions-api for GUIs and permissions.
• Inspired by HeadIndex.

📄 License

Released under MIT License.