StolenItemAdmin
一款用于追踪被盗/藏匿物品最终去向的管理员工具包,无需依赖物品追踪功能——因此它可以在从未设置过任何追踪功能的旧世界回溯使用。该插件基于原始的 RecursiveInvSee 库存查看器构建。
目标平台为 Paper / Folia 26.1.2 版本(预计在其他 26.1+ 系列的构建版本中也能继续正常工作,且能兼容相当长远的未来版本——详见下方的“兼容性”部分)。
⚠️ 警告:由 AI 生成代码
我是一名普通的开发者,你真的不应该信任在网上找到的随机内容。请查看源代码(点击侧边的 GitHub “查看源码”链接),如果你不信任预编译的 jar 文件,请使用 mvn clean package 自行编译(需要安装 Java JDK 21+ 和 Maven)。
由于离线库存编辑会直接写入玩家的存档文件,请先在测试世界/备份中进行测试。每次保存前会自动创建一个 .dat 文件的 .bak 副本作为安全网,但你仍然是在非游戏运行会话状态下直接编辑原始玩家数据。
库存 / 末影箱查看
/invsee <player> - 查看/编辑玩家的库存,无论在线或离线
/endersee <player> - 查看/编辑玩家的末影箱,无论在线或离线
两者均支持递归(可以打开内部发现的潜影盒和包裹),即使目标玩家离线也可用(编辑操作直接写入其 .dat 文件,并自动先创建 .bak 备份,且在编辑期间阻止玩家登录),并且兼容 Geyser/Floodgate,因此基岩版账号也能正确解析。
全服务器容器与方块搜索
四个命令均在类箱子样式的分页 GUI 中打开(每页显示 45 个结果,包含 GUI 内的“上一页/下一页”按钮以及一个自然生成过滤器的切换开关),按距离由近到远排序。每次扫描覆盖整个服务器,而不仅仅是当前加载的区域:
/chestfind [item_id] [x] [y] [z] - 列出整个服务器上的所有存储容器(箱子、陷阱箱、 barrels、潜影盒、漏斗、发射器、投掷器、熔炉、酿造台……),优先显示离你指定点最近的。双箱子仅列出一次,并合并显示其内容。可从控制台使用(以纯文本摘要形式输出,因为控制台没有库存来打开 GUI,需等待完整扫描完成后打印)。左击结果传送至该位置;右击直接在 GUI 中打开该容器(递归地——内部的潜影盒/包裹也会打开,与 /invsee 一样),全程无需传送。
/chestfindnearby [item_id] [radius_x] [radius_y] [radius_z] - 同上,但始终以你当前位置为中心,并可缩小到你周围的区域而非整个服务器。别名:/chests、/cfn。仅限玩家使用(需要获取你的位置信息)。
/blockfind <block_id> [x] [y] [z] - 类似于 /chestfind,但查找的是特定方块的所有实例而非容器(方块 ID 为必填项)。别名:/bf。
/blockfindnearby <block_id> [radius_x] [radius_y] [radius_z] - 结合 /blockfind 和 /chestfindnearby 的特点:必填方块 ID,以你为中心,可选半径范围。别名:/bfn。
方括号中的物品/方块 ID 参数是可选的——例如 /chestfindnearby 50 50 50 将直接进行无物品过滤的 50 格半径搜索,这与带过滤条件的 /chestfindnearby diamond 50 50 50 效果完全一致。如果只提供一个半径数字(如 /chestfindnearby 50),则该数值均匀应用于 X/Y/Z 三个轴;提供三个数字则可分别设置 X/Y/Z 的半径。
每个结果的提示框(tooltip)会显示其所在世界、精确坐标、与你之间的距离,以及(对于容器)已填充的槽位数量和包含的搜索物品数量。
隐藏自然生成的结果
在上一页/下一页按钮之间有一个切换按钮(灰色/亮绿色染料),用于隐藏或显示位于自然生成结构内的结果——包括村庄、地牢、废弃矿井、沉船、神殿、废墟、要塞、堡垒遗迹、末地城、远古城市、试炼密室等。默认情况下此功能是关闭的(即隐藏),因此新开始的搜索默认只显示那些看似由玩家放置的物品,而不是原版战利品生成机制产生的物品。这不需要物品追踪功能,即使在安装此插件之前就已经完全生成的世界中也能立即生效——它读取 Minecraft 本身永久记录的三种数据,且不涉及任何放置追踪:
- 结构归属关系 ——大多数含有战利品的结构(村庄、废弃矿井、神殿、要塞、末地城……)已由游戏本身按区块记录(通过
Chunk#getStructures()),因此“是否位于某个生成结构的包围盒内”是一个直接且可靠的检查方式。这也使其在与大多数自定义/插件世界生成器兼容时依然有效,因为它使用的是原版结构定位/地图 API 所依赖的相同数据。
- 未解析的战利品表 ——尚未被任何人打开过的容器仍保留其生成时所使用的战利品表(通过
Lootable#getLootTable()),Bukkit 可直接暴露此接口。这能通用性地捕获自然战利品,包括单靠结构归属无法检测到的情况(见下一点)——但仅在容器首次被打开前有效,因为一旦打开,该标签会被解析并清除。
- 刷怪笼 proximity(邻近度) ——普通的“地牢”(由苔石怪物刷怪笼组成的房间)在信号 1 中存在真实盲区:它们是世界的 feature(特性) 而非 jigsaw structure(结构)——不受“生成结构”选项的影响,也无法通过
/locate 命令找到,这一点已通过 Minecraft 官方文档确认。没有任何结构条目可用于定位它们。因此,距离刷怪笼几格以内的地牢宝箱被视为自然生成,作为当信号 2 不再适用时(即已被打开过的地牢宝箱)的最后备用信号。
切换筛选器纯粹是一个显示开关——无论是否启用,所有结果都会被找到并收集,因此切换它不会触发额外的扫描。
这仅对容器可靠有效。对于方块,只有位于结构边界框内的方块才会被标记为“自然生成”——对于普通地形生成(如矿脉)没有等效机制,因为原版游戏并没有在任何可访问的地方记录“此方块来自世界生成”,除非使用世界种子重新生成区块。结构外的方块始终被视为“非自然生成”(即显示出来),这是安全默认值——它永远不会隐藏可能值得仔细查看的内容。
最小物品筛选器
在上一页/下一页按钮之间(仅限容器——/chestfind 和 /chestfindnearby)还有一个第二个切换开关,打开后会出现一个双箱大小的编辑器:在里面放入物品——比如 5 下界合金块——然后关闭它,结果列表将缩小到仅包含至少拥有你放入的每一种物品指定数量的容器(汇总容器中每个槽位的物品,忽略附魔/耐久度/名称等因素——只关注材质和数量)。放入空内容并关闭即可清除筛选器。每次你在编辑器中放置的物品都会在关闭时立即全部返还给你——它只是一个用于指定条件的临时空间,并非真正的容器;没有任何物品会被保留或消耗,如果你的背包已满导致无法直接返还,剩余物品会掉落至你的脚下而不是丢失。与“自然生成”筛选器一样,这也无需额外扫描:每个容器的完整物品分解信息已在找到时记录,因此该筛选器纯粹是在显示时进行过滤。
全服扫描的工作原理
对于玩家而言,一次扫描分为两个阶段,两者都填充同一个已打开的 GUI:
- 即时: 当前已加载的所有内容会立即被扫描,完成后 GUI 随即打开并显示这些结果——通常耗时不到一秒。
- 按需后台运行: 通过读取区域文件头(开销极小——无需解析 NBT),找出世界中曾经生成并保存到磁盘上的其余所有区块,然后以小批量节流的方式加载、扫描并卸载——但仅加载足够多的区块以保持比当前查看内容多一页的预览量。一旦现有结果足以填满当前页加上预览页,后台扫描会自动暂停,而不是为了无人观看而继续遍历服务器其余部分;翻到下一页时会将其唤醒。GUI 中的信息项会反映这一状态(“正在扫描...”、“已暂停——有更多结果可用”或当所有区块确实都被覆盖后显示“已扫描整个服务器”)。关闭 GUI 将永久停止后台扫描。控制台没有分页功能来驱动此过程,因此控制台运行的命令总是扫描整个服务器直至完成,然后再打印其唯一摘要。本次扫描自身加载的区块会在之后再次卸载;因其他原因已经加载的区块则保持不变;并且在整个扫描期间,区块会通过临时加载票保持加载状态,防止服务器本身将其卸载从而干扰扫描。
config.yml 中有两个可调参数控制后台阶段的速率/激进程度(对覆盖多少服务器内容没有限制——仅限制速度):
find:
max-results: 500 # 一次性显示/分页的结果数量(按距离由近到远排序)
chunk-batch-size: 50 # 每批同时加载+扫描的区块数量
chunk-batch-delay-ticks: 2 # 批次之间的延迟(20 tick = 1秒);调高可减少服务器负担
此外还存在一个硬编码(不可配置)的安全上限,总计匹配数不超过 50,000,纯粹是为了避免在类似 /blockfind stone 这样大范围搜索时耗尽内存——如果你达到此上限,GUI 会提示你,解决方法是缩小搜索范围(半径/坐标,或选择更稀有的方块),而不是提高这个数值。
stolenitemadmin.find 权限组控制了这四个命令;stolenitemadmin.invsee / stolenitemadmin.endersee 控制了那两个查看器命令;stolenitemadmin.* 授予所有权限。所有这些权限默认均为 op。
兼容性 / Folia 注意事项
本插件完全基于标准的 Paper/Folia 调度器 API(RegionScheduler、GlobalRegionScheduler、Entity#getScheduler())编写,而非 Folia 内部类,因此同一个 jar 包在纯 Paper 和 Folia 上均能正常运行:
- 容器扫描在每个区块所属的区域线程上读取实时方块状态(通过
Bukkit.getRegionScheduler()),因此在 Folia 上内容始终是最新的且线程安全。
- 方块类型扫描仅需方块类型,无需实时状态,因此所属线程仅用于获取廉价的区块快照;实际(可能庞大的)逐方块比较则完全脱离该线程运行,因此大型扫描绝不会阻塞区域 Tick。
- 后台阶段使用异步区块 API(
World#getChunkAtAsync)加载尚未加载的区块,从不使用阻塞同步加载器,并且随后始终通过所属区域线程将其卸载。
- 区域文件头读取(用于发现所有曾生成的区块)是在小型专用线程池上进行的纯
java.io 磁盘访问——完全不涉及 Bukkit/Paper API——因此它们无需在任何特定线程上运行,也绝不会阻塞游戏/区域线程。
- 传送至结果始终使用
Player#teleportAsync,这是 Folia 对跨区域/跨世界传送的要求,且在纯 Paper 上行为一致。
- GUI 的打开/关闭/刷新始终通过相关玩家自身的实体调度器分发执行。
StolenItemAdmin
An admin toolkit for tracking down where stolen/stashed items have ended up, without relying on
item tracing - so it works retroactively on worlds that were never set up to trace anything.
Built on top of the original RecursiveInvSee inventory viewer.
Targets Paper / Folia build 26.1.2 (and should keep working on other builds in that 26.1+ line,
and reasonably far beyond it - see "Compatibility" below).
WARNING: Made with AI
I am a random dev, and you should really not trust random stuff you find on the Internet. Take a
look at the source code (click the GitHub "view source" link on the side), and compile it
yourself with mvn clean package (requires Java JDK 21+ and Maven installed) if you'd rather not
trust a prebuilt jar.
Because offline inventory editing writes directly to a player's save file, test on a throwaway
world/backup first. A .bak copy of the .dat file is made automatically right before every
save as a safety net, but you're still editing raw player data outside of a running game session.
Inventory / ender chest viewing
/invsee <player> - view/edit a player's inventory, online or offline
/endersee <player> - view/edit a player's ender chest, online or offline
Both are recursive (you can open shulker boxes and bundles found inside), work even when
the target is offline (edits are written straight to their .dat file, with an automatic
.bak backup taken first, and the player is prevented from logging in while being edited), and
are Geyser/Floodgate-aware so Bedrock accounts resolve too.
Server-wide container & block search
Four commands, all opened in a chest-style paginated GUI (45 results per page with in-GUI
"previous/next page" buttons plus a natural-generation filter toggle) for any player who runs
them, sorted closest-first. Every scan covers the entire server, not just what's currently
loaded:
/chestfind [item_id] [x] [y] [z] - lists every storage container on the entire server
(chests, trapped chests, barrels, shulker boxes, hoppers, dispensers, droppers, furnaces,
brewing stands, ...), closest to a point of your choosing first. Double chests are listed once,
with their combined contents. Usable from console (as a plain-text summary, printed once the
full scan finishes, since console has no inventory to open a GUI in). Left-click a result to
teleport to it; right-click to open the container itself right there in the GUI (recursively -
shulker boxes/bundles inside it open too, same as /invsee) without teleporting at all.
/chestfindnearby [item_id] [radius_x] [radius_y] [radius_z] - the same, but always centred on
your current position, and can be narrowed to a box around you instead of the whole server.
Aliases: /chests, /cfn. Players only (it needs your location).
/blockfind <block_id> [x] [y] [z] - like /chestfind, but finds every occurrence of a
specific block instead of containers (the block id is mandatory). Alias: /bf.
/blockfindnearby <block_id> [radius_x] [radius_y] [radius_z] - a mix of /blockfind and
/chestfindnearby: mandatory block, centred on you, optional radius. Alias: /bfn.
The item/block id argument is optional wherever shown in brackets - e.g. /chestfindnearby 50 50 50 goes straight to a 50-block radius search with no item filter, exactly like /chestfindnearby diamond 50 50 50 does with one. A single radius number (/chestfindnearby 50) applies uniformly
to all three axes; give three numbers for separate X/Y/Z radii.
Each result's tooltip shows its world, exact coordinates, distance from you, and (for containers)
how many slots are filled and how many of the searched-for item it holds.
Hiding naturally-generated results
Between the previous/next page buttons sits a toggle button (a grey/lime dye) that hides or shows
results sitting inside a naturally-generated structure - villages, dungeons, mineshafts,
shipwrecks, temples, ruins, fortresses, bastions, end cities, ancient cities, trial chambers, and
so on. It's off (hidden) by default, so a fresh search starts by showing only things that
plausibly look player-placed, not vanilla loot generation. This needs no item tracing and works
immediately even on worlds that were already fully generated before this plugin was ever
installed - it reads three kinds of data Minecraft already permanently records, none of it
placement-tracking:
- Structure membership - most loot-bearing structures (villages, mineshafts, temples,
fortresses, end cities, ...) are recorded per-chunk by the game itself
(
Chunk#getStructures()), so "is this inside a generated structure's bounding box" is a direct,
reliable check. This also keeps working with most custom/plugin world generators, since it's
the same data vanilla's own structure-locate/map APIs rely on.
- Unresolved loot table - a container nobody has opened yet still carries the loot table it
generated with (
Lootable#getLootTable()), which Bukkit exposes directly. This catches natural
loot generically, including things structure membership alone can't (see next point) - but only
until the container is opened for the first time, since opening it resolves and clears the tag.
- Spawner proximity - plain "dungeons" (the mossy-cobblestone monster-spawner room) are a
genuine gap in signal 1: they're a world-gen feature, not a jigsaw structure - not disabled
by the "Generate Structures" option and not findable with
/locate either, confirmed against
Minecraft's own documentation. There is no structure entry to find for one. A dungeon chest
within a few blocks of its spawner is therefore treated as natural too, as a last-resort signal
for exactly the case where signal 2 no longer applies (an already-opened dungeon chest).
Toggling the filter is purely a display switch - every result is always found and collected
regardless of it, so switching it never triggers extra scanning.
This only reliably works for containers. For blocks, only ones inside a structure's
bounding box are ever marked natural - there's no equivalent for ordinary terrain generation like
ore veins, since vanilla doesn't record "this block came from worldgen" anywhere accessible
without regenerating the chunk against the world's seed. Blocks outside a structure are always
treated as "not natural" (shown), which is the safe default - it never hides something that might
be worth a closer look.
Minimum-item filter
Also between the previous/next buttons (containers only - /chestfind and /chestfindnearby) is
a second toggle that opens a double-chest-sized editor: put items in it - say, 5 netherite blocks -
and close it, and the results list narrows to only containers holding at least that many of
every item you put in (aggregated across every slot in the container, ignoring things like
enchantments/durability/names - only material and amount matter). Put in nothing and close it to
clear the filter again. Every item placed in the editor is always handed straight back to you
the moment you close it - it's a scratch space for specifying criteria, not a real container;
nothing is ever kept or consumed, and if your own inventory happens to be full when it hands
things back, the leftover is dropped at your feet rather than lost. Like the natural-generation
filter, this needs no extra scanning: every container's full item breakdown was already recorded
when it was found, so the filter is purely a display-time narrowing.
How the whole-server scan works
For a player, a scan happens in two phases, both feeding the same already-open GUI:
- Instant: everything already loaded right now is scanned immediately, and the GUI opens with
those results as soon as that finishes - typically well under a second.
- Background, on demand: every other chunk that was ever generated and saved to disk for
the world(s) being searched is found by reading region-file headers (cheap - no NBT parsing),
then loaded, scanned, and unloaded again in small throttled batches - but only as many as are
needed to stay one page ahead of whatever you're currently looking at. Once enough results
exist to fill the current page plus a lookahead page, the background scan pauses itself rather
than continuing to grind through the rest of the server for no one; turning to the next page
wakes it back up. The info item in the GUI reflects this ("Scanning...", "Paused - more results
available", or "Whole server scanned" once every chunk really has been covered). Closing the
GUI stops the background scan for good. Console has no paging to drive this, so a console-run
command always scans the entire server to completion before printing its one summary. Chunks
this scan itself loads are unloaded again afterwards; chunks that were already loaded for some
other reason are left alone, and a chunk is held with a temporary loading ticket for the whole
time it's being scanned so it can't be unloaded out from under the scan by the server itself.
Two tunables in config.yml control how fast/aggressive the background phase is (there is no cap
on how much of the server gets covered - only on how quickly):
find:
max-results: 500 # how many results (closest first) are ever shown/paginated at once
chunk-batch-size: 50 # chunks loaded+scanned together per batch
chunk-batch-delay-ticks: 2 # delay between batches (20 ticks = 1s); raise to go easier on the server
A hardcoded (non-configurable) safety ceiling of 50,000 total matches also exists purely to avoid
running out of memory on something like a wide-open /blockfind stone - if you ever hit it, the
GUI will say so and the fix is narrowing the search (radius/coords, or a rarer block), not raising
a number.
Everything under stolenitemadmin.find gates these four commands; stolenitemadmin.invsee /
stolenitemadmin.endersee gate the two viewer commands; stolenitemadmin.* grants all of it. All
default to op.
Compatibility / Folia notes
This plugin is written entirely against the standard Paper/Folia scheduler API
(RegionScheduler, GlobalRegionScheduler, Entity#getScheduler()), not internal Folia
classes, so the same jar runs correctly on both plain Paper and Folia:
- Container scans read live block state on each chunk's owning region thread (via
Bukkit.getRegionScheduler()), so contents are always current and thread-safe on Folia.
- Block-type scans only need block types, not live state, so the owning thread is used just to
take a cheap chunk snapshot; the actual (potentially large) block-by-block comparison then runs
off that thread entirely, so a big scan never blocks a region tick.
- The background phase loads not-yet-loaded chunks with the async chunk API
(
World#getChunkAtAsync), never the blocking synchronous loader, and always unloads them again
through the owning region thread afterward.
- Region-file header reads (used to discover every chunk ever generated) are plain
java.io
disk access on a small dedicated thread pool - not Bukkit/Paper API at all - so they never need
to run on any particular thread and never block a game/region thread.
- Teleporting to a result always uses
Player#teleportAsync, which Folia requires for
cross-region/cross-world teleports and which behaves identically on plain Paper.
- GUI opening/closing/refreshing is always dispatched through the relevant player's own entity
scheduler.
评论 0
登录后参与评分
还没有评论,来抢沙发吧