BlueMap Structures Paper

Minecraft 版本： 26.1 26.1.1 26.1.2

平台： paper purpur

标签： utility

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

1. Drop BlueMapStructuresPaper-x.y.z.jar into plugins/.
2. 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.