? HeadVault
适用于 Minecraft Fabric 生存服的服务端自定义头颅商店。
在一个整洁的箱子 GUI 中浏览超过 90,000 个装饰性玩家头颅 —— 通过命令、NPC 店主或命名的村民打开。无需客户端模组,无需资源包。原版玩家即可直接游玩。
Fabric · 仅服务端
✨ 为什么选择 HeadVault?
自定义头颅能让建筑栩栩如生 —— 但逐个命令发放实在令人头疼。HeadVault 将整个 minecraft-heads.com 目录变成了一个游戏内商店,你的玩家可以从中浏览和购买,你可以根据喜好配置运行方式:使用命令、放置 NPC,或者给村民命名。它仅在服务端运行,因此任何人都不需要安装任何东西即可使用。
? 功能一览
- ? 真正的商店 GUI —— 分类 → 分页的头颅网格 → 点击购买。原生渲染于原版客户端。
- ? 完整目录 —— 涵盖 10 个分类的约 90k 个头颅,实时获取并缓存至磁盘。后台刷新;绝不会导致服务器卡顿。
- ? 离线始终可用 —— API 无法访问?它将提供最后一次缓存的数据,随后是打包进 jar 文件的快照。
- ? 搜索 —— 在整个目录中通过名称或标签查找头颅。
- ? 玩家头颅 —— 输入任何用户名,即可获得该玩家的头颅作为可点击的结果。
- ? 三种进入方式 ——
/heads 命令、持久化的商店 NPC,以及 命名的村民。可以混合使用。
- ? 任意生物均可成为交易者 (自 1.1.0) —— 不仅仅是村民。给僵尸、牛等任何生物戴上命名牌,使其成为商店。通过“允许全部”、“白名单”或“黑名单”模式选择哪些生物类型有资格成为交易者。
- ? 冻结命名交易者 (自 1.1.0) —— 可选功能:当命名牌将生物变为交易者时,将其锁定在原地(禁用 AI),防止其四处游荡,就像生成的 NPC 一样。当你将其改回正常名称时,立即解除锁定。
- ? 灵活的经济系统 —— 免费、物品消耗或经验值(等级/点数),支持按分类定价。购买操作是原子性的。
- ? 头颅堆叠 —— 相同的头颅可堆叠至 64 个。
- ♻️ 热重载 —— 修改配置文件并运行
/headvault reload。无需重启服务器。
- ? 权限支持 —— 兼容 LuckPerms,若无权限模组则回退至合理的原版 OP 级别。
- ? 可扩展 —— 提供
PurchaseEvent 供其他模组监听。
? 快速开始
- 要求: 运行在 Java 25 或更高版本上的 Fabric 26.1.2 或更高版本服务器,并已安装 Fabric API。
- 将
head-vault-<version>.jar 放入服务器的 mods/ 文件夹中。(sgui 和 fabric-permissions-api 已内置——无需安装其他内容。)
- 启动服务器。HeadVault 会将配置文件写入
config/headvault/config.json,并在后台开始下载头颅目录。
- 运行
/heads —— 即可开始购物。?
首次启动时,在完整目录下载完成前(仅需几秒),会显示一个内置的小型示例。
? 访问模式
在配置文件中启用任意组合。
| 模式 |
工作原理 |
| 命令 |
/heads 打开商店(需权限)。 |
| NPC |
/headvault npc spawn <name> 在你站立处放置一个无敌且无 AI 的商店keeper 村民。它会在重启后保留;右键点击打开商店。使用 npc list / npc remove 进行管理。 |
| 命名村民 |
将你配置的名称(默认为 “Head Trader”)赋予任意村民,右键点击即可为所有人打开商店 —— 无需权限。手持命名牌可将其改回正常名称。自 1.1.0: 通过 access.villager.mode 你可以让任意生物成为命名交易者 —— 不限于村民(全部/白名单/黑名单);并且 access.villager.freeze 可以将新创建的交易者锁定在原地。 |
? 经济系统
选择一个全局模式(可选按分类覆盖):
| 模式 |
玩家支付… |
FREE |
免费 |
ITEM |
可配置的物品 × 数量(例如 1 颗钻石) |
XP_LEVELS |
经验等级 |
XP_POINTS |
总经验点数 |
每次购买都会在点击时重新检查成本并原子性地扣除 —— 玩家绝不会被收费却收不到头颅。玩家名称头颅使用全局价格。授予 headvault.free-bypass 权限可使某人免费购物。
⌨️ 命令
| 命令 |
描述 |
权限 (默认) |
/heads |
打开商店 |
headvault.command.use (OP 2) |
/heads search <query> |
按名称/标签搜索头颅 |
headvault.command.search |
/heads player <name> |
获取特定玩家的头颅 |
headvault.command.use |
/heads give <player> <head-id> |
免费给予头颅 (head-id = 其 UUID) |
headvault.command.give / headvault.admin |
/headvault reload |
重载配置 |
headvault.admin |
/headvault npc spawn <name> |
在你站立处生成商店 NPC |
headvault.npc.manage |
/headvault npc remove |
移除你注视的 NPC |
headvault.npc.manage |
/headvault npc list |
列出已加载的商店 NPC |
headvault.npc.manage |
? 权限
| 节点 |
授予 |
headvault.command.use |
打开商店、/heads player |
headvault.command.search |
/heads search |
headvault.command.give |
/heads give |
headvault.admin |
/headvault reload、/heads give |
headvault.npc.manage |
生成 / 移除 / 列出 NPC |
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,
```json
"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": [], // 当 mode = "MOB_WHITELIST" 时允许的生物类型 ID,例如 ["minecraft:zombie"]
"entityBlacklist": [], // 当 mode = "MOB_BLACKLIST" 时阻止的生物类型 ID
"freeze": false // 冻结带有名牌的交易商位置(禁用 AI)
}
},
"ui": {
"title": "HeadVault", // 商店窗口标题
"showPriceInLore": true, // 在每个头上显示价格
"headsPerPage": 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 |
钻石×1 / 1 |
ITEM / XP_* 模式的全局价格。 |
economy.categoryOverrides |
{} |
按分类的价格覆盖,通过 slug 键控(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(仅在 entityWhitelist 中的 ID),MOB_BLACKLIST(除 entityBlacklist 中的 ID 外的任何生物)。 |
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 会自动回退到上一个缓存,然后是捆绑快照 — 商店永远不会消失。
? 致谢
? 许可证
根据 MIT 许可证发布。
? 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 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
- Requirements: a Fabric 26.1.2 or Greater server on Java 25 or Greater, with Fabric API installed.
- Drop
head-vault-<version>.jar into your server’s mods/ folder. (sgui and fabric-permissions-api are bundled inside — nothing else to install.)
- Start the server. HeadVault writes its config to
config/headvault/config.json and begins downloading the head catalog in the background.
- 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
? License
Released under MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧