Position Updates

One of the features of most multiplayer real time games and virtual worlds is updating each user's position on the screen. While there are many ways to do this in an ElectroServer application, some are better than others.

Before choosing which method to use to update position, answer these key questions:

• How often do we need the position updates for each user?
• How many users are in the same game, maximum?

The reason for these questions is that most of the ways to send the position update information go out immediately to everybody in the same room. Since the Flash player tends to break all socket connections if it gets too many socket messages in too short a time, if the product of the two answers to the above questions is 20 per second or more you really need to use queued messages from a plugin.

Immediate Updates

Each of the following ways to send position update messages is sent immediately to each person in the room. That means that if there could be 20 users in the room, each client would be limited to one update per second.

• User variables: store the current position as a user variable, and all users in the room listen for user variable events
• Room variables: store the current position of the user as a room variable named with this user's name. All users in the room listen for room variable events.
• Public messages: Send the current position as an EsObject attached to a public message. Users listen for public message events, and check the EsObject attached. Add a boolean to the EsObject that specifies whether this is a position update or chat message.
• Plugin message: Send the current position to a room plugin attached to this room. Room plugin adds the user's name and sends the message to the room.

Reducing Frequency of Position Update Messages

How do we reduce the number of position update messages we send? The most common way is to send the position every so many frames, and then other clients tween from the current position to the new one, timed so that it lasts approximately that number of frames. Another good solution here is to send a path that will be taken or destination, such as when a user clicks to move to a point.

Best Solution: Queued Plugin Messages

The overall best solution is to use a room plugin to send queued messages. This technique automatically accumulates messages for a given number of milliseconds, then sends them all as a single bundled message. The Flash player considers this one socket message, but the client application thinks that it is getting each message separately. If the queue is set to send every 200ms, then clients would either tween the other players or simply update them immediately which might cause a small amount of jerkiness in the display but not much.

The room plugin can still send immediate messages for events that require immediate notification, such as an end of round or end of game message. The only disadvantage to queued messages is that it does require a room plugin attached to the room.

Rolling Out a New Release Gracefully

ElectroServer applications do not usually get installed and then just ignored by the developers. In most cases, bugfixes, tweaks, and new content are added on a continuing basis, even if the version of ElectroServer is not changed and no new hardware is needed. How can you keep your users from getting upset with the new change? We assume of course that the new version of the application has been beta tested.

Scheduled Maintenance

The easiest solution is to announce ahead of time on the website (and likely via email) that the application will be down for scheduled maintenance on a given day. Allow extra time in case there are bugs in the deployment and you have to either fix them or rollback to the previous version.

This method will still have some users playing the game when the ES4 is shut down, and completely surprised because they never bothered to read the announcement, or didn't know how to determine what that means in their own time zone.

Parallel ElectroServer System

If you have the extra hardware, this is likely the best solution. Bring up the new version of the application on a parallel ElectroServer (or set of ES4s if it is distributed). Test it as long as you need to, so that you are confident that the new deployment is stable and configured correctly. This ES4 has its own client build on your webserver (so the old version is available pointing to the current ES4, as well as the new version pointing to the alternate ES4). After you are confident that it is configured correctly and all files were copied to the correct locations, simply edit the HTML page that sends users to the application, so that it points to the new client build instead of the old one. Users who are still logged in will likely notice that there are fewer and fewer other users logged in. As soon as they refresh their HTML page, they will be connecting to the new build, and see the usual number of users.

After a few hours, or the next day, you can shut down the old ES4 until the next deployment. The best part is that if there is a serious bug discovered after the new build is live, if the old ES4 is still running all that is needed is to edit the HTML page again, to redirect the traffic back to the old build. This also has the advantage of fewer chances that a user will have the old version of the client files in his browser's cache.

Note that this solution does require a second license for ElectroServer or a special type of license.

Server Announcements

Another good solution is to have the clients listening for server announcements. When the server is notified that it will be shut down in a given number of minutes, a server level plugin can use code similar to this to send an EsObject containing any needed information to the clients:

getApi().sendPluginMessageToServer(esob);

Any client that is listening for plugin messages and knows how to process the EsObject can then display the announcement, in-game.

The server level plugin can also set a variable of some kind that the LoginEventHandler can read, that would prevent users from logging in until after the reboot (or just to warn the users when they log in that reboot is happening soon), and possibly to other plugins to prevent other activities that will take more than just a few minutes.

Here are some ways to inform the server that the warning should be sent and/or logins should be turned off:

• The server level plugin could read a certain XML file every 15 minutes, and that XML file could be edited to specify that the server is shutting down, possibly including the number of minutes or a timestamp for the shut down.
• Similarly, the server level plugin could query a database every so many minutes.
• A special admin client could send a message to the server level plugin when a shutdown is needed, with some kind of authentication so that hackers can't ruin fun for other users.
  

Using FlashDevelop for Client Development

ElectroServer clients can be developed using pure FlashDevelop if you don't have the Flash IDE. You can download an entire example FlashDevelop project from FlashDevelopExample.zip.

This example uses only .as files (no .fla files). It reads the IP and port from an XML file, connects to ElectroServer via Binary protocol, and logs in, sending a username, password, and an EsObject with data to be processed by a login event handler. It also includes a hook for handling plugin messages.

After installing FlashDevelop as described in this tutorial, simply unzip FlashDevelopExample.zip, then double click ConnectAndLogin.as3proj to edit the classes. The example can be run by opening bin/Example.html or bin/ConnectAndLogin.swf.

Custom Policy File

If your ES4 is behind a router that uses port forwarding to a different port, then you will need to use a custom policy file. How do you tell if you need one? If external clients can connect to your ES4 without one, then you don't need one!

Here's a scenario that does need a custom policy file.

• Client applications are connecting using port 9899
• Router forwards the messages from the clients to the ES4's server, but uses 19899
• ES4's gateway listeners are listening on port 19899

Customize the Policy File

The Custom policy file tutorial explains the exact XML needed for your custom policy file.

Install the Custom Policy File

• From the web admin's General tab, click Edit server settings.
  
• Near the bottom you will find Enable Custom Policy File. Toggle it on.
  
• Click Save.
  
• A button should appear that says Edit Custom Policy File Contents. Click it.
  
• Paste the policy file that you customized above into the text area.
  
• Click Save.
  
• Restart the ES4 and test that clients can connect.

Running ElectroServer as a Windows Service

For development purposes, particularly if you are using ES4 locally, it is often more convenient to have ElectroServer running in a window so that you can watch the console while a test is being run. When run in a window, ElectroServer is stopped by closing the window. The main disadvantages of using a window instead of a service are:

• When the server boots, each ES4 instance has to be started manually.
• Care must be taken to not accidentally close the window that ElectroServer is running in.
• If the same server is running multiple ES4s, there is a separate window for each which can cause some confusion.

Running ElectroServer as a service fixes the above three problems. The following instructions are specifically for Windows. A future blog will explain how to use a Linux service.

Installing the Service

When installing ElectroServer, you must select the option that installs the service.

Finding the Services Tool

After installation, to start and stop the service you will use the Windows Services tool. On Vista, this is found by:

1. Control Panel
2. System and Maintenance
3. Administrative Tools
4. Services

Other Windows operating systems will have similar paths to find this. It is useful to make a desktop shortcut to Services.

Using the Services Tool

From the Services tool, scroll to find ES_4_0_6_Standalone_Service and click it. On the left you will see links to click to stop or restart the service, or if it is already stopped, a link to start the service. In the screenshot below, the ES4 is set to not start automatically when Windows starts.

For a distributed ES4, the service names will be slightly different.

Buddy Lists

Whether you call them buddies, friends, team members, or something else, most users want to know when their friends are online. ElectroServer supports basic buddy lists without any need for an extension, plugin or other server side code, and if you add a server-level plugin you can implement your own needed extra features, such as persisting the buddy lists to a database or requiring that the other user accept the buddy relationship.

Add a Buddy

A client can add a buddy with an optional EsObject that can be packed full of information about the buddy (normally specifying the type of relationship). After a buddy is added, if the client listens for BuddyStatusUpdatedEvent, it will know when the buddy logs on or off. If we do not need to store information about the buddy, then adding takes a single line of code:

es.addBuddy(buddyName, new EsObject() );

Remove a Buddy

Removing a buddy is even easier. The client will hear a BuddyStatusUpdatedEvent when the server removes the buddy, indicating that the buddy is now offline.

es.removeBuddy(buddyName);
Plugin Buddy Commands

A plugin can add or remove a buddy just as easily:

boolean ok = getApi().addBuddy(username, buddyName, new EsObject());

boolean ok = getApi().removeBuddy(username, buddyName);

For a tutorial with full source code see Buddy list tutorial.

Troubleshooting Connection Problems

If the ES4 is up but your custom client can't connect, try these tests to narrow down the cause.

Telnet Test

Open a command window on the client machine that can't connect and try to telnet to the ES4, using the same IP address and port that your client application uses:

telnet 192.168.1.100 9898

If you don't get an XML file, then either the ES4 is down, the network between is down, or there is a firewall issue. See Enabling remote connections to a local ES4 for more information.

If you do get an XML file in response, then it there is no network or firewall problem connecting to the ES4, so try the next test.

Local Swf Test

Try connecting using a very basic client that just connects and logs in, by running the swf right from your hard drive. ElectroServer comes with several example clients, such as SimpleChat. Choose one that uses the protocol you need or ask for help finding one with the right protocol for your exact version of ElectroServer. Edit the XML file for the example to use the same IP and port that your own client application uses.

The first time you try to connect using a local swf, you will need to set the Flash Player global security settings. Click this link and then add the location where you normally put swfs that will need to communicate with ElectroServer (or just add your entire hard drive). This is not needed when a SWF is loaded from a website, only when it is loaded from your hard drive.

If you can connect using the example client with the exact same IP, port, and protocol as your own client application, then the problem is with your client application and the way it connects. In that case, try tracing the IP, port, and protocol, and compare your code with the sample code in the Connection & Login Tutorial.