head-vault

---

✨ 为什么选择 HeadVault？

自定义头颅能让建筑活起来——但一个一个地通过指令发放非常痛苦。HeadVault 将整个 minecraft-heads.com 目录变成了一个游戏内商店，你的玩家可以浏览和购买，无论你想如何运行：通过指令、放置的 NPC，或你命名的村民。它是仅服务端的，所以没人需要安装任何东西即可使用。

🎯 功能一览

• 🛒 真实的商店 GUI — 分类 → 分页的头颅网格 → 点击购买。原生渲染于原版客户端。
• 🌍 完整目录 — 跨越 10 个分类的约 9 万个头颅，实时获取并缓存到磁盘。后台刷新；永远不会让服务器卡顿。
• 🔌 始终离线可用 — API 无法访问？它会提供最后的缓存，然后是 jar 内置的快照。
• 🔎 搜索 — 在整个目录中按名称或标签查找头颅。
• 🙂 玩家头颅 — 输入任意用户名即可获得该玩家的头颅作为可点击结果。
• 🚪 三种进入方式 — /heads 指令、持久的商店 NPC，以及命名村民。可混合搭配。
• 🧟 任何生物都可成为商人 (自 1.1.0 起) — 不只村民。用命名牌标记一只僵尸、一头牛，任何东西，让它成为商店。通过允许所有、白名单或黑名单模式选择哪些生物类型符合条件。
• 🧊 冻结命名商人 (自 1.1.0 起) — 可选开启：当命名牌将生物变成商人时，将其锁定在原地（禁用 AI）以防止它四处游荡，就像生成的 NPC 一样。当你将其重命名回去时立即恢复。
• 💰 灵活的经济系统 — 免费、物品成本或经验值（等级/点数），带有按分类定价。购买是原子性的。
• 📦 头颅可堆叠 — 相同的头颅可堆叠至 64 个。
• ♻️ 热重载 — 调整配置并运行 /headvault reload。无需重启。
• 🔐 权限 — 兼容 LuckPerms，且在没有权限模组时提供合理的原版 OP 后备方案。
• 🪝 可扩展 — 其他模组可以监听的 PurchaseEvent。

🚀 快速开始

1. 要求： 一个运行在 Java 25 上的 Fabric 26.1.2 服务器，并安装了 Fabric API。
2. 将 head-vault-<version>.jar 放入服务器的 mods/ 文件夹。（sgui 和 fabric-permissions-api 已内置——无需额外安装。）
3. 启动服务器。HeadVault 会将配置文件写入 config/headvault/config.json 并开始在后台下载头颅目录。
4. 运行 /heads — 然后你就可以购物了。🎉

首次启动会显示一个小的内置示例，直到完整目录下载完成（几秒钟）。

🚪 访问模式

在配置中启用任意组合。

模式	工作原理
指令	/heads 打开商店（受权限控制）。
NPC	/headvault npc spawn <name> 放置一个无敌、无 AI 的商店管理员村民。它在重启后持续存在；右键点击可打开商店。通过 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,

  "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": {
      // 按分类覆盖价格（key = 分类 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,
      // ── 自 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             // 每页 9–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 起)	[] / []	用于 MOB_WHITELIST / MOB_BLACKLIST 模式的实体类型 ID（例如 "minecraft:zombie"；裸的 "zombie" 假定为 minecraft 命名空间，匹配不区分大小写）。
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 会自动回退到最后缓存，然后是内置的快照——商店永远不会无货可用。

🙌 鸣谢

• 头颅数据来自 minecraft-heads.com。
• sgui 和 fabric-permissions-api 提供的 GUI 和权限支持。
• 灵感来自 HeadIndex。

📄 许可协议

基于 MIT 许可证发布。