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
1409 customisable ASCII board diagram display.
1411 This is how the starting position looks in its default configuration:
1425 -- User Option: chess-plain-separate-frame
1426 If non-nil, display the chessboard in its own frame.
1428 -- User Option: chess-plain-border-style
1429 If non-nil, a vector of Characters used to draw borders.
1431 Otherwise, omit to draw any border around the chessboard diagram.
1433 -- User Option: chess-plain-black-square-char
1434 Character used to indicate empty black squares.
1436 -- User Option: chess-plain-white-square-char
1437 Character used to indicate black white squares.
1439 -- User Option: chess-plain-piece-chars
1440 Alist of pieces and their corresponding characters.
1442 -- User Option: chess-plain-upcase-indicates
1443 Defines what a upcase char should indicate. The default is
1444 ‘'color’, meaning a upcase char is a white piece, a lowercase char
1445 a black piece. Possible values: ‘'color’ (default),
1446 ‘'square-color’. If set to ‘'square-color’, a uppercase character
1447 indicates a piece on a black square. (Note that you also need to
1448 modify ‘chess-plain-piece-chars’ to avoid real confusion.)
1450 -- User Option: chess-plain-spacing
1451 Number of spaces between files.
1454 File: chess.info, Node: ICS1 style ASCII displays, Next: Graphical displays, Prev: Plain ASCII diagram displays, Up: Chessboard displays
1456 3.4 ICS1 style ASCII displays
1457 =============================
1459 ‘chess-ics1’ is a more verbose ASCII chessboard display.
1461 This is how the starting position looks with this chessboard display:
1463 +---+---+---+---+---+---+---+---+
1464 8 | r | n | b | q | k | b | n | r |
1465 +---+---+---+---+---+---+---+---+
1466 7 | p | p | p | p | p | p | p | p |
1467 +---+---+---+---+---+---+---+---+
1469 +---+---+---+---+---+---+---+---+
1471 +---+---+---+---+---+---+---+---+
1473 +---+---+---+---+---+---+---+---+
1475 +---+---+---+---+---+---+---+---+
1476 2 | P | P | P | P | P | P | P | P |
1477 +---+---+---+---+---+---+---+---+
1478 1 | R | N | B | Q | K | B | N | R |
1479 +---+---+---+---+---+---+---+---+
1482 -- User Option: chess-ics1-separate-frame
1483 If non-nil, display the chessboard in its own frame.
1486 File: chess.info, Node: Graphical displays, Prev: ICS1 style ASCII displays, Up: Chessboard displays
1488 3.5 Graphical displays
1489 ======================
1491 The graphical chessboard display (‘chess-images’) uses image files to
1492 create a visually appealing chessboard in a buffer.
1494 -- User Option: chess-images-directory
1495 A directory which contains images in XPM format.
1497 If you want to draw your own images, each piece must be named
1498 ‘COLOR-PIECE.xpm’, where COLOR is either black or white, and PIECE
1499 is one of rook, knight, bishop, queen, king or pawn.
1501 The only image format currently supported is XPM.
1504 File: chess.info, Node: Engines, Next: Chess Session, Prev: Chessboard displays, Up: Top
1509 Engines are the representation of an opponent in Chess. THe main type
1510 of engine interfaces with an external chess program. However, there can
1511 be other uses for engine objects, such as providing networked engined
1512 for playing with opponent over different types of transports.
1516 * Common functions::
1527 File: chess.info, Node: Common functions, Next: AI, Prev: Engines, Up: Engines
1529 4.1 Common functions
1530 ====================
1532 -- Function: chess-engine-create module game &optional response-handler
1533 &rest handler-ctor-args
1534 Create a new chess engine MODULE (a symbol) associated with GAME.
1535 Optionally supply a new RESPONSE-HANDLER.
1537 -- Function: chess-engine-set-option engine option value
1538 Set ENGINE OPTION to VALUE by invoking its handler with the
1541 -- Function: chess-engine-position engine
1542 Return the current position of the game associated with ENGINE.
1544 -- Function: chess-engine-command engine event &rest args
1545 Call the handler of ENGINE with EVENT (a symbol) and ARGS.
1547 -- Function: chess-engine-send engine string
1548 Send the given STRING to ENGINE. If ‘chess-engine-process’ is a
1549 valid process object, use ‘process-send-string’ to submit the data.
1550 Otherwise, the ’send event is triggered and the engine event
1551 handler can take care of the data.
1554 File: chess.info, Node: AI, Next: Crafty, Prev: Common functions, Up: Engines
1559 The AI engine module defines a pure Emacs Lisp implementation of an
1560 opponent. Contrary to all other engine modules mentioned later on, it
1561 does not require any external programs to be installed.
1563 To explicitly select this engine as an opponent, use ‘C-u M-x chess
1566 -- User Option: chess-ai-depth
1567 Defines the default search depth for this engine.
1569 -- User Option: chess-ai-quiescence-depth
1570 Defines the number of plies to search for a quiet position. This
1571 is in addition to ‘chess-ai-depth’.
1573 If you’d like to employ the search and evaluation functions provided
1574 by this module programmatically, the following function is the top-level
1577 -- Function: chess-ai-best-move position &optional depth eval-fn
1578 Find the supposedly best move (ply) for POSITION. DEPTH defaults
1579 to the value of ‘chess-ai-depth’.
1582 File: chess.info, Node: Crafty, Next: Fruit, Prev: AI, Up: Engines
1587 "Crafty" is a chess program written by Michael Byrne, UAB professor Dr.
1588 Robert Hyatt, Tracy Riegle, Peter Skinner and Ted Langreck. It is
1589 directly derived from Cray Blitz, winner of the 1983 and 1986 World
1590 Computer Chess Championships.
1592 If the ‘crafty’ program is installed and can be found in the program
1593 search path (‘exec-path’), the ‘chess-crafty’ engine module will
1594 automatically detect it.
1596 If ‘crafty’ is installed in a non-standard location, variable
1597 ‘chess-crafty-path’ can be set to point to the executable.
1599 If you have multiple engines installed you can explicitly select to
1600 play against Crafty by invoking ‘C-u M-x chess <RET> crafty <RET>’.
1603 File: chess.info, Node: Fruit, Next: Glaurung, Prev: Crafty, Up: Engines
1608 "Fruit" is a chess engine developed by Fabien Letouzey. It was
1609 commercially available from September 2005 until July 2007. Now it is
1610 freeware and you can download it for free from
1611 <http://www.fruitchess.com/>. The development on Fruit by Fabien
1612 Letouzey has ceded and it is unlikely to continue.
1614 Fruit was vice world computer chess champion 2005.
1616 If the ‘fruit’ command is installed and can be found in the program
1617 search path (‘exec-path’), the ‘chess-fruit’ engine module will
1618 automatically detect it.
1620 If Fruit is installed in a non-standard location, variable
1621 ‘chess-fruit-path’ can be set to point to the executable.
1623 If you have multiple engines installed you can explicitly select to
1624 play against Fruit by invoking ‘C-u M-x chess <RET> fruit <RET>’.
1627 File: chess.info, Node: Glaurung, Next: GNU Chess, Prev: Fruit, Up: Engines
1632 "Glaurung" is another freely distributed strong computer chess engine.
1634 If the ‘glaurung’ program is installed and can be found in the
1635 program search path (‘exec-path’), the ‘chess-glaurung’ engine module
1636 will automatically detect it.
1638 If Glaurung is installed in a non-standard location, variable
1639 ‘chess-glaurung-path’ can be set to point to the executable.
1641 If you have multiple engines installed you can explicitly select to
1642 play against Glaurung by invoking ‘C-u M-x chess <RET> glaurung <RET>’.
1645 File: chess.info, Node: GNU Chess, Next: Phalanx, Prev: Glaurung, Up: Engines
1650 "GNU Chess" is free software, licensed under the terms of the GNU
1651 General Public License version 3 or any later version, and is maintained
1652 by collaborating developers. As one of the earliest computer chess
1653 programs with full source code available, it’s one of the oldest for
1654 Unix-based systems and has since been ported to many other platforms.
1656 If the ‘gnuChess’ program is installed and can be found in the
1657 program search path (‘exec-path’), the ‘chess-gnuchess’ engine module
1658 will automatically detect it.
1660 If GNU Chess is installed in a non-standard location, variable
1661 ‘chess-gnuchess-path’ can be set to point to the executable.
1663 If you have multiple engines installed you can explicitly select to
1664 play against GNU Chess by invoking .
1667 File: chess.info, Node: Phalanx, Next: Sjeng, Prev: GNU Chess, Up: Engines
1672 "Phalanx" is an old, popular chess engine, with an interesting history.
1674 If the ‘phalanx’ program is installed and can be found in the program
1675 search path (‘exec-path’), the ‘chess-phalanx’ engine module will
1676 automatically detect it.
1678 If Phalanx is installed in a non-standard location, variable
1679 ‘chess-phalanx-path’ can be set to point to the executable.
1681 If you have multiple engines installed you can explicitly select to
1682 play against Phalanx by invoking ‘C-u M-x chess <RET> phalanx <RET>’.
1685 File: chess.info, Node: Sjeng, Next: Stockfish, Prev: Phalanx, Up: Engines
1690 "Sjeng" (http://sjeng.org/) is a championship-winner automated chess
1691 engine developed by Gian-Carlo Pascutto from Belgium. While its
1692 original version was free, recent developments are for sale.
1694 If the ‘sjeng’ program is installed and can be found in the program
1695 search path (‘exec-path’), the ‘chess-sjeng’ engine module will
1696 automatically detect it.
1698 If Sjeng is installed in a non-standard location, variable
1699 ‘chess-sjeng-path’ can be set to point to the executable.
1701 If you have multiple engines installed you can explicitly select to
1702 play against Sjeng by invoking ‘C-u M-x chess <RET> sjeng <RET>’.
1705 File: chess.info, Node: Stockfish, Prev: Sjeng, Up: Engines
1710 "Stockfish" (http://www.stockfishchess.org/) is one of the strongest
1711 chess engines in the world, appearing near or at the top of most chess
1712 engine rating lists. Stockfish is also free software, licensed under
1713 the terms of the GNU General Public License.
1715 If the ‘stockfish’ program is installed and can be found in the
1716 program search path (‘exec-path’), the ‘chess-stockfish’ engine module
1717 will automatically detect it.
1719 If Stockfish is installed in a non-standard location, variable
1720 ‘chess-stockfish-path’ can be set to point to the executable.
1722 If you have multiple engines installed you can explicitly select to
1723 play against Stockfish by invoking ‘C-u M-x chess <RET> stockfish
1727 File: chess.info, Node: Chess Session, Next: Internet Chess Servers, Prev: Engines, Up: Top
1732 A chess session assembles all modules mentioned in previous chapters
1733 into a working system to interact with. A session typically consists of
1734 at least one display module, one engine module, and possibly a number of
1735 optional modules. All these mdoules share a common game object which is
1736 used to keep track of the currently active game.
1738 -- Function: chess engine disable-popup engine-response-handler &rest
1740 Play a game against ENGINE.
1742 This function constructs all the necessary modules required for a
1743 chess session. In particular, it will start ENGINE and create a
1744 chess display as configured in ‘chess-default-display’.
1746 This is the main entry-point for interactively launching a
1747 chessboard display with associated engine.
1749 If you want to launch a chess session as part of your own code, the
1750 probably more expressive alias ‘chess-session’ might be interesting
1753 You can have several active chess sessions. In fact, some features
1754 later described in this manual make use of this, *Note Internet Chess
1758 File: chess.info, Node: Internet Chess Servers, Next: Concept Index, Prev: Chess Session, Up: Top
1760 6 Internet Chess Servers
1761 ************************
1763 Based on the services provided above, there is also a special mode for
1764 communication with Internet Chess Servers.
1766 On an Internet Chess Server you can seek to play against other human
1767 or computer players, observe other games being player or examined, play
1768 tournaments, chat with fellow chess players, participate in team games,
1769 or do various other interesting chess related things.
1771 A default set of well known servers is defined in the following
1774 -- Variable: chess-ics-server-list
1775 A list of servers to connect to. The format of each entry is:
1777 (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER
1780 Internet Chess Servers based on FICS (Free Internet Chess Server)
1781 (http://www.freechess.org/) and ICC (Internet Chess Club)
1782 (http://www.chessclub.com/) are currently supported.
1786 * Connecting to a server::
1789 * Seeking an opponent for a new game::
1790 * The sought game display::
1791 * Watching other games::
1794 File: chess.info, Node: Connecting to a server, Next: Chess ICS Mode, Prev: Internet Chess Servers, Up: Internet Chess Servers
1796 6.1 Connecting to a server
1797 ==========================
1799 To open a new connection to an Internet Chess Server, use:
1801 -- Function: chess-ics server port &optional handle
1802 password-or-filename helper &rest helper-args
1803 Connect to an Internet Chess Server.
1805 If called interactively, you will be prompted to enter a server
1806 (from ‘chess-ics-server-list’ and possibly identification
1810 File: chess.info, Node: Chess ICS Mode, Next: Command History, Prev: Connecting to a server, Up: Internet Chess Servers
1815 The major mode for ICS buffers is Chess ICS mode. Many of its special
1816 commands are bound to the ‘C-c’ prefix. Here is a list of ICS mode
1820 Send the current line as input to the server (‘comint-send-input’).
1821 Any prompt at the beginning of the line is omitted. If point is at
1822 the end of buffer, this is like submitting the command line in an
1823 ordinary interactive shell. However, you can also invoke <RET>
1824 elsewhere in the ICS buffer to submit the current line as input.
1827 Either delete a character or send EOF (End Of File)
1828 (‘comint-delchar-or-maybe-eof’). Typed at the end of the ICS
1829 buffer, this sends EOF to the server and terminates the connection.
1830 Typed at any other position in the buffer, this deletes a character
1834 Move to the beginning of the line, but after the prompt if any
1835 (‘comint-bol-or-process-mark’). If you repeat this command twice
1836 in a row, the second time it moves back to the process mark, which
1837 is the beginning of the input that you have not yet sent to the
1838 server. (Normally that is the same place—the end of the prompt on
1839 this line—but after ‘C-c <SPC>’ the process mark may be in a
1843 Accumulate multiple lines of input, then send them together
1844 (‘comint-accumulate’). This command inserts a newline before
1845 point, but does not send the preceding text as input to the
1846 server—at least, not yet. Both lines, the one before this newline
1847 and the one after, will be sent together (along with the newline
1848 that separates them), when you type <RET>.
1851 Kill all text pending at end of buffer to be sent as input
1852 (‘comint-kill-input’). If point is not at end of buffer, this only
1853 kills the part of this text that precedes point.
1856 Kill a word before point (‘backward-kill-word’).
1859 Delete the last batch of output from an ICS server command
1860 (‘comint-delete-output’). This is useful if a server command spews
1861 out lots of output that just gets in the way.
1864 Write the last batch of output from an ICS server command to a file
1865 (‘comint-write-output’). With a prefix argument, the file is
1866 appended to instead. Any prompt at the end of the output is not
1871 Scroll to display the beginning of the last batch of output at the
1872 top of the window; also move the cursor there
1873 (‘comint-show-output’).
1876 Scroll to put the end of the buffer at the bottom of the window
1877 (‘comint-show-maximum-output’).
1879 ‘M-x comint-truncate-buffer’
1880 This command truncates the ICS buffer to a certain maximum number
1881 of lines, specified by the variable ‘comint-buffer-maximum-size’.
1882 Here’s how to do this automatically each time you get output from
1885 (add-hook 'comint-output-filter-functions
1886 'comint-truncate-buffer)
1888 ICS mode is a derivative of Comint mode, a general-purpose mode for
1889 communicating with interactive subprocesses. Most of the features of
1890 ICS mode actually come from Comint mode, as you can see from the command
1894 File: chess.info, Node: Command History, Next: Seeking an opponent for a new game, Prev: Chess ICS Mode, Up: Internet Chess Servers
1896 6.3 ICS Command History
1897 =======================
1899 ICS buffers support two ways of repeating earlier commands. You can use
1900 keys like those used for the minibuffer history; these work much as they
1901 do in the minibuffer, inserting text from prior commands while point
1902 remains always at the end of the buffer. You can move through the
1903 buffer to previous inputs in their original place, then resubmit them or
1904 copy them to the end.
1908 * ICS Command Ring::
1909 * ICS History Copying::
1912 File: chess.info, Node: ICS Command Ring, Next: ICS History Copying, Prev: Command History, Up: Command History
1914 6.3.1 ICS Command History Ring
1915 ------------------------------
1919 Fetch the next earlier old ICS command.
1923 Fetch the next later old ICS command.
1926 Begin an incremental regexp search of old ICS commands.
1929 Fetch the next subsequent command from the history.
1932 Fetch one argument from an old ICS command.
1935 Display the buffer’s history of ICS commands in another window
1936 (‘comint-dynamic-list-input-ring’).
1938 ICS buffers provide a history of previously entered commands. To
1939 reuse commands from the history, use the editing commands ‘M-p’, ‘M-n’,
1940 ‘M-r’ and ‘M-s’. These work just like the minibuffer history commands
1941 (*note (emacs)Minibuffer History::), except that they operate within the
1942 ICS buffer rather than the minibuffer.
1944 ‘M-p’ fetches an earlier ICS command to the end of the ICS buffer.
1945 Successive use of ‘M-p’ fetches successively earlier commands, each
1946 replacing any text that was already present as potential input. ‘M-n’
1947 does likewise except that it finds successively more recent ICS commands
1948 from the buffer. ‘C-<UP>’ works like ‘M-p’, and ‘C-<DOWN>’ like ‘M-n’.
1950 The history search command ‘M-r’ begins an incremental regular
1951 expression search of previous ICS commands. After typing ‘M-r’, start
1952 typing the desired string or regular expression; the last matching ICS
1953 command will be displayed in the current line. Incremental search
1954 commands have their usual effects—for instance, ‘C-s’ and ‘C-r’ search
1955 forward and backward for the next match (*note (emacs)Incremental
1956 Search::). When you find the desired input, type <RET> to terminate the
1957 search. This puts the input in the command line. Any partial input you
1958 were composing before navigating the history list is restored when you
1959 go to the beginning or end of the history ring.
1961 Often it is useful to reexecute several successive ICS commands that
1962 were previously executed in sequence. To do this, first find and
1963 reexecute the first command of the sequence. Then type ‘C-c C-x’; that
1964 will fetch the following command—the one that follows the command you
1965 just repeated. Then type <RET> to reexecute this command. You can
1966 reexecute several successive commands by typing ‘C-c C-x <RET>’ over and
1969 The command ‘C-c .’ (‘comint-input-previous-argument’) copies an
1970 individual argument from a previous command, like ‘<ESC> .’ in Bash.
1971 The simplest use copies the last argument from the previous ICS command.
1972 With a prefix argument N, it copies the Nth argument instead. Repeating
1973 ‘C-c .’ copies from an earlier ICS command instead, always using the
1974 same value of N (don’t give a prefix argument when you repeat the ‘C-c
1977 These commands get the text of previous ICS commands from a special
1978 history list, not from the ICS buffer itself. Thus, editing the ICS
1979 buffer, or even killing large parts of it, does not affect the history
1980 that these commands access.
1983 File: chess.info, Node: ICS History Copying, Prev: ICS Command Ring, Up: Command History
1985 6.3.2 ICS History Copying
1986 -------------------------
1989 Move point to the previous prompt (‘comint-previous-prompt’).
1992 Move point to the following prompt (‘comint-next-prompt’).
1995 Copy the input command at point, inserting the copy at the end of
1996 the buffer (‘comint-copy-old-input’). This is useful if you move
1997 point back to a previous command. After you copy the command, you
1998 can submit the copy as input with <RET>. If you wish, you can edit
1999 the copy before resubmitting it. If you use this command on an
2000 output line, it copies that line to the end of the buffer.
2003 If ‘comint-use-prompt-regexp’ is ‘nil’ (the default), copy the old
2004 input command that you click on, inserting the copy at the end of
2005 the buffer (‘comint-insert-input’). If ‘comint-use-prompt-regexp’
2006 is non-‘nil’, or if the click is not over old input, just yank as
2009 Moving to a previous input and then copying it with ‘C-c <RET>’ or
2010 ‘Mouse-2’ produces the same results—the same buffer contents—that you
2011 would get by using ‘M-p’ enough times to fetch that previous input from
2012 the history list. However, ‘C-c <RET>’ copies the text from the buffer,
2013 which can be different from what is in the history list if you edit the
2014 input text in the buffer after it has been sent.
2017 File: chess.info, Node: Seeking an opponent for a new game, Next: The sought game display, Prev: Command History, Up: Internet Chess Servers
2019 6.4 Seeking an opponent for a new game
2020 ======================================
2022 After you connected to a server, one of the first things you will want
2023 to do is find an oponent for a new game. You can use the ICS command
2024 "seek" to announce your availability for a chess game to interested
2029 fics% seek 10 10 rated
2031 This will announce your availability to play a rated game with 10
2032 minutes initial time-control for each player, and 10 seconds added for
2036 File: chess.info, Node: The sought game display, Next: Watching other games, Prev: Seeking an opponent for a new game, Up: Internet Chess Servers
2038 6.5 The sought game display
2039 ===========================
2041 There is a special mode for displaying games sought by other users on an
2042 Internet Chess Server. Provided you didn’t turn off seek advertisments
2043 manually (for instance by setting the seek variable to 0 (off) on the
2044 ICS server by issueing "set seek 0"), the first seek advertisment
2045 automatically pops up a new window which is in ‘chess-ics-ads-mode’, a
2046 derivative of ‘tabulated-list-mode’.
2048 -- Function: chess-ics-ads-mode
2049 A mode for displaying ICS game seek advertisments.
2051 This mode runs the hook ‘chess-ics-ads-mode-hook’, as the final
2052 step during initialization.
2056 ? describe-mode RET chess-ics-sought-accept <mouse-2>
2057 chess-ics-sought-accept
2059 In this buffer, use mouse-2 or ‘<RET>’ on a line to accept that
2060 particular game and play it.
2063 File: chess.info, Node: Watching other games, Prev: The sought game display, Up: Internet Chess Servers
2065 6.6 Watching other games
2066 ========================
2068 You can also watch other games currently being played on ICS. Even
2069 services like ‘LectureBot’ from FICS can be used.
2071 fics% observe lecturebot
2072 You are now observing game 5.
2073 Game 5: LectureBot (0) LectureBot (0) unrated untimed 0 0
2075 LectureBot(TD)(----)[5] kibitzes: (Note: A passed pawn is a pawn that
2076 does not have enemy pawns blocking the path either on the
2077 same or adjacent files).
2078 LectureBot(TD)(----)[5] kibitzes: Connected passed pawns are a pain to
2079 have to deal with. They are usually a winning advantage if
2080 they cannot be blockaded. The blockading piece has to give
2081 up duties elsewhere. It's almost like being a piece up.
2082 fics% unobserv lecturebot
2083 Removing game 5 from observation list.
2086 Once you start to observe a particular game or player, the current
2087 position will pop up in a chessboard display. As you are an observer,
2088 you will not be able to enter new moves. However, you should be able to
2089 navigate back and forth in the history of the game.
2091 If a new move is made by any party in the game and you are currently
2092 displaying the last position in the game, the chessboard display will
2093 automaticall update to reflect the new position and show the last move
2097 File: chess.info, Node: Concept Index, Next: Function and Variable Index, Prev: Internet Chess Servers, Up: Top