Packet Mines

Packet Mines (Virtual Mining Regions)

Packet mines make X-PrivateMines behave like modern OP-prison cores: the ore blocks inside every mining region exist only on players' clients and in an in-memory store — never in the server world. That means:

• Instant resets. A reset is an in-memory refill plus a packet resend to nearby players. No FAWE job, no chunk writes, no TPS impact — even for hundreds of mines resetting at once.
• Zero block lag while mining. The server never processes block updates, physics or light for mine ore.
• Exact remaining-block counts. The store knows precisely how many blocks are left, so reset-percentage triggers and placeholders are exact instead of estimated.

The schematic shell (walls, platform, decoration) and the optional bedrock walls stay real blocks — only the inner mining region is virtual.

Requirements

Requirement	Why
allow-flight=true in server.properties	Players stand on client-side blocks; the server sees them floating in air and would kick them otherwise. The plugin logs a SEVERE warning at startup if this is missing.
Spigot or Paper, 1.20 – 1.21.x (and the 26.x calendar builds)	Packet mode's supported version band. On any older version the plugin logs a notice and auto-falls back to the classic real-block (FAWE) reset — mines still work, just without packet mode. Built and tested against Paper 1.21.8 / 26.1.2.
X-Prison 2026.3.0.0+ (optional)	Older X-Prison builds don't ship the virtual-blocks API; the plugin then falls back to a standalone drop pipeline (blocks go to the digger's inventory, no autosell/enchants).

PacketEvents is bundled inside the plugin jar — you do not need to install anything extra.

Enabling

# config.yml
packet-mines: true

packet-mines-settings:
  break-effects: true              # break particles + sound for other players in the mine
  vanilla-drops-to-inventory: true # only used when X-Prison is NOT installed
  dig-leniency: 0.85               # fraction of the vanilla break time accepted (anti-cheat timing skew)
  teleport-on-reset: false         # packet resets are instant; true restores the legacy teleport
  store-eviction-minutes: 0        # free memory of unviewed mines every N minutes (0 = off)

Restart the server after toggling. Switching is safe in both directions: on the first boot in packet mode the plugin clears the real ore blocks left behind by the classic reset (staggered, async); switching back simply lets the classic FAWE reset refill the regions.

X-Prison integration

With X-Prison (2026.3.0.0+) installed, virtual blocks behave exactly like real ones for the whole prison economy:

• Autosell & sell prices — priced through the same MineBlock ids, visitor tax included.
• Enchants — pickaxe block counters, pickaxe exp, finders, and the area enchants (Explosive, Layer, Nuke, Laser Beam) all enumerate and remove virtual blocks.
• Bombs — the explosion scan sees virtual blocks; selling and clearing route through the packet engine.
• Quests, lucky blocks, battle pass — per-type counting resolves virtual block types.

Two ops requirements (identical to physical mines):

1. The schematic's mine-region-flags must include upc-enchants: allow.
2. The private-mines world must be listed in X-Prison's enchants enabled-worlds.

How it works (short version)

• Each mine has a palette-compressed in-memory store (~1 byte per block; a typical 60x40x60 mine is ~144 KB). Stores materialize lazily — mines nobody is near cost almost nothing.
• Outgoing chunk packets are rewritten to overlay the virtual blocks, so joining, teleporting and respawning players always see the correct state.
• Dig packets targeting the mining region are intercepted, validated against the vanilla break formula server-side (tool speed, efficiency, haste, fatigue), and never reach the vanilla block handler. Timing cheats are resynced instead of rewarded.
• Every break still fires a normal BlockBreakEvent (on the real, server-side-air block handle), so protection plugins and third-party listeners keep working.

Limitations & notes

• Mined progress is memory-only. After a server restart (or store eviction) every mine renders fully filled again. There is no world data to persist — this is by design.
• No item entities, no tool durability from virtual blocks (standard for OP prison setups where drops are auto-sold and pickaxes are unbreakable).
• Anti-cheat plugins (Grim, Vulcan, …) may need the mines world exempted from fast-break / air-interact checks. The engine validates break timing itself.
• Bedrock clients (Geyser) use server-authoritative breaking; packet mines are Java-first. Bedrock players may see occasional block resyncs.
• UltraBackpacks does not yet understand virtual blocks — area enchants bypass it (with a console notice) and use the internal pipeline for those breaks.
• The interior of the mine is always fully lit (there is no real block to cast shadows).

For addon developers

Virtual breaks reach your code as a normal BlockBreakEvent whose block is server-side air.

• Listeners that only use event.getPlayer() (currency finders, sound/command enchants, …) work unchanged.
• To read the block's type, resolve it through the X-Prison factory instead of Block#getType(): XPrisonAPI.getInstance().getBlocksApi().getMineBlockFactory().fromBlock(block) — inside X-Prison pipelines this resolves virtual blocks (including after removal, via snapshots), or use EffectiveBlocks.getEffectiveType(block) from X-Prison core.
• To remove blocks, use EffectiveBlocks.removeBlock(player, block) (X-Prison core) or the VirtualBlockProviders API — never assume setType(AIR) does something for a mine block.
• To query or break virtual blocks directly, see dev.drawethree.xprison.api.virtualblocks (X-Prison 2026.3.0.0+): VirtualBlockProviders.blockAt(location), VirtualBlockProviders.breakBlocks(player, locations).

Troubleshooting

Symptom	Fix
Players get kicked for flying inside mines	Set allow-flight=true in server.properties.
Mining gives no money / enchants don't trigger	Update X-Prison to 2026.3.0.0 or newer; check upc-enchants: allow on the mine region and the world in X-Prison's enabled-worlds.
Old ore blocks visible after switching modes	Restart once — the migration clear runs on the first boot after the toggle.
Anti-cheat flags players mining	Exempt the private-mines world from fast-break / ghost-block checks.