File | Date | Author | Commit |
---|---|---|---|
5k | 2012-03-14 |
![]() |
[0ede36] move all the image files to places where they'r... |
6k | 2012-03-14 |
![]() |
[0ede36] move all the image files to places where they'r... |
6k-expanded | 2012-03-14 |
![]() |
[0ede36] move all the image files to places where they'r... |
misc | 2012-03-14 |
![]() |
[7ea5d3] move unicode under misc |
prehistory | 2012-03-14 |
![]() |
[f03e12] add html to prehistory directory |
scripts | 2012-04-08 |
![]() |
[c18dae] A little script to update the p4wn.sf.net website |
src | 2019-11-10 |
![]() |
[fcdda9] fen-test: add the 218 move position |
test | 2012-05-31 |
![]() |
[9fba3e] Put some speed tests in the test directory, and... |
website | 2013-04-18 |
![]() |
[44abb7] Óscar Toledo G.'s website has moved to nanoches... |
.gitignore | 2012-03-08 |
![]() |
[36d8a1] ignore backup files, .emacs.desktop files |
README.rst | 2014-10-22 |
![]() |
[f4cb3d] Update README.rst |
P4wn is both - an online web page and an offline HTML mobile and tablet application - that can play chess. It is quite small, plays well enough to be interesting, and is easy to embed in your pages. The default interface is easy to replace, and the engine is simple and tunable. P4wn is completely free, available under CC0 or public domain terms. You can use it for anything you want.
If you load src/index.html (or http://p4wn.sf.net/src) in a modern javascript enabled browser, you should see a small chess board. You are playing white. To change that, click swap. You can swap sides at any stage of the game.
To move a piece, click on it and click again where you want it to be.
If the game is too easy or hard, click on the computer level button until it seems about right. Depending on you browser and computer, the slower settings might cause the browser to pop up warning windows.
When you make a stupid move, you can undo it by clicking on the undo button. To jump back a long way, you can click on a move in the game log.
The pawn becomes ... button switches between the various possible promotions for a pawn that reaches the end. If you want to change it, do so before you move the pawn.
If a draw is technically possible (either through 3 repetitions of the same position, or 50 moves without a capture or pawn move) , a Draw? button will appear. You can claim a draw by clicking it. P4wn will never claim a draw on its own, just offer you the button.
There is a homepage at http://p4wn.sf.net and git repositories at http://p4wn.git.sourceforge.net/git/gitweb.cgi?p=p4wn/p4wn and https://github.com/douglasbagnall/p4wn. The two git repositories should be pretty similar. Most people seem to use the github one. Zip and tar files of version 2 can be found at http://sourceforge.net/projects/p4wn/files/.
The git tree contains several files not included in the version 2 zip and tar files. These are mainly interesting for historical reasons, or for testing, and are unnecessary and potentially confusing if you just want to play chess. So they have been left out and instead you'll get confused when this document refers to them. You can get these files via git, or just look at them on the Github and Sourceforge links above.
There is a mailing list at https://lists.sourceforge.net/lists/listinfo/p4wn-chess, and the issue tracker at https://github.com/douglasbagnall/p4wn/issues is used.
P4wn was originally written between 2000 and 2002 in a very compressed form, and was entered in the 2002 5k web contest. This version can still be found in the 5k and 6k directories. It is quite obtuse, due to its minified nature and the inexperience of the programmer.
In 2004 it gained a sourceforge page (http://p4wn.sf.net) with a CVS tree and a public domain dedication. This spurred a small flurry of forks, as various people tried fixing the obvious bugs and bad graphics or further reducing the code size. These forks never coalesced into anything that could be called a stream of development, no doubt due to the pathological state of the code and a perceived lack of need for small chess playing web pages.
The name “p4wn” was originally only intended as a sourceforge subdomain, not to be applied to the chess program itself (which was called “5k chess” or somesuch). People have universally assumed otherwise, so the name sticks.
In 2012 P4wn was rewritten for readability, correctness, and speed. The code in the src directory is version 2; that in 5k is version 1. Version 2 followed liberation from CVS into git.
Version 2.01 contains an interface fix for Internet Explorer.
Version 2.02 introduces changes and wrappers so p4wn runs with an offline.appcache. Now p4wn can be installed as a packaged application or hosted application on Firefox OS devices to run even offline and in full screen. Furthermore p4wn can now be installed and run on iOS devices being started via icon from Home Screen and run in full screen, too. An optimize to screen resolution feature is available now. It provides resolution awareness, e.g. on mobile devices if switching between portrait and landscape, etc. New SVG (Scalable Vector Graphics) chess set has been created from scratch under CC0. See
Although they look entirely different, there is a structural and algorithmic continuity between the versions.
P4wn 1 was written to run on turn of the century browsers, and to be as small as possible. It works in browsers newer than Netscape 3 and Internet Explorer 4. Version 2 targets HTML5-ish browsers and aims to be as small as is reasonable, while remaining easy to modify and embed. It probably works in all versions of Firefox, Chrome, and Safari, and (more slowly) in Internet Explorer 5.5 and above.
P4wn 2 in 2012 works a few thousand times faster than p4wn 1 did is 2002. Much, but not all, of that is down to browser and hardware improvements.
TL;DR: look at src/index.html. If you are trying something more complex than that, look also at src/fen-test.html. Failing that, read on.
The default interface (display.js) is deliberately primitive, to encourage the development of replacements.
Copy the files engine.js, display.js, p4wn.css, and the images directory into your html directory. Then add these lines to your html:
<link rel="stylesheet" href="p4wn.css" />
in the <head>,
<div id="board-goes-here"></div>
where you want the board to be, and this:
<script src="engine.js"></script> <script src="display.js"></script> <script> var game = p4wnify("board-goes-here"); game.next_move(); </script>
at the bottom (as seen in src/index.html).
You might want the p4wn files somewhere else in your web tree, in which case you would do something like this (replacing p4wn/src with the correct path):
<html> <link rel="stylesheet" href="p4wn/src/p4wn.css" /> <body> Your content... <div id="board-goes-here"></div> Your other content... <script src="p4wn/src/engine.js"></script> <script src="p4wn/src/display.js"></script> <script> P4WN_IMAGE_DIR = 'p4wn/src/images'; var game = p4wnify("board-goes-here"); game.next_move(); </script> </body> </html>
Replacing every instance of p4wn/src in the above example with http://p4wn.sf.net/src ought to work. (Which is not to say http://p4wn.sf.net/src will always contain working and up-to-date code).
Start from p4wn.css. A few rules (e.g. the log panel height) are overridden by javascript. If you really need to wrest control back, use the !important declaration. Or you could write your own version of p4wnify() from display.js that doesn’t do that.
The images are found in a directory specified by P4WN_IMAGE_DIR. When you have better images, put them where you like and change that variable before calling p4wnify():
<script src="p4wn/src/engine.js"></script> <script src="p4wn/src/display.js"></script> <script> P4WN_IMAGE_DIR = '/path/to/better/images'; var game = p4wnify("board-goes-here"); game.next_move(); </script>
Alternatively you can change the P4WN_IMAGE_NAMES variable, which is a list of variable names:
var P4WN_IMAGE_NAMES = [ 'empty.gif', '', // 1 is unused 'white_pawn.gif', 'black_pawn.gif', 'white_rook.gif', 'black_rook.gif', 'white_knight.gif', //.... ];
but that is more work.
The size of the board is controlled by the size of each square, which is controlled by two variables:
<script> P4WN_SQUARE_WIDTH = 60; /* default is 30 x 30 */ P4WN_SQUARE_HEIGHT = 60; var game = p4wnify("board-goes-here"); game.next_move(); </script>
The images will be scaled to this size.
Should the board flip around when you are playing black, so your pieces are at the bottom?
P4WN_ROTATE_BOARD = false; //default is true
Do you dislike the names of the various levels, or think the default level is wrong? Change these:
P4WN_LEVELS = ['stupid', 'middling', 'default', 'slow', 'slowest']; P4WN_DEFAULT_LEVEL = 2;
The names of pieces for pawn promotions can be localised:
P4WN_PROMOTION_STRINGS = ['queen', 'rook', 'knight', 'bishop'];
as can the moves in the game log:
P4_ENCODE_LUT = " ♙♟♖♜♘♞♗♝♔♚♕♛";
Should p4wn keep trying deeper and deeper searches until it runs out of time (around a second)?
P4WN_ADAPTIVE_LEVELS = true;
It is possible to replace the display.js interface altogether, or to modify the way the engine plays. But these topics are discussed below. It is time for a break.
For convenience, the p4wnify function will work with an element ID (as seen in the other examples), a DOM element itself, or a jquery object:
var el = document.getElementById("board-goes-here"); var $el = $("#board-goes-here"); p4wnify(el).next_move(); p4wnify($el).next_move();
engine.js keeps track of the game, finds moves to play, and tries to communicate as much of this as is necessary to the human interface (display.js, by default). There are a few functions and a state object you need to worry about if you are writing a new interface, and a number of configurable constants you can fiddle with whether you are replacing display.js or not.
FEN, or Forsyth-Edwards Notation is a standard for describing chess positions. It is fairly simple and widely used.
Algebraic Notation or AN is a widely used but not quite precisely defined standard for describing chess moves. If you have ever read a chess article you will have seen little clusters of letters and numbers like “a8=Q Nbxa8”. That is algebraic notation. P4wn follows the PGN dialect which uses upper case Os instead of zeros in castling notation (O-O-O vs 0-0-0), but it tries to understand a wider range, including the long form which names each square rather than the moved piece (e.g. b1-c3 rather than Nc3).
Finally, a pseudo-legal move is a move that is allowed by the movement rules of chess without regard for check. The pseudo legal moves are an easier to find super-set of the actually legal moves.
p4_new_game() creates a state object representing a game in the initial position. This is actually just a wrapper for p4_fen2state(P4_INITIAL_BOARD), with P4_INITIAL_BOARD being the appropriate FEN string. With other FEN strings you can start the game in another position.
The state object has three methods, which are wrappers around global functions in engine.js. You can use the global functions just as well, using this conversion table:
state.findmove(depth) <--> p4_findmove(state, depth) state.move(...) p4_move(state, ...) state.jump_to_moveno(n) p4_jump_to_moveno(state, n)
This finds the computer’s moves. state is the object returned by p4_new_game(), and depth is an integer 1 less than the depth of the desired search. That is, a 3 will give you a 4-ply search.
It returns the array [start, end, score], where start and end are board co-ordinates suitable for feeding into state.move(), which is what you need to do if you actually want to make the move it found.
This moves the piece and updates the board state. promotion is the piece the pawn should become if this move happens to be moving a pawn to the end. The options are P4_ROOK, P4_KNIGHT, P4_BISHOP, and P4_QUEEN, equating to 4, 6, 8, and 12 respectively. If promotion is omitted, P4_QUEEN is assumed.
The start and end can take various forms. The native form used by display.js and state.findmove are indexes into a 120 element array, which is conceptually a 10x12 board, with the 8x8 board placed at the centre, thus:
+ 0123456789 0 ########## 10 ########## 20 #RNBQKBNR# 30 #PPPPPPPP# 40 #........# 50 #........# 60 #........# 70 #........# 80 #pppppppp# 90 #rnbqkbnr# 100 ########## 110 ##########
The idea behind this representation is that any piece trying to walk off the board will hit a wall (“#” in the diagram), which simplifies bounds checking. There are two rows at top and bottom to catch the knights. The white pieces start in locations 21-28 and 31-38, and the black ones in 91-98 and 81-88, so moving the white kings pawn out 2 rows (e4 in algebraic notation) would be made using:
state.move(35, 55);
But state.move will also accept a split algebraic form:
state.move('e2', 'e4'); /*start and end in algebraic notation*/
or various complete algebraic forms, where end and promotion are both ignored:
state.move('e4'); state.move('e2-e4'); /* 'long' algebraic notation */
If you are using this for, you should set the pawn promotion as part of the algebraic string (or you’ll just get queens):
state.move('e8=N'); /got to end; promote to knight/
You get back an object like this:
{ flags: <integer flags>, string: <algebraic notation>, ok: <boolean> }
ok says whether or not the move was legal. If ok is true, the move stuck and the state has changed accordingly. flags contains more detailed information about what happened. The flags are:
P4_MOVE_FLAG_OK = 1 the move is OK P4_MOVE_FLAG_CHECK = 2 a king is in check P4_MOVE_FLAG_MATE = 4 checkmate or stalemate P4_MOVE_FLAG_CAPTURE = 8 a piece has been taken P4_MOVE_FLAG_CASTLE_KING = 16 king side castle P4_MOVE_FLAG_CASTLE_QUEEN = 32 queen side castle P4_MOVE_FLAG_DRAW = 64 a draw is available
For example, if you put the other king into check by taking a piece, the flags attribute will be P4_MOVE_FLAG_OK | P4_MOVE_FLAG_CHECK | P4_MOVE_FLAG_CAPTURE, which is 11. An ordinary move with no capture or check results in a 1.
If P4_MOVE_FLAG_MATE is set without P4_MOVE_FLAG_CHECK, the result is stalemate.
P4_MOVE_FLAG_DRAW indicates that a technical draw can be claimed (that is, a position has been repeated three times or 50 full moves have passed without a pawn move or capture).
If the move is OK, string is a description of it in algebraic notation. If the move fails, string may or may not contain an explanation (“in check” or similar).
Rewind the game to an earlier move, wth n being the half-move number to jump to. Examples:
state.jump_to_moveno(0) /* jump to the beginning */ state.jump_to_moveno(3) /* jump to black's second move */
If the game was initialised using p4_fen2state(), you can only rewind as far back as the move specified by the FEN involved.
The display code reads two attributes of the state object:
{ board: array, to_play: 0 }
where board is the 120 element array described above, and to_play is 0 during white’s turn and 1 during blacks.
These can be adjusted in the same way as themeable constants above: just change them after you load engine.js, and before you do anything else.
It would be wise to stick to approximately the same scale:
P4_VALUES=[0, 0, 20, 20, //pawns 100, 100, //rooks 60, 60, //knights 61, 61, //bishops 8000, 8000,//kings 180, 180, //queens 0];
You can make p4wn play the same game every time and possibly log more to the javscript console:
P4_DEBUG = 1; /*or true */
Modern browsers have typed arrays which p4wn uses by default where they exist. You can force them off or on:
P4_USE_TYPED_ARRAYS = false;
The state object has a treeclimber attribute, which points to a function used by p4_find_move to evaluate the various possible moves. The default implementation calls itself recursively to perform an alpha-beta search, but replacement treeclimbers need not do this.
There are a number of alternatives in parse-test.js, and if you visit src/fen-test.html you will see a button for cycling through these.
To replace the search, just go state.treeclimber = your_search_function, making sure of course that your function knows the treeclimber signature:
treeclimber( state, /* p4wn state object */ depth, /* integer indicating depth of search */ colour, /* colour to move 0 == white, 1 == black */ score, /* base score to alter */ s, e, /* start and end squares of the move to be considered */ alpha, beta /* low and high cutoffs */ ){ return score; /*score adjusted by evaluation */ }
If you don’t know alpha and beta do, you can ignore them (or look up alpha-beta search). You can probably ignore the score argument too if your function is not performing cumulative evaluation via recursion.
This alters the state object by making the move indicated by start and end. If the move puts a pawn in the promotion row, promotion must be set. The returned object contains all the information necessary to unmake the move (and a bit more).
This undoes a p4_make_move move. The basic pattern is:
var move = p4_make_move(state, start, end, promotion) /* evaluate... */ p4_unmake_move(state, move)
This returns an array of arrays representing the available pseudo-legal moves along with a partial evaluation of the move’s value. Each returned move is represented thus: [score, start, end]. Even if you aren’t using the evaluation, p4_parse is reasonably quick.
As an exception to the pseudo-legal moves rule, p4_parse thoroughly checks that castling is possible.
Returns true if the king of the colour in question is in check. Otherwise false.
If you wanted to shrink p4wn back down to a few kilobytes, you could get rid of much of the last third of engine.js which is mostly about interpreting and producing strings in standard formats. Then if you manually shorten the global names (including functions), an automatic minimiser should be able to make it quite small, though probably not down to 5k.
A few tests are run automatically by src/auto-test.html. The test harness in src/auto-test.js is primitive but reusable, topical, and extensible.
src/fen-test.html doesn’t test anything on its own, but offers more debugging options than index.html.
The board state, search depth, and player colour can be set via the http query string. The following options are recognised:
For example, http://p4wn.sf.net/src/?start=8/8/8/8/8/4K3/5Q2/7k+w+-+-+11+56&player=black lands you in a pickle, playing black.
These people (and probably others whose names I have mislaid) have added something to p4wn:
All of the authors listed have dedicated their contributions to this work to the public domain by waiving all of his rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.
You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.
If you want your contributions to be included in the main p4wn repository, you will also need to waive copyright on them.