Leaderboards

Currently Leaderboards can be edited by developers on the website. It's a pretty hefty interface and a difficult job to get a leaderboard working just right. It genuinely takes some care and attention to get a good leaderboard working, so in this doc we'll try to understand how it works.

Overview

This is how a game's Leaderboard List looks like on the website:

In the center you can see every already made Leaderboard, and in the right column you can see the Code Notes for the game. The Code Notes are here to help with some conditions we'll see below.

Here's a brief explanation of each field of a single Leaderboard:

• Title: the leaderboard's title.
• Description: the leaderboard's description.
• Format: it can be Score, Time (Frames), Time (Milliseconds) or Value. It's used to distinguish what sort of leaderboard this is (we'll go into this below).
• "LowerIsBetter" checkbox: when checked, it means that a lower value is a better thing. It's usually the case for time based leaderboards, whereas a larger score generally is better.
• Start: start conditions, aka STA.
• Cancel: cancel conditions, aka CAN.
• Submit: submit conditions, aka SUB.
• Value: a value interpreter, aka VAL.

Note: A valid leaderboard MUST have all four of these conditions.

Those last 4 fields are really important and LOTS of care must be taken over the entry of any characters into these strings. That's why they deserve a further explanation:

The STA or Start condition is a series of values, like an achievement, that must be true in order to start looking for a leaderboard submission. Once the STA is true, the game will activate the other three, and will keep processing them constantly.

If a Cancel (CAN) condition is true, then it will cancel the leaderboard and no score will be submitted.

If the Submit (SUB) condition is true, then the leaderboard score will be submitted. NOTE: Cancel is given priority over Submit. If both become true in the same frame, the score will not be submitted.

Finally, the Value (VAL) is a special case, and will be taken from memory using the formula stated in the memory box. This is the score that gets displayed while the leaderboard is active, and the value that's submitted if SUB is true.

NOTE: Once an active leaderboard is cancelled or submitted, it cannot be reactivated until the Start condition becomes false, then true again. This prevents the leaderboard from immediately reactivating after submission/cancel.

Logic Symbols

Place these symbols in/between conditions to cause the stated effects:

Symbol	Where to Use the Symbol	Meaning
=	Connect an address with a value/another address	equals
!=	Connect an address with a value/another address	does not equal

| Connect an address with a value/another address | is greater than = | Connect an address with a value/another address | is greater than or equal to < | Connect an address with a value/another address | is less than <= | Connect an address with a value/another address | is less than or equal to _ | Connect two conditions | and s | Connect two conditions | or $ | Connect two addresses (only in Value Interpreter) | max/use highest value

Address Format

The memory addresses for STA/CAN/SUB/VAL have the following format:

location/size	prefix (the letters can be in lower case)	example
bit0	0xM	0xM01234
bit1	0xN	0xN01234
bit2	0xO	0xO01234
bit3	0xP	0xP01234
bit4	0xQ	0xQ01234
bit5	0xR	0xR01234
bit6	0xS	0xS01234
bit7	0xT	0xT01234
Lower4	0xL	0xL01234
Upper4	0xU	0xU01234
8bit	0xH	0xH01234
16bit	0x	0x01234
32bit	0xX	0xX01234

Example

The best place to start is to look at one of the existing leaderboards https://retroachievements.org/leaderboardList.php and break it down to see how it works. We're going to use the Green Hill Act 1 (Sonic the Hedgehog) Leaderboard for this purpose. Then let's see how it looks:

The Title/Description fields are quite obvious.

The Type is "Time (Frames)". In Sonic every 60 frames is 1 second, then we'll monitor the time using the frames.

The Lower Is Better flag is checked, then the one who makes the shortest time will be the #1.

Now we're going to break down the most important parts.

Start Conditions

STA: 0xfe10=h0000_0xhf601=h0c_d0xhf601!=h0c_0xfff0=0

• 0xfe10=h0000: If 16-bit RAM address 0xfe10 is equivalent to hex 0000,
• _: AND,
• 0xhf601=h0c: If 8-bit RAM address 0xf601 is equivalent to hex 0c,
• _: AND,
• d0xhf601!=h0c: If the previous 8-bit RAM address 0xf601 is NOT equivalent to hex 0c,
• _: AND,
• 0xfff0=0 If 16-bit RAM address 0xfff0 is equivalent to 0.

This might seem daunting, because we don't know what these addresses mean. That's why the Code Notes in the right column are pretty handy! You can see how these addresses are labelled in memory. In our example we have:

• 0xfe10 is the level, and is expected to be 0 (the first level).
• 0xf601 is an 8-bit memory address, and we use the prefix 0xh instead of 0x to signify this. The 0xf601 is the screen mode. The second and third parts of the start statement are saying "the current mode should be ingame (0c), and the mode on the previous frame should NOT be ingame". Note: that d prefix on the address represents delta, or "the previous frame's value". Summing up: trigger this if we've JUST arrived in a level (the start of the level, when we want to start testing their time).
• Finally we also expect 0xfff0 to be equivalent to 0, because this address is used for demo mode, and we don't want to award a leaderboard entry when the demo is active!

Tip: the most common mistake when creating leaderboards is forgetting the h when trying to reference an 8-bit memory address.

Pro-tip: STA, CAN, and SUB support all logic available in the achievement editor. The easiest way to make sure you get them written correctly is to create local achievements that capture the events, then extract the serialized values from the "XXX-User.txt" file associated to the game you're working on.

Cancel Conditions

CAN: 0xhfe13<d0xhfe13

• 0xfe13 is the number of lives.

The cancel section checks if the player's LIVES counter ever becomes lower. Literally, it says "Cancel if the CURRENT value at 0xfe13 is less than the PREVIOUS value at 0xfe13". We want to do this because you could reach the final checkpoint and run out of time, resetting your timer to 0:00. We don't want to allow this, because it's not the correct way of completing the level. So if the player dies, we reset their leaderboard progress.

Submit Conditions

SUB: 0xf7cc!=0_d0xf7cc=0

• 0xf7cc is the endlevel flag, non-interactive.

The submit section checks if the current frame has the 'endlevel' flag set to true (or !=0, 'nonzero'), and the previous frame (delta) has it set to false (or =0, 'zero'). This suggests that the player has reached the end of the level, and has proven to be a fairly sturdy benchmark.

Tip: it can be useful to watch these values in memory to see how they perform, and what sort of values they end up at in different circumstances.

Value Interpreter

See also: Binary Coded Decimal

VAL: 0xhfe24*1_0xhfe25*60_0xhfe22*3600

Finally, value. Once the player has reached the start condition, they will be shown a popup which remains on-screen, showing their progress so far. If it's a time leaderboard, it will be a clock, and if it's a score, it will just be the value. If they fulfill the cancel condition, they will be told that they have failed, and the popup will be removed. If they successfully reach the submit condition, the current value will be taken and submitted as their score, and on successful submission, an ingame popup will inform the player of the leaderboard so far, and their position in the leaderboard.

The value condition is special in a few ways. It is evaluated constantly and shown on-screen all the time when the leaderboard is active. It doesn't work like the other conditions, it expects addresses in the following way:

address*modifier (address times modifier)

and it uses the _ underscore operator as a 'plus'. The * asterisk signifies 'multiply', so in the value

0xhfe24*1_0xhfe25*60_0xhfe22*3600

represents:

8-bit 0xfe24 times 1, PLUS 8-bit 0xfe25 times 60, PLUS 8-bit 0xfe22 times 3600

The reason for this is that the values in each of these addresses signifies frames, seconds, and minutes respectively. When we add these values together, we get a grand total in frames that we submit to the database.

Remember that 'Format' field that can be either Score, Time (Frames), Time (Milliseconds) or Value? Time (Frames) is the most common one, and represents 'frames'. Time (Milliseconds) expects a value that we can convert directly into millisecs (Super Mario Kart uses this). However to convert a value in frames into a human-readible format, we should divide the value by 60 to get an accurate representation of seconds, and a value in millisecs should be divided by 100 to get the number of seconds. This is used both on the website and in the app to display the value properly, and is important to distinguish so we can be sure we get the most accurate value out of the emulator, by using whatever format they use to record time.

NOTE: Time (Milliseconds) is actually hundredths of a second, not thousandths of a second. i.e. a Value of 6234 would be 62.34 seconds, not 6.234 seconds.

Tip: modifier is a decimal value, so if you need to divide by two, you can multiply by 0.5: 0xhfe24*0.5

Further help

There are unfortunately MANY ways to get this process wrong, so if you are having any trouble feel free to ask for help in our Discord server.

If you want to practice, it's highly recommended to create your own leaderboard and attempting something on a new game, rather than using an existing leaderboard.

Please remember that these files are pulled directly into someone's game if they decide to play it, and a badly formed memory address or string could cause their emulator to crash, so please test your leaderboard code!