Packet Mines

Packet Mines (Virtual Mining Regions)

Packet mines make X-PrivateMines behave like modern OP-prison cores: the ore inside every mining region is rendered to players entirely through network packets instead of being stored as real blocks in the world.

What is packet mining?

To understand packet mining, it helps to see how normal mining works first.

Traditional (real-block) mining. Every block in a mine is a real block the server stores in the world on disk. When a player breaks one, the server updates that chunk, runs block physics and lighting, and tells nearby clients. When a mine resets, the server has to rewrite every block in the region — thousands or millions of block writes, chunk saves and lighting updates. On a busy OP-prison server with big mines resetting constantly, that block I/O is the number-one source of lag, and it's why classic mines lean on FastAsyncWorldEdit to soften the hit.

Packet mining. The server world where the mine sits is left empty (air). The ore a player sees isn't really there — the plugin keeps a tiny in-memory description of the mine and sends the blocks straight to each player's client as packets (the same messages the server normally uses to tell a client "this chunk looks like this"). The client draws the ore and lets the player mine it; the plugin watches the player's dig packets, decides what broke, and simply sends back a packet that turns that block to air. A reset is nothing more than refreshing that in-memory description and sending each nearby player a "here's the mine again" packet.

Because the blocks never exist on the server:

• there is no chunk to write, no physics, no lighting, no disk save — mining and resets are almost free for the server;
• resets are instant, even for hundreds of mines at once;
• thousands of mines can share the same empty world with zero block-lag.

The trade-off is that the ore isn't "real", so anything that normally reacts to real blocks (an economy, enchants, sell systems) has to be taught to understand virtual blocks. That's exactly what the X-Prison integration below does — so autosell, enchants, bombs and the rest behave as if the blocks were real, while the server enjoys the packet-only performance.

What this looks like in X-PrivateMines

• 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
  instant-break: false             # true = one-click break for every block (OP-prison feel)
  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)

Instant break

instant-break: true makes every block in a packet mine break on the first click, regardless of pickaxe tier or block hardness — the classic OP-prison feel. Hold left-click and sweep the crosshair and blocks pop continuously. Players still need permission to mine (ban / open / owner checks apply), and dig-leniency is ignored while it's on.

When false (the default), blocks obey the vanilla break speed — tool tier, Efficiency and Haste all count, computed server-side so a modified client can't mine faster than it should.

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.