---

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