head-vault

✨ 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.

| Mode | How it works |
|—|—|
| Command | /heads opens the shop (permission-gated). |
| NPC | /headvault npc spawn <name> places an invulnerable, AI-less shopkeeper villager. It persists across restarts; right-click opens the shop. Manage with npc list / npc remove. |
| Named villager | Name any villager your configured name (default “Head Trader”) and right-clicking it opens the shop for everyone — no permission needed. Hold a name tag to rename it back to normal. Since 1.1.0: via access.villager.mode you can let any mob be a named trader — not just villagers (all / whitelist / blacklist); and access.villager.freeze can lock a fresh trader in place. |

💰 Economy

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

| Mode | Players pay… |
|—|—|
| FREE | nothing |
| ITEM | a configurable item × amount (e.g. 1 diamond) |
| XP_LEVELS | experience levels |
| XP_POINTS | total experience points |

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

| Command | Description | Permission (default) |
|—|—|—|
| /heads | Open the shop | headvault.command.use (OP 2) |
| /heads search <query> | Search heads by name/tag | headvault.command.search |
| /heads player <name> | Get a specific player’s head | headvault.command.use |
| /heads give <player> <head-id> | Give a head for free (head-id = its UUID) | headvault.command.give / headvault.admin |
| /headvault reload | Reload the config | headvault.admin |
| /headvault npc spawn <name> | Spawn a shop NPC where you stand | headvault.npc.manage |
| /headvault npc remove | Remove the NPC you’re looking at | headvault.npc.manage |
| /headvault npc list | List loaded shop NPCs | headvault.npc.manage |

🔐 Permissions

| Node | Grants |
|—|—|
| headvault.command.use | Open the shop, /heads player |
| headvault.command.search | /heads search |
| headvault.command.give | /heads give |
| headvault.admin | /headvault reload, /heads give |
| headvault.npc.manage | Spawn / remove / list NPCs |
| headvault.free-bypass | Always pay nothing |

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

| Key | Default | What it does |
|—|—|—|
| catalog.source | "v1" | v1 = the no-token endpoint serving the full catalog (recommended). v2 = the licensed REST API (needs an App UUID). bundled = the offline snapshot only. |
| catalog.refreshIntervalHours | 24 | Background refresh interval. The catalog is only re-downloaded when older than this. |
| catalog.requestTimeoutSeconds / maxRetries | 15 / 2 | Network resilience knobs. |
| catalog.v2AppUuid / v2UrlTemplate | "" | Only used when source is v2. Register at minecraft-heads.com, then set the UUID; adjust the template to match the official v2 docs if needed. |
| catalog.userAgent | browser string | minecraft-heads.com rejects non-browser agents (HTTP 403), so the default mimics a browser. Leave it unless you know the API accepts yours. |
| economy.mode | "FREE" | Global payment mode. |
| economy.item / economy.xp | diamond×1 / 1 | Global price for ITEM / XP_* modes. |
| economy.categoryOverrides | {} | Per-category price overrides, keyed by slug (alphabet, animals, blocks, decoration, food-drinks, humanoid, humans, miscellaneous, monsters, plants). |
| access.command.enabled / permissionLevel | true / 2 | Toggle the /heads shop and its default OP level. |
| access.npc.enabled | true | Toggle NPC shopkeepers. |
| access.villager.enabled / name / caseInsensitive | true / Head Trader / true | Toggle named-trader mode, the trigger name, and case-sensitivity of the name match. |
| access.villager.mode (since 1.1.0) | "ONLY_VILLAGER" | Which entity types may be a named trader: ONLY_VILLAGER (villagers only — default, unchanged behavior), ALL (any mob), MOB_WHITELIST (only ids in entityWhitelist), MOB_BLACKLIST (any mob except ids in entityBlacklist). |
| access.villager.entityWhitelist / entityBlacklist (since 1.1.0) | [] / [] | Entity type ids (e.g. "minecraft:zombie"; a bare "zombie" assumes the minecraft namespace, and matching is case-insensitive) used by the MOB_WHITELIST / MOB_BLACKLIST modes. |
| access.villager.freeze (since 1.1.0) | false | When a name tag turns a mob into a trader, freeze it in place — disables AI so it stops wandering, like a spawned NPC. Reverts automatically when the mob is renamed so it no longer qualifies. Off (default) = unchanged behavior. |
| ui.title / showPriceInLore / headsPerPage | HeadVault / true / 45 | Cosmetic shop options. |
| logging.purchaseVerbosity | "INFO" | How loudly purchases are logged to console. |

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.