Saturday, June 23, 2012

Planning an Extension with Java Server API

In this article I'll describe how to begin making your own server extensions and hint at connecting to a database. If you haven't been reading about this on the Smart Fox website, then I suggest reviewing the information at to gain a basic understanding of why and how to start. The overview is that a .jar file is created by compiling a java project from an IDE (Integrated Development Environment) such as Eclipse. You'll link the SFS2X and SFS2X-core files which contain a lot of classes that you can use in your extension. This includes the User and Room classes which you can extend with extra features and functions.

Smart Fox's Java Server API is thorough, but this detailed documentation will be more useful when you are trying to learn how to use a specific piece of code. If you've read my prior posts, then you've already downloaded the examples which are a great place to start learning how to write an extension: the Tris and FPS examples. Each of these have the .java files that were used to create a server side extension to run the games. By looking at the code, you can start to understand the layout that you will need for your specific use.

So, at this point, you're probably overwhelmed by how much you need to learn to write even a basic extension... let alone an entire game. Well, that's why you're keeping up with my blog right?  The first question is "what kind of experience are you trying to create for the user". If you'd like to make a game where people can come together and play board games, then the Tris example is a great place to start. Otherwise, if you want to make a game that has character movement in a collaborative or competitive environment, then the place to start is the server code of the First Person Shooter example. Honestly though, it is a good idea to look at the Tris code first because there are fewer files to pore over. Read the code and each time it refers to another file, look there and understand how the files relate to one another.

Here are a few points of advice. Both projects have a .java file with the same name as the extension. This file is like a wrapper for all of the code. It has a reference to most of the other files which in turn reference others. There are also event listeners created here. A RequestListener responds to messages that are sent from the user's scripts (the scripts in Unity). An EventHandler responds to events within the server. Each file in the handlers package contains all the responses to an event listener of the same name.  The FPS example is split into multiple packages, and this is to help you understand which files are closely related.

The Simulation folder holds all the classes that tend to resemble in-game objects. This includes, the world class which contains a list of all the players and objects in the world. The Combat Player class holds all the information of a combatant such as a function to return a transform (location of a player) and functions that respond to event handlers. The files in the helper folder help the extension interact with Smart Fox's User and Room classes. I could go deeper into this but SFS has plenty of documentation on the project; I'm trying to show you how this is all wrapped up into a .jar file that extends the server's ability to monitor this game world and all of its intricacies.

The next step after reading documentation and looking at files is to think of what you need for your game. If you have Microsoft Visio or any other visual layout program then draw a rectangle for each class that you think you need. Add to this class a name and several attributes that you think it needs. Even if you don't manage to follow this exact structure, it's the perfect way to wrap your mind around everything that you are going to need to make your extension. Without this, you won't be able to extract all the important information from the classes. I've had to leave out quite a bit of the code, but that has been easier to discern since I understood what I needed in my code. I tend to remove all the lines that refer to bullets firing because my game doesn't have guns. So sometimes I copy all the contents of a class or function except for a few lines, and I have to rename the variables according to something meaningful for what I am creating.

I'll elaborate on this post when I've finished up my extension. For now I'll tell you this. I'm using the extension to monitor a lot of people in a game world. So, the important things for me are to have a room which monitors the location and animation of the registered players inside. How though, can you allow only players who have registered? This is done with a database that you can also link to your server. You can learn more about server extensions and database connections here:

~Helpful tip
Sometimes, when you add a room extension, the server might not restart because your extension is not built properly. If this happens, you can manually open up the xml at [~installation]\SmartFoxServer2X\SFS2X\zones\yourZoneName.xml. Whether it's a zone or room extenstion, between <extension> and </extension>, delete the contents between <name></name> & <file> </file> to  reset your extension.

As always, feel free to comment here or send me a message by going to

No comments:

Post a Comment