← Back to branch summary

~ubuntu-branches/debian/sid/gnubg/sid

« back to all changes in this revision

Viewing changes to doc/gnubg.texi.old

  • Committer: Bazaar Package Importer
  • Author(s): Russ Allbery
  • Date: 2006-12-28 10:45:05 UTC
  • mfrom: (2.1.5 feisty)
  • Revision ID: james.westby@ubuntu.com-20061228104505-4p6sxxdosrlvhgpr
Tags: 0.14.3+20060923-4
http://bugs.debian.org/404254
http://bugs.debian.org/404613
* Translation updates:
  - French, thanks Thomas Huriaux.  (Closes: #404254)
  - Spanish, thanks Javier Ruano.  (Closes: #404613)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gnubg.texi.old
 
1
\input texinfo
 
2
@setfilename gnubg.info
 
3
@settitle GNU Backgammon
 
4
@include version.texi
 
5
 
 
6
@set month-year April, 2001
 
7
 
 
8
@syncodeindex vr cp
 
9
 
 
10
@macro gnubg
 
11
@t{gnubg}
 
12
@end macro
 
13
 
 
14
@dircategory Games
 
15
@direntry
 
16
* gnubg: (gnubg).               GNU Backgammon.
 
17
@end direntry
 
18
 
 
19
@ifinfo
 
20
This file documents GNU Backgammon, a program for playing and analysing
 
21
backgammon games and matches.
 
22
 
 
23
Copyright @copyright{} 1999, 2000, 2001 Gary Wong.
 
24
 
 
25
Permission is granted to copy, distribute and/or modify this document
 
26
under the terms of the GNU Free Documentation License, Version 1.1; with
 
27
no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 
28
copy of the license is included in the section entitled "GNU Free
 
29
Documentation License".
 
30
@end ifinfo
 
31
 
 
32
@titlepage
 
33
@sp 10
 
34
@title GNU Backgammon
 
35
@subtitle version @value{VERSION}
 
36
@subtitle @value{month-year}
 
37
@author Gary Wong
 
38
@page
 
39
@vskip 0pt plus 1filll
 
40
Copyright @copyright{} 1999, 2000, 2001 Gary Wong.
 
41
 
 
42
Permission is granted to copy, distribute and/or modify this document
 
43
under the terms of the GNU Free Documentation License, Version 1.1; with
 
44
no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 
45
copy of the license is included in the section entitled "GNU Free
 
46
Documentation License".
 
47
@end titlepage
 
48
 
 
49
@ifnottex
 
50
@node Top
 
51
@top GNU Backgammon
 
52
 
 
53
This manual describes how to use GNU Backgammon to play and analyse
 
54
backgammon games and matches.  It corresponds to version @value{VERSION}
 
55
(updated in @value{month-year}).
 
56
 
 
57
@menu
 
58
* Introduction::                   What GNU Backgammon does.
 
59
* How to Play Backgammon::         The rules of the game.
 
60
* Sample Game::                    An example of how to play against gnubg.
 
61
* Invocation::                     Starting and leaving gnubg.
 
62
* Basic Commands::                 Fundamental operations in gnubg.
 
63
* Playing::                        gnubg's game playing features.
 
64
* GTK::                            gnubg's optional graphical interface.
 
65
* Analysis::                       Using gnubg to evaluate positions.
 
66
* Databases::                      Storing information about positions.
 
67
* Training::                       Modifying gnubg's neural nets.
 
68
* Guile::                          Extending GNU Backgammon with Guile.
 
69
* Frequently Asked Questions::     Brief answers to things you might ask.
 
70
* GNU Free Documentation License:: Your rights regarding this manual.
 
71
* Appendices::                     Technical stuff
 
72
* Command Index::                  A summary of all the gnubg commands.
 
73
* Concept Index::                  Index of concepts described in this manual.
 
74
@end menu
 
75
 
 
76
@end ifnottex
 
77
 
 
78
@node Introduction
 
79
@chapter Introduction
 
80
@cindex introduction
 
81
 
 
82
GNU Backgammon (@gnubg{}) plays and analyses backgammon games and matches. 
 
83
 
 
84
It is currently a work-in-progress.  So far it is able to play
 
85
individual games and tournament matches, evaluate and roll out
 
86
positions, tune its own evaluation functions using either
 
87
@uref{http://www.research.ibm.com/massdist/tdl.html,,TD} or supervised
 
88
training, maintain databases of positions for training and other
 
89
purposes, and more.
 
90
 
 
91
It is driven by a command-line interface, and displays an ASCII
 
92
rendition of a board on text-only terminals, but also allows the user to
 
93
play games and manipulate positions with a GTK+
 
94
@uref{http://www.gnu.org/software/gnubg/board.png,,board window} where
 
95
available.  It is extensible on platforms which support
 
96
@uref{http://www.gnu.org/software/guile/guile.html,,Guile}.
 
97
 
 
98
It currently plays at about the level of a championship flight
 
99
tournament player (depending on its parameters and its luck in recent
 
100
games, it rates from around 1900 to 2000 on
 
101
@cindex FIBS
 
102
@uref{http://www.fibs.com/,,FIBS}, the First Internet Backgammon Server
 
103
--- at its strongest, it ranks in the top 5 of over 6000 rated players
 
104
there) and is gradually improving; it should be somewhat stronger than
 
105
this when released.  Since almost all of the CPU time required during
 
106
supervised training is spent performing rollouts, and rollouts can
 
107
easily be performed in parallel, it is hoped that users will be able to
 
108
pool rollout results and collectively train it to a level stronger than
 
109
any individual could obtain.
 
110
 
 
111
If you can tolerate the rough edges, periodic pre-releases of the source
 
112
will be made on @uref{ftp://alpha.gnu.org/gnu/gnubg/,the alpha.gnu.org
 
113
FTP server}.
 
114
 
 
115
Anonymous CVS access to the very latest code is available: if you have a
 
116
CVS client, set @env{CVSROOT} to
 
117
@code{:pserver:anoncvs@@subversions.gnu.org:/cvs} and check out module
 
118
@file{gnubg}.  If not, daily snapshots of the CVS repository are made
 
119
available by @uref{ftp://alpha.gnu.org/gnu/gnubg/snapshots/,FTP}, or you
 
120
can browse the repository through the
 
121
@uref{http://subversions.gnu.org/cgi-bin/cvsweb/gnubg/,WWW gateway}.  Do
 
122
not expect this code to be stable; it will generally include both more
 
123
features and more bugs than the main pre-release version.
 
124
 
 
125
You can also compete against recent versions of @gnubg{} on FIBS; it
 
126
plays there under the names @samp{gnu}, @samp{mgnutest}, @samp{mpgnu}
 
127
and @samp{gnu_one_ply}.
 
128
 
 
129
@node How to Play Backgammon
 
130
@chapter How to Play Backgammon
 
131
@cindex backgammon
 
132
 
 
133
The rules presented in this chapter were written by Tom Keith for the
 
134
@uref{http://www.bkgm.com/,Backgammon Galore web site}, and are included
 
135
here with his permission.
 
136
 
 
137
@menu
 
138
* Rules of Backgammon::         How to play the board game.
 
139
* Match Play::                  Special rules used in tournament matches.
 
140
@end menu
 
141
 
 
142
@node Rules of Backgammon
 
143
@section Rules of Backgammon
 
144
@cindex backgammon rules
 
145
@subsection Setup
 
146
@cindex board setup
 
147
 
 
148
Backgammon is a game for two players, played on a board consisting of 
 
149
twenty-four narrow triangles called @cindex points
 
150
@dfn{points}. 
 
151
The triangles alternate in color and are grouped into four quadrants of 
 
152
six triangles each. 
 
153
The quadrants are referred to as a player's
 
154
@cindex home board
 
155
@dfn{home board} and
 
156
@cindex outer board
 
157
@dfn{outer board}, and the opponent's home board and outer board. 
 
158
The home and outer boards are separated from each other by a ridge down 
 
159
the center of the board called the
 
160
@cindex bar
 
161
@dfn{bar}. 
 
162
 
 
163
@ifnottex
 
164
@multitable @columnfractions 0.67 0.33
 
165
@item @image{rulfig1} @tab @strong{Figure 1.}  A board with the checkers
 
166
in their initial position.
 
167
 
 
168
An alternate arrangement is the reverse of the one shown here, with the
 
169
home board on the left and the outer board on the right.
 
170
@end multitable
 
171
@end ifnottex
 
172
@tex
 
173
\medskip
 
174
\hbox{
 
175
\hbox{@image{rulfig1}}
 
176
\vbox{
 
177
\hsize=5 cm
 
178
\raggedright
 
179
\parindent=0 pt
 
180
{\bf Figure 1.}  A board with the checkers in their initial position.\par
 
181
 
 
182
\hsize=5 cm
 
183
\raggedright
 
184
\parindent=0 pt
 
185
An alternate arrangement is the reverse of the one shown here, with the
 
186
home board on the left and the outer board on the right.\par\vskip 2 cm}}
 
187
@end tex
 
188
 
 
189
The points are numbered for either player starting in that player's home 
 
190
board. 
 
191
The outermost point is the twenty-four point, which is also the opponent's 
 
192
one point.  
 
193
Each player has fifteen checkers of his own color. 
 
194
The initial arrangement of checkers is: 
 
195
two on each player's twenty-four point, five on each player's thirteen point, 
 
196
three on each player's eight point, and five on each player's six point.
 
197
 
 
198
@cindex doubling cube
 
199
Both players have their own pair of dice and a dice cup used for shaking.  
 
200
A @dfn{doubling cube}, with the numerals 2, 4, 8, 16, 32, and 64 on its 
 
201
faces, is used to keep track of the current stake of the game.
 
202
 
 
203
@subsection Object of the Game
 
204
@cindex object of the game
 
205
 
 
206
The object of the game is for a player to move all of his checkers into 
 
207
his own home board and then bear them off. 
 
208
The first player to bear off all of his checkers wins the game.
 
209
 
 
210
@ifnottex
 
211
@multitable @columnfractions 0.67 0.33
 
212
@item @image{rulfig2} @tab @strong{Figure 2.}  Direction of movement of
 
213
White's checkers.  Red's checkers move in the opposite direction.
 
214
@end multitable
 
215
@end ifnottex
 
216
@tex
 
217
\medskip
 
218
\hbox{
 
219
\hbox{@image{rulfig2}}
 
220
\vbox{
 
221
\hsize=5 cm
 
222
\raggedright
 
223
\parindent=0 pt
 
224
{\bf Figure 2.}  Direction of movement of White's checkers.  Red's
 
225
checkers move in the opposite direction.\par\vskip 2 cm}}
 
226
@end tex
 
227
 
 
228
@subsection Movement of the Checkers
 
229
@cindex moving chequers, rules
 
230
 
 
231
To start the game, each player throws a single die.  
 
232
This determines both the player to go first and the numbers to be played. 
 
233
If equal numbers come up, then both players roll again until they roll 
 
234
different numbers.  
 
235
The player throwing the higher number now moves his checkers according to 
 
236
the numbers showing on both dice.  
 
237
After the first roll, the players throw two dice and alternate turns.
 
238
 
 
239
@cindex pips
 
240
The roll of the dice indicates how many points, or @dfn{pips}, 
 
241
the player is to move his checkers.  
 
242
The checkers are always moved forward, to a lower-numbered point.
 
243
The following rules apply:
 
244
 
 
245
@enumerate
 
246
@item
 
247
@cindex open point
 
248
A checker may be moved only to an @dfn{open point}, one that is not 
 
249
occupied by two or more opposing checkers.
 
250
 
 
251
@item
 
252
The numbers on the two dice constitute separate moves. 
 
253
For example, if a player rolls 5 and 3, he may move one checker five 
 
254
spaces to an open point and another checker three spaces to an open 
 
255
point, or he may move the one checker a total of eight spaces to an 
 
256
open point, but only if the intermediate point (either three or five 
 
257
spaces from the starting point) is also open.
 
258
 
 
259
@ifnottex
 
260
@multitable @columnfractions 0.67 0.33
 
261
@item @image{rulfig3} @tab @strong{Figure 3.}  Two ways that White can
 
262
play a roll of 53.
 
263
@end multitable
 
264
@end ifnottex
 
265
@tex
 
266
\medskip
 
267
\hbox{
 
268
\hbox{@image{rulfig3}}
 
269
\vbox{
 
270
\hsize=5 cm
 
271
\raggedright
 
272
\parindent=0 pt
 
273
{\bf Figure 3.}  Two ways that White can
 
274
play a roll of 53.\par\vskip 2 cm}}
 
275
@end tex
 
276
 
 
277
@item
 
278
A player who rolls doubles plays the numbers shown on the dice twice.  
 
279
A roll of 6 and 6 means that the player has four sixes to use, and he 
 
280
may move any combination of checkers he feels appropriate to complete 
 
281
this requirement.
 
282
 
 
283
@item
 
284
A player must use both numbers of a roll if this is legally possible 
 
285
(or all four numbers of a double). 
 
286
When only one number can be played, the player must play that number. 
 
287
Or if either number can be played but not both, the player must play 
 
288
the larger one. 
 
289
When neither number can be used, the player loses his turn. 
 
290
In the case of doubles, when all four numbers cannot be played, the 
 
291
player must play as many numbers as he can.
 
292
@end enumerate
 
293
 
 
294
@subsection Hitting and Entering
 
295
@cindex hitting
 
296
@cindex entering
 
297
 
 
298
A point occupied by a single checker of either color is called a
 
299
@cindex blot
 
300
@dfn{blot}.  If an opposing checker lands on a blot, the blot is @dfn{hit}
 
301
and placed on the bar.
 
302
 
 
303
Any time a player has one or more checkers on the bar, his first obligation 
 
304
is to
 
305
@cindex enter
 
306
@dfn{enter} those checker(s) into the opposing home board. 
 
307
A checker is entered by moving it to an open point corresponding to one of 
 
308
the numbers on the rolled dice.
 
309
 
 
310
For example, if a player rolls 4 and 6, he may enter a checker 
 
311
onto either the opponent's four point or six point, so long as the 
 
312
prospective point is not occupied by two or more of the opponent's checkers. 
 
313
 
 
314
@ifnottex
 
315
@multitable @columnfractions 0.67 0.33
 
316
@item @image{rulfig4} @tab @strong{Figure 4.}  If White rolls 64 with a
 
317
checker on the bar, he must enter the checker onto Red's four point 
 
318
since Red's six point is not open.
 
319
@end multitable
 
320
@end ifnottex
 
321
@tex
 
322
\medskip
 
323
\hbox{
 
324
\hbox{@image{rulfig4}}
 
325
\vbox{
 
326
\hsize=5 cm
 
327
\raggedright
 
328
\parindent=0 pt
 
329
{\bf Figure 4.}  If White rolls 64 with a
 
330
checker on the bar, he must enter the checker onto Red's four point 
 
331
since Red's six point is not open.\par\vskip 2 cm}}
 
332
@end tex
 
333
 
 
334
If neither of the points is open, the player loses his turn.  
 
335
If a player is able to enter some but not all of his checkers, he must enter 
 
336
as many as he can and then forfeit the remainder of his turn.
 
337
 
 
338
After the last of a player's checkers has been entered, any unused numbers 
 
339
on the dice must be played, by moving either the checker that was entered 
 
340
or a different checker.
 
341
 
 
342
@subsection Bearing Off
 
343
@cindex bearing off
 
344
 
 
345
Once a player has moved all of his fifteen checkers into his home board, 
 
346
he may commence @dfn{bearing off}. 
 
347
A player bears off a checker by rolling a number that corresponds to the 
 
348
point on which the checker resides, and then removing that checker from 
 
349
the board. 
 
350
Thus, rolling a 6 permits the player to remove a checker from the six point.
 
351
 
 
352
If there is no checker on the point indicated by the roll, the player 
 
353
must make a legal move using a checker on a higher-numbered point. 
 
354
If there are no checkers on higher-numbered points, the player is 
 
355
permitted (and required) to remove a checker from the highest point on 
 
356
which one of his checkers resides. 
 
357
A player is under no obligation to bear off if he can make an otherwise 
 
358
legal move.
 
359
 
 
360
@ifnottex
 
361
@multitable @columnfractions 0.67 0.33
 
362
@item @image{rulfig5} @tab @strong{Figure 5.}  White rolls 64 and bears
 
363
off two checkers.
 
364
@end multitable
 
365
@end ifnottex
 
366
@tex
 
367
\medskip
 
368
\hbox{
 
369
\hbox{@image{rulfig5}}
 
370
\vbox{
 
371
\hsize=5 cm
 
372
\raggedright
 
373
\parindent=0 pt
 
374
{\bf Figure 5.}  White rolls 64 and bears off two checkers.\par\vskip 2 cm}}
 
375
@end tex
 
376
 
 
377
A player must have all of his active checkers in his home board in order 
 
378
to bear off. 
 
379
If a checker is hit during the bear-off process, the player must bring 
 
380
that checker back to his home board before continuing to bear off. 
 
381
The first player to bear off all fifteen checkers wins the game.
 
382
 
 
383
@subsection Doubling
 
384
@cindex doubling, rules
 
385
 
 
386
Backgammon is played for an agreed stake per point. 
 
387
Each game starts at one point. 
 
388
During the course of the game, a player who feels he has a sufficient 
 
389
advantage may propose doubling the stakes. 
 
390
He may do this only at the start of his own turn and before he has rolled 
 
391
the dice.
 
392
 
 
393
A player who is offered a double may @dfn{refuse}, in which case he 
 
394
concedes the game and pays one point. 
 
395
Otherwise, he must @dfn{accept} the double and play on for the new higher 
 
396
stakes.  
 
397
A player who accepts a double becomes the
 
398
@cindex cube owner
 
399
@dfn{owner of the cube} and only he may make the next double.  
 
400
 
 
401
Subsequent doubles in the same game are called @dfn{redoubles}. 
 
402
If a player refuses a redouble, he must pay the number of points that were 
 
403
at stake prior to the redouble.  
 
404
Otherwise, he becomes the new owner of the cube and the game continues
 
405
at twice the previous stakes.  
 
406
There is no limit to the number of redoubles in a game.
 
407
 
 
408
@subsection Gammons and Backgammons
 
409
@cindex gammons
 
410
@cindex backgammons
 
411
 
 
412
At the end of the game, if the losing player has borne off at least one 
 
413
checker, he loses only the value showing on the doubling cube (one point, 
 
414
if there have been no doubles).  
 
415
However, if the loser has @emph{not} borne off any of his checkers, 
 
416
he is @dfn{gammoned} and loses @emph{twice} the value of the doubling cube.  
 
417
Or, worse, if the loser has not borne off any of his checkers and still has 
 
418
a checker on the bar or in the winner's home board, he is @dfn{backgammoned}
 
419
and loses @emph{three times} the value of the doubling cube.
 
420
 
 
421
@subsection Optional Rules
 
422
@cindex optional rules
 
423
@cindex rules, optional
 
424
 
 
425
The following optional rules are in widespread use.  
 
426
 
 
427
@table @dfn
 
428
@item Automatic doubles
 
429
@cindex automatic doubles
 
430
@cindex doubles, automatic
 
431
If identical numbers are thrown on the first roll, the stakes are doubled.
 
432
The doubling cube is turned to 2 and remains in the middle. 
 
433
Players usually agree to limit the number of automatic doubles to one per game.
 
434
 
 
435
@item Beavers
 
436
@cindex beavers
 
437
When a player is doubled, he may immediately redouble (beaver) while 
 
438
retaining possession of the cube.  
 
439
The original doubler has the option of accepting or refusing as with a
 
440
normal double.
 
441
 
 
442
@item The Jacoby Rule
 
443
@cindex Jacoby rule
 
444
Gammons and backgammons count only as a single game if neither player has
 
445
offered a double during the course of the game.
 
446
This rule speeds up play by eliminating situations where a player avoids 
 
447
doubling so he can play on for a gammon.
 
448
@end table
 
449
 
 
450
@subsection Irregularities
 
451
@cindex irregularities
 
452
 
 
453
@enumerate
 
454
@item
 
455
The dice must be rolled together and land flat on the surface of the 
 
456
right-hand section of the board. 
 
457
The player must reroll both dice if a die lands outside the right-hand 
 
458
board, or lands on a checker, or does not land flat.
 
459
 
 
460
@item
 
461
A turn is completed when the player picks up his dice. 
 
462
If the play is incomplete or otherwise illegal, the opponent has the option 
 
463
of accepting the play as made or of requiring the player to make a legal play. 
 
464
A play is deemed to have been accepted as made when the opponent rolls his 
 
465
dice or offers a double to start his own turn.
 
466
 
 
467
@item
 
468
If a player rolls before his opponent has completed his turn by picking up 
 
469
the dice, the player's roll is voided. 
 
470
This rule is generally waived any time a play is forced or when there is no 
 
471
further contact between the opposing forces.
 
472
@end enumerate
 
473
 
 
474
@node Match Play
 
475
@section Rules for Match Play
 
476
@cindex match rules
 
477
 
 
478
When backgammon tournaments are held to determine an overall winner, 
 
479
the usual style of competition is @dfn{match play}. 
 
480
Competitors are paired off, and each pair plays a series of games to decide 
 
481
which player progresses to the next round of the tournament.  
 
482
This series of games is called a @dfn{match}.
 
483
 
 
484
Matches are played to a specified number of points. 
 
485
The first player to accumulate the required points wins the match. 
 
486
Points are awarded in the usual manner: 
 
487
one for a single game, two for a gammon, and three for a backgammon. 
 
488
The doubling cube is used, so the winner receives the value of the game 
 
489
multiplied by the final value of the doubling cube.
 
490
 
 
491
Matches are normally played using the
 
492
@cindex Crawford rule
 
493
@dfn{Crawford rule}. 
 
494
The Crawford rule states that if one player reaches a score one point short 
 
495
of the match, neither player may offer a double in the immediately following 
 
496
game. 
 
497
This one game without doubling is called the Crawford game. 
 
498
Once the Crawford game has been played, if the match has not yet been decided, the doubling 
 
499
cube is active again.
 
500
 
 
501
@html
 
502
<center><table width=406 border=0 cellspacing=0 cellpadding=1>
 
503
<tr><td colspan=2><font face="Arial,Helvetica"><b>Match to 5</b></font></td>    <td align=center><font size=2 face="Arial,Helvetica"><b>&nbsp;White&nbsp;</b></font></td>       <td align=center><font size=2 face="Arial,Helvetica"><b>&nbsp;Black&nbsp;</b></font></td><tr>
 
504
<tr><td colspan=6><img src="bar.png" border=0 width=402 height=3></td></tr>
 
505
<tr><td><b>Game 1:&nbsp;&nbsp;</b></td><td>White wins 2 points&nbsp;&nbsp;</td> <td align=center>2</td>         <td align=center>0</td> <td rowspan=3 valign=center><img src="rbrace3.png" width=9 height=52></td><td rowspan=3 valign=center><font size=2 face="Arial,Helvetica">&nbsp;Doubling Allowed</font></td></tr>
 
506
<tr><td><b>Game 2:</b></td><td>Black wins 1 point</td>  <td align=center>2</td>         <td align=center>1</td></tr>
 
507
<tr><td><b>Game 3:</b></td><td>White wins 2 points</td><td align=center>4</td>          <td align=center>1</td></tr>
 
508
<tr bgcolor=FFCC99><td><b>Game 4:</b></td><td>Black wins 1 point</td>   <td align=center>4</td>         <td align=center>2</td>         <td>&nbsp;</td><td><font size=2 face="Arial,Helvetica">&nbsp;Crawford Game</font></td></tr>
 
509
<tr><td><b>Game 5:</b></td><td>Black wins 2 points</td><td align=center>4</td>          <td align=center>4</td>         <td rowspan=2 valign=center><img src="rbrace2.png" width=9 height=34></td><td rowspan=2 valign=center><font size=2 face="Arial,Helvetica">&nbsp;Doubling Allowed</font></td></tr>
 
510
<tr><td><b>Game 6:</b></td><td>White wins 2 points</td><td align=center>6</td>          <td align=center>4</td></tr>
 
511
<tr><td colspan=6><img src="bar.png" border=0 width=402 height=3></td></tr>
 
512
</table></center>
 
513
@end html
 
514
@tex
 
515
\medskip
 
516
\moveright 5 mm \vbox{
 
517
\settabs \+ \hskip 6 cm & \hskip 2 cm & \hskip 2 cm & \cr
 
518
\+ \bf Match to 5 & \bf \hfil White \hfil & \bf \hfil Black \hfil & \cr
 
519
\smallskip
 
520
\hrule width 14 cm
 
521
\smallskip
 
522
\hbox{\vbox{%
 
523
\+ {\bf Game 1:}\quad White wins 2 points & \hfil 2 \hfil & \hfil 0 \hfil & \cr
 
524
\+ {\bf Game 2:}\quad Black wins 1 point & \hfil 2 \hfil & \hfil 1 \hfil & \cr
 
525
\+ {\bf Game 3:}\quad White wins 2 points & \hfil 4 \hfil & \hfil 1 \hfil & \cr
 
526
}\vbox{%
 
527
\vfil
 
528
\hbox{$\Biggr\}$Doubling Allowed}
 
529
\vfil}
 
530
}
 
531
\+ {\bf Game 4:}\quad Black wins 1 point & \hfil 4 \hfil & \hfil 2 \hfil & \quad Crawford Game \cr
 
532
\hbox{\vbox{%
 
533
\+ {\bf Game 5:}\quad Black wins 2 points & \hfil 4 \hfil & \hfil 4 \hfil & \cr
 
534
\+ {\bf Game 6:}\quad White wins 2 points & \hfil 6 \hfil & \hfil 4 \hfil & \cr
 
535
}\vbox{%
 
536
\vfil
 
537
\hbox{$\biggr\}$Doubling Allowed}
 
538
\vfil}
 
539
}}
 
540
@end tex
 
541
@ifinfo
 
542
@example
 
543
Match to 5                    White  Black
 
544
--------------------------------------------------------------
 
545
Game 1:  White wins 2 points    2      0  \
 
546
Game 2:  Black wins 1 point     2      1   @} Doubling Allowed
 
547
Game 3:  White wins 2 points    4      1  /
 
548
Game 4:  Black wins 1 point     4      2     Crawford Game
 
549
Game 5:  Black wins 2 points    4      4  \
 
550
Game 6:  White wins 2 points    6      4  /  Doubling Allowed
 
551
@end example
 
552
@end ifinfo
 
553
@quotation
 
554
In this example, White and Black are playing a 5-point match.
 
555
After three games White has 4 points, which is just one point 
 
556
short of what he needs.  
 
557
That triggers the Crawford rule which says there can be no 
 
558
doubling in next game, Game 4.
 
559
@end quotation
 
560
 
 
561
There is no bonus for winning more than the required number of points
 
562
in match play.
 
563
The sole goal is to win the match, and the size of the victory doesn't matter.
 
564
 
 
565
Automatic doubles, beavers, and the Jacoby rule are not used in match play. 
 
566
 
 
567
@node Sample Game
 
568
@chapter Sample Game
 
569
@cindex sample game
 
570
 
 
571
Although GNU Backgammon has many commands and options, only a few of them
 
572
are used during routine play.  This chapter demonstrates some of those
 
573
most commonly used.
 
574
 
 
575
If your @gnubg{} installation is complete, you should be able to start it
 
576
and see output similar to the following:
 
577
 
 
578
@example
 
579
GNU Backgammon 0.02  Copyright 1999, 2000, 2001 Gary Wong.
 
580
GNU Backgammon is free software, covered by the GNU General Public
 
581
License, and you are welcome to change it and/or distribute copies
 
582
of it under certain conditions.  Type "show copying" to see the
 
583
conditions.
 
584
There is absolutely no warranty for GNU Backgammon.  Type "show
 
585
warranty" for details.
 
586
(No game) 
 
587
@end example
 
588
 
 
589
When you start a game, @gnubg{} will (by default) show which player's move it
 
590
is; it is displaying @samp{(No game)} at the moment to indicate that it
 
591
isn't anybody's turn.
 
592
 
 
593
GNU Backgammon uses a pseudo-random number generator to produce dice
 
594
rolls.  It will normally initialise the state of the generator to
 
595
some value based on the current time (and perhaps other system information,
 
596
depending what features are available on your platform).  But for purposes
 
597
of this example, it will be better to start the generator from a known
 
598
state, so that the rolls it generates will be repeatable.  Enter the
 
599
following command to change the generator state (``seed''):
 
600
 
 
601
@example
 
602
(No game) set seed 15
 
603
Seed set to 15.
 
604
(No game)   
 
605
@end example
 
606
 
 
607
The default settings allow you to play X (the black pieces, if you have
 
608
a graphical board window) and the computer will play O (red).  It will
 
609
play with no lookahead by default; it is very fast at choosing moves
 
610
in this mode (instantaneous, on most hardware) though it does not play
 
611
at its full strength.  Let's start a game.
 
612
 
 
613
@example
 
614
(No game) new game
 
615
gnubg rolls 1, user rolls 3.
 
616
@group
 
617
 GNU Backgammon  Position ID: 4HPwATDgc/ABMA
 
618
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
619
 | X           O    |   | O              X |     
 
620
 | X           O    |   | O              X |     
 
621
 | X           O    |   | O                |     
 
622
 | X                |   | O                |     
 
623
 | X                |   | O                |    
 
624
v|                  |BAR|                  |     (Cube: 1)
 
625
 | O                |   | X                |    
 
626
 | O                |   | X                |     
 
627
 | O           X    |   | X                |     
 
628
 | O           X    |   | X              O |     
 
629
 | O           X    |   | X              O |     Rolled 13
 
630
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
631
@end group
 
632
 
 
633
(user) 
 
634
@end example
 
635
 
 
636
This is the output you will see if a graphical board is unavailable or
 
637
disabled; if your environment supports a graphical board, you will see a
 
638
better representation of a backgammon board than this.  Exactly the
 
639
same information is available, either way.
 
640
 
 
641
You have just won the opening roll (you have a 3, and @gnubg{} has a 1) --- the
 
642
dice roll is in the bottom right hand corner for the TTY board, or shown
 
643
as graphical dice on the right hand side of the board window.  The
 
644
position ID (the @samp{4HPwATDgc/ABMA} in this example) is an encoded
 
645
representation of the current position.  It comes in useful when using
 
646
some of @gnubg{}'s advanced commands, but you can safely ignore it for now.
 
647
Notice that the prompt has changed to @samp{(user)}, to indicate that it
 
648
is your turn; on systems where a login name is available, @gnubg{} will
 
649
use that instead.
 
650
 
 
651
If you are familiar with backgammon, you will know that the best play
 
652
for this roll is to make your 5 point.  The command to do that is:
 
653
 
 
654
@example
 
655
(user) 8 5 6 5
 
656
@end example
 
657
 
 
658
@noindent
 
659
in the terminal window (i.e.@: move one chequer from your 8 point to
 
660
your 5 point, and move another from your 6 to your 5 point); or by
 
661
dragging each chequer to the destination point in the board window.
 
662
Click mouse button 1 on the dice to indicate you have finished your move
 
663
(just as you would pick up your dice to end your move if you were
 
664
playing on a real board).
 
665
 
 
666
Once you have done that, @gnubg{} will take its turn, rolling 63 and playing
 
667
24/15.  It is now your move again:
 
668
 
 
669
@example
 
670
@group
 
671
 GNU Backgammon  Position ID: 4HPwCSCwZ/ABMA
 
672
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
673
 | X           O    |   | O              X |     
 
674
 | X           O    |   | O              X |     
 
675
 | X           O    |   | O                |     
 
676
 | X                |   | O                |     
 
677
 | X                |   | O                |    
 
678
v|                  |BAR|                  |     (Cube: 1)
 
679
 | O                |   |                  |    
 
680
 | O                |   | X                |     
 
681
 | O                |   | X                |     
 
682
 | O           X    |   | X  X             |     
 
683
 | O     O     X    |   | X  X           O |     On roll
 
684
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
685
@end group
 
686
 
 
687
(user) 
 
688
@end example
 
689
 
 
690
Since it is no longer the opening roll, you have the option of doubling
 
691
before rolling your dice.  To roll without doubling, just enter the
 
692
command @kbd{roll} (or @kbd{r} for short):
 
693
 
 
694
@example
 
695
(gnubg) roll
 
696
@group
 
697
 GNU Backgammon  Position ID: 4HPwCSCwZ/ABMA
 
698
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
699
 | X           O    |   | O              X |     
 
700
 | X           O    |   | O              X |     
 
701
 | X           O    |   | O                |     
 
702
 | X                |   | O                |     
 
703
 | X                |   | O                |    
 
704
v|                  |BAR|                  |     (Cube: 1)
 
705
 | O                |   |                  |    
 
706
 | O                |   | X                |     
 
707
 | O                |   | X                |     
 
708
 | O           X    |   | X  X             |     
 
709
 | O     O     X    |   | X  X           O |     Rolled 35
 
710
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
711
@end group
 
712
 
 
713
(user)
 
714
@end example
 
715
 
 
716
@noindent
 
717
(You can also roll by clicking the dice just underneath the board
 
718
window.)
 
719
 
 
720
Let's play this roll by hitting twice: 13/10*, 6/1*.  You can enter this
 
721
move with @kbd{13 10 6 1} --- note that you don't need to specify anything
 
722
special to hit; @gnubg{} will automatically move blots that are hit to the
 
723
bar.  You can also make this move by dragging chequers in the board window,
 
724
of course.
 
725
 
 
726
@example
 
727
(user) 13 10 6 1
 
728
@group
 
729
 GNU Backgammon  Position ID: 4HPwAWBhZ+IBMA
 
730
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
731
 | X           O    | O | O              X |     
 
732
 | X           O    | O | O              X |     
 
733
 | X           O    |   | O                |     
 
734
 | X                |   | O                |     
 
735
 |                  |   | O                |    
 
736
v|                  |BAR|                  |     (Cube: 1)
 
737
 | O                |   |                  |    
 
738
 | O                |   |                  |     
 
739
 | O                |   | X                |     
 
740
 | O           X    |   | X  X             |     
 
741
 | O     X     X    |   | X  X           X |     On roll
 
742
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
743
@end group
 
744
 
 
745
(user) 
 
746
@end example
 
747
 
 
748
GNU Backgammon has rolled 65 and been unable to move.  Let's take another
 
749
roll:
 
750
 
 
751
@example
 
752
(user) roll
 
753
@group
 
754
 GNU Backgammon  Position ID: 4HPwAWBhZ+IBMA
 
755
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
756
 | X           O    | O | O              X |     
 
757
 | X           O    | O | O              X |     
 
758
 | X           O    |   | O                |     
 
759
 | X                |   | O                |     
 
760
 |                  |   | O                |    
 
761
v|                  |BAR|                  |     (Cube: 1)
 
762
 | O                |   |                  |    
 
763
 | O                |   |                  |     
 
764
 | O                |   | X                |     
 
765
 | O           X    |   | X  X             |     
 
766
 | O     X     X    |   | X  X           X |     Rolled 25
 
767
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
768
@end group
 
769
 
 
770
(user)
 
771
@end example
 
772
 
 
773
Play this roll as @kbd{13 11 6 1}.  @gnubg{} will now roll 16 --- and still
 
774
can't move!
 
775
 
 
776
@example
 
777
@group
 
778
 GNU Backgammon  Position ID: 4HPwAWDDZsoBMA
 
779
 +13-14-15-16-17-18------19-20-21-22-23-24-+     gnubg
 
780
 | X           O    | O | O              X |     
 
781
 | X           O    | O | O              X |     
 
782
 | X           O    |   | O                |     
 
783
 |                  |   | O                |     
 
784
 |                  |   | O                |    
 
785
v|                  |BAR|                  |     (Cube: 1)
 
786
 | O                |   |                  |    
 
787
 | O                |   |                  |     
 
788
 | O                |   |                  |     
 
789
 | O           X    |   | X  X           X |     
 
790
 | O  X  X     X    |   | X  X           X |     On roll
 
791
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     user
 
792
@end group
 
793
 
 
794
(user) 
 
795
@end example
 
796
 
 
797
Our position is now strong.  Let's try doubling --- this can be done by
 
798
entering the command @kbd{double} at the prompt, or by clicking the
 
799
doubling cube in the board window.  When you are doubled, you should use
 
800
the command @kbd{take} or @kbd{drop} to accept or refuse the cube.  GNU
 
801
Backgammon will drop this double:
 
802
 
 
803
@example
 
804
(user) double
 
805
gnubg refuses the cube and gives up 1 point.
 
806
user wins a single game and 1 points.
 
807
The score (after 1 game) is: gnubg 0, user 1 (money session,
 
808
without Jacoby rule).
 
809
@end example
 
810
 
 
811
That concludes the example game.  You have seen most of the commands
 
812
normally used while playing; others you will need include @kbd{bar}
 
813
when re-entering a hit chequer (e.g.@: @kbd{bar 20 24 20}) and
 
814
@kbd{off} to remove a chequer from the board when bearing off
 
815
(e.g.@: @kbd{6 off 5 off}).
 
816
 
 
817
Type @kbd{help} from within @gnubg{} for a summary of all commands, or
 
818
browse the rest of this manual to learn more.  Have fun playing
 
819
GNU Backgammon!
 
820
 
 
821
@ignore
 
822
We need to think of logical sections that each command belongs to so
 
823
that appropriate commands are documented together.  We can easily make
 
824
a table or summary later to group commands by name; for the rest of
 
825
the manual it is better to group them by purpose.
 
826
 
 
827
accept                  playing         / the game, cube
 
828
agree                   playing         / the game
 
829
analysis                analysis
 
830
beaver                  playing         / cube
 
831
database dump           databases
 
832
database export         databases
 
833
database generate       databases
 
834
database import         databases
 
835
database rollout        databases
 
836
database train          databases
 
837
decline                 playing         / the game
 
838
double                  playing         / cube
 
839
drop                    playing         / cube
 
840
eval                    analysis
 
841
exit                    invocation
 
842
export database         databases
 
843
export game
 
844
export match
 
845
export pos
 
846
external                playing         / computer player
 
847
help                    basic
 
848
hint                    playing         / the game
 
849
list game
 
850
list match
 
851
list session
 
852
load commands
 
853
load game               playing         / recording
 
854
load match              playing         / recording
 
855
load weights            training
 
856
move                    playing         / the game
 
857
new game                playing
 
858
new match               playing         / matches and sessions
 
859
new session             playing         / matches and sessions
 
860
new weights             training
 
861
next
 
862
pass                    playing
 
863
play                    playing         / computer player
 
864
previous
 
865
quit                    invocation
 
866
redouble                playing         / cube
 
867
reject                  playing
 
868
resign                  playing
 
869
roll                    playing         / dice
 
870
rollout                 analysis
 
871
save game               playing         / recording
 
872
save match              playing         / recording
 
873
save settings
 
874
save weights            training
 
875
set auto bearoff        playing         / the game
 
876
set auto crawford       playing         / matches and sessions
 
877
set auto doubles        playing         / matches and sessions
 
878
set auto game           playing         / matches and sessions
 
879
set auto move           playing         / the game
 
880
set auto roll           playing         / dice
 
881
set beavers
 
882
set board               playing         / the game
 
883
set cache               analysis
 
884
set colours             gtk
 
885
set confirm
 
886
set crawford            playing         / matches and sessions
 
887
set cube centre         playing         / cube
 
888
set cube owner          playing         / cube
 
889
set cube use            playing         / cube
 
890
set cube value          playing         / cube
 
891
set delay               gtk
 
892
set dice                playing         / dice
 
893
set display             playing         / the game
 
894
set evaluation *        analysis
 
895
set jacoby              playing         / matches and sessions
 
896
set matchequitytable *
 
897
set nackgammon
 
898
set output matchpc
 
899
set output mwc
 
900
set output winpc
 
901
set player eval *       playing         / computer player
 
902
set player external     playing         / computer player
 
903
set player gnubg        playing         / computer player
 
904
set player human        playing         
 
905
set player name         playing         
 
906
set player pubeval      playing         / computer player
 
907
set postcrawford        playing         / matches and sessions
 
908
set prompt
 
909
set rng ansi            playing         / dice
 
910
set rng bsd             playing         / dice
 
911
set rng isaac           playing         / dice
 
912
set rng manual          playing         / dice
 
913
set rng md5             playing         / dice
 
914
set rng mersenne        playing         / dice
 
915
set rng user            playing         / dice
 
916
set rollout *           analysis
 
917
set score               playing         / matches and sessions
 
918
set seed                playing         / dice
 
919
set turn                playing
 
920
show automatic
 
921
show beavers
 
922
show board              playing
 
923
show cache              analysis
 
924
show commands
 
925
show confirm            playing?
 
926
show copying            basic
 
927
show crawford           playing         / matches and sessions
 
928
show cube
 
929
show delay              gtk
 
930
show dice
 
931
show display
 
932
show evaluation
 
933
show gammonprice        analysis
 
934
show jacoby             playing         / matches and sessions
 
935
show kleinman
 
936
show marketwindow       analysis
 
937
show matchequitytable   analysis
 
938
show nackgammon
 
939
show output
 
940
show pipcount           playing
 
941
show player             playing
 
942
show postcrawford       playing         / matches and sessions
 
943
show prompt
 
944
show rng                playing         / dice
 
945
show rollout
 
946
show score              playing         / matches and sessions
 
947
show seed               playing         / dice
 
948
show thorp
 
949
show turn               playing
 
950
show warranty           basic
 
951
take                    playing         / cube
 
952
train database          training
 
953
train td                training
 
954
! (shell)
 
955
: (Guile)
 
956
@end ignore
 
957
 
 
958
@node Invocation
 
959
@chapter Starting and Leaving @gnubg
 
960
 
 
961
This chapter describes how to run @gnubg{}, and how to end it when you
 
962
are finished.
 
963
 
 
964
@menu
 
965
* Invoking gnubg::              How to start gnubg.
 
966
* Leaving gnubg::               How to end gnubg.
 
967
* Shell Commands::              How to issue shell commands from within gnubg.
 
968
@end menu
 
969
 
 
970
@node Invoking gnubg
 
971
@section Invoking @gnubg
 
972
@cindex invoking @t{gnubg}
 
973
@cindex starting @t{gnubg}
 
974
@cindex running @t{gnubg}
 
975
@cindex command line options
 
976
 
 
977
Start GNU Backgammon by running the program @kbd{gnubg}.  Once started, it
 
978
will process commands from the terminal.
 
979
 
 
980
You can also instruct @gnubg{} to read an existing game or match from a
 
981
file, to play or analyse.  To read from @var{filename}, specify
 
982
@kbd{gnubg @var{filename}}.
 
983
 
 
984
@gnubg{} will give you a short summary of how to invoke it if given the
 
985
option @option{--help} (@option{-h} for short), and report its version
 
986
with @option{--version} (@option{-v}).
 
987
 
 
988
GNU Backgammon will normally use a graphical board window if a window
 
989
system is available.  To prevent this behaviour and use standard
 
990
terminal output instead, you can specify the @option{--tty} option (which
 
991
can be abbreviated to @option{-t}).
 
992
 
 
993
By default, @gnubg{} will attempt to load pre-trained neural net
 
994
weights; if you have no weights or wish to train a net from scratch,
 
995
you can supply the @option{--no-weights} (@option{-n}) option, and
 
996
new weights will be randomly generated.
 
997
 
 
998
FIXME the previous command is out of date; --no-weights is now --new-weights.
 
999
 
 
1000
FIXME document --no-bearoff, --no-rc, --datadir and
 
1001
--window-system-only options.
 
1002
 
 
1003
@node Leaving gnubg
 
1004
@section Leaving @gnubg
 
1005
@cindex leaving @t{gnubg}
 
1006
@cindex exiting @t{gnubg}
 
1007
@cindex quitting @t{gnubg}
 
1008
 
 
1009
@table @code
 
1010
@kindex exit
 
1011
@kindex quit
 
1012
@item exit
 
1013
@itemx quit
 
1014
To exit @gnubg{}, use the @kbd{exit} or @kbd{quit} commands (they are
 
1015
synonymous).  If you are currently playing a game, the match in progress
 
1016
will be lost, so @gnubg{} will ask you if you are sure you want to exit
 
1017
in this case.
 
1018
@end table
 
1019
 
 
1020
@gnubg{} will also exit upon end-of-file; you can therefore exit by typing
 
1021
an end-of-file character (usually @kbd{C-d}, i.e.@: hold the @key{CTRL}
 
1022
key and press D).
 
1023
 
 
1024
@cindex interrupting @t{gnubg}
 
1025
@cindex cancelling commands
 
1026
If you send an interrupt sequence (often by pressing @kbd{C-c}), the
 
1027
current @gnubg{} command (if any) will be terminated.  This can be useful
 
1028
if you do not want to wait for a slow command to complete.
 
1029
 
 
1030
@node Shell Commands
 
1031
@section Shell Commands
 
1032
@cindex shell commands
 
1033
@cindex escapes, shell
 
1034
 
 
1035
You can execute shell commands from @gnubg{} without leaving or suspending it.
 
1036
 
 
1037
@table @code
 
1038
@kindex !
 
1039
@item ![@var{command}]
 
1040
Invoke a subshell to execute @var{command}.  If you do not give a
 
1041
command, a shell will be invoked (the shell is specified by the environment
 
1042
variable @env{SHELL} if it is set, or defaults to @file{/bin/sh} if not).
 
1043
@end table
 
1044
 
 
1045
@node Basic Commands
 
1046
@chapter Basic Commands
 
1047
@cindex basic commands
 
1048
@cindex commands, basic
 
1049
 
 
1050
There are a few simple commands you can use within GNU Backgammon to
 
1051
display information you might need to know:
 
1052
 
 
1053
@table @code
 
1054
@kindex help
 
1055
@kindex ?
 
1056
@item help [@var{command}]
 
1057
@itemx ? [@var{command}]
 
1058
Describe the commands that @gnubg{} understands.  @code{help} by itself
 
1059
lists the main commands with a one-line description of each; when
 
1060
@var{command} is specified, that command is explained in more detail,
 
1061
and if it has any subcommands then they are listed in brief.
 
1062
 
 
1063
@code{?} is a synonym for @code{help}.
 
1064
@kindex show copying
 
1065
@kindex show warranty
 
1066
@item show copying
 
1067
@itemx show warranty
 
1068
These commands are used to show the conditions GNU Backgammon is
 
1069
distributed under (the GNU General Public License).  Essentially, there
 
1070
is no warranty for @gnubg{}, and everybody is free to use, inspect,
 
1071
copy, modify and distribute it.  You are permitted to do just about
 
1072
anything with @gnubg{}, except deny these freedoms to others.  For a
 
1073
precise description of your rights and obligations, please use the
 
1074
@code{show copying} and @code{show warranty} commands, or see the file
 
1075
@file{COPYING} in the @gnubg{} distribution (the contents are identical).
 
1076
@end table
 
1077
 
 
1078
@node Playing
 
1079
@chapter Playing Backgammon with @gnubg
 
1080
@cindex playing commands
 
1081
@cindex commands, playing
 
1082
 
 
1083
This chapter introduces several more commands used while playing games
 
1084
and matches in @gnubg{}.
 
1085
 
 
1086
@menu
 
1087
* The Game::                    Commands used during the game.
 
1088
* Dice::                        Controlling dice rolls.
 
1089
* Computer Player::             Having gnubg make moves.
 
1090
* Matches and Sessions::        Playing series of games.
 
1091
* Cube::                        Using the doubling cube.
 
1092
* Recording::                   Saving games and matches.
 
1093
@end menu
 
1094
 
 
1095
@node The Game
 
1096
@section Commands Used During the Game
 
1097
@cindex game commands
 
1098
 
 
1099
@table @code
 
1100
@kindex new game
 
1101
@item new game
 
1102
This command is used to start a game within a match or session.  (Note
 
1103
that all games are played within matches or sessions; see
 
1104
@ref{Matches and Sessions}.  To play a single game, use either a
 
1105
1 point match or a session lasting for one game, depending whether
 
1106
you want gammons and the doubling cube to be active.)  @code{new game}
 
1107
will set up the board in the starting position, and roll one die for
 
1108
each player for the opening move.
 
1109
 
 
1110
If you are in the middle of a game, @code{new game} will ask you if
 
1111
you want to abort the game in progress.  If you do, a new game will
 
1112
replace the current one (i.e.@: the partially completed game will have
 
1113
no effect on the score).  If you want the current game to be scored
 
1114
for either player, you should use the @code{resign} command instead.
 
1115
@kindex move
 
1116
@item move @var{from} @var{to} @dots{}
 
1117
@itemx move =@var{number}
 
1118
@itemx @var{from} @var{to} @dots{}
 
1119
@itemx =@var{number}
 
1120
 
 
1121
The @code{move} command allows you to make chequer plays when it is your
 
1122
turn.  In its normal form, you should specify pairs of point numbers
 
1123
indicating the points you want to move a chequer from and to.  Specify
 
1124
one pair for each chequer you want to move.  (For instance, on an
 
1125
opening roll of 31, you might use @code{move 8 5 6 5} to move two
 
1126
chequers --- one from your 8 point to your 5 point, and the other from
 
1127
your 6 point to your 5 point.)  For several example moves, see
 
1128
@ref{Sample Game}.
 
1129
 
 
1130
You should use the words @code{bar} and @code{off} when moving a chequer
 
1131
from the bar or bearing it off the board, e.g.@: @code{move bar 20} or
 
1132
@code{move 3 off}.  These words can be abbreviated to @code{b} and
 
1133
@code{o} respectively.
 
1134
 
 
1135
If there is only one legal move you can make, then the command @code{move}
 
1136
by itself will make it for you without requiring you to specify it in full.
 
1137
Similarly, if there is no play available at all, then @code{move} will
 
1138
end your turn without moving.
 
1139
 
 
1140
As long as you specify at least one pair of points, then the word
 
1141
@code{move} is optional --- the command @code{bar 20 24 20} means exactly
 
1142
the same thing as @code{move bar 20 24 20}, for instance.
 
1143
 
 
1144
FIXME document `=n' notation.
 
1145
 
 
1146
If you are using a window system, you can also move chequers using the
 
1147
board window.  One way to do this is to use any mouse button to drag a
 
1148
chequer (that is, press the button when the pointer is over the chequer
 
1149
you wish to move; move the pointer to the point you wish to play it to,
 
1150
and then release the button).
 
1151
 
 
1152
An alternative is to click a mouse button on the chequer; button 1 will
 
1153
move it by the number of pips showing on the left die, and any other
 
1154
button will move it according to the right die.  If you don't like the
 
1155
order the dice are displayed in, pressing either button 2 or 3 on the
 
1156
dice will swap their positions.
 
1157
 
 
1158
Whichever method you use to move the chequers, once you have made a legal
 
1159
move you can end your turn by clicking mouse button 1 on the dice.
 
1160
 
 
1161
FIXME reference set auto move and set auto bearoff.
 
1162
@kindex resign
 
1163
@kindex agree
 
1164
@kindex accept
 
1165
@kindex decline
 
1166
@kindex reject
 
1167
@item resign [@var{type}]
 
1168
@itemx agree
 
1169
@itemx accept
 
1170
@itemx decline
 
1171
@itemx reject
 
1172
The @code{resign} command is used to give up a game without playing it to
 
1173
completion.  It is often useful during endgame play when the game reaches
 
1174
a position where it is impossible for one player to win.  If you do not
 
1175
specify a value @var{type}, then the player whose turn it is offers to
 
1176
give up one game (at the current cube value) to the opponent; you can
 
1177
also specify @code{1}, @code{2} or @code{3} to resign a single, double
 
1178
or triple game.  Specifying @code{normal}, @code{gammon} or
 
1179
@code{backgammon} is also legal, and is identical to expressing the
 
1180
number of points as a digit.  @code{single} is yet another synonym for
 
1181
one game.
 
1182
 
 
1183
The opponent may accept the resignation with either the @code{agree} or
 
1184
@code{accept} commands, but is not obliged to.  To ignore the
 
1185
resignation and continue play normally, use either the @code{decline} or
 
1186
@code{reject} commands.  (@code{accept} and @code{reject} are also legal
 
1187
commands in response to a double; @pxref{Cube}.)
 
1188
@kindex set board
 
1189
@item set board @var{id}|=@var{number}
 
1190
If you wish to directly set the chequers to a different position, you
 
1191
can use the @code{set board} command.  You need to know the
 
1192
@dfn{position ID} of the chequer arrangement you want; position IDs
 
1193
are always displayed when the board is shown.  (If you are playing
 
1194
on a text terminal, the position ID is in the upper right hand corner
 
1195
of the board diagram; when using the board window, the ID is shown
 
1196
below the board on the right hand side.)  For instance, to set the
 
1197
chequers to the starting position, use the command
 
1198
@code{set board 4HPwATDgc/ABMA}.
 
1199
 
 
1200
FIXME reference =n notation and describe the GTK edit mode
 
1201
 
 
1202
@kindex set matchid
 
1203
@item set matchid @var{id}
 
1204
The @code{set matchid} commands is a convienient way of settings the
 
1205
match length, match score, cube owner and value, player on roll
 
1206
etc. etc. For example, @code{set matchid QYk5ASAAIAAA} will start a new
 
1207
9 point match where the score is set to 2-4, player 0 owns a 2-cube, and
 
1208
player 1 has rolled 6-3 (@pxref{Detailed description of the match ID}
 
1209
for a detailed description).
 
1210
 
 
1211
The match ID is shown on the board, both in text mode and
 
1212
graphical mode.
 
1213
 
 
1214
 
 
1215
@kindex show board
 
1216
@item show board [@var{id}|=@var{number}]
 
1217
The @code{show board} command is used to display a particular position ---
 
1218
normally the board of the current game, but it is also possible to view
 
1219
unrelated layouts.  When specified without the optional @var{id} parameter,
 
1220
the current position is displayed.  (When using a text terminal, this
 
1221
is useful if subsequent output has caused the board diagram to scroll
 
1222
off the screen.  In the board window, the command can be used to undo
 
1223
erroneous chequer plays by resetting the window to the position at the
 
1224
start of the turn.)
 
1225
 
 
1226
When a position ID @var{id} is given, the chequers are arranged into
 
1227
the position specified and that board is displayed.  Note that this
 
1228
command affects the display only; the current game is unchanged.  Use
 
1229
the @code{show board} command with no parameter if you want to see
 
1230
the current game again.
 
1231
@kindex hint
 
1232
@item hint
 
1233
At any time during the game when the dice have been rolled, you can
 
1234
use the @code{hint} command to see the moves @gnubg{} recommends.
 
1235
The output is of the following form:
 
1236
 
 
1237
@example
 
1238
@group
 
1239
Win    W(g)   W(bg)  L(g)   L(bg)  Equity       Move
 
1240
0.542  0.142  0.008  0.113  0.008  (+0.114)     6/5 8/5 
 
1241
0.505  0.120  0.008  0.122  0.007  (+0.009)     24/23 23/20 
 
1242
0.498  0.126  0.008  0.123  0.007  (+0.000)     24/23 13/10 
 
1243
0.499  0.113  0.008  0.121  0.007  (-0.011)     24/23 24/21 
 
1244
0.486  0.125  0.008  0.120  0.009  (-0.024)     13/10 10/9 
 
1245
0.481  0.116  0.008  0.129  0.008  (-0.051)     6/5 24/21 
 
1246
0.472  0.122  0.008  0.129  0.009  (-0.064)     6/5 13/10 
 
1247
@end group
 
1248
@end example
 
1249
 
 
1250
The moves are listed in descending order of preference, so in this case,
 
1251
@gnubg{} recommends the move @samp{6/5 8/5}.  The first five columns are
 
1252
its estimates of the probability of the player on roll winning
 
1253
(@samp{Win}), winning a gammon (@samp{W(g)}), winning a backgammon
 
1254
(@samp{W(bg)}), losing a gammon (@samp{L(g)}), and losing a backgammon
 
1255
(@samp{L(bg)}) if the game is played to completion without use of the
 
1256
doubling cube, after the candidate move in that row is
 
1257
made@footnote{Note that the probability of winning includes the
 
1258
probability of winning a gammon or backgammon, and likewise the gammon
 
1259
probabilities include the backgammon probabilities.}.  The sixth column,
 
1260
@samp{Equity}, is the estimated cubeless equity following the move ---
 
1261
this is the expected number of points per game won by the player on
 
1262
roll.
 
1263
 
 
1264
FIXME describe =n notation.
 
1265
 
 
1266
@gnubg{} will `look ahead' a certain number of moves when evaluating
 
1267
the probabilities, according to the search depth set by the
 
1268
@code{set plies} command (@pxref{Analysis}).
 
1269
@kindex show pipcount
 
1270
@item show pipcount [@var{id}|=@var{number}]
 
1271
Use @code{show pipcount} to automatically count the number of `pips'
 
1272
each player needs to bear off.  Depending on the position, the output
 
1273
will look something like:
 
1274
 
 
1275
@example
 
1276
The pip counts are: X 103, O 112.
 
1277
@end example
 
1278
@kindex set player human
 
1279
@kindex set player name
 
1280
@kindex show player
 
1281
@itemx show player
 
1282
@item set player @var{name} human
 
1283
@itemx set player @var{old-name} name @var{new-name}
 
1284
Both players have a certain amount of configuration information; use the
 
1285
command @code{show player} to summarise these settings.  By default,
 
1286
@gnubg{} will play for player 0, whose name is initially @samp{gnubg}.
 
1287
Player 1 defaults to a human (i.e.@: @gnubg{} will prompt the user
 
1288
for a move when it is player 1's turn) whose name is the user's login
 
1289
name, on systems where this information is available; on single-user
 
1290
systems, the default name @samp{user} applies.
 
1291
 
 
1292
Either player can be set to a human with the command @code{set player
 
1293
@var{name} human}, where @var{name} is either the number of the player
 
1294
(0 or 1) or that player's name (initially @samp{gnubg} and @samp{user}
 
1295
or the user's login name).  You can also specify @code{both} which will
 
1296
set both players simultaneously.  There are also options for computer
 
1297
players (@pxref{Computer Player}).
 
1298
 
 
1299
You can change the names of the players with the
 
1300
@code{set player @var{old-name} name @var{new-name}} command.  Again,
 
1301
either the player numbers or names are valid for the @var{old-name}
 
1302
parameter.  Names may not contain whitespace characters, and may not
 
1303
be longer than 31 characters.  The names @samp{0}, @samp{1} and
 
1304
@samp{both} are not permitted, to avoid ambiguities, and the players
 
1305
may not both share the same name.  Names are not case sensitive.
 
1306
@kindex set turn
 
1307
@kindex show turn
 
1308
@item set turn @var{player}
 
1309
@itemx show turn
 
1310
The command @code{set turn @var{player}} (where @var{player} can be the
 
1311
player's name or number, as above) is used to control which player is on
 
1312
roll.  It will cancel the current dice roll and cube action (if any),
 
1313
and set the named player on roll.
 
1314
@kindex set automatic bearoff
 
1315
@kindex set automatic move
 
1316
@item set automatic bearoff
 
1317
@itemx set automatic move
 
1318
FIXME
 
1319
@kindex set display
 
1320
@item set display @var{value}
 
1321
By default, @gnubg{} will update the display before and after every move,
 
1322
whether made by a human or automatically.  (When using the graphical board,
 
1323
the board window is redrawn to the current position; when using the ASCII
 
1324
board, a new diagram is displayed on the terminal.)  Information about
 
1325
cube actions and resignations offered will also appear as appropriate.
 
1326
 
 
1327
The command @code{set display off} will suppress this output, which can
 
1328
speed up the display and reduce clutter (this might be useful when completing
 
1329
a game where both sides are played by the computer, for instance).
 
1330
@code{set display on} will restore the default behaviour.  The standard
 
1331
toggle synonyms may be substituted for @code{on} and @code{off}.
 
1332
 
 
1333
The board will always be updated when it is a human player's turn to move,
 
1334
regardless of the @code{display} setting.
 
1335
@end table
 
1336
 
 
1337
@node Dice
 
1338
@section Controlling Dice Rolls
 
1339
@cindex dice
 
1340
@cindex rolls, dice
 
1341
 
 
1342
@table @code
 
1343
@kindex roll
 
1344
@item roll
 
1345
This is the basic command used to roll the dice before each turn.  It will
 
1346
use the current random number generator to produce a dice roll, and then
 
1347
allow the player to move (if there is at least one legal play for the
 
1348
dice rolled).  By rolling the dice, the player gives up any opportunity
 
1349
to double this turn.
 
1350
@kindex set automatic roll
 
1351
@itemx set automatic roll @var{value}
 
1352
When the cube is not being used, or is owned by the opponent, or at
 
1353
certain scores in a match, it is either illegal or pointless for a
 
1354
player to double.  Under these circumstances, the player might as well
 
1355
roll the dice immediately --- the @code{set automatic roll} command
 
1356
instructs @gnubg{} to go ahead and roll the dice without waiting for the
 
1357
player to issue @code{roll}, whenever no doubling decision is necessary.
 
1358
The standard toggle commands may be used to turn this option on and off.
 
1359
@kindex set dice
 
1360
@itemx set dice @var{pips} @var{pips}
 
1361
To set the dice to a particular roll (whether they have already been rolled
 
1362
or not), use the @code{set dice} command.  The player can then play a move
 
1363
according to the dice specified.  Like the @code{roll} command, this will
 
1364
also forego any opportunity to double; to disregard a dice roll and
 
1365
allow the player to roll again (or double, if permitted), use @code{set
 
1366
turn @var{player}}.
 
1367
@kindex set rng
 
1368
@kindex show rng
 
1369
@item set rng @var{generator} [@var{seed}]
 
1370
@itemx show rng
 
1371
@gnubg{} allows a variety of methods for generating dice rolls, including
 
1372
several built-in pseudo-random number generators and a facility for external
 
1373
libraries to be used.  It is also possible to enter a roll manually whenever
 
1374
required.
 
1375
 
 
1376
The @code{set rng} command is used to select which generator will be used.
 
1377
The @var{generator} parameter must be one of the following:
 
1378
@table @code
 
1379
@item ansi
 
1380
The ANSI C standard @code{rand()} random number generator.  The
 
1381
behaviour of this generator will depend on the C library linked with
 
1382
@gnubg{}, but is typically a linear congruential pseudo-random number
 
1383
generator.  Such generators have fairly weak distribution properties,
 
1384
but are generally adequate for producing backgammon dice.  However, the
 
1385
ANSI generator is not recommended for performing rollouts, because any
 
1386
small biases in the dice could accumulate over hundreds or thousands of
 
1387
trials and distort the results.  Using a better generator would be
 
1388
safer for rollouts.
 
1389
@item bsd
 
1390
The 4.3BSD @code{random()} non-linear additive feedback random number
 
1391
generator.  This is a good quality generator, but is not available on
 
1392
all systems.  @gnubg{} will report an error if you attempt to use this
 
1393
generator if the C library used in your installation does not include
 
1394
the BSD @code{random} code.
 
1395
@item isaac
 
1396
Bob Jenkins' ISAAC random number generator.  This is believed to be a
 
1397
high quality generator.
 
1398
@item manual
 
1399
By setting the generator to @code{manual}, @gnubg{} will not generate
 
1400
the dice itself; rather, it will prompt for a roll to be entered whenever
 
1401
one is required.
 
1402
@item md5
 
1403
MD5 is a public domain message digest algorithm invented by Ron
 
1404
Rivest and documented in RFC 1321.  @gnubg{} can use MD5 as a procedure
 
1405
for generating dice rolls --- this generator has the property that
 
1406
the seed increments by one each roll, and so the sequence generated
 
1407
by seed @samp{n+1} will be identical to that generated by seed @samp{n},
 
1408
with the first roll omitted.  The command @code{show seed} is available
 
1409
when using the @var{md5} generator, for obtaining the current seed value.
 
1410
@item mersenne
 
1411
Choosing this option will enable the Mersenne Twister generator designed
 
1412
by Matsumoto and Nishimura.  This should be an excellent pseudo-random
 
1413
number generator.
 
1414
@item user
 
1415
Use the @code{user} generator to dynamically load a user library which
 
1416
will be used to produce the dice rolls.  See the file @file{userrng.c}
 
1417
in the @gnubg{} distribution for an example user generator, and instructions
 
1418
on how to write your own.
 
1419
@end table
 
1420
FIXME explain optional seed parameter
 
1421
@kindex set seed
 
1422
@item set seed @var{seed}
 
1423
You can change the random number generator seed at any time with the
 
1424
@code{set seed} command.  FIXME
 
1425
@kindex show seed
 
1426
@item show seed
 
1427
FIXME
 
1428
@end table
 
1429
 
 
1430
@node Computer Player
 
1431
@section Having @gnubg{} Make Moves
 
1432
@cindex computer player
 
1433
@cindex @t{gnubg}, making moves
 
1434
 
 
1435
@table @code
 
1436
@kindex set player gnubg
 
1437
@item set player @var{name} gnubg
 
1438
This command will instruct @gnubg{} to choose moves (and make cube decisions)
 
1439
for the specified player, using its evaluation engine.
 
1440
@kindex set player pubeval
 
1441
@item set player @var{name} pubeval
 
1442
An alternative computer player can be chosen by setting a player to
 
1443
@code{pubeval}.  This will cause moves for that player to be made by
 
1444
Gerry Tesauro's benchmark player.  @code{pubeval} is much weaker than
 
1445
@gnubg{}'s own evaluator, but provides a constant level of play which
 
1446
is useful for measuring different players against.
 
1447
 
 
1448
@code{pubeval} is not capable of making cube or resignation decisions
 
1449
based on the position.  It will never accept resignations at less than
 
1450
triple (backgammon) stakes, and will take all cubes.  It nevers offers
 
1451
resignations or doubles of its own.
 
1452
@kindex set player external
 
1453
@item set player @var{name} external
 
1454
FIXME
 
1455
@kindex set player evaluation
 
1456
@item set player @var{name} evaluation
 
1457
FIXME
 
1458
@kindex play
 
1459
@item play
 
1460
FIXME
 
1461
@kindex external
 
1462
@item external
 
1463
FIXME
 
1464
@end table
 
1465
 
 
1466
@node Matches and Sessions
 
1467
@section Matches and Sessions
 
1468
@cindex matches
 
1469
@cindex sessions
 
1470
 
 
1471
This section describes how to use GNU Backgammon to play series of
 
1472
games, whether those games are part of a match (as in tournament
 
1473
backgammon) or a session of independent games (conventionally
 
1474
called ``money'' play, regardless of whether any payment is involved).
 
1475
 
 
1476
@table @code
 
1477
@kindex new match
 
1478
@kindex new session
 
1479
@kindex set automatic game
 
1480
@kindex set crawford
 
1481
@kindex set postcrawford
 
1482
@kindex set automatic crawford
 
1483
@kindex set jacoby
 
1484
@kindex set automatic doubles
 
1485
@kindex set score
 
1486
@kindex show crawford
 
1487
@kindex show postcrawford
 
1488
@kindex show jacoby
 
1489
@kindex show score
 
1490
@item new match @var{length}
 
1491
@itemx new session
 
1492
@itemx set automatic game
 
1493
@itemx set crawford
 
1494
@itemx set postcrawford
 
1495
@itemx set automatic crawford
 
1496
@itemx set jacoby
 
1497
@itemx set automatic doubles @var{limit}
 
1498
@itemx set score @var{points} @var{points}
 
1499
@itemx show crawford
 
1500
@itemx show postcrawford
 
1501
@itemx show jacoby
 
1502
@itemx show score
 
1503
FIXME
 
1504
@end table
 
1505
 
 
1506
@node Cube
 
1507
@section The Doubling Cube
 
1508
@cindex cube, doubling
 
1509
@cindex doubling, commands
 
1510
 
 
1511
@table @code
 
1512
@kindex double
 
1513
@kindex redouble
 
1514
@kindex beaver
 
1515
@kindex take
 
1516
@kindex accept
 
1517
@kindex drop
 
1518
@kindex pass
 
1519
@kindex reject
 
1520
@kindex set cube centre
 
1521
@kindex set cube owner
 
1522
@kindex set cube use
 
1523
@kindex set cube value
 
1524
@item double
 
1525
@itemx redouble
 
1526
@itemx beaver
 
1527
@itemx take
 
1528
@itemx accept
 
1529
@itemx drop
 
1530
@itemx pass
 
1531
@itemx reject
 
1532
@itemx set cube centre
 
1533
@itemx set cube owner @var{player}
 
1534
@itemx set cube use
 
1535
@itemx set cube value @var{points}
 
1536
FIXME
 
1537
@end table
 
1538
 
 
1539
@node Recording
 
1540
@section Saving Games and Matches
 
1541
@cindex recording matches
 
1542
@cindex saving matches
 
1543
@cindex matches, saving
 
1544
@cindex games, saving
 
1545
 
 
1546
@table @code
 
1547
@kindex save game
 
1548
@kindex save match
 
1549
@kindex load game
 
1550
@kindex load match
 
1551
@item save game @var{file}
 
1552
@itemx save match @var{file}
 
1553
@itemx load game @var{file}
 
1554
@itemx load match @var{file}
 
1555
FIXME
 
1556
@end table
 
1557
 
 
1558
@node GTK
 
1559
@chapter The Graphical Interface to @gnubg{}
 
1560
@cindex graphical interface
 
1561
@cindex GTK+
 
1562
 
 
1563
@table @code
 
1564
@kindex set colours
 
1565
@kindex set delay
 
1566
@kindex show delay
 
1567
@item set colours
 
1568
@itemx set delay
 
1569
@itemx show delay
 
1570
FIXME
 
1571
@end table
 
1572
 
 
1573
@node Analysis
 
1574
@chapter Using @gnubg{} to Analyse Positions
 
1575
@cindex analysis of positions
 
1576
@cindex position analysis
 
1577
 
 
1578
@table @code
 
1579
@kindex eval
 
1580
@kindex rollout
 
1581
@kindex set evaluation
 
1582
@kindex set rollout
 
1583
@kindex set cache
 
1584
@kindex show cache
 
1585
@kindex show gammonprice
 
1586
@kindex show marketwindow
 
1587
@kindex show matchequitytable
 
1588
@kindex analysis
 
1589
@item eval [@var{id}|=@var{number}]
 
1590
@itemx rollout [@var{id}|=@var{number} @dots{}]
 
1591
@itemx set evaluation
 
1592
@itemx set rollout
 
1593
@itemx set cache @var{size}
 
1594
@itemx show cache
 
1595
@itemx show gammonprice
 
1596
@itemx show marketwindow
 
1597
@itemx show matchequitytable
 
1598
@itemx analysis
 
1599
FIXME
 
1600
@end table
 
1601
 
 
1602
@node Databases
 
1603
@chapter Position Databases
 
1604
@cindex databases
 
1605
@cindex position databases
 
1606
 
 
1607
@table @code
 
1608
@kindex database dump
 
1609
@kindex database export
 
1610
@kindex export database
 
1611
@kindex database generate
 
1612
@kindex database import
 
1613
@kindex import database
 
1614
@kindex database rollout
 
1615
@kindex database train
 
1616
@item database dump
 
1617
@itemx database export
 
1618
@itemx export database
 
1619
@itemx database generate
 
1620
@itemx database import
 
1621
@itemx import database
 
1622
@itemx database rollout
 
1623
FIXME
 
1624
@item database train
 
1625
@itemx train database
 
1626
FIXME pointer only
 
1627
@end table
 
1628
 
 
1629
@node Training
 
1630
@chapter Modifying @gnubg{}'s Neural Nets
 
1631
@cindex training
 
1632
@cindex neural nets, training
 
1633
 
 
1634
@table @code
 
1635
@kindex new weights
 
1636
@kindex save weights
 
1637
@kindex load weights
 
1638
@kindex database train
 
1639
@kindex train database
 
1640
@kindex train td
 
1641
@item new weights
 
1642
@item save weights @var{file}
 
1643
@itemx load weights @var{file}
 
1644
@itemx database train
 
1645
@itemx train database
 
1646
@itemx train td
 
1647
FIXME
 
1648
@end table
 
1649
 
 
1650
@image{annealing}
 
1651
 
 
1652
@node Guile
 
1653
@chapter Extending @gnubg{}
 
1654
@cindex extending @t{gnubg}
 
1655
@cindex Guile
 
1656
@cindex Scheme
 
1657
 
 
1658
@table @code
 
1659
@kindex :
 
1660
@item :
 
1661
FIXME
 
1662
@end table
 
1663
 
 
1664
@include faq.texi
 
1665
 
 
1666
@c This is the old FAQ chapter:
 
1667
@ignore
 
1668
@node Frequently Asked Questions
 
1669
@chapter Frequently Asked Questions
 
1670
@cindex frequently asked questions
 
1671
@cindex FAQ
 
1672
 
 
1673
@menu
 
1674
* Where can I get GNU Backgammon?::  
 
1675
* How do I play a game?::       
 
1676
* gnubg.bd errors::             
 
1677
* gnubg.weights errors::        
 
1678
* Black and white board window::  
 
1679
@end menu
 
1680
 
 
1681
@node Where can I get GNU Backgammon?
 
1682
@section Where can I get GNU Backgammon?
 
1683
@cindex obtaining @t{gnubg}
 
1684
 
 
1685
Pre-release snapshots of GNU Backgammon are periodically made available
 
1686
for FTP at @uref{ftp://alpha.gnu.org/gnu/gnubg/}.
 
1687
 
 
1688
If you want to experiment with the very latest code, the development
 
1689
sources are kept in a CVS repository at
 
1690
@uref{http://subversions.gnu.org/cgi-bin/cvsweb/gnubg/}; see the @gnubg{}
 
1691
web page at @uref{http://www.gnu.org/software/gnubg/gnubg.html} for
 
1692
instructions on checking out sources from the repository.  Daily snapshots of
 
1693
the main branch of the repository are automatically placed in the
 
1694
@file{snapshots} directory of the FTP area above, if you wish to retrieve
 
1695
this experimental code via FTP.
 
1696
 
 
1697
@node How do I play a game?
 
1698
@section How do I play a game?
 
1699
@cindex playing a game
 
1700
@cindex moving chequers, commands
 
1701
 
 
1702
Once you are running @gnubg{}, enter @kbd{new game} at the
 
1703
@samp{(gnubg)} prompt to start a game against the computer opponent.
 
1704
You should now see a board (if a window system is available, @gnubg{}
 
1705
will use a graphical board window; otherwise, it will display an ASCII
 
1706
board on your terminal).  If @gnubg{} won the opening roll, it will have
 
1707
moved; you can now type @kbd{roll} (or click on the dice below the board
 
1708
window) to roll the dice yourself.  In either case, it will now be your
 
1709
move; you should enter the moves for each chequer as pairs of numbers.
 
1710
For instance, if you have rolled 3 and 1, you could type @kbd{8 5 6 5}
 
1711
to move one chequer from the 8 point to the 5 point and another from the
 
1712
6 point to the 5 point.  Use @kbd{bar} to move from the bar, and
 
1713
@kbd{off} to bear off.  If you are using the board window, you can also
 
1714
drag chequers around the board.  Click on the dice when you have
 
1715
finished.
 
1716
 
 
1717
@node gnubg.bd errors
 
1718
@section I only see @samp{gnubg.bd: No such file or directory}.  What's wrong?
 
1719
@vindex gnubg.bd
 
1720
@cindex errors starting @t{gnubg}
 
1721
 
 
1722
The file @file{gnubg.bd} is the bearoff database that @gnubg{} uses to
 
1723
evaluate endgame positions.  @gnubg{} will look for it first in the current
 
1724
directory and then in the installed directory (@file{/usr/local/share/gnubg/}
 
1725
by default).
 
1726
 
 
1727
The @gnubg{} distribution is set up to create @file{gnubg.bd} by itself
 
1728
during compilation, but it can be a slow process (taking half an hour
 
1729
or more, depending on the speed of your computer).  If you would rather
 
1730
not wait to generate the database yourself, you can obtain a copy
 
1731
via FTP from @uref{ftp://alpha.gnu.org/gnu/gnubg/gnubg.bd.gz}.
 
1732
 
 
1733
FIXME this is out of date; gnubg can cope without gnubg.bd if it has to.
 
1734
 
 
1735
@node gnubg.weights errors
 
1736
@section Now I get @samp{gnubg.weights: No such file or directory}.  What's that?
 
1737
@vindex gnubg.weights
 
1738
@cindex errors starting @t{gnubg}
 
1739
 
 
1740
The file @file{gnubg.weights} contains the trained neural net weights
 
1741
for most of @gnubg{}'s position evaluators.  Like @file{gnubg.bd}, it should
 
1742
be kept in either the current directory or the installed directory.
 
1743
 
 
1744
A binary variant of the weights file named @file{gnubg.wd} can also be
 
1745
used (this version can be loaded more quickly, but is not portable
 
1746
between different computer architectures).  It will automatically be
 
1747
built during the compilation process, and used in preference to
 
1748
@file{gnubg.weights} if found.
 
1749
 
 
1750
You should be able to obtain a copy of the weights from wherever you
 
1751
found the @gnubg{} distribution.  If you wish to start @gnubg{} without
 
1752
any weights (and train your own), you can use the @option{--no-weights}
 
1753
option (see @pxref{Invoking gnubg}).
 
1754
 
 
1755
@node Black and white board window
 
1756
@section The board window is shown in black and white and looks awful!  What's wrong?
 
1757
 
 
1758
If you see this problem, your X server is probably using a
 
1759
@dfn{PseudoColor} visual, and is dynamically allocating colours
 
1760
to clients from a limited colourmap.  On these types of displays, 
 
1761
@gnubg{} tries to be a well-behaved client by using colours from the
 
1762
default standard colourmap.  This will allow it to share colours
 
1763
with other clients that use the same scheme, which will help them
 
1764
all to use as many colours as possible without exhausting the
 
1765
colourmap.
 
1766
 
 
1767
Unfortunately, not all X clients use standard colourmaps.  If other
 
1768
clients have been run before @gnubg{} and allocated most of the colours,
 
1769
then there may not be enough left for @gnubg{} to allocate a standard
 
1770
colourmap.  If this happens, it will just take what it can get (which
 
1771
in the worst case might be black and white only).  You can try to
 
1772
avoid this problem by running @gnubg{} before other colour-hungry clients,
 
1773
or by using the @file{xstdcmap} utility to install the default
 
1774
standard colourmap early in your session while colours are still
 
1775
available.  Depending on your hardware, you may be able to configure
 
1776
your display to allow more colours, or use a @dfn{DirectColor} or
 
1777
@dfn{TrueColor} visual which should resolve the problem.
 
1778
 
 
1779
Of course, if your X server can only display black and white (not even
 
1780
shades of grey), then there's not much you can do!
 
1781
 
 
1782
@node Are the dice fair?
 
1783
 
 
1784
@end ignore
 
1785
 
 
1786
@include fdl.texi
 
1787
 
 
1788
@node Appendices
 
1789
@chapter Appendices
 
1790
@cindex appendix
 
1791
 
 
1792
@menu
 
1793
* Detailed description of the position ID::
 
1794
* Detailed description of the match ID::
 
1795
@end menu
 
1796
 
 
1797
@node Detailed description of the position ID
 
1798
@section Detailed description of the position ID
 
1799
@cindex position ID
 
1800
 
 
1801
[insert the contents of
 
1802
http://www.cs.arizona.edu/~gary/backgammon/positionid.html here]
 
1803
 
 
1804
@node Detailed description of the match ID
 
1805
@section Detailed description of the match ID
 
1806
@cindex match ID
 
1807
 
 
1808
@subsection Introduction
 
1809
 
 
1810
This section describes how the match ID is calculated. The match ID  can
 
1811
be used for easy exchange of positions for @gnubg{} users in
 
1812
conjuction with the position ID. The match key is a 9 byte
 
1813
representation of the match score, match length, value of cube, owner of
 
1814
cube, Crawford game flag, player on roll, player to make a decision,
 
1815
doubled flag, resigned flag, and the dice rolled. The match ID is the 12
 
1816
character Base64 encoding of the match key.
 
1817
 
 
1818
@subsection Match key
 
1819
 
 
1820
The match key is a bit string of length 66:
 
1821
 
 
1822
@enumerate
 
1823
@item
 
1824
Bit 1-4 contains the 2-logarithm of the cube value. For example, a
 
1825
8-cube is encoded as 0011 binary (or 3), since 2 to the power of 3 is
 
1826
8. The maximum value of the cube in with this encoding is 2 to the power
 
1827
of 15, i.e., a 32768-cube.
 
1828
 
 
1829
@item
 
1830
Bit 5-6 contains the cube owner. 00 if player 0 owns the cube, 01 if
 
1831
player 1 owns the cube, or 11 for a centered cube.
 
1832
 
 
1833
@item
 
1834
Bit 7 is the player on roll or the player who did roll (0 and 1 for
 
1835
player 0 and 1, respectively).  
 
1836
 
 
1837
@item
 
1838
Bit 8 is the Crawford flag: 1 if this game is the Crawford game, 0
 
1839
otherwise.
 
1840
 
 
1841
@item
 
1842
Bit 9-11 is the game state: 000 for no game started, 001 for playing a game,
 
1843
010 if the game is over, 011 if the game was resigned, or 100 if the
 
1844
game was ended by dropping a cube.
 
1845
 
 
1846
@item
 
1847
Bit 12 indicates whose turn it is. For example, suppose player 0 is on
 
1848
roll then bit 7 above will be 0. Player 0 now decides to double, this
 
1849
will make bit 12 equal to 1, since it is now player 1's turn to decide
 
1850
whether she takes or passes the cube.
 
1851
 
 
1852
@item
 
1853
Bit 13 indicates whether an doubled is being offered. 0 if no double is
 
1854
being offered and 1 if a double is being offered.
 
1855
 
 
1856
@item
 
1857
Bit 14-15 indicates whether an resignation was offered. 00 for no
 
1858
resignation, 01 for resign of a sigle game, 10 for resign of a gammon,
 
1859
or 11 for resign of a backgammon. The player offering the resignation is
 
1860
the inverse of bit 12, e.g., if player 0 resigns a gammon then bit 12
 
1861
will be 1 (as it is now player 1 now has to decide whether to accept or
 
1862
reject the resignation) and bit 13-14 will be 10 for resign of a gammon.
 
1863
 
 
1864
@item
 
1865
Bit 16-18 and bit 19-21 is the first and second die, respectively. 0 if
 
1866
the dice has not yet be rolled, otherwise the binary encoding of the
 
1867
dice, e.g., if 5-2 was rolled bit 16-21 will be 101-010.
 
1868
 
 
1869
@item
 
1870
Bit 22 to 36 is the match length. The maximum value for the match length
 
1871
is 32767. A matchscore of zero indicates that the game is a money game.
 
1872
 
 
1873
@item
 
1874
Bit 37-51 and bit 52-66 is the score for player 0 and player 1
 
1875
respectively. The maximum value of the match score is 32767.
 
1876
 
 
1877
@end enumerate
 
1878
 
 
1879
For example, assume the score is 2-4 in a 9 point match with player 0
 
1880
holding a 2-cube, and player 1 has just rolled 52. The match key for
 
1881
this will be (note that the bit order is reversed below for readability)
 
1882
 
 
1883
1000 00 1 0  100 1 0 00 101 010 100100000000000 010000000000000 001000000000000            
 
1884
 
 
1885
 
 
1886
In little endian the bytes looks like:
 
1887
 
 
1888
01000001 10001001 00101010 00000001 00100000 00000000 00100000 00000000 00
 
1889
 
 
1890
0x41     0x89     0x2A     0x01     0x20     0x00     0x20     0x00     0x00
 
1891
 
 
1892
@subsection Match ID
 
1893
 
 
1894
Analogous to the position ID from the previous section the match ID
 
1895
format is simply the Base64 encoding of the key. 
 
1896
 
 
1897
To continue the example above, the 9 8-bit bytes are grouped into 12
 
1898
6-bits groups:
 
1899
 
 
1900
 
 
1901
010000 011000 100100 101010 000000 010010 000000 000000 001000 000000
 
1902
000000 000000
 
1903
 
 
1904
In Base64 encoding, the groups are represented as:
 
1905
 
 
1906
Q Y k q A U A A I A A A
 
1907
 
 
1908
So, the match id is simply:
 
1909
 
 
1910
QYkqAUAAIAAA
 
1911
 
 
1912
@node Command Index
 
1913
@unnumbered Command Index
 
1914
@printindex ky
 
1915
 
 
1916
@node Concept Index
 
1917
@unnumbered Index
 
1918
@printindex cp
 
1919
 
 
1920
@contents
 
1921
@bye