Make your own free website on Tripod.com

Screamer Readme File

Release: Screamer 1.0, build 48
Date: 01/2000

Introduction

Screamer is a Macintosh based chess engine and interface (PPC and 68k) developed over several
years as a hobby. It is continually under development and new versions should appear
intermittently. It is released as freeware but is copyrighted with all rights reserved. Please
feel free to contact me for questions or concerns.

William
wbryant@ix.netcom.com

Overview
Features
Screamer Chess Engine
Macintosh Chess Interface
Commands and Menu Options
Chess Board Window
Screen and File Logs
Test Positions (FEN/EPD) and Test Suite Files
System Requirements
Known Limitations and Bugs
Future Directions
Contact Information, Credits, and Resources
Legal Stuff

Features
*Fully functional chess engine that plays legal chess including castling, en-passant, and
recognized standard draw positions including draw by 3 fold repetition, draw by
insufficient material, draw by 50 move rule.
*Unlimited move take back.
This is ability to take back all moves up to the initial move made by a player or the
computers.
*Variable hash table support from 512kb to 40Mb.
*Intuitive Click and Drag -or- Point and Click piece movement.
*Fully scriptable interface and support for AppleEvents.
*Exachess 2.x and Exachess Lite 2.x chess database compatibility.
Simply place Screamer or an alias to Screamer in the Exachess:Tools:Engines folder
and select Screamer in the engines dialog. (See Exachess in Resources section)

Screamer Engine v.1.00, build 48
The engine is written in ANSI C++ with no (or very limited) use of Macintosh specific functions.
All interactions with MacOS is via a standard interface below.
*Negamax version of alpha, beta search
*PVS with aspiration windows
*Recursive Null Move
*Variable size hash table support
*Limited pawn hash table support

Current Test Suite Scores (1/10/2000, Macintosh G3/266mhz):
WAC 290/300 at 1 minute
Score Score(USCF)
CCR Test Suite 18/25 2330 2510
LCT II 20/30 2360 2540
BT2630 21/30 2325 2505
Average Score: 2338 2518

Macintosh Chess Interface
The interface was created using Metrowerks Codewarrior and Powerplant. Through the use of a
standard set of functions and call back routines, all Mac specific functionality has been
isolated in the interface. This should allow the interface to be compiled with other C,
C++ chess engines that support its protocol.

The interface provides support for standard MacOS interface elements, AppleEvents, and is
fully scriptable. It does not (yet) support navigation services or printing but these are on
the list of things to do.

Commands and Menu Options

Apple Menu
About...
The about box for Screamer with basic overview, credits, and contact information.

File Menu
New
Resets the game window to a new game, flushes the hash table, and resets the move list.
It also set the computer to off. This command is not undoable.

Run Test File
This opens a file called "EPD Test File" and runs the resulting positions sequentially,
placing the analysis in the log file and (if open) the screen log. The test file must be
in the same folder as Screamer.

See the section ' Test Positions (FEN/EPD) and Test Suite Files' for a description of
the file format used for creating your own test files.

I plan to add navigation services support and a standard dialog in the future, to make
selecting test files easier. (See Future Directions). For now, rename your test file
"EPD Test File". A sample file has been provided.

Quit
This exits Screamer.
Note: Screamer will not exit until the current search is complete. To halt the search
early Type <command-period> while the game window is selected or select <Stop Search>
from the Game menu.

Edit Menu
The standard edit menu options work as expected in all text windows and dialogs.

When the game window is selected and active, the edit menu commands have the following
effects:

Copy <command-c>
copies the current board position in the form of an EPD string into the clipboard.

Paste <command-v>
Calls up the 'Set EPD/FEN dialog'. Selecting Paste again (typing <command-v> again)
will place a EPD/FEN string into the dialog box were it can be used to set up the current
board position.

Note: There is a memory fault when pasting the position directly into the board from the
clipboard without going through the dialog box. I am working on this. Sorry for the
additional step at this time. Wm.

Undo <command-z>
This takes back the last move and sets the computer side to off. To have the computer
resume playing select 'Go' from the game menu, or type <command-g>.

Game Menu
Go (Computer to Move ...) <command-g>
This sets the computer to search the current position and to play subsequent moves
for which ever side is on move at the time go is selected.

Computer Off
This set the computer to off and it will not move for either side until reset.
Note: Taking back a move automatically sets the computer to the off position.

List Moves
This outputs a complete list of the moves of the current game to the log file/files.
It also prints a text representation of the current board position.

Clear Hash Table
This manually clears all the entries in the hash table by setting the entries to invalid
and removes any bestmove data.

Get Position
This command places an EPD string describing the current position into the log file and
screen log when open. To place the EPD string into the clipboard simply highlight it
from the log and select copy. A shortcut is to simply select the board window
and select copy which will automatically place the EPD string into the clipboard.
(select the game window and type <command-c>).

Set Position

This command brings up a copy of the current board in the Set Position dialog for editing.
The board can be cleared or set to a new game with the appropriate buttons at the bottom
of the dialog. Select the piece buttons and arrange the board as desired. To set the
ep square, select the ep button and click on the square desired.

The default is no castling rights, no ep square, and white to move. These can also be
set in the dialog.

Note: if the resulting position is illegal, Screamer will beep and display a message in
the screen log explaining why the position is illegal. In that case, the board remains
unchanged.

Set EPD/FEN position

This command brings up a simple dialog window with an editable text box to allow a position
in EPD notation to be typed or pasted into the window.

There are several shortcuts:
When the game window is active, selecting 'Paste' from the edit menu (or typing)
<command-v> will bring up the dialog window.

When the dialog is displayed typing <command-v> again will paste an EPD string
from the clipboard into the text dialog.

Enter or Return can be used to trigger the default 'Set Pos' button.
Escape can be used to trigger the 'Cancel' button.

Note: if the resulting position is illegal, Screamer will beep and display a message in
the screen log explaining why the position is illegal. In that case, the board
remains unchanged. A carriage return as the leading character of a pasted EPD string will
cause Screamer to consider the string invalid.

Search Menu
This menu is designed for you to select the depth or time for the computer to search each position.
An option to search for mate will be added in the future, but is disabled at present.

Depth Search
This allows you specify how deep you want to computer to search in plies. (a ply is
a half-move). The computer will search to this depth regardless of the time required.
The search can be stopped by typing <command-.> with the game window active or by selecting
'Stop Search' in the Game menu.

Time Search
This allows you to specify how long you want the computer to search.
The computer will search until this amount of time has expired, and report the last
completed ply and its principal variation. You can set the time to MaxTime
(approximately 24 hours).
The search can be stopped by typing <command-.> with the game window active or by selecting
'Stop Search' in the Game menu.

Mate
This searches the current position looking for checkmate in the specified depth.
IT IS NOT YET IMPLEMENTED.

Options Menu
Output Logs
Log to Screen
Log to File
This enables / disables search output and player moves to the respective log files.
By default, the log file is opened at startup and closes at exit. Turning off the log
to file does not close the log, just suspends output until enabled or exit.

Piece Movement
Point & Click
Click & Drag
This lets you toggle between click_and_drag and point_and_click piece movement.
Click_and_drag is the default. Changes are not saved upon exit.

Piece Sets

This lets you toggle between the default set of pieces that I created, and Richard Fowell's
American set of pieces. Changes are not saved upon exit.

Enable Audible Move Alarm/Disable Audible Move Alarm

This option, when enabled, sends a brief system beep when the computer makes a move.

Chess Board Window

The main chess board window consists of the chess board and pieces, engine messages, side to
move information, and search information.

The pieces on the board itself are movable when the engine in not searching by either
clicking on a piece and dragging it to a new square, or by clicking on a piece and then
clicking on a square. Dragging is the default. Piece movement can be changed in the Options
menu. Only pieces for the side on move can be selected and moved. Attempting to move a piece
of the wrong color results in a warning beep from the interface.

Above the board on the right and left corners are the words 'White' and 'Black'. The side to
move is indicated by a black box around it. The computer side is indicated by a small black
dot to the right of the side that the computer is playing.

The message window sits in the middle above the board, and usually echo's the move number
and side to move. 'Move 1 B' indicates that it is the first move, black is on move.
Other messages from the chess engine, include checkmate and stalemate notification and illegal
move notification, are displayed here as well.

The right half of the window is the search information, which is blank until the engine searches
a position.
The top half displays search statistics while the bottom half shows the current
principal variation up to 32 ply (16 full moves).
PV Move is the move that is currently considered the best move, and is the move to be played
if the search ended immediately.
Score is the current evaluation score of the PV move in centipawns (1/100 of a pawn).
Depth is the current depth of the search. It has 3 components:
1. Ply Depth (a ply is the half-move count)
2. Root move number (the current root move being considered)
3. Root move notation (the short algebraic notation for the move being considered)
This move may or may not end up being the best move and may or may not end up in the PV
move window.
For example: 21/0 KB1 means the search is on the 21st ply, searching the initial root
move which is Knight to f3.
Note: the root moves start at 0, not at 1.
Nodes is the current number of total nodes searched.
NPS is nodes per second, or the current speed of the search. This number will vary from machine
to machine. At present, I get approximately 50,000 nps on opening and middle game positions,
rising to 110,000 nps on end game positions on my G3/266mhz machine.

Screen and File Logs

Screamer maintains two log files that provide a running summary of the game and the current search.

The log file is found in the same directory as the Screamer application itself. Log files are
numbered sequentially and have a black pawn as their icon. These are text files and can be
viewed with any text editor or word processor (including Simple Text).

The screen log is identical to the log file but appears just below the game window. It is
movable and resizable and can be placed where you wish. Screamer will not, at present,
remember any changes to this window and it will again be placed in the startup position when
the program is relaunched. This is an editable text window and analysis and EPD position
strings can be selected and copied to the clipboard and other applications. Any information
pasted into this window will not affect the Screamer engine. This window is not saved on exit
(the information is available in the log file.)

The default is for the log file to be active, and the screen log to be inactive.
These can be changed in the Options menu. A check mark beside each file name says that this file is
active. Screamer does not currently remember changes to the defaults when the program is
relaunched.

Test Positions (FEN/EPD) and Test Suite Files

To set up the board and enter a test position, select 'Set Position' from the Game menu to bring
up the Set Position dialog. The Set Position board is initially set to the current game board.
It can be cleared or set to a new game with the appropriate buttons at the bottom of the dialog.
Select the piece buttons and arrange the board as desired. The default is no castling rights,
no ep square, and white to move. These can also be set in the dialog. To set the ep square,
select the ep button and click on the square desired.
Note: if the resulting position is illegal, Screamer will beep and display a message in the
screen log explaining why the position is illegal. In that case, the board remains unchanged.

To extract an EPD string from the current board position, make sure the board window is the
active window, and type <command-c> (the standard copy command). This will place a EPD string
describing the current board position into the clip board where it can be pasted into any program
that can access the clipboard.

To set the board to an EPD string , copy the string into the clipboard from any source and then
select the game window to make it active. Select 'Set EPD/FEN Position' from the game menu or
alternatively type <command-v> (the standard paste command) to bring up the Set EPD/FEN dialog.
With the dialog active, type <command-v> (paste) to place the string into the dialog. The either click
the SetPos or Cancel buttons. SetPos is default and can be selected by typing <return> or <enter>.
Cancel can be selected by typing escape.
Note: if the resulting position is illegal, Screamer will beep and display a message in the
screen log explaining why the position is illegal. In that case, the board remains unchanged.

One or more EPD strings can also be entered from a file. At present this file must be called
"EPD Test File" and must be in the same folder and location as the Screamer application itself.
(See the 'Run Test File' menu command above). The positions are searched sequentially at the
current search depth/time until each position has been searched and the end of the file has been
reached. This file should have the filetype "TEXT".

The format for the EPD file is as follows:
1. Each position is on its own line following the EPD/FEN standard notation.
2. Blank lines are permitted and ignored
3. To enter comments into the file, begin each comment line with a double slash
'//' (C++ style comment). This line will then be ignored when interpreting this file.
4. To allow for variable times when searching several test sets within the same file, or to
set the time automatically for a test set or position, the following command can be
placed in the file on its own line prior to the positions to be searched.
#tc=SSS
Where '#tc=' tells Screamer that this is a command to set the _time_control_ to the
value following the command. 'SSS' is the total search time for each position in
seconds.
Example: #tc=600 means search for 600 seconds (10 minutes).
This search time is used for all positions until reset by another #tc= command.
5. A sample "EPD Test File" is supplied with the Screamer distribution.

System Requirements

Any PPC Macintosh with System 8.5 or greater. It has not been tested with OS9 yet.
5 Mb of physical ram or greater. For best performance, turn virtual memory off.
Maximum memory is approximately 45 Mb.

<THIS HAS BEEN FIXED>
Note: There is a library linking bug that prevents Screamer from running on an OS older than
8.5. This should be fixed in a later release. That will allow the release of a 68k version
as well.

A 68k version is available on the web site.

Known Limitations and Bugs

Stopping a test file early.
There is no command yet that stops a test file early. (See Future Directions)
Typing <command-period> halts the current search, advancing the file to the next position.
This can be done repeatedly until the all the positions have been halted.
For a long file, this may become quite tedious.

Alternatively, by selecting the screen log window (enable it in the options menu if it
is not on the screen) and then typing <command-period> will cause Screamer to immediately
Quit. The analysis up to this point is saved in the log file.

Future Directions

Add opening book and endgame tablebase support.
Add PGN file support.
Add Printing support.
Add Navigation Services for file and EPD Test File Support.
Fix the memory fault problem to allow direct pasting of FEN/EPD positions into the
game window.
Add the option for a Mate search (and enable the option in the search menu).
Add preference data to remember board setup and position, and search settings.

Contact Information, Credits, and Resources

Screamer Chess Web Site
http://pweb.netcom.com/~wbryant/screamer.html
For questions, concerns, feature requests or bug reports...
Contact me at: wbryant@ix.netcom.com

For general information and discussion of computer chess,
Try Computer Chess Club, a free web based discussion board at: http://www.icdchess.com/ccc
The service is free, but moderated and requires a valid email address and registration.

For computer chess source code try:
Tom's Simple Chess Program (TSCP):
E-mail: Thomas.Kerrigan@Colorado.EDU
http://ucsu.colorado.edu/~kerrigat/

For a more mature and complete chess program source code try:
Crafty: ftp:// ftp.cis.uab.edu/pub/hyatt/

For Information on Exachess / Exachess Lite look at:
http://www.exachess.com/

Exachess Interface: 'CHES' Apple Event Suite
Rolf Exner at www.exachess.com
Used with permission

American Chess Piece Set
Copyright Richard Fowell
"Richard A. Fowell" <fowell@netcom.com>
Used with permission

Powerplant application framework
Copyright Metrowerks Corportation
http://www.metrowerks.com

For information on other Macintosh chess software,
see the Macintosh Chess Software Index:
http://dmoz.org/Games/Board_Games/Chess/Software/Macintosh/


Legal Stuff

This program is freeware.
It is not in the public domain. I retain the copyright to all parts of the program not
copyrighted by others as credited in this document.

The black and white chess pieces are copyrighted by me and may be used with permission in other
programs with appropriate credit and copyright notification.

This program is provided as is without any expressed or implied warranties.

Use at your own risk.

Have fun.

William
wbryant@ix.netcom.com


Original file name: Screamer 1.0 _ReadMe_ - converted on Thursday, 10 February 2000, 01:51

This page was created using TextToHTML. TextToHTML is a free software for Macintosh and is (c) 1995,1996 by Kris Coppieters