BYOND Hub Communicator Library


Author: Dan
Version: 10 (13-Jul-2006)
Version: 7 (05-Jun-2002)
Version: 6 (22-Mar-2002)
Version: 5 (02-Feb-2001)
Version: 4 (09-Dec-2000)
Version: 3 (27-Oct-2000)
Version: 2 (30-June-2000)

A library for communicating with the BYOND Hub for the purpose of sharing savefiles and maintaining a central database of ranked players. Several other miscelaneous hub-related features also exist.


Contents

Hubfiles
Ranks
Hub Info
Sending Email

Hubfiles

A group of players can share a savefile, which is saved at the hub for easy access by everyone. The intention behind this is to make it convenient to play 'postal' games, such as chess. Players may checkout the game and make a move whenever they happen to log in, rather than always having to play in realtime.

The first thing you need to do is define procedures to load and save the state of your game to a savefile. Once you have done that, the rest is easy.

Assuming you have the savefile in hand, posting it to the hub is accomplished by calling byondhub.CheckinHubfile():

#include<hublib/hublib.dm> world hub = "Dantom.HubFileDemo" //set this to your game's hub id proc/SaveGame() var/savefile/F = new() //save your game here! var/players[0] players["Dan"] = byondhub.USER_ACTIVE //it is Dan's turn players["Tom"] = byondhub.USER_INACTIVE //while Tom and James wait players["JamesByond"] = byondhub.USER_INACTIVE var/title //I am leaving optional title unset byondhub.CheckinHubfile(F,players,title)

That saves the file and sends out notifications via email. Now when any of the players logs in, they will see the file and an indication of their status (waiting or moving). All they have to do is click on the file to open it up and make a move. If you have uploaded a hub installation package for your game, they don't even need to have your game installed in advance!

When a player connects by clicking on the saved game, they come into the world with a special topic string which gets routed to the byondhub object, telling it to download the requested file. To intercept the file, you have to override ByondHub/LoadHubfile():

ByondHub/LoadHubfile(File,players[],title,resolved_email[]) if(File) var/savefile/F = new(File) //restore your game here!

Once you have loaded a savefile in this manner, the next CheckinHubfile() will automatically write over the previous file at the hub. When the game is over, you can totally delete the hubfile by writing to it with an empty player list or by calling DeleteHubfile().

Note that hubfile owners may be specified either by BYOND Key or by email address. In the case of email addresses, you will not know the true BYOND Key of the user until they accept the invitation. Any email addresses that become "resolved" in this way are indicated in the resolved_email argument to LoadHubfile(). For example, if this list contains an entry "dan@dantom.com", then the associated value (resolved_email["dan@dantom.com"]) would be "Dan".

Generally speaking, you will want to go through the list of players stored in your game's savefile and replace any email addresses with the BYOND Key, once it becomes known.

Ranking

Players are ranked from weakest to strongest on a scale of 1 to 10. This is done by taking into account the cumulative scores of every player against every other player. These scores may be any numerical value. For example, you could use 1 and 0 for win and loss or you could have a fuzzy scale that indicates the degree of victory or defeat.

For more information about the ranking algorithm, see the official MANTRA specifications.

To report scores at the end of the game, you need to call the hub's ReportScores() procedure. This takes a list of players and their associated scores and adds this data to your game's central rank database, maintained by the hub.

The following example shows the basic syntax:

#include <hublib/hublib.dm> world hub = "Dantom.HubScoresDemo" //set this to your game's hub id hub_password = "YourPassword" //only necessary for "authenticated" hubs proc/GameOver(Player1,score1,Player2,score2) var/scores[0] scores[Player1] = score1 scores[Player2] = score2 byondhub.ReportScores(scores)

Presumably, you would call the procedure GameOver() when the final results of the game are known. This example is for a two player game, but the list of scores may be any length. The players in the list may be mobs, clients, or keys.

The scores are submitted to a database in the hub. You can view it by going to your game in the hub and clicking on "Ranks". (It is automatically created when you first report some scores.) It might look something like this:

Rank 2
Somebody
Somebody Else
Rank 1
Dan (we suck at games)
Tom

Remember, high rank numbers are better than low ranks. The ranking algorithm may not always produce the results you expect. I will be providing some more documentation on how you might influence the algorithm.

Internals

For the most part, the ByondHub object handles everything for you. In a few cases, you might want slightly different behavior, or you might just want to change the look and feel of the user interface. To do that, you will probably need to override one or more procedures.

The appearance of output text produced by ByondHub can be controlled in your stylesheet (see the docs on client.style). The style class 'hub' is used for all output from ByondHub, allowing you to easily change its appearance.

For complete control over the user-visible actions of the hub, you will need to override some procedures. These are not documented here yet. Check hublib.dm for the details.

Hub Info

You can query the hub to get all the same information that is visible to users when they view your game's hub page.

Example:

mob/verb/test() var/HubInfo/hub_inf = byondhub.GetHubInfo(world.hub,WORLDS_HUB_INFO) usr << "Worlds online:" for(var/HubWorldInfo/w in hub_inf.worlds) usr << w.url

The example above shows the basic mechanics. You get an object back of type /HubInfo and this contains a list of worlds of type /HubWorldInfo. For a description of these objects, see the code.

To save network bandwidth, you should request only the content that you care about. Possible values are: GENERAL_HUB_INFO, WORLDS_HUB_INFO, and USERS_HUB_INFO. Any combination of these may be ORed together. If you do not specify the content that you want, all available information will be sent.

Sending Email

You can send email to a user from a world that is registered at the hub with a login url. In other words, the world must be running on a fixed port designated by you. The hub requires this in order to assign responsibility for the email that gets sent (for security purposes).

Example:

world/hub = "You.TestWorld" //this must be filled in mob/verb/test() var/recipient = usr.key var/subject = "Testing" var/message = "This is a test of the email broadcasting service." byondhub.SendEmail(recipient,subject,message)

This could be useful for notifying admins of events that are taking place in a MUD, for example.