物品搜寻器

物品搜寻器

一个适用于Minecraft 1.21/1.21.1的客户端Fabric模组,帮助你定位附近容器中存放的物品。它会在你打开容器时缓存容器物品栏,并显示一个HUD,展示距离你最近的存有目标物品的容器,以及彩色轮廓

工具

Item Finder

Modrinth

开发中 — 此模组功能可用,但仍处于早期开发阶段。可能会有粗糙之处、缺失功能和错误。性能目前不是优先考虑的事项,在某些情况下可能明显较差。

AI 辅助披露 — 此模组的部分内容是在 AI 工具(Claude)的帮助下开发的。代码已经过审查和测试,但请留意这一点。

一个适用于 Minecraft 1.21/1.21.1 的客户端 Fabric 模组,可帮助你定位存储在附近容器中的物品。它会在你打开容器时缓存容器物品栏,并显示一个 HUD,展示距离你最近的、装有目标物品的容器,同时在世界中直接渲染彩色轮廓。

工作原理

Item Finder 是纯客户端模组——它不需要服务器端对应模组,在单人游戏和多人游戏中均可工作。代价是容器必须至少被访问过一次,否则不会出现在搜索结果中。当你打开一个容器时,其内容会被自动记录。当你关闭它时,缓存会更新,并立即运行新的搜索。

周期性后台搜索每隔 N tick(可配置)重新运行一次,以便在你移动时距离保持最新。

服务器支持(可选)

为了在服务器上获得更好的体验,可以在客户端与 Item Finder 一起安装 Litematica。当 Litematica 存在时,它可以让你找到玩家附近容器中的物品,而无需手动打开每个容器。

然而,这需要在服务器上安装 Servux,并在服务器端 Servux 配置中启用 entityDataSync 选项。否则,只有标准的访问并缓存方式可用。

功能

HUD 覆盖层

  • 显示当前目标物品及其图标
  • 显示距离最近持有该物品的容器的距离(例如 12.5m)
  • 显示持有该物品的容器数量(例如 3 boxes)
  • 显示你在活动列表中的当前位置(例如 [4/25])
  • 颜色编码状态:绿色 = 已找到,红色 = 未找到,灰色 = 已禁用
  • 位置可在设置中配置(左上角、右上角、左下角、右下角),会感知其他 HUD 元素,不会与原生药水/状态效果区域重叠等

世界渲染

  • 在世界中围绕最近的容器绘制方框轮廓
  • 当前选中物品的容器显示绿色方框
  • 可选的穿墙显示模式(在设置中切换)

容器缓存

  • 在你打开和关闭容器时自动记录容器内容
  • 存储每个槽位的物品 ID 和数量(不包括你的玩家物品栏)
  • 缓存在会话期间持续存在;容器会一直被追踪,直到游戏重启

搜索与距离过滤

  • 可配置的搜索半径(4–128 格,默认 32)
  • 结果按距离排序,最近的优先
  • 搜索会按可配置的间隔自动刷新(1–200 tick,默认 20)

物品列表

  • 从 config/itemfinder/lists/ 中的 JSON 文件加载物品列表
  • 每个列表是一个由物品 ID 组成的命名集合
  • 可单独开启/关闭每个物品;状态会按列表在会话之间保存
  • 使用热键导航物品(在已启用的物品之间循环)
  • 自动禁用缺失项:禁用所有在任何已缓存容器中都未找到的物品
  • 物品管理器中有全部启用 / 全部禁用按钮

槽位高亮

  • 当你打开一个持有当前目标物品的容器时,匹配的槽位会以绿色高亮
  • 可在设置中切换

物品管理器 GUI

  • 显示活动列表中的所有物品,包括图标、数量、容器数量和最近距离
  • 可搜索/过滤的列表
  • 每个物品的切换按钮
  • 汇总统计:物品总数、已启用、已禁用、已找到

文件浏览器

  • 浏览并加载 config/itemfinder/lists/ 中的 .json 列表文件
  • 可导航子目录

配置界面

可从 Mod Menu 或通过热键访问。两个标签页:

  • 通用 — 所有数值和布尔设置
  • 热键 — 查看和重新绑定所有按键

按键绑定

操作 默认按键 描述
打开列表浏览器 I 浏览并加载物品列表文件
下一个物品 N 循环到下一个已启用的物品
上一个物品 B 循环到上一个已启用的物品

所有按键绑定均可在设置界面的“热键”标签页中配置。

配置

配置文件:config/itemfinder.json

设置 默认值 范围 描述
searchRadius 32 4–128 将已缓存容器纳入结果的方块半径
searchInterval 20 1–200 自动搜索刷新之间的 tick 数
showThroughWalls false — 透过固体方块渲染容器轮廓
highlightSlots true — 高亮已打开容器中的匹配槽位

物品列表格式

将 .json 文件放入 config/itemfinder/lists/。示例:

{
  "name": "My List",
  "items": [
    "minecraft:diamond",
    "minecraft:iron_ingot",
    "minecraft:oak_log"
  ]
}

物品 ID 遵循标准的 namespace:item_id 格式。

文件位置

文件 用途
config/itemfinder.json 主配置
config/itemfinder/lists/*.json 物品列表定义
config/itemfinder/state.json 每个物品的启用/禁用状态

构建

需要 JDK 21。

./gradlew build

输出的 jar 将位于 build/libs/。

TODO

容器与数据

  • 改进 Litematica/Servux 集成,以同步玩家周围的容器数据。

有用链接

Fabric 文档

库(Minecraft 1.21.11)

Maven 仓库

许可证

LGPLv3 — 见 LICENSE。