                                  PANDA-glGo 1.4
                                  --------------

                  A 3D and 2D Goban, SGF editor, client for
                    IGS-PandaNet and interface for GNU Go.

Table of Content

(A) Requirements
(B) Usage
(C) GNU Go / GTP
(D) Saving the configuration
(E) Known problems
(F) How to use own images and sounds
(G) Technical informations
(H) The Playermanager
(I) Copyright


(A) REQUIREMENTS

-------------------------------------------------------------------------------
       ! If you use the OpenGL board you will not have much fun without
                      a proper 3D hardware driver !
-------------------------------------------------------------------------------

The goban display is available in two modes: 3D based on OpenGL and 2D based on
SDL. The SDL 2D board is pretty much looking the same as the gGo/Java
board. Some users might not have a graphic card with OpenGL support (but those
must be very old, any consumer card sold after 1998 supports OpenGL) or prefer
the classic 2D view, so the 2D mode might be an alternative. The default view is
the 2D board.
You can switch between 3D and 2D board display in the preferences dialog.

If you have a proper 3D graphiccard, make sure you have some recent driver from
your hardware manufactorer installed. The default drivers that come with Windows
do *NOT* work well.

The most common consumer cards should be from NVidia or ATI, all of them will
work properly with glGo if you have a NVIdia or ATI driver installed. Be careful
with NVidia, there will be two drivers available for "NVidia Riva TNT" card in
the Windows driver selection: One from Microsoft and one from NVidia. Use the
NVidia one, the Microsoft driver is useless.

If you run Linux and don't have a hardware driver installed, the Mesa libraries
might work, but will be inferior to a real driver. There are both NVidia and ATI
drivers for Linux available (my old NVidia TNT 1 card works fine with the latest
NVidia/Linux driver).

The OpenGL mode won't work well without a hardware driver installed. It will be
slow and ugly. I am aware this is a serious limitation to the program. Most
gamers have those drivers up to date, but the average IGS user is no computer
gamer and certainly will have the default Microsoft Windows drivers installed,
which won't work with glGo.

The glGo sound system is based on the OpenAL or SDL mixer libraries. Both are
available and can be selected from the preferences dialog. OpenAL is the default
system and basically superior. Both OpenAL and SDL_mixer runtime support are
provided with the glGo Windows installer. On Linux you need to install OpenAL
and/or SDL mixer from your distribution, it is not included in the glGo installer.

The SDL board requires the SDL, SDL_image, SDL_ttf and SDL_gfx libraries. They
are all included in the Windows installer, on Windows you don't need anything
additional. On Linux you require libsdl, libsdl_ttf and libsdl_image, which skip
with all major Linux distributions. It does not make sense to include the SDL
runtime libraries on Linux as they are all available with your distribution
already.

glGo requires the Python runtime library which is included in the Windows
installer. Linux users please install Python 2.4 from your distribution. To find
out if and which Python version is installed type "python" in a terminal, the
version is shown there.

On Mac OS X 10.3 "Panther" glGo runs out of the box. The current status of glGo
on OS X 10.4 "Tiger" is unknown to me until I upgraded to Tiger myself.


(B) USAGE

Start glGo on Windows either using the desktop or the startmenu icon. On Linux
type "glGo" in a shell.

There are two different board displays available: The 3D board based on OpenGL
and a 2D board based on SDL. To switch between both types use the "Board type"
selection in the preferences dialog. All newly opened boards will use this set
type (the current board won't change if you access the dialog from a board
window).

You find several switches for the OpenGL display in the "OpenGL Options" dialogs
from the "View" menu. If glGo runs too slow you can try tinkering these options.
The manual contains some detailed information what each option does.

There is some extensive keyboard control. Please see the provided manual for
details. In short, use the cursor keys plus Control, Shift or Alt to rotate and
shift the board. Numpad plus/minus zooms in and out. Backspace resets the
default view. Cursor right/left without modifier key will move forward/backward.
There are more keys, see the manual.
The board can be rotated and shifted using the mouse: Hold right button and move
the mouse to rotate, hold both buttons and move the mouse to shift the board.

Some hints and informations about the OpenGL settings can be found in the
manual. Please have a look.

Comments and suggestions are welcome. Please drop me an email.


(C) GNU Go / GTP Mode

You can use glGo as an interface to play with GNU Go. If you are on Windows,
download GNU Go from the glGo webpage or get a version from the GNU Go homepage
and copy gnugo.exe into the glGo installation folder. If you are on Linux, install
GNU Go from your distribution or download it from the GNU Go webpage.
If the gnugo.exe file is in the same folder as the glGo executable, glGo won't
have trouble finding the file. If it does, it will complain and offer the user
a way to find the right file.
You can change the GTP engine and arguments in the preferences dialog. The arguments
must include "--mode gtp" for GNU Go.
To start a game with GNU Go, select the "Play GNU Go" button in the start
window. You will get a dialog to configure the game options. To end a GNU Go
game and return to normal playing mode, you need to close the GTP connection,
select menu "GNU Go" - "Disconnect GNU Go".
There is a GTP console available to see and manually control the GTP transfer.
Resuming games is supported, you can select a SGF game you want to continue
playing in the GNU Go setup dialog.
After two passes, the "Pass" button in the sidebar changes to "Score", which
allows you to manually score the game with the glGo built-in scoring tool. Hint:
Open the GTP console and type "estimate_score" to let GNU Go give an estimated
result.
Not supported yet are clocks.

GNU Go can be used to estimate the score of a game. You can call this using the
"Edit" - "Guess score" menuitem in a board window. The estimation will be run on
a temporay SGF file using the current move.


(D) SAVING THE CONFIGUTATION

The configuration is saved into a plain text file. On Linux in $HOME/.glGo/glGo.rc
and on Windows into $HOME/glGo/glGo.rc, where $HOME usually resolves into something
like: C:\Documents and Settings\<yourusername>.
This is at least the case for Windows 2000 and XP, older Windows versions might handle
this different. Windows 9x does not know about $HOME and saves the configuration file
into C:\Program Files\glGo\glGo\glGo.rc (or whereever you installed glGo).


(E) KNOWN PROBLEMS

Generally problems and bugs can be expected. If it crashes, don't panic. Please
try to reproduce the problem and report the bug to me.

Text scrolling in the various IGS output windows is strange on Windows 98. To fix
this, I included a special Windows 98 compatible resource file. Replace
C:\Program Files\glGo\share\resource.xrs with resource.xrs_win98 found in the same
directory. This changes all textareas to be more Win98-friendly. Maybe the
installer should do this automatically, but as I lack a proper Windows 98 test
system I am currently unsure about this. Also try changing the "Force scrolling"
option in the IGS preferences.

When opening a board on Windows, sometimes there are display artifacts. Once the
window got a bit resized or moved, the artifacts are gone. Another good idea is
to enable "Autohide starter" in the preferences, this seems to solve the issue
as well. This does not happen on Linux. I don't know the reason for this.

If you run a GNU Go score estimation and kill the gnugo process via task manager
or killall, glGo will crash.

The captures algorithm has trouble with Kos. When loading SGF files this could
produce some wired results. With observed IGS games it should be ok as then glGo
won't calculate captures itself but instead use the provided list sent from IGS.

On Linux, toggling the toolbar creates some artifacts; resize the window manually
a little to fix this. I don't know why this happens, it's ok on Windows.

Automatch does not display a dialog. glGo will automatically select nmatch if
available, which is far superior to automatch.

The localhost server mechanism on Windows is a potential security risk if you
run Windows without firewall. However, if you do such, you have much more
serious things to worry about than someone hacking your Go client.

Mac note: The new SGF parser on Mac has a tendency to crash on big files like
Kogo. So on Mac the old SGF parser is the default setting. You can change it
in the preferences dialog. On normal files (Kogo just isn't normal) the new
parser works fine.

If you encounter trouble, please don't hesitate to tell me about it. What I
don't know I cannot solve.


(F) HOW TO USE OWN IMAGES AND SOUNDS

You find the sounds in the share directory within the glGo installation. On
Linux this is /usr/share/games/glGo, on Windows C:\Program Files\glGo\share (or
whereever you installed glGo). On Mac you need to right-click on the glGo icon
in your Applications folder, select "Show package contents" and move to the
SharedSupport folder.

In this directory you find the sound files and a file data.dat which contains
the default images.

Using own sound files is pretty easy, just replace the existing sound files with
your own. You need to use exactly the filenames. To replace the stone sound, you
need to replace "stone.wav", etc.
The current sounds were taken from CGoban2 with the permission of the author.
If you have a cool sound, please send it to me if you want to share it!

To use own images, you need to create a directory data/ within the share
directory and drop the images there. glGo will first search real existing files,
and if they are not found use the defaults in data.dat. The images must have a
certain name, format and size:

The goban kaya background      : kaya.jpg                 512x512
The 3D white stone texture     : white_tex.jpg            64x64
The 3D white last-move marker  : mark_white.jpg           64x64
The 3D black last-move marker  : mark_black.jpg           64x64
The table background (2D+3D)   : table.png                128x128
The SDL white stones           : hyuga1.png - hyuga8.png  49x49
The SDL black stone            : blk.png                  49x49

Example:
To replace the kaya goban background, copy an image file kaya.jpg of size
512x512 pixels into the following location:
Windows: C:\Program Files\glGo\share\data\kaya.jpg
Linux:   /usr/share/games/glGo/data/kaya.jpg
Mac:     /Applications/glGo.app/Contents/SharedSupport/data/kaya.jpg

If you use another image format or another size, it might work or not. Probably
not. The OpenGL images *must* have a size of a power of two. SDL doesn't care.

All images are automatically resized. The table background is made from 6x6
tiles with each 128x128 pixels size.

To change the font used by the 2D board, replace FreeSans.ttf with a TrueType
font file of your choice. The font does not need to be FreeSans, just the file
must be named "FreeSans.ttf".

You can also use an own font file for OpenGL board coordinates and text markers
by replacing the coords_font.txf file in the share directory. If you want to
create those font files yourself, have a look at the gentexfont program within
the GLUT distribution which allows to convert a X-server font to a .txf file. I
have no idea if there is a way to create these font files on Windows. You can
find them on the net, the Plib example code has a couple of those font files.


(G) TECHNICAL INFORMATIONS

I started writing glGo on my old computer, a Pentium 2 333 MHz with a Diamond
Viper (Riva TNT1) graphiccard. This is a very low end system, but at least has
the advantage that if glGo runs on my computer, it will run on all hardware. :)
Meanwhile I moved to a modern system, but occasionally test glGo on above old box
to make sure the system requirements don't get out of range.

The used OpenGL version is 1.4, but is compatible with OpenGL 1.1, which is what
Microsoft ships with Windows.

The used wxWidgets version is 2.6.1
The used SDL version is 1.2.8
The used Plib version is 1.8.4
The used Python version is 2.3 (Windows/Mac) and 2.4 (Linux)
The Linux binary is compiled with GCC 3.3.5 on Debian/testing, the Windows binary
with MinGW (GCC 3.4) on Windows XP.


(H) THE PLAYERMANAGER

The playerdatabase is an extension implemented in Python and used as a
sort of "plugin" (embedded python, to be exact) within glGo. It offers the
friends/bozo list known from the Java gGo, the possibility to edit and assign
custom flags and write a comments about a player. Additionally directories can
be scanned for SGF files and all games of a certain player be looked up in the
playermanager. A graph and win/loss statistics are created from this games
collection.

Please see the glGo manual for further details.


(I) COPYRIGHT

Written by Peter Strempel <pstrempel@panda-igs.joyjoy.net>.
The artwork was designed by Tweet <tweet@panda-igs.joyjoy.net>.

PANDA-glGo is copyrighted work: Copyright (c) 2003-2006 PANDANET Inc.
All rights reserved.

The artwork and images are copyrighted work and must not be redistributed.
Copyright (c) 2002-2006 Tweet <tweet@panda-igs.joyjoy.net>. All rights
reserved.

Permission is granted to download, install and use this software.
Permission of the author must be obtained to redistribute the software.
It is forbidden to decompile and modify the software to alter its behaviour, or
distribute such a modified software.

This software is provided 'as-is', without any express or implied warranty,
without even the implied warranty of merchantability or fitness for a particular
purpose. In no event will the authors be held liable for any damages arising
from the use of this software.
