README
ampersand-chess-state
Install
npm install ampersand-chess-state
What?
ampersand-chess-state
is an ampersand-state
wrapper around the awesome chess.js
library.
The main reason for the wrapper is to allow for listening to changes in properties like checkmate
or check
when moving pieces without needing to call the synchronous chess.js methods like chess.in_checkmate()
or chess.in_check()
.
This also adds a few other conveniences not found in chess.js
:
- A
redo/last/first
methods to go along withundo
- Optionally keeping time for each side
- Getting the pgn as an array with the active ply flagged
- A helper derived property for getting the reason for an ended game
- The ability to "freeze" certain properties based on their end state when replaying a game
Example
Load a starting position and listen for pgn/fen changes and moves
var Chess = require('../ampersand-chess-state');
var chess = new Chess();
var log = function (prefix, model, value) { console.log(prefix, JSON.stringify(value)); };
chess.on('change:fen', log.bind(null, 'FEN'));
chess.on('change:pgn', log.bind(null, 'PGN'));
chess.on('change:move', log.bind(null, 'MOVE'));
// Use the move method
chess.move('e4');
// FEN "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1"
// PGN "1. e4"
// MOVE {"color":"w","from":"e2","to":"e4","flags":"b","piece":"p","san":"e4"}
chess.move('e5');
// FEN "rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6 0 2"
// PGN "1. e4 e5"
// MOVE {"color":"b","from":"e7","to":"e5","flags":"b","piece":"p","san":"e5"}
// Or append to the pgn property
chess.pgn += ' 2. f4';
// FEN "rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq f3 0 2"
// MOVE {"color":"w","from":"f2","to":"f4","flags":"b","piece":"p","san":"f4"}
// PGN "1. e4 e5 2. f4"
API
props
(string) fen
(string) pgn
Either of these can be set as strings on the state object, but only one may be set on initialization. If neither is set, it default to normal starting position.
Setting fen
will wipe out all previous move and pgn history.
Appending a new move to pgn
will not cause any history to be lost and will instead call move()
with the newest move. But making a wholesale pgn
change will reset all history.
(number) blackTime
(number) whiteTime
A number in milliseconds to start with for the time for that color. This number will decrease (using requestAnimationFrame) while it is that color's turn.
(boolean, false) freezeOnFinish
This is a flag that if true
will cause certain properties to be "frozen" once a game has been finished. This allows for the position to be changed (by undo/redo
for example) but still have the properties keep the same value that they did at the end of the game. See the freezable tag on the derived property documentation for which ones will be frozen.
You're most likely going to want to set this to true
for legal games but leave it as the default for things like analysis boards, etc.
derived
(array) future
(array) history
(boolean) canUndo
(boolean) canRedo
history
and future
are arrays containing any previous or future moves relative to the current position when replaying a game which can be done with the undo
, redo
, first
, last
methods.
canUndo
and canRedo
are booleans which trigger based on if the corresponding array has length > 0
.
(boolean) valid
(string) errorMessage
These contain information about whether the position is valid and the possible resulting error message when setting the fen
or pgn
. These won't be triggered when using any of the methods such as move
. Those will instead return null
if they move was invalid.
(boolean, freezable) start
Triggers whenever the board is in the starting position.
(boolean, freezable) empty
Triggers whenever the board is empty. This wouldn't ever get triggered during a legal game.
(string, ["black", "white"], freezable) turn
Triggers with the color whose turn it is.
(boolean, freezable) checkmate
(boolean, freezable) check
(boolean, freezable) draw
(boolean, freezable) stalemate
(boolean, freezable) threefoldRepetition
(boolean, freezable) insufficientMaterial
(boolean, freezable) lostOnTime
(boolean, freezable) gameOver
Each of these trigger when the resulting condition is met in the position.
(string, ["black", "white", ""], freezable) winner
Returns the winning color based on checkmate
or if one side lostOnTime
.
(string) ascii
An ascii representation of the board. Pop it in <pre></pre>
and you're halfway to ascii chess.
(array) moves
An array of valid moves based on the current position.
(array) pgnArray
An array of each pgn move in the following format. The active
flag will be updated based on the history
which can be used to highlight the active ply when replaying a game.
Example:
// Black's turn in the second move
[{
move: 1,
ply1: {san: 'e4'},
ply2 {san: 'e5'}
}, {
move: 2,
ply1: {san: 'f4', active: true},
ply2: {san: ''}
}]
(string, freezable) endResult
Triggers when the game is over with one of the following values:
Lost on time
Checkmate
Draw - Stalemate
Draw - Threefold Repetition
Draw - Insufficient Material
Methods
All these methods change the position in someway and will trigger changes in fen
and pgn
. They take an options
object as the last parameter which will be passed along when set
is called on fen
and/or pgn
.
load(fen, options)
loadPgn(pgn, newlineChar, options)
These methods will load a new fen
or pgn
. These exist for convenience when wanting to use the options or newlineChar parameters. Most of the time you'll want to do chess.fen = newFen
or chess.pgn = newPgn
.
Also note that loading a new fen
or pgn
will result in lost history. You should normally use the move()
method. In the case of appending a new valid move to pgn
this will call move(appendedMove)
under the hood.
move(move, options)
This method will make the move requested. If the move is invalid it will return null
.
random(options)
Make a random but valid move. Returns the move.
put(piece, square, options)
remove(square, options)
reset(options)
clearEngine(options)
These methods are used mostly in analysis style situations since they allow adding or removing pieces from the board. See the chess.js
docs for more info about them.
undo(options)
redo(options)
first(options)
last(options)
These will change to the previous or next move in the history, or to the first or last move in the history. They will return the move to be played or null
if no such move exists.
Tests
Run npm test
for the command line tests (using phantomjs) or npm start
to open a browser with the tests.
LICENSE
MIT