Kami Chess 1.6.2
====================

Chess on a 3D board with boxwood and walnut pieces. Play a friend at the same
computer, play against the computer, or, with a Kami Chess account, play other
players online.


Start
-----

Unpack the archive anywhere and run the program from the folder it made:

    tar -xzf kami-chess-1.6.2-linux-x86_64.tar.gz
    ./kami-chess-1.6.2/kami-chess

That is all it needs: nothing is installed. The program finds its board and
pieces in the assets folder beside it, so keep the folder together; to remove
the game, delete it.


Install (optional)
------------------

To start Kami Chess from the application menu, with its icon, run the install
script in the folder:

    ./kami-chess-1.6.2/install.sh

It installs for you alone and asks for no password: the game goes into
~/.local/share/kami-chess, its menu entry into ~/.local/share/applications and
its icon into ~/.local/share/icons. Look for Kami Chess among your games; some
desktops show a new entry only after you log out and in again. The unpacked
folder is not needed afterwards, and you can delete it.

Running install.sh again, or the one from a newer version, replaces the
installed game with that one.

To remove the installed game, its menu entry and its icon:

    ~/.local/share/kami-chess/uninstall.sh


Playing
-------

Beside the board, on the right (below it in a window taller than it is wide),
are the status line and four buttons. The status line says whose turn it is,
that the computer is thinking, and how the game ended, by checkmate or a draw.

  Undo    Takes back a move. Against the computer it takes back its reply
          and your move.
  Flip    Turns the camera to the other player's side.
  Reset   Puts the camera back where it started. The position stays.
  Menu    Opens the menu.

To play against the computer, click Menu and choose under Play against the
side the computer plays, White or Black; you play the other one. Nobody, where
the game starts, is two players at one computer. Strength sets how strong the
computer plays: Gentle, Steady (where it starts) or Strong. A new strength
applies from the computer's next move; a move it is already thinking about
keeps the strength it started with.

The menu also holds How to play, the game in a few lines; Privacy, which opens
the privacy policy (kamidesigns.be/privacy/kami-chess) in your browser; and
the version. On How to play, Close goes back to the menu. Close on the menu, a
click outside the menu or the Esc key closes it.

Under Account, Log in opens the Kami Chess login page (auth.kamidesigns.be)
in your browser, and Create account opens its form for a new account. Once
you have logged in there, the browser hands you back to the game, which then
shows the name you are logged in as. It stays logged in the next time you
start it, until you choose Log out. The game keeps its login in
~/.config/kami-chess/account (or under $XDG_CONFIG_HOME), a file only you can
read; Log out removes it. Logging in needs libcurl, which most Linux
distributions install; the game plays without it.

Logged in, Multiplayer lists the players of Kami Chess: those online now
first, the others greyed, and beside each name your wins and losses against
them (-/- before your first game). Click a name to challenge that player,
online or not; they see the challenge in Your games, which also holds your
open and finished games and your record. An online game has no time limit and
waits for as long as it takes: close Kami Chess or log out, and it is still
there in Your games. In an online game Resign stands where Undo was, and the
result says whom you won or lost against.

Kami Chess goes online only for your account: to log in, and while you are
logged in, to say that you are playing, to show the other players and to
play your online games. Without an account it sends nothing anywhere. What
an account keeps, and what other players see, is in the privacy policy for
accounts (kami-chess.kamidesigns.be/privacy).


Options
-------

The options start a game with the computer already chosen, another way to do
what the Menu does. From a terminal, in the unpacked folder:

    cd kami-chess-1.6.2
    ./kami-chess                                     two players at one computer
    ./kami-chess --opponent black                    you play white, the computer black
    ./kami-chess --opponent white                    the computer moves first
    ./kami-chess --opponent black --depth 6 --time-ms 3000
                                                     the computer thinks longer

After an install, from any folder:

    ~/.local/share/kami-chess/kami-chess
    ~/.local/share/kami-chess/kami-chess --opponent black
    ~/.local/share/kami-chess/kami-chess --opponent white
    ~/.local/share/kami-chess/kami-chess --opponent black --depth 6 --time-ms 3000

  --opponent none|white|black   The side the computer plays. Default none: two
                                players. Otherwise you play the other side.
  --depth N                     How many half-moves ahead the computer looks,
                                1 to 64. Default 4.
  --time-ms N                   How long the computer may think, in
                                milliseconds, before it plays its best move so
                                far. Default 1000; 0 means no limit.
  --fen FEN                     Start from a position written in FEN instead of
                                the start position.
  --width N, --height N         The window size. Default 1280 x 960. The window
                                can also be resized.
  --help, --version             Print the options, or the version.

The Menu shows the choice --opponent made. It shows Steady whatever --depth
and --time-ms say, and choosing a Strength replaces them.

While the computer thinks, a pulsing blue strip lights its half of the board
frame and the board ignores your clicks.


Controls
--------

The buttons have keys too, and the mouse turns and zooms the camera:

  Click a piece, then a      Move. A pawn reaching the last rank opens a choice
  highlighted square         of four pieces on the board.
  Drag with the left button  Turn the camera around the board.
  Mouse wheel                Zoom.
  f                          Turn the camera to the other player's side.
  r                          Reset the camera.
  u                          Undo. Against the computer it takes back its reply
                             and your move.
  Esc                        Close the menu if it is open; otherwise deselect,
                             or close the promotion choice.
  q r b n                    Choose the promotion piece while the choice is open.
  Ctrl+Q                     Quit.


Requirements
------------

  - 64-bit Linux on x86-64 with glibc 2.38 or newer (for example Ubuntu 24.04,
    Debian 13, Fedora 39 or later).
  - A desktop session, X11 or Wayland.
  - OpenGL 3.3 graphics with the GLVND libraries libOpenGL.so.0 and
    libEGL.so.1, which current graphics drivers install (on Debian and Ubuntu
    the packages libopengl0 and libegl1).

The C++ runtime is built in; nothing else is needed.


Licences
--------

THIRD-PARTY-NOTICES.txt holds the licences of the libraries built into the
program.
