PocketMap
无需客户端模组的小地图。适用于 Paper 1.21+ 及 26.x。
每位玩家获得一张属于自己的原版地图,该地图始终以玩家为中心,并放置于副手栏——客户端会将其作为 HUD 界面自行绘制。无数据包交互、无 NMS(非标准 Minecraft 代码)、无外部依赖:只需将 plugins/ 文件夹中放入一个 jar 文件,执行 /pocketmap 即可启用。
- 玩家无需安装任何内容。 这是一张普通的原版地图,因此它可在纯净客户端、通过 Geyser 连接的基岩版以及任何启动器上正常运行。
- 无依赖项。 不需要 PacketEvents、ProtocolLib 或数据库库。仅一个 jar 文件。
- 你的副手物品是安全的。 该槽位中原有的物品及其所有数据会被妥善保存,并在小地图关闭、玩家退出、死亡或插件禁用时归还。存储的数据在服务器重启后依然存在,且永远不会被覆盖。
- 它不会让你付出生命的代价。 如果副手中持有不死图腾,而该图腾正在保护你免受其他物品占用的影响,那么 PocketMap 将不会启用。这是一种可配置的拒绝机制,而非静默处理。
- 每个玩家拥有唯一且永久复用的地图 ID。 创建地图会在世界数据中占用一个永久 ID;如果一个插件每次会话都创建新地图,将会导致你的世界中充满废弃的地图 ID。
- 在使用期间,地图物品无法被丢弃、移动或交换 到主手栏。
命令:/pocketmap [on|off|status|reload](别名 /pmap) · 权限:pocketmap.use(所有人),pocketmap.admin(重载、OP)
诚实的限制
副手栏是一个真实的物品槽,PocketMap 会占用它。如果你的玩家需要使用副手栏来持盾或不死图腾,那么这个插件并不适合他们——可以通过 /pocketmap off 关闭它,该槽位会立即恢复原状。由于地图是原版的,它只显示地形,而不显示玩家或怪物;基于数据包的小地图可以绘制这张地图无法呈现的内容。
测试环境
Paper 1.21.11、26.2 和 26.3 —— 经过运行时测试,而不仅仅是“能加载”。通过插件自身的类加载器,对分发的 dev.pocketmap.Hud 运行了 29 个断言,确保测试不会因副本差异而失效:包括跨轴和跨越零点的跟随玩家阈值(用于区分我们的地图与玩家自己的地图,即使经过箱子往返后依然有效)、配置回退机制,以及所有可能导致存储的副手物品丢失的路径——损坏字节、空字节、null。两个版本均 29/29 全部通过,此外还有 19 个针对地图 API 本身的额外断言。在该插件组合的其他 13 个插件同时加载的情况下,两个服务器上均未出现错误。
小众选择
目前为此类功能提供的成熟插件(VanillaMinimaps,约 60,000 次下载)已于 2024 年 7 月发布最后一个版本,并且不再能在当前的 Minecraft 版本上启动——它在 1.21.11 的 org.bukkit.craftbukkit.v1_21_R1.CraftServer 和 26.2 的 net.minecraft.world.level.World 上崩溃。它的失败正是源于本插件所避免的 NMS 耦合问题。存在另一个活跃的替代方案,它可以正常工作,但需要手动从 GitHub 下载一个强制依赖项。
具体数据和证据见:LISTING.md。
安装
将 jar 文件放入 plugins/ 目录,启动服务器,然后运行 /pocketmap。默认设置:最近缩放比例,每 8 格重新居中,显示玩家标记,保护副手物品。
AI 披露
人类主导开发:Arvid Grün 负责指导项目、设定需求、测试并批准每次发布。代码和文档均在 AI(Claude)辅助下编写。未使用 AI 生成的图像;图标是通过代码绘制的几何图形。
许可证
MIT — 详见 LICENSE。
人类主导开发:由人类维护者指导、测试并对每次发布承担责任;AI 仅作为开发工具使用(根据 Modrinth 政策进行披露)。图标为手工制作的几何艺术作品,并非 AI 生成。
PocketMap
A minimap without a client mod. For Paper 1.21+ and 26.x.
Every player gets their own vanilla map, kept centred on them and placed in the offhand — where
the client draws it as a HUD all by itself. No packets, no NMS, no external dependency: one jar
in plugins/, and /pocketmap turns it on.
- Nothing to install for players. It is a normal vanilla map, so it works on the plain
client, on Bedrock via Geyser, and on any launcher.
- No dependencies. Not PacketEvents, not ProtocolLib, not a database library. One jar.
- Your offhand item is safe. Whatever was in that slot is stored with all its data and handed
back when the minimap goes off, on quit, on death, and when the plugin is disabled. The store
survives a restart and is never overwritten.
- It refuses to cost you a life. A Totem of Undying in the offhand does not save you while
something else occupies the slot, so PocketMap will not turn on over a totem. That is a
configurable refusal, not a silent one.
- One map id per player, reused forever. Creating a map burns a permanent id in the world
data; a plugin that made a new one every session would fill your world with dead map ids.
- The map item cannot be dropped, moved or swapped into the main hand while it is in use.
Commands: /pocketmap [on|off|status|reload] (alias /pmap) · Permissions: pocketmap.use
(everyone), pocketmap.admin (reload, op)
Honest limits
The offhand is a real slot, and PocketMap takes it. If your players need the offhand for shields
or totems, this is the wrong plugin for them — turn it off with /pocketmap off and the slot
comes straight back. The map is a vanilla map, so it shows terrain, not players or mobs; a
packet-based minimap can draw things this one cannot.
Tested on
Paper 1.21.11, 26.2 and 26.3 — runtime-tested, not just "it loads". 29 assertions run against the
shipped dev.pocketmap.Hud through the plugin's own classloader, so the test cannot drift
from a copy: the follow-the-player threshold on both axes and across zero, telling our map apart
from a player's own map (including after a round trip through a chest), the config fallbacks, and
every path that could lose a stored offhand item — corrupt bytes, empty bytes, null. 29/29 green
on both versions, plus 19 further assertions on the map API itself. Loaded together with the
other 13 plugins of the portfolio on both servers, 0 errors.
Niche
The established plugin for this (VanillaMinimaps, ~60,000 downloads) shipped its last version in
July 2024 and no longer starts on either current Minecraft version — it crashes on
org.bukkit.craftbukkit.v1_21_R1.CraftServer on 1.21.11 and on net.minecraft.world.level.World
on 26.2. It died of exactly the NMS coupling this plugin does not have. There is one active
alternative; it works, but needs a mandatory dependency hand-downloaded from GitHub.
Numbers and evidence: LISTING.md.
Install
Drop the jar in plugins/, start, /pocketmap. Defaults: closest zoom, re-centre every 8 blocks,
player marker on, offhand item protected.
AI disclosure
Human-led development: Arvid Grün directs the work, sets the requirements, tests and approves
every release. Code and documentation are written with AI assistance (Claude). No AI-generated
images are used; the icon is drawn geometrically in code.
License
MIT — see LICENSE.
Human-led development: a human maintainer directs, tests and takes responsibility for every release; AI is used as a development tool (disclosed per Modrinth policy). The icon is hand-made geometric artwork, not AI-generated.
评论 0
登录后参与评分
还没有评论,来抢沙发吧