JLMahJongg features the ability to create your own lists of winning hands (cards) used to play American Mah Jongg. You can create two types of cards: 1) National Mah Jongg League (NMJL) Standard, and 2) JLMahJongg Custom. You can only store one of each card type, standard and custom, at a time.  Note that deleting the browser storage (cookies) will delete the card data for the browser version and you will have to enter the card again. The NMJL standard card data distributed with the app cannot be viewed or edited, but the card data can be used to play a game and you can see your win history for each card line.  If you enter a standard card yourself using the card editor, you can view the card in a popup window during the game.

The host can send a custom card automatically to other players.

We define a language called Mah Jongg Card Language (MJCL) that is used to enter custom or standard cards into JLMahJongg.  This language and how to enter cards are described in this section. I am describing the steps in great detail – it is not as difficult as it looks below. What you type in is almost exactly what is on a standard card.

A card has 3 things: 1) card name, 2) card groups (also called categories), and 3) lines in each group.  You enter these into JLMahJongg using its Card Editor.  Most of what you input defines the lines on the card.  We have attempted to make the card language match the standard card format as closely as possible. It can take less than 15 minutes to enter a card.  If you don’t need to view the card in the app and want to use the latest standard card data, you don’t need to enter it with the card editor. Just select the JL2025 card from the Card Type menu.

Each line can have either 1 or 2 base patterns that define the winning hands for that line.  The base patterns are what you see on a standard printed card.  Each base pattern contains sets of tiles. The number of tiles in each base pattern must equal 14, the number of tiles in a winning hand.

Each line contains the following:

1. Sets in the hand – each set has a specified number of tile types.  Tile types are: numbers 1 to 9; Dragons, D for any suit, or G for Green, R for Red, and 0 (zero, not O) for White; Flowers, F; and Winds, N E W & S. Numbers and dragons have suits that must be specified if the sets in a hand are not all the same suit. Flowers and winds do not have a suit, so no suit specifier is needed for these. There can be up to two base patterns on a line that are separated by either the OR character (| “the shift \ on the keyboard”) or the letter o (lower case O). Note that spaces can be used to make the sets and lines clearer, but are not needed.
2. Expander codes – expander codes indicate how the base pattern of sets is repeated to generate multiple hands represented by the base pattern.  The codes correspond to some of the text in parentheses on a standard card line. The text information about the number of suits is not included because it is redundant with the pattern.
3. Exposed (X) or Closed (C) hand indicator (NOTE: X must be upper case)
4. Base hand value

Specifying suits.  The number of specific suits is specified by indicating each set’s color by preceding it with a letter for the color:  green (g), red (r), or blue (b).  The default color is green (g) and does not need to be entered if it is the first color.  Sets with different colors need to be different suits.  Sets with the same color need to be the same suit.  The suit starts out as the default, green, if it is not specified.  The suit will stay the default until a new color is specified on the line. If a set needs to be specified as a specific suit, it can be preceded by a specific character for the suit (m=bam, c=crak, d=dot). NOTE: Bam is NOT “b” because “b” is used for the color blue.  Specific suits are rarely used on standard cards (other than 0 for white dragon in year groups).

Expander Codes. The expander codes cause the pattern to be replicated (except the default T=These numbers only).  This corresponds to some of the wording explaining a line or group on standard cards. For example, in the “Any Like Numbers” group, the expander code, “L”, means to expand the “1’s” in the pattern to any like number, not just “1”. The expander code options are:

T = These numbers only – does not expand (default),

Ichrs = Like singles defined by chrs (the single set marked by the first character in chrs will also be replaced by all the following characters in chrs.  For example, INEWS (chrs=NEWS) replaces a single North, N, with the additional winds E, W, and S. 

The below expanders work similarly to the above Ichrs, but for different size sets:

            Achrs = Like pairs defined by chrs,

            Pchrs = Like pungs (sets of 3) defined by chrs,

            Kchrs = Like kongs (sets of 4) defined by chrs,

            Qchrs = Like quints (sets of 5) defined by chrs.

Zchrs = Like (any set sizes) – any set sizes defined by chrs, (for example, ZENWS, replace any set sizes of E with the additional winds N, W, and S,

Lchrs = Like numbers (replaces pattern number 1 (or 2 if even numbers) by 1 to 9, or if chrs is “o” or “e” replaces by odd or even numbers only),

            Uchrs = Unlike number sets (chrs = I, A, P, K, or Q followed by the 2 tile types replaced by the unlike numbers). For example, UK18 means kong sets with 1’s and 8’s replaced by any 2 unlike numbers between 1 and 9),

            Vchrs = Consecutive run (replaces consecutive number runs starting with 1 (or 2 if even run) by all possible runs up to ending with 9). Can use chrs as “a,” “o,” or “e” for all, odd, or even number runs.

*snum = Wild card for suit on sets in the list given by snum. Note that the set number starts at zero and only sets up to number 9 (single digit set number) can be set as a wild suit (any suit). This expander code is used along with the code, “a” before the sets that can be any suit.  This “a” code shows the “wild” sets that can be any suit in color purple.

>chrs = Replace a specific set number with a set of alternate values. The code, chrs, is the set number to be replaced followed by the values to replace (see comments on * above).

Ychrs = Replace pairs after the first pair with the specified value. The code chrs can be “o” for odd numbers, “e” for even numbers, or a specific set of values.

Hchrs = Set each of the set numbers in the range defined by chrs to a pair, one at a time.  Each of the other sets in the range is set to a single. The first set in the range needs to be initialized to a pair.

# = Sets of different numbers are used in any order, regardless of set size. Currently implemented only for 3 different number sets (for example, 3,6,9).

~ = Opposite winds (if have NN and SS, replace with EE WW or vice versa).

!chrs = restrict like numbers, unlike numbers, or a run to only numbers in chrs. Note that this is not a separate expander stage (limited to 2 stages), but modifies a like, unlike, or run stage. This code must come first before any other expander codes.

For some examples of how these expanders are used, see the below values for the 2025 card.  If you are brave enough to try to use our card editor and Mah Jongg Card Language (MJCL) to enter the 2025 card, here are the expander codes for lines that need one or two:

2025 Line 1: P25

2468 Lines 4 & 8: P2468

2468 Line 7: K2468

Any Like Numbers, Lines 1 & 2: L

Any Like Numbers, Line 3: *4 L

Quints, Lines 1 & 2: Va

Quints, Line 3: L

Consecutive Run, Lines 2 – 6 & 8: Va

Consecutive Run, Line 7: H01234 Va

Winds – Dragons line 2: *123 Va

Winds – Dragons line 5: Lo

Winds – Dragons line 6: Le

369, Line 3 & 5: K369

Singles and Pairs, Lines 1 & 4: Va

Singles and Pairs, Line 3: >6369

Singles and Pairs, Line 5: Yo

Example Card Definition.  Below is the MahJongg Card Language code for the Basic1 card.

Basic1
“2468”
FF 222 444 666 888 X25
222 4444 r666 8888 X25
22 444 r66 888 bDDDD X30
“Like Numbers”
FF 1111 NEWS DDDD L X25
FF 1111 NEWS r1111 L X25
FF 1111 r1111 b1111 L X25
“Consecutive Run”
111 222 333 44 DDD Va X25
111 2222 r333 4444 Va X25
FFF 1111 r2222 b333 Va X25
“13579”
11 333 5555 777 99 X25
11 333 55 r55 777 99 X25
FF 111 r33 55 77 b999 X30
“Winds/Dragons”
NNNN EEEE WWWW SS X25
FF 111 DDD rDDD bDDD Va X25
FFFF EEE 1111 WWW Va X25
FFF DDDD rDDD bDDDD X25
FF NNN EEE WWW SSS C30
“369”
FFF 333 6666 9999 X25
333 6666 r666 9999 X25
FF 333 666 999 DDD X25
“Singles & Pairs”
FF 11 22 33 44 55 66 Va C50
NN 11 22 33 44 55 66 Va C50
SS 11 22 33 44 55 66 Va C50
DD 11 22 33 44 55 66 Va C50

Card Editor Interface

The card editor is accessed from Advanced Setup by pressing the “Card Editor” button.   The “Card Editor” button will only be available if your skill level is set to higher than “Beginner” and you are not currently in a game (may need to enable the network).

A card editor display will be shown.  What is shown depends on the number of previously-stored cards.  If no cards are saved (first time using the editor), then a blank editor is shown as in Figure E2.  The editor starts with three drop-down boxes:

1. Card Type – Determines type of card being created or edited (standard or custom).
2. Mode – Determines if you are entering new groups or lines (Enter) or editing an existing group or line (Edit).
3. View – Selects “Code” view that shows the MJL code as entered or “Card” view that shows what the card will look like when viewed in the game or printed.

Depending on your device type and operating system, your display may not look exactly like the ones shown here.  In particular, the drop-down boxes might not show the down arrow on the right indicating it has a drop-down menu.  Even if the arrow is not shown, you can still click in or select the box to show the menu.

The “Close” button in the middle closes the editor window and returns to the lobby.

To start entering a card, first select the card type from the “Card Type” drop-down box. You can select either Custom or Standard.  Figure E3 shows the display after selecting a standard card.  The process for entering and editing standard and custom cards is the same.

Next enter the card name in the Card box and press enter. For this example, we show starting to enter a “2024” card.  The display after entering the name is shown in Figure E4. Note that the editor mode is set to “Enter.”  The “Enter” mode is used when adding new groups or lines to a card.

Next enter the first group name in the Group box and press enter.  The first 2024 card group is called “2024” and is shown entered in Figure E5.

The editor mode has automatically been changed to “Edit”.

Also, the “View” has automatically been set to “Code.”  There are 2 view types: 1) Card, and 2) Code.  The Code view shows the Mahjongg Card Language code as you have entered it.  The “Card” view shows how the card will look when formatted for display/printing or during play.  You can switch between Code and Card view at any time using the drop-down box under “View.”  You can use either view, but Code view is more useful for creating or editing a card.

Buttons named “Codes” and “Process” buttons are now shown.  The “Codes” button pops up a reference list of expander codes.  An example is shown here.  The “Process” button evaluates the card and generates the number of unique hands defined by the whole card, each group, and each line.  These values are displayed when a line is selected if the card is processed.  An example is shown here.  The “Process” button is shown here because the editor does not know you don’t want to see the card statistics for this card.  A card with a single group and line is a valid card.

When the new group name is entered, the group and a default placeholder line are shown in the card display at the top.  The default View when entering a new card is “Code” view.  The purpose of the default line is to make sure you can select the 2024 group.  Only lines can be selected, not groups.  To select a group, you must click on a line in that group.  Therefore, all groups must always have at least one line. If a group without a line were created and then a different group was selected, it would not be possible to edit or delete the empty group and you would need to delete the whole card and start again.  The default line prevents this potential problem.  The default line is “FF NNNN EEEE WWWW X25”. When the new group is entered:

• The selected group and an empty line are shown in the “Group:” and “Line:” boxes, respectively.
• The default “Line:” box is selected so it is ready to enter a new line
• The Code display shows the new group and line in red, indicating they are the current selection
• Buttons called “Delete Line” and “Delete Group” are now shown.

The default line is not what we want, so we need to change it to the actual first line.  You just need to enter the line you want to replace the default line and press enter.  The resulting display before pressing enter is shown in Figure E6.

Because a specific line and group are selected, they can now be deleted, if desired.  If there is only one line in a group, deleting the last line deletes the group.

We need to change the default line to the actual first line of the 2024 group on the 2024 card.  This first line is: “222 000 r2222 4444 X25”.  The only difference between this code and the actual line on the card is that the letter “r” is used to indicate the sets following the “r” are red (they are printed in red on the physical card).  The “X25” on the line is the default, so that does not need to be typed in.

Figure E6 shows this correct first line typed in, but not entered yet.  Figure E6 is before the line is entered by pressing the enter key.  You can modify the line until you enter it. 

Figure E7 shows the display after entering the first line shown in the “Line:” box of Figure E6.  The correct line is now displayed in the Code view, the mode returns to Enter, and the “Line:” box is cleared.  The editor is now ready to accept additional lines for this new group.

You can continue entering more lines by entering additional lines in the “Line:” box.  We’ll show adding the 2^nd 2024 group line, “FFFF 2222 0000 r24”.  The resulting display is shown in Figure E8.

If you select the View drop-down and select “Card”, the display looks like Figure E9. The card view looks like a printed card would look.  The sets are shown with the correct colors that indicate how many different suits are used.

This “Card” view for the card in use can be popped up during a game using the menu option “View Card”. 

The other thing you need to do to enter a new card is add additional new groups.  Without adding the rest of the lines for the 2024 group, we’ll show how to add the next group, “2468”.  You can do this in either view, but we recommend entering new code in “Code” view.  When in the Enter mode and the last line is selected (as in Figure E8), to enter a new group at the end, add the new group name in the “Group:” box. You can only enter either a new group or a new line – you can’t enter both a new group and a new line at the same time. To enter the new group name, click in or select the “Group:” box and enter the name, “2468” in this case.  Press enter to enter the new group name and create the new group. The result is shown in Figure E10.

As in the first group, type the first line of the second group and press enter.  The result is shown in Figure E11.

To finish adding the rest of a new card, repeat the same steps above until all groups and lines are entered.  If you have pressed the process button while entering lines or are editing a previously-existing card, press the process button when you are done.  Otherwise, just close the editor.  The card is automatically saved whenever you make a change. The card will be automatically processed, if necessary. What you see in the View displays is what is stored.

General notes about using the editor:

1. The card is automatically saved every time you make a change.
2. The “Codes” button shows a popup list of expander codes
3. The “Process” button calculates how many unique hands are produced by each line. After processing is complete, the editor will show the statistics for the number of unique hands generated by each line, group, and the whole card. To see these numbers, select a line. You don’t need to “Process” when entering a new card.
4. Most line entries can be entered in lower or upper case with the exception that the X for eXposed needs to be upper case and x for multiply needs to be lower case.
5. The X or C designating either an eXposed or Closed hand and the hand value default to “X 25.”  You only need to enter these if they are different than the default.
6. Press the close button to close the editor window and return to the lobby.

Starting the Editor with an Existing Card to Modify the Card or Correct Mistakes

When the editor starts with one (standard or custom) saved card, the editor shows that card. When the editor starts with two (standard and custom) saved cards, the editor shows the standard card.  You can switch to the other card using the Card Type dropdown.

An example after opening with an existing custom card is shown in Figure E12. The editor opens in Edit mode and Card view.  There are 3 things you can do to an existing card:

1. Change or correct an existing group, line, or the card name
2. Add a new group or line
3. Delete a group, line, or the whole card.

The following describes editing an example existing card named “CardEx”.

Changing a Group or Line

To change an existing group or line, first select the group and line either by selecting the left set in card view or the line in code view.  If you select the third line of the 2468 group, the card display is shown as in Figure E13. The selected group and line are shown in the Group: and Line: boxes. 

For example, if we want to make the blue 8’s in this line red, we can remove the “b” before the 8888 in the line code.  To do this just edit the text in the “Line:” box and press Enter. The display changes to that shown in Figure E14. The blue 8’s in the third line are now red.

After entering the change, the editor is ready to enter a new line after the changed line. In the Card view, you can no long see which line is selected until a line is selected again.  If you enter a new line at this point, the editor will switch to code view and show the new selected line in red.

Changing the Card Name

To change the card name:

1. Enter the new card name in the “Card:” box and press or select enter.

Entering a New Group

To enter a new group:

1. select the last line of the last group for a group at the end or select any line in the group after where you want the new group otherwise,
2. change to enter mode with the Mode drop-down box,
3. type the new group name in the Group: box and select or press Enter,
4. Modify the placeholder line, “FF NNNN EEEE WWWW”, that is added with the new group.

Entering a New Line

To enter a new line:

1. select the line before where you want the new line
2. change to enter mode with the Mode drop-down box,
3. type the new line in the Line: box and select or press Enter.

Figure E15 shows the display after entering “DD NNNN EEEE WWWW” as a new line in the middle of the “2468” group.  Note that this line was entered manually, not as a new group placeholder line.

If we are done with this card, we can press the “Process” button.  The “Process” button converts the card code into a form that the app can load quickly and generates statistics about the card.  When processing is complete and a line is selected, the number of unique hands defined by the card, the selected group, and the selected line are shown as in Figure E16.  In this simple example, there are a total of 24 unique hands defined by the card, 21 by the 2468 group, and 6 by the selected “22 444 r44 666 8888 X25” line.  This selected line corresponds to 6 unique hands because there are sets which must have 2 different suits out of the 3 possible suits (bams, craks, or dots). The 6 possibilities are: 1) bam, crak, 2) crak, bam, 3) bam, dot, 4) dot, bam, 5) dot, crack, 6) crack, dot.  Note that swapping the suits (bam, crak vs crak, bam for example) is not the same hand because the 1^st suit tiles, 22 444, are not the same as the second suit tiles, 44 666 8888.  If the tiles for the 2 suits were the same, this would be considered only 3 unique hands.

The Codes button pops up the expander codes you can use in the line definitions. The Codes Summary popup is shown in Figure E17.  The popup also list a few other codes (“OR” code, dragon codes, and suit codes) at the bottom.

Deleting a Line, Group, or the Whole Card

To delete a line, select the line with the mouse (or by touching it on a touch screen).  Press the “Delete Line” button to delete the line.  If the line is the last line in a group, the group is also deleted.

To delete a group, select any line in the group you want to delete.  This selects that group.  Click or press the “Delete Group” button to delete the group.  Deleting the last group will delete the card.

To delete a card, select the card by selecting the card name at the top of the editor display. Click or press the “Delete Card” button to delete the card.  If you are using the browser version of the app, NOTE: clearing the cache will also delete all saved cards, in addition to your profiles.

Notes on making changes and correcting mistakes:

1. You can select a line in code view by mouse clicking or pressing on a particular line.  This makes that line/group the current line and enters the “Edit” mode.  The line and group selected will be shown in the Line and Group boxes.  You can then edit either the line or the group.  After making a change to the line or group, press enter in the line or group box.  The editor will automatically return to enter mode and will enter new lines after the currently-selected line.  To add new lines at the end, select the last line and change back to Enter mode using the mode dropdown.  To enter a new group at the end, first select the last line, then change back to Enter mode and type a new group name in the Group: box.
2. You can delete a group or line by selecting a group/line and then pressing the “Delete Group” or “Delete Line” button.  Deleting the last line of a group deletes the group.
3. You can also get back to Enter mode by selecting the line where you want to enter (after), then entering that line without any changes.
4. To select a line in Card view, you must select the first set on the left.
5. To select the whole card, click on or press the card name at the top.  A “Delete Card” button is then shown. Pressing it will delete the card with no warning.
6. New lines added in edit mode are inserted after the selected line in a group.  To insert a line before the first line in a group, you need to insert it after the first line, delete the first line, then re-enter the line you deleted after the new line.
7. New groups are inserted before the currently selected group unless the last line of the last group is selected (end of card), then the group is inserted after the last group.
8. Groups are selected by selecting any line in the group.  If a new group is inserted before other groups, a placeholder line with the tiles “FF NNNN EEEE WWWW” is inserted.  This is to ensure that the group can be selected.  You can’t select on the group name to select it – you must select one of the group’s lines.
9. You can change the line and group text to be entered in the Line and Group boxes until you enter it (select or press Enter key).
10. Any changes you make are automatically saved.
11. The editor checks the number of tiles in each hand every time you enter a new line.  If you enter a hand that does not have exactly 14 tiles, an error is output on the display indicating the wrong number of tiles (not 14). The hand is not entered until the line is corrected to have 14 tiles. No other error checking is performed. Figure E18 shows an example error after trying to enter only 13 tiles.

Viewing and Printing a Card

A custom or standard card entered with the card editor can be viewed during a game by selecting the “View Card” option from the game menu. Non-standard cards included with JLMahJongg can also be viewed.  An example of the Basic1 card viewed during a game is shown in Figure E19.

To print a card:

1. Perform a print screen operation with the card displayed as in Figure E19.  In Windows you can press Fn + Print Screen (keys in blue) and choose “Rectangle” from the dropdown at the top. Select the card area on the screen that you want to print (dragging a rectangle).  Note: I must do the print screen 2 times in a row to get the screen to copy to the clipboard.
2. Paste the copied card into an app, such as Word, that can print.
3. Print the file

An example of a card copied in this way is shown in Figure E20.