The first step to modifying Minecraft with the Bukkit API is to install a multiplayer server on your Windows PC. A multiplayer server is essentially the same as the single-player Minecraft server, but it allows for more customization and is not limited to the people in your home network. Spigot is a modified version of a Minecraft server, which will be used to load the plugins that you create. A plugin is a piece of software that hooks or plugs into another piece of software. The code that you will develop in this book will be in the form of plugins. These plugins will hook into the Minecraft code and change how Minecraft operates. We will set up a Spigot server and use it to test the plugins that you will write. By the end of this chapter, all of your friends will be able to log on to your modified Minecraft server and play together. By working through the following segments of this chapter, we will deploy a Spigot server, which will be modified in the later chapters:
An introduction to Spigot
Installing a Spigot server
Understanding and modifying the server's settings
Using the console and in-game Minecraft and Bukkit server commands
Port forwarding
As you set up your own server and begin to create plugins, you will encounter a few terms that may be new to you. The terms are Vanilla, Bukkit, CraftBukkit, and Spigot.
Vanilla refers to the normal Minecraft game developed by Mojang/Microsoft. The Vanilla Server is the official version of the game. It can be downloaded from minecraft.net and is typically named minecraft_server.jar
or minecraft_server.exe
. The vanilla server currently does not support any sort of mods or plugins. This is where Bukkit comes in.
Bukkit is an API that helps us to develop plugins. We will discuss this in detail in Chapter 2, Learning the Bukkit API. Until then, it is sufficient to know that when you hear the phrase bukkit plugins, it is referring to the plugins that are built against the Bukkit API.
The Bukkit API was originally developed by the CraftBukkit team. This brings us to the next term. CraftBukkit is a modified Minecraft server that replaces the vanilla server. CraftBukkit and vanilla Minecraft provide us with essentially the same game. The difference is that CraftBukkit has the ability to load Bukkit plugins and execute the code within the game. CraftBukkit translates the Bukkit methods and variables into Minecraft code, which was developed by Mojang. CraftBukkit also includes additional code to aid plugin developers with completing certain tasks, such as saving/loading data, listening for server events, and scheduling the code that needs to be executed. We will not mention CraftBukkit much in this book, because it has been replaced with a project named Spigot.
Spigot completely replaces the vanilla Minecraft server, just as CraftBukkit does. Spigot was built on top of the CraftBukkit project. Therefore, they share a lot of the same code. However, Spigot is more configurable via its settings; in many ways, it is much faster. The Spigot team now maintains all three of the projects, namely Bukkit, CraftBukkit, and Spigot. You will be able to use either CraftBukkit or Spigot to run a server, since the Spigot team has been kind enough to provide us with both. I recommend running the Spigot server for the reasons mentioned earlier.
We will start from scratch to set up this new server. If you wish to use a preexisting world, you will be able to do so after creating a new Spigot server. To start, let's create a new empty folder named Bukkit Server
. We will run the Spigot server from this newly created folder.
The main file that you will need to start a new server is spigot.jar
. A JAR file is an executable Java file. Minecraft, Spigot, and every plugin that we will create are all written in Java and therefore are run from a JAR
file. The Spigot team updates the spigot.jar
file as Mojang releases new versions of Minecraft. Typically, when connecting to a Minecraft server, you must be playing on the same version. In case you are unsure of your Minecraft version, it is displayed in the bottom-left corner of the Minecraft client. A client is the program that you use to play Minecraft, as shown in the following screenshot:
You can choose the version of Minecraft that you want to play by creating a new profile in the Minecraft launcher, as shown in the following screenshot:
For legal reasons, the Spigot team is not allowed to let you download spigot.jar
. However, it does provide you with tools and instructions so that you can build the JAR
file yourself. The Spigot team continues to improve this process by providing the latest instructions as well as a troubleshooting guide at https://www.spigotmc.org/threads/buildtools-updates-information.42865/. This chapter includes simplified instructions on how to obtain the needed JAR
file. However, in case you run into problems while building these jar
files, refer to the instructions provided on spigotmc.org.
You will need Git for Windows in order to run the build tools. You can download it from http://msysgit.github.io/. When installing Git for Windows, the default installation settings will be fine. You will also need to download the build tools JAR
file, which can be found at https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar. Create a new folder to place BuildTools.jar
in. Name this folder Spigot Build Tools
. Also create a new text file within the same folder. Name this text file update.txt
. Open the text
file and write the following line of code in it:
"<java bin path>\java.exe" -jar BuildTools.jar
<java bin path>
should be replaced with the location of the Java installation. The java path depends on the version of Java that you have on your computer. Look for the Java
folder inside the Program Files
or Program Files (x86)
directory. The Program Files
directory can be found at the root of the main hard drive, which is typically C:\
. If you do not see the Java folder, then you will have to install Java. You can download it at https://java.com/download/.
Once you are in the Java
folder, you will see one or more java installation folders, such as jre7
or jre8
. Open the installation folder. In case you see more than one, open the one with the higher version number. Within the java installation folder, open the bin
directory. Here you should see java.exe
, though it may be displayed as simply java. Copy the path from the top of the explorer window; this is the java bin path, as shown in the following screenshot:
If you have Java 8, then the line of code in the update file will be similar to the following code:
"C:\Program Files (x86)\Java\jre1.8.0_45\bin\java.exe" -jar BuildTools.jar
Tip
On most PCs, you can reference the java variable in place of the java.exe path. Therefore the line of code in the update file will be as follows: java -jar BuildTools.jar
Save the file and then rename it from update.txt
to update.sh
. If you don't see the .txt
extension on the file, then you will have to adjust your folder options by performing the following steps:
Open the View tab to the upper left
Select Folder and search options
Uncheck Hide extensions for known file types
Click on OK
Now, you can rename update.txt
to update.sh
. Run update.sh
by double-clicking on it. This will execute the build tools, downloading all the code and applying changes until it is up to date. It will take several minutes to complete. Once it's complete, you will have spigot.jar
, craftbukkit.jar
, and bukkit.jar
. The two server jars, namely spigot and craftbukkit, will be found in the Spigot Build Tools
directory, where you placed BuildTools.jar
. The bukkit.jar file
is located in the Bukkit/target
directory in the same folder. Each file will have a version number appended to it, such as spigot-1.8.8.jar
and bukkit-1.8.8-R0.1-SNAPSHOT.jar
. Note the location of these files, as you will need them within this chapter as well as throughout the book.
Copy the spigot.jar
file and place it in the Bukkit Server
folder that was created by you at the beginning of this segment. For simplicity, we will remove the version number and rename the file spigot.jar
.
Now, we will create a batch file that we can double-click on every time we wish to start the server. In a new text document, type the following two lines:
java -Xms1024M -Xmx1024M -jar spigot.jar PAUSE
1024
tells how much of the computer's RAM the server will be allowed to use. You can change this number if you want the server to use more or less RAM. spigot.jar
is the name of the spigot.jar
file. This must match the name of your file. We renamed the file to exclude the version number so that we will not need to edit this batch file every time we update the Spigot server to the latest version. java
indicates that we are using Java to run the server. In case the server does not start during the following step, you may need to replace java
with the full java path that you copied earlier. The rest of the code in the batch file should not concern you, and it should remain unchanged.
Save the text document as Start Server.bat
and ensure that it is in the same folder as that of spigot.jar
. Now, you will be able to run the server. Double-click on the batch file that you just created. It will open the command prompt and start creating server files. It will look like the following screenshot and should display the Minecraft server version that you are using:
If you do not see the Starting minecraft server message, then there may be something wrong with the batch file. If a window similar to what's shown in the previous screenshot does not appear, then make sure that the batch file is named Start Server.bat
and not Start Server.bat.txt
. When you first start the server, you will see a few warnings. Most of them shouldn't worry you as they are expected. However, you may see a message that explains that you need to agree to the EULA in order to run the server. If you look in the Bukkit Server
folder, you will now see a new file named eula.txt
. Open this file, set eula=true
, and save it to agree to the terms, which are outlined by Mojang at https://account.mojang.com/documents/minecraft_eula. Once you do so, you can start the server again. This time, you will see the server loading and generating a new world.
You will see the server folder populated with several files and folders. The purpose of some of these are explained in this section, but most of the files should not concern you at present:
plugins
: This folder is where you will place all the Bukkit plugins that you wish to use on the server.world
: The folders that begin withworld
, such asworld
,world_nether
, and so on, include all the information for the new world of the server. If you already have a Minecraft world that you wish to use, then replace these new folders with the old world folders. Do not attempt to do this while the server is running as it will cause problems.server.properties
: This file holds several options that allow you to change how a Minecraft server operates. You can open it with a text editor. There are many settings, and most of them are pretty self-explanatory. I will go over a few settings in the following list that you may want to modify. For a full list of property explanations, you can visit www.minecraftwiki.net/wiki/Server.properties. Changing any of these settings will require you to restart the server.pvp=true
: Thepvp
property can be set to aboolean
value. PvP (short for Player versus Player) determines whether players can attack and harm each other. You will want to set this totrue
orfalse
, depending on whether you want PvP to be on or off respectively.difficulty=1
: The difficulty property can be set to a number from0
to3
, where0
means Peaceful,1
means Easy,2
means Normal, and3
means Hard. Everyone on the server will play at this difficulty level.gamemode=0
: This property determines which game mode players will start in, where0
means Survival,1
means Creative, and2
means Adventure.motd=A Minecraft Server
: MOTD (short for Message Of The Day. This message will be displayed when viewing your server in the Minecraft multiplayer server list, as shown in the following screenshot. It is a good idea to set this to a short description of your server. An example of this isBukkit plugin testing
.online-mode=true
: This can be set tofalse
to allow players to connect to the server when in the offline mode. This is useful in case http://minecraft.net/ is unavailable or your computer is not connected to the Internet. Running your server in the offline mode can cause security issues, such as other players logging in to your account.
bukkit.yml
: This file contains many server options. These are the options that a vanilla server does not offer and are only available when you run a modified server. Note that this file is a YMAL (.yml
) file and not a PROPERTIES (.properties
) file. When you open it, you will see how the two file types are formatted differently. The first difference that you will see is that certain lines are indented. You do not need to fully understand the YMAL formatting, as it will be explained further as we progress through creating Bukkit plugins. There are a few settings in this file that I will bring to your attention, as shown in the following list. For a full list of these Bukkit settings, you can visit wiki.bukkit.org/Bukkit.yml. Likeserver.properties
, changing any of these settings will require you to restart the server.allow-end: true
: A vanilla Minecraft server allows you to disable the nether world from functioning. A Bukkit server allows you to disable the end world as well. Set this tofalse
to prevent players from traveling to the end.use-exact-login-location: false
: Vanilla Minecraft contains a feature that will prevent players from spawning inside a block. The player will instead be spawned above the block so that they will not be stuck when they join the server. This can be easily exploited to climb onto blocks that a player could normally not reach. Bukkit can prevent this from occurring by spawning the player exactly where they logged out. Set this property totrue
if you wish to prevent this.spawn-limits
: Bukkit allows a server admin to modify the number of monsters and animals that are allowed to spawn within a given chunk. If you are unfamiliar with the term chunk, it is a group of16 x 16
blocks from bedrock to the highest point of the sky. The following is a picture of a single chunk in Minecraft; if you feel that there are too many (or too few) mobs, then you will want to adjust these values accordingly:ticks-per: autosave: 0
: Unlike vanilla Minecraft, a Bukkit server will not periodically save your player/world data. Automatically saving data may prevent the server from losing the changes that were made in the game in case it crashes or shuts down for some reason, such as the computer losing power. Vanilla has set this to6000
by default. This value is provided in ticks. There are 20 ticks every second. We can determine how long 6,000 ticks is with this math: 6000 ticks / 20 ticks/second = 300 seconds and 300 seconds / 60 seconds/minute = 5 minutes. From this calculation, you should be able to calculate an appropriate time period after which you want your server to autosave your progress. If your server lags whenever it saves your changes, then you may want to increase this number. A setting of72000
will cause a lag only once every hour. However, if the server crashes right before it saves, you may lose any progress that you made in the past hour.
spigot.yml:
This file is similar tobukkit.yml
. It has many settings and configurations that are only available when running a Spigot server. If you wish to configure any of these options, refer to the documentation at the top of the file.
We now have all the custom options set. Next, let's log on to the server and take a look at the in-game server commands.
To log in to your server, you will need to know the IP address of your computer. Later in this chapter, we will work through finding this essential information. However, I will assume that for now, you will be playing Minecraft on the same machine on which you are running your server. In this case, for the IP of the server, simply type localhost
. Once you are connected to the server, you will see that the Spigot server is essentially the same as the vanilla server because you do not have any plugins installed yet. The first indication that the server is running Bukkit is that you will have a few extra commands at your disposal.
Bukkit inherits all the Minecraft server commands. If you have ever played on a Minecraft server, then you have probably already used some of these commands. In case you have not, I will explain some of the useful ones. These commands can be typed into the console or an in-game console. By "console", I am referring to the command prompt that is running your server. Bukkit has a built-in permissions system that limits players from using specific commands.
They cannot use a command if they do not have the necessary permissions. We will discuss this in detail in a later chapter, but for now, we will make your player an operator, or op for short. An operator automatically has all the permissions and will be able to execute all the commands that will be presented. To make yourself an operator, issue the op
command to the console, as follows:
>op <player>
Replace <player>
with your player name. See the highlighted command in the following screenshot for an example:
Once you have been Opped, you are ready to test some of the in-game server commands. In order to understand how to use commands properly, you must understand the command syntax. Let's look at the gamemode
command as an example:
gamemode <0 | 1 | 2 | 3> [player]
< >
indicates that it is a required argument.[ ]
indicates that it is an optional parameter. For this command, if the player parameter is not included, then the game mode of your own player will be set.|
is a known symbol for the word or. So,<0 | 1 | 2 | 3>
indicates that 0, 1, 2, or 3 can be entered. They represent Survival, Creative, Adventure, and Spectator respectively.Parameters must always be typed in the same order in which they are displayed. Usually, if you enter an incorrect command, a help message will appear, reminding you of how to use the command properly.
Note that when you issue an in-game command, you must start with /
, but when issuing a command from the console, /
must be left out. A proper use of the gamemode
command will be /gamemode 1
, which will set your game mode to Creative, as shown in the following screenshot:
Another example of this command is /gamemode 2 Steve
, which will find the player whose username is Steve
and change his game mode to Adventure.
Now that you understand the basic syntax for commands, you can learn how to use some other useful server commands from the following list. Most of these commands are also present in vanilla Minecraft. Only a few of them are specific to Bukkit servers:
gamerule <rule> [true | false]
An example of this is
/gamerule mobGriefing false
.The rule parameter can be set to any of the following:
doMobSpawning
: This determines whether mobs will naturally spawnkeepInventory
: This determines whether players will keep their items if they diemobGriefing
: This determines whether mobs, such as creepers, can destroy blocksdoFireTick
: This determines whether fire should be spreaddoMobLoot
: This determines whether mobs should drop itemsdoDaylightCycle
: This determines whether the day/night cycle is in effect
give <player> <item> [amount [data]]
For example,
/give Codisimus wool 3 14
gives Codisimus 3 red wool.
plugins
(applicable only in Bukkit)For example,
/plugin
s or /pl
displays a list of all the plugins that are installed on the server.
reload
(applicable only in Bukkit)spawnpoint [player] [x y z]
For example,
/spawnpoint
allows you to spawn where you are standing when you die.
stop
For example,
/stop
saves your progress and shuts down the server. This is how you should stop the server to ensure that data is saved. You will lose data if you simply close the command prompt by clicking on X.
tell <player> <message>
For example,
/tell Steve my secret base is behind the waterfall
sends a message that only Steve will be able to see. Note that these messages will also be printed to the console.
time set <day | night>
For example,
/time set day
sets the time of the server to0
(daytime).
toggledownfall
For example,
/toggledownfall
stops or starts rain/snowfall.
tp [player] <targetplayer>
For example,
/tp Steve Codisimus
teleports Steve to the location of Codisimus.
For more information regarding these and other commands, visit minecraft.gamepedia.com/Commands and wiki.bukkit.org/CraftBukkit_commands. The commands and property files mentioned earlier give you a lot of control over how the server functions.
Where's the fun in running your own Minecraft server when no one else can log on to it? I will now explain how to allow your friends to connect to your server so that they can play with you. In order to do this, we must first find your IP address. Just like your place of residence has a street address, your computer has an address on the Internet. This is what your friends will type into their Minecraft client to find your server. To find the IP address, simply search IP
on Google. At the top of the results will be a line that states, "Your public IP address is XX.XX.XXX.XX" (the X signs will be replaced by numbers, and its overall length may be different). You can also visit www.whatismyip.com to find out your IP address.
Once you have your IP address, try using it to connect to your server rather than using localhost
. If you are able to connect, then your friends will be able to do so too. If not, you will have to take additional steps to allow other players to connect to your server. This will be the case if your computer is attached to a router. We must let the router know that it should point other Minecraft players towards your computer, which is running the server. This process is called port forwarding. To do so, we will first need some additional information.
We need to know the IP address of your computer on your local network. This IP address will be different from the address that we obtained earlier. We will also need to know the IP address of your router. To find out this information, open a new command prompt window. The command prompt can be found at the following path:
Start Menu/All Programs/Accessories/Command Prompt
You can also search for cmd.exe
to find it. Once the command prompt is open, type in the following command:
>ipconfig
Then, press the Enter key. A screen will be displayed, which will be similar to the one shown in the following screenshot:
In the previous image, the two IP addresses that you were looking for have been highlighted. The numbers will most likely be very similar to these sample numbers. IPv4 Address is the address of your computer, and Default Gateway is the address of your router. Make a note of both of these IPs.
Next, we will log in to your router. In a web browser, type the IP address of the router, which is 192.168.1.1 in our example. If you do this correctly, then you will be prompted with a login form asking for a username and password. If you do not know this information, you can try to input admin
for both the fields. If this is unsuccessful, you will have to find the default username and password, which can be found in the paperwork that was provided with your router. This information can usually be found online as well by searching for the name of your router along with the term default login.
Once we are logged in to the router, we must find the area that includes the settings for port forwarding. There exist many brands and models of routers in the world, and all of them present this option differently. Therefore, I cannot provide a specific walkthrough of how this page is found. However, you will want to look for a tab that says something that includes the terms Forwarding, Port Forward, or Applications & Gaming. If you do not see any of these, then expand your search by exploring the advanced settings. Once you find the correct page, you will most likely see a table that looks like the following one:
Application Name |
External Port |
Internal Port |
Protocol |
IP Address |
---|---|---|---|---|
Bukkit Server |
25565 |
25565 |
TCP and UDP |
192.168.1.100 |
Fill in the fields, as shown in the previous table. The layout and formatting will of course differ depending on your router, but the important details are that you forward port 25565
to the IP address that you found earlier, which is 192.168.1.100 in our example. Ensure that you save these new settings. If you have done this correctly, then you should now be able to connect to the server by using your public IP address.
You now have a Spigot server running on your PC. You can inform your friends of your IP address so that they can play on your new server with you. In this chapter, you became familiar with in-game commands and how to use them, and your server is ready to have Bukkit plugins installed onto it as soon as we program them. To prepare ourselves for programming these plugins, we will first become familiar with the Bukkit API and how it can be used.