Migrating to Sponge

The purpose of the articles within this section is to help current server owners to migrate from other server platforms to Sponge.

Warning

Please backup your server files before migrating. In case something goes wrong, you still have your backups!

Migrating to Sponge

To migrate to SpongeForge or SpongeVanilla, look at the sections below. Most instructions are identical for both, differences are stated below.

Migrating from CraftBukkit or Spigot

Note

Spigot is a modified fork of CraftBukkit.

Worlds

Forge, and thus SpongeForge (and also SpongeVanilla), use the same world structure as vanilla Minecraft. Vanilla Minecraft places the nether (typically world_nether) and the end (typically world_the_end) dimensions within the world folder. However, Bukkit and Spigot don’t use this system to save the worlds, thus migration is needed.

SpongeForge and SpongeVanilla provide a fully automated conversion script which converts your worlds for you. This is how it works:

  1. Shutdown your Bukkit or Spigot server and Backup the entire folder.
  2. Install SpongeForge or SpongeVanilla in the folder where you ran your old server, remove the Bukkit or Spigot jars. If you’re unsure how you’re supposed to install SpongeForge or SpongeVanilla properly, read this.
  3. Start the Sponge server, the migrator will be loaded automatically.
  4. The Migrator will look into the bukkit.yml for a config key called world-container and will search that folder for worlds to transfer. If that file isn’t around (or something caused it to fail to read), then the migrator will use the root folder of the server (which is CraftBukkit standard).
  5. Now the migration is performed. At this point, worlds are copied over from what we call the world container into the folder defined in the server.properties file via the level-name key. Note that the original files in the world container remain unchanged, a copy is made during migration.
  6. Bukkit puts things in weird places (with weird names), thus two important fixes have to be applied. Keep in mind that these fixes are based on assumptions (due to Bukkit’s structure).
    • The first fix is to rename any folder whose name starts with level-name property and ends with a Vanilla dimension name (_nether/_the_end) to DIM-1 and DIM1 respectively.
    • The second fix is to migrate up the region data within a Bukkit Vanilla nether/the_end. Bukkit puts this data into DIM-1\region and DIM1\region respectively whereas Vanilla/Forge expect region to be in the root of the world’s folder structure.

The migrator can’t provide all needed configuration values. This is the reason why you need to change several parameters by hand to make the world work properly upon loading it on SpongeForge or SpongeVanilla. It is strongly advised to use a World Management Plugin to set the right parameters and actually load the world.

Note

As already pointed out, we have to deal with several assumptions while migrating your world. Thus Sponge does not load the world directly, you need to install a plugin to handle this.

The output generated by the migration tool should look like this, if everything went fine:

[17:32:29] [Server thread/INFO] [Sponge]: Checking for worlds that need to be migrated...
[17:32:29] [Server thread/INFO] [Sponge]: Migrating [world_lol] from [.].
[17:32:29] [Server thread/INFO] [Sponge]: Migrated world [world_lol] from [.] to [.\world\world_lol]
[17:32:29] [Server thread/INFO] [Sponge]: Migrating [world_nether] from [.].
[17:32:29] [Server thread/INFO] [Sponge]: Migrated world [world_nether] from [.] to [.\world\DIM-1]
[17:32:29] [Server thread/INFO] [Sponge]: Migrating [world_the_end] from [.].
[17:32:29] [Server thread/INFO] [Sponge]: Migrated world [world_the_end] from [.] to [.\world\DIM1]
[17:32:29] [Server thread/INFO] [Sponge]: [3] worlds have been migrated back to Vanilla's format.

When this is complete, you should have a copy of the world(s) in a structure that Sponge can load. The original world files remain untouched in their original location, in case something went wrong.

Server and World Configuration Files

CraftBukkit and Sponge both share files that are made available by vanilla Minecraft. These files can thus be reused on Sponge, if they are already present in your CraftBukkit installation:

  • server.properties
  • banned-ips.json
  • banned-players.json
  • ops.json
  • usercache.json
  • whitelist.json

The following files are used by CraftBukkit only, and can be removed because Sponge does not use them:

  • bukkit.yml
  • commands.yml
  • help.yml
  • permissions.yml

Users who are migrating from Spigot may wish to compare spigot.yml to global.conf in Sponge. Some keys in spigot.yml have counterparts in global.conf, and it may be desirable to copy over the values of any keys that are present in both files.

Plugins

Sponge has no native support for Bukkit plugins. However, some members of the community are re-implementing the Bukkit API within a special Sponge plugin, which may allow Bukkit plugins to function on a Sponge server. This plugin has not yet been slated for release.

Ore is Sponge’s official repository for finding plugins, and it is recommended to download all Sponge plugins from Ore. When finding replacements for your Bukkit plugins, there are a few points to keep in mind:

  • Not all Bukkit developers have chosen to port their plugins to Sponge. Over time, however, someone else may create a suitable replacement.
  • Not all Sponge plugins that are ported from Bukkit will automatically convert configuration files. Individual plugin developers make the decision on whether or not to automatically convert configuration files.
  • Some Sponge plugins that are ported from Bukkit may change in functionality, or may not even use the same configuration structure.

Migrating from Canary

Worlds

Forge, and thus SpongeForge (and also SpongeVanilla), use the same world structure as vanilla Minecraft. Vanilla Minecraft places the nether (typically world_nether) and the end (typically world_the_end) dimensions within the world folder.

Canary relocates the nether and end dimensions outside of the world folder, which must be remedied if it is desired to retain the nether and end dimensions when running Sponge. However, Canary provides an easy method to convert Canary worlds to a structure usable by Sponge with the /makevanilla command. If the world conversion is successful, the output will be placed in the vanilla folder.

Server and World Configuration Files

Sponge uses many files that are made available by vanilla Minecraft, such as server.properties. Canary, however, does not; the only file it has in common with vanilla Minecraft is usercache.json. Thus, usercache.json is the only file from Canary that can be reused on Sponge.

Nevertheless, it is possible to manually migrate some Canary configuration files to their Sponge counterparts, which have been provided below.

Canary file(s) Sponge counterpart(s)
server.cfg <world>_<dimension>.cfg server.properties
<world>_<dimension>.cfg global.conf <dimension>/dimension.conf
ops.cfg ops.json
db.cfg No counterpart
motd.txt No counterpart

Plugins

SpongeVanilla and SpongeForge have no native support for Canary plugins. It may be possible to re-implement the Canary API in a special Sponge plugin.

Ore is Sponge’s official repository for finding plugins, and it is recommended to download all Sponge plugins from Ore. When finding replacements for your Canary plugins, there are a few points to keep in mind:

  • Not all Canary developers have chosen to port their plugins to Sponge. Over time, however, someone else may create a suitable replacement.
  • Not all Sponge plugins that are ported from Canary will automatically convert configuration files. Individual plugin developers make the decision on whether or not to automatically convert configuration files.
  • Some Sponge plugins that are ported from Canary may change in functionality, or may not even use the same configuration structure.

Migrating from Forge

Migrating from a plain Forge server to a SpongeForge or SpongeVanilla server is a fairly simple process that needs little-to-no preparatory work.

Migrating to SpongeForge

You must first ensure you are running a version of Forge that is compatible with the version of SpongeForge your plan to use. You may find recommended builds of Forge at Forge Downloads. If you are using any other mods, they must also be updated.

When you are ready to install SpongeForge, you may proceed with the following steps:

  1. Stop your Forge server if it is running.
  2. Download SpongeForge from the Sponge website and Forge from MinecraftForge.
  3. Place SpongeForge.jar into your mods folder.
  4. Start the server and party!

Note

If SpongeForge is the only mod on your server, players will be able to log in with a vanilla client. Other mods may require players to install Forge on their own computers.

Migration to SpongeVanilla

Warning

If migrating to SpongeVanilla: You will lose all Forge mod data, blocks and entities as SpongeVanilla can’t run Forge mods. Keep that in mind when deciding whether you go with SpongeForge or SpongeVanilla.

The process of migration is almost the same as above:

  1. Stop your Forge server if it is still running.
  2. Download SpongeVanilla and the vanilla server from Mojang.
  3. Place your worlds and config files in the server folder.
  4. Run the server by launching the spongevanilla.jar.

Migrating from Vanilla

Administrators of vanilla Minecraft servers can migrate to Sponge easily because Forge, and thus SpongeForge (and SpongeVanilla), use the same world structure as vanilla Minecraft. Sponge also uses the same files used by vanilla Minecraft, such as server.properties.

At first you should decide if you want to run SpongeForge or SpongeVanilla.

Note

Both flavors of Sponge are able to serve vanilla clients. Keep in mind that this only applies to SpongeForge as long as you don’t install Forge mods which require client modifications.

  1. Stop your Vanilla server if it is still running
  2. Download SpongeVanilla or SpongeForge.
  3. Place your worlds and config files in the server folder.
  4. Run your new server.

Installing Sponge

The guides at Installing SpongeForge and Installing SpongeVanilla provide instructions for installing Sponge while you’re migrating.