# 🗿 HeadVault **A server-side custom-heads shop for Minecraft Fabric SMPs.** Browse 90,000+ decorative player heads in a clean chest GUI — open it with a command, a shopkeeper NPC, or a named villager. No client mods. No resource packs. Vanilla players just play. `Fabric` · `Server-side only`

--- ## ✨ 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](https://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. - 💰 **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** server on **Java 25**, with [Fabric API](https://modrinth.com/mod/fabric-api) installed. 2. Drop `head-vault-.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 ` 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. | ## 💰 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 ` | Search heads by name/tag | `headvault.command.search` | | `/heads player ` | Get a specific player’s head | `headvault.command.use` | | `/heads give

` | Give a head for free *(head-id = its UUID)* | `headvault.command.give` / `headvault.admin` | | `/headvault reload` | Reload the config | `headvault.admin` | | `/headvault npc spawn ` | 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: ```jsonc { "_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 } }, "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-villager mode and the trigger name. | | `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](https://minecraft-heads.com). - [sgui](https://github.com/Patbox/sgui) & [fabric-permissions-api](https://github.com/lucko/fabric-permissions-api) for GUIs and permissions. - Inspired by [HeadIndex](https://github.com/PotatoPresident/HeadIndex). ## 📄 License Released under MIT License.

head-vault

External resources

Featured versions

Project members

Technical information