» Table of contents:
Introduction:
The BlueBox is a new SmartFoxServer module designed to allow connections behind firewall and proxies.
Once the add-on is installed the Flash client will be able to redirect its connection to the BlueBox, if a direct
socket connection is not available.
BlueBox enables players under restricted network configurations to play and enjoy fast multiplayer apps and games with little
to no noticeable performance loss. All existing SmartFoxServer applications can take advantage of the BlueBox without any code change!
Just recompile your SWF files with the provided API and you're up and running.
Behind the scenes BlueBox will wrap the SmartFoxServer protocol in HTTP packets, similarly to what is done with a so-called
http-tunnel. The behavior of the BlueBox is however pretty different from regular polling solutions.
The major disadvantages of this approach is the continuous traffic of requests coming from the clients, even during
inactivity. Additionally the overall performance isn't very good especially if the polling interval is bigger than a couple of seconds.
The BlueBox uses a different approach eliminating the need
for continuous polling. Additionally the client API provide the developer with the ability to fine tune the server response times, allowing near real-time performance!
Download:
Click the download button below and follow the installation instructions to get started.
Installation:
Prerequisites:
Unzip the BlueBox_beta.zip file to a folder of your choice. This is what you should find:
-
API/ contains the AS 2.0 and AS 3.0 API files
-
BlueBox/ contains specific BlueBox files
-
Examples/ contains 4 pre-compiled example files
-
Jetty/ an upgrade of the Jetty embedded web-server
Move to the BlueBox/ folder and copy the following files:
- BlueBox.war goes into the Server/webserver/webapps/ folder
- bluebox.properties goes into the Server/ folder
From the
jetty/ folder copy all files to
Server/lib/jetty/ and replace them.
Before you're ready to go there's one last change to do, adding an entry in the classpath.
This can be done in different ways based on your OS and how you're running the server.
» Running the server as service/daemon
You should open the conf/wrapper.conf file.
In the classpath section add a new entry like this:
wrapper.java.classpath.XX=/path-to-installation/Server/webserver/webapps/BlueBox.war
Where XX is a progressive number. If you're using relative paths it will be slightly different:
wrapper.java.classpath.XX=webserver/webapps/BlueBox.war
» Running the server standalone (start.sh or start.bat)
Linux/Unix: open the start.sh script with your favorite text editor and add
webserver/webapps/BlueBox.war to the classpath parameter. Make sure to separate each entry with a colon (:).
Windows: open the start.bat script with your favorite text editor and add
webserver/webapps/BlueBox.war to the classpath parameter. Make sure to separate each entry with a semi-colon (;).
Finally start the server and point your browser to: http://localhost:8080/BlueBox.
You should see a simple web page confirming that the installation was done correctly.
IMPORTANT NOTE: Port 8080 is great for testing but we highly recommend to configure the web-server to run on
port 80 for production environments.
Running on port 80 requires that you don't have other services on that port and that you start the server as root user
if you use a Unix/Linux OS.
Examples:
In the Examples/ folder you will find 4 SmartFoxServer examples recompiled with the new API.
Each example will try to connect via socket to 127.0.0.1:9338, which is wrong (9339 is the default port).
Since the socket connection will fail, the API will then establish a connection to the BlueBox.
Note: make sure the web-server is turned on before launching the examples.
- Advanced Chat (default polling speed = 750ms.)
- Avatar Chat (default speed)
- Realtime Maze (tweaked speed = 200ms.)
- SmartFoxTris AS3 (default speed)
Flash API:
In order to test your existing SmartFoxServer applications with BlueBox support, you simply have to recompile them
with the new API provided in the package. The API will attempt a socket connection first and, on failure, they will
switch to the http connection.
New properties and methods are available to the SmartFoxClient object:
-
smartConnect: boolean flag. If true will attempt a connection to the BlueBox
if a socket connection is not available (default = true).
-
getConnectionMode(): the method returns the current connection mode. It can be any of the following three states:
- SmartFoxClient.CONNECTION_MODE_DISCONNECTED
- SmartFoxClient.CONNECTION_MODE_SOCKET
- SmartFoxClient.CONNECTION_MODE_HTTP
-
httpPort: specifies the port of the embedded web server (8080 by default).
-
httpPollSpeed: specifies the minimum interval between two polling requests (750ms by default).
F.A.Q:
-
What's the recommended value for polling speed?
A value between 750-1000ms. is very good for all chatting, turn-based games and similar kind of applications.
It will add minimum lag to the client responsiveness and it will keep the server cpu usage low.
Lower values (200-500ms.) can be used where a faster responsiveness is necessary. For super fast real-time games you can try values
between 50 and 100ms. We don't recommend using values below 50ms.
With settings < 200 ms. the cpu usage will grow significantly as the http connection and packet wrapping/unwrapping is more expensive than
using a persistent connection.
-
What's the difference between regular polling and the BlueBox polling?
With "regular polling" the client will ask the server for new data/events every x seconds.
This is quite inefficient as the server will receive many continuous requests even when there's nothing to send back to the client.
Additionally there are times when an event occurs just a few milliseconds after the client asked for new data. If this happens the lag time
is almost doubled as the client didn't receive anything in the last poll request and now has to wait another full interval before he can ask again.
Because of this, even if the poll interval is set to 1 second, the lag can get as high as 2 seconds!
The SmartFoxServer BlueBox optimizes both scenarios by suspending HTTP requests and resuming them immediately, as data becomes available.
The result is that server minimizes the client lag, greatly enhances the performance and makes smart use of resources and bandwidth.
Additionally this allows the BlueBox to support extremely low polling values such as 300ms. (and lower) without the risk of bombarding the server with requests when no data is
available for the client.
-
How many concurrent clients can be handled by the BlueBox?
It's difficult to estimate, it all depends on the hardware, the type of game/application and the client latency settings.
If you plan to run thousands of http connections we highly recommend a 2x or 4x multi-core CPU.
-
Is it possible to run the BlueBox on a dedicated server?
Not in this beta, but we plan to add this feature in the final release.
Using a dedicated machine exclusively for HTTP connections can greatly help when handling thousands of clients or when using very low polling settings.
-
Does the BlueBox limit any of the SmartFoxServer features?
With the the exclusion of a couple of minor things, no. All the features are available as if it was used with socket connections.
The only limitations are:
- Banning by IP address
- IP Filtering
These two features won't be available because BlueBox-ed users don't establish a direct connection with the server.
-
How does the licensing for the BlueBox work?
The BlueBox final will ship with the next SmartFoxServer release ( 1.6.0 ) and it will be free to use with
the same limitations of the free SFS license (20 users).
There will be one single license type available for the BlueBox, which allows unlimited connections.
The license can be purchased separately or together with the server. The price will be the same.
-
What's the price of the BlueBox license?
The final price isn't defined yet. We'll be able to give more details with the release of SmartFoxServer 1.6
I.A.Q (Infrequently asked questions):
-
Why is it called the "BlueBox"?
Well, since it's a separated component we thought of it as a strange, enigmatic box that you add it to the server
and it does the magic. Something like a "black box" which seems so mysterious... but black boxes already exist and they are done for
logging informations. So we had to choose another color.
Blue was our choice, hence the BlueBox :-)
Reporting problems:
We have launched a new section in our support forums dedicated to the BlubeBox where you
can post your feedback, report issues or bugs etc...
Know bugs/issues:
-
It seems that sometimes the Flash Player takes quite a bit of time (10 seconds or so) before reporting that a socket connection is
not possible. This can lead to an apparently slow connection because the client API are waiting the Flash Player to
notify if it's possible to use sockets or not.
-
When a client closes the connection by quitting the Flash Player / browser you may still see him as connected to the
server. This is due to the fact that BlueBox does not use persistent connections, hence it can't immediately detect when
a client gets disconnected. In order to determine this it uses a timeout which can be changed in the bluebox.properties file.
The property is called client_idle_request_time.
-
If you're running multiple copies of your client in the same browser you may experience strange application behaviors.
We recommend to use 2 different browsers in order to run two instances of your application.
The reason behind this is that the browser might reuse the same http connection for both instances: while this is a good optimization for the browser resources, it
is a problem for the BlueBox which expects each client to communicate on a different connection.
..:: Document revision 1.2.0 -- (c) 2007 by gotoAndPlay() -- All rights reserved ::..
