l

p

a

h

a

i

l

t

e

s

setup

instructions

March 2025

before getting started

These literacy games are designed for use on Android cell phones. Before getting started:

​

1. Read through this guide. This will prevent unnecessary work renaming files, recropping images, etc.
2. Will you use locally photographed images (.jpg) or will you use icons (.png) from a site like Flaticon/? Local photographs better reflect the uniqueness of each culture, but these images will make the app size much larger. If you are aware of culturally diverse image (.png) collections like SIL Mexico’s ARCODI images, please let us know at alpha_tiles@sil.org.
3. Ensure you collect necessary image and audio permissions as you prepare your media files. SIL International has a Flaticon premium license which can be used for Alpha Tiles apps published through SIL.
4. Alpha Tiles currently requires Android 6.0 (compatible with 99.6% of existing devices as of December 2025)..

​

• The font Charis SIL will be used unless another font is requested.
• This document will guide you through the preparation of your “language pack.” Once the language pack is ready, SIL can assist you in creating the app. To create the app yourself using Android Studio, refer to the README information on Github.
• The optional Stages feature lets you introduce the most productive letters first, enabling students to read whole texts early. To follow this approach, you can introduce groups of letters in anywhere from 2 to 7 stages, allowing words to be built progressively, step by step.
• The Alpha Tiles code is open source.
• If you have any questions, please use our tech support Google Form.

before getting started

overview of steps

To get started, open our tech support Google Form and select “Set up new project”. We will then set up a Google Drive project folder with a Google Sheets template for your language. Then complete these steps:

​

REQUIRED

1. Language information list (langinfo tab)
2. Game tiles list (gametiles tab)
3. Word list (wordlist tab)
4. Keyboard keys list (keyboard tab)

​

OPTIONAL and/or DEFAULT VALUES ACCEPTABLE FOR INITIAL TEST APP

• Syllables list (syllables tab)
• Promoted websites list (resources tab)
• Settings list (settings tab)
• Names list (names tab)
• Games list (games tab)
• Colors list (colors tab)
• Share (share tab)

• Prepare images (.png o .jpg) (one for every word in wordlist)
• Prepare audio files in .mp3 format:
1. one for every word in wordlist
2. (optional) one for every tile in gametiles
3. (optional) one for every syllable in syllables
4. (optional) one instruction audio file for every game in games (note that the same instruction audio file can be used for multiple levels of the same game)
5. (optional) instruction audio files for choosing a player, editing the player name, choosing a game, the About page, and the Resources page
• Upload audio and image files to their respective project folders in Google Drive
• Contact Alpha Tiles to ask us to (1) validate your language pack, (2) build your app and (3) upload the .apk file (Android game app install file) to the project folder.

overview of steps

(1) langinfo

1. Fill out the yellow cells.
2. Do not insert or delete columns or rows
3. Do not rename the cells in white
4. For field 10 (The word NAME in local language), you may enter “custom” if you would like the app to use the list of names from the (8) names tab

(1) langinfo

• Language name in the local language
• Language name in English
• Language name in a regional/national language
• Ethnologue code
• Country
• Variant info (required field). Enter “none” if no variant.
• Game name in the local language
• Script direction: either “LTR” or “RTL”
• Audio and photo credits
• The word “name” or “person” in the local language. This name will be used on the opening Choose Player screen.
• Script Type
• Email
• Privacy Policy
• Audio and photo credits (lang 2)

​

(1) langinfo

(2) gametiles

(2) gametiles

1. Fill out the yellow cells.
2. Do not insert or delete columns
3. Do not rename the header rows
4. The elements in the “tiles” column are the game tiles. Note in the example that the letter “d” will always appear on its own tile |d|, except when followed by the letter “x”. In this case, “d” and “x” will appear together on the same tile, |dx|.

(2) gametiles

5. If the language has pairs of words like the English pair phone/haphazard (where the first word should have a game tile |ph| and the second word should have separate |p| and |h| game tiles, include “ph”, “p” and “h” as game tiles and in the word list use a period to force a tile break (e.g. hap.hazard).

(2) gametiles

6. The three columns (Or1, Or2, Or3) contain “distractors”. They are used to provide alternative (incorrect) answers. For example, in the word-builder game to the right, the player has compared the two tiles |r| and |l| in the leftmost column and has correctly selected |r|. The game tile |i| appears as an option because in the gametiles tab, the tile |i| is listed to the right of the row for the tile |r|. You should only select distractors from the tiles found in the first column of the gametiles tab.
7. The game randomizes which of the three distractors appears and whether the correct game tile appears above or below. This randomization means that, in the example to the right, there are 7,776 possible arrangements that the player might engage with the word.

​

(2) gametiles

• The Type column marks:
• V = vowels
• C = consonants
• T = tone markers
• X = other
• SAD = space & dash
• For languages where 95% of common words do not have spaces or dashes, it is recommended to exclude words with spaces or dashes. But for other languages, code the space tile and dash tiles as type SAD.

(2) gametiles

• Marking spaces and dashes as “SAD” type rather than “X” type ensures that the games will function properly with words containing spaces and dashes. For example, spaces and dashes will never be chosen as the missing tile or syllable in fill-in-the-blank games.

(2) gametiles

• For Thai, Lao and similar scripts, tiles can also be marked as type AD, AV, BV, FV and LV, which will trigger a second words-into-tiles parser that can handle discontiguous vowel complexes.

(2) gametiles

• If games are created using tile-based audio, those audio file names should be entered in the AudioName column.
• In the column Upper, enter the uppercase form of the tile. For space and dash, repeat the same character in the Upper column.

(2) gametiles

• In most cases, setup for multi-function symbols (columns H, I, J and K) is not necessary. See this YouTube video for more information.
• You do not need to fill out any fields in columns L, M and N.

(2) gametiles

• In column O you can assign a stage (1-7) to each tile. Use Columns P & Q to assign stages to multi-function symbols. (The default “-” puts tiles in stage 1).
• Use the validator report to ensure at least 12 words appear in stage 1. (Currently, games ensure words are not repeated across a span of 12 instances.)

In game 3 to the left, the missing tile will always be of type V.

In game 14 to the right, “p” is a distractor of “d”.

(2) gametiles

(3) wordlist

1. Fill out the yellow cells.
2. If you want to use syllable-based games, you must put periods between syllables in each word. If your words have spaces or dashes, you must put periods around the spaces or dashes. Example: o.pen.-.source
3. Do not insert or delete columns
4. There must be a header row with a Language of Wider Communication (LWC) name and after that a Language of Play (LOP) name.
5. WARNING!! The naming conventions for the LWC column (first column) are very strict. JAVA only permits the English letters a-z, the numbers 0-9 and underscore.

​

​

​

(3) wordlist

• How many words should be included? 300 words is recommended, but 100-150 words is a common starting point. A good goal is to include, for every game tile, one word that begins with that game tile (although there are of course some game tiles in some languages that never appear at the beginning of words).
• If you have more than 300 words, it is worth considering whether multiple apps should be made, perhaps dividing the words into semantic groupings or beginner/advanced groupings, etc.

​

​

​

​

(3) wordlist

• There is a fixed word-length limit of 15 tiles. However, it is recommended that you focus on shorter words (less than 10 tiles), which are easier for new readers.
• Columns C and E are not required. These fields have been deprecated.
• If you are defining stages for each tile, exceptions can be defined in column F. For example, the word “sol” might be a stage 2 word, but you can enter a different stage number in column F to override the stage that would have been determined by the tiles that the word contains.

​

​

​

(3) wordlist

(4) keyboard

1. Fill out the yellow cells.
2. If your words contain spaces, you must include a space key. Likewise for dashes.
3. Do not insert or delete columns
4. Do not rename the header rows
5. The order in which the keys are listed in the keyboard tab will be the order in which the keyboard is created in the game.

(4) keyboard

• The keyboard uses the color codes from the colors tab.

​

​

(5) syllables

• This tab is optional. You can make the app without syllable-based games.
• Fill out the yellow cells if you wish to use syllable-based games. If you don’t want syllable games, you can leave this sheet blank and move on to the next section.
• You can also use the tech support Google Form to ask us to generate a syllable list (column A) from your wordlist.
• All syllables that appear in words in the wordlist tab must be included in this list
• Space and dash are excluded from this table.
• Do not insert or delete columns.

(5) syllables

• Do not rename the header rows.
• The three columns (Or1, Or2, Or3) contain “distractors”. They are used to provide alternative (incorrect) answers. For example, in the word-builder game to the right, the player has compared the syllables in the first column and has correctly selected |chá| below and not |ché| above. The syllable |ché| appears as an option because, in the syllables tab, “ché” is listed as a distractor of “chá”. For distractor syllables, only use syllables that appear in column A as well.
• This game randomizes which of the three distractors appears and whether the correct game syllable appears above or below.

(5) syllables

• If you would like to include syllable audio in certain games, list the corresponding audio file names in the “SyllableAudioName” column. If you do not want to use syllable audio, fill in this column with “X”.
• The “Color” column indicates which color from your colors tab will appear as the background for that syllable in the Sudan game. This may help you to visually group syllables based on similarity in the Sudan game.
• Unlike tiles, syllables cannot currently be assigned to a stage.

In game 95 to the right, “bá” is a distractor of “lá”.

(5) syllables

(6) resources

• This tab is optional.
• Use the resources tab to promote web sites related to the language. NOTE!! The Google Play Console has rejected Play Store app submissions at least twice now when including a link to a Play Store listing.
• Fill out the yellow cells.
• Do not insert or delete columns
• Do not rename the header rows
• For each resource, a square image (.png or .jpg) should be uploaded to its respective project subfolder in Google Drive.
• For the third column (“Image”), enter the icon file name WITHOUT the extension suffix.

(6) resources

(7.0) settings

• This tab is required, but you can accept all default values when making the app. Typically, the person assigned to build the app will review and adjust these values before building the app.
• Fill out the yellow cells.
• Do not insert or delete columns or rows
• Do not rename the header rows

(7.1) settings

a

q

t

r

word list

art, tart, tar

tile list

a, q, r, t

SKIP

SKIP

t

a

r

t

a

r

t

a

r

t

t

a

r

t

a

r

t

t

a

r

a

r

t

t

a

r

t

t

a

r

a

r

t

t

a

r

t

t

a

r

a

r

t

t

a

r

t

t

a

r

a

r

t

t

a

r

t

t

a

r

If the symbol appears in the app instead of a word image, to fix, remove excess tiles or add illustrative words

Game 001

TRUE: display buttons allow users to toggle between the three modes for how Game 001 filters word lists (right image).

​

FALSE: the only available mode is defined by the previous setting (left image).

(7.2) settings

0.75

Setting = 1: nothing happens. The user can continue to play the same game.

​

Setting = 2: app returns users to game selection screen after checking 12 trackers.

​

Setting = 3: after 12 successful repetitions (12 checked trackers), the app displays a celebration screen and then moves on to the next incomplete game (less than 12 checked trackers).

​

​

celebration screen

for setting = 3

See Section F: Points for a more detailed explanation of the 12 trackers.

(7.3) settings

0.75

(7.4) settings

instruction audio icon

Number of avatars is customizable. If you include instruction audio for the choose player (choose avatar) screen, the maximum number of avatars that can be shown is 11. If you do NOT include instruction audio for this screen, the maximum is 12.

See Section C: Avatar Selection / Choose Player for a more detailed explanation.

0.75

For Learn the Tiles (“Romania”), often listed as Game 001, and for Tile/Syllable List (“Sudan”)…

​

TRUE: the game will show separate collections of words for each different tile Type.

​

FALSE: the game will place all words for a given tile in one collection regardless of Type

Gametiles tab:

(7.5) settings

0.75

Let’s say that the symbol |a| shown to the right can act as both a vowel and a consonant in this language.

TRUE would mean that the number 8 (in “1 / 8”) notes that eight words begin with the symbol as a vowel. Words beginning with the |a| symbol as a consonant would be a separate collection accessed using the blue arrows.

FALSE would mean that the number 8 notes that eight words begin with the |a| symbol regardless of the type and are grouped together in a single collection.

(7.6) settings

0.75

Default is 75% (0.75). Specifies the percentage of tiles in a word that must belong to a given stage for the word as a whole to belong to that stage. For example, if set to 60% (0.6), “cabin” would belong to stage 1 if stage 1 contains a,b,c,d, and e.

(7.7) settings

0.75

TRUE:

The first tile of a word MUST belong to a certain stage for the word as a whole to belong to that stage, regardless of whether the stage correspondence ratio is met. Ex: “faded” would not be included in stage 1 (a,b,c,d,e) even with a stage correspondence ratio of 80%, because the first tile “f” is not in stage 1.

​

FALSE:

Ex: “faded” would be included in stage 1 with a stage correspondence ratio of 80%

(7.8) settings

0.75

Maximum word length of stages 1 and 2 in terms of tiles

(7.9) settings

0.75

You may add an optional setting if you want your app to have an expiration date. For example, if you are testing your language’s orthography, you may want to distribute a temporary version of the app that expires after 30 days.

(7.10) settings

0.75

l

For the Guess the Word (Chile.java) game, you can specify the keyboard width, the number of guesses per round and the range of word sizes (in tile length) allowed.

​

This game does not consider the stage assigned to tiles or words. A word from any stage may be chosen as the word to be guessed.

(7.11) settings

For the Learn the Tiles (Romania.java) game, you can choose whether the focus tiles are displayed in Bold.

​

Select TRUE or FALSE for non-initial and initial tiles

(7.12) settings

(7.12) settings

(7.12) settings

(7.12) settings

(7.12) settings

For the Lotería (Bingo) (Italy) game, you can reduce the minimum number of tiles needed for a valid game. The game displays 16 words at a time, but selects from a larger set when playing the audio for each word.

​

The default minimum is 54 tiles. If the stage assigned to an Italy game instance has fewer than 54 words, you must lower this minimum. Steps 9-10 in the upcoming games slides explain how to assign a stage to a game instance.

​

If a stage has fewer words than the minimum, the game intentionally does not launch. The example below sets the minimum to 32 words.

(7.13) settings

(8) names

• This tab is optional. You can make the app using the default name structure, which uses the word for “name/player” in the local language from item 10 in the langinfo tab.
• However, because the app assumes a syntax of [name] + [counter (1 to 12)], some languages will be required to explicitly list the 12 default avatar names, as shown to the right.

(8) names

• If you want to use your own custom avatar names, you must set “The word NAME in local language” field of the langinfo tab to “custom”

(9) games

• The games tab determines which games are included and in which order.
• Most teams prefer to include all games in the default order for the initial trial version and then make modifications after reviewing the trial app.

(9) games

• The Door corresponds to the numbered doors on the app’s games menu.
• The Country is an internal game name, as defined in the game library. This information is not visible to users of the app.
• The ChallengeLevel can be adjusted for most (but not all) games to create multiple levels of the same base game.
• The Color is the color of the door, corresponding to the numbers in the first column of the colors tab.
• Optionally, you can supply instruction audio files, which will cause a button to appear in the game explaining how to play. See section B4 for more information.

(9) games

• SyllOrTile indicates whether the game will be tile-based (T) or syllable-based (S).
• StagesIncluded indicates the stages that the game incorporates (e.g. “3” means words from Stages 1, 2 and 3 are included). If you are not using stages in your app, be sure to leave dashes in each row.
• StagesIncluded lets you set up two or more versions of a game, where each version includes a progressively larger set of words.
• Your games list will depend on the optional assets you provide (tile audio, syllable divisions and/or syllable audio). You can find the basic game sets in the Google Sheets language pack template.

(10) colors

• This tab is required, but you can accept all default values when making the app..
• Fill out the yellow cells. The “Game Color Number” is the code you will use to refer to these colors in all other tabs going forward. The “Color Name” is for your own reference and is not used in the code. The “Hex Code” is what actually determines the color.

• You must list at least 5 colors; there is no maximum number of colors.
• Only the first 5 colors will be used inside within the games, while all colors can be used for game door colors.
• If you need help finding hex codes, you can use a website such as https://htmlcolorcodes.com/
• Do not insert or delete columns or rows
• Do not rename the header rows.

(10) colors

(11) Sharing

• This tab is optional. The share button allows you to point the user directly to the Play Store or another link via the aa_share.txt file.
• The first field (A1) will always have “Link” as the header.
• The second field (A2) will either be blank or list the web address of the Play Store or other site hosting the app.
• If link included, Share icon will appear at the bottom of Game selection screen. Clicking Share icon will display QR code

(A1) word images

1. Will you use locally photographed images (.jpg) or will you use icons (.png) from a site like https://www.flaticon.com/? Local images can reflect the uniqueness of the local culture, but these images will make the app size much larger.
2. Ensure you collect necessary image and audio permissions as you prepare your media files.
3. Photographers can note their preference to be credited or remain anonymous.
4. Important! The images should have equal height and width dimensions!

(A1) word images

5. For each item in the wordlist tab, you need a corresponding image (as shown to the right).
6. The image file name must match the entry in the wordlist tab exactly (as shown to the right).
7. Because of this, the image file can only include the English letters a-z, the numbers 0-9 and underscore.

(A1) word images

• Images should be in .png and/or .jpg format. (Contact us if you have a large image collection in a different format that would be difficult to convert.)
• It is possible that another app has already been created with a collection of freely shareable images that would be culturally appropriate for your language. Ask us if you are interested.
• For colors, it is recommended to use an image like the one to the right above from a collection like ARCODI. For numbers, it’s preferable to use just the number as shown to the right below from a site like ARCODI or flaticon.com..

(A1) word images

• Android apps typically have six sizes of each image to ensure high quality images on every device from large tablets with high density screens to tiny cell phones with low density screens. When you download an app from the Play Store, only the images from the necessary set are downloaded, thus saving storage space. However, when creating apps locally and sharing them locally (sideloading), the entire app (potentially with all six sets of images) is transferred. This means that we must choose between (a) smaller size apps that may look pixelated on large tablets with high density screens and (b) larger size apps that display well across all devices.
• The next slides provides more detailed information.
• To ensure the best image quality across all devices, please provide 1310 x 1310 pixel images for the words. To save space, images as small as 300-500 x 300-500 pixels will display well on most devices. In either case, when publishing to the Play Store, we will use your base image to create the set of six sizes per image.

Android drawable folders

carpetas drawable de Android

https://developer.android.com/training/multiscreen/screendensities

Google: What PPI is phone [X]

Google: Qué PPI tiene teléfono [X]

English

If you remove the xxxhdpi images from your app project, you might reduce the size by around 40%. If you remove both the xxxhdpi and xxhdpi images, it might reduce the size by around 65%. However, this might cause the images to appear pixelated on xxhdpi and xxhdpi Android devices.

​

Español

Si quitas las imágenes xxxhdpi de tu proyecto de la app, quizás reducirás el tamaño por 40%. Si quitas las imágenes de xxxhdpi y también las de xxhdpi, quizás reducirás el tamaño por 65%. Sin embargo, esto podrá causar que las imágenes aparecen pixelada en equipos Android xxxhdpi y xxhdpi.

(A1) word images

• Click here for a presentation on image editing.
• Remember to also prepare resource promotion images (section 5).

(B1) word audio

1. The audio files must include permissions that allow legal sharing. In the langinfo tab you can list those voice actors who want to be recognized for their work.
2. For each item in the wordlist tab, you need a corresponding audio file. The audio file name must match the first column of the wordlist tab exactly.
3. Because of this, the audio file can only include the English letters a-z, the numbers 0-9 and underscore.

​

​

(B2) tile audio

• (Optional) For each item in the gametiles tab, you can add a corresponding audio file. The audio file name must match the name in the AudioName column of the gametiles tab exactly.
• It is best to use a “zz_” prefix for tile audio file names.
• The audio file can only include the English letters a-z, the numbers 0-9 and underscore.

​

​

(B3) syllable audio

• (Optional) For each item in the syllables tab, you can add a corresponding audio file. The audio file name must match the name in the AudioName column of the syllables tab exactly.
• It is best to use a “zs_” prefix for syllable audio file names.
• The audio file can only include the English letters a-z, the numbers 0-9 and underscore.

​

​

(B4) instruction audio

• (Optional) For each game in the games tab, you can add a corresponding audio file. The audio file name must match the name in the InstructionAudio column of the games tab exactly. This document will be helpful in planning your recordings.
• It is best to use a “zzz_” prefix for instruction audio files.

​

​

(B4) instruction audio

• The audio file can only include the English letters a-z, the numbers 0-9 and underscore.
• (Optional) For each non-game screen in the app, you can add a corresponding audio file. The audio file names must match these exactly:
• choose player screen = zzz_choose_player.mp3
• change player name screen = zzz_set_player_name.mp3
• about page = zzz_about.mp3
• resources promo = zzz_resources.mp3
• game selection = zzz_earth.mp3

This document may be helpful in planning your recordings.

​

Choose Player:

Change Player Name:

(B4) instruction audio

About Page:

Resources Promo:

Game Selection:

(B) audio

• To optimize the player’s experience, audio files should contain as little silence as possible before or after the recorded word. When silence is being played, this will be interpreted as a problem with the app and decrease interest in the app. On the other hand, if you cut the audio files too closely to the recorded word, (1) an unattractive click sound may be audible or (2) you may accidentally clip some acoustically non-prominent phonetic features!!
• Audio should be in .mp3 file format. If your audio files are in .wav format, these can be converted to .mp3 using batch functions in a program like Audacity.
• Click here for a presentation on audio editing.

​

​

(C) avatar selection / choose player

• The app offers multiple avatars so that multiple members of a family or multiple students in a school can share a single device and each player can track their scores.
• The number of visible avatars (representing the number of players who can share one device and save their own individual progress) is customizable. If you think users will be overwhelmed by seeing 12 options, you may reduce it in the settings tab.
• If you choose to provide instruction audio for this screen, 11 is the maximum number of visible avatars, as shown in the image on the far right.

​

(C) avatar selection / choose player

​

• Users can tap on the text below each avatar to navigate to the set player name screen where they can rename the avatar using the device keyboard or the Alpha Tiles keyboard.

(D) validator

• If you set up your own Android Studio project (link), you can validate your language pack yourself. Or you can contact us to ask us to validate your language pack for you. Most teams ask us to validate the language pack for them.
• The validator checks that all folder structures, folder names, file name and file contents are properly configured.
• It also check 100+ other items, including, for example, that every word from the wordlist tab can be built both from (1) the available keys in the keyboard tab and (2) the available tiles in the gametiles tab.
• When we run the validator report for you, we will send you the error report with some tips on how to resolve the errors.

​

(E) share build files

1. In the project folder of Google Drive, include a signed statement as follows (or similar):
1. “I/we have proper documentation allowing me/us to share the included audio and image files. These audio and image files can be freely shared via the Alpha Tiles app without copyright restrictions and, where requested, we have noted those individuals desiring acknowledgment of their contribution in the About page of the app.”

(E) share build files

• Upload word audio (required), tile audio (optional) and instruction audio (optional) to their respective project subfolders in Google Drive.

(E) share build files

5. Upload word images (required) and resource promotion images (required for each promoted web site) to their respective project subfolders in Google Drive.
6. In the Google Drive, you can ignore the subfolder images_words_low_res. When using the Android Studio validator to download the local language pack, it will automatically download the “image2” (low res) images, if the corresponding file is not found in the images_words_low_res subfolder.
7. Once your app is ready, we will notify you that your .apk (Android app install file) is available in the shared drive.

(F) points

• The games menu has a points counter, as shown in the leftmost image. This represents the total number of points that this player has earned across all games.
• Each individual game also has a points counter in a gem icon, representing the total number of points that player has earned on that specific game.

(F) points

• Each individual game also has 12 trackers at the top of the screen. When this player plays a game for the first time, the first 12 points count towards these trackers. After 12 points, the setting you chose during setup determines what happens.
• If you chose setting 3, the user will see a celebration screen, as shown in the image on the far right.

questions or comments?

Questions, comments, concerns?

Contact us via our tech support Google Form.