PocketDice

• Download source project (C#) - 29.8 KB
• Download CAB files - 120 KB

Introduction

I enjoy having some simple, small games on my PDA to offer a few minutes of distraction when needed. PocketDice, a variant of the dice game Yacht, is offered here as an entry for the Mobile Development Competition and to offer PocketPC owners a few free diversionary minutes. Code examples for persisting high scores and displaying online help are presented following a description of the game.

Playing the Game

PocketDice is a variant on the dice game Yacht with the twist that the dice values are suited like playing cards (clubs, hearts, diamonds, and spades). On each turn the player is allowed up to three rolls of five dice. On a second or third roll, the player may re-roll any or all of the dice. Clicking the Roll button rolls all "unlocked" dice. Tapping a die toggles whether the die is locked or unlocked.

Following any of the three rolls, the player may choose to score by tapping any available scoring box. A scoring box may be used only once in a game. If following a third roll, the player must choose an available scoring box. Points are awarded for a score according to the following table:

In addition to the points above, a Bonus value of 35 points is added if the sum of the Aces through Sixes scores total 63 or more. When scoring, an Ace is considered to have a value of one.

The game is over when all scoring boxes have been used.

Code Structure

The project, targeting the .NET Compact Framework, includes four form classes and several other supporting classes.

Forms and Control Classes

The following forms comprise the user interface for the application:

Supporting the main form are two custom control classes: SingleDie and ScoringBox. Each overrides OnPaint() for its custom display.

Application Data

High Scores for the application are persisted in an XML file through functions in the Data class. The Data constructor attempts to load the scores from the persisted file with an XmlTextReader; if the file doesn't exist, a blank score array is created.

public class Data
{
    const int kMAX_HIGHSCORES = 10;
    const string kDATA_FILE = @"\Program Files\PocketDice\data.xml";

    private HighScoreRecord[] _list;
    
    . . .

    public Data()
    {

        // check if a high scores data file already exists
        // if not, use a blank score array and we'll
        // save it later
        _list = new HighScoreRecord[kMAX_HIGHSCORES];
        int count = -1;
        XmlTextReader xml = null;
        FileStream stream = null;

        try
        {
            stream = new FileStream(kDATA_FILE, FileMode.Open);
            xml = new XmlTextReader(stream);
            xml.MoveToContent();
            
            while (xml.Read())
            {
                switch (xml.Name)
                {
                    case "HighScore": 
                        count++;
                        if (count < kMAX_HIGHSCORES)
                        {
                            _list[count] = new HighScoreRecord(xml);
                        }
                        break;
                }
            }

            count++;
            if (count < kMAX_HIGHSCORES)
            {
                for (int i=count; i<kMAX_HIGHSCORES; i++)
                {
                    _list[i] = new HighScoreRecord();
                }
            }
            
        }
        catch (System.IO.FileNotFoundException)
        {
            // file isn't here; initialize the structure for later saving
            for (int i=0; i<kMAX_HIGHSCORES; i++)
            {
                _list[i] = new HighScoreRecord();
            }
        }

        catch (Exception ex)
        {
            System.Windows.Forms.MessageBox.Show(
                ex.ToString(), "Error Loading High Scores");
            for (int i=0; i<kMAX_HIGHSCORES; i++)
            {
                _list[i] = new HighScoreRecord();
            }
        }

        finally
        {
            if (xml != null) xml.Close();
            if (stream != null) stream.Close();
        }

    }
    
    . . .
    
}

The HighScoreRecord class, also found in the source file Data.cs, contains a constructor which takes the XmlTextReader as a parameter.

  public HighScoreRecord(XmlTextReader xml)
  {
    // read attributes given this XmlTextReader
    _score = int.Parse(xml.GetAttribute("score"));
    _name = xml.GetAttribute("name");
    _date = XmlConvert.ToDateTime(xml.GetAttribute("date"), "yyyy-MM-dd");
  }

A Data object is created in the Load event handler for frmMain. Its Save() method is then called in frmMain's Closing event handler, persisting the scores with an XmlTextWriter:

public class Data
{
    . . .
    
    public void Save()
    {

        // before saving, sort the HighScores array
        SortHighScores();

        // now attempt to save;
        XmlTextWriter xml = null;

        try
        {
            xml = new XmlTextWriter(kDATA_FILE, System.Text.Encoding.ASCII);
            xml.WriteStartDocument();

            // write the HighScore list
            xml.WriteStartElement("HighScores");
            for (int i=0; i<_list.Length; i++)
            {
                _list[i].WriteXmlRecord(xml);
            }

            xml.WriteEndElement();  // </HighScores>

            xml.WriteEndDocument();
        }
        catch (Exception ex)
        {
            System.Windows.Forms.MessageBox.Show(ex.ToString());
        }
        finally
        {
            if (xml != null) xml.Close();
        }

    }

}

Called in the Save() method, the HighScoreRecord object's WriteXmlRecord() method takes care of persisting its high score properties:

public class HighScoreRecord
{
    ...
    public void WriteXmlRecord(XmlTextWriter xml)
    {
        xml.WriteStartElement("HighScore");
        
        xml.WriteStartAttribute("score","");
            xml.WriteString(_score.ToString());
        xml.WriteEndAttribute();

        xml.WriteStartAttribute("name","");
            xml.WriteString(_name);
        xml.WriteEndAttribute();

        xml.WriteStartAttribute("date", "");
            xml.WriteString(_date.ToString("yyyy-MM-dd"));
        xml.WriteEndAttribute();

        xml.WriteEndElement();
    }
    
}

Points of Interest

When considering how to display online help, I decided that I wanted some formatting and elected to use an HTML file. The article Launching Applications and Resuming Processes [^], from the .NET Compact Framework QuickStart Tutorial [^], was very useful in offering a means for launching a process. I added a function OpenWebPage() and wrapped it in the Launcher class of the project. This is used to open the HTML file containing game instructions.

Summary

PocketDice, a variant of the dice game Yacht for PocketPC, provides a simple diversion, taking only a few minutes to play a full game. Code samples in the article demonstrate the use of XmlTextReader and XmlTextWriter objects for persisting game data in an XML file, and code borrowed from the .NET Compact Framework QuickStart Tutorial to launch processes offers a solution for displaying an HTML file for online help. Enjoy the game!