OpenSpace logo

Support » Extending the OpenSpace Extension

Starting from version 2, OpenSpace features a dedicated SmartFoxServer' server-side Java extension which is responsible of a number of tasks in the OpenSpace workflow. In fact the OpenSpace Extension is in charge of loading and caching map files created with the OpenSpace Editor, load map items inventories, send maps and inventories to the clients, receive map changes from users and store them, calculate avatar paths and send them to the clients, etc. Also, the OpenSpace Extension provides some utility methods which make it easier to place Non-Player Characters inside the virtual environments and make them move around.

The OpenSpace Extension must be declared as a Zone-level extension in the SmartFoxServer configuration. Since the application which makes use of OpenSpace probably requires its own server-side logic (for example to handle the users' login process and implement other features external to OpenSpace itself), it is a common scenario that developers need to extend the OpenSpace Extension (sorry for the pun) itself, to add such logic or take advantage of the utility methods mentioned above. The following paragraphs describe how.

Please notice that this manual refers to the OpenSpace version compatible with SmartFoxServer 2X; the instructions for the SmartFoxServer PRO version are available here.

Creating a custom extension

When creating a standard SmartFoxServer extension, developers must extend the SFSExtension class contained in the com.smartfoxserver.v2.extensions package. Each extension accomplishes a number of tasks by implementing the init and destroy methods, and by adding requests and events handlers.

Being a regular extension, the OpenSpace Extension does exactly the same, in particular add its own handler for requests coming from the OpenSpace client and sends back responses which are part of the OpenSpace operations. When it's time for developers to extend the OpenSpace Extension, we have to make sure that the internal OpenSpace logic is safe, to avoid disrupting the proper functioning of the client.

In order to do this, inside the OpenSpace Extension the default init and destroy methods of SFSExtension have been overridden and declared as final, and two new methods with the same names but with an "_" prefix have been created. After completing its own logic execution, the final methods of the OpenSpace Extension call the corresponding "_" methods. Developers should then override the "_" methods to add their own logic (for example to add their own requests and events handlers), just like they would override the default SFSExtension methods during standard extension development.

So, in order to create a custom SmartFoxServer extension which in turn extends the OpenSpace Extension, developers should follow these steps:

  1. create a new project in the preferred development environment, for example Eclipse;
  2. add to the project the following libraries:
    • OpenSpaceExtension.jar, located in the [SFS installation location]/SFS2X/extensions/openSpace/ folder;
    • sfs2x.jar located in the [SFS installation location]/SFS2X/lib/ folder;
  3. create the main custom class, which must extend OpenSpaceExtension;
  4. override the "_" methods which are necessary to add the custom logic;
  5. deploy the custom extension as described below.

The following mockup shows a simple example of custom Java class extending the OpenSpace Extension:

package com.test;

import com.smartfoxserver.openspace.OpenSpaceExtension;

public class CustomOSExtension extends OpenSpaceExtension
{
	public void _init()
	{
		// Handle custom extension initialization
		// (for example add your own requests handler/s)
	}
}
			

Other than the "_" version of the standard extension methods, the OpenSpace Extension features a number of additional public methods, without the "_" prefix:

Please read the OpenSpaceExtension class API reference for:

An example of custom Java class extending the OpenSpace Extension and showing how to use the mentioned utility methods can be downloaded by clicking on this link.

Deploying the custom extension

After the custom extension is created, it is time to deploy it:

  1. compile the custom extension;
  2. create a JAR file containing the compiled classes;
  3. go to the [SFS installation location]/SFS2X/extensions/ folder and create a new folder which will contain all the files required by SmartFoxServer in order to execute the custom extension;
  4. copy the JAR file to the newly created folder; inside it, also create the OpenSpace_server.xml file (see the OpenSpace server-side configuration manual) and the data/ folder which will contain the OpenSpace maps created with the OpenSpace Editor;
  5. copy the OpenSpaceExtension.jar file from the [SFS installation location]/SFS2X/extensions/openSpace/ folder to the custom extension's folder created before (this is mandatory or a class-not-found exception will be thrown when launching SmartFoxServer);
  6. open the SmartFoxServer 2X Administration Tool and go to the Zone Configurator module: edit your application's Zone (or create a new one) and in Zone Extension tab configure the extension details, for example like this:
  7. stop SmartFoxServer if running, and restart it.

Check if no exceptions are thrown when SmartFoxServer is started. If not, your application (and OpenSpace inside it) can now communicate with your custom extension extending the OpenSpace one.