Theming in Tux Typing 1.5.13

A "Theme" is a method to change the data which Tuxtyping uses. While this could be used to change the game about Tux and fish, to a game about a Cat and mice, more likely you are interested in making Tuxtyping work in another language. (if you are intersted in creating a new graphical theme like "Racecars" or ... that is cool too, but if things don't act right, please contact us).

I will walk through how I created the "French" theme in boxes in this text.

Difference to Tuxtyping 1.0

In Tuxtyping 1.0, to create a theme, you needed to recreate every image file that was used by the game. This means you had to include every image even if you didn't change it. Plus all the text in the game were actually pre-created graphics, and the game could only use A-Z.

In Tuxtyping 1.5, you can can include changes to the image files, but if you don't include one, we will just use the default image included with the default theme (English). Also instead of all the text in the game being pre-created, it is all rendered, so you can change the font and/or the text very easily. Plus, you can change it so you include numbers, or anything else you can type!

Changes since 1.5.0 Theming Howto:
  • Keyboard.lst format changed to eliminate redundant information
  • themes.txt is no longer used... we create the list dynamically
  • words.lst is no longer used.. we create the list dynamically
  • The title of a wordlist is the first line of the file
All these changes were done to make it even easier to theme...

Components of a Theme

  1. Creating the directory and adding it to menu system

    Themes are located in the data directory of Tux Typing. This will be different depending on which operating system you are using. If you have trouble finding where the data directory is for your system, contact us. I will refer to this directory containing themes as data/themes/

    Each theme has its own directory in the data/themes/ directory. For instance if you are creating a French theme, you would create a directory called french in the themes directory, so you have data/themes/french. All of the data for your theme will be located in this directory.

    Now if you go into the game, you should see a new entry in the "Setup Languages" menu for your theme. 

        cd data/themes

    mkdir french

  2. Fonts

    Tux Typing currently uses three fonts (AndikaDesRevG.ttf, DoulosSILR.ttf, and Rachana_w01.ttf) to provide glyphs for the included themes. The default font is Andika, which has glyphs for English and other Western European languages. Doulos has wider coverage, and is included to support the Cyrillic characters needed for the Russian theme. Rachana provides glyphs for the Malayalam theme. If your theme works with the default Andika font, you do not need to specify anything. If one of the other fonts is needed, your theme directory needs to have a file "settings.txt" containing a line indicating your font selection, e.g.:
    theme_font_name=Rachana_w01.ttf
    Currently, the font name must exactly match one of the supported fonts, or you will wind up with the default. Note - all non-ASCII text needs to be encoded as UTF-8. This is not an issue for file names, but it is an issue when adding themes that require Unicode support.

    If you want to customize Tux Typing with another font, you can copy the *.ttf font file into data/fonts/ (alongside Andika, Doulos, and Rachana) and put the exact font file name into your theme's settings.txt file, and Tux Typing will use it.

  3. Translation

    To change the words that are within the menus and other parts of the game, you will need to create and edit a lang.po file. We have created a master lang.po file that is located in the data/themes directory. To start with, you should copy this file into your theme's directory. 

        cd data/themes

    cp lang.po french/lang.po

    This file is your your standard "gettext" type .po file. It is comprised of a sequence of msgid & msgstr pairs. The msgid is the string of words in English, what you will need to do is after edit each msgstr in the file so it corresponds to the msgid right about it. If your language uses non-Western Unicode characters, be sure to use a UTF-8 encoding for this file!

    For instance my data/themes/french/lang.po has the following lines: 
        msgid "Fish"
    msgstr "le Fish"

    msgid "Lives"
    msgstr "le Lives"

    msgid "Level"
    msgstr "le Level"

    msgid "Alphabet"
    msgstr "le Alphabet"

    Since I do not know french, but if I did, I may have had the following in the file: 
        msgid "Fish"
    msgstr "Poissons"

  4. Setup the keyboard

    Now you need to setup what characters (like ABCDEFGHIJKLMNOPQRSTUVWXYZ), you are going to have the player hit within the game. There are several things you need to specify. First let me explain with an example. In the English version, we don't mind if the user hit "A" or "a", we want it to mean the same thing "A" (we choose uppercase (capital) letters since they are easier to read). We also need to specify that the player would normally use the "0" finger to hit the key (see image)

    0 1 2 3 4 5 6 7 8 9

    So you need to create a keyboard.lst file. This file will contain all the characters that you wish to be typable. The format for the file is:

    0|A

    First you list the finger(s) that the player should use to press this letter, then a seperator |, then the character that the user can press. Each character is on its own line (this is changed from earlier versions of Tux Typing). Thus, one line should be "0|A" and another line "0|a". Tux Typing generates the list of allowed characters from this file. This is not the same as your theme's alphabet, which should consist only of the characters that correspond to "letters". 

        cd data/themes/french

    vi keyboard.lst
    Then I add the following lines to the keyboard.lst file: 
        0|A
    0|a
    3|B
    3|b
    2|C
    2|c
    2|D
    2|d
    2|E
    2|e
    3|F
    3|f
    and so on for each letter including non A-Z characters if needed! Tux Typing will use this list to determine which characters to pre-render (as well as for fingering hints), so be sure to include *all* characters needed for your theme, as omitted characters may not be able to be displayed. (I am trying to find a cross-platform way to query the OS as to what Unicode values can be typed by the user's current keyboard setup - if anyone has any ideas, please post to the dev list).

  5. Word Lists

    This is where you create the words that the player will have to type within the game. The word lists reside within the directory words in your theme's directory. Create this directory now. 

        cd data/themes/french

    mkdir words

    Then all that is left to be done is to create these word lists (soon this will be able to do this from within the game!) The first line of each wordlist should be the title of the wordlist. After that, list all the words (one on each line). If list contains any non-Western Unicode characters (i.e. Unicode value > 256), the file must be encoded as UTF-8. For instance data/themes/french/words/words1.txt is: 

        Jesse's French Words
    LIV
    POISSION

    The only thing you need to remember is that each word can only be up to 8 characters long. Also the game ignores ANYTHING after the first space. If this is an issue, please let us know!

    The MOST important step.

    You should send this file into the Tux Typing group so that it can be included in the distribution. That way anyone who downloads Tux Typing can use your theme without having to download your theme as well!

    TuxTyping Homepage             TuxTyping Forums             dbruce@tampabay.rr.com

    Last edited Sept 04, 2007 but by no means fully up-to-date!