Dependencies

Requires the following libraries: three.js, revision 80; and optionally OrbitControls.js (included with three.js download)

Also needs JSON files for piece set mesh data and font mesh data, in folder /assets.

Configuration

Pass a configuration object to the ChessBoard3 constructor:

var board = new ChessBoard3('some_div_id', config);

The config object can have the following properties and methods:

Property Type Default value Description
draggable boolean false If set to true, the user can drag pieces to other squares or off the board.
Default value of false makes a "read-only" board that restricts control of the board position to code.
dropOffBoard 'snapback' or 'trash' 'snapback' If set to 'trash', the user can drag pieces off the board to get rid of them.
Otherwise, 'snapback' makes those pieces snap back to their original square.
Using 'trash' generally makes no sense unless 'sparePieces' is set to true.
fontData string or function 'assets/fonts/helvetiker_regular.typeface.json' URL path to the three.js font file. This setting is specific to chessboard3.js.
localStorage String true (i.e., empty board) Determines whether piece meshes should be cached using the localStorage API.
This needs to be set to false to see any results if piece mesh files are being edited.
orientation 'white' or 'black'. 'white' This specifies the initial orientation of the board.
(This is actually implemented by changing the camera position.)
pieceSet string or function 'assets/chesspieces/classic/{piece}.json' A template string for the URL of the piece mesh files, where '{piece}' gets replaced by 'K', 'Q', 'R', 'B', or 'P'.

This setting is specific to chessboard3.js. The JSON files required are K.json, Q.json, R.json, B.json, N.json, and P.json, and each specifies the geometry of one type of piece, regardless of color, in three.js format.

In chessboard.js the analogous setting is pieceTheme for specifying the location of 12 image files- 'wK.png', 'bQ.png', etc.) A configuration object can have both of these set; chessboard.js will ignore one and chessboard3.js will ignore the other.

If pieceSet is a function, the only argument is a one character piece code. The function should return a URL to the JSON file.

NOTE: At present chessboard3.js only loads mesh geometries from the JSON files, without any added textures. It then slaps white and black PhongMaterials on the geometries to create the meshes.

Squares are 2x2, so the bounding box for a piece mesh should be restricted to [-0.5, 0.5] for x and y; the board itself lies on the z=0 plane.
position String '' (i.e., empty board) The initial position of the board as a FEN string.
Accepts 'start' as an alias for the starting FEN 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR'
position Object N/A The initial position of the board specified in chessboard.js format.
The object would typically look like this:
{ a4: 'wK', c4: 'bK', a7: 'wR'} Keys are squares ('a1' through 'a8', 'h1' through 'h8', etc.) Values are piece abbreviations such as 'wK' for white knight or 'bP' for black pawn.
rotateControls boolean true If set, the user can rotate the board around on its axis, unless OrbitControls.js has not been loaded.
showNotation boolean true Determines whether files and ranks are labeled (files a through h, ranks 1 through 8)
If set to true and helvetiker_regular.typeface.js has not been loaded, chessboard3.js will report an error and continue.
sparePieces boolean false If set to true, pieces appear next to the board that can be dragged onto it.
If sparePieces is set to true, draggable gets set to true.
zoomControls boolean false If set, the user can zoom using the middle mouse button or scroll wheel, unless OrbitControls.js has not been loaded.
This is great for screenshots, but it's disabled by default because the dolly controls in OrbitControls.js are so clunky.
backgroundColor Number 0xBBBBBB Background color of the redering window.
whitePieceColor Number 0xAAAAAA Color of White's pieces.
whiteSpecularColor Number 0xCCFFFF Specular color (for phong reflections) of White's pieces.
blackPieceColor Number 0x333333 Color of Black's pieces.
blackSpecularColor Number 0x553333 Specular color (for phong reflections) of Black's pieces.
notationColor Number 0x000000 Color of the notation labels.
appearSpeed Number or 'slow' or 'fast' 200 Animation speed for pieces appearing on squares (i.e. fully transparent to fully opaque).
Note that if sparePieces is set, these are not the type of animations that occur; the relevant setting is moveSpeed..
moveSpeed Number or 'slow' or 'fast' 200 Animation speed for pieces moving across or onto the board.
snapbackSpeed Number or 'slow' or 'fast' 50 Animation speed for when pieces dragged off the board snap back to their original square.
This only has an effect if dropOffBoard is set to 'snapback'.
snapSpeed Number or 'slow' or 'fast' 25 Animation speed for when pieces snap to the middle of a square upon being dropped.
trashSpeed Number or 'slow' or 'fast' 100 Animation speed for when pieces are removed.
showErrors false or 'console' or 'alert' false Errors are ignored if false. If 'console', errors go to console.log. If 'alert', errors go to window.alert().
showErrors function N/A If showErrors is a function, it receives the arguments:
  1. error code
  2. error string
  3. anything relevant (optional)
onChange function N/A Fires when the board position changes. Arguments are old position and new position.
WARNING: Calling clear, move, position, or start methods in your onChange function may trigger an endless loop or a stack overflow.
onDragStart function N/A Fires when a piece is picked up. Returning false from this method will prevent the drag action.
Arguments:
  1. source of the piece
  2. piece code
  3. current position on the board
  4. current board orientation
onDragMove function N/A Fires when a dragged piece changes location.
Arguments:
  1. new location of the piece
  2. old location of the piece
  3. original source of the piece
  4. piece code
  5. current board position
  6. current orientation
onDrop function N/A Fires when a dragged piece is dropped. Returning 'snapback' will return the piece to its source square; returning 'trash' from this method will remove the piece.
Arguments:
  1. original location of the piece
  2. target location of the piece
  3. piece code
  4. new board position once the piece drops
  5. prior board position
  6. current orientation
onMouseoutSquare function N/A Fires when a mouse leaves a square.
Arguments:
  1. square that was left
  2. piece on that square, or false if none
  3. Current board position
  4. Current orientation
NOTE: This method is not invoked during drag and drop interactions.
onMouseoverSquare function N/A Fires when a mouse enters a square.
Arguments:
  1. square that was entered
  2. piece on that square, or false if none
  3. Current board position
  4. Current orientation
NOTE: This method is not invoked during drag and drop interactions.
onMoveEnd function N/A Fires at the end of animations when the board position changes.
Arguments:
  1. old board position
  2. new board position
onRender function N/A Fires immediately before WebGL renders the board.
Arguments;
  1. The THREE.Scene object.
  2. An object with squares as keys, and square mesh ids within the THREE.Scene as values
  3. An object with squares as keys, and piece mesh ids within the THREE.Scene as values.
  4. Current board position.
Returning false from this function will prevent the rendering from taking place, but it will be called again.
onSnapbackEnd function N/A Fires when the 'snapback' animation is complete after users try to drag pieces off the board.
Arguments:
  1. piece code
  2. square piece returned to
  3. current board position
  4. current orientation
onSnapEnd function N/A Fires when the piece 'snap' animation is complete and the piece is positioned at the center of a square.
Arguments:
  1. original location of the piece
  2. target location of the piece
  3. piece code
WARNING: Some browsers will not actually render the piece in its new location until this method returns, so do not run off with the event thread at this point! Post any long synchronous routines using setTimeout() instead. This applies to both chessboard.js and chessboard3.js.

Methods

Once the widget is created, here is the stuff you can do with it.

Method Args Description
clear(useAnimation) useAnimation is an optional boolean argument, defaulting to true. Clears the board of all pieces.
destroy() none Removes the widget from the DOM.
fen() none Returns the current board position as a [partial] FEN string (without side-to-move, en passant square, castling permissions etc.)
Ths is an alias of position('fen').
flip() none Flips the board orientation; alias of orientation('flip').
greySquare(square) Takes one argument, square, e.g. 'e8'. Highlights the square.
This method is not supported in chessboard.js, but there is a workaround: 
var greySquare = function(square) {
      var squareEl = $('#board .square-' + square);
      var background = '#a9a9a9';
      if (squareEl.hasClass('black-3c85d') === true) {
        background = '#696969';
      }
      squareEl.css('background', background);
    };
move(move1, move2, move3, ... etc.) Arguments are a list of moves in algebraic notation ('e2-e4', 'g8-f6', etc. Executes one or more moves on the board, and returns an updated position object.
orientation() none Returns the current orientation of the board (i.e. 'black' or 'white').
orientation(side) Takes one string argument, either 'black', 'white', or 'flip'.
 This places the camera in the default position for the specified player. If the argument is 'flip' it flips the orientation and then moves the camera.
position() Takes one optional string argument, 'fen'. Returns the current position object in chessboard.js format, unless the 'fen' argument is given, in which case it returns the position as a FEN string.
position(newPosition, useAnimation)
  1. newPosition is a position object, a FEN string, or 'start'
  2. useAnimation is an optional boolean argument that defaults to true..
 Sets the current position of the board. Pass false for useAnimation to set the position instantly without animating to it.
removeGreySquares none Removes all highlights from the board that were set by calling greySquare().
This method is not supported in chessboard.js, but there is a workaround: 
var removeGreySquares = function() {
      $('#board .square-55d63').css('background', '');
    };
resize() none Recalculates the board size based on the parent element and resizes the board to the largest size that fits with a 4:3 aspect ratio.
rerender() none Rerenders the three.js scene (asynchronously).
start(useAnimation) useAnimation is an optional boolean parameter that defaults to true.
If useAnimation is false, the board position is set instantly.
 This is an alias of position('start', useAnimation).

Errors

There is an error system; you can control how the errors are presented with the showErrors config option.

ID Message Description
1001 The first argument to the constructor cannot be an empty string. The first argument should be a DOM element or its ID.
1002 Element with given ID passed to the constructor is not in the DOM. The first argument should be a DOM ID, not a selector (e.g. "#myBoard").
1003 The first argument to the constructor must be an ID or a single DOM node. See description for error 1001.
1004 JSON does not exist; please include a JSON polyfill. May happen on older browsers.
2354 config.showNotation is true and the font URL (default 'helvetiker_regular.typeface.json') doesn't load. This is not a fatal error; it omits the notation labels.
3701 Square has a piece in mesh array but not in current position. Internal error that you should not see.
3701 Square has a piece found in mesh array that does not exist in the three.js scene. Internal error that you should not see.
3703 Square has a piece found in current position but not in mesh array. Internal error that you should not see.
2826 Invalid move passed to the move method. Moves should be in algebraic format, e.g. "e2-e4".
5482 Invalid move passed to the orientation method. The argument needs to be 'white', 'black', or 'flip'.
6482 Invalid value passed to the position method. Position must be either 'start', a valid FEN string, or a valid position object.
7263 Invalid value found in config.position. Position must be 'start', a valid FEN string, or a valid position object.