Name

Synopsys

openallumette [ [-n|--number] SeedNumber ]  [ [-v|--varient] [trivial | marienbad | grundy | wythoff ]  [-w [ttl|ltl] ]
openallumette  Descriptor
openallumette [-h|--help]  [-v|--version]  [--hall-of-fame]

openallumettetutor
openallumette --tutor

Logo

Description

openallumette is a classical Nim game’s implementation writen in Python and Pygame library made to be all used with the keyboard (like vim).
At the first runing of this software, it is showen a tutorial showing how to use commands and interact with the interface. This tutorial are not reshown in the nexts runings but you can see it again with the shell command openallumettetutor.

Note that Nim games have a mathematical solution. Once you find it for a varient, you win at every game, then it is not yet insteresting to play it. That’s why openallumette is only designed Nim enthousiasts to find this solution.

Later, it will support all possible knowen varients of this game.
This game is dedicated to mathematic and serius games enthousiast. Later, it will bring tools to help understunding the Nim games.

⚠ if you were searching of dumb-friendly and WIMP interface, go away. Open Allumette is made for nerdz by a geek like if it was a programmer editor. And we are proud of that.

Rules

The classical Nim game is a turn-based game. The exact rules depend of the varient, but generally the player have to take the last match (in the ttl or take-the-last mode) or to force his opponent to take the last match (in the ltl or let-the-last mode). For the moment openallumette only bring IA opponent. It will probably support in futures versions online mode over XMPP.

Usage

The player can directly run the game with the desired configurations by using the starting options -n, -v, -w (See the Options’s section for that), or alternatively with the standard descriptor string (See the The configuration descriptor’s section).
Once he has open Open Allumette he could open another game session with the ex or normal commands (See the Commands and Ex commands’s sections).

Options

-n, --number=SeedNumber: Start a new game with SeedNumber as seed number (default: 16)
-v, --varient=Varient: Start new game with Varient as varient (default: trivial)
-w wtw: Start new game with with wtw as mode, there is two values possibles ttl and ltl. See wtw Mode’s section for more inforamtions.
-c, --color-sheme=Colorsheme: Set the colorsheme witch will be used to Colorsheme
--hall-of-fame: Display in the shell the hall of fame.

Window’s Anatomy

In a game session, the screen is generaly divided into tree main parts as described follow. The command zone allow typing commands, the history zone display list of actions, and the matchs zone give a view of the current situation.

╔═════╦════════════════════════════════════════════════════╗
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
║Hist-║                                                    ║
║ori  ║                                                    ║
║Zone ║                                                    ║
║     ║                                                    ║
║     ║                   Matchs zone                      ║
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
║     ║                                                    ║
╠═════╩════════════════════════════════════════════════════╣
║Command zone                                              ║
╚══════════════════════════════════════════════════════════╝

Command’s zone

It’s probably the main zone of the game because is the main part of the user’s interaction. It’s set on the window’s bottom and is divided into five parts witch are, frome left to right :

Varient name: Depending of the current screen displayed by the game, this zone remember witch varient or part of the game is currently displayed.
Ex command zone: This zone display the ex-mode commands. See Commands’s section for more details.
Key bindings: This zone display the normal-mode commands. See Key Bindings’s section for more details.
Mode: This zone display the WTW variable, it could be ttl (take the last) or ltl (let the last). See wtw Mode’s section for more details.
Passed time: This zone display the time passed since the bigining of the game.

History zone

The history zone display chronological list of actions the opponents do in the game. See Key Bindings’s section for more details about controling this area.

Match area

This part display current state of the game.

Key Bindins

n: Reload a new game with exactly the same parametters as the current one.
p: Put game on pause and suspend the time count.
numberu: Undo one (or number) last action(s).
numberr: Redo one (or number) last undid action(s).
F8: Toggle showing help mode for some varients.
↓, j: Go backward in the history of ex commands.
↑, k: Go forward in the history of ex commands.
⇟, ALT-j: Drop down history list.
⇞, ALT-k: Drop up history list.
⇲, J, G: Go to history list bottom.
⇱, K, gg: Go to history list top.
CTRL-↓, CTRL-j: Drop down autocompletion help menue in ex mode.
CTRL-↑, CTRL-k: Drop up autocompletion help menue in ex mode.

Ex commands

The “Ex commands” refer to all commands witch begin with the colon (:) and generaly his typing apear in the Command zone. This kind of commands could do many things, especially advanced features. Some ex commands, the ones described on the Commands’s section are for general use and could be used in any situations. Some others ex commands are specific to a varient game and are described in the Varients’s section.

To enter ex mode, the user have to type colon key (:) and a cursor will apear in the command zone. When the user begin typing a command, he can get at any time more information about it with Tab key witch will bring an autocompletion mode.

Then, the autocompletion mode open a box over the command zone, showing a quick help about the command writen.
At any time, the player could hide the autocompletion box with Esc key.

Commands

All this commands could be entered at any time and they are displayed in the command zone in the window’s bottom for the ex-commands with a cursor (witch are begin with the prefix :).

:n, :new varient SeedNumber wtw :n, :new Descriptor

Open new game with following options:

varient: The varient name, witch could be trivial (default), marienbad, grundy, or whythoff. See Varient’s section for more details about each varient.
SeedNumber: The seed number. It repreasent the number in the initial situation of a particular function. His exact usage depend of the varient.
wtw: It represent the condition of wining and could take two values: ttl (take-the-last) where the player have to take the last match to win ; ltl (let-the-last) where the goal for the player have to force his oponent to take the last match.

Alternatively, you can just use the configuration descriptor described in the The configuration descriptor’s section.

:about

Open the license screen.

:colorsheme varient

Change colorsheme to the varient one.

:quit, :q, ZZ

Quit the game.

:saveas, :w

Save the current game with time in a file.

:open, :o

Open registered game

:rules

Show the rules for the current varient.

:help command, :h command

Getting help about a command.

:tutor

Open the tutorial mode.

:tip

Bring a tip.

Varients

The syntax of the game actions mainly depand of the variant you are playing. And in all cases, you have to be in normal mode; to get it, just press ⎋ key.

Trivial (The default one)

Initializing

In the Trivial varient theire is only one heap of match, so the SeedNumber defined in the initializing exactly match the number of match in this unique heap. The trivial varient didn’t have assistant mode.

Rules

In the trivial variente, theire is only one heap of SeedNumber match. And, on each turn, every player have to take one, two, or tree matchs.

Intreface and command

To del 1, 2, or 3 matchs from the total number of matches in this varient theire is two possibilities. When the player type a del command, before it take effect, it is showen in the key bindings zone (See the Command’s zone’s section), untel he tape enter key.
It depend of the colorsheme but in general, the allowed matchs is distinguished by a shadow effect or some other effect. And the last match have a crown on top if the ttl mode is activated or a skull and bones if the ltl mode is activated.

-[1|3|3], [1|2|3]⏎: You can explicitly indicate the number of match you whant to del, for this, just type the number of match followed by ⏎. Optionnaly, the number of match you want to take could be precead by minus symbol -.
=NumberToLet⏎: You can also indicate the number of match you hant to let. For this you just have to prefix the number of match by equal sign =.

Wining situation

When the player could take the last match (so there is only tree match in the maximum), the remain matches are displayed burning (but this depend of the colorsheme).

Marienbad

Initializing

In the Marienbad variente, theire is as line number as the SeedNumber defined in the initializing. The top line contain one match, and the number of match increase at each column by two matchs. So we can calculate the number of colums with “2×SeedNumber-1”.
For example, with SeedNumber=4, we get the following configuration:

0       | 
1     | | | 
2   | | | | | 
3 | | | | | | | 

  0 1 2 3 4 5 6

Rules

At his turn, the player must take as matchs as he want from any column but from one and only one column. Depending of the WTW mode, the winer will be the one who can take the last match or force the oponent to take it.

Intreface and commands

To take matchs in the Marienbad varient, there are two information to give:

The column number.
The number of match to take (or, alternativly, to let).

So, theire is two operators and syntaxs possible:

column=matchs: Witch heap the number remain matchs to matchs in column of the number column
column-matchs: Witch del matchs matchs in column of the number column.

Assistant mode (Spoiler)

WARNING: This section spoil the trick. Read it only if you have difficulties with the resolution of the Marienbad solution.

In addition to that, the Marienbad’s varient have an assistant mode helping the player to understind how the mathematical mecanism is runing and how to find the wining strategy. By pressing the F8 key witch bring a little box with indications.

The box show the total match of each line and his binary representation. The wining strategy consist to maintain a binary value’s total (represented in the box by the T value) even at each turn.

As example, at the begining of marienbad game with a seed number equal to 4, this is how the assistant’s box appear:

1 = 0 0 1
3 = 0 1 1
5 = 1 0 1
7 = 1 1 1
---------
T = 2 2 4

The number 5 represent the total match of the 3th line, his benary value is 101. And T represent the total of benary values summed in decimal system. For wining, the T value have to be alway even at the end of the turn.

Grundy

Initialization

In the Grundy varient theire is only one heap in the bigining, so the SeedNumber is the number of the matchs in the innitial heap.

Rules

In this varient, the player didn’t take matchs and the goal isn’t to take the last one. Theire is only one heap of matchs and the fiirst player have to divided into two unequel heaps. In the next turn, each player have to take one child heap and divided into two unequal heaps. In the ttl mode, the goal is to make the oponant unable to play. In the ltl mode, the goal for the player is to be unable to play.

Interface and commands

In the openallumette implementation, all heaps have a number identifier code in the Grudy’s varient (exept the first, beacuse numbering him is useless). This identifier code is formed after the father heaps’s idintifier code and the number of current heap, separated with a dot “.”. When the initial heap is divided it give two child heap witch are numbered 0 and 1. After that, when a heap with an identifier code “N is divided, it give two others heap with identifiers codes N.0 and N.1.

Now, if the player want to divied a heap with the identifier code heap into two heap with a and b matchs (with a+b=the number of match of the concerned heap), he have to indicate the identifier code of the heap and of the two terms a or b. Note it isn’t necessary to indicate the two terms of this substraction, because the second one is defined after the initial number of matchs in the heap.

heap:term0, heap:term0+term1: Divide the heap with the identifier code heap into two child heaps with respectivelly term0 and term1 matchs and respectively heap.0 and heap.1 as identifier code. Note only one term is needed, the second one is absolutely facultative.

Assistant mode

TODO

Wythoff

Initialisation

In the Whythoff varient, theire is tow heaps of the same number of match in the initial situation, so the SeedNumber defined in the initialiasation is the number of matchs in each heap.

Rules

In the Whythoff varient, theire is two heaps and the players have, at theire turns two choices of actions:

Take the same quantities of matchs from the two heaps.
Take any quantities of matchs but from on and only one heap.

Interface and commands

The two heaps are named A and B. So, depending of if the player want take the same number of matchs from the two heaps or from one and only one heap, theire is two possible commands:

[-]matchs: Take matchs matchs from the two heaps.
heap-matchs: Take matchs matchs from the heap heap.
heap=matchs: Set the remain matchs to matchs in the heap heap.

The configuration descriptor

The configuraton descriptor is a short string describing the main configuration of a Nim session, including all variables. The main form of a configuration descriptor is:

FirstPlayer Variente;SeedNumber;wtw

Where the variable have the following meanings:

FirstPlayer: Describe witch will be the first player. + for the human player ; - for the computer. The default is the user.
Variente: Varient name, see the Varient’s section for allowed vallues.
SeedNumber: The seed number. His usage depend of the choosen varient.
wtw: The “What to (do for) win” variable. See wtw Mode’s section for more details.

For example the descriptor +Marienbad;26;ttl means the curent game in Marienbad varient, with 26 lines (then 57 columns), the winer is the player who take the last and the human player will be the first to play.

Note you can place all this ellements in another order, Open Allumette will understund it, but it steel better to place it in the canonical order. In addition to that, the first player information is optionnal.

wtw Mode

The wtw variable (for “Wat to [do for] win”) define the conditions of wining and the goal of the game. Generaly, the wining in the classical Nim game is set in two modes, one when the goal is to unlaw the opponent to be able to play, witch called “normal” mode, and another mode where the goal is to force the opponent to play the last possible movement.
In Open Allumette, the normal mode is called ttl (for “take the last”) and the other mode is called ltl (for “let the last”).

The exact meaning of ttl and ltl could depend of the varient played. But in general, the ttl means the winer is the player who could take the last match of the game and ltl means the winer is the player who will be forced to take the last match.

However, there is some exeptions like with the grundy varient where the ttl means the goal it to divide the last splitable heap and ltl means the goal is to force the opponent to divide the last splitable heap. See Grundy for more details.

Colorsheme

It is possible to change the default colorsheme with another one and also edit new one with CSS.

For changing the current colorsheme, just use --colorsheme or -c in the shell, or the ex command :c[olorsheme]. And then, chose a colorsheme between the installed ones.

Molokai

Bibliography

Here is some ressources for mathematical studys and comprehension of the Nim game.

Grundy’s varient

P. M. Grundy. Mathematics and Games. Eureka, vol.27, 1964.
E. Berlekamp, J. H. Conway, and R. Guy. Winning Ways for your Mathematical Plays. Academic Press, 1982.

Screenshots

You can see all screenshots at the official webstie.

About screen
Wining screen
Falling screen
Pause screen

Installation

Linuces and BSD: TODO
Windows: TODO

Licence

This game, included the related files and manpages, is placed under the CC-by-sa 3.0 lincence.

Author

The mayor part of Open Allumette is writen by Fauve (aka Idriss al Idrissi) http://taniere.info and could be foud on Github at https://github.com/FauveNoir/.