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

Sunday, June 17, 2012

Multiple Unity Scenes and Amazon EC2

Hey followers and new viewers. Today, I will review how to develop an overall structure for your Unity project that's networked with Smart Fox Server 2X. I'll also point you towards starting a server that can be accessed over the web.

I've noticed so many subtle features of Smart Fox that aren't explicitly stated in the documentation. That is why it's important for you to examine the code in the examples: found here SFS Unity Connector. When you look in each example's folder, you'll notice that it contains a deploy and source folder. The deploy folder contains the client which has been built to run in a web browser. The source folder typically contains a Unity package; the "First Person Shooter" and "Tris" example also contain a server folder which holds Java files necessary for maintaining the game on an external server. I discussed the Connector and Lobby examples in my last post, so today, I suggest that you tinker with "Object Movement" which is an example of networked game play that is Client to Client.  Create a new project in Unity and load the package by clicking Assets> Import Package> Custom Package. Once it is imported you will have access to all the scripts and assets for the project.

This example uses multiple Unity scenes which is why we're looking at it today. The architecture for this is that the first person to log in becomes the server. The data for all people who join afterwards is maintained by this first person. If your game doesn't require all that much movement, then this would be a decent architecture for you to look into further. For my purposes though, I'm showing this example so that you understand how to manage a smart fox server through multiple scenes and scripts on the client side without having to use any Java files. However, a game like the MMO you are trying to develop will benefit from having a true server / client architecture that uses Java files on an authoritative server. I'll talk about that in another post though.

The SmartFoxConnection script is crucial for maintaining a connection throughout your project. It holds a private static connection; static variables are maintained in memory until an application closes (watch out for making too many in a scene though; even when that scene is closed, the static variables will not be deleted). The first scene you'll open is Login, and you'll notice that there is a Login GUI script in the hierarchy. When it is selected, look in the inspector to see that the server Name is set to (If you are having problems connecting refer to my last post or go ahead and build it for pc/mac which will solve the problem). When you run this program, before you even click to log in, you're client will already be connected to the server. The connection in SmartFoxConnection is then set to the connection in the Login GUI. This is exactly what you want. Now, when you log in,  you will be logged in to the room The Lobby and the scene will close. If SmartFoxConnection had not copied your connection then the new scene would not be connected. It also maintains a fantastic function on lines 34-38 that will automatically disconnect you from the server when the application closes. If it weren't for this line, Unity would crash each time you stop the application. Now, when any script containing a private SmartFox is loaded with a scene, the instance will copy the static connection that is maintained by your SmartFoxConnection script.

It's important to follow a structure like this because it streamlines the execution of your game. Once you're connected to the server and subsequently logged in to a specific room, you can close the script that has all of those event listeners for the login process. This will make it so that all you need to focus on in the game scripts are the variables and messages that need to be transferred among all the users. You will be able to send public messages to everyone else in your room. You should also automatically send a public message to users in a room once you have logged in and loaded it. This way everyone will know that you've joined. Now take some steps on your own to read all of these scripts and see how they interconnect. If you don't work hard to see how they all work together, then you won't succeed at copying the important parts to your own project and manipulating it to suit your needs.

So that about covers how to manage the connection for all of your scripts in a project. Now, I will point out some of the basics of getting the server running on Amazon. Go to Amazon web services, and you will find that they even have a free plan for 1 year. Be wary though because this plan is intended to be used mostly for testing purposes and could cost you money if you go over the limits. But basically, you need to get the server and then instantiate a Virtual Machine on it. Amazon has several Virtual Machines to choose from which enable you to remotely control a computer. We went with Windows Server 2008 RC2. Install Smart Fox on it and follow the instructions at the bottom of this page Server Installation. If you're using Amazon EC2 to host SFS2X be sure to open the TCP & UDP ports in the Security Group settings in the EC2 control panel. Also, make absolutely certain that you edit the firewall settings as suggested in the Getting Started documentation linked above or it will not let you access it from other computers. Once you start the service, you can copy the URL (excluding http://) and paste it into Server Name in your project's Unity Inspector. You can even control it using the sfs admin tool as per usual with localhost:8080 in the browser on your Virtual Machine. Great try it out with a friend with the Lobby example and you'll both be able to chat with one another.

Thank you for reading. Please comment below with any suggestions, thoughts, or insights. Follow me at  and join my circles on Google+

Have a more in depth question? Use the forums at or drop me a line at

Friday, June 15, 2012

Starting the Server: smart fox lobby example

I'm developing a game that will be played online. It uses Unity as the game engine, and the networking portion is done with smart fox server 2x. Be kind on the parts where I am vague. I am trying to not let on as to what I'm actually building, but I want to create a little tutorial to coincide with the smart fox documentation as well as monitor my progress in this blog. This is my first post, and I've already done a good portion of the programming. As the need becomes apparent, I will explain things I have done already.

So the first thing you'll need to do is download and install the latest version of Unity. Then go to to download and install the free smart fox server 2x community edition. We have chosen to develop our Unity scripts in C#. Some of these scripts also act as client code which connects to the smart fox server. Now as it stands, we have started to use a free Amazon server, but it's not fully functional yet. I've read that we should have Right Scale to do it, but we would rather install and manage the server ourselves if possible.

When reading the smart fox documentation, you really have to know exactly what you are looking for. I would suggest reading most of the basics first (you will be rereading most of the documentation multiple times). Then, download the Unity examples and attempt to run them... you'll probably not understand at all what to do on your first go: I didn't. But after a little experimentation, I started to understand what is happening. Most of the examples have a login scene with a connector script. I'd suggest starting with the Lobby example. Now in the Unity inspector you can select which server ip address you want to connect to. You actually have to manage this ip address in the inspector and NOT in the script itself. The serverName is declared as a public variable in the script. This means that when it's value is set in the inspector, it overrides the value that is present in the script. The default is which known to most network programmers as "local host." If you and a friend want to connect to each other, then one computer will be the server, and one computer will be the client. The server computer will connect to the local host. If you're using windows then go to the start menu and type cmd. When it opens a dos window, type ipconfig. Scroll and look for your ip v4 address. Otherwise check out This is the address that your friend will type into serverName in their login scene in Unity. Make sure the host computer has started the smart fox service. You can check by going to your web browser and entering the url localhost:8080 and opening the smart fox admin tool. The default user name and password is sfsadmin.

Now, there is a good chance that your program will throw an error message and not connect to the server. This is an error anytime you have to load a config.xml file. It won't do this in the Unity Editor or a web browser. Essentially, the way it works in the browser it won't fetch the file. Check here for more info Go to your build settings and instead of running the project in the Unity Editor, set it to build for the pc/mac. Build and run it, and you should see that it's connected to the server. In a later post I will figure out a workaround so that you can hard code these settings into the project and thus enable it to run in both the editor and browser. So from here, you should both be connected to the same server and be able to chat with one another. Great!

Please comment with any suggestions, thoughts, or insights. Have a more in depth question? Use the forums at and check out my personal website at