=================== 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. .. only:: html .. contents:: :depth: 2 :local: .. 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. #. 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 :doc:`this `. #. Start the Sponge server, the migrator will be loaded automatically. #. 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). #. 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 :doc:`configuration/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. #. 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: .. code-block:: none [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 | server.properties | | _.cfg | | +----------------------------+----------------------------+ | _.cfg | global.conf | | | /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. #. Download SpongeForge from the Sponge website and Forge from MinecraftForge. #. Place ``SpongeForge.jar`` into your ``mods`` folder. #. 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. #. Download SpongeVanilla and the vanilla server from Mojang. #. Place your worlds and config files in the server folder. #. 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 flavours 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 #. Download SpongeVanilla or SpongeForge. #. Place your worlds and config files in the server folder. #. Run your new server. Installing Sponge ================= The guides at :doc:`implementations/spongeforge` and :doc:`implementations/spongevanilla` provide instructions for installing Sponge while you're migrating.