A program that finds the best move in a game of Rummikub.
"Rummikub" is a trademark of its owner. This is an independent project. It has no connection to the trademark owner.
You show the program the sets on the table and the tiles on your rack. The program tells you the best move. It also shows you how to make that move, one step at a time.
The program can move the tiles that are already on the table. It finds moves that are difficult to see. For example, it can break a run, take one tile out of a group, and repair that group with a tile from your rack.
- What this program does
- Before you start
- How to install the program
- How to use the program
- How to type a position
- The rules you can change
- How the solver works
- The files
- How to run the tests
- Known limits
- Glossary
- License
- Trademark notice
The program does these things:
- It reads the position of the game. The position is the sets on the table and the tiles on your rack.
- It finds the move that puts the largest number of tiles on the table. You can also tell it to find the move that scores the largest number of points.
- It shows you the move as a list of steps. Each step shows the table at that moment.
- It obeys the first meld rule. It also obeys the joker rules.
The program does not use artificial intelligence. It calculates the answer. The answer is always the best move that the rules permit.
Note The program looks only at the current turn. It does not keep tiles for a better move later. It does not know which tiles the other players hold.
You must have a Java Development Kit (JDK), version 17 or higher.
To find the version of Java on your computer, type this command:
java -versionIf the command does not work, install a JDK. Then do the test again.
The program needs no other software. It needs no libraries, no build tool, and no internet connection.
- Download the project, or clone it with Git.
- Open the project folder.
- Double-click
run.bat.
The script builds the program and then starts it. The build takes some seconds. The next time, the program starts immediately.
To build the program but not start it, double-click build.bat. This makes the file
rummikub.jar.
The program is standard Java. It operates on Linux and macOS. Type these two commands in the project folder:
javac -encoding UTF-8 -d out src/rummikub/*.java
java -cp out rummikub.RummikubAppNote The
.batscripts are for Windows only. The two commands above do the same work.
The window has three areas:
| Area | Position | Function |
|---|---|---|
| Palette | Top | All 53 different tiles. You take tiles from here. |
| Table and rack | Left | The position of the game. |
| Rules and result | Right | The options, and the move that the program finds. |
-
Put in the sets that are on the table. Drag a tile from the palette onto a row. Each row is one set. To start another row, click New table set. If the table is empty, go to step 2.
-
Put in your own tiles. Drag the tiles from the palette into the Your rack box.
-
Set the rules. Look at the Rules area. Refer to section 6. For a usual game, do not change anything.
-
Click Find the best move. The program calculates the move. This takes less than one millisecond.
-
Read the steps. Open the Step by step tab. Do the instruction that you see. Then click Next. Do this again for each step.
The tiles that glow are the tiles that you must touch. The tiles in the yellow box come from your rack.
- To remove one tile, click it.
- To undo any change, press Ctrl+Z, or click Undo.
- To move a tile, drag it. You can drag a tile from one set to a different set. You can also drag a tile between the table and your rack.
- To see a sample position, click Example.
- To read these instructions in the program, click Help.
Each row shows its condition:
| Message | Meaning |
|---|---|
valid set |
The row is a legal run or a legal group. |
not a valid set |
The row is not legal. Usually there is a mistake in the tiles. |
OK |
In the steps: this set is legal now. |
not legal yet |
In the steps: a later step repairs this set. |
set aside |
In the steps: these tiles are in your hands. They are not on the table. |
Note A broken set during your turn is correct. All the sets must be legal only when you stop.
You can type a position instead of a drag operation. This is faster for a large table.
Use the box at the top of the window. Then click Load.
set / set / set | your rack
- A slash (
/) divides two sets on the table. - A vertical bar (
|) divides the table from your rack. - A space divides two tiles.
| Letter | Colour |
|---|---|
k |
Black |
r |
Red |
b |
Blue |
o |
Orange |
Write the colour letter and then the number. Write J for a joker.
r4 r5 r6 r7 / b7 o7 k7 / b10 b11 b12 | r10 o10 k10 b13
This position has three sets on the table. Your rack has four tiles. The Example button loads this position.
All the rules are options. The program has no rule in its code that you cannot change.
| Option | Default | Function |
|---|---|---|
| Goal | Play the most tiles | Select the largest number of tiles, or the largest number of points. |
| Opening points | 30 | The points that you need for your first meld. |
| Enforce the opening threshold | On | Switch off to ignore the first meld rule. |
| This is my first meld | Off | Tick this if you did not come out. Then you cannot touch the table. |
| Auto-detect (empty table) | On | If the table is empty, the move is a first meld. |
| Table jokers must stay in play | On | A joker on the table must stay on the table. |
The program finds a first meld in two ways:
- Automatically. If the table is empty, the move is a first meld.
- Manually. Tick This is my first meld.
The tick box has more authority than the automatic method. The program cannot know your history. For example, you can start to play in a game that is already in progress.
Do not think about the table as a group of sets. A red run 4-5-6-7 is not four tiles that
are attached to each other. It is four red tiles in a legal arrangement at this moment.
Thus the question becomes:
Take all the tiles on the table, and any number of tiles from your rack. Divide these tiles into legal sets. Each tile from the table must be in one of the sets. Use the largest possible number of tiles from your rack.
All the difficult human moves are a result of this question. Those moves are only different arrangements of the same tiles. Therefore the program does not have a list of move types. This is the reason why the difficult positions operate correctly.
The program uses dynamic programming. It examines the values from 1 to 13, in sequence.
After each value v, the program keeps this data for each colour:
- The number of runs that stop at v and have one tile.
- The number of runs that stop at v and have two tiles.
- The number of runs that stop at v and have three tiles or more.
A run with one tile or two tiles is not legal. That run must get more tiles. A run with three tiles or more can stop, or it can continue. The program also counts the jokers that it used.
A group has only one value. Therefore the program makes the groups at each value.
You must use all the tiles that are on the table. This rule has a simple form. At each colour and value, the number of tiles that you use must be equal to or more than the number of tiles on the table. The additional tiles come from your rack. The program counts those tiles as your score.
A tile on the table and the same tile on your rack are equivalent. Thus the program does not record which physical tile is which.
Planner compares the new arrangement with the old arrangement. Walkthrough then makes the
list of steps. The sequence of the steps is the sequence that a person uses:
- Take out all the tiles that must move. Put them in front of you.
- Make the sets, one set at a time.
A usual position needs less than one millisecond.
src/rummikub/
├── Solver.java The algorithm
├── Walkthrough.java Makes the steps, and the picture of the table at each step
├── Planner.java Finds where each tile goes
├── RuleConfig.java All the rules
├── Tile.java One tile
├── Meld.java One set, and the test for a legal set
├── RummikubApp.java The window
├── TileView.java Draws one tile
├── SolverTest.java Tests for the algorithm and the steps
└── UiTest.java Tests for the window, with real mouse events
build.bat Builds rummikub.jar
run.bat Builds the program if necessary, then starts it
test.bat Runs the tests
Type this command:
test.batOn Linux or macOS, type these commands:
javac -encoding UTF-8 -d out src/rummikub/*.java
java -cp out rummikub.SolverTest
java -cp out rummikub.UiTestThere are two groups of tests.
The tests use positions with a known answer. They include the difficult moves:
- A run that gives one tile to a group.
- A tile that comes out of a group. A tile from your rack then repairs that group.
- A run that opens in the middle.
- A joker on the table that must stay in play.
- A first meld with sufficient points, and a first meld with insufficient points.
The tests examine two things. First, they examine the answer. Each set must be legal, and no tile from the table can disappear. Second, they examine the steps. If you obey all the steps, the table must become the arrangement that the solver found. No tile can stay in your hands.
These tests send real mouse events to the window. They examine the drag operation, the click operation, and the undo function.
Note The interface tests open a window for some seconds. On a computer with no screen, the tests report this and then stop. They do not fail.
- The program permits a maximum of two jokers. Two jokers is the standard game. With three jokers or more, the program can miss an unusual arrangement.
- The program examines only the current turn. It does not keep a tile for a better move in a later turn.
- The program does not know the tiles of the other players. Thus it gives no advice about strategy.
- When you drop a tile on a set, the tile goes to the end of that set. You cannot select a different position. The sequence in a set has no effect on the calculation.
These are the technical names in this document. Each name has one meaning only.
| Name | Meaning |
|---|---|
| Tile | One piece of the game. It has a colour and a number. |
| Set | Three tiles or more in a legal arrangement. A set is a run or a group. |
| Run | Three tiles or more. They have the same colour and sequential numbers. |
| Group | Three tiles or four tiles. They have the same number and different colours. |
| Joker | A tile that can replace any other tile. |
| Rack | The tiles that you hold. The other players cannot see them. |
| Table | All the sets that the players put down. |
| First meld | Your first move. It must have 30 points or more. |
| Move | All the changes that you make in one turn. |
| Step | One instruction in a move. |
| Solver | The part of the program that calculates the move. |
| Position | The tiles on the table and the tiles on your rack, at one moment. |
This project uses the MIT License. See the file LICENSE.
The MIT License is permissive. Any person may use, copy, modify, and sell this software. The person must keep the copyright notice and the license text. The software has no warranty.
"Rummikub" is a trademark. Lemada Light Industries Ltd. owns the trademark, or its assignee owns the trademark. This project is independent. This project has no connection to the trademark owner, and the trademark owner does not endorse this project.
The MIT License in section 12 applies to the source code. The license does not give any permission to use the name "Rummikub" as a trademark. The rules of a tile-and-number game are not eligible for copyright. Therefore this program is lawful. The name is a separate matter from the code.
This document obeys the writing rules of ASD-STE100 Simplified Technical English:
- One word has one meaning. One meaning has one word.
- Instructions use the imperative form. Example: "Click the button."
- Sentences in a procedure have a maximum of 20 words. Sentences in a description have a maximum of 25 words.
- Paragraphs have a maximum of six sentences.
- The text uses the active voice.
- The text does not use contractions.
- Section 11 gives the technical names.
The document follows these rules. It is not a certified STE document. A certified document needs a check of every word against the STE dictionary.