Now that hub entries can use medals and scores, you may be wondering: How do I use them in my game? These new features have two sides. One side is in the game code itself, where you can use new procs that were added to BYOND in order to talk to the hub. The other side your hub entry itself, its page on the BYOND website and the editor where you can make changes.

Medals

When you edit your hub entry, you will now see a new Medals & Scores button at the top. Click the button.

Since your hub entry doesn't have any medals yet, you can create some here. You'll see a section that says "Add a new medal" and asks for a name and a description. Come up with a name for your medal, and a description of what it signifies or how it can be earned. For example, you might create a medal called "Dragon slayer", and the description could say "Defeat a dragon in single combat". Who wouldn't want that feather in their cap? Click the [Add Medal] link and the medal will be created.

Now you'll see the medal has been added, and it shows that it has no icon yet. That won't do at all, so make a 64×64-pixel graphic for the medal. Click the [Change Icon] link and you'll be able to upload the image.

Finally you should have a medal that has a name, a description, and an image. You can create more now if you like.

At this point, here's an important reminder: If your hub entry doesn't have a password, give it one now. Without one, anyone will be able to award your medals to players at will.

To award this medal in your game, you'll need to use the new world.SetMedal() proc. It's as simple as this:

world.SetMedal("Dragon slayer", usr)

You can give a medal out to any player with a BYOND account--that is, not a guest. The second argument in the proc can be a mob, a client, or the user's key. When they visit their home page, they'll see a list of medals they've earned in any of their favorite games. If your game is among their favorites, it will show up there. On your hub entry, their special achievement will show up as one of the most recent medals earned; people will be able to look at who earned which medals and when.

If the medal is awarded, this proc returns 1. Otherwise it returns 0, which can happen if that medal has already been earned. If the hub can't be contacted, the result is null.

You also have the option of awarding a medal for a different game, if you have the hub path and password ready to use.

world.SetMedal("Dragon slayer", usr, "MyName.MyGame", "Secret hub password")

In your game you can also check on medals a player has earned, with the world.GetMedal() proc. It works the same way except you don't need a hub password. If the player has a certain medal the result is 1, or 0 otherwise. And again if the hub can't be contacted, the result is null.

It's important to remember with these procs that they're talking to the hub--that can take a moment. The server will probably find out when a player logs in which medals they have, so talking to the hub may not be necessary if the info is already available.

Scores

Scores are another new feature, similar to medals, that can help players see how they rate. The new procs to use for these are world.GetScores() and world.SetScores(). I'll use my game Runt as an example. When you win or lose the game, it tells you how much gold you earned, how many rooms you explored, and how many creatures you defeated in battle.

BYOND scores are kind of like a mini-database. For each player (or character, or whatever else with a unique name) you can have a set of data values recorded. Those values could include score, character level, character class, win/loss record, and so on. You read and write scores using params2list() and list2params(). In Runt, I would probably want data fields called "Gold", "Rooms", "Monsters", "Wins", and "Deaths".

Using world.GetScores(), you normally just use two arguments: The name of the user or character the scores are for, and the list of fields you want to retrieve. If you leave the fields blank, you'll get all the fields; or you can just get a specific set of values by using something like "Wins" or "Gold;Rooms;Monsters".

To record a player's records in Runt, I'd probably use GetScores() first to find out how well they've done:

mob/proc/RecordResults(win, gold, rooms, monsters)
  spawn(-1)
    var/list/records
    var/result = world.GetScores(key, "")
    if(isnull(result))
      src << "Sorry, the hub could not be contacted to record your score."
      return
    records = params2list(result)

If the scores were retrieved successfully, the records var should now be an associative list that looks something like this:

records["Gold"] = "5820"
records["Rooms"] = "67"
records["Monsters"] = "894"
records["Wins"] = "3"
records["Losses"] = "18"

All the values are in text format. Now to finish recording the records, I would compare the current values to them and make adjustments, then call SetScores() to make the update.

    var/list/new_records = new
    new_records["Gold"] = max(gold, text2num(records["Gold"]))
    new_records["Rooms"] = max(rooms, text2num(records["Rooms"]))
    new_records["Monsters"] = max(monsters, text2num(records["Monsters"]))
    if(win)
      new_records["Wins"] = text2num(records["Wins"] || "0") + 1
    else
      new_records["Losses"] = text2num(records["Losses"] || "0") + 1
    if(world.SetScores(key, list2params(new_records)))
      src << "Your journey has been recorded in the annals of [win ? "victory" : "failure"]."
    else
      src << "Sorry, the hub could not be contacted to record your score."

The world.SetScores() proc will set any of the data fields you tell it to. In this code, either "Wins" or "Losses" is left untouched. If you set a value to an empty string it will be deleted. And if you called SetScores() with "" as the whole second argument, that player's scores will be wiped clean.

Just like with medals, you can read or write scores from another hub entry. If you do, you'll need to use the hub password for both SetScores() and GetScores().

Once you've got your game using scores, you'll need to display them. Go to edit your hub entry and once again click on the Medals & Scores button. Next to the area where you can create medals, you'll see a box that says Player Scores. If your game has already recorded some scores, you'll see the data fields that are available to choose from. If not, you'll have to tell it which ones to use.

To set up scores for Runt Deluxe, I would type "Gold" into the empty box, and click the [Add new value] link. Then I would put it in the first position, and tell it to sort the values from highest to lowest. I would then add "Rooms", "Monsters", "Wins", and "Losses" the same way. The losses column could be sorted from lowest to highest, but seeing who failed the most could be fun too.

With all the columns in that order, the hub page will show a quick listing of just the top five gold earners. If you click on the Standings tab of the hub entry, you'll see a bigger score list you can look through.