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.
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():
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():
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.
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
The following example shows the basic syntax:
Presumably, you would call the procedure 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:
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.
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.
You can query the hub to get all the same information that is visible to
users when they view your game's hub page.
The example above shows the basic mechanics. You get an object back of
type 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.
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).
This could be useful for notifying admins of events that are taking place
in a MUD, for example.
Ranking
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.
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.
Internals
Hub Info
Example:
/HubInfo
and this contains a list of worlds of type
/HubWorldInfo
. For a description of these objects, see the code.
Sending Email
Example: