MGS

MSX Game Scores (MGS) is an online leaderboard platform for MSX games: https://aoineko.org/mgs.

It allows players to submit their high scores using codes generated by the games themselves. Developers can integrate score encoding into their games, and once submitted, the scores are verified server-side and displayed on public leaderboards. The goal is to bring a modern, competitive scoring system to new MSX games.

Note: The MGS site has the same author but is not directly linked to MSXgl, even though this library includes tools to help generate score code.

How do I add my game to MGS?

Generate a score code

The basic idea is that your MSX game must generate a code that encodes the relevant data:

• the score,
• the corresponding leaderboard (if there are several),
• and any other useful information for your game.

For example, in a racing game, besides the time to complete the race (the score) and the track (the leaderboard), you might also want to record the used car model, whether the player used a manual or automatic gearbox, etc.

You are free to use any technique you want to encrypt your data. Just make sure the encoding is strong enough to prevent someone from inputting random codes and getting a valid score. MSXgl provides a C module for encoding data than can be easily adapt to other development environment.

Add your game to MGS

After that, the game and its leaderboards have to be added to the MGS site. For now, this is a manual process that is handled directly by the site owner (MRC user Aoineko).

Finally, the interface for converting score code to leaderboard entry needs to be created. It consist of several PHP functions (the site owner can help you write them).

Decode

If you are not using MSXgl encryption feature in your MSX game, you will have to provide your own decrypt function in PHP (a language that looks a lot like C).

This function have to check the validity of the submitted code and, if valid, generates the entry to be added to the leaderboard.

Function prototype:

// Decode a string and if valid, output a data stream and return true
// Parameters:
//  $code       [in] Crypted code
//  $key        [in] Decoder key (game specific)
//  $data       [out] Data stream (bytes array)
// Return:
//  true if decode succeed
function Decode(string $code, string $key, array &$data): bool {}

Initialization

This function is used for game specific initialization. This function can be empty.

// Initialize score submission
function InitializeSubmission() {}

Columns description

This function describe the format of each column in addition to the 3 defaults columns: - Rank - User name - Time stamp

Example of adding a single score column:

// Get metadata format
// Return:
//  Array describing the format of each table row
function GetMetaFormat(): array
{
	$metaStruct = array(
		"score" => BOARD_TYPE_INT,
	);
	return $metaStruct;
}

Column format can be:

define("BOARD_TYPE_BOOL",	0x00); // Boolean
define("BOARD_TYPE_INT",	0x01); // Integer number
define("BOARD_TYPE_FLOAT",	0x02); // Float number
define("BOARD_TYPE_SEC",	0x05); // Time in seconds
define("BOARD_TYPE_MIN",	0x06); // Time in minutes
define("BOARD_TYPE_TIME",	0x07); // Time
define("BOARD_TYPE_DATE",	0x08); // Date
define("BOARD_TYPE_STRING",	0x0A); // Character string
define("BOARD_TYPE_IMAGE",	0x0F); // Image URL
//-----------------------------
define("BOARD_TYPE_HIDE",	0x10); // Meta-data not to be displayer

Validate data

This function will validate then convert the input data stream (bytes array) into leaderboard entry.

Example:

// Validate decoded data
// Parameters:
//  $data       [in] Decode bytes list
//  $board      [out] Board to add the score in
//  $keyValue   [out] Key value for sorting (ascendent)
//  $metadata   [out] Score metadata (encoded JSON)
// Return:
//  true if validation succeed
function Validate(array &$data, string &$board, int &$keyValue, string &$metadata): bool
{
	// Validate data size
	if(count($data) < 1)
		return false;

	// Extract data from bytes array
	$score = $data[0];

	// Set output variables
	$board = "myboard"; // The leaderboard to add the entry
	$keyValue = $score; // The integer value used for rank sorting

	// Create board metadata
	$metaStruct = array(
		"score" => $score,
	);
	$metadata = json_encode($metaStruct);
	return true;
}