6.1 Introduction to Server Side Extensions

The idea behind a server side extension is very simple: it allows developers to extend the server functionalities allowing them to create all kinds of new features and behaviors.
SmartFoxServer PRO comes with a standard set of features that cover all the basic tasks of a multi user server: handling applications, user connections, room creation and destruction, broadcasting user messages etc..
With these built-in features you can already create a good number of multiplayer applications, but when things get more sophisticated, it is necessary to have new behaviors at hand. Server side extensions are an easy and powerful tool for developers to implement simple to very complex application logic on the server side.

» An Example
If you have already been using SmartFoxServer Lite or Basic you should know the SmartFoxTris example, essentially it is a multiplayer tic-tac-toe game.
Using the server-side variables we can keep the game logic all on the client without worrying of the server side.
Let's say we now want to make it more complex: we'd like to add registered user support with a high score table, user profile and user registration. With the SFS Extensions you can implement all the registration/login/high score handling on the server side pretty easily.

You can connect to your existing database, retrieve and modify user data, save high scores and even send html-formatted confirmation emails!



» How do Extensions work?
Extensions can be written using Java or Actionscript 1.0 (Javascript/ECMA-262).
Using the provided Actionscript framework is the easiest and more productive way of creating your own custom server logic, and these articles will be focused on the Actionscript framework.

Basically an extension consists of a simple .as file (just like you would do in Flash) saved in the sfsExtensions/ folder, which is the root directory for all Actionscript extensions. You can also create your own folder structure starting from the root, to better organize your .as files.

The next step is to tell the server that you have created an extension for a certain Zone or Room (more on this in the next chapters) and activate it, by modifying the config.xml. Below follows an example of the XML used to load an extension.

<Extensions>
	<extension name="myExt" className="myExtension.as" type="script" />
</Extensions>

The name attribute represents the name you will use to "invoke" the extension from the client application, and the className is the Actionscript file to load. Alternatively you can dynamically attach your extensions to dynamic rooms (both regular or game ones) from the client:

	var gameRoom:Object		= new Object()
	gameRoom.name 			= name
	gameRoom.password 		= pwd
	gameRoom.maxUsers 		= 2
	gameRoom.maxSpectators 	= spec
	gameRoom.isGame 		= true
	gameRoom.isTemp 		= true
	
	xt = {}
	xt.name = "tris"
	xt.script = "sfsTris.as"
	gameRoom.extension		= xt
	
	smartfox.createRoom(gameRoom)

The above example is taken from the pro_sfsTris example file, provided with SmartFoxServer PRO, and it shows how simple is to dynamically create a new game room and attach a server side extension to it. If your are familiar with SmartFoxServer Basic you will notice that the only addition in the code is the the new "extension" property.

Now you are ready to start sending requests from your Flash client to the extensions and handle the its responses.

Essentially an extension should take care of two different tasks: responding to client requests and handling internal server events.
Here's an example of a client request:

server.sendXtMessage("myExt", "helloWorld", obj)

The first argument is the name of the extension that we want to call, the second one is the name of the command / request we want the extension to execute, and the last parameter is an object containing data to pass to the server.

In order to handle extension responses on the client you will use the onExtensionResponse event handler:

smartfox.onExtensionResponse = function(resObj:Object, type:String)
{
	var cmd:String = resObj._cmd
	
	if (cmd == "myCommand")
	{
		// Handle the response here
	}
}

All the data sent by the server is held in the resObj object and, as a convention, you will always find a property called "_cmd" which contains the name of the response command sent by the server.

Internal server events are sent by SmartFoxServer to its extensions to notify that something important is happening, for example a new room was created in the Zone where the extension is attached to, or a login request was sent etc...

Finally each extension can be monitored from the AdminTool. They can be restarted and paused while the server is running and you can also debug them remotely using the AdminTool trace window.

» Raw protocols vs XML

One of the most important features of SmartFoxServer Extensions is the possibility to use a raw string-based protocol for messages instead of the standard XML format used by default.
This feature allows client and server to send very small messages, saving a lot of bandwidth which is ideal for real time action-based games. Also you can mix the two formats transparently.
In other words you can send some requests using the default protocol and some others using the raw format. For example in a multiplayer car game you can send all the non time-critical messages using plain XML and use the raw format for quickly updating the car positions, collisions etc...

You will find detailed informations about this feature in the SmartFoxServer PRO tutorials section.



  doc index