Examples (iOS)
Examples (Android)

 

» Writing the first Extension

Extensions are a fundamental element in SmartFoxServer 2X, they open a world of limitless possibilities for developers to create their custom game logic and integrate other technologies to support their project. To draw a parallel we could think of Extensions as the equivalent of server-side code for web pages, where all the "business" logic is developed.

Provided that you have an intermediate understanding of Java or any other object-oriented language (ActionScript 3, C#, C++, etc), it will be very easy to get started writing you first Extension.

» Use an IDE to assist the development

First thing first we need an IDE that will help us writing the code, compiling it and creating a binary package (a jar file) that we will deploy in SFS2X.

There are several well known Java IDEs available, both free and commercial. We usually recommend:

In this tutorial we will be using Eclipse, however setting up a new project in another IDE should be a very similar process, especially if the IDE you use is the one you are most familiar with.

» Setting up a new project

Let's start Eclipse and from the File menu choose New > Project... Choose Java Project from the Java folder and click the Next button.

step1

In the new window we give the project a name, for example MyJavaExtension, and proceed to the next screen.

step2

Now it is time to add the libraries that are needed to compile our Extension. Click on Libraries tab, then on the Add External JARs... button and browse your file system to your {sfs-install-dir}/SFS2X/lib/ folder.
Select two files: sfs2x-core.jar and sfs2x.jar and click Finish in the main window.

step3

The new project will appear in the Package Explorer panel which by default is located in the top left column of your interface. Now you can create a new Java class by right-clicking on the src folder and selecting New > Class from the menu.

step4

Here we proceed by entering the name of the class, for example MyExtension, and its package which in this case will be my.test. Please notice that using the Extension suffix in the class name is highly recommended, because it will make it easier to assign it to the server's Zone or Room in the AdminTool (see the additional note on the Type parameter of the Zone Extension tab or Room Extension tab in the Zone Configurator module documentation).

step5

Finally we have created our main Extension class; we can now proceed adding some very basic code like the following picture shows.

step6

In this article we are not going to dive into the details of server side logic coding. After you've finished this tutorial you can watch a short Youtube video on how to write a simple Extension and you can consult more advanced articles on the same topic:

» Deploying the Extension

The deployment follows a simple set of rules. Every extension must reside in a folder under the {sfs-install-dir}/SFS2X/extensions/ folder. The name you choose for this folder will determine the Extension name that is shown in the AdminTool when you activate the Extension.

Let's say we create a folder called MyFirstExtension under extensions/. Under this path we can deploy the jar file containing our server code classes and any other jar file that might contain other dependencies required in our Extension.

IMPORTANT NOTE
The name of the main Extension jar file must end with the word Extension, for example MyExtension.jar. This is important because the AdminTool will only show the classes contained in the jar files which use this convention. For more informations see the additional note on theUse naming convention setting of the Zone Extension tab or Room Extension tab in the Zone Configurator module documentation).

In Eclipse the compiled classes are usually stored in the bin/ folder, which sits next to the src/ folder in your project. You can export the compiled code in a jar file directly to the SFS2X deployment folder by following the next steps.

In the Package Explorer right-click the project folder and choose Export.... In the next dialogue box open the Java folder and choose JAR file, then click the Next button. A new window will open, click the Browse...button in the middle of it and navigate to the SFS2X deployment folder (as we explained,) specifying a name for the jar file to be created (remember the naming convention described above).

jar-make

Click Next to advance to the next screen. Here you can store the export settings so that the next time you need to re-deploy your Extension it can be done in a snap, by simply clicking a file in your project folder.

Activate the check box next to the Save the description... and click Browse....You will be presented a list with all your Java projects, select your own and provide a name for the export configuration; click Ok to close the panel and click Finish to complete the process.

make-jar2

At this point you will have deployed your jar file in the SFS2X Extension folder and also saved the export configuration for future re-deployments.

SFS2X can actively monitor all the Extension folders for changes and as soon as it detects an updated jar file it will restart your Extension. This is valid for all Zone-level Extensions, while it cannot be done for Roo-level Extensions.

In order to toggle this feature you need to launch the Server Configurator in the AdminTool and turn on the Extension file monitor option.

» Assigning an Extension to a Zone or Room

The most simple way to plug our Extension to a Zone or Room is via the AdminTool. Launch the Zone Configurator, select a Zone and enter the edit mode. You will find the Zone Extension tab where you can configure a few parameters. Essentially all you need is to select the Extension name and the main Extension class (the one extending SFSExtension).

ext-deploy

Now you can save, restart the server and the Extension will be activated. The same can be done for Room Extensions: simply access the Room Extension tab in the Room configuration panel of the Zone Configurator panel.

» Python Extensions

We should also quickly mention that it is possible to write Python scripts and run them as Extensions, although this is not recommended for production. The reason is that interpreted Python code is not able to deliver the performance obtained with pure Java code and we suggest its usage only for rapidly building prototypes, proof-of-concepts, test cases, etc.

The process to build a Python extension is almost identical to what we have already described, but with a few small differences.

» What's next

Now that you have gained the basic understanding of how to create an Extension, it is time to learn more about the features offered by the server-side framework. Make sure to continue the learning process by following the links we recommended in the early stages of this document.