Smartfoxserver 2X HowTos

»smartfoxserver 2X HowTos

In this document, we have gathered some quick tutorials on how to complete the simple and specific tasks that you might need to use the Smartfoxserver 2X process.

How to add a new Java library or extension dependency how to
set up a connection to an external database how to
create an extension-based custom login how to
use Smartfoxbits 2X how to
Check server logs how
to debug an extension
How to schedule a timed task in
an extender how to send e-mail from an extender
more recipes

» How to add a new Java library or extension dependency

It's a breeze to add a new library to Smartfoxserver 2X. Do not confuse classpath: all you need to do is deploy the. jar file in the correct directory and restart the server.

We recommend the use of two folders:

{Sfs2xroot}/lib/
This is what we recommend to add libraries, such as database drivers or other multipurpose libraries that all zones and servers themselves will use. Another example is the custom implementation of the Buddylist storage class.

{Sfs2xroot}/Extensions/_ lib _/
This folder is recommended for libraries that are shared by multiple extenders in the system. such as "Google collections" jar or hibernate jar. Do not add an extension jar to this folder, because Admintool will not be able to detect it when you set up the Zone/room configuration.

Finally, if you have one or more jar files that will be used by a specific extension, you can simply deploy these files in the extension folder, which will look like this: {sfs2xroot}/extensions/{The-extension-name}.

» How to set up a connection to an external database

SFS2X allows you to connect to a database in a way that is very similar to its predecessor. All you need to do is download the JDBC connector from the database vendor (for example, MySQL or MSSQL) and place the. jar in the {sfs2xroot}/lib/folder.

Of course, if you use ODBC instead of JDBC, you can even skip the driver deployment steps. In fact, the ODBC driver is already provided by the Java runtime.

The following is a list of the pages of the JDBC driver that can find the most common RDBMS:

MySQL JDBC Driver for
Microsoft SQL Server JDBC driver
Postgres jdbc driver
Oracle JDBC Driver

The next step is to run sfs2x Admintool, launch the Zone Configurator module, select your zone, and finally click on the Database Manager tab to edit the configuration.

At the end of the process, click Submit and restart the server.

» How to create an extension-based custom login

It is a simple process to implement a custom login on the server side. SFS2X starts the following two logon events.

User_login: Triggered when a client requests to join a zone. Here, you can verify the client credentials and determine whether the user can continue the logon process. At this stage, the client is represented by the session object, not the Sfsuser object.
 User_join_zone: Notifies when a client successfully joins a ZONE (and becomes sfsuser).

In order to add your custom login logic, you should perform at least the following first two steps.
1) Configuration Area

Start Admintool, open the Zone Configurator module and enable zone's use of custom login settings; Then Sestart sfs2x.
2) Server Code

Create a new server-side extension that extends the Sfsextension class. Your init () method should look like this:

@Override public
void init () 
{ 
   trace ("My customlogin extension starts!"); 

   Register for Login Event 
   addEventHandler (Sfseventtype.user_login, Logineventhandler.class); 
}    

Now create the Logineventhandler class, which will be responsible for user name/password checking. In the following example, two specific user names are not allowed to log on.

public class Logineventhandler extends Baseservereventhandler 
{ 
   @Override public
   void Handleserverevent ( Isfsevent event) throws Sfsexception 
   { 
      String name = (string) event.getparameter (sfseventparam.login_name); 

      if (name.equals ("Gonzo") | | | name.equals ("Kermit")) 
      {

        //Create the error code to send to the client  
        sfserrordata errdata = new Sfserrordata (sfserrorcode.login_bad_ USERNAME);
        Errdata.addparameter (name);

        Fire a Login exception
        throw new Sfsloginexception ("Gonzo and Kermit is not allowed in this zone!", errdata); 
  }
   } 
}

If one of the two unwanted names is detected, sfsexception can be triggered. In doing so, we provide a message that is logged on the server side and a Sfserrordata object that contains the error code (SFSERRORCODE.LOGIN_BAD_USERNAME) and the error name itself.

The typical error codes used in this context are sfserrorcode.login_bad_username and Sfserrorcode.login_bad_password, both with an incorrect name or additional parameters for the password.

Now this is a very simple example, it just shows how to deny access to a user named Kermit or Gonzo. Of course, your logic may require more complexity, but you should get the idea. When you need to stop the login process, you simply throw sfsloginexception.

If no exception is thrown, the system accepts the user and continues the logon process.
There are other things that can go wrong at this stage, such as:

The area is full and no more logons are allowed;
Another user with the same name is already logged in;
The user is currently in the Forbidden list;
The user name may contain unacceptable error terms (depending on your custom configuration);
Wait a minute

Once all these checks pass, the user is finally logged into the zone. At this point, if you subscribe to the server code, the server code receives a User_join_zone event.

The final step is optional and is not required in many cases.
Typically, you will use this feature when you need to perform a specific action when a user logs on to the system, such as setting user variables, automatically joining a room, and so on.

TIP
When using asynchronous events such as User_login and User_join_zone, it is much more difficult to maintain the state of the current transaction/operation.
A convenient way to maintain state is to use the user session object. In particular, session objects allow custom parameters to be stored as key-value pairs (see Javadoc, Method Getproperty/setproperty, etc.).
3) Security Password

For security reasons, the user password is never transferred from the client to the server. In order to be able to compare the encrypted password with your database's original password, we provide a convenient method in the API.

Getapi (). Checksecurepassword (Session, Clearpass, Encryptedpass);

If the password matches, the method call returns True, otherwise false is returned.

On the client side, there is absolutely no difference between "standard" logins and "custom". All you need to do is add a listener for the Sfsevent.login event to receive the server response and send loginrequest to log in to the zone.

You can view the AS3 documentation and samples for all the details on how to do this. For other languages, the process is the same. Another interesting reading related to this topic is the discussion of user rights.
4) change user name at login

In some cases, you need to change the user-supplied name at logon and fetch another name from the database. An example is when a user logs in using an e-mail address as a login, but stores his nickname in the database and should use it instead of e-mail.

We have established a simple convention that allows you to provide alternate names for the login system. In the User_login event, you pass an empty sfsobject that can be used to return the custom data to the client. You only need to provide this name in the object under a very specific (and reserved) key name. See the following code:

public class Logineventhandler extends Baseservereventhandler 
{ 
   @Override public
   void Handleserverevent ( Isfsevent event) throws Sfsexception 
   { 
      String name = (string) event.getparameter (sfseventparam.login_name); 
      Isfsobject Outdata = (isfsobject) event.getparameter (sfseventparam.login_out_data);

      // ...
      Your login logic goes here
      //...

      Provide a new name for the user:
      String newName = "user-" + name;
      Outdata.pututfstring (Sfsconstants.new_login_name, newName);
   } 
}

» How to use Smartfoxbits 2X

Together with SFS2X, we offer the latest version of the Smartfoxbits component, which can save you a lot of time setting up the application GUI if you are building your client using the Adobe Flash platform.

The basic Smartfoxbits package consists of five components:

Connectors: Manage Connection/Disconnect procedures (also support new reconnection systems)
login: Process Login procedure
roomlist: Manage the rooms list, including the Groups feature (allows multiple views of a list to be created from a group)
UserList: Manage the list of users who allow private chats
chatbox: Provide basic chat components

You can view all the details and read the documentation on the Smartfoxbits page.

» How to check server logs

SFS2X provides detailed logging of all activities. You can query them at any time by checking the logs/folders. In addition, under Logs/boot/folders, you can find detailed logs of the boot phase.

If the server has any problems starting the boot log will help you to quickly identify the problem.

» How to Debug extensions

You can easily attach the remote debugger to the server and enable your favorite debugger to extend your extension.

You can use Sfs2x.bat (Windows) or sfs2x.sh (LINUX/UNIX/MACOSX) scripts to start Smartfoxserver 2X. You can enable remote debugging by adding some JVM switches to the startup script. You can do this by following these steps:

Open the Admintool Server Configurator module and go to the JVM Settings tab;
Add the following switches to the list of JVM options:
-xdebug
-xnoagent
-xrunjdwp:transport = dt_socket,address = 8787,server = Y,suspend = n< c4/> Commit the changes and restart Smartfoxserver: You will now be able to start the remote debugging session.

If you want to keep the script from allowing debugging to be separated from the standard startup script, simply copy the starter script and modify it by adding the switch above using a text editor. Then save the script as debug.sh or Debug.bat and start it.

» How to schedule Scheduled tasks in an extension program

In general, in the server-side game logic, it is necessary to use a timer to send to the client periodic events (such as the end time, NPC actions, etc.).

The quickest way to solve this problem is to use the Scheduledthreadpoolexecutor class provided in the JDK, which provides a convenient task executor that is supported by a single thread pool. SFS2X has run its own instance of this executor (wrapped in a class named TaskScheduler).

The following Java code snippet shows how to run a looping task using Smartfoxserver's own TaskScheduler.

public class Schedulertestextension extends Sfsextension {Private class Taskrunner implements Runnable {

        private int runningcycles = 0;    
                public void Run () {try {runningcycles++; Trace ("Inside the running task.

                Cycle: "+ runningcycles);
                    if (Runningcycles >=) {trace ("Time to stop the task!");
                Taskhandle.cancel ();
            }} catch (Exception e) {e.printstacktrace ();

    }}}//keeps a reference to the task execution scheduledfuture<?> Taskhandle;

        @Override public void init () {Smartfoxserver SFS = smartfoxserver.getinstance (); Schedule the task to run every second, with no initial delay taskhandle = Sfs.gettaskscheduler (). Scheduleatfixe Drate (New Taskrunner (), 0, 1, timeunit.secOnds); }
}

The Scheduleatfixedrate method has four parameters:

A Runnable object that can execute the task code;
Initial delay before execution starts;
Time interval for task execution;
The unit of time used to represent the time value.

The scheduler also publishes a scheduling method that performs a runnable task once after a specified time. Finally, the dispatcher's thread pool can be dynamically resized at run time through the Resizethreadpool () method.

Important: Run-time exceptions that occur in the run () method will prevent the task from running. If you do not want the task to be interrupted by the expected error, be sure to catch any exceptions that may occur.

Attention
The initial size of the thread pool TaskScheduler by the system can be adjusted through the Server Configurator module in Admintool.

» How to send e-mail from extension programs

Email can be sent directly from your server-side code to provide registration confirmations, updates, and even debug and statistical reports.

In order to enable e-mail delivery, you need to set the Emailer service from Admintool: Select the Emailer tab from Serverconfigurator, open the service and set the SMTP parameters.

To restart the server, you can now send e-mail messages using the following lines of code:

Email myemail = new Sfsemail ("sender@email.com", "recipient@email.it", "Test Mail", "Hello from sfs2x");
Smartfoxserver.getinstance (). Getmailservice (). SendEmail (myemail);
There are three ways to send an e-mail message: "Blind" to confirm event latency. You can learn more from the Sfspostoffice class in Javadoc.

» More Recipes

Our smartfoxserver blog has more recipes. Note the monthly updates and subscribe to our twitter/fb/g + page for Automatic Updates.

Translated from Http://docs2x.smartfoxserver.com/GettingStarted/howtos