Creating Pocket PC games that publish high scores in web

By Andrey Lebedev, January 13, 2003.
Print version

Introduction

Playing games is more interesting if you can compare your results with those of other people. Spb Software House along with PocketGamer.org has developed an open system for creating Pocket PC games that supports publishing high scores in web. This system consists of a scores section of the PocketGamer.org website, a freeware program for desktop PC that retrieves high scores from the connected Pocket PC and a C++ library for creating Pocket PC games with high scores support. This article explains how to use this library in your games.

Background

Almost every game application has a high scores (or records) table. Each developer who writes a game has to implement a high scores table and he does this in his own way using his own data format. By the way, he must provide data integrity checking.

The Pocket Highscores library does all these and many other tasks for you, simplifying the development process significantly.

There is also a freeware program for desktop PC - Pocket Highscores that allows users to publish their high scores in web. You can distribute this program along with your Pocket PC games that use Pocket Highscores library. The high scores will be published to the PocketGamer.org website. Users will be able to compare their results and take part in monthly contests organized by PocketGamer.org.

About Pocket Highscores system

Pocket Highscores system consists of 3 parts:

• a C++ library for creating Pocket PC games that support high scores
• a freeware program for desktop PC that retrieves high scores from the connected Pocket PC and allows user to publish them in web
• a scores section on the PocketGamer.org website where all high scores are published to.

What You Need

• Microsoft eMbedded Visual C++ 3.0
• Pocket Highscores library - HighScores.h

About Pocket Highscores library

The library loads/saves/enumerates/modifies high scores located in a HighScores.sco file in your folder. It supports crypto signature to prevent cheating.

The library is implemented as a single h-file with three classes in it (CHighScores, CByteStorage, CCryptoHashMD5). CByteStorage class is a simple memory stream, CCryptoHashMD5 is a wrapper around md5 algorithm. The Highscores library doesn't use MFC and therefore it can be used in both MFC and non-MFC projects.

CHighScores class is a container for a limited number of high scores records with an ability to load the list from a file or a memory stream, to save the list into a file or a memory stream, to add, sort and enumerate the high scores records. Each high score record keeps the following information:

• player name (string)
• score value (integer)
• additional information (string).

The Additional information can contain any auxiliary string data.

Here is the CHighScores interface:

Using the Highscores library

Initialization

Define a variable of CHighScores class: it's a good idea for this variable to exist during the whole application lifetime. For example, in MFC application the best place for the high scores variable will be a field of the application object.

Pass the following data into the constructor: the maximum number of high scores records to be kept in the list and the "magic" string to be used in the encryption for security purposes.

To specify the game application and its version use the following methods: SetAppName(), SetAppID() and SetAppVersion(). This data will also be placed into the high scores file and will be saved during the next save operations and loaded during the load operations.

Loading from file

To load the high scores list from a file call the Load method passing there the directory path where the high scores file (HighScores.sco) is placed:

If load operation succeeds, the Load method returns HS_OK value. If an error occurs then it returns one of HS_XXXX or HSL_XXXX constant values. If the signature check succeeds then the IsSignatureOk() method will return TRUE, otherwise FALSE. The failure of the signature check will not cause any error in the load process, but during the save process it will be checked whenever the signature check succeeded or not (see the description of the save process).

The high scores list is automatically sorted after each loading.

Saving to file

To save the high scores list into a file call the Save method passing there the directory path where the high scores file (HighScores.sco) should be placed:

The second (boolean) optional parameter of the Save method only makes sense in a case of the signature check failure during the previous load operation (call the IsSignatureOk() method to check this). The parameter indicates whether to add the security signature to the high scores file or not. If no parameter is passed, the FALSE value is assumed (this is a recommended value for security purposes).

If save operation succeeds, the Save method returns HS_OK value. If an error occurs then it returns one of HS_XXXX or HSS_XXXX constant values.

Enumerating the high scores

To list the scores (in the dialog box or wherever you want) call the FirstRecord() method first to move to the beginning of the records list, then iteratively call the GetNextRecord() method. Both methods return a boolean value indicating whether there exists a record or not.

Adding a new score

To add a high score record into the list use the AddScore() method. It checks whether the passed score value is "high" - that is if the value should be placed in the top scores table (checking the maximum number of records in the table, etc.).

Important: the score value should be nonnegative, the player name should not contain "|" characters. The list is not automatically sorted after each score insertion, therefore you should sort it by calling the Sort() method.

Misc

You can save and load the high scores list from the memory stream (CByteStorage class): the appropriate methods are SaveIntoBS() and LoadFromBS() which are boolean. After calling LoadFromBS() you can also check the IsSignatureOk() value as described above.

Step by step

1. Download HighScores.h file
2. Add this file to your project
3. Choose a key that will be used for high scores signature ("magic string")
4. Add code that uses CHighScores class for loading/saving/displaying scores in your game
5. Register your game at PocketGamer.org - http://www.pocketgamer.org/scores/add.php
6. In case of any questions contact Spb Software House support

Conclusion

You can save your development time and make your Pocket PC games more attractive to users by using Pocket Highscores library.

Related resources:

• Section: GAPI
• Library: STGapiBuffer
• Library: GapiDraw
• Library: EasyCE
• Library: GAPI for Emulator
• Library: Pocket GL (iPAQ and Cassiopeia)
• Library: GapiTools
• Control: ASpriteCE Game Control
• Article: Drawing images and other graphics with GAPI
• Article: GapiDraw from a DirectDraw developers perspective
• Article: Creating a new project with GapiDraw
• Article: Programming DieselEngine 2. Using Diesel3D
• Article: Programming DieselEngine 1. Close up and personal with DieselEngine, Using DieselGraphics
• Article: Getting Started with the Game API
• Article: Here Comes GAPI!
• Article: PocketPC Advanced Graphics & Games Programming Tutorial. Part 1 - Getting started with EasyCE
• Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 2 - Advanced tricks with pixels
• Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 3 - Pixel warps and displacement tables
• Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 4 - Buffers, pointers and sprites
• Article: Pocket PC Advanced Graphics & Games Programming Tutorial. Part 5 - Rotozooming and fixed point arithmetic
• Article: Sprite
• Article: Animation
• Article: Timer call back
• Article: Scrolling background
• Article: Object collision
• Article: Off-screen technique

Discuss