Migrating from Paper and Folia

Chunkwake runs ordinary Paper and Folia plugins, reads and writes Anvil worlds both ways and uses the same server.properties. But this is not a one-file replacement: the core is different, some Paper settings are not imported, and NMS plugins must be checked individually.

Copy first. Do not migrate a live server without a backup and a test clone. Chunkwake is early-stage, and the feature matrix is honest about what is not ready.

What carries overCopy Anchor Link

• Anvil worlds. Regular .mca regions, level.dat, player data. Chunkwake reads and writes worlds that vanilla understands, in both directions.
• Plugins. plugins/*.jar, plugin.yml and paper-plugin.yml, Maven libraries:, loader and bootstrapper.
• Events and schedulers. Bukkit/Paper events in Paper order, plus GlobalRegionScheduler, RegionScheduler, AsyncScheduler and EntityScheduler for every plugin.
• server.properties. Supported keys are read from the same file; some world and game settings are stored but not applied yet.
• Commands and permissions. Vanilla command tree, ops.json, console and plugin permissions.

What does not migrate automaticallyCopy Anchor Link

Migration checklistCopy Anchor Link

Tick the completed items. Progress is stored locally in your browser and is not sent anywhere. The items follow the migration order below.

Migration orderCopy Anchor Link

1. Check plugins and featuresCopy Anchor Link

Open the feature matrix and your plugin list. "Partial" and "not started" rows show what is not yet ready for a production server.

Pay special attention to:

• plugins with NMS/CraftBukkit;
• plugins that assume one global thread;
• plugins with their own scheduler and regional assumptions;
• plugins that read Paper config files directly;
• multiworld and custom dimensions.

2. Make a full copyCopy Anchor Link

Stop Paper/Folia and copy the entire server directory, not just the world:

server/
├── world/
├── world_nether/
├── world_the_end/
├── plugins/          # jars and per-plugin data folders
├── server.properties
├── ops.json
├── whitelist.json
├── banned-ips.json
├── banned-players.json
└── config/           # Paper configs: keep them, do not expect an import

You can also take a Chunkwake backup after the first start:

chunkwake backup create --dir /srv/chunkwake
chunkwake backup verify <id> --dir /srv/chunkwake

Backups only run while the server is stopped.

3. Install Chunkwake next to PaperCopy Anchor Link

Do not delete the Paper install. Put Chunkwake in a separate directory and keep the old server in place — that is your rollback plan.

mkdir /srv/chunkwake
chunkwake setup --dir /srv/chunkwake

There is no public release yet: build the binary from source or take a CI artifact.

git clone https://github.com/chunkwake/core.git
cd core
cargo build --release -p chunkwake-server

Plugins need Java 25+. The server finds it through java-path, CHUNKWAKE_JAVA or PATH.

4. Move the worldCopy Anchor Link

Copy the world directories and level.dat into the Chunkwake directory. Names must match level-name in server.properties.

cp -a /srv/paper/world /srv/chunkwake/
cp -a /srv/paper/world_nether /srv/chunkwake/
cp -a /srv/paper/world_the_end /srv/chunkwake/

Chunkwake reads .mca with gzip, zlib, uncompressed and lz4, including external c.X.Z.mcc for large chunks. Writing is compatible with vanilla too.

Never run two servers against the same world directory at the same time.

5. Move pluginsCopy Anchor Link

Copy plugins/ as a whole, including config and database folders. Make sure Java 25+ is available for plugins.

cp -a /srv/paper/plugins /srv/chunkwake/

Plugins with folia-supported: true do not need a special switch: Folia schedulers are available to everyone. Ordinary Paper plugins are not disabled.

6. Move settingsCopy Anchor Link

You can copy server.properties as is, but not every key is applied. Check network, port, MOTD, online-mode, level-name, seed, compression and Java paths:

chunkwake config show --dir /srv/chunkwake
chunkwake config set server-port 25565 --dir /srv/chunkwake
chunkwake doctor --dir /srv/chunkwake

If the server runs behind Velocity, enable modern forwarding only:

online-mode=false
velocity-enabled=true
velocity-secret=<secret from forwarding.secret>

Legacy/BungeeCord forwarding is not supported. The backend port must be reachable only by the proxy.

7. Start and verifyCopy Anchor Link

chunkwake doctor --dir /srv/chunkwake
chunkwake --dir /srv/chunkwake

The first start extracts game data (≈27 MB) and the plugin API (≈37 MB). Later starts are fast.

Check:

• the server is visible in the list and accepts logins;
• worlds, inventories, positions and player data are intact;
• there are no chunk or light load errors;
• core commands and permissions work;
• plugins enabled, events fire, scheduler tasks run;
• PDC, registries, tags and attributes read correctly;
• Velocity login works, if used;
• TPS and MSPT did not regress under your load.

If a plugin crashes, disable it and retry. Do not migrate all plugins to the working environment at once.

8. Keep a way backCopy Anchor Link

Do not delete the Paper install or backups until Chunkwake has run under real load for a few days.

Rollback:

1. Stop Chunkwake with stop.
2. Restore the Paper directory and its server.properties.
3. Start Paper on the same world.
4. If Chunkwake already changed the world, restore the copy taken before migration.

Docker: itzg/minecraft-serverCopy Anchor Link

The itzg/minecraft-server:java25 image can run a custom server with TYPE=CUSTOM, but by default it starts it as a Java jar. Chunkwake is a native binary, so the image needs native mode explicitly:

services:
  chunkwake:
    image: itzg/minecraft-server:java25
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "CUSTOM"
      FAMILY: "NATIVE"
      CUSTOM_SERVER: "/data/chunkwake"
      ENABLE_RCON: "false"
    volumes:
      - ./data:/data

1. Build the Linux binary and put it at ./data/chunkwake.
2. Make it executable: chmod +x data/chunkwake.
3. Run docker compose up -d and follow docker compose logs -f.

CUSTOM_SERVER can also be a URL to the binary itself. Do not point it at a .tar.gz: the image downloads the archive and tries to run it as a file.

Why these settings:

• TYPE=CUSTOM selects the image's custom-server path;
• FAMILY=NATIVE makes start-finalExec run the file directly instead of through java -jar;
• ENABLE_RCON=false disables RCON, which Chunkwake does not implement yet;
• java25 in the image is for plugins; the core itself does not need a JVM;
• EULA=TRUE is required by the image itself.

Caveats:

• FAMILY=NATIVE is the image's internal path for native servers (currently used by Pumpkin). Re-check startup after image updates.
• The file must be readable and executable by the container user (UID 1000).
• The image creates server.properties and eula.txt; Chunkwake reads the supported keys.
• Do not run two servers against the same /data.

Folia: what changesCopy Anchor Link

On Folia, ordinary plugins are disabled unless they declare folia-supported. On Chunkwake:

• GlobalRegionScheduler, RegionScheduler, AsyncScheduler and EntityScheduler are available to everyone;
• ordinary plugins keep working;
• Folia's regional model is not forced on plugins that do not expect it.

Still, code that assumes "one main thread for the whole world" or relies on ordering between regions needs testing.

Performance expectationsCopy Anchor Link

On the project bench, Chunkwake starts in 0.6–0.9 s versus 6.6–11.4 s for vanilla, 20 bots joining gives p95 11–26 ms versus 845–860 ms, and peak memory is 182–236 MiB versus 845–929 MiB. Details and caveats: benchmarks and docs/perf.md.

Speed does not remove the need to verify behaviour: if a plugin sees a different event order, that is a bug, not an optimization.

If something goes wrongCopy Anchor Link

• chunkwake doctor --dir ... — config, port, Java, world integrity.
• logs/latest.log — the main log; logs/chunkwake.<date>.log — daily files.
• chunkwake backup rollback --dir ... — recover after an interrupted restore.
• Issues — include the version, plugin, steps and what vanilla does.