ID:55025
 
Keywords: beginner, tutorial

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.

Very nice addition indeed.
Bug on adding medals. My attempt to add two medals failed. The first one went through, the second one stayed as the form and another blank form was created above it.

Edit: Actually, the medal was added, but I had to navigate away from the page and return back to it for the medal to be displayed properly.
I love you.
Nice But I would Like For You To Do A Demo On This Also I know How To Use It Just This Post Wont Be Here Foreverz
Will it be possible down the road to remove a users medals (say the user becomes the hero of the land, but then does something drastically evil to it's people) and to delete fields in the Scores section?
Tiberath wrote:
Will it be possible down the road to remove a users medals (say the user becomes the hero of the land, but then does something drastically evil to it's people) and to delete fields in the Scores section?

I was wondering something to that effect to, Tiberath. lol
Just some possible additions:

Counters:
Have a way to set a medal as a counter. You set a numeric value on the medal. When the proc is called it is incremented by one. When the value hits the set numeric value set, the medal shows up.

Ex:
Killed 1000 of X

Progress / Multistage:
Have a way to set in multiple steps needed to be completed. The proc will be called with the name of the step.

Ex:
world.SetMedalProgress("Dragon Slayer", usr, "Killed Demon 1")
Good stuff.
Just to second Tib's suggestion:
I think a remove medal might be in order to expand the concept of medals as well. A king of the hill type of award (say for a PvP game) would probably be only one recipient at any moment and would pass from one player to another. A removeMedal would be necessary there, too.

But, overall: a good addition.
Nice tutorial! I completely understand medals now :)
Dbar910 wrote:
Im not exactly sure how 2 use the medals do i just put that code in or is there more to it

Have you read the tutorial? If not, do so. If so, what are you exactly confused about?
I tried to follow the directions for the Score's Procs, but for some reason it is either not recognizing the variables, or it is rejecting the coding itself. Im not sure what to do.

-Mysterio
I tried to follow the directions for the Score's Procs, but for some reason it is either not recognizing the variables, or it is rejecting the coding itself. Im not sure what to do.

-Mysterio
Ernesto5432 wrote:
I tried to follow the directions for the Score's Procs, but for some reason it is either not recognizing the variables, or it is rejecting the coding itself. Im not sure what to do.

-Mysterio

ehhh because if that game dosent have gold and stuffz as it is in example then u change itz
Make sure you're using the latest version of BYOND (Here) before you try to use these new procs.
Ernesto5432 wrote:
I tried to follow the directions for the Score's Procs, but for some reason it is either not recognizing the variables, or it is rejecting the coding itself. Im not sure what to do.

-Mysterio

Don't reload, it makes you re-post. This may sound stupid, but did you update your BYOND Client :P
Dbar910 wrote:
Flame Guardian wrote:
Dbar910 wrote:
Im not exactly sure how 2 use the medals do i just put that code in or is there more to it

Have you read the tutorial? If not, do so. If so, what are you exactly confused about?

I did everything it said and when i went to compile it went to another Dm and said there was a Error but when i took out the medal code it was all good so i dont know where i messed up

Yeah, like what I said to the Ernesto5432(Or Mysterio??). Make sure you have the client downloaded, if not. You could page me the error, or post on the forums for help.
---
I put it at the bottom of a Dm and at the top of the next one i got Bad Argument Definition

Ok, we don't need to clutter the post anymore. Hopefully, your pager is on so I'll page you :)

Alright guys, time to move development questions to The Forums. They'll be noticed by more people there and we wont clog up this post.
Ernesto5432 wrote:
I tried to follow the directions for the Score's Procs, but for some reason it is either not recognizing the variables, or it is rejecting the coding itself. Im not sure what to do.

-Mysterio

ehhh because if that game dosent have gold and stuffz as it is in example then u change itz
Page: 1 2 3 4