How To: Extend the Font Description Processor to Support Additional Characters

In a font description (.spritefont) file, the <CharacterRegions> area can be used to add additional characters to a font description, allowing an additional range of characters to be rendered using a SpriteFont.

For some languages this approach is not ideal. For example, Chinese and Japanese both have many thousands of characters. Adding the full range of characters to <CharacterRegions> would increase the size of the font asset, and the time required to build the font asset, dramatically. A better solution would add individual characters as needed. You can create a custom content processor to implement this solution.

This document describes the process of developing a custom content processor to add additional characters to a FontDescription object based on the text that is required by the game. In this example, all of the text that must be rendered by the game is contained in a file called messages.txt. The custom processor will add all of the characters contained in the text in this file to a FontDescription, and then process the resulting object in the standard way using the base FontDescriptionProcessor functionality. All of the characters in messages.txt will then be available to the resulting SpriteFont object at run time.

The Complete Sample

The code in this tutorial illustrates the technique described in the text. A complete code sample for this tutorial is available for you to download, including full source code and any additional supporting files required by the sample.

To Specify the Character Regions and Messages to Process

  1. Add a new Sprite Font called DefaultFont to a game project by right-clicking on the nested Content node in Solution Explorer and clicking Add, then clicking New Item. Select the Sprite Font template, then click Add to add the new sprite font to the game.
  2. Modify this file to use an existing font and any additional characteristics you prefer. For more information, see Sprite Font XML Schema Reference.
  3. Add a file named "messages.txt" to the game project. Right-click on the game project node in Solution Explorer and click Add, and then click New Item. Select the Text File template, enter messages.txt for the file name, and then click Add to add the text file to the game.
  4. In the new text file, enter any messages that will be printed by the font described in the Sprite Font file.

    We will use the method File.ReadAllText to read the text in this file. This method requires a carriage return ("\r") or line feed ("\n") after the last string, so be sure to follow the last line of text in the file with a carriage return or line feed.

To Create the New Content Processor Project

The Content Pipeline is part of the build process and is separate from your game code. Therefore, you need to create a new assembly that contains the code developed in this topic. Creating this new assembly project is the first step in developing a new processor.

It is assumed that you have an existing game project that you will modify. For the purposes of this example, the game project is called "FontGame."
  1. Add the new processor project to the game solution. From Solution Explorer, right-click the Solution node, click Add, and then click New Project. From this dialog box, select the Content Pipeline Extension Library (2.0) template, enter FontProcessor in the Name field, and then click OK.
  2. The new project automatically contains references to the XNA Framework run-time and design–time Content Pipeline assemblies.

To Extend the Font Processor

  1. Add the following lines of code, after the last using statement:

    using System.IO;
    using System.ComponentModel;
  2. In ContentProcessor1.cs, remove the following code, located near the top of the file:

    // TODO: replace these with the processor input and output types.
    using TInput = System.String;
    using TOutput = System.String;
  3. Using attributes, add a processor parameter to the beginning of the class declaration. This parameter stores the name of the text file that stores the messages displayed by the game.

    [DisplayName("Message File")]
    [Description("The characters in this file will be automatically added to the font.")]
    public string MessageFile
        get { return messageFile; }
        set { messageFile = value; }
    private string messageFile = "..\\messages.txt";
  4. Change the derivation of ContentProcessor1 from ContentProcessor to FontDescriptionProcessor.
  5. Modify the Process method override to match the following code:

    public override SpriteFontContent Process(FontDescription input, ContentProcessorContext context)

    This modification replaces the template parameter and return types with the proper types needed for the extended font processor.

  6. Register a Content Pipeline dependency on messages.txt. This dependency tells the Content Pipeline that if messages.txt changes, the font must be rebuilt.

    string fullPath = Path.GetFullPath(MessageFile);
  7. Read the contents of the file and add each letter to the input font one by one. Note that the Characters collection keeps track of duplicates automatically. It is not necessary for the user to make sure that each letter is added only once. The Characters collection will contain only one instance of each character; no matter how many times Add has been called.

    string letters = File.ReadAllText(fullPath, System.Text.Encoding.UTF8);
    foreach (char c in letters)

    In this example, messages.txt has been saved with Unicode UTF-8 encoding, which is why this encoding format is specified in the call to File.ReadAllText. The default file encoding format for text files that have been added to a Visual Studio project is Western European (Windows) encoding, corresponding to code page 1252. If your text file uses the default encoding, specify the character encoding as follows:

    string letters = File.ReadAllText( fullPath, System.Text.Encoding.GetEncoding( 1252 ) );
  8. Finally, call the existing Process method of the base FontDescriptionProcessor to build the font with the newly requested characters.

    return base.Process(input, context);

To Associate the Custom Font Processor with the Sprite Font

  1. Compile the solution to build MyFontProcessor.
  2. Add your custom font processor as an available content processor for the game. From Solution Explorer, right-click the Content node, and then click Add Reference. From the Projects tab, select your content extension project (FontProcessor) node and click OK.
  3. To ensure that the processor project is always up-to-date when the main game is built, create a project dependency. In Solution Explorer, right-click the game project (FontGame) node, and then click Project Dependencies. Select the check box next to FontProcessor, and then click OK to add a new dependency so that FontGame depends on FontProcessor.
  4. Finally, change the content processor for the .spritefont file from Sprite Font Description - XNA Framework to the newly created processor. Select the .spritefont file, and then in the Properties window, choose your custom processor from the drop-down list associated with the ContentProcessor field.

When you build the solution, the new processor adds the characters in messages.txt to the list of characters available to the SpriteFont.


To debug a Content Pipeline importer or processor, add the following line to the processor code to launch the debugger.


Community Additions