Skip to main content
A border you cannot see through is a wall. The ghost band is the strip either side of every border where each shard shows the other’s players, mobs and block changes.

Ghosts

Every tick, a shard describes everything standing within ghost-width blocks of a neighbour and publishes it to that neighbour. The neighbour keeps one local stand-in per entity: a mannequin carrying the real skin for players, an inert copy for everything else. Ghosts are deliberately not real. They have no AI, cannot be hurt, targeted, picked up, merged or interacted with, and never persist. One not refreshed for a few seconds is removed.
Ghosts are moved rather than teleported. A teleport is a discontinuity the client starts fresh from, and twenty of those a second is why an early version stepped instead of walking. Changing the position directly lets the entity tracker emit a relative move, which the client interpolates.

What keeps it cheap

A border can have a lot standing on it, and a naive implementation is an amplifier: every entity serialised once per neighbour per tick. Four things bound it.

Silence is free

An entity that has not moved is not described. A parked minecart costs nothing until something happens to it.

Nobody looking, nothing sent

A shard with no players on it is not mirrored to at all. Presence is announced directly rather than read from a heartbeat, so an arrival is noticed at once.

A cap per frame

Players are never cut. Behind them, the nearest hold still and the rest rotate, so nothing is starved long enough to be reaped.

Equipment is cached

Armour changes about once a minute and was being re-serialised twenty times a second. It is now compared before it is encoded.
The main thread only reads: positions, poses, and a copy of any equipment that changed. Building the JSON, encoding items and publishing happen on a separate thread, in order, so a busy border costs the tick almost nothing beyond the reads.

Block mirroring

Any block change within the band is noted, its final state read two ticks later so a chain of changes costs one message, and then sent two ways. The first is a delta to each neighbour whose rectangle is inside the band, applied with physics off and only in loaded chunks. The second is an upsert into a journal collection keyed by position. The journal is the catch-up path: when a chunk in the band loads on the neighbour, it replays the journal for that chunk. Without it, a neighbour that had been restarted would show freshly generated terrain where the owner has a hole. Only reading the blocks happens on the main thread. Deltas are encoded and sent in order from their own thread, and journal writes are coalesced: whatever piled up while the last write was out goes in the next one, keeping only the latest state of each position. Past the band, out to the view distance, the neighbour shows the owner’s ground as of its last publish when border chunks are on. Changes that fire no Bukkit event, such as /fill, /setblock or a plugin writing blocks directly, are caught by reading the block updates the server sends to clients. That covers every source of change with one hook instead of an ever-growing list of events.

The region guard

The other half of the mirror is a guard that refuses every write the shard is not authoritative for: placement, breaking, buckets, fluid flow, fire, growth, decay, both explosion events, pistons, and the multi-block changes that carry a list of states rather than a block, such as bonemeal, saplings and sponges. The band is written only by the mirror. It also turns a plugin’s cross-region teleport into a proper transfer, which is what lets an ordinary warp or home plugin work here without knowing any of this exists.

Reaching across

Breaking, placing and hitting across a border do work. The shard the player is standing on cannot make the change and the shard that owns the block cannot see the player, so each side does the half it is authoritative for, in three steps:
  1. Ask. The player’s own attempt is cancelled at once, so nothing on their server treats it as an edit yet. The owner checks the block and raises ShardRemoteEditEvent for its own protection, and if the edit may go ahead, holds the block for a few seconds.
  2. Confirm. Only then does the player’s shard raise an ordinary BlockBreakEvent or BlockPlaceEvent. Every plugin there — protection, jobs, economy, logging — sees exactly one real edit, and any of them can still refuse it.
  3. Commit. The owner applies the change and says what dropped; the player’s shard spends the item, wears the tool and hands over the drops.
A refusal at either step changes nothing and raises nothing, so a protected block cannot be farmed for rewards by swinging at it. Setting up protection for this is covered in Claims and protection. It never errs towards a duplicate. A break hands over drops only when the owner confirms it applied. A place spends the item before the commit and refunds it only when the owner explicitly refuses; if the owner does not answer, the item is not refunded, because the block may well be standing over there. An item carrying data of its own — a filled shulker box, a named or written block — does not place across a border at all, since only the block’s state is forwarded. And no entity can spawn on ground the shard does not own, so a vein miner answering a confirmed break by breaking the mirrored blocks around it gets no drops from a copy.
Interactions are refused on purpose. A container or a screen is a live session against a block on a server this one cannot hold a reference to, and half-implementing that is how you get duplicated items. Players get an action bar line saying so rather than silence.