head-vault

模组

· 作者 jaameypr

适用于 Minecraft 26.1.2 的服务端 Fabric 模组,允许玩家通过游戏内图形界面浏览并购买超过 90,000 个装饰性自定义头颅,无需安装任何客户端模组或资源包。

0 本站下载 0 关注 更新于 3 周前

需要前置:Fabric API

最新 1.3.0+26.3 · 26.3 · Fabric

一键开服(送7天)

? 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 供其他模组监听。

? 快速开始

  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 的商店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 许可证发布。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源