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 PRO; the instructions for the SmartFoxServer 2X version are available here.

Creating a custom extension

When creating a standard SmartFoxServer extension, developers must extend the AbstractExtension class contained in the it.gotoandplay.smartfoxserver.extensions package. Each extension accomplishes four main tasks by implementing the following main methods:

Being a regular extension, the OpenSpace Extension does exactly the same, in particular handles 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 AbstractExtension methods have been overridden and declared as final, and a new set of methods with the same names but with an "_" prefix was 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, just like they would override the default AbstractExtension 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]/Server/openSpace/ folder;
    • jysfs.jar and json.jar, located in the [SFS installation location]/Server/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 it.gotoandplay.smartfoxserver.data.User;
import com.smartfoxserver.openspace.OpenSpaceExtension;

public class CustomOSExtension extends OpenSpaceExtension
{
	public void _init()
	{
		// Handle custom extension initialization
	}
	
	public void _handleRequest(String cmd, org.json.JSONObject data, User fromUser, int fromRoom)
	{
		try
		{
			// Handle client requests
		}
		catch (Exception e)
		{
			// Handle exceptions
		}
	}
}
			

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. copy the compiled class(es), including their package folders, to the [SFS installation location]/Server/openSpace/ folder;
  3. using a text editor, open the start.sh (Mac OS X/Linux systems) or start.bat (Windows systems) file located in the Server/ folder;
  4. at the end of the list of JAR files, just before the closing double quotes, append the following:
    • Mac OS X/Linux » :openSpace/ (including the colon)
    • Windows » ;openSpace/ (including the semicolon)
  5. if you run SmartFoxServer as a service, open the wrapper.conf file located in the Server/conf/ folder and the following entry at the bottom of the wrapper.java.classpath... list:
    • wrapper.java.classpath.XX=openSpace/ where XX is a progressive number with respect to the previous list entry;
  6. in the Zone definition corresponding to your application in the SmartFoxServer configuration, associate the custom extension to the Zone by means of the <extension> tag; for example:
    <extension name="__$OpenSpace$__" className="com.test.CustomOSExtension" type="java"/>
  7. set the OpenSpace component's IOpenSpace.xtName property accordingly to the name attribute of the <extension> tag, if changed;
  8. 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.