Server agent

Server Agents are the names for code running on the server.

Thane

Thane is the name of our server-side action script interpreter with a custom "shell", including a means of capturing trace output and some of the flash basics like EventDispatcher. The source code for thane is derived from the Mozilla Tamarin project [1] and hosted locally here.

When you upload your game's abc file and someone starts a game, the server spawns a thane process that downloads the abc file and instantiates your Server class. By default, the name of the Server class is assumed to be just "Server", but this can be changed on the upload page.

Server Agents

"Server Agent" is simply the name for your game code running on the server. It acts very much like a normal client, but cannot display graphics, use sockets or use any of the flash display classes. All "top-level" objects and language features are supported such as Array and String. Other classes that are fully supported include Event, EventDispatcher and Timer. A full list of supported classes can be found here.

Building a Server Agent

Server agents are normally built from a Server.as file in your game directory and result in an abc file with the same base name as your game's swf file. For example, the server agent code for TicTacToe.swf is TicTacToe.abc.

For a New Game

As of SDK version 0.33, when you're creating a new game using the "ant newproject" or "ant newgame" command included in the SDK, you'll be asked whether or not you want your game to have a server agent. Answer "y" and you can then add your code to the Server.as file that shows up in your game directory.

For an Existing Game

Existing games can also be converted to have server agents in a few easy steps. First, you need to add this to your the build.xml file in your game's directory in the SDK:

<actionscript><property name="app.enable-server-agent" value="true"/></actionscript>

Next, copy the whirled/templates/Server.as file from root of the SDK into your game directory. Don't forget to replace the @project@ in the comments with the name of your game!

When you then build your game you should see some output like this showing that the server agent has also been built:

<actionscript>build-server:

    [java] Loading configuration file /export/sdk/whirled/etc/thane-config.xml
    [java] MyGame.server.swf (13374 bytes)
    [echo] Turning .swfs into .abcs...
  [delete] Deleting: /export/sdk/whirled/mygame/MyGame.server.swf</actionscript>

Testing Your Game

Doing local testing on a game with a server agent is designed to work automatically. When you type "ant test" (and the -Dplayers=N argument to test with multiple flash clients) and a server agents has been built as above, the test environment will automatically fire up a thane interpreter to run your agent.

If everything is working properly, you should see some output like this in your console:

<actionscript>WARNING com.threerings.bureau: whirled-game-default output: New server instantiated! INFO com.whirled.game: Agent ready for [oid=5 receivers=([3e98f7a30deb5a8e25e05c71c6081bf4 => 0])]</actionscript> These two lines mean that your server agent was successfully loaded by thane and logged into the locally running test server.

In the test environment, your server agent's trace lines will be printed to the console identified with the prefix "com.threerings.bureau: whirled-game-default-output: " as above.

Note: the interpreter that loads and executes your server agent is a native application file called avmthane. We build and distribute Mac, Linux and Windows versions with the SDK, unpacked to dist/bin the first time you run a server agent.

Uploading a Server Agent

Once you've built an abc file containing your server agent code, you can then upload it on the game upload page. Don't forget to always update both files when something changes!

Checking Your Server Agent's Output On whirled.com

When your server agent is running on whirled and calls the built-in function trace, the text is sent to the server. Up to 64k of text is stored per game and may be found on the "Logs" tab in the game details page (see below). This allows you to investigate problems and see stack traces of unhandled exceptions. Note that other users cannot see the logs for your game. The in-development logs are tracked separately from the the logs of listed game.

The logs will be pruned periodically and the size limit may change. You should normally have access to the last few days of logs.