This guide will teach you how to get started developing civ server plugins. In order for you to follow this guide, you must already know how to code in Java. If you don't know Java, you should learn it before attempting to develop plugins in Java.
You will need Java, the Java build tool Maven, the version control tool Git, and a text editor you know how to use.
You should install these things using your package manager (sudo apt-get install for Ubuntu) or download and install them in Windows.
In order to run plugins, you must use a modified version of the Minecraft server called Spigot.
Because Spigot is based on Minecraft, and it is illegal to redistribute Minecraft, you must compile Spigot yourself, using the vanilla Minecraft server and the Build Tools provided by the developers of Spigot.
You should download these build tools into a new directory (we'll call it $BUILD) using this link, or by using this command:
wget https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar -O $BUILD/BuildTools.jar
Now, we need to use the Build Tools to compile Spigot. The Build Tools are very picky about the line ending setting in Git, so we must set it as follows:
git config --global --unset core.autocrlf
Now, to actually build Spigot, run this command inside $BUILD, replacing 1.12 with whichever Minecraft version you are using:
java -Xmx1500M -jar BuildTools.jar --rev 1.12
This will take a while, and produce a lot of output, but will eventually finish building Spigot (as well as CraftBukkit and their respective APIs). It will also install all relevant jars into your local Maven repository automatically. This is what allows you to build plugins based on Spigot and CraftBukkit.
Next, you need make a local Spigot server for testing the plugins you develop.
Make an empty directory for your server (we'll call this $SERVER).
It needs to have three things in it:
- A copy of your spigot jar from
$BUILD/spigot-1.12.jar(or whichever version you used). - A directory called
plugins. This is where you will put your compiled plugins later on. - A file called
eula.txtwith the contentseula=trueto indicate that you agree to the Minecraft EULA.
Now, start the server using java -Xmx1500M -Xms500M -jar spigot-1.12.jar nogui.
This is the same command you will use to start the serer when you want to test your plugins.
The server will start, and once it is finished generating terrain, you can stop it with the stop command.
Now that you have a Minecraft server to work with, you are almost ready to start writing plugins.
Now that you have Spigot in your local Maven repository, you can begin building plugins.
We'll be using CivModCore.
On the Github website, go to the CivModCore repository and click the "Fork" button to create your own working copy (your own fork) of the repository.
On your dev machine, clone your fork (clone means download).
You can put it wherever you want, but I would recommend not putting it in $BUILD or $SERVER to avoid the clutter.
The command should look like this:
git clone https://github.com/<YOUR GITHUB USERNAME HERE>/CivModCore
cd CivModCore
You can see the Java source code of the project is laid out under the src directory.
This is where you should edit files to develop the plugin.
When you want to compile the plugin, (try it now!) use the command mvn clean package.
This will tell Maven (mvn) to compile the plugin into a jar file (package) and clean up the extra junk it normally makes when it compiles things.
If all goes well, it should say "Build Success", and you will find a jar file in the newly created target directory.
To test the plugin, put this jar file in the $SERVER/plugins directory from before, and start the server.
Once you have made some changes, and you want to put your work on your fork on Github, do git add . to add all of your changes to the list of staged ("ready to commit") changes.
Next, do git commit to commit your changes.
It will open a text editor, which you should use to give your commit a descriptive message.
Describe what your changes are and why you made them.
Save and close the file to finish commiting.
To upload your commit to your fork on Github, do git push, and give it your Github credentials.
When you are done developing the plugin, and have fully tested your changes, you are ready to send a pull request to the main repository. To do this, go to your fork on Github, and click the "Compare and Pull Request" button. It will walk you through opening a request for the main repository (my repository) to pull in your changes.
If you plan on doing any serious development, including outside of mineman, you should invest the time to read up on how Git and Github work. It makes much more sense once you do, I promise.
Every plugin that you work on will have some dependencies, which will be listed in the file pom.xml.
If you look in the pom.xml and go to the <dependencies> section, you will find something that looks like this: (Example from CivModCore)
<dependency>
<groupId>org.spigotmc</groupId>
<artifactId>spigot</artifactId>
<version>1.12-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>vg.civcraft.mc.mercury</groupId>
<artifactId>Mercury</artifactId>
<version>1.2.20</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>2.6.2</version>
<scope>compile</scope>
</dependency>
This is simply a list of all the other projects that this plugin requires to be able to build. You already have the first one, since that is in your local Maven repository from the section on Building Spigot. The next dependency is Mercury, which is another civ-series plugin.
- If the
groupIdfor a civ-series plugin looks likecom.github.Username, then it is being fetched using the new Travis/Jitpack build system (see below). - If the
groupIdfor a civ-series plugin looks likevg.civcraft.mc.mercury, then it is being fetched from a traditional build server (see below).
Either way, Maven will automatically get the plugin for you, and you don't have to worry about it.
The last dependency is HikariCP, which is not a civ-series plugin.
Maven will download this dependency from the central Maven repository, so you don't have to worry about it.
Moral of the story: don't worry about dependencies unless something has already gone wrong.
There are two different mechanisms for getting civ-series dependencies. One is to use the Devoted build server. The other is to use the new ad-hoc system based on Travis CI and Jitpack.
This is my new, somewhat experimental build system based on Travis Continuous Integration and Jitpack. This system builds new a new version of every your plugins as soon as they are pushed to the Github repo. It has the advantage of being 100% up-to-date within a few minutes. I recommend reading this wonderfully written guide on how the build system works that definitely wasn't written by me, but it isn't required to understand it in order to use it.
You can recognize when this build system is being used when you have dependencies specifying a Github repo (in this case CivClassic/Mercury) in your pom.xml:
<dependency>
<groupId>com.github.CivClassic</groupId>
<artifactId>Mercury</artifactId>
<version>1.2.20</version>
<scope>provided</scope>
</dependency>
They will also have Jitpack listed as a Maven repository:
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
If a plugin uses the Devoted build server, it will have a section like this in the <repositories> section of the pom.xml:
<repository>
<id>devoted-repo</id>
<url>https://build.devotedmc.com/plugin/repository/everything/</url>
</repository>
This tells Maven to try fetching dependencies it couldn't find anywhere else from the Devoted build server. The Devoted build server is not necessarily up-to-date, however, so I recommend switching to the Travis CI/Jitpack build system detailed above.
When you run your test server, you will probably want to use lots of plugins to make sure everything works together like it will on the actual server. While you could clone and compile all the various plugins yourself, there is an easier way.
- If the plugin you want uses Travis/Jitpack, you can go to its Github release page to get the jar file.
- If the plugin you want is available in the version you want on the Devoted build server, go to its page and download the jar from there.
You can put this jar in your plugins folder, renaming as needed, and it will just work.
If you have questions about any of this, even if you figure it out eventually, please let me know. I'd like this guide to be as helpful as possible, but I simply don't know what would be helpful to include, so please tell me if you know.