/******************************************************************************
* REMOTE CHESS - Copy(L)eft 2015                         http://harald.ist.org/
* README
******************************************************************************/

Table of Contents
	1. Overview
	2. Installing
	3. Files
	4. Mode of Operation
	5. Resources
	6. Todo


1. OVERVIEW
===========

REMOTE CHESS is a web platform for playing chess via e-mail or instant
messenger. Every state of a game is represented by a URL, saving the game is
done by bookmarking the page. Players receive a link, enter their move and send
the resulting link back to their chess partners, so they can continue the game.

The benefit of this system is, that the users have maximum control over their
data without the need to identify themselves on the server. The program can be
used in text browsers linke links2 or lynx and is meant to be very simple.

Using this program makes more sense with E-Mail, because instant messengers
tend to induce speedy exchange of moves. This may cause copy/pasting becoming
too frequent and annoying.


2. INSTALLING
=============

Copy all files into a folder in your web space.

You may have to enable PHP. Also, directory requests like xy.com/chess/?params
should be handled by  index.php , which will likely be the default.

Since short tags are deprecated, you can either set
	php_value short_open_tag 1
or replace all instances of  <?= STUFF ?>  with  <?php echo STUFF ?> .

There is a bunch of options in  definitions.php .


3. FILES
========
index.php           - Include all files, call main_control(), HTML template
helpers.php         - Conversions
definitions.php     - Settings, constants
movement_rules.php  - See, what moves a piece can do
url_helpers.php     - Manipulate the GET parameters of a link
generate_markup.php - Create HTML for the chess board, game's history, etc.
game_logic.php      - main_control() - Handle any input in one huge function

icons_white.png, icons_black.png - CSS sprites for each player.


4. MODE OF OPERATION
====================

SOME DEFINITIONS
----------------
A chess board is divided into rows ("Ranks" 1 to 8) and columns ("Files" A to H).
The bottom left field (for White) is named A1, right to it is B1, a.s.o.
Fields A1 and H8 (bottom left for each player) have a dark color, A8 and H1 are
colored brightly. In this case, the rule applies: "White queen to white field,
black queen to black field". See diagram below.

PROGRAM FLOW
------------
After  index.php  is loaded, it immediately includes all other PHP files and
calls the main program in  game_logic.php:main_control() . After it is finished
and returns to  index.php , the results (global variables) are used to build the
markup for the page, mainly a table and a list of history entries.

The main function is very long and described in more detail below. According to
the given parameters, a specific game state is assumed and executed:

MAIN ACTIONS
* New game (when called without GET parameters, asks for player names)
* Select a piece of the current player
* Select a field to move a piece to
* Promote a pawn that reached the top of the board

SECONDARY ACTIONS
* Flip board            ?flip
* Switch player         ?player=<white|black>
* Clear board           ?base=   (Empty)
* Create/Remove piece   Editor: from=<piece code>, to=<field name>
                        To remove a piece, you must name the correct piece code

GAME STATE STORAGE
------------------
The complete game state is being stored in the very link of the page. This is
done using the GET parameters:

	&player=<white|black>
	&history=<coded list of moves>
	&white=<Name of white player>
	&black=<Name of black player>
	&enpassant=<file name>


BOARD ENCODING

  +--+--+--+--+--+--+--+--+         BLACK          LOCATION_CODES
  |A8|B8|C8|D8|E8|F8|G8|H8|    r n b q k b n r     4 5 6 7 8 9 * $
  +--+--+--+--+--+--+--+--+
  |A7|B7|C7|D7|E7|F7|G7|H7|    p p p p p p p p     W X Y Z 0 1 2 3
  +--+--+--+--+--+--+--+--+
  |A6|B6|C6|D6|E6|F6|G6|H6|                        O P Q R S T U V
  +--+--+--+--+--+--+--+--+
  |A5|B5|C5|D5|E5|F5|G5|H5|   S, s: Rook, n.y.m.   G H I J K L M N
  +--+--+--+--+--+--+--+--+   L, l: King, n.y.m.
  |A4|B4|C4|D4|E4|F4|G4|H4|                        y z A B C D E F
  +--+--+--+--+--+--+--+--+
  |A3|B3|C3|D3|E3|F3|G3|H3|                        q r s t u v w x
  +--+--+--+--+--+--+--+--+
  |A2|B2|C2|D2|E2|F2|G2|H2|    P P P P P P P P     i j k l m n o p
  +--+--+--+--+--+--+--+--+
  |A1|B1|C1|D1|E1|F1|G1|H1|    R N B Q K B N R     a b c d e f g h
  +--+--+--+--+--+--+--+--+         WHITE

Example: starting board, encoded:
	  'SaNbBcQdLeBfNgSh'   // Row 1, A1..H1
	. 'PiPjPkPlPmPnPoPp'   // 2
	. 'pWpXpYpZp0p1p2p3'   // 7
	. 's4n5b6q7l8b9n*s$'   // 8


HISTORY
-------
The game is stored in a string, kept in the GET parameter  &history . The
history consists of a list of moves, encoded by one character for the origin
and the target field according to the  LOCATION_CODES  shown above. The meaning
of each move is implied and reconstructed in  decode_history()  and
 history_markup() .

PROMOTIONS are encoded as an "empty" round, using 4 characters:
"(AB)" where A stands for the top rank field, a pawn moved to in the previous
move, and B is the piece code of what the pawn became according to the player's
choice when promoting that pawn.

Since the ROUND NUMBER is derived from the string length of the history,
certain routines need to subtract the amounts of occurances of opening
parantheses "(" multiplied by 4.


MAIN_CONTROL()
--------------
The main program consists of several sections, which can roughly be divided
into:
	* Initialization
	* Fetch GET parameters
	* Build  $board_array  from  &base=  and/or  $history .
	* Analyse  from  and  to  and execute
		* EDITOR
		* COMMAND
		* MOVE
		* SELECT/DESELECT
	* Create  $href_this  (Adding GET parameters describing current state)
	* Possible redirection (in order to make the URL nicer)
	* Building markup
	* Set  $heading  and  $game_title , if
	* Set a default  $game_title , if none given
	* Create  $game_state_link  (The link that is sent to the other player)


MOVING A PIECE (HTTP Redirect)
------------------------------
When  from  and  to  contain valid field names and the move is possible, it
will be applied to the current  $board_array  and the move is added to the
history. To clear the URL of parameters  from  and  to ,  $redirect_after_move
is set in order to trigger the according actions later in  main_control() .


ILLEGAL MOVES
-------------
Rules for moving a piece are handled in piece specific functions which return a
list of fields, the piece could physically move to. This does not include
considerations of the king's safety, but includes possible enemies to capture.
See  movement_rules.php .

Sopme possible moves may be forbidden. For instance, when the king would be
left in check after the move, or in case of casteling, when some of the fields
between king and rook are under attack. These considerations are done, when
clickable fields are calculated in  game_locig.php:select_piece() .


CASTLING
--------
Rooks and kings are initially coded as  S, L  or  s, l  indicating, that they
have not yet been moved. The code will be switched to  R, K  or  r, k  in
apply_move(), preventing them from being considered for castling again.


EN PASSANT
----------
When a pawn is moved two ranks on its first move, the other player may be
allowed to capture that pawn en passant, but only immediately after the pawn
was moved. A special GET parameter  &enpassant=<file name>  indicates the file
of the pawn that moved 2 ranks in the move before.


PROMOTING A PAWN
----------------
When a pawn reaches the top, the redirect that would be triggered by this MOVE
action is supressed, which results in a pawn promotion menu to be shown instead.
Selecting a replacement will trigger a "normal" move with a redirect.


5. RESOURCES
============
https://en.wikipedia.org/wiki/Chess
https://en.wikipedia.org/wiki/Castling
https://en.wikipedia.org/wiki/Promotion_%28chess%29
https://en.wikipedia.org/wiki/En_passant
https://en.wikipedia.org/wiki/Checkmate
https://en.wikipedia.org/wiki/Stalemate
https://en.wikipedia.org/wiki/Draw_%28chess%29
https://en.wikipedia.org/wiki/Threefold_repetition

https://en.wikipedia.org/wiki/Chess_opening
https://en.wikipedia.org/wiki/Chess_middlegame
https://en.wikipedia.org/wiki/Chess_endgame
https://en.wikipedia.org/wiki/Glossary_of_chess

https://en.wikipedia.org/wiki/Chess_notation
https://en.wikipedia.org/wiki/Algebraic_chess_notation
https://en.wikipedia.org/wiki/Chess_symbols_in_Unicode
https://en.wikipedia.org/wiki/Portable_Game_Notation
https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation
https://www.reddit.com/r/dailyprogrammer/comments/3t0xdw/20151116_challenge_241_easy_unicode_chess/
https://en.wikipedia.org/wiki/Correspondence_chess
https://en.wikipedia.org/wiki/Elo_rating_system
https://en.wikipedia.org/wiki/Chess_composition
http://derstandard.at/r1229777262316/Raetsel--Sudoku
https://en.wikipedia.org/wiki/Universal_Chess_Interface

https://developers.google.com/speed/pagespeed/insights/
https://developers.google.com/speed/docs/insights/UseLegibleFontSizes
https://developers.google.com/speed/docs/insights/ConfigureViewport


6. TODO v0.2b
=============
- Detect Draw
- Reflect end of game in History
== OPTIONAL ===================================================================
- JS: Button to copy the history
* a2enmod headers expires ; service apache2 restart
- mailto:username@example.com?subject=Subject&body=message%20goes%20here
  http://stackoverflow.com/questions/13231125/automically-open-default-email-client-and-pre-populate-content
- "A. White's move - Check!": Dash still green --> black
? Get rid of redirect, use params for visualizing last move
- Date and Time in Title
- Refactor: Semantic markup for history
- Send This Link Section: Start date and last move date in URL
- Send This Link Section: Move of previous player
- History: Show En Passant
- History: Show Castling
- History: Show Check!
- History: Goto Previous
? History: No prompt, when check mate
? History: Cont: Make it possible to continue playing from a previous move
? History: Cont: Click history back, Return Link shows link to clear rest of history
- Keep orientation: &top={white|black}
- Chess Riddles: $riddle[code]=description html
. Capture: Utilize "Taken by player" locations "." and ":"
- Capture: visual list of removed pieces, Utilize locations "." and ":"
- Speech bubbles over pieces with user comments, dialog sequences
- JS Request Reduction: Provide everything needed for selecting a full move
- Play against AI
- Rename files with dash using underscore
- <base href> for shorter links?
- Errors: Proper error messages instead of  die() .
- Errors: Manually type move that would get king in check: Get rid of die()
- Errors: Select valid piece of opponent: No error is shown! Must be ignored completly.
- Errors: Respond to improper input verbously
== RE-CHECK ===================================================================
- CSS: Cross browser compatibility, Print Style, Mobile Friendly
- Long history, long player names
- Sync GET parameter order between  update_href()  and form in  index.php
- Replace all hardcoded strings with constants (GET_TO, GET_FROM, ...)
- Test with links2 or lynx
- Fix everything marked with  "//..."