1 This is chess.info, produced by makeinfo version 5.2 from chess.texi.
5 * Chess: (chess). Chess.el is an Emacs chess client.
8 Copyright © 2001, 2002, 2014 Free Software Foundation, Inc.
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation.
15 File: chess.info, Node: Top, Next: The chess.el library, Prev: (dir), Up: (dir)
20 Chess.el is an Emacs chess client and library, designed to be used for
21 writing chess-related programs, or for playing games of chess against
22 various chess engines, including Internet servers. The library can be
23 used for analyzing variations, browsing historical games, or a multitude
26 The purpose of this manual is to help you understand how Chess.el is
27 structured for use as a library, and also how to use it as a client.
31 * The chess.el library:: Basic objects required to deal with Chess
32 * Modules:: The module-system explained
33 * Chessboard displays:: Different types of chessboards in a buffer
34 * Engines:: Internal and external chess-playing engines
35 * Chess Session:: Tying it all together
36 * Internet Chess Servers:: Playing chess with other people
38 * Function and Variable Index::
42 File: chess.info, Node: The chess.el library, Next: Modules, Prev: Top, Up: Top
44 1 The chess.el library
45 **********************
47 This chapter documents the low-level aspects of chess.el, mostly
48 targeting developers interested in understanding the underlying APIs.
50 *note Chessboard displays:: and following chapters if you are
51 interested in the more user-visible aspects of chess.el.
60 * Chess Opening Books::
63 File: chess.info, Node: Positions, Next: Plies, Prev: The chess.el library, Up: The chess.el library
68 A chess "position" is a given layout of pieces on a chess board, also
69 reflecting which side is next to move, and what privileges are currently
70 available to each side (castling short or long, en passant capture,
73 A position may be represented in ASCII using FEN (or EPD), or
74 graphically by displaying a chess board. It is rather inconvenient to
77 The position can be represented on a remote terminal using X windows,
78 or by transmitting the FEN string via a network connection, or
79 clipboard, to another chess board rendering tool. It may of course also
80 be represented physically, by setting up the pieces to match the FEN
83 Chess puzzles are most often provided as a set of positions.
87 * Creating positions::
88 * Position coordinates::
95 File: chess.info, Node: Creating positions, Next: Position coordinates, Prev: Positions, Up: Positions
97 1.1.1 Creating positions
98 ------------------------
100 -- Function: chess-pos-create &optional blank
101 Create a new chess position, set at the starting position. If
102 BLANK is non-nil, all of the squares will be empty. The current
103 side-to-move is always white.
105 -- Function: chess-pos-copy position
106 Copy the given chess POSITION. If there are annotations or EPD
107 opcodes set, these lists are copied as well, so that the two
108 positions do not share the same lists.
110 -- Variable: chess-starting-position
111 Starting position of a chess game.
113 -- Function: chess-fischer-random-position
114 Generate a Fischer Random style position.
117 File: chess.info, Node: Position coordinates, Next: Position details, Prev: Creating positions, Up: Positions
119 1.1.2 Position coordinates
120 --------------------------
122 First of all, a coordinate system of octal indices is used, where ?\044
123 signifies rank 4 file 4 (i.e., "e4"). Rank is numbered 0 to 7, top to
124 bottom, and file is 0 to 7, left to right.
126 -- Function: chess-index-rank index
127 Return the rank component of the given INDEX.
129 -- Function: chess-index-file index
130 Return the file component of the given INDEX.
132 -- Function: chess-rf-to-index rank file
133 Convert RANK and FILE coordinates into an octal index.
135 For those who wish to use ASCII coordinates, such as "e4", there are
136 two conversion functions:
138 -- Function: chess-coord-to-index coord
139 Convert a COORD string into an index value.
141 -- Function: chess-index-to-coord index
142 Convert the chess position INDEX into a coord string.
144 For fast manipulation of chess position indices, the following
145 constants and functions are provided:
147 For queens and rooks:
149 -- Constant: chess-direction-north
150 Signify one step north, as seen from the perspective of the white
153 -- Constant: chess-direction-east
154 Signify one step east, as seen from the perspective of the white
157 -- Constant: chess-direction-south
158 Signify one step south, as seen from the perspective of the white
161 -- Constant: chess-direction-west
162 Signify one step west, as seen from the perspective of the white
165 For queens and bishops:
167 -- Constant: chess-direction-northeast
168 Signify one step northeast, as seen from the perspective of the
171 -- Constant: chess-direction-southeast
172 Signify one step southeast, as seen from the perspective of the
175 -- Constant: chess-direction-southwest
176 Signify one step southwest, as seen from the perspective of the
179 -- Constant: chess-direction-northwest
180 Signify one step northwest, as seen from the perspective of the
183 -- Function: chess-next-index index direction
184 Create a new INDEX from an old one, by advancing it into DIRECTION.
185 If the resulting index is not valid (outside the board), nil is
188 Due to the underlying technique used to efficiently detect off-board
189 squares, a direction specifier should at most do two steps in any
190 direction. Directions can be combined, so that ‘(*
191 chess-direction-north 2)’ will give a typical initial white pawn push.
194 File: chess.info, Node: Position details, Next: Annotations, Prev: Position coordinates, Up: Positions
196 1.1.3 Position details
197 ----------------------
199 With an octal index value, you can look up what’s on a particular
200 square, or set that square’s value:
202 -- Function: chess-pos-piece position index
203 Return the piece on POSITION at INDEX.
205 -- Function: chess-pos-piece-p position index piece-or-color
206 Return non-nil if at POSITION/INDEX there is the given
207 PIECE-OR-COLOR. If PIECE-OR-COLOR is t for white or nil for black,
208 any piece of that color will do.
210 -- Function: chess-pos-set-piece position index piece
211 Set the piece on POSITION at INDEX to PIECE. PIECE must be one of
212 ‘?K’ ‘?Q’ ‘?N’ ‘?B’ ‘?R’ or ‘?P’. Use lowercase to set black
215 -- Function: chess-pos-search position piece-or-color
216 Look on POSITION anywhere for PIECE-OR-COLOR, returning all
217 coordinates. If PIECE-OR-COLOR is t for white or nil for black,
218 any piece of that color will do.
220 -- Function: chess-pos-search* position &rest pieces
221 Look on POSITION for any of PIECES.
223 The result is an alist where each element looks like (PIECE .
224 INDICES). Pieces which did not appear in POSITION will be present
225 in the resulting alist, but the ‘cdr’ of their entries will be nil.
227 -- Function: chess-search-position position target piece &optional
228 check-only no-castling
229 Look on POSITION from TARGET for a PIECE that can move there. This
230 routine looks along legal paths of movement for PIECE. It differs
231 from ‘chess-pos-search’, which is a more basic function that
232 doesn’t take piece movement into account.
234 If PIECE is t or nil, legal piece movements for any piece of that
235 color will be considered (t for white, nil for black). Otherwise,
236 the case of the PIECE determines color.
238 The return value is a list of candidates, which means a list of
239 indices which indicate where a piece may have moved from.
241 If CHECK-ONLY is non-nil and PIECE is either t or nil, only
242 consider pieces which can give check (not the opponents king). If
243 NO-CASTLING is non-nil, do not consider castling moves.
245 -- Function: chess-pos-can-castle position side
246 Return whether the king on POSITION can castle on SIDE. SIDE must
247 be either ?K for the king side, or ?Q for the queen side (use
248 lowercase to query if black can castle).
250 -- Function: chess-pos-set-can-castle position side value
251 Set whether the king can castle on the given POSITION on SIDE.
253 See ‘chess-pos-can-castle’.
255 It is only necessary to call this function if setting up a position
256 manually. Note that all newly created positions have full castling
257 privileges set, unless the position is created blank, in which case
258 castling privileges are unset. See ‘chess-pos-copy’.
260 -- Function: chess-pos-en-passant position
261 Return the index of any pawn on POSITION that can be captured en
262 passant. Returns nil if en passant is unavailable.
264 -- Function: chess-pos-set-en-passant position index
265 Set the index of any pawn on POSITION that can be captured en
268 -- Function: chess-pos-status position
269 Return whether the side to move in the POSITION is in a special
270 state. nil is returned if not, otherwise one of the symbols:
271 ‘check’, ‘checkmate’, ‘stalemate’.
273 -- Function: chess-pos-set-status position value
274 Set whether the side to move in POSITION is in a special state.
275 VALUE should either be nil, to indicate that the POSITION is
276 normal, or one of the symbols: ‘check’, ‘checkmate’, ‘stalemate’.
278 -- Function: chess-pos-side-to-move position
279 Return the color whose move it is in POSITION.
281 -- Function: chess-pos-set-side-to-move position color
282 Set the color whose move it is in POSITION.
284 -- Function: chess-pos-passed-pawns position color &optional
286 If COLOR has Passed Pawns in POSITION, return a list of their
287 indices. Optionally, if INDICES is non-nil those indices are
288 considered as candidates.
290 A Pawn whose advance to the eighth rank is not blocked by an
291 opposing Pawn in the same file and who does not have to pass one on
292 an adjoining file is called a passed Pawn.
294 -- Variable: chess-pos-always-white
295 When set, it is assumed that white is always on move. This is
296 really only useful when setting up training positions. This
297 variable automatically becomes buffer-local when changed.
299 -- Function: chess-pos-move position &rest changes
300 Move a piece on the POSITION directly, using the indices in
301 CHANGES. This function does not check any rules, it only makes
302 sure you are not trying to move a blank square.
305 File: chess.info, Node: Annotations, Next: FEN notation, Prev: Position details, Up: Positions
310 -- Function: chess-pos-annotations position
311 Return the list of annotations for this position.
313 -- Function: chess-pos-add-annotation position annotation
314 Add an annotation for this position.
317 File: chess.info, Node: FEN notation, Next: EPD notation, Prev: Annotations, Up: Positions
322 "FEN (Forsyth-Edwards Notation)" encodes a chess position using a simple
323 string. The format is:
325 POSITION SIDE CASTLING EN-PASSANT
327 The POSITION gives all eight ranks, by specifying a letter for each
328 piece on the position, and a number for any intervening spaces, ranks
329 separated by slashes. Trailing spaces need not be counted. Uppercase
330 letters signify white, and lowercase black. For example, if your
331 position only had a black king on d8, your POSITION string would be:
335 For the three spaces (a, b and c file), the black king, and then all
336 the remaining ranks (which are all empty, so their spaces can be
339 The SIDE is ‘w’ or ‘b’, to indicate whose move it is.
341 CASTLING can contain ‘K’, ‘Q’, ‘k’ or ‘q’, to signify whether the
342 white or black king can still castle on the king or queen side. If
343 neither colour can castle on any side, ‘-’ should be provided.
345 EN-PASSANT signifies the target square of an en passant capture, such
348 -- Function: chess-fen-to-pos fen
349 Convert a FEN-like string to a chess position.
351 -- Function: chess-pos-to-fen position &optional full
352 Convert a chess POSITION to a FEN string. If FULL is non-nil,
353 represent trailing spaces as well.
355 This is how the starting position looks like:
357 (chess-pos-to-fen chess-starting-position)
358 ⇒ "rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR w KQkq -"
360 Some external programs might have problems parsing terse FEN strings.
361 If you are unsure, use the more verbose form:
363 (chess-pos-to-fen chess-starting-position t)
364 ⇒ "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"
367 File: chess.info, Node: EPD notation, Prev: FEN notation, Up: Positions
372 "EPD (Extended Position Description)" is a standard for describing chess
373 positions along with an extended set of structured attribute values
374 using the ASCII character set. It is intended for data and command
375 interchange among chess-playing programs. It is also intended for the
376 representation of portable opening library repositories.
378 A single EPD uses one text line of variable length composed of four
379 data field followed by zero or more operations. The four fields of the
380 EPD specification are the same as the first four fields of the FEN
383 A text file composed exclusively of EPD data records should have a
384 file name with the suffix ‘.epd’.
386 -- Function: chess-epd-to-pos &optional string
387 Convert extended position description STRING to a chess position.
388 If STRING is not specified, look for an epd string in the current
389 buffer, and advance point after the correctly parsed position.
391 -- Function: chess-pos-to-epd position
392 Convert a chess POSITION to a string representation in extended
393 position description format.
395 -- Function: chess-epd-read-file file
396 Return a list of positions contained in FILE.
401 * Opcode "acd" analysis count depth::
402 * Opcode "acn" analysis count nodes::
403 * Opcode "acs" analysis count seconds::
404 * Opcode "am" avoid move(s)::
405 * Opcode "bm" best move(s)::
408 File: chess.info, Node: Operations, Next: Opcode "acd" analysis count depth, Prev: EPD notation, Up: EPD notation
413 An EPD operation is composed of an opcode followed by zero or more
414 operands and is concluded by a semicolon.
416 Multiple operations are separated by a single space character. If
417 there is at least one operation present in an EPD record, it is
418 separated from the last (fourth) data field by a single space character.
420 Some opcodes that allow for more than one operand may have special
421 ordering requirements for the operands. For example, the "pv"
422 (predicted variation) opcode requires its operands (moves) to appear in
423 the order in which they would be played. All other opcodes that allow
424 for more than one operand should have operands appearing in ASCII order.
425 An example of the latter set is the "bm" (best move[s]) opcode; its
426 operands are moves that are all immediately playable from the current
430 File: chess.info, Node: Opcode "acd" analysis count depth, Next: Opcode "acn" analysis count nodes, Prev: Operations, Up: EPD notation
432 1.1.6.2 Opcode "acd" analysis count depth
433 .........................................
435 The opcode "acd" takes a single non-negative integer operand. It is
436 used to represent the ply depth examined in an analysis.
439 File: chess.info, Node: Opcode "acn" analysis count nodes, Next: Opcode "acs" analysis count seconds, Prev: Opcode "acd" analysis count depth, Up: EPD notation
441 1.1.6.3 Opcode "acn" analysis count nodes
442 .........................................
444 The opcode "acn" takes a single non-negative integer operand. It is
445 used to represent the number of nodes examined in an analysis. Note
446 that the value may be quite large for some extended searches and so use
447 of (at least) a long (four byte) representation is suggested.
450 File: chess.info, Node: Opcode "acs" analysis count seconds, Next: Opcode "am" avoid move(s), Prev: Opcode "acn" analysis count nodes, Up: EPD notation
452 1.1.6.4 Opcode "acs" analysis count seconds
453 ...........................................
455 The opcode "acs" takes a single non-negative integer operand. It is
456 used to represent the number of seconds used for an analysis. Note that
457 the value may be quite large for some extended searches and so use of
458 (at least) a long (four byte) representation is suggested.
461 File: chess.info, Node: Opcode "am" avoid move(s), Next: Opcode "bm" best move(s), Prev: Opcode "acs" analysis count seconds, Up: EPD notation
463 1.1.6.5 Opcode "am" avoid move(s)
464 .................................
466 The opcode "am" indicates a set of zero or more moves, all immediately
467 playable from the current position, that are to be avoided in the
468 opinion of the EPD writer. Each operand is a SAN move; they appear in
472 File: chess.info, Node: Opcode "bm" best move(s), Prev: Opcode "am" avoid move(s), Up: EPD notation
474 1.1.6.6 Opcode "bm" best move(s)
475 ................................
477 The opcode "bm" indicates a set of zero or more moves, all immediately
478 playable from the current position, that are judged to the best
479 available by the EPD writer. Each operand is a SAN move; they appear in
483 File: chess.info, Node: Plies, Next: Variations, Prev: Positions, Up: The chess.el library
488 A "ply" is the differential between two positions. Or, it is the
489 coordinate transformations applied to one position in order to arrive at
490 the following position. It is also informally called "a move".
492 A ply may be represented in ASCII by printing the FEN string of the
493 base position, and then printing the positional transformation in
494 algebraic notation. Since the starting position is usually known, the
495 FEN string is optional. A ply may be represented graphically by moving
496 the chess piece(s) involved. It may be rendered verbally by voicing
497 which piece is to move, where it will move to, and what will happen a
498 result of the move (piece capture, check, etc).
500 Plies may be sent over network connections, postal mail, e-mail,
501 etc., so long as the current position is maintained at both sides.
502 Transmitting the base position’s FEN string along with the ply offers a
503 form of confirmation during the course of a game.
509 * The "next" position::
510 * Algebraic notation::
513 File: chess.info, Node: Creating plies, Next: Ply details, Prev: Plies, Up: Plies
518 -- Function: chess-ply-create position &optional valid-p &rest changes
519 Create a ply from the given POSITION by applying the supplied
520 CHANGES. This function will guarantee the resulting ply is legal,
521 and will also annotate the ply with :check or other modifiers as
522 necessary. It will also extend castling, and will prompt for a
525 Note: Do not pass in the rook move if CHANGES represents a castling
528 -- Function: chess-legal-plies position &rest keywords
529 Return a list of all legal plies in POSITION. KEYWORDS allowed
532 :any return t if any piece can move at all :color <t or nil> :piece
533 <piece character> :file <number 0 to 7> [can only be used if :piece
534 is present] :index <coordinate index> :target <specific target
535 index> :candidates <list of indices>
537 These will constrain the plies generated to those matching the
540 NOTE: All of the returned plies will reference the same copy of the
541 position object passed in.
544 File: chess.info, Node: Ply details, Next: The "next" position, Prev: Creating plies, Up: Plies
549 -- Function: chess-ply-pos ply
550 Returns the base position associated with PLY.
552 -- Function: chess-ply-set-pos ply position
553 Set the base position of PLY.
555 -- Function: chess-ply-changes
556 Return the coordinate transformations and keywords associated with
559 A list of a pair of indices (or two, in case of castling) followed
560 by optional keywords.
562 -- Function: chess-ply-set-changes
563 Set the coordinate transformations and keywords associated with
566 -- Function: chess-ply-source ply
567 Return the source square index value of PLY.
569 -- Function: chess-ply-target ply
570 Return the target square index value of PLY.
572 For example, here is how to find the source square of a freshly
575 (chess-ply-source (chess-ply-create chess-starting-position nil
576 (chess-coord-to-index "e2")
577 (chess-coord-to-index "e4")))
581 File: chess.info, Node: The "next" position, Next: Algebraic notation, Prev: Ply details, Up: Plies
583 1.2.3 The "next" position
584 -------------------------
586 -- Function: chess-ply-next-pos ply
587 Return the position that results from executing PLY.
589 -- Function: chess-ply-final-p ply
590 Return non-nil if this is the last ply of a game/variation.
593 File: chess.info, Node: Algebraic notation, Prev: The "next" position, Up: Plies
595 1.2.4 Algebraic notation
596 ------------------------
598 A thing to deal with in chess is algebraic move notation, such as
599 ‘Nxf3+’. This notation is a shorthand way of representing where a piece
600 is moving from and to, by specifying the piece involved, where it’s
601 going, and whether or not a capture or check is involved.
603 You can convert from algebraic notation to a ply using the following
606 -- Function: chess-algebraic-to-ply position move &optional trust
607 Convert the algebraic notation MOVE for POSITION to a ply.
609 The function also checks if a move is legal, and will raise an error
612 To convert from a ply to algebraic notation, use:
614 -- Function: chess-ply-to-algebraic ply &optional type
615 Convert the given PLY to algebraic notation (a string).
617 Optional argument TYPE specifies the kind of algebraic notation to
618 generate. ‘:san’ (the default) generates short (or standard)
619 algebraic notation. ‘:lan’ generates long algebraic notation (like
620 ‘Nb1-c3’). ‘:fan’ generates figurine algebraic notation (uppercase
621 letters will be replaced by Unicode chess figures).
623 Lastly, there is a regexp for quickly checking if a string is in
624 algebraic notation or not, or searching out algebraic strings in a
627 -- Variable: chess-algebraic-regexp
628 A regular expression that matches all possible algebraic moves.
629 This regexp handles both long and short form.
632 File: chess.info, Node: Variations, Next: Games, Prev: Plies, Up: The chess.el library
637 A "variation" is a sequence of plies that occur after some starting
638 position. If the starting position represents the initial setup of a
639 chess board, and if the final ply results in completion of the game, it
640 is called the "main variation". Otherwise, variations typically
641 represented interesting tangents during a game—but not actually
642 played—as envisioned by the player, an annotator, or someone studying
645 Variations may be represented in ASCII by stating the FEN string for
646 starting position, followed by the list of plies that follow that
647 position. They are difficult to represent graphically, except for
648 showing each position in turn with a slight pause between—or by allowing
649 the user to navigate each of the subsequent positions in turn. They may
650 be represented verbally by announcing each of the plies in turn, as
655 * Creating variations::
656 * Variation positions::
658 * Making a move in a variation::
661 File: chess.info, Node: Creating variations, Next: Variation positions, Prev: Variations, Up: Variations
663 1.3.1 Creating variations
664 -------------------------
666 -- Function: chess-var-create &optional position
667 Create a new chess variation object. Optionally use the given
671 File: chess.info, Node: Variation positions, Next: Variation plies, Prev: Creating variations, Up: Variations
673 1.3.2 Variation positions
674 -------------------------
676 -- Function: chess-var-pos var &optional index
677 Return the position related to VAR’s INDEX ply.
679 -- Function: chess-var-index var
680 Return the VAR’s current position index.
682 -- Function: chess-var-seq var
683 Return the current VAR sequence.
685 -- Function: chess-var-side-to-move var &optional index
686 Return the color whose move it is in VAR at INDEX (or at the last
687 position of the variation if INDEX is nil).
690 File: chess.info, Node: Variation plies, Next: Making a move in a variation, Prev: Variation positions, Up: Variations
692 1.3.3 Variation plies
693 ---------------------
695 -- Function: chess-var-ply var &optional index
696 Return VAR’s INDEXth ply.
698 -- Function: chess-var-plies var
699 Return the plies of VAR.
701 -- Function: chess-var-to-algebraic var &optional long
702 Reveal the plies of VAR by converting them to algebraic notation.
705 File: chess.info, Node: Making a move in a variation, Prev: Variation plies, Up: Variations
707 1.3.4 Making a move in a variation
708 ----------------------------------
710 -- Function: chess-var-move var ply
711 Make a move in the current VAR by applying the changes of PLY.
712 This creates a new position and adds it to the main variation. The
713 ’changes’ of the last ply reflect whether the var is currently in
714 progress (nil), if it is drawn, resigned, mate, etc.
716 -- Function: chess-var-add-ply var ply
717 Add to VAR the given PLY.
720 File: chess.info, Node: Games, Next: Collections, Prev: Variations, Up: The chess.el library
725 A "game" includes its main variation, incidental information about the
726 game (who played it, where, when, who won, etc), and any sub-variations
727 of interest to those studying the game afterwards.
729 Where TAGS is an alist that associates arbitrary English tag names to
732 A game may be represented in ASCII using PGN (Portable Game
733 Notation). Representing them graphically or verbally is similar to what
734 is done for variations.
736 -- Function: chess-game-add-hook game function &optional data prepend
737 Add to GAME an event hook FUNCTION.
739 -- Function: chess-game-add-ply game ply
740 Add PLY to the main variation of GAME.
742 -- Function: chess-game-hooks game
743 Return the event hooks associated with GAME.
745 -- Function: chess-game-plies game
746 Return the main variation of GAME as a list of plies.
748 -- Function: chess-game-remove-hook game function &optional data
749 Remove from GAME all event hooks that match FUNCTION. If DATA is
750 specified, only remove those hooks whose associated data matches.
752 -- Function: chess-game-run-hooks game &rest args
753 Run the event hooks of GAME and pass ARGS.
755 -- Function: chess-game-set-hooks game hooks
756 Set the event hooks associated with GAME.
758 -- Function: chess-game-set-plies game plies
759 Set the list of plies which represents the main variation of GAME.
771 File: chess.info, Node: Creating games, Next: Game tags, Prev: Games, Up: Games
776 -- Function: chess-game-create &optional position tags
777 Create a new chess game object. Optionally use the given starting
778 POSITION (see also ‘chess-game-set-start-position’). TAGS is the
779 starting set of game tags (which can always be changed later using
780 the various tag-related methods).
783 File: chess.info, Node: Game tags, Next: Game positions, Prev: Creating games, Up: Games
788 -- Function: chess-game-tags game
789 Return the tags alist associated with GAME.
791 -- Function: chess-game-set-tags game tags
792 Set the tags alist associated with GAME. After the TAGS alist was
793 set the ’set-tags event is triggered.
795 -- Function: chess-game-tag game tag
796 Return the value for TAG in GAME.
798 -- Function: chess-game-set-tag game tag value
799 Set a TAG for GAME to VALUE.
801 -- Function: chess-game-del-tag game tag
802 Delete a TAG from GAME.
805 File: chess.info, Node: Game positions, Next: Game plies, Prev: Game tags, Up: Games
810 -- Function: chess-game-pos game &optional index
811 Return the current position of GAME or a position of a given INDEX.
813 -- Function: chess-game-index game
814 Return the GAME’s current position index.
816 -- Function: chess-game-seq game
817 Return the current GAME sequence number.
819 -- Function: chess-game-side-to-move game &optional index
820 Return the color whose move it is in GAME at INDEX (or at the last
821 position if INDEX is nil). ‘t’ for white and ‘nil’ for black.
824 File: chess.info, Node: Game plies, Next: Making a move, Prev: Game positions, Up: Games
829 -- Function: chess-game-ply game &optional index
830 Return a ply of GAME. If INDEX is non-nil, the last played ply is
834 File: chess.info, Node: Making a move, Next: PGN notation, Prev: Game plies, Up: Games
839 -- Function: chess-game-move game ply
840 Make a move in the current GAME using PLY. This creates a new
841 position and adds it to the main variation. The ’changes’ of the
842 last ply reflect whether the game is currently in progress (nil),
843 if it is drawn, resigned, mate, etc.
846 File: chess.info, Node: PGN notation, Prev: Making a move, Up: Games
851 -- Function: chess-pgn-to-game &optional string
852 Convert "PGN notation" at point into a chess game. Optionally use
853 the supplied STRING instead of the current buffer.
855 -- Function: chess-game-to-pgn game &optional indented to-string
856 Convert a chess GAME to "PGN notation". If INDENTED is non-nil,
857 indent the move texts. If TO-STRING is non-nil, return a string
858 instead of inserting the resulting PGN text.
860 -- Function: chess-pgn-insert-plies game index plies &optional
861 for-black indented no-annotations
862 NYI: Still have to implement INDENTED argument.
869 File: chess.info, Node: PGN mode, Prev: PGN notation, Up: PGN notation
874 -- Function: chess-pgn-visualize
875 Visualize the move for the PGN game under point. This does not
876 require that the buffer be in PGN mode.
879 File: chess.info, Node: Collections, Next: Chess Opening Books, Prev: Games, Up: The chess.el library
884 A "collection" is a set of games archived for later perusal. A set of
885 games conceptually represents a large tree of branching variations, and
886 can be used for studying current theory, examining Master preferences,
889 Chess.el itself does not attempt to provide library services, nor
890 does it ever represent library collections in memory. Instead, it
891 interacts with a chess database engine for the purpose of storing and
892 retrieving games from the library, or performing library-wide analyses
897 * Opening Databases::
898 * Querying Databases::
899 * Modifying Databases::
900 * Finalising Databases::
904 File: chess.info, Node: Opening Databases, Next: Querying Databases, Prev: Collections, Up: Collections
906 1.5.1 Opening Databases
907 -----------------------
909 -- Variable: chess-database-modules
910 List of database modules to try when ‘chess-database-open’ is
913 -- Function: chess-database-open file &optional module
914 Returns the opened database object, or nil.
917 File: chess.info, Node: Querying Databases, Next: Modifying Databases, Prev: Opening Databases, Up: Collections
919 1.5.2 Querying Databases
920 ------------------------
922 -- Function: chess-database-filename database
923 Return the filename of an already opened DATABASE.
925 -- Function: chess-database-read database index
926 Return from DATABASE the chess game object at INDEX.
928 -- Function: chess-database-query database &rest terms
929 Run a query on DATABASE. TERMS is partly dependent on the
930 chess-database module in use. chess-scid: tree-search GAME:
931 Perform a tree search on the last position of GAME.
934 File: chess.info, Node: Modifying Databases, Next: Finalising Databases, Prev: Querying Databases, Up: Collections
936 1.5.3 Modifying Databases
937 -------------------------
939 -- Function: chess-database-read-only-p database
940 Return non-nil if DATABASE is read only.
943 File: chess.info, Node: Finalising Databases, Next: Database Modules, Prev: Modifying Databases, Up: Collections
945 1.5.4 Finalising Databases
946 --------------------------
949 File: chess.info, Node: Database Modules, Prev: Finalising Databases, Up: Collections
951 1.5.5 Database Modules
952 ----------------------
954 Currently, there are two subclasses of the above defined database
963 File: chess.info, Node: chess-file, Next: chess-scid, Prev: Database Modules, Up: Database Modules
968 This module does not use an external chess database program to store and
969 retrieve games. It uses the PGN of EPD format parsing routines provided
970 in ‘chess-pgn.el’ and ‘chess-epd.el’ to implement Collections for
971 ordinary PGN and EPD files.
973 EPD file collections are represented as a collection of games
974 originating at the given position. One might argue that conceptually,
975 they represent a collection of positions, but it is more convenient to
976 merge all collections into one uniform concept.
979 File: chess.info, Node: chess-scid, Prev: chess-file, Up: Database Modules
984 This modules implement basic reading and writing functionality for SCID
985 (Shane’s Chess Information Database) files.
988 File: chess.info, Node: Chess Opening Books, Prev: Collections, Up: The chess.el library
990 1.6 Chess Opening Books
991 =======================
993 There are two different modules/libraries provided for looking up chess
994 positions in opening books.
998 * ECO Classification::
999 * Polyglot opening book format support::
1002 File: chess.info, Node: ECO Classification, Next: Polyglot opening book format support, Prev: Chess Opening Books, Up: Chess Opening Books
1004 1.6.1 ECO Classification
1005 ------------------------
1007 Module ‘chess-eco’ provides a database of well known names for chess
1008 opening positions. If this module is activated (see variable
1009 ‘chess-default-modules’) known chess opening positions will be announced
1010 in the minibuffer during a game.
1013 File: chess.info, Node: Polyglot opening book format support, Prev: ECO Classification, Up: Chess Opening Books
1015 1.6.2 Polyglot opening book format support
1016 ------------------------------------------
1018 The popular and freely documented Polyglot opening book format is
1019 supported. There is a default polyglot book file shipped with chess.el
1020 to support engines which do not have built-in support for looking up
1021 positions in opening books (such as some UCI protocol based engines).
1023 -- Variable: chess-polyglot-book-file
1024 Path to default polyglot book file.
1026 -- Variable: chess-polyglot-book
1027 If non-nil, the buffer holding the currently loaded polyglot book
1030 This is used by UCI based engine modules as well as the internal
1033 -- Function: chess-polyglot-book-open file
1034 Open a polyglot book FILE.
1036 Returns a buffer object which contains the binary data.
1038 -- Function: chess-polyglot-book-plies book position
1039 Return a list of plies found in BOOK for POSITION. The resulting
1040 list is ordered, most interesting plies come first. The
1041 ‘:polyglot-book-weight’ ply keyword is used to store the actual
1042 move weights. Use ‘chess-ply-keyword’ on elements of the returned
1043 list to retrieve them.
1045 -- Function: chess-polyglot-book-ply book position &optional strength
1046 If non-nil a (randomly picked) ply from BOOK for POSITION. Random
1047 distribution is defined by the relative weights of the found plies.
1048 If non-nil, STRENGTH defines the bias towards better moves. A
1049 value below 1.0 will penalize known good moves while a value above
1050 1.0 will prefer known good moves. The default is the value of
1051 ‘chess-polyglot-book-strength’. A strength value of 0.0 will
1052 completely ignore move weights and evenly distribute the
1053 probability that a move gets picked.
1056 File: chess.info, Node: Modules, Next: Chessboard displays, Prev: The chess.el library, Up: Top
1061 Positions, plies and variations are typically accessed in reference to a
1062 game object, which has a main variation containing the plies and
1063 positions that represent the number of moves made within that game up to
1066 Another thing that the game object does is to manage events that
1067 occur within that game. If a move is made from the final position, for
1068 example, it will cause a new ply to be created, adding it to the end of
1069 the main variation. Then, a ‘move’ event is triggered within the game
1070 and passed to any chess modules which are currently associated with that
1071 game. The concept of modules allows far more complex aspects of chess
1072 playing to be dealt with, while allowing the library itself to still
1073 operate solely in terms of the game object.
1075 For example, although the plies of a game object contain all the
1076 information the computer needs to follow the game, a user needs much
1077 more. He wants to see the pieces move. To support this, a display
1078 module (see next chapter) can be created, and linked to the game. The
1079 first effect of this association will be to create a chess board display
1080 and show the game’s final position on it. Now whenever plies are added
1081 to the game, the chess board will be updated to show the effect of that
1082 move on the board. The display module realizes that a move has been
1083 made by receiving the ‘move’ event which is passed to all modules
1084 associated with the game object.
1086 There may be any number of modules associated with a chess game, and
1087 they may do anything you like. Basically, for a module called
1088 chess-sample, a function must exist called ‘chess-sample-handler’. This
1089 takes two or more arguments: a game object, the event symbol, and
1090 whatever other arguments were passed along with the event symbol.
1092 When an event is triggered on a game object (and this may happen as a
1093 byproduct of manipulating the game, or events may be manually
1094 generated), every associated module, in order, is called with that event
1095 and whatever arguments were passed along with the event. The game
1096 object is passed also, so that the module knows which game this event
1097 has occurred in reference to.
1099 Once called, the module can do whatever it likes. Some events expect
1100 certain values to be returned, to indicate success or failure in
1101 processing the event. There are many different events, each depicting
1102 something specific that might happen in the context of playing or
1103 manipulating a chess game. Some events relate only to the chess game
1104 itself, some are triggered by the various chess engines that might be
1105 associated with that game. Modules may even trigger events in response
1106 to event. The game itself remains unaware of events, except for the
1107 fact that it will pass them along to every module associated with that
1110 This is how displays get updated, for example, because once a ’move’
1111 event is triggered, each display knows that it must now look at the new
1112 final position and update its display. It may even trigger new events
1113 special to displays, to cause a refresh to happen after update
1114 calculations have been performed, for example. All such details are
1115 left to the module, and the game does not interfere with such
1116 intra-module messaging.
1118 Looked at as an object-oriented design, these are typical polymorphic
1119 events. Certain generic situations frequently occur, such as moves,
1120 which trigger events so that everyone concerned with the game can be
1121 updated as to the move that occurred. This way, no one need to actively
1122 query the game to find out if something new has happened. The game will
1123 notify every listening module by sending an event.
1125 The core library, which consists of code to manipulate games, does
1126 not define any modules. The rest of the chess.el library is strictly a
1127 set of module implementations, of various types. Display modules react
1128 to moves, and may modify the game based on user input; engine modules
1129 react to moves by notifying the engine of the move; network client
1130 modules react to moves by sending the move text over the network.
1131 Engine and network modules may also trigger new events when the engine
1132 or network player has decided on their move, and this move is then
1133 applied to the game object.
1135 At the moment, no negotiation is done to determine which module may
1136 modify the game object. All modules have equal privilege. This means
1137 it is the programmer’s duty not to associate conflicting modules with a
1138 single game object. If two artificial intelligence engines were linked,
1139 for example, they would quickly start stepping on each other’s toes.
1140 But it perfectly fine to have one artificial intelligence engine, and
1141 another passive engine whose only purpose is to relay the moves to a
1142 networked observer on another computer. The possibilities are endless.
1144 Modules are very easy to write, although engines and displays are
1145 rather different from each other in their principles. There is a base
1146 engine, and a base display, which receive the same events as any other
1147 module. But then there are derived engines and derived displays which
1148 trigger a whole family of events specific to those module types. If you
1149 suspect a bug in your module, put a breakpoint in your handler function,
1150 and wait for the offending event to come through. Then you can watch
1151 what your module does in response to that event. If it leaves the game
1152 object alone, it should be easy to locate the problem, since it will
1153 always be within the module itself. But if your module also modifies
1154 the game object in response to certain events, you may induce a feedback
1155 loop that is much more difficult to sort out. Test often and keep in
1156 mind that *many* events might end up coming through as a result of the
1157 game changes your module makes!
1159 That, in essence, is how the module system works. From the game
1160 object’s perspective, it is a very simple mechanism, much like a
1161 function ring or a hook. The hook is called at certain points, so that
1162 any listener can react to changes in the game. But from each module’s
1163 perspective, it is a rich way to allow inter-operation between both
1164 passive and reactive modules, all of them acting together to enrich the
1165 context of play involving the central game object.
1167 The only other rule to be mentioned is that each module instance
1168 should be associated with only one game object at a time, although a
1169 game object may have unlimited modules of any type linked to it.
1170 Otherwise, trying to update a chess board based on input from two
1171 different games would get impossible to sort out. Better to create a
1172 new board for every game—the way ordinary humans would do it in the real
1176 File: chess.info, Node: Chessboard displays, Next: Engines, Prev: Modules, Up: Top
1178 3 Chessboard displays
1179 *********************
1181 The previous chapter described all the objects found in chess—positions,
1182 plies, variations, games and collections. However, these objects can
1183 only be manipulated programmatically using the functions given so far.
1184 In order to present them in a meaningful fashion to a human reader, it
1185 is necessary to create and use a display object.
1189 * Generic display manipulation functions::
1190 * Chess display mode::
1191 * Plain ASCII diagram displays::
1192 * ICS1 style ASCII displays::
1193 * Graphical displays::
1196 File: chess.info, Node: Generic display manipulation functions, Next: Chess display mode, Prev: Chessboard displays, Up: Chessboard displays
1198 3.1 Generic display manipulation functions
1199 ==========================================
1201 -- Function: chess-display-create game style perspective
1202 Create a chess display, for displaying chess objects. Where GAME
1203 is the chess game object to use, STYLE should be the display type
1204 to use (a symbol) and PERSPECTIVE determines the viewpoint of the
1205 board, if non-nil, the board is viewed from White’s perspective.
1207 -- Function: chess-display-active-p
1208 Return non-nil if the displayed chessboard reflects an active game.
1209 Basically, it means we are playing, not editing or reviewing.
1211 -- Function: chess-display-clear-board
1212 Setup the current board for editing.
1214 -- Function: chess-display-highlight display &rest args
1215 Highlight the square at INDEX on the current position. The given
1216 highlighting MODE is used, or the default if the style you are
1217 displaying with doesn’t support that mode. ‘selected’ is a mode
1218 that is supported by most displays, and is the default mode.
1220 -- Function: chess-display-invert
1221 Invert the perspective of the current chess board.
1223 -- Function: chess-display-move display ply
1224 Move a piece on DISPLAY, by applying the given PLY. The position
1225 of PLY must match the currently displayed position.
1227 -- Function: chess-display-perspective display
1228 Return the current perspective of DISPLAY.
1230 -- Function: chess-display-position display
1231 Return the position currently viewed on DISPLAY.
1233 -- Function: chess-display-quit
1234 Quit the game associated with the current display.
1236 -- Function: chess-display-set-game display game &optional index
1237 Set the given DISPLAY to display the GAME object, optionally at
1238 INDEX. This is the function to call to cause a display to view a
1239 game. It will also update all of the listening engines and other
1240 displays to also view the same game.
1242 -- Function: chess-display-set-perspective display perspective
1243 Set PERSPECTIVE of DISPLAY.
1245 -- Function: chess-display-set-position display &optional position
1247 Set the game associated with DISPLAY to use POSITION and MY-COLOR.
1249 -- Function: chess-display-set-variation display variation &optional
1251 Set DISPLAY VARIATION. If INDEX is not specified, this will cause
1252 the first ply in the variation to be displayed, with the user able
1253 to scroll back and forth through the moves in the variation. Any
1254 moves made on the board will extend/change the variation that was
1257 -- Function: chess-display-update display &optional popup
1258 Update the chessboard DISPLAY. POPUP too, if that arg is non-nil.
1261 File: chess.info, Node: Chess display mode, Next: Plain ASCII diagram displays, Prev: Generic display manipulation functions, Up: Chessboard displays
1263 3.2 Chess display mode
1264 ======================
1266 Chess display mode is a special major mode (*note (emacs)Major Modes::)
1267 that allows to select pieces to move with the mouse or by moving point
1268 to the desired square/piece. Additionally, you can enter moves in a
1269 variant of algebraic notation via the keyboard.
1271 All the chessboard displays described in following sections share the
1272 basic behaviour provided by chess display mode. They basically only
1273 differ in appearance of the various chessboards.
1277 * Basic operations::
1278 * Selecting pieces with the keyboard::
1279 * Selecting pieces with the mouse::
1280 * Entering moves with algebraic notation::
1283 File: chess.info, Node: Basic operations, Next: Selecting pieces with the keyboard, Prev: Chess display mode, Up: Chess display mode
1285 3.2.1 Basic operations
1286 ----------------------
1290 Invert the perspective of the current chess board.
1293 Show the previous move in the current game.
1296 Find previous move which algebraic notation matches a regular
1297 expression ‘chess-display-search-backward’.
1300 Find next move which algebraic notation matches a regular
1301 expression ‘chess-display-search-forward’.
1304 Show the next move in the current game.
1307 Move to the initial position of the current game
1308 (‘chess-display-move-first’).
1311 Move to the last position of the current game
1312 (‘chess-display-move-last’).
1315 Offer to draw the current game (‘chess-display-draw’).
1318 Resign the current game (‘chess-display-resign’).
1321 Copy the currently displayed position to the kill ring as a FEN
1322 string (‘chess-display-kill-board’).
1325 Set the current display position via a FEN string from the kill
1326 ring (‘chess-display-yank-board’).
1328 This is useful to copy positions from one chessboard display to
1329 another, as well as quickly setting up a position from a FEN string
1330 previously added to the kill ring from somewhere else.
1333 Quit this chessboard display (‘chess-display-quit’).
1335 This destroys the session (and all related modules) associated with
1336 this chessboard display.
1339 File: chess.info, Node: Selecting pieces with the keyboard, Next: Selecting pieces with the mouse, Prev: Basic operations, Up: Chess display mode
1341 3.2.2 Selecting pieces with the keyboard
1342 ----------------------------------------
1344 In character based chessboard displays, point can be moved around in the
1345 buffer as uaual. You can indicate the initial square/piece and the
1346 target square/piece by moving point to the desired position and pressing
1350 Select the piece/square currently indicated by point
1351 (‘chess-display-select-piece’) to move from/to.
1354 File: chess.info, Node: Selecting pieces with the mouse, Next: Entering moves with algebraic notation, Prev: Selecting pieces with the keyboard, Up: Chess display mode
1356 3.2.3 Selecting pieces with the mouse
1357 -------------------------------------
1359 Similarily, you can also use the mouse (if available) to indicate the
1360 source and target square of your move.
1366 Select the piece/square currently indicated by the mouse pointer
1367 (‘chess-display-select-piece’) to move from/to.
1370 File: chess.info, Node: Entering moves with algebraic notation, Prev: Selecting pieces with the mouse, Up: Chess display mode
1372 3.2.4 Entering moves with algebraic notation
1373 --------------------------------------------
1384 Enter move in algebraic notation.
1386 The move will be accepted as soon as it is unambiguous. So in most
1387 situations, you do not need to type the complete algebraic move
1388 string. For instance, if there is only one piece which can be
1389 taken by one of your knights, typing ‘N x’ is sufficient to select
1392 Additionally, the characters ‘x’ and ‘=’ are optional, as there is
1393 no difference between ‘N x e 4’ and ‘N e 4’.
1396 Delete the last entered chess move character
1397 ‘chess-input-shortcut-delete’.
1399 This is useful if you have accidentally typed a wrong character,
1400 and the move was not unambiguous yet.
1403 File: chess.info, Node: Plain ASCII diagram displays, Next: ICS1 style ASCII displays, Prev: Chess display mode, Up: Chessboard displays
1405 3.3 Plain ASCII diagram displays
1406 ================================
1408 The simplest display style available is CHESS-PLAIN, a very customisable
1409 ASCII board diagram display.
1411 -- User Option: chess-plain-separate-frame
1412 If non-nil, display the chessboard in its own frame.
1414 -- User Option: chess-plain-border-style
1415 If non-nil, a vector of Characters used to draw borders.
1417 Otherwise, omit to draw any border around the chessboard diagram.
1419 -- User Option: chess-plain-black-square-char
1420 Character used to indicate empty black squares.
1422 -- User Option: chess-plain-white-square-char
1423 Character used to indicate black white squares.
1425 -- User Option: chess-plain-piece-chars
1426 Alist of pieces and their corresponding characters.
1428 -- User Option: chess-plain-upcase-indicates
1429 Defines what a upcase char should indicate. The default is
1430 ‘'color’, meaning a upcase char is a white piece, a lowercase char
1431 a black piece. Possible values: ‘'color’ (default),
1432 ‘'square-color’. If set to ‘'square-color’, a uppercase character
1433 indicates a piece on a black square. (Note that you also need to
1434 modify ‘chess-plain-piece-chars’ to avoid real confusion.)
1436 -- User Option: chess-plain-spacing
1437 Number of spaces between files.
1440 File: chess.info, Node: ICS1 style ASCII displays, Next: Graphical displays, Prev: Plain ASCII diagram displays, Up: Chessboard displays
1442 3.4 ICS1 style ASCII displays
1443 =============================
1445 -- User Option: chess-ics1-separate-frame
1446 If non-nil, display the chessboard in its own frame.
1449 File: chess.info, Node: Graphical displays, Prev: ICS1 style ASCII displays, Up: Chessboard displays
1451 3.5 Graphical displays
1452 ======================
1454 The graphical chessboard display (‘chess-images’) uses image files to
1455 create a visually appealing chessboard in a buffer.
1457 -- User Option: chess-images-directory
1458 A directory which contains images in XPM format.
1460 If you want to draw your own images, each piece must be named
1461 ‘COLOR-PIECE.xpm’, where COLOR is either black or white, and PIECE
1462 is one of rook, knight, bishop, queen, king or pawn.
1464 The only image format currently supported is XPM.
1467 File: chess.info, Node: Engines, Next: Chess Session, Prev: Chessboard displays, Up: Top
1472 Engines are the representation of an opponent in Chess. THe main type
1473 of engine interfaces with an external chess program. However, there can
1474 be other uses for engine objects, such as providing networked engined
1475 for playing with opponent over different types of transports.
1479 * Common functions::
1490 File: chess.info, Node: Common functions, Next: AI, Prev: Engines, Up: Engines
1492 4.1 Common functions
1493 ====================
1495 -- Function: chess-engine-create module game &optional response-handler
1496 &rest handler-ctor-args
1497 Create a new chess engine MODULE (a symbol) associated with GAME.
1498 Optionally supply a new RESPONSE-HANDLER.
1500 -- Function: chess-engine-set-option engine option value
1501 Set ENGINE OPTION to VALUE by invoking its handler with the
1504 -- Function: chess-engine-position engine
1505 Return the current position of the game associated with ENGINE.
1507 -- Function: chess-engine-command engine event &rest args
1508 Call the handler of ENGINE with EVENT (a symbol) and ARGS.
1510 -- Function: chess-engine-send engine string
1511 Send the given STRING to ENGINE. If ‘chess-engine-process’ is a
1512 valid process object, use ‘process-send-string’ to submit the data.
1513 Otherwise, the ’send event is triggered and the engine event
1514 handler can take care of the data.
1517 File: chess.info, Node: AI, Next: Crafty, Prev: Common functions, Up: Engines
1522 The AI engine module defines a pure Emacs Lisp implementation of an
1523 opponent. Contrary to all other engine modules mentioned later on, it
1524 does not require any external programs to be installed.
1526 To explicitly select this engine as an opponent, use ‘C-u M-x chess
1529 -- User Option: chess-ai-depth
1530 Defines the default search depth for this engine.
1532 -- User Option: chess-ai-quiescence-depth
1533 Defines the number of plies to search for a quiet position. This
1534 is in addition to ‘chess-ai-depth’.
1536 If you’d like to employ the search and evaluation functions provided
1537 by this module programmatically, the following function is the top-level
1540 -- Function: chess-ai-best-move position &optional depth eval-fn
1541 Find the supposedly best move (ply) for POSITION. DEPTH defaults
1542 to the value of ‘chess-ai-depth’.
1545 File: chess.info, Node: Crafty, Next: Fruit, Prev: AI, Up: Engines
1550 "Crafty" is a chess program written by Michael Byrne, UAB professor Dr.
1551 Robert Hyatt, Tracy Riegle, Peter Skinner and Ted Langreck. It is
1552 directly derived from Cray Blitz, winner of the 1983 and 1986 World
1553 Computer Chess Championships.
1555 If the ‘crafty’ program is installed and can be found in the program
1556 search path (‘exec-path’), the ‘chess-crafty’ engine module will
1557 automatically detect it.
1559 If ‘crafty’ is installed in a non-standard location, variable
1560 ‘chess-crafty-path’ can be set to point to the executable.
1562 If you have multiple engines installed you can explicitly select to
1563 play against Crafty by invoking ‘C-u M-x chess <RET> crafty <RET>’.
1566 File: chess.info, Node: Fruit, Next: Glaurung, Prev: Crafty, Up: Engines
1571 "Fruit" is a chess engine developed by Fabien Letouzey. It was
1572 commercially available from September 2005 until July 2007. Now it is
1573 freeware and you can download it for free from
1574 <http://www.fruitchess.com/>. The development on Fruit by Fabien
1575 Letouzey has ceded and it is unlikely to continue.
1577 Fruit was vice world computer chess champion 2005.
1579 If the ‘fruit’ command is installed and can be found in the program
1580 search path (‘exec-path’), the ‘chess-fruit’ engine module will
1581 automatically detect it.
1583 If Fruit is installed in a non-standard location, variable
1584 ‘chess-fruit-path’ can be set to point to the executable.
1586 If you have multiple engines installed you can explicitly select to
1587 play against Fruit by invoking ‘C-u M-x chess <RET> fruit <RET>’.
1590 File: chess.info, Node: Glaurung, Next: GNU Chess, Prev: Fruit, Up: Engines
1595 "Glaurung" is another freely distributed strong computer chess engine.
1597 If the ‘glaurung’ program is installed and can be found in the
1598 program search path (‘exec-path’), the ‘chess-glaurung’ engine module
1599 will automatically detect it.
1601 If Glaurung is installed in a non-standard location, variable
1602 ‘chess-glaurung-path’ can be set to point to the executable.
1604 If you have multiple engines installed you can explicitly select to
1605 play against Glaurung by invoking ‘C-u M-x chess <RET> glaurung <RET>’.
1608 File: chess.info, Node: GNU Chess, Next: Phalanx, Prev: Glaurung, Up: Engines
1613 "GNU Chess" is free software, licensed under the terms of the GNU
1614 General Public License version 3 or any later version, and is maintained
1615 by collaborating developers. As one of the earliest computer chess
1616 programs with full source code available, it’s one of the oldest for
1617 Unix-based systems and has since been ported to many other platforms.
1619 If the ‘gnuChess’ program is installed and can be found in the
1620 program search path (‘exec-path’), the ‘chess-gnuchess’ engine module
1621 will automatically detect it.
1623 If GNU Chess is installed in a non-standard location, variable
1624 ‘chess-gnuchess-path’ can be set to point to the executable.
1626 If you have multiple engines installed you can explicitly select to
1627 play against GNU Chess by invoking .
1630 File: chess.info, Node: Phalanx, Next: Sjeng, Prev: GNU Chess, Up: Engines
1635 "Phalanx" is an old, popular chess engine, with an interesting history.
1637 If the ‘phalanx’ program is installed and can be found in the program
1638 search path (‘exec-path’), the ‘chess-phalanx’ engine module will
1639 automatically detect it.
1641 If Phalanx is installed in a non-standard location, variable
1642 ‘chess-phalanx-path’ can be set to point to the executable.
1644 If you have multiple engines installed you can explicitly select to
1645 play against Phalanx by invoking ‘C-u M-x chess <RET> phalanx <RET>’.
1648 File: chess.info, Node: Sjeng, Next: Stockfish, Prev: Phalanx, Up: Engines
1653 "Sjeng" (http://sjeng.org/) is a championship-winner automated chess
1654 engine developed by Gian-Carlo Pascutto from Belgium. While its
1655 original version was free, recent developments are for sale.
1657 If the ‘sjeng’ program is installed and can be found in the program
1658 search path (‘exec-path’), the ‘chess-sjeng’ engine module will
1659 automatically detect it.
1661 If Sjeng is installed in a non-standard location, variable
1662 ‘chess-sjeng-path’ can be set to point to the executable.
1664 If you have multiple engines installed you can explicitly select to
1665 play against Sjeng by invoking ‘C-u M-x chess <RET> sjeng <RET>’.
1668 File: chess.info, Node: Stockfish, Prev: Sjeng, Up: Engines
1673 "Stockfish" (http://www.stockfishchess.org/) is one of the strongest
1674 chess engines in the world, appearing near or at the top of most chess
1675 engine rating lists. Stockfish is also free software, licensed under
1676 the terms of the GNU General Public License.
1678 If the ‘stockfish’ program is installed and can be found in the
1679 program search path (‘exec-path’), the ‘chess-stockfish’ engine module
1680 will automatically detect it.
1682 If Stockfish is installed in a non-standard location, variable
1683 ‘chess-stockfish-path’ can be set to point to the executable.
1685 If you have multiple engines installed you can explicitly select to
1686 play against Stockfish by invoking ‘C-u M-x chess <RET> stockfish
1690 File: chess.info, Node: Chess Session, Next: Internet Chess Servers, Prev: Engines, Up: Top
1695 A chess session assembles all modules mentioned in previous chapters
1696 into a working system to interact with. A session typically consists of
1697 at least one display module, one engine module, and possibly a number of
1698 optional modules. All these mdoules share a common game object which is
1699 used to keep track of the currently active game.
1701 -- Function: chess engine disable-popup engine-response-handler &rest
1703 Play a game against ENGINE.
1705 This function constructs all the necessary modules required for a
1706 chess session. In particular, it will start ENGINE and create a
1707 chess display as configured in ‘chess-default-display’.
1709 This is the main entry-point for interactively launching a
1710 chessboard display with associated engine.
1712 If you want to launch a chess session as part of your own code, the
1713 probably more expressive alias ‘chess-session’ might be interesting
1716 You can have several active chess sessions. In fact, some features
1717 later described in this manual make use of this, *Note Internet Chess
1721 File: chess.info, Node: Internet Chess Servers, Next: Concept Index, Prev: Chess Session, Up: Top
1723 6 Internet Chess Servers
1724 ************************
1726 Based on the services provided above, there is also a special mode for
1727 communication with Internet Chess Servers.
1729 On an Internet Chess Server you can seek to play against other human
1730 or computer players, observe other games being player or examined, play
1731 tournaments, chat with fellow chess players, participate in team games,
1732 or do various other interesting chess related things.
1734 A default set of well known servers is defined in the following
1737 -- Variable: chess-ics-server-list
1738 A list of servers to connect to. The format of each entry is:
1740 (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER
1743 Internet Chess Servers based on FICS (Free Internet Chess Server)
1744 (http://www.freechess.org/) and ICC (Internet Chess Club)
1745 (http://www.chessclub.com/) are currently supported.
1749 * Connecting to a server::
1752 * Seeking an opponent for a new game::
1753 * The sought game display::
1754 * Watching other games::
1757 File: chess.info, Node: Connecting to a server, Next: Chess ICS Mode, Prev: Internet Chess Servers, Up: Internet Chess Servers
1759 6.1 Connecting to a server
1760 ==========================
1762 To open a new connection to an Internet Chess Server, use:
1764 -- Function: chess-ics server port &optional handle
1765 password-or-filename helper &rest helper-args
1766 Connect to an Internet Chess Server.
1768 If called interactively, you will be prompted to enter a server
1769 (from ‘chess-ics-server-list’ and possibly identification
1773 File: chess.info, Node: Chess ICS Mode, Next: Command History, Prev: Connecting to a server, Up: Internet Chess Servers
1778 The major mode for ICS buffers is Chess ICS mode. Many of its special
1779 commands are bound to the ‘C-c’ prefix. Here is a list of ICS mode
1783 Send the current line as input to the server (‘comint-send-input’).
1784 Any prompt at the beginning of the line is omitted. If point is at
1785 the end of buffer, this is like submitting the command line in an
1786 ordinary interactive shell. However, you can also invoke <RET>
1787 elsewhere in the ICS buffer to submit the current line as input.
1790 Either delete a character or send EOF (End Of File)
1791 (‘comint-delchar-or-maybe-eof’). Typed at the end of the ICS
1792 buffer, this sends EOF to the server and terminates the connection.
1793 Typed at any other position in the buffer, this deletes a character
1797 Move to the beginning of the line, but after the prompt if any
1798 (‘comint-bol-or-process-mark’). If you repeat this command twice
1799 in a row, the second time it moves back to the process mark, which
1800 is the beginning of the input that you have not yet sent to the
1801 server. (Normally that is the same place—the end of the prompt on
1802 this line—but after ‘C-c <SPC>’ the process mark may be in a
1806 Accumulate multiple lines of input, then send them together
1807 (‘comint-accumulate’). This command inserts a newline before
1808 point, but does not send the preceding text as input to the
1809 server—at least, not yet. Both lines, the one before this newline
1810 and the one after, will be sent together (along with the newline
1811 that separates them), when you type <RET>.
1814 Kill all text pending at end of buffer to be sent as input
1815 (‘comint-kill-input’). If point is not at end of buffer, this only
1816 kills the part of this text that precedes point.
1819 Kill a word before point (‘backward-kill-word’).
1822 Delete the last batch of output from an ICS server command
1823 (‘comint-delete-output’). This is useful if a server command spews
1824 out lots of output that just gets in the way.
1827 Write the last batch of output from an ICS server command to a file
1828 (‘comint-write-output’). With a prefix argument, the file is
1829 appended to instead. Any prompt at the end of the output is not
1834 Scroll to display the beginning of the last batch of output at the
1835 top of the window; also move the cursor there
1836 (‘comint-show-output’).
1839 Scroll to put the end of the buffer at the bottom of the window
1840 (‘comint-show-maximum-output’).
1842 ‘M-x comint-truncate-buffer’
1843 This command truncates the ICS buffer to a certain maximum number
1844 of lines, specified by the variable ‘comint-buffer-maximum-size’.
1845 Here’s how to do this automatically each time you get output from
1848 (add-hook 'comint-output-filter-functions
1849 'comint-truncate-buffer)
1851 ICS mode is a derivative of Comint mode, a general-purpose mode for
1852 communicating with interactive subprocesses. Most of the features of
1853 ICS mode actually come from Comint mode, as you can see from the command
1857 File: chess.info, Node: Command History, Next: Seeking an opponent for a new game, Prev: Chess ICS Mode, Up: Internet Chess Servers
1859 6.3 ICS Command History
1860 =======================
1862 ICS buffers support two ways of repeating earlier commands. You can use
1863 keys like those used for the minibuffer history; these work much as they
1864 do in the minibuffer, inserting text from prior commands while point
1865 remains always at the end of the buffer. You can move through the
1866 buffer to previous inputs in their original place, then resubmit them or
1867 copy them to the end.
1871 * ICS Command Ring::
1872 * ICS History Copying::
1875 File: chess.info, Node: ICS Command Ring, Next: ICS History Copying, Prev: Command History, Up: Command History
1877 6.3.1 ICS Command History Ring
1878 ------------------------------
1882 Fetch the next earlier old ICS command.
1886 Fetch the next later old ICS command.
1889 Begin an incremental regexp search of old ICS commands.
1892 Fetch the next subsequent command from the history.
1895 Fetch one argument from an old ICS command.
1898 Display the buffer’s history of ICS commands in another window
1899 (‘comint-dynamic-list-input-ring’).
1901 ICS buffers provide a history of previously entered commands. To
1902 reuse commands from the history, use the editing commands ‘M-p’, ‘M-n’,
1903 ‘M-r’ and ‘M-s’. These work just like the minibuffer history commands
1904 (*note (emacs)Minibuffer History::), except that they operate within the
1905 ICS buffer rather than the minibuffer.
1907 ‘M-p’ fetches an earlier ICS command to the end of the ICS buffer.
1908 Successive use of ‘M-p’ fetches successively earlier commands, each
1909 replacing any text that was already present as potential input. ‘M-n’
1910 does likewise except that it finds successively more recent ICS commands
1911 from the buffer. ‘C-<UP>’ works like ‘M-p’, and ‘C-<DOWN>’ like ‘M-n’.
1913 The history search command ‘M-r’ begins an incremental regular
1914 expression search of previous ICS commands. After typing ‘M-r’, start
1915 typing the desired string or regular expression; the last matching ICS
1916 command will be displayed in the current line. Incremental search
1917 commands have their usual effects—for instance, ‘C-s’ and ‘C-r’ search
1918 forward and backward for the next match (*note (emacs)Incremental
1919 Search::). When you find the desired input, type <RET> to terminate the
1920 search. This puts the input in the command line. Any partial input you
1921 were composing before navigating the history list is restored when you
1922 go to the beginning or end of the history ring.
1924 Often it is useful to reexecute several successive ICS commands that
1925 were previously executed in sequence. To do this, first find and
1926 reexecute the first command of the sequence. Then type ‘C-c C-x’; that
1927 will fetch the following command—the one that follows the command you
1928 just repeated. Then type <RET> to reexecute this command. You can
1929 reexecute several successive commands by typing ‘C-c C-x <RET>’ over and
1932 The command ‘C-c .’ (‘comint-input-previous-argument’) copies an
1933 individual argument from a previous command, like ‘<ESC> .’ in Bash.
1934 The simplest use copies the last argument from the previous ICS command.
1935 With a prefix argument N, it copies the Nth argument instead. Repeating
1936 ‘C-c .’ copies from an earlier ICS command instead, always using the
1937 same value of N (don’t give a prefix argument when you repeat the ‘C-c
1940 These commands get the text of previous ICS commands from a special
1941 history list, not from the ICS buffer itself. Thus, editing the ICS
1942 buffer, or even killing large parts of it, does not affect the history
1943 that these commands access.
1946 File: chess.info, Node: ICS History Copying, Prev: ICS Command Ring, Up: Command History
1948 6.3.2 ICS History Copying
1949 -------------------------
1952 Move point to the previous prompt (‘comint-previous-prompt’).
1955 Move point to the following prompt (‘comint-next-prompt’).
1958 Copy the input command at point, inserting the copy at the end of
1959 the buffer (‘comint-copy-old-input’). This is useful if you move
1960 point back to a previous command. After you copy the command, you
1961 can submit the copy as input with <RET>. If you wish, you can edit
1962 the copy before resubmitting it. If you use this command on an
1963 output line, it copies that line to the end of the buffer.
1966 If ‘comint-use-prompt-regexp’ is ‘nil’ (the default), copy the old
1967 input command that you click on, inserting the copy at the end of
1968 the buffer (‘comint-insert-input’). If ‘comint-use-prompt-regexp’
1969 is non-‘nil’, or if the click is not over old input, just yank as
1972 Moving to a previous input and then copying it with ‘C-c <RET>’ or
1973 ‘Mouse-2’ produces the same results—the same buffer contents—that you
1974 would get by using ‘M-p’ enough times to fetch that previous input from
1975 the history list. However, ‘C-c <RET>’ copies the text from the buffer,
1976 which can be different from what is in the history list if you edit the
1977 input text in the buffer after it has been sent.
1980 File: chess.info, Node: Seeking an opponent for a new game, Next: The sought game display, Prev: Command History, Up: Internet Chess Servers
1982 6.4 Seeking an opponent for a new game
1983 ======================================
1985 After you connected to a server, one of the first things you will want
1986 to do is find an oponent for a new game. You can use the ICS command
1987 "seek" to announce your availability for a chess game to interested
1992 fics% seek 10 10 rated
1994 This will announce your availability to play a rated game with 10
1995 minutes initial time-control for each player, and 10 seconds added for
1999 File: chess.info, Node: The sought game display, Next: Watching other games, Prev: Seeking an opponent for a new game, Up: Internet Chess Servers
2001 6.5 The sought game display
2002 ===========================
2004 There is a special mode for displaying games sought by other users on an
2005 Internet Chess Server. Provided you didn’t turn off seek advertisments
2006 manually (for instance by setting the seek variable to 0 (off) on the
2007 ICS server by issueing "set seek 0"), the first seek advertisment
2008 automatically pops up a new window which is in ‘chess-ics-ads-mode’, a
2009 derivative of ‘tabulated-list-mode’.
2011 -- Function: chess-ics-ads-mode
2012 A mode for displaying ICS game seek advertisments.
2014 This mode runs the hook ‘chess-ics-ads-mode-hook’, as the final
2015 step during initialization.
2019 ? describe-mode RET chess-ics-sought-accept <mouse-2>
2020 chess-ics-sought-accept
2022 In this buffer, use mouse-2 or ‘<RET>’ on a line to accept that
2023 particular game and play it.
2026 File: chess.info, Node: Watching other games, Prev: The sought game display, Up: Internet Chess Servers
2028 6.6 Watching other games
2029 ========================
2031 You can also watch other games currently being played on ICS. Even
2032 services like ‘LectureBot’ from FICS can be used.
2034 fics% observe lecturebot
2035 You are now observing game 5.
2036 Game 5: LectureBot (0) LectureBot (0) unrated untimed 0 0
2038 LectureBot(TD)(----)[5] kibitzes: (Note: A passed pawn is a pawn that
2039 does not have enemy pawns blocking the path either on the
2040 same or adjacent files).
2041 LectureBot(TD)(----)[5] kibitzes: Connected passed pawns are a pain to
2042 have to deal with. They are usually a winning advantage if
2043 they cannot be blockaded. The blockading piece has to give
2044 up duties elsewhere. It's almost like being a piece up.
2045 fics% unobserv lecturebot
2046 Removing game 5 from observation list.
2049 Once you start to observe a particular game or player, the current
2050 position will pop up in a chessboard display. As you are an observer,
2051 you will not be able to enter new moves. However, you should be able to
2052 navigate back and forth in the history of the game.
2054 If a new move is made by any party in the game and you are currently
2055 displaying the last position in the game, the chessboard display will
2056 automaticall update to reflect the new position and show the last move
2060 File: chess.info, Node: Concept Index, Next: Function and Variable Index, Prev: Internet Chess Servers, Up: Top