Match API Object

This represents an instance of a running game, including all the moves that have been played to reach the current state.

Method	Description
`userTurn()`	Requests the user to enter a move
`abortUserTurn()`	Aborts a previous call to `userTurn()`, causing this pending call to fail
`machineSearch()`	Requests the best move from the artificial intelligence
`abortMachineSearch()`	Aborts a previous call to `machineSearch()`, causing this pending call to fail
`playMove()`	Applies a move to the match, running visual animations if any
`applyMove()`	Applies a move to the match, without running visual animations
`attachElement()`	Provides a user interface to the match through the given DOM element
`detachElement()`	Detaches the match from a previously attached element
`setViewOptions()`	Sets the options of the user interface
`getFinished()`	Returns the current game ending status of the match
`getTurn()`	Returns who is the player to play next move
`getMoveString()`	Returns a game-normalized string representing the given move
`rollback()`	Changes the match state to a previous situation
`save()`	Returns a string that represents the exact state of the match
`load()`	Sets the state of the match from a previous save
`pickMove()`	Returns the Jocly move best matching the given string
`otherPlayer()`	Returns the player other than the one as input
`getPlayedMoves()`	Returns the moves played in the match

userTurn()

Requests the user to enter a move.

On completion, this method returns an object with the properties:

move: the played move under the form of a javascript object. You should not try to interpret the properties in this object as they are completely dependant game implementation
finished, winner: as described in getFinished()

Once this method resolves, the move has been applied to the match and saved in the list of played moves.

Example:

match.userTurn()
  .then( (result) => {
    if(!result.finished)
      // play next move
  })

abortUserTurn()

Aborts a previous call to userTurn(), causing this pending call to fail.

cGenerally, there is no need to call this method since the actual user turn ends when the user completes the input. However, the function may be used in case for instance the user ran out of time.

On completion, this method does not return any value.

Example:

var timer = setTimeout( () => {
  match.abortUserTurn();
}, 5000)

match.userTurn()
  .then( (result) => {
    clearTimeout(timer);
    // ...
  })
  .catch( (error) => {
    // error should be "Aborted"
  })

machineSearch([options])

Requests the best move from the artificial intelligence.

options: an optional javascript object with properties:
- level: an object describing the parameter for the machine level. By default, it is the first level defined in the game model configuration
- threaded: a boolean indicating whether the artificial should run in a separate thread (javascript Worker). This parameter is ignored on node.js

On completion, this method returns an object with the same properties as the ones from userTurn().

Once this method resolves, the move has not been applied to the match, in fact the match state has not changed. You need to call either playMove() or applyMove().

Example:

match.machineSearch()
  .then ( (result) => {
    match.playMove(result.move)
      .then( () => {
        if(!result.finished) {
          // proceed to next move
        }
      })
  })

abortMachineSearch()

Aborts a previous call to machineSearch(), causing this pending call to fail.

One reason for aborting a machine search is for instance to change the artificial intelligence level. Since a given Match object can only run a single machine search at once, the previous search must be aborted before starting a new search.

On completion, this method does not return any value.

Example:

var timer = setTimeout( () => {
  // abort the engine search if it did resolve within 1 second
  match.abortMachineSearch();
}, 1000)

match.machineSearch()
  .then( (result) => {
    clearTimeout(timer);
    // ...
  })
  .catch( (error) => {
    // error should be "Aborted"
  })

playMove(move)

Applies a move to the match, running visual animations if any.

move: the move to be played

The method runs animations that may have been defined in the game implementation before resolving. If the move is not valid, the method rejects the returned promise.

Returns a javascript object describing the outcome of the move:

finished, winner: as described in getFinished()

Example:

match.machineSearch()
  .then ( (result) => {
    match.playMove(result.move)
      .then( (result2) => {
        if(!result2.finished) {
          // proceed to next move
        }
      })
  })

applyMove(move)

Applies a move to the match, without running visual animations.

move: the move to be played

The method does not run animations that may have been defined in the game implementation before resolving. If the move is not valid, the method rejects the returned promise.

Returns a javascript object describing the outcome of the move:

finished, winner: as described in getFinished()

Example:

match.machineSearch()
  .then ( (result) => {
    match.applyMove(result.move)
      .then( (result2) => {
        if(!result2.finished) {
          // proceed to next move
        }
      })
  })

attachElement(element [,options])

Provides a user interface to the match through the given DOM element.

element: a DOM element (like a DIV) to attach the game to
options: see setViewOptions()

When a match has just been created from [[Jocly.createMatch()|Jocly API Object#createMatch]], it does not provide any user interface. attachElement() must be used to display the board and accept user input. Only one element can be attached to a match. When used from node.js, this method fails.

Example:

Jocly.createMatch('classic-chess',(match) => {
  var element = document.getElementById("game-area");
  match.attachElement(element)
    .then( () => {
      // proceed with playing the game
    })
})

detachElement()

Detaches the match from a previously attached element.

The initial state of the element is restored. This method fails when used from node.js.

Example:

// attach the match to an element
match.detachElement()
  .then( () => {
  })

setViewOptions(options)

Sets the options of the user interface.

options: a javascript object with properties:
- skin: the name of the view skin (as defined in the game view configuration)
- notation: boolean, should notation appear on the board (if supported by the game implementation)
- showMoves: boolean, during user input, should possible moves displayed (if supported by the game implementation)
- sounds: boolean, should sounds be played (if supported by the game implementation)
- autoComplete: boolean, should moves automatically be completed during the user input if there is no choice left (if supported by the game implementation). Note that at least one user action (click) is required

Only the parameters specified in options are updated. If the match is not attached to an element, the method fails. setViewOptions is not supported on node.js.

Example:

match.setViewOptions({
      skin: "skin3d",
      sounds: false
    })
  .then( () => {
  })

getFinished()

Returns the current game ending status of the match.

The returned object has properties:

finished: a boolean indicating whether this move ended the game
winner: in case finished is true, this property indicates who won:
- Jocly.PLAYER_A: player A (the first player in the game, i.e White in Chess)
- Jocly.PLAYER_B: player B (the second player, i.e Black in Chess)
- Jocly.DRAW: draw

Example:

match.getFinished()
  .then( (result) => {
    if(result.finished) {
      if(result.winner == Jocly.PLAYER_A)
        alert("A wins");
      else if(result.winner == Jocly.PLAYER_B)
        alert("B wins");
      else if(result.winner == Jocly.DRAW)
        alert("Draw");
    }
  })

getTurn()

Returns who is the player to play next move.

The returned value can be:

Jocly.PLAYER_A: next move must come from player A (i.e the user who made the first move in the match, e.g White at Chess)
Jocly.PLAYER_B: next move must come from player B (i.e the user who made the second move in the match, e.g Black at Chess)

Example:

match.getTurn()
  .then( (who) => {
    if(who==1) {
      // get move from player A
    } else {
      // get move from player B
    }
  })

getMoveString(move)

Returns a game-normalized string representing the given move.

move: a javascript object representing a Jocly move, or an array containing move objects

Jocly moves returned by userTurn() or machineSearch() are obscure objects, i.e their properties are game-dependant and should not be interpreted with the application. But many games have their own move notation, e.g in Chess, e2-e4 means King's pawn moves 2 square ahead). The getMoveString() returns the game-normalized string value given a Jocly move object.

If the input parameter is an array of move objects, the return is an array of string-transformed moves transformed.

Example:

match.machineSearch()
  .then( (result) => {
    match.getMoveString(result.move)
      .then( (moveString) => {
        console.info("Computer plays",moveString);
      })
    })
  });

rollback(index)

Changes the match state to a previous situation.

index: an integer specifying a previous state. If index is positive (including 0), it represents the number of moves since the beginning of the match, 0 represents the initial state. If negative, index is the number of moves to step back, e.i -1 steps back 1 move prior to the current state

If the match is attached to an element, the user interface will display the new state of the board.

Example:

match.rollback(-1)
  .then( () => {
    // we just cancelled the last move
  });

save()

Returns a string that represents the exact state of the match.

The returned string can be saved for a future call to load().

Example:

match.save()
  .then( (matchData) => {
    // save the object through whatever mean
  });

load(matchData)

Sets the state of the match from a previous save.

matchData: a javascript object obtained from save()

Restores the state of the match when matchData was obtained from save()

Example:

var match_data;
match.save()
  .then( (matchData) => {
    match_data = matchData;
  });
// then later
match.load(match_data)
  .then( () => {
    // move on with restored state
  });

destroy()

Frees all resources associated to the match.

Once a match object is no longer needed, it is a good idea to destroy it explicitly instead of leaving the garbage collector doing the job for you. A good reason for doing this is that the match object may be attached to a WebGL context and those browser objects are limited (generally 16 contexts per tab), and shortage may cause other games not to display.

Example:

match.destroy()
  .then( () => {
    // the match object has been freed
  });

pickMove(moveString)

Returns the Jocly move best matching the given string.

moveString: a string representing a move, obtained from an external engine or move history

An external move source, like the output of a game engine or a PGN file, may provide strings representing moves. Those strings cannot be digested immediately by Jocly which requires game-dependant obscure objects. pickMove() returns the closest Jocly move object corresponding to the given string, amongst the possible moves in the current state. The method fails if no move was close enough to the input string or if ambiguities could not be resolved.

Example:

// assuming match has been created from 'classic-chess'
match.pickMove('e4')
  .then( (move) => {
    match.applyMove(move)
      // ...
  });

otherPlayer(player)

Returns the player other than the one as input.

Given player is either Jocly.PLAYER_A or Jocly.PLAYER_B, returns the other player.

Example:

match.getTurn()
  .then( (player) => {
    match.otherPlayer(player)
      .then( (other) => {
         // if player == Jocly.PLAYER_A then other == Jocly.PLAYER_B
         // if player == Jocly.PLAYER_B then other == Jocly.PLAYER_A
      })
  });

getPlayedMoves()

Returns the moves played in this match.

The returned array returns Jocly obscure move objects.

Example:

match.getPlayedMoves()
  .then( (moves) => {
    match.getMoveString(moves)
      .then( (humanReadableMoves) => {
        console.info("Moves played:",humanReadableMoves)
      })
  });

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Match API Object

userTurn()

abortUserTurn()

machineSearch([options])

abortMachineSearch()

playMove(move)

applyMove(move)

attachElement(element [,options])

detachElement()

setViewOptions(options)

getFinished()

getTurn()

getMoveString(move)

rollback(index)

save()

load(matchData)

destroy()

pickMove(moveString)

otherPlayer(player)

getPlayedMoves()

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally