Using The Server Status Images On Your Site
The data contained in the images is live and no more than
about 20 seconds old. We have added basic functionality and are open to
modifying it. Contact us here.
Our functionality comes from using the Perl GD package, so theoretically we
could add any of the functionality from there. Refer to the GD Documentation for more
information. If you need more control over the image, let us know.
Any donations to this part time project appreciated. You can
make them here.
Using
The Server Status Images On Your Site.
Changing
the Background Colour
Changing
the Height and Width of the Image
Special
Note on Background Image Palettes:
Specifying
Server Data Elements (Fields)
Specifying
Server Data Icon Elements (Icons)
Showing
the List of Current Players
Filtering
the List of Current Players by Their Name
Showing
Players from All Servers
Basic Images
The images are simply added to your site through the use of the HTML <img> tag. The most basic form of this would be:
<img src=“http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=MY_REGION&serverpattern=MY_SERVERPATTERN“>
where:
MY_REGION is the two letter region code for your server
Available Regions are:
|
JO |
Joint Operations |
|
DFX |
Delta Force |
|
DFX2B |
Delta Force 2 Beta |
|
NA |
Joint Operations |
If not region is specified it will default to JO
MY_SERVERPATTERN is a regular expression, or in its most simple form the complete server name. Since we match your server using a pattern you do not need to include the full name, but you do need to include enough to make sure that it is the only server matching that pattern. Additionally, since we are passing this server pattern in an HTML request string we can not include certain characters or we must translate them to their hexadecimal form. Fortunately, since we are using regular expression this becomes a lot simpler. Normally we would just replace any non-alphabetic characters with the “.” character and this is satisfactory. For example, if your server name was “JO Server” then the server pattern to match this might simply be “server”. However, since there may be another server called “My Server” our pattern “server” would match both names and we would not get an image. We need to use the server pattern “my.server”.
Let’s have a look at the example image for the Monsoon 1 server. This can be viewed at:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2
You would include this in your site using
<img src=“http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2“>
Notice how we replaced
MY_REGION by NA, and
MY_SERVERPATTERN by monsoon.2
As long as there are no other servers with “monsoon” in their name we could have replaced MY_SERVERPATTERN by monsoon.
This returns us the default image for this server, a very basic graphic.
There are other parameters to enhance the image.
Changing the Font
We can set the size of the font and its colour.
The font sizes available are tiny, small, medium, large and giant.
The available colours can be seen here. It would be possible to add other colours, contact us here.
To set the size and/or colour we add the font and fontcol parameters to the HTTP request string. For example, to change the font to small and make it blue we use:
Changing the Background Colour
We can set the background colour using the bgcol parameter. For example, to set the background colour to yellow use:
Adding a Frame
We can add a frame around the image. There are actually 2 ways to do this. You can use the “border” option to the <img> tag eg
The image at
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2
could be included in your site by using
<img border=1 src=“http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2“>
Or we can use the frame and framecol parameters.
For example to add a black frame right on the outside of the image you could use:
If we changed the 0 to a 5 the frame would be moved inwards by 5 pixels. Compare the images:
This is probably only useful if you have a background colour set. For example,
Changing the Height and Width of the Image
We can change the height and width (in pixels) of the image using the size parameter. For example:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&size=300,200
This creates an image that is 300 pixels wide by 200 pixels high.
Changing the Text Offset
We can move all of the text and icons in the image by a certain number of pixels, using the offset parameter. For example if we wanted to move them 10 pixels to the right and 5 pixels down we would using the following:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&offset=10,5
If we wanted to move in the reverse direction we specify a negative number using the minus sign “-”:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&offset=-10,5
Changing the Background Image
We can add a background image to the server status image. You can use images that are predefined and stored on our server. We are happy for you to send your images to us so that you can use them. We only accept images in the PNG format.
You can also specify the complete URL of an image. The URL must be of an image only or you will get an error returned. If the url does not exist we will draw the image with no background template. This may or may not work as the size of the images may differ and your text may no longer e in the correct location. You could specify the size parameter in case the URL failed so that the replacement image was the correct size.
We have a couple of samples of predefined images.
You specify the background image using the style parameter. Have a look at these:
Notice how we changed the font colour to white and set the style to 2. Remember that we can move the text around using the offset? Try this:
The other sample image is
That one needs some work with the colours and text placement locations. Fortunately, we can move and even specify what text and icon elements we want in our image.
Here is an example of using a background image from a URL using the style parameter:
Note that using remote images is always slower than using predefined images since we have to go and fetch the image every time, build the data on the image and then deliver it to you. If the remote URL is slow from our perspective, then our image delivery to you will be slow from your perspective. Using the remote image is easier when you are developing and testing your image but feel free to send your completed image to us. Contact us here.
Also note that we may cache the remote image so that we do not have to fetch it every time. This may result in changes to your image not being shown.
Special Note on Background Image Palettes:
We can only write/change text/field/icon elements using the palette of the background image. For example, if you want to have white writing you need to make sure that white is included in the palette of the image.
Specifying Text Elements
The following parameters give us fine control over what text is shown on the image, where it is located and what colour and size it is. These are the text parameters. Look at this example:
You’ll notice that we have taken the text element number 0 (text0) and changed it so that it is located at pixels 10,140 where 10 is 10 pixels across from the left and 140 is 140 pixels down from the top. The top left hand corner is position 0,0.
We have also changed the font to large and made it red (or tried to – read the note above Special Note on Background Image Palettes: - in this case our background image palette does not contain red so we can not draw red).
We have also changed the wording to be THE SERVER NAME. Notice how we have used %20 instead of spaces? This is hexadecimal encoding. If you want to use any non-alphabetic characters it’s normally best to encode them. Try different characters and see what works. If it does not work you will need to encode them.
The most common conversions (encoding) you might need are:
Space => %20
& => %26
? => %3F
, =>
You’ll need to refer to an ASCII to HEX conversion table for other conversions.
The format required for specifying a text element is
textN=X,Y,FONT,COLOUR,TEXT
For example
text0=10,140,large,red,THE%20SERVER%20NAME
or
text1=10,140,,,THE%20SERVER%20NAME
You need to specify the X, Y and TEXT values, but if you leave out the FONT and COLOUR values the text will be written using the values from the font and fontcol parameters you set above.
By default, the elements text0 through to text 4 are predefined with Server Name, Mission Name etc. You can overwrite them as we have just shown. You could even just blank the default one out by not giving it any values like this:
You can set text0 through to text9 using any text, colour, location, or size information you need.
View all the default settings here.
Specifying Server Data Elements (Fields)
As well as being able to specify arbitrary text fields you can place data about your server on the image in a similar way using the field0 to field9 parameters.
Have look at this example:
This has taken the ServerName field and placed it at location 10,200 using a small, white font.
The Server Information Fields available include (it is important the you use the field name exactly as defined here):
|
servername |
The name of the server |
|
game |
The type of the current game eg AAS, DM etc |
|
mission |
The name of the current map |
|
region |
The region the map covers eg Jungle |
|
players |
The number of players currently on |
|
maxplayers |
The maximum number of players the map supports |
|
timeleft |
The amount of time left for the current map in minutes |
|
servermsg |
The server messages |
|
age |
The amount of time the server has been up in days, HH:MM:SS |
|
timeofday |
The time of day on the current map eg Dawn |
|
tracers |
Are tracers enabled for the server |
The format required for specifying a field element is
fieldN=X,Y,FONT,COLOUR,FIELDNAME
For example
field0=10,140,large,red,Players
or
field1=10,140,,,Players
By default, the elements field0 through to field5 are predefined with ServerName, MissionName etc. You can overwrite them as we have just shown. You could even just blank the default one out by not giving it any values like this:
View all the default settings here.
Specifying Server Data Icon Elements (Icons)
Some of the server based parameters are actually displayed as icons. These are 16x16 pixels. You can specify icon0 to icon5. Here’s an example:
This example shows the icon 0 at location 10,140 showing the Mod icon.
The icon is drawn using the palette from the background image. If the background image does not have all the colours the icons requires it may look strange.
Icon based information fields include (it is important the you use the field name exactly as defined here):
|
password |
Shows a padlock icon if the server has a password |
|
country |
Shows a country flag if the Country has been defined |
|
punkbuster |
Shows a Punk Buster icon if Punk Buster is enabled |
|
mod |
Show an Icon for the Game Mod the server is running eg Typhoon Rising, Escalation etc |
The format required for specifying an icon element is
iconN=X,Y,FIELDNAME
For example
icon0=10,140,Mod
View all the default settings here.
Showing the List of Current Players
You can add the list of current player names to the graphic. The list of players is a special version of a field element. To show the list of players enable it by specifying one of the field elements 0 to 9 and using the field name “PlayerList”. For example, to show the list of players using field element 9 with a small, white font at position 10,10 use: field9=10,10,large,white,PlayerList.
Just showing the PlayerList using the above setting is not very helpful on its own. You need to control how the player list is shown. This can be achieved using the special “playerlist” parameter. The “playerlist” parameter is used as follows:
playerlist=NumberPerLine,LineHeight,Maximum,Grow,DummyPlayers,Delimiter,FixedWidth
where
· NumberPerLine is the number of players to show per line. The default is 1.
· LineHeight is the number of pixels high each line is. The default is 10. This will control how close together the players are shown.
· Maximum is the maximum number of players to show. The default is all. Enter the maximum number or leave it blank to show all.
· Grow this is the number of pixels that we will increase the height of the image by for each line of players shown. The default is 0. You may like to make this the same value as LineHeight to make the image grow in direct proportion to the number of lines of players shown. If you have specified a background image using the style parameter then you will not be able to “grow” the image.
· DummyPlayers is the number of dummy players to add to the player list. The default is 0. Use this when testing how your image will look with certain numbers of players. For example, you might like to set it to 32 if your server can support 32 players to see how the image will look. Dummy player names are shown as 16 characters long, which is the maximum you should ever see.
· Delimiter is the character to show between players. The default is to show nothing. Use the word “comma” to use a comma between players, leave it blank to show nothing. You may need to use hexadecimal encoding to show certain characters, eg %20 if you want to use a space. So to show a comma and a space as the delimiter use comma%20.
· FixedWidth is the number of characters to fix the length of the player name at. The default is not to fix width the player name. If you are trying to display the player names in columns then you’ll probably want to set the value of this to the maximum size of the player name eg 16. By default, the names are right-aligned. You can make them left aligned by prefix this value with a minus sign eg -16.
For example,
playerlist=2,10,16,10,16,comma%20,-20
will show 2 players per line, where the lines are 10 pixels high, a maximum of 16 players, growing the image height by 10 pixels per line of players, adding up to 16 dummy players and using a comma and a space between players. The player names are fixed at 20 characters and left-aligned (-).
Here’s a complete example where we have added the player list to the server status image:
You could create a graphic which just included the list of current players by specifying set=none and then defining the PlayerList as the only field element, like this:
or changing it to a single column vertical list
Notice how most of the values in playerlist have been left at default values. In this case, you still need the commas to separate the fields.
Filtering the List of Current Players by Their Name
Once you have added the list of current player names to the graphic, we can filter them and only show players matching a certain pattern.
This can be achieved using the special “playerpattern” parameter. The “playerpattern” parameter is used as follows:
playerpattern=PATTERN
where
· PATTERN is a regular expression that players must match to be included in the list. The pattern is case insensitive.
For simple searches enter part of the player name(s) you wish to match.
More advanced searches can be built using the following examples:
· Matching multiple players in one search: eg AW|IWI
· Match players starting with some text: eg ^AW
· Match Players ending with some text: eg FMS$
· Combinations: eg ^AW|FMS$
Experts: Read up on regular expressions!
Here’s a complete example where we have added the player list and only show players with the letter “S” in their name (note that at the time you look at the example there may actually be no players with a “S” in their name):
Show players from the AW clan, whose names start with AW. We don’t want to see players that have AW in their name somewhere else eg McGraw:
Showing Players from All Servers
This is a special mode of operation. Up until now you have always specified a “serverpattern”. In this mode of operation we want to look for players across all servers. So we do not specify a “serverpattern”. We must specify a “playerpattern” (see above section). In this mode we find all player names that match “playerpattern” on any servers.
The player list will not just show itself by magic. You must still specify all the other parameters which will show the player list. Here is the most basic example:
Show any players whose names start with the letter d.
You may want to adjust the size of the image using the size parameter, like this:
If you want to show the server that the player is on you can also do this. In order to do this you need to specify a formatting parameter which allows you to control whether the server name comes first or goes last, the spacing parameters and any other characters eg put the server name in brackets.
To show the servername and control its formatting you use the “withservername” parameter as follows:
withservername=FORMAT
where
FORMAT is like a printf formatting statement with some special exceptions.
Here are some examples:
withservername=!-30<>_!-40{}
WHERE
!-30<> is the location where the Server Name is shown and – (is optional) means to left justify it and 30 means allow 30 characters for the name
!-40{} is the location where the Player Name is shown and – (is optional) means to left justify it and 40 means allow 40 characters for the name
_ (underscore) is converted to a space
Now show the playername first (put {} before <>):
Now do not allocate fixed character widths to the names:
That is very hard to read so put brackets around the server name:
Still hard to read, try putting the word SERVER: in front of the server name with some more spaces:
Now lets make it fixed width again, but with 30 characters allocated to the playername (right justified) and 40 characters to the servername (left justified):
This example is quite nice. It left justifies the player name and server names giving them a fixed width. Titles are put above the columns. We start with an image size of 500x50 (which grows as required):
All through these examples we are looking for players whose name starts with “d”.
If we wanted to find players whose name ended in CZX we would use playerpattern=CZX$, like this:
Note that this operation mode always uses set=none so that no fields are automatically shown. Sets are introduced in the next section.
Sorting the Player Lists
Any where you show a list of players you can sort it using the “playerlistsort” parameter.
The format for the specifying a sort is
playerlistsort=ASC,CASE
where
ASC = 1 for ascending sort, 0 for descending sort
CASE = 1 for case sensitive sort, 0 for case insensitive sort
Eg playerlistsort=1,1
Show all players on any server whose name starts with d and sort it ascending and case sensitive
If you include this parameter with no values you will get a default sort which is ascending and case in-sensitive.
Data Sets (or Groupings)
Up till now we have been using all the default text, field and icon settings from the default set, which is set=0. If you do not specify any set, you get set=0. All the above examples, did not specify a set and so used set=0. You can select other sets e.g. set=1, or select no set by using set=none. Compare the following:
Set 0, a horizontal set:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&set=0
Set 1, a vertical set:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&set=1
Set 2, a brief set:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&set=2
You can see all the settings for a given set (in the following example set=0) by using the showset=1 parameter:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img&set=0&showset=1
If you wanted to completely define all elements yourself, you would use set=none. This gives an empty image:
http://www.edcint.co.nz/jo/lobby/lobby.cgi?mode=img®ion=JO&serverpattern=monsoon.2&set=none
From an empty image you would have to add text and field elements. You could also specify a different image size etc.
For example:
These are actually the settings from set=2.
We then modify the settings further, changing the framecol, bgcol and font: