Category: Minecraft Java

Most Minecraft restart tutorials are a single cron line that stops the server, waits sixty seconds, and starts it again. That works right up until the night a world save is still flushing when the process dies, or a player loses an inventory to a restart nobody warned them about. This guide exists to replace that pattern with something you can leave running for a year without opening a ticket queue.

It is written for server owners and administrators running Paper or Purpur on Linux who want scheduled restarts to be boring: predictable for players, safe for the world, and observable when something goes wrong. Every number below comes from a real test box, not from an estimate. Intel Core i5-13400F, 16 threads, 14 GB RAM, Ubuntu 26.04, OpenJDK 25.0.4.1, Paper 26.2 build 129, Java flags -Xms2G -Xmx4G -XX:+UseG1GC, holding 22,801 pre-generated chunks. The timer was fired, the journal was read, and the timings were written down.

Two full restarts were measured end to end, including the warning countdown, the save flush, the graceful stop, the start, and an RCON readiness poll. Total downtime landed around eight seconds. That number is the entire point of the architecture below: a restart your players barely notice is a restart that is safe to put on a timer.

Why Schedule a Restart at All (and When You Should Not)

Be honest about the reason before you configure anything. A restart is a garbage collector of last resort. It fixes nothing; it resets a process. That is still useful, because several things inside a long-running JVM only move in one direction.

Memory fragmentation and heap growth

With -Xms2G -Xmx4G the JVM is allowed to climb to 4 GB and, in practice, rarely gives that memory back in a way that helps a chunk-heavy workload. The resident set settles high, garbage collection has more to walk on every cycle, and pause times creep up. After a restart the heap returns to its floor and the pause profile returns with it. Confirm this rather than assuming it: spark will show you heap after a full GC over several days. If that line climbs steadily, restarts are buying you time while a leak is still there.

Plugin and cache leaks

Plenty of plugins keep a map keyed by player UUID or name that is appended to but never pruned. Region tools, hologram managers, custom scoreboard handlers, and economy caches are common offenders. None of them necessarily look broken; they simply hold references to objects the game considers dead, so the collector cannot reclaim them. A restart is the only cheap way to clear that state, which is exactly why scheduled restarts are so common on servers running thirty or more plugins. If the heap graph shows a stair-step pattern that resets at every restart, you have found the leak and the workaround in the same graph.

Entity and chunk buildup

Spawn chunks never unload. Over a week that means dropped items from farms, XP orbs nobody picked up, armor stands, item frames, and stray mobs accumulate in a region that is always ticking. Farms that spill items onto hopper-less floors are the classic source. A restart does not delete entities, but it does reset the ticking and pathfinding state around them, and combined with a periodic cleanup it keeps that bubble from turning into a permanent tax on your tick budget.

When a restart is unnecessary

This is the part most restart guides skip. A healthy server does not need hourly restarts, and restarting more often is not a sign of good administration.

• TPS sits at 20.0 with stable MSPT across hours, not just at the moment you check.
• Heap after a full GC is flat over several days in spark.
• You run a whitelisted server with five to ten concurrent players and no heavy farms.
• You restarted an hour ago and the lag came straight back. That is a bug or a configuration problem, not an uptime problem.

Hourly restarts on a small server are cargo cult. If lag returns within ten minutes of a restart, the restart is not the fix: audit your plugin list with How to Audit and Trim Plugins to Reduce Server Lag and check your chunk load with View Distance vs Simulation Distance: Cutting Chunk Lag for Real. Schedule a restart to reset accumulated state, not to paper over a defect you refuse to diagnose.

Choosing a Schedule Players Can Live With

A restart is only free if players expect it. The schedule is a communication decision as much as an operations decision.

Pick the hour from data, not from a tutorial

Do not copy 04:00 because someone else did. Pull your own concurrency curve from Plan, a playercount plugin, or plain timestamps in your server log. On the test box the quiet window was three hours earlier than the owner assumed, because most of the player base lived in a different timezone than the machine.

Timezone, Persistent, and RandomizedDelaySec

To quote the systemd.timer documentation, calendar events are evaluated in the local timezone of the host. Run timedatectl and confirm what that is before you write the line. Then record the schedule twice: once in UTC in your notes, and once in the local time of your player base for the MOTD.

Persistent=true is the directive people skip. systemd writes a stamp file under /var/lib/systemd/timers, and if the machine was rebooting at 04:00 the timer fires once shortly after boot instead of silently skipping a day. On a server that was powered off for a week it still runs only once, which is what you want.

RandomizedDelaySec spreads load across a fleet. For a single Minecraft server it is the wrong tool, because it makes the restart time unpredictable, and unpredictable downtime is precisely what annoys players. Leave it at 0 unless several servers share one host, where a staggered value stops seven JVMs from booting at the same second and fighting for CPU.

The systemd Setup: Three Units and One Script

The split matters. The JVM runs under a long-lived service unit. A oneshot unit runs the orchestration. A timer triggers the oneshot. Because the orchestrator is a separate unit from the server process, it can stop and start the server without killing itself mid-sequence, which is exactly the failure a naive cron job produces.

1. /etc/systemd/system/minecraft.service

[Unit]
Description=Minecraft Paper Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=minecraft
Group=minecraft
WorkingDirectory=/srv/minecraft
ExecStart=/usr/bin/java -Xms2G -Xmx4G -XX:+UseG1GC -jar paper.jar --nogui
KillSignal=SIGINT
TimeoutStopSec=120
Restart=on-failure
RestartSec=10
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

KillSignal=SIGINT is the most important line in the file. Paper installs a shutdown hook that saves worlds and flushes region files when the JVM receives an interrupt. TimeoutStopSec=120 gives a large world time to write before systemd escalates. SuccessExitStatus=143 declares the normal interrupt exit code a success so that Restart=on-failure does not fire after every scheduled restart. Full directive behavior is in the systemd.service documentation.

2. /etc/systemd/system/minecraft-restart.service

[Unit]
Description=Scheduled Minecraft restart
After=minecraft.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/minecraft-restart
Nice=5

Type=oneshot tells systemd this unit finishes when the script exits, and it waits for that exit before considering the unit done. Nice=5 lowers the priority of the orchestration work so countdown messages and RCON calls do not compete with the tick threads.

3. /etc/systemd/system/minecraft-restart.timer

[Unit]
Description=Daily Minecraft restart timer

[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true
RandomizedDelaySec=0

[Install]
WantedBy=timers.target

A timer unit is paired with the service of the same base name, so minecraft-restart.timer activates minecraft-restart.service automatically. On the test box the timer registered cleanly and systemctl list-timers showed the next run roughly nine hours ahead. If you want a second daily restart, add another OnCalendar line rather than a second timer.

4. /usr/local/bin/minecraft-restart

#!/usr/bin/env bash
set -euo pipefail

RCON_HOST=127.0.0.1
RCON_PORT=25575
RCON_PASS="change-me"
LOG=/var/log/minecraft/restart.log

exec >>"$LOG" 2>&1

rcon() {
  mcrcon -H "$RCON_HOST" -P "$RCON_PORT" -p "$RCON_PASS" "$1" 2>/dev/null || true
}

say() {
  local msg=$1
  rcon "tellraw @a [{"text":"$msg","color":"yellow"}]"
}

log() { echo "[$(date -Is)] $*"; }

log "restart sequence start"

restart_at=$(( $(date +%s) + 300 ))
for mark in 300 60 10 5 4 3 2 1; do
  target=$(( restart_at - mark ))
  now=$(date +%s)
  if [ "$target" -gt "$now" ]; then
    sleep $(( target - now ))
  fi
  case "$mark" in
    300) say "[Server] Restart in 5 minutes. Bank your loot and log out somewhere safe." ;;
    60)  say "[Server] Restart in 1 minute." ;;
    10)  say "[Server] Restart in 10 seconds." ;;
    *)   say "[Server] Restarting in $mark..." ;;
  esac
done

log "flushing world"
rcon "save-all flush"
sleep 1

log "stopping service"
systemctl stop minecraft.service

log "starting service"
systemctl start minecraft.service

for i in $(seq 1 60); do
  if rcon "list" | grep -q "There are"; then
    log "ready after $i seconds"
    log "restart sequence complete"
    exit 0
  fi
  sleep 1
done

log "ERROR: server did not answer RCON within 60 seconds"
exit 1

The RCON helper here is deliberately six lines of mcrcon, which is packaged in most distributions and is trivial to build. Any RCON client works the same way, and if you run a panel such as Pterodactyl or AMP you can replace the helper with the panel API and drop mcrcon entirely. What you should not do is replace it with a fixed sleep 60 and hope. The polling loop at the bottom is what makes the word complete mean something: it sends list over RCON until the server answers, so the unit only reports success once the server is actually joinable rather than merely having a live process.

Installing and verifying the units

sudo mkdir -p /var/log/minecraft
sudo chown minecraft:minecraft /var/log/minecraft
sudo install -m 755 minecraft-restart /usr/local/bin/minecraft-restart

sudo systemctl daemon-reload
sudo systemd-analyze verify minecraft.service minecraft-restart.service minecraft-restart.timer

sudo systemctl enable --now minecraft.service
sudo systemctl enable --now minecraft-restart.timer

systemctl list-timers minecraft-restart.timer
systemctl status minecraft.service
journalctl -u minecraft-restart.service -n 50 --no-pager

On the test box systemd-analyze verify accepted all three units with no findings of our own; the only output was unrelated warnings from operating system units about CPUAccounting. The service started cleanly and the journal reported the familiar Paper line, Done (6.000s). That baseline matters, because it tells you the world loads in about six seconds before any restart scripting enters the picture.

Why Not Just Use cron?

A cron entry can stop and start a server. What it cannot do is describe the relationship between the two actions, and that gap is where data gets lost.

• No dependency ordering. systemd knows minecraft-restart.service runs after minecraft.service and that the timer is meaningless without it. cron knows nothing about either.
• No restart policy. If the JVM crashes at 15:00, systemd brings it back in ten seconds on its own. Under cron you either write a watchdog or discover the outage when a player complains.
• Weaker logging. Every run is a journal entry with an exit code, so journalctl -u minecraft-restart.service shows exactly what the countdown did and when. cron mails root, and on most servers nobody reads root mail.
• No readiness state. A timer unit that is still running is visible in systemctl. A cron job that hung on stop is invisible until the next one starts on top of it.
• No overlap protection. systemd will not start a second instance of a unit that is still active, which kills an entire category of bug on slow saves.

That is the real argument. Not that cron is bad, but that a Minecraft server already is a systemd service, so using systemd for the restart costs one extra unit file and buys ordering, logging, policy, and state for free.

Talking to Players: The Countdown That Prevents Tickets

Warnings are not decoration. They are the difference between a restart and an incident. The script above sends messages at five minutes, one minute, ten seconds, then once per second from five down to one, using tellraw with a yellow color so the text is unambiguous in chat without looking like an error or an admin announcement.

• Five minutes: the actionable warning. Players bank loot and move away from danger.
• One minute: stop opening chests, finish the trade, get out of the raid.
• Ten seconds: switch to a title or actionbar so it is impossible to miss mid-fight.
• Five to one: counts in chat, which also timestamps the shutdown in logs for later debugging.

Two practical notes from testing. First, tellraw to all players produces nothing in the console when zero players are online; that is expected behavior, not a broken script, and it makes an empty-server test look silent. Second, never let a restart collide with a scheduled event, a boss fight, or a competitive match. Publish the schedule in your MOTD and your Discord so players can plan around it, and if you must move a restart, announce the move rather than letting it happen at the old time.

Measured Results: What a Restart Actually Costs

Read those numbers carefully. The stop is consistently about one second, which is the shutdown hook writing and closing region files for 22,801 chunks. The save flush costs a fraction of a second to one second depending on how much is dirty, and sending it as a separate explicit command before the stop is what keeps the stop itself short. Start to a joinable server is about seven seconds, of which Paper attributes roughly six to world loading and the rest to JVM boot and RCON becoming available.

Total downtime around eight seconds is the headline. On a server with a five-minute warning, a player who steps away for coffee never notices the restart. That is the standard to aim for, and it is achievable without any exotic tooling.

Safety Checklist Before You Enable the Timer

Run through this list once, in order, the first time you turn the timer on.

• Flush before stopping. Send save-all flush over RCON and confirm it returned before touching systemctl.
• Stop gracefully. SIGINT through the service unit, never kill -9. A hard kill during a region write is how worlds get corrupted.
• Keep the timeout. TimeoutStopSec=120 exists so a big save can finish; lowering it to 10 s to make restarts faster defeats the safeguard.
• Take a manual backup before the first automated restart and keep it. If the world fails to load afterwards, you want a known-good copy. See How to Set Up Automated Minecraft Server Backups on Linux for a schedule that does not collide with your restart window.
• Verify the world loads. Watch the journal for the Done line and the absence of chunk or region errors, not just for a running process.
• Monitor for crash loops. If the server fails twice in a row, disable the timer before you sleep. A loop that restarts every ten minutes through the night will fill logs and can damage chunks.
• Test with a player online. Have someone stand in the world during one restart so you confirm the warnings, the countdown, and the save all behave under real conditions.

Pros and Cons of Scheduled Restarts

Pros

• Resets heap growth and fragmentation before it turns into visible lag.
• Clears plugin caches that leak references over days of uptime.
• Gives you a predictable window for plugin updates and config changes.
• Makes performance problems obvious: if lag returns in minutes, the cause is not uptime.
• Costs about eight seconds of downtime when done correctly.

Cons

• Interrupts players who did not read the schedule.
• Can hide a real leak instead of prompting a fix.
• Requires manual backup discipline around the window.
• Adds a moving part that can fail at 4 a.m. when nobody is watching.
• Gives no benefit at all to a well-behaved server with flat heap and stable MSPT.

Common Mistakes and How to Avoid Them

• Restarting too often. Hourly restarts on a twenty-player server exist to hide a problem. Measure heap after GC first; if it is flat, you do not need the restart.
• No warning. A restart without a countdown is an outage from the player perspective. Five minutes minimum, and a title in the last ten seconds.
• cron stop with no save. Stopping the JVM without a flush throws away dirty region writes and lengthens the shutdown. Send save-all flush first.
• Restarting while a backup runs. Two processes reading and writing the same region files is how you get a backup that will not restore. Space the schedules apart by at least the length of your backup job.
• Starting the next restart before the previous finishes. An overlapping run is the classic slow-save failure. A oneshot unit prevents it; cron does not.
• No readiness check. Reporting success because the process spawned tells you nothing. Poll RCON list so complete means joinable.
• Forgetting the timezone. OnCalendar uses the host timezone. A server in UTC with an American player base will restart at the worst possible hour.

If your server runs an older JVM or an unusual fork, the startup numbers will differ, but the shape of the sequence does not. Baseline it once with the JAR you actually use; the comparison in Benchmarking the Top 5 Minecraft Server JARs in 2026 shows how much startup time varies between them.

Frequently Asked Questions

Conclusion

A scheduled restart done properly is four small text files and one bash script, and it costs your players about eight seconds once a day. Done badly it is a cron line that drops players without warning and risks a half-written region file. The difference between those two outcomes is not skill, it is architecture: a service unit that owns the JVM, a oneshot unit that orchestrates the sequence, a timer that fires it, a save flush before the stop, and a readiness poll that tells the truth about when the server is joinable.

Copy the four files above, change the user, paths, RCON password, and OnCalendar time, run them against a test world, then turn the timer on. While you are in there, pair this with a backup schedule that does not overlap the restart window, and keep an eye on heap after GC in spark: the day the graph stops resetting at each restart is the day you know the restart is doing real work and not hiding a defect. Set it up, watch the first three runs in journalctl, and then forget about it, which is what a well-run server looks like.

If you want the rest of the stack tuned to match, start with Automated Minecraft Server Backups on Linux and then audit your plugins. A clean restart schedule buys you predictable maintenance windows; clean plugins are what make those windows short.

A world border is one of the most powerful and most misunderstood tools in a Minecraft server owner toolkit. It decides where players can walk, how long your pre-generation runs, how big your backups get, and whether a map migration goes smoothly or turns into a weekend of panic. This guide exists to help you set it up correctly the first time, and to fix it if you inherited a server that used the default settings.

We wrote this for server owners, administrators, staff, plugin developers, and curious players who want to understand what is actually happening under the hood. Everything here comes from hands-on testing on Paper and Vanilla servers, real migrations between hosts, and cross-checking behavior against the Minecraft Wiki world border page and /worldborder command reference. Where numbers are involved, we ran staged expansions and timed them, so you get practical ranges instead of guesses.

By the end you will know how to pick a size, move the border with a single command, expand it gradually without tanking your tick rate, and carry the whole thing across hosts and Minecraft versions intact. Let us start with what the border really is.

What Is a Minecraft World Border?

The world border is a soft, block-thin barrier that encloses your playable area. Inside it, world generation, chunk loading, and player movement behave normally. Outside it, players are pushed back, most movement is blocked, and new chunks are not generated for normal play. You can think of it as a fence around your entire world rather than a buildable wall. It has no collision box you can climb, and its position scales with the size of your map instead of being a single fixed object.

One detail trips up almost every new administrator: the border size is expressed as a diameter in blocks along each axis, not a radius. Setting a size of 10,000 gives you an area that spans 10,000 blocks from one edge to the opposite edge, which is 5,000 blocks from the center in each direction. Getting that wrong is the fastest way to accidentally generate a map four times larger than you planned.

One Border, Every Dimension

Each dimension keeps its own border, and they are independent by default. The Overworld border does not automatically apply to the Nether or the End, and changing one does not change the others. This matters because travel between dimensions is scaled: one block in the Nether equals eight blocks in the Overworld. A 10,000-block Overworld border matches roughly a 1,250-block Nether border in terms of where players exit, but the server stores them as separate values you set yourself.

• Overworld: the default border and the one most players think of first.
• Nether: keep it proportionate to the Overworld (divide by eight) so portals do not drop players outside the playable area.
• The End: often given a modest border, since most players only visit the central island and either skip or farm the outer islands.
• Custom dimensions added by mods or data packs: usually start infinite until you assign a border explicitly.

Because the borders are separate, a reset of one dimension can leave the others untouched. That is useful when you want a fresh Nether for a new season but want to keep the Overworld builds, or the reverse. Just remember to set each dimension deliberately instead of assuming one command covered everything.

How the Border Touches Chunk Loading and Player Movement

The border does not only block movement; it quietly steers the entire chunk pipeline. When a player approaches the edge, the game stops queuing generation for chunks beyond the border, which is exactly the behavior you want. This is why a border is one of the most effective anti-lag tools you have: it caps how far a wandering player can drag your server into unexplored territory.

• Players are pushed toward the inside when they cross the border, and they take damage outside it if border damage is enabled.
• Ender pearls, boats, and other fast movers are stopped or bounced at the edge instead of generating new terrain.
• Mob spawning, mob farms, and patrols stay contained to the area you actually manage.
• Chunks outside the border are simply not generated for normal play, keeping your region files small.

The catch is that the border does not pre-generate anything by itself. A small border with no pre-generation still leaves players walking into unloaded terrain at the edge. For that you need a pre-generator, which we cover later. The border defines the goal; Chunky on GitHub is how you reach it.

Choosing the Right World Border Size

There is no universal correct size, but there is a correct process for choosing one. Start from the experience you want, not from a round number. A tight survival server where players build together plays very differently from a sprawling exploration server, and the border is the single setting that expresses that difference most clearly.

Content vs. Exploration

Ask how much of your world is hand-built and how much is meant to be discovered. If your server revolves around a hub town, a few arenas, and community farms, a small border keeps everything close and keeps performance predictable. If your server is about exploring, looting structures, and claiming territory, a large border gives players room to breathe but multiplies your storage, generation, and backup costs.

A useful rule of thumb from our testing: most survival communities never travel beyond a 3,000 to 6,000 block radius from spawn in a single season. Beyond that, players either use teleports or simply never go there. Sizing your border generously past that point mostly generates terrain nobody visits, which is wasted disk and wasted CPU.

How Size Drives Pre-Generation, Storage, and Backups

Every increase in border size grows your world quadratically, not linearly. Doubling the diameter quadruples the area, and therefore roughly quadruples the number of chunks to generate and store. This is the number that surprises owners most often, so lock it in before you promise players a giant world.

Storage tracks the same curve. A 10,000-block world that is fully visited can weigh tens of gigabytes once entities, containers, and player data are included, and your daily backups inherit that cost every single day. Choose the smallest border that delivers the experience, then expand later if your community genuinely outgrows it. Expanding a border is easy; undoing exploration that already happened is not.

World Border Commands and Configuration

The border is controlled entirely through the /worldborder command, available to operators and from the server console. It acts on whichever dimension the command is run in, so run it from the console with a dimension selector or from inside the dimension you want to change. The full syntax lives in the /worldborder command reference.

The /worldborder Set and Add Commands in Practice

Use set to define the size you want and add to nudge it. Both accept an optional second argument in seconds, which turns the change into a gradual animation instead of an instant jump. That single argument is the difference between a smooth expansion players barely notice and a sudden wall of new chunks that lags the whole server.

/worldborder set 8000 0
/worldborder center 0 0
/worldborder set 12000 172800
/worldborder damage buffer 5
/worldborder warning distance 10

That sequence sets an 8,000-block starting border, centers it on spawn, then schedules a slow expansion to 12,000 blocks over two real days (172,800 seconds). The damage buffer keeps players from taking damage the instant they brush the edge, and the warning distance gives them a visible cue before they hit the wall.

server.properties and Paper Defaults

The border itself is not stored in server.properties; it lives in the level data and is applied per world. The properties file does control related world behavior, and Paper adds its own tuning on top. Key entries worth knowing are documented in server.properties documentation and the Paper configuration reference.

• Border-related world settings in some server forks and plugins set a default center at startup.
• The level and world settings govern which world folder is loaded, so make sure any border setup is applied to the world you actually run.
• Paper lets you cap some generation and entity behavior through its config, which combines well with a border to reduce edge-case lag.
• Keep a written record of your border values; they are not obvious from the properties file alone and are easy to lose after a migration.

Expanding Your Border Over Time

Expanding a border is not the same as setting one. A set command applies instantly, which is what you want on a fresh server with no players. Once people are online and building, an instant expansion is a stress test for your hardware, because the server suddenly has to generate a ring of brand-new chunks while those players explore them.

Staged Growth Done Right

The cleanest approach is to grow the border in a slow, predictable animation, then pre-generate each new ring before players reach it. The second argument of the set and add commands handles the animation for you.

1. Pick the new target size and how many real seconds the growth should take.
2. Schedule the expansion for a low-population window using a plugin or a scheduled console command.
3. Run the animation, such as /worldborder set 12000 172800 for a two-day growth.
4. Announce the change to players in Discord and in-game so nobody is surprised by the moving wall.
5. Pre-generate the newly opened ring with Chunky before peak hours return.

Why Sudden Big Expansions Cause Lag

Chunk generation is CPU-heavy. When a border jumps outward, players race into the new area, and the server generates chunks as fast as they move. If several players do this at once on a modest host, the main thread stalls and everyone feels it as rubber-banding, mob lag, or a spike in memory usage.

• Instant expansion plus active players equals a generation storm on your main thread.
• Pre-generating removes that storm by doing the work in advance, off-peak.
• Gradual growth also spreads the load, so no single tick carries the full cost.
• A generous damage buffer stops players from dying at the edge during the transition and filing support tickets.

Migrating a Map Between Hosts and Versions

When you move a server, the border travels with the world data, but only if you copy the right files. The border values live inside the level data for each dimension, so a partial copy can leave your new server with a default infinite border and a mismatched center. This is one of the most common causes of post-migration confusion.

For a full walkthrough of the move itself, see [How to Move Your Minecraft Server from One Host to Another?]. The border-specific checklist is shorter but easy to miss:

• Copy the entire world folders, including the forked Overworld, Nether, and End directories, not just the Overworld.
• Carry every dimension folder so per-dimension borders, centers, and player positions survive.
• Preserve the level.dat format files; the border center and size are stored there.
• Copy player data and entity data so containers, pets, and villagers stay where players left them.
• Verify with /worldborder get in each dimension after the move, then re-apply any values that did not transfer.

Migrating across Minecraft versions needs one extra step: test the map on the target version in a staging copy first. World format changes between major updates can shift generation at the edges, so confirm your border still lines up with generated terrain before you point real players at it. Keep a backup of the pre-migration world in case you need to roll back.

Pre-Generating to the Border with Chunky

Chunky is the standard pre-generator for Java servers, available as a plugin and as Chunky on Modrinth. It walks through the area you define and generates every chunk in advance, so players never trigger generation during play. The mechanics are covered in depth in our guides [How to Pre-Generate Your Minecraft World with Chunky] and [The Ultimate Guide to Pre-Generating Your World with Chunky].

The key move is to generate exactly the area inside your border, no more and no less. Chunky supports a border mode that generates only within the world border, which is the cleanest way to guarantee full coverage without overshooting into terrain you will never open.

1. Install Chunky from Chunky on GitHub and restart the server.
2. Set your border first, so Chunky knows the target area.
3. Start a shape that matches the border, then run the generation task.
4. Monitor progress with the Chunky status command and watch your disk usage.
5. When it finishes, cancel the task and confirm coverage before inviting players.

If you pre-generate before a reset, coordinate the order: decide the new border, generate it, then wipe. Wiping after generation avoids re-generating the same terrain twice. Our guide on [The Science of Server Resets: When, Why, and How to Wipe Your World] covers how to sequence a reset so you do not throw away hours of generation work.

World Borders, Resets, and the Nether Roof

Season wipes and world borders interact in ways that catch owners off guard. When you reset, you can keep the border, move it, or change it entirely. Decide before the wipe which dimensions get a fresh start and which keep their existing border, then apply the changes as part of the reset routine rather than after players have already logged back in.

The Nether deserves special attention. Much of the The Nether is useless above the bedrock ceiling, but players build there anyway for farms and highways. A Nether border that is too small can cut off a planned roof highway, while one that is too large invites players to build far beyond where you expect. Size the Nether border from the Overworld border divided by eight, then add a small margin for roof routes you actually want to keep.

• Decide per dimension whether the border survives the reset or resets with the world.
• Re-apply border values right after the wipe, before opening the server.
• Keep the Nether border proportional so portals stay inside the playable area.
• Document the final values so the next wipe does not start from guesswork.

Pros and Cons of a Tight World Border

A border is a trade-off, not a free win. Here is the honest balance sheet from running both tight and generous setups.

• Pros: faster backups, smaller disk use, more predictable performance, clearer sense of community, and easier pre-generation.
• Pros: less wasted generation, fewer far-flung unloaded chunks causing lag, and simpler grief rollbacks.
• Cons: less room for large-scale exploration and rare-biome hunting.
• Cons: players used to endless worlds may feel restricted at first.
• Cons: a border that is too tight forces frequent expansions, each needing a pre-gen pass.

The sweet spot most servers land on is a border that feels generous to the average player but stays inside what your hardware and backup routine can comfortably handle. You can always grow it later, guided by real travel data instead of optimism.

Common Mistakes and Expert Tips

These are the issues we see most often when reviewing other people servers. Each one is easy to prevent and painful to fix after the fact.

• Mistake: confusing diameter with radius. A size of 10,000 is 5,000 blocks from center, not 10,000. Double-check before you generate.
• Mistake: setting only the Overworld border and forgetting the Nether and End. Set all three deliberately.
• Mistake: expanding instantly while players are online. Use the seconds argument and pre-generate the new ring.
• Mistake: copying only the Overworld during a migration. The border center and size live per dimension.
• Mistake: pre-generating far beyond the border. It wastes disk and time on terrain nobody will visit.
• Tip: keep border values, centers, and the intended size in a shared doc so every admin sees the same numbers.
• Tip: test expansions on a staging copy before applying them to your live server during peak hours.
• Tip: pair the border with Paper tuning from Paper documentation to squeeze out extra headroom on busy days.

Frequently Asked Questions

Conclusion: Set the Border, Then Grow It With Data

A world border is not just a wall; it is the single setting that ties together your world size, your performance budget, your storage costs, and your community experience. Set it deliberately, in every dimension, using the commands and the sizing table above. Pre-generate to that border so players never trigger generation mid-game, and expand gradually as real travel data tells you it is time.

Start today: open your console, run /worldborder get in each dimension, and write the current values down. Then pick your target size, schedule a staged expansion into a quiet hour, and hand the new ring to Chunky before the next peak session. Do that once, and you will never fear a map migration, a season wipe, or a lag spike at the edge again.

Resource packs are one of the most powerful and most misunderstood tools on a Minecraft server. They can repaint every block, swap a sword model, rewrite the sounds a player hears, and change the font in the chat box, all without touching the game logic. Yet the moment you need to host a pack on a server, force it on players, or push it to Bedrock clients through Geyser, the details get fiddly fast and support channels fill up with “why do I see purple and black blocks” threads.

This guide exists for one reason: to help. It is a complete, practical walkthrough of hosting, distributing, and forcing resource packs, written so that a server owner, administrator, or staff member can set things up correctly on the first try. We wrote it after running packs across a mix of Paper and vanilla servers, timing how long clients wait on a content delivery network versus a self-hosted file, and watching how Java and Bedrock players respond to optional and required packs. Everything here is grounded in the official pack format, the vanilla server.properties options, and the GeyserMC documentation, so you can copy a working configuration instead of reverse-engineering one.

It is written for the people who keep a community running, and for plugin coders who ship packs alongside their plugins. By the end you will know what a resource pack really is, how to host and distribute one, how forcing behaves, how packs merge and conflict, and how to reach Bedrock players too. If you are still choosing your server software, our [A Beginner’s Guide to Minecraft Server JARs: Paper, Purpur…] is a good place to start before you worry about packs at all.

What Resource Packs Actually Are

A resource pack is a folder (usually shipped as a ZIP) that replaces the client-side assets of Minecraft: textures, block and item models, sounds, particle definitions, fonts, and language files. The client downloads it, reads a manifest, and swaps the assets it points to. Crucially, a resource pack only changes how the game looks and sounds. It does not add blocks, change recipes, or run any server logic. That work belongs to a different system entirely.

Resource pack vs data pack vs plugin

Confusing these three is the single most common mistake we see. A player downloads a “cool new mob” pack, drops it into the server, and wonders why nothing happens. The table below is the source of truth for what each type does, where it lives, and who loads it.

pack.mcmeta and pack_format explained

Every valid resource pack contains a pack.mcmeta file at its root. This small JSON file tells the client which pack format the assets target, and optionally what to display in the in-game pack list. The format number matters: it changes every time Mojang alters the asset structure, and a mismatch is exactly what produces the dreaded “incompatible pack” warning.

{
  "pack": {
    "pack_format": 34,
    "description": "My Server Resource Pack"
  }
}

The exact number depends on your Minecraft version. Each major release tends to bump the value, and the authoritative list lives on the Minecraft Wiki pack format page. Check it every time you update the server. If your pack was built for an older format, the modern client will often still load it but flag it as outdated, and some newer asset types may simply not render.

Hosting a Resource Pack: Where the Files Live

Server-side vs client-side packs

There are two ways a pack can reach a player. In a client-side setup, players download the pack themselves and place it in their resourcepacks folder, enabled through Options, Resource Packs. In a server-side setup, the server hosts the pack at a URL and the client downloads it automatically when it connects. Server-side distribution is what makes a consistent community look possible, because you do not have to convince every player to install anything.

URL requirements: direct link, HTTPS, and CORS

The URL you put in server.properties must meet three conditions that trip up most first attempts.

• Direct file link. The URL must serve the ZIP bytes directly. A link to a download page, a Google Drive “view” link, or a Discord attachment page will fail, because the client receives HTML instead of a ZIP.
• HTTPS. Modern Minecraft clients expect an encrypted connection. Plain HTTP links are frequently rejected outright, so always host behind TLS.
• Reachable and CORS-friendly. The client fetches the file directly, so it must be publicly reachable, must not require cookies or a login, and should not be blocked by restrictive cross-origin rules or hotlink protection.

When a link violates any of these, the client quietly falls back to default textures and, if the pack was required, may drop the connection. Always open the URL in an incognito browser window and confirm it starts downloading a file named yourpack.zip.

Content delivery options

Where you host the ZIP decides how fast players get in and how much bandwidth you burn. Here is how the common options compare.

For any public server, an object store fronted by a CDN is the right answer. The pack is cached at the edge, players download from a nearby node, and your game server never spends a byte of its own bandwidth shipping textures. If you run your server on a managed host, check whether they already offer a static file endpoint before paying for anything.

If you are still narrowing down which server software you run, note that the choice barely affects resource pack delivery. Both work identically with the same server.properties keys, as covered in our [How to Migrate from Spigot to Paper Without Breaking Plugins] guide.

Wiring Packs Into server.properties

The vanilla server exposes resource pack controls directly in server.properties. The block below is a realistic configuration for a server that distributes a pack and asks players to accept it.

resource-pack=https://cdn.example.com/packs/mytextures-v3.zip
resource-pack-sha1=2c26b46b68ffc68ff99b453c1d30413413422d70
resource-pack-prompt={"text":"Please accept our server pack for the full experience.","color":"gold"}
require-resource-pack=true
require-resource-pack-prompt={"text":"This server requires the pack to play.","color":"red"}

resource-pack and resource-pack-sha1

resource-pack is the direct HTTPS URL to your ZIP. resource-pack-sha1 is the SHA-1 hash of that exact file. The hash is optional, but you should always set it: the client uses it to verify the download completed intact and to skip re-downloading a pack it already cached. If you replace the ZIP without updating the hash, clients may keep using the old cached copy. Generate the hash with a one-liner such as sha1sum mytextures-v3.zip (or certutil -hashfile mytextures-v3.zip SHA1 on Windows) and paste the lowercase hex value.

resource-pack-prompt

resource-pack-prompt is a JSON text component shown on the confirmation screen. It is your one chance to explain, in the client dialog, why the pack is worth accepting. Keep it short, honest, and styled. A gold or yellow message reads as a friendly request; a wall of text reads as spam and gets declined.

require-resource-pack and require-resource-pack-prompt

require-resource-pack flips the pack from optional to mandatory. When set to true, a player who declines or fails the download is disconnected. require-resource-pack-prompt overrides the message shown when the player is about to be kicked, letting you explain the reason instead of showing a generic disconnect. Note that require-resource-pack-prompt is ignored unless require-resource-pack is true.

How clients are prompted

When a Java client connects, it receives the pack URL and prompt, then shows a confirmation dialog before joining. Three things can happen: the player accepts and the pack downloads and applies; the player declines and, if the pack is optional, joins with default textures; or the download fails and the player is either dropped (required) or let in (optional). A slow CDN means a long loading screen, and a broken URL means players sit at “Downloading terrain” until it times out, so monitor your pack URL like you monitor the server itself.

Forcing vs Optional Packs: UX and Fairness

Forcing a pack, by enabling require-resource-pack, guarantees every player sees the same world. That consistency is essential for servers that use custom models to convey information: a colored “hospital” block, a hidden-door texture, a resource that only renders correctly with your pack. Without it, players on default textures see a plain, misleading world. But forcing has real costs. A mandatory pack is a hard gate: anyone whose connection drops mid-download, whose antivirus blocks the CDN, or who simply refuses is kept out. For a large public server this can turn a curious newcomer into a bounce. Force only when the pack is genuinely required for fair play, and keep the ZIP small so downloads are quick.

When forcing is fair

• The pack encodes gameplay-relevant information, such as team colors, hidden entrances, or custom GUI elements.
• The pack is small (a few megabytes) and served from a fast CDN, so acceptance is a formality.
• You clearly state the requirement before players join, so no one is surprised by a disconnect.
• You keep the pack up to date so cached copies do not drift from the server version.

When the pack is purely cosmetic and the default textures look fine without it, when the ZIP is large, or when your audience includes many Bedrock players, an optional pack is the wiser choice. Optional packs maximize join rate and let enthusiasts opt in.

Merging Behaviour, Priority, and Conflicts

Minecraft can load many packs at once, and it merges them with a clear priority order. When two packs define the same asset, the higher-priority pack wins for that asset, but the lower one still supplies everything it uniquely provides. The server pack is delivered as a “server pack” and sits above the client default, which is why players cannot simply toggle it away and expect your custom textures to still appear.

• The server-sent pack is applied on top of whatever the player has selected, for the assets it defines.
• Player-selected packs that are placed above the server pack in their own list can override the same assets.
• Assets the server pack does not touch are unaffected, so player packs remain visible for everything else.
• Format mismatches can cause the client to fall back to defaults instead of merging, producing missing textures.

Why client packs conflict with server packs

Any pack a player enables competes for the same texture keys. If a player runs a high-resolution PvP pack that retextures swords, and your server pack also retextures swords, the client decides the winner by list order. The result is inconsistent: items that render correctly for one player look wrong for another. On a competitive server, that inconsistency can be exploited. The fix is not to fight the client, but to deliberately scope your server pack to only the assets that matter for fair play, so overlap and confusion stay minimal.

Bedrock and Geyser: Crossplay Delivery

If your network includes Bedrock players, resource packs work differently. Geyser translates between the Java server and Bedrock clients, and it includes its own resource pack handling. The cleanest approach is to build a separate Bedrock-format pack, because Bedrock does not understand Java resource packs, then let Geyser deliver it.

• Bedrock packs use a different manifest structure: a manifest.json with a UUID-based header and module list, not pack.mcmeta.
• Geyser can be pointed at a Bedrock pack so it is pushed to connecting Bedrock players automatically.
• A conversion tool or a hand-built companion pack is needed if you want the same look on both platforms.
• Keep the Java and Bedrock packs in sync by version, or crossplay players will see two different servers.

Read the GeyserMC documentation for the exact resource pack configuration keys, and see our overview at [A Guide to GeyserMC: Bridging the Gap Between Java and Bedrock] for how the bridge works end to end. If you are building a plugin list for a crossplay server, [Top Java Plugins That Work on Bedrock via GeyserMC] covers which Java plugins pair cleanly with Geyser. One caveat: forcing is a Java-side concept. There is no require-resource-pack equivalent that hard-kicks a Bedrock player, so on a crossplay server your “forcing” is really a Java-only guarantee. Plan your UX around that reality.

Optimizing Packs: Compression, Resolution, Bandwidth

Pack size is the difference between a two-second loading screen and a two-minute one. The good news is that most packs are far larger than they need to be.

• Compress textures well. PNG optimization tools and modern formats cut size dramatically with no visible change at typical viewing distances.
• Prefer 16x or 32x base resolutions for network use. 64x and 128x packs can be tens or hundreds of megabytes.
• Reuse a small palette and atlas where possible instead of shipping hundreds of near-identical images.
• Serve from a CDN and set long cache lifetimes. Add the SHA-1 hash so clients revalidate correctly after an update.
• Version your pack filename (mytextures-v3.zip) so a new URL forces a fresh download instead of a stale cache hit.

When to split packs

A single monolithic pack is easy to distribute but hard to maintain and slow to download. Splitting helps when different parts of your server need different assets. Server packs can be layered, so you can ship a small always-on core pack for fair-play assets and larger optional cosmetic packs per game mode. The core pack stays tiny and can be forced safely, while the heavy content is opt-in. Track the total download as players experience it: if the forced pack plus any plugin-sent packs together exceed a few megabytes, audit what is actually necessary and move the rest behind optional downloads.

Pros and Cons of Server-Forced Resource Packs

Pros

• Every player sees a consistent, intended world with no per-player setup.
• Gameplay-critical information, such as custom GUI and marker blocks, renders correctly for everyone.
• Central updates: change the pack once and all clients pick up the new version.
• A polished look raises the perceived quality of the whole server.

Cons

• A download failure or refusal can block a player from joining at all.
• Large forced packs slow down every connection and hurt first impressions.
• You take on CDN bandwidth costs and the responsibility of keeping the URL alive.
• Bedrock players cannot be force-gated the same way, so crossplay consistency is only partial.

Common Mistakes and Expert Tips

• Linking to a download page instead of the file. The client needs the raw ZIP. Test in incognito and confirm a download begins.
• Forgetting the SHA-1 hash. Without it, clients may reuse a stale cached pack and players report “it did not update”.
• Burying pack.mcmeta in a subfolder. The manifest and assets must be at the ZIP root, not inside an extra directory.
• Using plain HTTP. Modern clients reject or warn on unencrypted pack URLs. Always use HTTPS.
• Forcing a huge pack. Force the small core, make the big cosmetics optional.
• Ignoring Bedrock. Crossplay players need a separate Bedrock-format pack; Java packs will not load there.
• Never testing a declined prompt. Connect with the pack check unchecked and confirm the optional path still lets you in.

Expert tip: keep a staging pack URL for testing and a production URL for players, so a broken edit never reaches your community. Pair every pack change with a format-number check against the pack format page for your exact server version.

Frequently Asked Questions

Conclusion: Ship Packs Players Actually Accept

Resource packs are the fastest way to make a server feel bespoke, but a pack is only as good as its delivery. Get the format right, host the ZIP on a fast HTTPS CDN with a valid hash, choose forcing or optional based on fairness rather than convenience, and remember that Bedrock needs its own pack through Geyser. Do those things and the purple-and-black blocks, the failed downloads, and the “why does it look different for me” tickets simply stop happening.

Your next step is concrete: open your server.properties, add the resource-pack and resource-pack-sha1 lines from this guide, upload the pack to an object store, and test with a fresh client and a declined prompt. Then review your crossplay path with [A Guide to GeyserMC: Bridging the Gap Between Java and Bedrock] and keep your server software current using [How to Migrate from Spigot to Paper Without Breaking Plugins]. A few careful minutes now saves hours of support later.

Minecraft data packs are the vanilla way to add or change gameplay on a Java server without installing a single plugin. They let you define custom recipes, rewrite loot tables, ship advancements, run scheduled functions, and even shape world generation, all through plain JSON and text files that the game reads straight from the world folder. This guide exists to help server owners, admins, and plugin coders understand how data packs actually work, so you can customize a server safely while keeping it close to vanilla.

We wrote this after building and breaking data packs across several Paper and vanilla server download Java servers, moving them between game versions and watching exactly which folder names, tag names, and format numbers the game accepts. Everything below comes from that hands-on testing: the metadata that decides whether your pack loads at all, the folder layout that decides whether your functions ever run, and the small mistakes that make a pack load silently and then do nothing.

By the end you will be able to build, install, debug, and package a data pack on your own, and you will know when a data pack is the right tool and when a plugin is. If you are brand new to running a Java server, start with our [A Beginner’s Guide to Minecraft Server JARs: Paper, Purpur…] first, then come back here.

What Are Minecraft Data Packs?

A data pack is a folder, or a .zip archive, that lives inside a world and feeds the game structured data. It can add or override functions, tags, recipes, loot tables, advancements, predicates, item modifiers, dimensions, world generation features, and structures. The engine treats the pack exactly like its own built-in data, which is why a well-made pack feels native rather than bolted on.

The key idea to internalize is that data packs change data, not code. They are interpreted by the existing game engine. You are not adding a new Java class or registering a listener; you are describing recipes, rules, and command sequences the engine already knows how to run. That is what makes packs portable and safe, and also what limits them compared to a plugin.

Because data packs are part of the world save, they travel with the world. Copy the world to another machine, run a different server JAR, or open it in singleplayer, and the pack comes along and keeps working as long as the game version matches.

How Data Packs Differ from Plugins and Resource Packs

Plugins are Java code loaded through a server API such as Bukkit, Spigot, Paper, or Purpur. They can react to events, add new commands from scratch, talk to databases, and invent entirely new mechanics. Data packs run inside the vanilla game itself, so they work on any Java server, including vanilla and Realms, with no plugin platform or modloader required. Resource packs are a third thing entirely: they change what players see and hear, meaning textures, sounds, models, and language, and have nothing to do with gameplay logic or rules.

A quick way to remember the difference: data packs change the rules, plugins change the behavior, and resource packs change the appearance. Most healthy servers use a mix of all three, each for the job it does best.

Pack Metadata, pack_format, and Version Compatibility

Every data pack needs a pack.mcmeta file at its root. This small JSON file declares what the pack is and which game versions it supports. If it is missing or malformed, the pack is ignored.

{
  "pack": {
    "pack_format": 48,
    "description": "Example survival data pack"
  }
}

The pack_format number is the game’s data version gate. If that number falls outside the range your Minecraft version accepts, the game marks the pack as incompatible and will not load its data. Since the 1.20.2 update, packs can also declare a range so a single pack works across several versions:

{
  "pack": {
    "pack_format": 41,
    "supported_formats": [41, 48],
    "description": "Example survival data pack"
  }
}

The table below shows a sample of pack_format values for recent Java versions. Treat it as a starting point, not gospel, because Mojang bumps the number whenever the data format changes. Pack format on the Minecraft Wiki keeps the authoritative, always-current list, and the official Data pack page covers every field.

Checking Loaded Packs with /datapack list

Inside the game or server console, the /datapack command is your fastest diagnostic tool. Use /datapack list to see every enabled pack. The output looks roughly like a list containing vanilla and file/mypack, where vanilla is the built-in data and file/mypack is your pack loaded from the world folder. If your pack does not appear at all, it is either in the wrong folder or its pack.mcmeta is broken. You can also toggle packs at runtime with /datapack enable and /datapack disable followed by the pack name.

One important nuance: because packs are world-scoped, a pack loaded for one world is not active for another. New worlds start with only vanilla data unless you copy the pack into each world’s datapacks folder.

The Folder Structure of a Data Pack

Everything meaningful lives under a data folder, organized by namespace. A namespace is a name you choose, using lowercase letters, digits, and underscores. Vanilla data uses the minecraft namespace, so your pack should always use its own unique namespace to avoid overwriting built-in data by accident. A single pack can contain several namespaces if you need to organize large projects.

my_datapack/
  pack.mcmeta
  pack.png
  data/
    mypack/
      functions/
        tick.json
        on_load.mcfunction
      tags/
        function/
          tick.json
          load.json
        item/
        block/
        entity_type/
      recipes/
      loot_tables/
      advancements/
      predicates/
      worldgen/
      dimension/
      structures/

Here is what each folder under your namespace is for:

• functions: the .mcfunction text files that hold batched commands. A .mcfunction runs one command per line with no leading slash.
• tags: JSON files that group other data by type. Function tags drive scheduling, and item, block, and entity_type tags let you target whole families of things at once.
• recipes: crafting, smelting, blasting, smoking, campfire, smithing, and stonecutting recipes that add or replace how items are made.
• loot_tables: drop rules for blocks, entities, chests, fishing, and more. These decide what players actually get.
• advancements: the goals, triggers, and rewards shown in the advancement screen, including custom tabs if you build a root.
• predicates: reusable conditions that reference entity state, location, weather, and more, used inside loot tables and advancements.
• worldgen: biome, feature, configured feature, and placement data for custom terrain decoration.
• dimension and dimension_type: the definitions that create custom dimensions.
• structures: structure definitions that tell the game how to place jigsaw-built structures.

Folder names must match exactly. A folder called functions that you spell funtions, or a file that ends in .json where the engine expects .mcfunction, will be ignored without an error message. If a feature is missing, check spelling before you check logic.

Installing, Loading, and Reloading a Data Pack

Installing a pack is deliberately simple because it is just file placement. Follow these steps on a running Java server:

1. Stop the server, or at least be ready to reload, and locate your world folder. On a default server the world is named world, but Paper and Purpur may use a custom level-name in server.properties.
2. Create a datapacks folder inside that world folder if it does not already exist.
3. Drop your pack in as either an unzipped folder or a .zip file. Both work. A folder is easier to edit on the fly.
4. Start the server, or type /reload, so the game reads the new pack.
5. Run /datapack list to confirm the pack shows up, then test one recipe or function to verify the data loaded.

Troubleshooting a Pack That Will Not Load

• Pack missing from /datapack list: wrong folder, wrong world, or invalid JSON in pack.mcmeta. Validate your JSON before blaming the server.
• Pack listed but marked incompatible: pack_format is out of range for your game version. Update the number and reload.
• Functions do nothing: wrong namespace inside a tag file. Tags reference functions as namespace:path, and an empty or wrong namespace matches nothing.
• Changes not visible: /reload refreshes data packs, but some changes need a full restart, and world generation changes only apply to newly generated chunks.
• Recipes fail to craft: ingredient IDs or the result format changed between versions. In 1.20.5 and later the result uses id instead of item.

Remember that /reload reloads data packs and the function stack, not plugins. On a mixed server, keep that boundary in mind so you debug the right layer.

Functions, Tags, and Scheduling

Functions are the workhorse of data packs. A Function is a text file with the .mcfunction extension that contains one command per line, no leading slash. You can reference another function from inside a function, and the engine runs them in order. This turns a pile of commands into a reusable script you can call from anywhere, including other functions, advancements, and tags.

Functions run in the order they appear, and each line is treated as a console command. That means you can build small systems: give players effects, teleport them, reward them with items, or run conditional logic using execute commands.

The tick.json and load.json Tag Functions

Two special tag files give functions a sense of time. Both live under data/<namespace>/tags/function/.

• load.json runs its listed functions once when the pack loads or the server reloads. It is perfect for setting up scoreboard objectives, teams, and initial state.
• tick.json runs its listed functions every game tick, twenty times per second. It is how packs implement clocks, timers, and per-tick logic.

data/mypack/tags/function/load.json
{
  "values": [
    "mypack:on_load"
  ]
}

data/mypack/tags/function/tick.json
{
  "values": [
    "mypack:clock"
  ]
}

A word of caution: anything in tick.json runs twenty times a second forever. Keep tick functions tiny, and move heavy work behind scoreboard timers so you only run it when needed. A common pattern is a single clock function that increments a scoreboard value and triggers heavier logic every N ticks.

Scoreboards and Schedules as Timers

Scoreboard objectives make excellent timers. Create a dummy objective, increment it each tick, and use execute if score to fire an action at a chosen interval. You can also use the schedule command to run a function once after a delay, or repeatedly with schedule … clear and replace. Between tick tags, scoreboard counters, and the schedule command, you can build everything from boss bar countdowns to automated events without a single plugin.

Tags in Depth

Tags are a foundational feature of data packs and the reason many systems scale. A Tag is a JSON file that lists a set of values of one type. Vanilla itself is built on tags, and your pack can add to them. The main kinds you will touch are:

• item tags: used in recipes, in the /clear and /give commands, and in many vanilla mechanics that treat groups of items the same way.
• block tags: used by tools, by ore and wood detection, and to make a custom block family behave like a known one.
• entity_type tags: group mobs so commands and mechanics treat them as one category, such as all undead or all raid participants.
• function tags: drive scheduling through load.json and tick.json and let you call a whole set of functions by one name.

The power of tags is that other data references the tag name, not the individual items. Add one item to your tag, and every recipe, loot table, and command that uses that tag suddenly includes it. That is how you make additions that feel native instead of long lists of duplicated entries. To extend a vanilla tag, use the “replace”: false flag so your values are merged with the built-in ones.

Practical Use Cases for Data Packs

Data packs shine in the space between a purely vanilla server and a fully plugin-driven one. The following are the features we reach for most often, and each maps cleanly to a folder from the structure above.

• Custom recipes: add a new crafting recipe, tweak smelting outputs, or create smithing upgrades. Great for progression tweaks and quality-of-life crafts.
• Custom advancements: build a progression tree with triggers, hidden goals, and item or experience rewards, all shown in the advancement screen.
• Loot table tweaks: change drop rates, add rare drops to specific mobs, or reshape what comes out of dungeon and structure chests.
• Worldgen and structure tweaks: adjust biome decoration, add configured features, and shape how structures are placed.
• Cross-version behavior: because packs are data, a well-structured pack can span several versions, though you must verify pack_format and any result-format changes each update.

For world generation in particular, packing a data pack together with [How to Pre-Generate Your Minecraft World with Chunky] is a strong combination: you shape the terrain with data, then pre-generate the chunks so players never wait for them.

Hands-On Walkthrough: A Custom Recipe and a Load Function

Let us build a tiny but complete pack. It adds one crafting recipe and prints a welcome message whenever the pack loads. Create a folder named intro_datapack inside world/datapacks, then add these files.

First, the metadata:

intro_datapack/pack.mcmeta
{
  "pack": {
    "pack_format": 48,
    "description": "Intro pack"
  }
}

Next, a shaped recipe that turns eight paper and one diamond into an enchanted book. Note that on 1.20.5 and later the result uses an id field:

intro_datapack/data/intro/recipes/paper_codex.json
{
  "type": "minecraft:crafting_shaped",
  "category": "misc",
  "pattern": ["PPP", "PDP", "PPP"],
  "key": {
    "P": { "item": "minecraft:paper" },
    "D": { "item": "minecraft:diamond" }
  },
  "result": { "id": "minecraft:enchanted_book", "count": 1 }
}

Then the load function and the tag that runs it:

intro_datapack/data/intro/functions/on_load.mcfunction
tellraw @a {"text":"Intro pack loaded. Happy crafting!","color":"gold"}

intro_datapack/data/intro/tags/function/load.json
{
  "values": [
    "intro:on_load"
  ]
}

Save everything, restart the server or run /reload, then check /datapack list and try crafting the book. If both work, you have built, installed, and validated a complete data pack. From here you can add more recipes, more functions, and more tags following the same rhythm.

Performance, Packaging, and When to Prefer a Plugin

Data packs are lightweight because they are data the engine already knows how to consume, but they are not free. Every function listed in tick.json runs twenty times per second, and a single expensive command on that path can hurt a busy server. The rules of thumb we use in production are straightforward:

• Keep tick functions minimal and gate heavy work behind scoreboard timers.
• Prefer tags over long duplicated lists so the engine can resolve groups efficiently and you avoid bloat.
• Avoid running broad selectors like @e with no filters on a per-tick path.
• Split large packs into multiple namespaces and files so you can disable one feature without touching the rest.
• Validate JSON and test on a copy of the world before deploying to production.

For packaging, ship a folder while you are developing and a .zip when you distribute. Include a pack.png for a clean icon and always keep the pack.mcmeta at the root of the archive, not buried one level deep. That single detail trips up more first-time pack authors than any other.

Data Pack Pros and Cons

• Pros: works on every Java server, including vanilla and Realms; no Java knowledge required; ships with the world; reloads live with /reload; safe and portable; free and open format.
• Cons: cannot add new Java events or true code logic; limited to what the engine already supports; version-sensitive pack_format changes; no support for database or external service integration; complex systems can get unwieldy compared to a plugin.

So when should you choose a plugin instead? If you need custom event handling, a new command implemented in code, database storage, cross-server messaging, or mechanics the engine simply does not express as data, reach for a plugin. On Paper and Purpur you get a mature plugin API, and if you are moving from Spigot it is worth reading [How to Migrate from Spigot to Paper Without Breaking Plugins] so you do not break what you already run. For lighter scripting-style gameplay, a tool like [Minecraft Scripting Guide: Unique Gamification with Skript] can split the difference between data packs and full plugins.

A practical pattern many communities adopt is to start with a data pack, prove the feature, and only graduate to a plugin when a real limitation appears. That keeps your long-term maintenance surface small. The Paper documentation is the best place to check what a plugin API can and cannot do.

Common Mistakes and Expert Tips

Almost every broken data pack we debugged came down to one of these. Save yourself the afternoon.

• Forgetting /reload after editing. The game will happily run your old data until you reload or restart. This single habit prevents most “my change did nothing” reports.
• Wrong pack_format. A stale number silently disables the whole pack. Bump it when you update the server version.
• Mismatched namespace in tags. Tag entries must read namespace:path. A path with no namespace, or the wrong one, matches nothing and fails quietly.
• Overwriting vanilla data. Always use your own namespace and merge tags with “replace”: false instead of replacing the minecraft namespace.
• Result format drift. The 1.20.5 change to id-based results broke countless older recipes. Check the Recipe page for the format your version expects.
• Tick functions doing too much. Running heavy logic in tick.json twenty times a second is the number one cause of lag from data packs. Move it behind a timer.

Expert tips: validate every JSON file with a linter before installing, keep a development copy of the world so you never test on live data, and document each function with a comment line using the hash prefix so future you understands what it does. If you maintain a large pack, generate boilerplate with Misode’s data pack generators to avoid hand-writing structures that must be exact.

Frequently Asked Questions

Conclusion: Start Small, Then Scale

Data packs are the fastest, safest way to customize a vanilla Java server. They install as plain files, reload live, travel with your world, and require no Java to ship a real feature. Once you understand pack.mcmeta, the data/<namespace>/ layout, functions, and tags, you can build custom recipes, advancements, loot, and worldgen that feel like part of the game.

Our advice is to start with one small pack. Add a recipe, wire up a load function, confirm it with /datapack list, and only then expand. When a feature genuinely needs code, database access, or event handling, move to a plugin and follow a clean migration path like our [How to Migrate from Spigot to Paper Without Breaking Plugins] walkthrough. If you are still choosing your server software, the [A Beginner’s Guide to Minecraft Server JARs: Paper, Purpur…] will help you pick a stable base first.

Ready to customize your world? Open your world folder, create a datapacks directory, drop in a pack.mcmeta and your first .mcfunction, and run /reload. That first successful reload is the moment data packs click, and from there your server becomes yours to shape.

If you run more than one Minecraft server, you have probably hit the same wall: players need to move between worlds, minigames, and lobbies without ever typing a new IP address. A proxy sits in front of your backend servers and turns a messy cluster into one seamless network. The two names that come up again and again are Velocity and BungeeCord. This guide exists to help you choose between them with confidence, whether you are launching your first network or migrating a busy one that already has hundreds of players online.

This article is written for server owners, network administrators, plugin developers, and staff who need a straight answer instead of forum hearsay. We built it from hands-on testing across both proxies, real deployment notes, and a close reading of the official Velocity documentation, the BungeeCord wiki, and both projects’ source code. Where the two disagree, we say so plainly.

By the end you will understand what a proxy does, how the two architectures differ under load, why modern player-info forwarding matters for security, how the plugin ecosystems compare, and exactly when to pick each one. If you are still deciding how to host the whole stack, our comparison of Pterodactyl vs Multicraft pairs well with this guide.

What a Minecraft Proxy Actually Does

A proxy is a single entry point that accepts player connections and then hands each player off to the correct backend server. Instead of publishing five different addresses for your lobby, survival world, creative plot world, and minigames, you publish one. The proxy keeps its own connection to every backend, mirrors the player list, and switches players between servers in milliseconds. To the player it feels like one giant world; to you it is a fleet of independent servers you can restart, scale, and update separately.

The proxy is also where the clever parts of a network live. It handles forced hosts, so a domain like play.example.com can route different subdomains to different lobbies. It manages tab list and scoreboard merging across servers, runs the login handshake, and often applies global chat or punishment plugins. Because every connection passes through it, the proxy is the natural chokepoint for rate limits, authentication, and whitelist logic.

• One address, many servers: players join once and travel freely.
• Central control: global chat, permissions, and bans apply everywhere.
• Independent scaling: crash one backend and the rest of the network survives.
• Forced hosts and routing: send players to a lobby based on the domain they used.

Velocity vs BungeeCord: Architecture and Performance

Architecture: How the Two Differ

BungeeCord is the original, battle-tested proxy written by md_5 and maintained under the SpigotMC umbrella. It has years of production history and an enormous plugin library. It also carries legacy design decisions from an era when Minecraft’s networking was far less flexible. Velocity, built by PaperMC, was written from scratch with modern networking, asynchronous packet handling, and a focus on performance and correctness. Its source lives on GitHub, as does BungeeCord’s.

The practical differences show up in three places: concurrency, compression, and the plugin API. Velocity processes packets asynchronously and uses a more efficient internal representation, so it tends to hold lower CPU per player, especially with hundreds of connections and heavy player-list traffic. BungeeCord does more work on a smaller set of threads, which is usually fine for small and medium networks but becomes a bottleneck at scale. Velocity also ships with native compression tuning and a cleaner, type-safe plugin API that encourages third-party code to behave correctly.

• Concurrency: Velocity handles packets asynchronously; BungeeCord is more synchronous.
• Compression: Velocity exposes native compression level and threshold control.
• API: Velocity’s API is modern and type-safe; BungeeCord’s is older but familiar.
• Maintenance: Both are actively maintained, but Velocity moves faster on modern protocol features.

Performance in Practice

On identical hardware and the same backend servers, Velocity generally wins on raw throughput. In our testing with a few hundred simulated players joining, switching, and disconnecting, Velocity used noticeably less CPU for the same player count and recovered faster during login bursts. BungeeCord was never unstable, but it needed more headroom once the player list and chat traffic grew. The gap widens the more you stress connection churn, because that is exactly where async handling pays off.

One caveat: a proxy is rarely your bottleneck. If your worlds lag, the cause is usually the backend servers, disk I/O, or a misconfigured GC, not the proxy. Velocity buys you margin and headroom, not a fix for a badly tuned backend. Our guide on containerizing your Minecraft server with Docker is a good place to standardize how those backends are deployed.

Player Info Forwarding: Modern vs Legacy

When a player joins your proxy, the proxy knows their real UUID, username, and skin. The backend server does not, unless the proxy forwards that information. How that forwarding works is the single most important configuration decision you will make, and it has direct security consequences.

Legacy forwarding injects the player’s identity into the handshake packet as a plain-text field. It is simple and works with almost anything, but it has a fatal flaw: any client can craft a handshake that claims to be a network operator or another player. This means a backend server using legacy forwarding and running in offline mode is trivially impersonatable unless it is firewalled so that only the proxy can reach it.

Modern forwarding solves this with a shared secret. The proxy and backend share a secret key; the proxy signs the player data and the backend verifies the signature before trusting it. Velocity calls this player-info-forwarding and it is the recommended default. A forged handshake from anywhere except the proxy fails verification. This is why the community repeatedly tells people to set online-mode correctly on the backend and never expose it directly.

# server.properties on each backend
online-mode=false
# velocity.toml on the proxy
[advanced]
  forwarding-secret = "a-long-random-string"

• Never trust legacy forwarding on a publicly reachable backend.
• Set backends to offline mode and block direct access with a firewall.
• Use a long, random forwarding secret and rotate it if it leaks.
• Keep the proxy itself in online mode so Mojang sessions verify real players.

Plugin Ecosystems: BungeeCord vs Velocity

BungeeCord’s biggest advantage is history. Thousands of plugins were written for it, from chat managers and anti-bot tools to lobby and punishment systems. If your network depends on an old, unmaintained BungeeCord plugin, switching proxies is not trivial. Velocity’s ecosystem is smaller but growing quickly, and most actively developed network plugins now ship Velocity builds. Many popular paid and free plugins now offer both.

Where Velocity lacks a native port, there is a compatibility bridge. The Velocity/BungeeCord compatibility plugin lets many BungeeCord plugins run on Velocity by translating the older API calls. It is a useful migration tool, but treat it as a bridge and not a destination. For anything performance-critical or security-sensitive, prefer a native Velocity build. For cross-platform networks, remember that Bedrock players route through GeyserMC, and you should check GeyserMC guidance on proxy support before committing. If you run a mixed Java/Bedrock network, our crossplay scaling guide covers the extra moving parts.

Velocity vs BungeeCord: Side-by-Side Comparison

Setting Up or Migrating to Velocity

If you are starting fresh, Velocity is the sensible default. Migration from BungeeCord is straightforward if you plan it. The outline below covers both.

1. Back up every backend server and your current proxy configuration.
2. Download the latest Velocity build from the official source and place it in a clean directory.
3. Run it once to generate velocity.toml and forwarding.secret, then stop it.
4. Set each backend to offline mode and add it to the servers section of velocity.toml.
5. Enable modern player-info-forwarding and copy the same secret to every backend.
6. Install a native Velocity variant of each BungeeCord plugin where one exists; otherwise add the compatibility plugin.
7. Firewall every backend so only the proxy can reach its port.
8. Point your DNS and forced hosts at the proxy, then test with a staging account before opening the doors.

Give yourself a maintenance window. Cut over during low traffic, keep the old BungeeCord setup intact until you are sure, and watch the proxy console and your backend logs together during the first hour. Networking details like DNS, tunneling, and port exposure are covered in our port forwarding and tunnels guide.

Security Hardening Checklist

• Keep the proxy in online-mode so Mojang verifies real sessions.
• Set backends to offline-mode and never expose them to the internet.
• Firewall backend ports so only the proxy’s IP can connect.
• Use a long random forwarding secret shared between proxy and backends.
• Enable proxy-level rate limiting to blunt bot floods and connection spam.
• Lock down the proxy console and restrict who can issue remote commands.
• Keep everything updated; proxy exploits are rare but devastating when they land.

When to Choose Each

Choose Velocity When

• You are building a new network and want the modern, supported path.
• You expect to scale past a few hundred concurrent players.
• Your plugins have native Velocity builds or viable alternatives.
• You care about security defaults and modern forwarding out of the box.

Choose BungeeCord When

• You depend on legacy plugins that have no Velocity equivalent.
• Your network is small and stable and you value zero migration effort.
• Your team already knows BungeeCord config and you need it working today.

In short, Velocity is the stronger technical choice for most new deployments. BungeeCord remains a valid choice when legacy compatibility outweighs performance and modernization.

Common Mistakes and Expert Tips

Most proxy problems come from a handful of recurring errors. Avoid these and your network will be stable from day one.

• Exposing backends to the internet. If your survival server is directly reachable, players can join it and bypass the proxy, including its permissions, rate limits, and whitelist.
• Mixing online-mode states. Proxy online-mode with offline-mode backends is correct; getting it backwards breaks UUIDs and lets impersonation in.
• Using legacy forwarding by default. Modern signed forwarding exists precisely to stop forged identities. Turn it on.
• Ignoring the forwarding secret. A short or reused secret weakens the whole trust chain. Use a long random value.
• Porting every plugin blindly. Some BungeeCord plugins behave badly under the compatibility layer. Test each one.
• Forgetting fallback behavior. If a backend dies mid-session, players need somewhere to land. A fallback server keeps them in the network instead of kicking them out.

Frequently Asked Questions

Conclusion

Velocity and BungeeCord both solve the same problem: one address, many servers. Velocity is the modern, faster, more secure default, while BungeeCord stays relevant for legacy plugin compatibility. The right answer depends on your plugins, your scale, and your appetite for migration. If you are starting now, run Velocity with modern forwarding and a firewalled backend fleet; if you are running a stable legacy network, keep BungeeCord and plan a test migration before you commit. Whichever you choose, configure forwarding, firewalls, and fallbacks carefully, and your players get the seamless network they expect. Ready to build? Pick your proxy, lock down those backend ports, and launch your first test network this week.

Moving a live Minecraft server from Spigot to Paper is one of the highest-return upgrades a Java edition owner can make, and it is also one of the easiest to get wrong. This guide exists to help you do it safely: keep your players online, keep your plugins working, and keep a clear path back if something misbehaves. Whether you run a ten-player SMP or a network pushing hundreds of concurrent users, the same careful process applies.

This article is written for server owners, administrators, plugin developers, and staff who are comfortable editing configs and dropping JARs into a plugins folder but want a battle-tested migration process rather than guesswork. The recommendations below come from running Spigot and Paper builds side by side on staging hardware, profiling both with spark, reading the Paper project documentation, and reviewing how plugin compatibility actually breaks in practice.

By the end you will know exactly why Paper is worth the move, how to back up and stage the change, which plugins are risky and why, how configs and worlds carry over, how to verify performance after the switch, and how to roll back in minutes if you need to. If you are brand new to server JARs in general, read our [Beginner’s Guide to Minecraft Server JARs] first, then come back here for the migration specifics.

Why Paper Is Worth Leaving Spigot For

Paper is a high-performance, open-source fork of Spigot that has been the de facto standard for Java servers for years. It is not a different game and it is not a different plugin platform; it is a drop-in server JAR that keeps the Bukkit and Spigot plugin APIs intact while fixing thousands of issues and optimizing the hot paths that Spigot leaves alone. You can read the full feature list and usage guidance in the Paper documentation and grab current builds from papermc.io/downloads.

The three reasons that matter most during a migration are performance, bug fixes, and an actively maintained API.

• Performance: Paper reduces entity ticking cost, optimizes chunk loading and saving, and adds async chunk handling. On busy worlds these wins translate into lower tick times and more headroom before you hit the tick budget.
• Bug fixes: Paper patches long-standing vanilla and Spigot exploits, duplication bugs, and crash vectors. Many of these fixes never land in Spigot, which often lags behind on non-security patches.
• Updated API: Paper tracks new Minecraft versions quickly and extends the Bukkit API with modern events and helpers. Plugin developers increasingly target Paper-first features, so staying on Spigot means slowly losing access to updates.

Because the source is public, you can verify exactly what changes before you commit. The Paper GitHub repository publishes every patch, and each release notes the upstream Minecraft version it is built against. That transparency is part of why so many production networks standardize on it.

Before You Touch Anything: Backup and Staging Plan

A migration without a backup is not a migration, it is a gamble. Do this work on a copy of your server, never on the live instance, until the very final cutover. The goal is a fully tested Paper server that behaves identically to your Spigot server, ready to swap in during a maintenance window.

Step 1: Take a Full, Verifiable Backup

• Stop the server cleanly and let it finish saving before you copy anything.
• Archive the entire server directory: JAR, plugins with their configs and data, world folders, server.properties, and any custom scripts.
• Keep one off-site copy. An archive on the same disk is not a backup.
• Record your current Spigot build number and your exact plugin list with versions, so you can reproduce the baseline.

Step 2: Stand Up a Staging Copy

Copy the archive to a separate staging directory or machine and run the existing Spigot server there first. Confirm it starts and behaves normally, so you know the baseline is healthy before you change the JAR. Then, and only then, swap in Paper on the staging copy. This isolates the migration as the single variable you are testing.

Step 3: Know Your Rollback

1. Keep the Spigot JAR and the original plugin versions in a known folder.
2. Snapshot the world folders before the cutover so you can restore them in one move if a plugin corrupts data.
3. Write down the exact stop, swap, and start command sequence so rollback is a copy-paste operation, not improvisation.
4. Announce a maintenance window to players so a rollback is invisible rather than a surprise.

Plugin Compatibility: The Real Risk

The plugin platform does not change when you move to Paper, so the vast majority of plugins built against the Bukkit and Spigot APIs work without modification. Where migrations break is almost always one of three things: plugins that reach into server internals, plugins that are version-locked, and plugins that are simply abandoned. Search the SpigotMC resource directory for each of your plugins and check the last update date and stated compatibility.

NMS, Reflection, and Version-Locked Plugins

NMS means the plugin uses internal Minecraft server classes (net.minecraft.server) instead of the public API. Because those internals change with every Minecraft version and are remapped differently between Spigot and Paper, NMS plugins are the number one cause of migration failures. Reflection-based plugins that fish for internal fields are nearly as fragile. Version-locked plugins explicitly state they support only certain versions and often refuse to load outside that range.

If you depend on an NMS or reflection plugin, check whether a Paper-native build or a modern replacement exists before you migrate. The good news is that most performance and utility plugins now ship Paper-friendly versions, and many features that once required NMS (custom blocks, mob AI tweaks, region handling) are covered by maintained projects.

How to Test Plugin Compatibility Safely

• Start the staging Paper server and read the console for red stack traces and unsupported warnings.
• Run each plugin command and simulate its typical workload, not just its load time.
• Check plugins with databases (permissions, economy, stats) and confirm their data still reads correctly.
• For permissions specifically, validate your setup against a guide like [LuckPerms Guide: Advanced Permissions] to confirm groups, tracks, and inherited nodes behave as expected.

Config and World Migration

Your worlds and most configs carry over directly because Paper reads the same formats Spigot does. Still, a few areas deserve attention.

• Worlds: Copy the world, world_nether, and world_the_end folders intact. Paper upgrades region data on first start; keep the pre-upgrade backup in case you need to revert.
• paper.yml and new configs: Paper adds its own config (paper.yml, later the split config files under config/). It generates defaults on first run. Review performance and anti-exploit settings rather than copying Spigot settings blindly.
• server.properties: Safe to copy as-is, but re-check view-distance and simulation-distance, which Paper can often raise for the same CPU cost.
• Plugin data: Copy each plugin folder, not just the JAR. This preserves ranks, homes, warp points, and economy balances.

Vanilla-Behavior Flags Matter

Paper ships with tweaks enabled by default, and a handful of them change gameplay. If you want maximum parity with vanilla or Spigot behavior, review the settings that affect redstone, mob spawning, and item merging. Turning the aggressive tweaks off gives you Spigot-like behavior while keeping the performance improvements; leaving them on gives you the Paper experience most players now expect. Decide deliberately rather than accepting whatever the defaults happen to be.

The Step-by-Step Switch

1. Complete a rehearsal on staging until login, worlds, and every plugin behave correctly.
2. Announce and open a maintenance window; warn players to log out.
3. Stop the live server cleanly and take a fresh backup of the production world and plugin data.
4. Replace the Spigot JAR with the matching Paper JAR, keeping the Spigot JAR nearby.
5. Start the new server and watch the console for errors, warnings, and deprecation notices.
6. Run smoke tests: log in, teleport, use each plugin command, and check the economy and permissions.
7. Open the server to players and monitor tick times closely for the first few hours.

Keep the cutover boring. If a critical plugin fails on the live server, stop, restore the backed-up world and plugin data, put the Spigot JAR back, and start again. Because you rehearsed, this should take minutes, not hours.

Verifying With spark and Timings

After the switch, measure instead of assuming. Paper recommends spark for profiling, and it is the tool you want in place of the old timings system, which Paper removed. Run a spark profiler during a busy period and read the results.

• Use /spark profiler start, let it collect for a few minutes under load, then /spark profiler stop and inspect the report.
• Look at tick durations: a healthy server stays well under 50 ms per tick (20 TPS). Paper should reduce this versus your Spigot baseline.
• Identify the plugin or system consuming the most time and optimize or replace it.
• Track TPS and MSPT over the first week to confirm the improvement holds as player counts grow.

If you tune your JVM at the same time, align your flags with current best practice. Our [Aikar’s Flags Explained] guide and the [ZGC vs G1GC comparison] cover the collector and flag combinations that pair best with Paper builds.

Compatibility Checklist

Run through this table before you call the migration done. It maps each risk area to what to check and the likely verdict.

Benefits vs Caveats

Paper is the right default for almost every Java server, but an honest look at both sides keeps expectations realistic.

• Benefit – performance: Lower tick times and better scaling under load.
• Benefit – stability and security: Regular bug and exploit fixes Spigot often skips.
• Benefit – active API: Fast support for new Minecraft versions and modern plugin features.
• Benefit – tooling: First-class spark support and clear documentation.
• Caveat – default tweaks: Some Paper defaults change gameplay; review them if you want vanilla parity.
• Caveat – NMS plugins: Internals-based plugins may need replacement or a Paper-native build.
• Caveat – learning curve: New config files and settings take an afternoon to understand.
• Caveat – timing tool changes: The old timings command is gone; you must adopt spark.

Common Mistakes and Expert Tips

Most failed migrations share the same handful of errors. Avoid these and you will have a smooth cutover.

• Migrating on the live server: Always rehearse on a copy. The live instance is for the final, tested swap only.
• Skipping the world backup: Paper upgrades region data on first start. Without a snapshot you cannot cleanly revert.
• Copying only plugin JARs: You lose ranks, warps, and balances. Copy the plugin data folders too.
• Ignoring the console: Silent deprecation warnings become crashes later. Read every startup line.
• Assuming a version-locked plugin is fine: Check its changelog and stated support range explicitly.
• Not profiling afterward: You cannot prove the win or find the next bottleneck without spark data.

Expert tip: run Paper on staging for a full week with a few trusted players before the production cutover. Real player behavior surfaces plugin edge cases that a five-minute smoke test never will. Pair that with reading the release notes for each build so nothing surprises you on switch day.

Frequently Asked Questions

Conclusion: Make the Move the Safe Way

Migrating from Spigot to Paper does not have to be risky. Back up everything, rehearse on a copy, check your NMS and version-locked plugins first, carry over your plugin data, and verify the result with spark. Do that, and the switch becomes a routine upgrade that buys you better performance, stronger security, and an API that keeps pace with Minecraft itself.

Ready to start? Grab the current build from papermc.io/downloads, read the Paper documentation for your version, and set up your staging copy today. If you want to go further, explore Purpur once you are comfortable on Paper – it builds on the same foundation with even more configuration options.

Whether you are looking to start a minecraft server for a small group of friends or launch a massive public minecraft server, your first and most important decision isn’t the name or the map—it’s the server JAR.

In 2026, the Minecraft multiplayer landscape is more diverse than ever. Using the default “Vanilla” server software provided by Mojang is fine for a weekend project, but if you want a low lag minecraft server that supports minecraft server plugins, custom mechanics, and optimized performance, you need to understand the world of server forks.

This article is your definitive Beginner’s Guide to Minecraft Server JARs: Paper, Purpur, and Beyond. We’ll break down the hierarchy of server software, compare the top contenders, and help you choose the perfect engine for your next masterpiece.

What is a Minecraft Server JAR?

A “JAR” file (Java Archive) is essentially the engine of your Minecraft server. When you run a server, this file tells the computer how to handle world generation, entity AI, player movements, and redstone logic.

While the “Vanilla” JAR is the official version, the community has created “forks”—modified versions of the code—designed to fix bugs, improve performance, and add support for APIs. These APIs allow you to run minecraft server plugins (like EssentialsX or WorldEdit) without requiring players to install any mods on their own computers.

The Hierarchy of Server Software

In 2026, the development lineage generally looks like this:

1. Vanilla: The official code. No plugin support, poor optimization.
2. Spigot: The classic foundation. Adds plugin support and basic fixes.
3. Paper: The modern standard. Built on Spigot, it introduces massive performance gains.
4. Purpur: The “power user” choice. Built on Paper, adding hundreds of fun toggles.
5. Folia: The “next-gen” experimental fork. Designed for massive regional multi-threading.

PaperMC: The Industry Standard

For 95% of users looking for best minecraft servers, Paper (PaperMC) is the correct choice. It has become the gold standard for minecraft server hosting because it is incredibly stable and significantly faster than Vanilla or Spigot.

Why Choose Paper?

• Async Chunk Loading: Paper loads world chunks on a separate thread, meaning when a player flies with an Elytra, the whole server doesn’t lag for everyone else.
• Exploit Fixes: It automatically patches hundreds of “headless” exploits, duplication glitches, and lag machines that can ruin a public minecraft server.
• Timings & Spark: Paper comes with built-in profiling tools (like Spark) that show you exactly which plugin or mob farm is causing lag.

Cons of Paper

• Technical Redstone: Some ultra-complex technical redstone contraptions that rely on “unintended” vanilla bugs might break, as Paper prioritizes server stability over “bug-compatibility.”

Purpur: Customization Without Compromise

If Paper is the “Stable Sedan,” Purpur is the “Customized Sports Car.” Purpur is a fork of Paper (meaning it includes every single optimization Paper has) but adds a massive purpur.yml configuration file.

Why Choose Purpur?

• Fun Toggles: Want to ride a Creeper? Want to make Endermen pick up Bedrock? Want to disable the “Infinity” enchantment’s requirement for a single arrow? Purpur lets you toggle these in the config without extra plugins.
• Pufferfish Optimizations: Purpur integrates Pufferfish, an optimization layer specifically designed to handle large amounts of entity AI (like villagers or mob farms) with much lower CPU usage.
• Drop-in Replacement: You can switch from Paper to Purpur simply by swapping the JAR file; your plugins and world will remain identical.

Beyond the Basics: Pufferfish and Folia

For those moving into professional minecraft server hosting for hundreds of players, the “Beyond” category becomes relevant.

Pufferfish

Pufferfish is an “enterprise-grade” fork of Paper. It is designed for servers that struggle with “Entity Tick” lag. If you are running a Skyblock or Factions server where players have massive mob grinders, Pufferfish (or Purpur, which includes it) is a must.

Folia

Folia is the newest revolution in the scene. Traditionally, Minecraft runs on a “Single Thread.” If one area of the world lags, the whole server lags. Folia introduces “Regional Multi-threading.” It splits the world into independent regions that run on different CPU cores.

• Best For: Massive networks with 200+ players in a single world.
• Requirement: It requires specialized plugins and a very high-end CPU. Check out our guide on [CPU vs RAM: What Actually Stops Minecraft Lag in 2026?] to see if your hardware can handle it.

Comparison Table: Which JAR is Right for You?

How to Install Your Chosen JAR

Regardless of which software you choose, the process for how to run a minecraft server with a custom JAR is generally the same.

1. Download the JAR: Visit the official site (e.g., papermc.io or purpurmc.org).
2. Upload to Host: Use your hosting panel’s File Manager or FTP to upload the file to your root directory.
3. Rename/Select: Most minecraft server hosting providers have a dropdown menu to select your JAR. If you are self-hosting, rename the file to server.jar.
4. Launch & EULA: Run the server once, open eula.txt, change eula=false to eula=true, and restart.

Expert Tip: For maximum performance, always use Aikar’s Flags in your startup script. We’ve covered the science behind this in [Aikar’s Flags Explained: The Secret to Perfect Garbage Collection].

Common Mistakes Beginners Make

• Using Vanilla for Public Servers: You will quickly find that without Paper’s optimizations, even 5-10 players can cause “Can’t Keep Up!” errors.
• Over-optimizing Purpur: It is tempting to turn on every “fun” feature in Purpur. However, changing too many vanilla mechanics can confuse your players.
• Ignoring Plugin Compatibility: While Paper runs Spigot plugins perfectly, some older plugins from 2018 may not work on 2026 JARs. Always check for updates on SpigotMC or Hangar.

FAQ: People Also Ask

Conclusion: Start Your Journey

Choosing the right JAR is the foundation of a successful community. If you are just starting, download Paper. It is the most supported, most stable, and most optimized version of Minecraft for the average user. If you find yourself wanting more control and quirky features, make the jump to Purpur.

Ready to take the next step? Now that you have your JAR, it’s time to optimize your hardware. Check out our guide on [The Best Linux Distros for Hosting a Minecraft Server in 2026] to ensure your operating system is as fast as your server software.

For over a decade, the dream of “Pokémon in Minecraft” was synonymous with one name: Pixelmon. It was a total conversion mod that practically replaced the base game. But as we move through 2026, a new titan has emerged from the tall grass. The Rise of Cobblemon: Why Pokémon Mods are Dominating Servers is the biggest story in the multiplayer community today.

Cobblemon has taken the best minecraft servers by storm, offering a “Vanilla+” experience that feels like Pokémon was always meant to be part of the Minecraft ecosystem. Instead of bulky 3D models that clash with the world, Cobblemon uses beautiful, blocky animations that stay true to the game’s aesthetic.

Whether you’re a player looking for a new adventure or an owner wanting to start a minecraft server, understanding the Cobblemon phenomenon is key to staying ahead of the curve in 2026.

1. What is Cobblemon? (The “Vanilla+” Revolution)

Unlike its predecessors, Cobblemon is an open-source Pokémon mod built for the modern age (Fabric and Forge). It focuses on seamless integration. When you see a Snorlax sleeping in a forest, it doesn’t look like a high-poly asset dropped into a low-poly world—it looks like a Minecraft mob.

Why Players are Swapping to Cobblemon:

• Legends Arceus-Style Mechanics: You can physically run away from battles, throw Poké Balls in real-time, and watch your Pokémon roam the world.
• Open Source & Lightweight: It runs significantly smoother than older mods, allowing for a low lag minecraft server experience even with hundreds of Pokémon active.
• Showdown Integration: The battle engine is powered by Pokémon Showdown, ensuring competitive balance and accuracy to the official games.

2. Cobblemon vs. Pixelmon: Which Should You Choose?

If you are planning to start a minecraft server, the choice between these two mods will define your community.

The Verdict: If you want a “Pokémon Simulator” that happens to be in Minecraft, go with Pixelmon. If you want a “Minecraft Adventure” enhanced by Pokémon, Cobblemon is the winner.

3. How Pokémon Mods Dominate the Server Market

The reason these mods are dominating public minecraft servers comes down to the Gameplay Loop. Minecraft is a sandbox, but sandbox games often suffer from “What do I do next?” syndrome.

Pokémon mods solve this by providing:

1. Clear Progression: Catching them all, winning badges, and leveling up.
2. Infinite Collection: Rare “Shiny” variants and “Hidden Abilities” keep players grinding for months.
3. Social Status: Showing off a legendary Rayquaza at spawn is the ultimate “flex” on a public minecraft server.

4. How to Start a Cobblemon Minecraft Server in 2026

Ready to build your own Pokémon empire? Follow this step-by-step blueprint.

Step 1: Secure High-Performance Hosting

Cobblemon is lighter than Pixelmon, but “catching” logic still requires a fast CPU. Look for minecraft server hosting that offers high-performance NVMe drives.

• Internal Link Suggestion: Check our list of [The Best Minecraft Hosting Providers] for servers specifically optimized for Cobblemon modpacks.

Step 2: Choose Your Modpack

Most owners use the “Official Cobblemon Modpack” but add “Sidemods” to enhance the experience.

• Essential Sidemods: Cobblemon Challenge (for NPC battles) and Megabolons (for Mega Evolution support).

Step 3: Configure Your “Brand”

To stand out, you need a professional look.

• Internal Link Suggestion: Read our guide on [Building a “Brand” for Your Server] to create logos and banners that attract Pokémon fans.

Step 4: Implement Anti-Cheat

Competitive Pokémon is no fun if people are using “Auto-Catch” scripts.

• Internal Link Suggestion: Protect your world by reading [Minecraft Server Security: Anti-Cheat and DDoS Protection].

5. Pros & Cons of Running a Pokémon Server

The Pros

• Massive Audience: There is a permanent, global demand for Pokémon servers.
• Easier Monetization: Selling cosmetics (Shiny particles, custom Poké Ball skins) is 100% EULA-compliant.
• Community Driven: Pokémon players are famously loyal and active on Discord.

The Cons

• Nintendo Sensitivity: Always ensure your server is a “community project” and not a “commercial rip-off” to avoid legal eyes. (External Resource: Mojang’s Commercial Guidelines).
• Content Updates: You are reliant on the mod developers to add new generations.

Common Mistakes and Expert Tips

• Mistake: No Pre-Generation. Pokémon spawns require the server to check every block. If you don’t pre-generate your world, your low lag minecraft server will quickly become a “lag-fest” as players fly around looking for Legendaries.
• Expert Tip: Add “Create” Mod. Many of the best minecraft servers combine Cobblemon with the Create mod. This allows players to build automated Poké Ball factories and healing centers, blending technical play with creature collecting.

FAQ: People Also Ask

Conclusion: The Adventure is Just Beginning

The Rise of Cobblemon: Why Pokémon Mods are Dominating Servers isn’t just a trend; it’s a shift in how we play Minecraft. By blending the infinite creativity of the blocky world with the competitive soul of Pokémon, Cobblemon has created an experience that feels fresh even after 15 years of Minecraft.

If you are ready to start a minecraft server, there has never been a better time to tap into the Pokémon niche. The tools are faster, the hosting is better, and the players are waiting.

Find here how you can grow your Coblemon server!