DimensioneX/RSS

back to DimensioneX WIKI main and Italian WIKI

This article describes how to make your game to produce a standard RSS feed with the main in-game events. The RSS feed can be either used by followrs like it is, or it can be piped to other Web 2.0 services and websites such as Facebook, Twitter, etc.

Why producing an RSS feed is so important

It takes much effort to let people to enter and try out your game. Normally you want your visitors to come back, and play more. An RSS feed is a simple and yet standard device to let people outside the game to stay informed about what happen inside the game. Thanks to popular Web 2.0 services such as Facebook and Twitter, by publishing important in-game event news you stimulate new user's curiosity and make them enter and try out your game, thus making it more viral.

This technique, also, is the basis for our DimensioneX-to-Facebook kit, which can turn any DimensioneX-powered game into a full-fledged Facebook App. This aspect will be dealt in another tutorial.

So, you want to create an RSS, just read on.

What is an RSS feed

You get a exhaustive explanation on Wikipedia http://en.wikipedia.org/wiki/RSS, if you want to look at the final result of how your game feed might be, just at this one.

Steps

In brief, here is what it takes to have your game's RSS feed up and working:

• Authorize your game to write a Journal file on your game server
• Place Journal instructions in the game, at specific (and important) in-game events
• Transform the journal file to a standard RSS feed by using our PHP script (or write your own)
• Publicize the feed to your users
• (optional) pipe the feed to popular services: FeedBurner, Twitter, Facebook

Step 1 - Update your game engine

First, verify you are running an updated version of DimensioneX. The DimensioneX version is displayed on the connect screen of your own game ("built with DimensioneX ...") it should be at least 6.4.9

If the game engine is not updated, then the Journal instruction won't be available.

So, if it's the case, go download the most recent version and upgrade.

Step 2 - Authorize creation of the Journal file

DimensioneX is designed for server safety so it will never let the game developer to write files on the server without authorization. So before your game can write the journal file, this must be authorized.

Open your game's settings file (worldnavNN.properties in the dimx/WEB-INF/system directory) and add this line (if the setting is already there, just edit it):

#
# journal
# Path of a local file for producing RSS
# e.g. C:/journal.txt
journal=C:/journal.txt

In this setting you tell the game engine where the journal file will be created and how to call it. Here we chose to create it on the C: drive, root folder and name it journal.txt. Adjust the value to your own preference. Save, close, next step.

Step 3 - Insert Journal instruction in the game

Just for getting the things started, we can place a Journal instruction in a frequently called point of the game code so that we can easily see if it works.

Let's open your game (if you don't have one, just pick one out of the DimensioneX kit) and insert this event code:

EVENT onNew
	Print "Hello!"
	Journal "New player!",gameinfo("site"),"A new player named: " & $AGENT.name & " has entered the game","user:" & $AGENT.name
END_EVENT

If the game already has got an event named onNew, you can just insert the Journal instruction.

Let's now start the DimensioneX game engine, and enter in the game.

If everything worked fine, you should see a "Hello!" string on the game view.

Now check out your hard disk drive, where you configured the journal file to be written (it was C: drive, root folder, in the above step).

A journal.txt file should be there.

If you open it with a text editor you should be able to see the contents, there should be some text inside.

The juornal file is a sort of RSS feed itself written in a proprietary text format.

Now we just need to set up a tool which will convert it on-the-fly. See next step.

Step 4 - Having the journal.txt accessed by a PHP-powered webserver

This can be either straightforward or difficult, it depends on your own situation.

If your java webserver (tomcat) is installed on the same machine where a PHP powered webserver (Apache?) is, then this step is straightforward. Any PHP script is capable of accessing the local filesystem.

If you own a PHP powered webspace that is physically different than the game server running your game you have to set up some mechanism to make the journal.txt file accessible from the PHP script that will convert it.

We have tools and advice on how to do this, if you need help just contact us on the [DimensioneX forum http://z4.invisionfree.com/dimensionex/index.php?showforum=2] and explain your own situation when asking for advice.

For the purposes of this tutorial, we will be happy just by manually copying the journal.txt file to our PHP-powered webspace (let's choose a folder where you can run a PHP script from the web, just to make things simple)

Step 5 - Installing the Journal-to-RSS converter

The Journal-to-RSS converter is freely available from our Download Page or directly from here

Unpack the ZIP and copy the grss.php file onto your own webserver.

Step 6 - Configure grss.php

The configuration section is at the top of the file.

// CONFIG HERE
$gamewebsite = 'http://www.gamesite.net/'; // URL to game's official web site (used in RSS feed)
$gamedescr = 'Your great MMORPG game'; // (brief)  game description to be used in game RSS feed
$journalfile = '../private/journal.txt'; // Path to journal file. Can be relative. Does NOT need to be accessible via web (better not).
$feedtitle = 'MMORPG Game Feed'; // Human-readable title for Game events RSS Feed
$feedurl = 'http://www.gamesite.net/grss.php'; // URL to Game events RSS Feed
$debugmode = FALSE; // Set to TRUE to see diagnostic messages
// STOP CONFIG!

$journalfile: Specify here how to reach the game's journal file on the local filesystem from the grss.php file location. You can either specify a relative path or an absolute one.

Step 7 - Call the grss.php file from the web

By opening the script from the web, say:

http://www.gamesite.net/grss.php

Voilà, you should be able to see your game events, in a perfect RSS format.

htaccess shorthand recipe

As an optional step, if have an Apache webserver and if you like to, you can edit your .htaccess file so that the game feed is accessible via a different, simpler and cleaner URL that hides the real script's name. For example, at http://www.underworld-game.net I have edited the .htaccess file:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^game-feed$ grss.php [L]
</IfModule>

So that you can access the feed via: http://www.underworld-game.net/game-feed

Step 8 - Publicize / Distribute

It is now time to publicize your game feed to the game target users.

FeedBurner

Before you do this, you should be aware that FeedBurner.com offers for free the possiblity to enhance your game feed with sharing tools, extra gadgets and (important!) provide you usage statistics about how many users have subscribed to the feed, how many items are being clicked, etc.

If you are interested, just go to http://www.feedburner.com , get the service (it is a Google account based free service) and follow on-screen instructions to "burn" your feed. At the end of the process, you will be given a new, feedburned URL to be used and distributed to final users.

For example, my Underworld Online game feed has been transformed by Feedburner from this:

http://www.underworld-game.net/game-feed

to this

http://feeds.feedburner.com/UnderworldOnlineGameFeed

On your game site

It's a good practice to place, in the <HEAD> section of each page of your site, a showing the browser where the game feed is. here is an example that you can copy and customize for your own case:

<link rel="alternate" type="application/rss+xml" title="Underworld Free MMORPG Game Feed" href="http://feeds.feedburner.com/UnderworldOnlineGameFeed" />

Of course you have to customize the TITLE and HREF attributes of the tag.

Please note that this tag works for the browser's "Subscribe" function. Adding an icon with a normal link to the feed for human users to click on, is another must-have. If you look at http://ww.underworld-game.net you will find these icons in the right side bar.