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
-----

1. Open kami-chess-1.6.2-macos-universal.zip in Finder if your browser has
   not unzipped it already (Safari does). It makes the folder
   kami-chess-1.6.2 with the Kami Chess app in it.
2. Double-click Kami Chess. To keep it, drag it to your Applications folder
   first.

Nothing else is installed. The board and pieces are inside the app; to remove
the game, move the app to the Trash.


The first start
---------------

Kami Chess is signed and notarised by Apple. The first time you open a new
version, macOS asks whether you are sure you want to open an app downloaded
from the Internet. Check that it names Kami Chess, then click Open.

If macOS instead says it cannot open Kami Chess or cannot check it for
malicious software, download the zip again and open the new copy. If it still
refuses:

  - macOS 15 Sequoia and newer: open System Settings, Privacy & Security,
    scroll down to Security, click Open Anyway next to the message about
    Kami Chess, and confirm with your login password. The button is there
    for about an hour after you tried to open the app.
  - macOS 14 Sonoma and older: Control-click Kami Chess in Finder, choose
    Open, then click Open.

macOS remembers the choice, and later starts open the game directly.


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 your login
keychain, as the item be.kamidesigns.kamichess; Log out removes 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. Start the game from Terminal with them, for example with
the app in Applications:

    open -a "Kami Chess" --args --opponent black     you play white, the computer black
    open -a "Kami Chess" --args --opponent white     the computer moves first
    open -a "Kami Chess" --args --opponent black --depth 6 --time-ms 3000
                                                     the computer thinks longer

  --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 or trackpad 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 mouse or     Turn the camera around the board.
  trackpad button held
  Scroll                     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.
  Control-Q                  Quit.


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

  - macOS 11 Big Sur or newer on a Mac with Apple silicon, or
    macOS 10.15 Catalina or newer on a Mac with an Intel processor.
    The app runs natively on both.
  - Nothing else: OpenGL is part of macOS.


Licences
--------

THIRD-PARTY-NOTICES.txt holds the licences of the libraries built into the
program. The app holds a copy too.
