GlkChess
--------

GlkChess is a chess playing program built around the Inform MSCP engine.  It
offers a complete graphical playing interface, handled totally through a
single Glk graphical window.  See the file

	glkchess.gif

for an example screenshot.


Graphical interface
-------------------

The GUI for GlkChess should be fairly obvious.  In case it's not, however,
and to explain one or two less obvious features, here are a few notes:

- General -

GlkChess looks best in a Glulx window of around 640x480.  Minimum window
size is around 576x352.  Any smaller than this and parts of the GUI will not
be visible.

GlkChess stresses the Glk event mechanism.  In particular, resizing the
window can cause a blizzard of GUI repainting, which may be slow.  In
general, it's best to avoid resizing too much, and to do it quickly and
decisively when necessary.  Xglk can also fail to completely draw window
borders after a resize.  In this case Ctrl-L is your friend; use it to
redraw the display correctly.

The button presses are only simulation.  Glk does not offer mouse-down and
mouse-up events, only mouse-press events, so the press-release effect is
constructed with Glk timers.

The graphical interface needs the interpreter to provide graphics, image
drawing, mouse event input, and timers.  Unless it's a character mode Glulx
interpreter, it's likely to offer these features.  If you're using an
interpreter that doesn't have all of these, GlkChess will tell you.

- The board -

This is displayed on the left half of the GUI, and is oriented so that your
pieces always play upwards (a normal orientation for a chess playing
program).

To move a piece, first select the piece by clicking on it.  If it is a valid
piece (that is, one of your's and not GlkChess's), the board outlines the
piece in red.  Now click the target square.  This may be either an empty
square, or a square to capture on.  If the move is valid, the board also
outlines the target square.  If you select a piece to move and then change
your mind, click the piece a second time to cancel the selection.

Once you make a move, by selecting a valid target square, GlkChess will make
its reply move.  The board generally outlines the last move made, either
your's or GlkChess's.

- Moves -

Above the control buttons, which appear to the right of the board, GlkChess
displays the two last white and black moves in standard algebraic notation.
These are blank if no moves have yet been made.

- Busy... -

This button appears while GlkChess is considering a move, alongside the last
move for the colour that GlkChess is playing.  While it's displayed, it's
the only button on the GUI that can be pressed -- all others are disabled
while GlkChess is evaluating moves.

Press it to force GlkChess to make the current best move (which may not be
all that good).  This terminates long searches, and is the moral equivalent,
in chess terms, of beating an opponent over the head until they make a move
out of frustration.

Because GlkChess is very busy at this point, you may need a little patience
with the Busy... button.

- White/Black -

This is a pair of "radio buttons", allowing you to choose which colour you
are playing by clicking on the relevant button.  If you switch in mid-game,
GlkChess will take over your position.  This can be handy if you start to
lose badly.

- Undo -

This button takes back a pair of moves: your last one, and GlkChess's
response.

- 1/2/3/4/5/6/7/8 -

These radio buttons select the play level, with 1 being easiest and 8
hardest.  Click on the level button to set it.  At lower levels, GlkChess
makes moves quickly, but does not play as strongly as at higher levels,
where move selection takes longer.

- Save, Load -

These buttons let you save and restore games.  The function is limited to a
single file, called GLKCHESS.PGN, partly because the GlkChess GUI doesn't
work well with Glk's file selection methods.  Clicking Save will save the
current game position into the file GLKCHESS.PGN, overwriting any existing
GLKCHESS.PGN file.

Clicking Load will restore the position saved in the GLKCHESS.PGN file, if
any.  Just in case you meant to save the current game before doing this,
GlkChess will back it up into GLKCHESS.BAK just before loading, so there's
usually a way to recover a board position accidentally lost by Load.

GlkChess saves games in PGN file format.  PGN is "Portable Game Notation", a
standard used by most current chess playing programs.  Games saved with
GlkChess can be loaded into Xboard (and probably Winboard).  Games saved
with Xboard (and again, probably Winboard) can also be loaded into
GlkChess.  Some chess puzzle position PGN files can also be loaded into
GlkChess.

PGN files are ASCII text, and can be edited.  GlkChess recognizes both the
FEN header and the moves list of a PGN file.  The PGN specification actually
describes two PGN formats: output format, and input format.  Output format
is more structured, and is intended for programs to save games.  Input format
is lax, and geared to manually created PGN files.

A complete PGN parser would be slow and difficult for GlkChess, so it uses a
smaller parser, and as a result is happier with output format PGN, though it
can cope with a few deviations from strict output format.

For speed, GlkChess saves backed up board positions into GLKCHESS.BAK in a
"degenerate" form of PGN file.  Here, it saves only the current board
position, as a PGN "FEN" header field.  This is enough for the game position
to be restored if necessary, but the moves history, present in GLKCHESS.PGN,
is lost in GLKCHESS.BAK backups.

- New -

This button starts a new game.  The current game in progress is saved into
GLKCHESS.BAK for safety.

- Quit -

Stops the game, and exits to the interpreter.  Since there's no "Are you
sure?" confirmation, the current game in progress is saved into GLKCHESS.BAK
for safety.  An interpreter may display something like "Hit any key to exit"
on Quit.


Character interface
-------------------

If your interpreter lacks any of graphics, image drawing, mouse input, or
timers, GlkChess will display in Xboard mode instead of using a GUI.  This
is useful for testing Inform MSCP with a simple interpreter, or for use with
Xboard or Winboard.

If you don't have a graphical Glulxe, take a look at glkchess.gif to see
what you would get if you had one.


Acknowledgments
---------------

GlkChess relies on a lot of code and tools from elsewhere, and thanks are
due to:

	o Marcel van Kervinck, for the MSCP chess engine.
	o Andrew Plotkin, for Glulx, the glulxe interpreters, and the Inform
	  Glulx compiler.
	o Graham Nelson, for designing Inform with enough features to make
	  this whole thing possible.
	o Evin Robertson, for blorbtar.
	o "Anonymous", for the chess piece designs.  Traditional, but easy to
	  recognize and use.


--

Simon Baldwin <simon_baldwin@yahoo.com>
10th Sept 2003
