BlueMap Structures Paper
基于 Chunkbase 风格、由世界种子衍生的结构标记,适用于 BlueMap,作为 Paper/Purpur 插件使用。村庄、要塞、海洋神殿等 18 种其他结构层会以可切换的标记图层形式显示在你的网页地图上——这些标记由世界种子计算得出,无需加载或生成区块。
这是 Fabric 模组
mc-bluemap-structures
在 Paper-API 下的重新实现版本
(该模组无法在 Paper/Purpur 服务器上运行)。
功能
- 21 种结构图层——村庄、沙漠神殿、丛林神庙、沼泽小屋、冰屋、掠夺者前哨站、远古城市、遗迹小径、试炼密室、海底废墟、沉船、传送门遗迹(主世界与下界)、海洋神殿、林地府邸、下界要塞、堡垒遗迹、末地城、埋藏的宝藏(可选启用)、废弃矿井(可选启用)、要塞。
- 各图层的独立开关位于 BlueMap 侧边栏中,每个图层都有专属图标——首次启动时从 Mojang 官方客户端资源生成(服务器直接从 Mojang 下载并缓存在插件数据文件夹中;未捆绑或重新分发任何第三方艺术作品)。
- 每个标记弹窗内提供可复制的
/tp 指令。
- 对密集图层(如沉船、海底废墟等)实施缩放级别可见性限制,以保持网页应用的响应速度。
- 基于种子计算、生物群系验证——候选位置来自原版自身的放置算法(与 Chunkbase 采用的方法相同),随后通过 Paper API 检查每个候选位置是否符合世界基于噪声的生物群系来源(
has_structure/* 生物群系标签)。全程不会加载或生成任何区块。
- 对 TPS 友好——整个扫描过程纯粹是在异步线程上进行的数学运算,每世界仅需数毫秒即可完成;主线程仅负责发布标记。
要求
- Paper 或 Purpur,Minecraft 26.1 或更高版本(
api-version: '26.1';基于 paper-api 26.1.2 构建)
- Java 25
- BlueMap 5.x(软依赖——若缺少 BlueMap,插件将处于空闲状态)
安装
- 将
BlueMapStructuresPaper-x.y.z.jar 放入 plugins/ 目录。
- 重启服务器。每次启动时,插件都会根据每个已映射世界的种子重新计算标记(每世界仅需数毫秒;控制台会输出总计时间),并注册相应的标记图层。
首次启动时,插件还会从 Mojang(piston-meta.mojang.com,与启动器相同的来源)下载与你服务器版本匹配的 Minecraft 客户端 jar 文件,并从中裁剪出标记图标;jar 文件和生成的图标都会缓存在 plugins/BlueMapStructuresPaper/ 目录下。如果下载失败(例如服务器处于离线状态),标记仍会使用 BlueMap 默认的 POI 图标,并且插件会在下次启动时重试。
配置
plugins/BlueMapStructuresPaper/config.yml:
areas: # 扫描区域(所有条目的并集,去重后)
- center: origin # 原点 (0,0) | 出生点 | {x: <方块>, z: <方块>}
radius-blocks: 5000 # 正方形的半边长
#worlds: # 每个世界的覆盖配置(完全替换默认列表)
# resource:
# areas:
# - center: spawn
# radius-blocks: 2000
layers: # 每个结构层一个开关
village: true
# ...
buried_treasure: false # 可选启用:~0.01/区块 → 在半径 5000 范围内会出现数千个标记点
mineshaft: false # 可选启用:~0.004/区块 → 在半径 5000 范围内会出现 1500+ 个标记点
旧的顶层 radius-blocks: 5000 写法仍然有效,可作为单个以原点为中心的区域设置的简写形式。
标记点会在每次启动时根据种子重新计算(耗时仅几毫秒),因此配置更改将在下次重启后生效——无需清除缓存。
工作原理
结构位置通过世界种子与原版放置算法(按结构组划分的随机分布网格,以及以同心圆环布局的 stronghold)计算得出,随后通过 Paper API 与基于噪声的生物群系数据源进行验证——这与 Chunkbase 的种子地图技术相同,也是无需加载区块的原因。早期原型使用了 World#locateNearestStructure;但它会同步加载每个候选单元格的区块并导致服务器卡顿(参见 issue #3)。详见 docs/DESIGN.md,精炼后的需求见 docs/REQUIREMENTS.md。
构建
./gradlew build # 插件 jar 位于 plugin/build/libs/
./gradlew :core:test # 仅运行纯逻辑测试(无需访问 Paper 仓库)
相关项目
许可证
MIT — 见 LICENSE。第三方来源信息(来自 mc-bluemap-structures 的参考数据、来自 Mojang 客户端资产的运行时生成图标、种子数学算法来源)已在 THIRD_PARTY_NOTICES.md 中记录。
BlueMap Structures Paper
Chunkbase-style, seed-derived structure markers for BlueMap,
as a Paper/Purpur plugin. Villages, strongholds, ocean monuments and 18 other
structure layers appear as toggleable marker layers on your web map — computed from the
world seed, without loading or generating chunks.
A Paper-API reimplementation of the Fabric mod
mc-bluemap-structures
(which cannot run on Paper/Purpur servers).
Features
- 21 structure layers — village, desert pyramid, jungle temple, swamp hut, igloo,
pillager outpost, ancient city, trail ruins, trial chambers, ocean ruin, shipwreck,
ruined portal (overworld & nether), ocean monument, woodland mansion, nether
fortress, bastion remnant, end city, buried treasure (opt-in), mineshaft (opt-in),
stronghold.
- Per-layer toggles in the BlueMap sidebar, each with its own icon — generated on
first startup from Mojang's official client assets (downloaded by your server
directly from Mojang, cached in the plugin data folder; no third-party artwork is
bundled or redistributed).
- Copyable
/tp command in every marker popup.
- Zoom-gated visibility for dense layers (shipwrecks, ocean ruins, …) to keep the
web app responsive.
- Seed-derived, biome-validated — candidate positions come from vanilla's own
placement math (same approach as Chunkbase), then each candidate is checked against
the world's noise-based biome source (
has_structure/* biome tags) through the
Paper API. No chunks are loaded or generated at any point.
- TPS-friendly — the whole scan is pure math on an async thread and finishes in
milliseconds per world; the main thread only publishes the markers.
Requirements
- Paper or Purpur, Minecraft 26.1 or later (
api-version: '26.1'; built against
paper-api 26.1.2)
- Java 25
- BlueMap 5.x (soft dependency — the plugin
idles when BlueMap is absent)
Install
- Drop
BlueMapStructuresPaper-x.y.z.jar into plugins/.
- Restart. On every start the plugin recomputes the markers from each mapped world's
seed (milliseconds per world; totals in console) and registers the marker layers.
On the first start the plugin also downloads the Minecraft client jar for your server's
version from Mojang (piston-meta.mojang.com, the same source launchers use) and crops
the marker icons out of its textures; both the jar and the generated icons are cached
under plugins/BlueMapStructuresPaper/. If the download fails (offline server),
markers still work with BlueMap's default POI icon and the plugin retries on the next
start.
Configuration
plugins/BlueMapStructuresPaper/config.yml:
areas: # scanned squares (union of all entries, deduplicated)
- center: origin # origin (0,0) | spawn | {x: <block>, z: <block>}
radius-blocks: 5000 # half-side of the square
#worlds: # per-world overrides (replace the default list entirely)
# resource:
# areas:
# - center: spawn
# radius-blocks: 2000
layers: # one toggle per structure layer
village: true
# ...
buried_treasure: false # opt-in: ~0.01/chunk → thousands of markers at radius 5000
mineshaft: false # opt-in: ~0.004/chunk → 1500+ markers at radius 5000
The legacy top-level radius-blocks: 5000 form still works as shorthand for a single
origin-centered area.
Markers are recomputed from the seed on every start (it costs milliseconds), so config
changes apply on the next restart — there is no cache to clear.
How it works
Structure positions are computed from the world seed with vanilla's placement
algorithm (random-spread grids per structure set, concentric rings for strongholds),
then validated against the server's noise-based biome source via the Paper API — the
same technique as Chunkbase's Seed Map, and the reason no chunks need to exist. An
earlier prototype used World#locateNearestStructure; it turned out to sync-load
chunks per candidate cell and stall the server (see issue #3). See
docs/DESIGN.md for the details and
docs/REQUIREMENTS.md for the refined requirements.
Building
./gradlew build # plugin jar at plugin/build/libs/
./gradlew :core:test # pure-logic tests only (no Paper repo access needed)
Related projects
- mc-bluemap-structures — the
Fabric original this plugin reimplements (structure-catalog reference data, see
THIRD_PARTY_NOTICES.md).
- BlueMapStructures — Paper-based
alternative that reads generated chunks from disk instead of predicting from the
seed.
License
MIT — see LICENSE. Third-party provenance (reference data from
mc-bluemap-structures, runtime-generated icons from Mojang client assets, seed-math
provenance) is documented in THIRD_PARTY_NOTICES.md.
评论 0
登录后参与评分
还没有评论,来抢沙发吧