Matcher API v7

• status: complete
• version: 7.x

Overview

The api is limited to matching players into pairs only.

The only matching algorithm is already implemented is round robin (also known as perfect stranger), but custom matching algorithms can be plugged into the api easily.

Round Robin API

Additional options not described in the tutorial

• bye: number (Default: -1) sets the number assigned to dummy players in tournament tables with odd number of participants.
• skypBye: boolean (Default: false) controls whether matches with dummy players are included in the final schedule.
• missingId: string (Default: 'bot') sets the id for players whose number in the tournament table cannot be resolved.
• assignerCb: function (Default: Matcher.randomAssigner) sets the assigner callback
• x: number (Default 0) sets the round index for method getMatch when called with no parameter.
• y: number (Default 0) sets the match index for method getMatch when called with no parameter.

Matcher

The Matcher is available under node.game.matcher, or it can be created as a new object in the logic:

var Matcher = require('nodegame-client').Matcher;
var matcher = new Matcher();

The matcher can be re-initialized calling the init method any time.

matcher.init(options);

Get specific matches

It is possible to request specific matches by passing parameters to the getMatch method.

matcher.getMatch(1,1); // ['c', 'b']
matcher.getMatch(3,1); // null (out of bounds)

Get all round matches

It is possible to get all the matches of a round by leaving out the second parameter to getMatch

matcher.getMatch(1); // [ ['c', 'b'], ['a', 'd'] ]

Get round matches as key-value pairs

To get all the matches of a round in one object use the getMatchObject method, with or without the round parameter.

matcher.getMatchObject(); // {a: 'b', c: 'd' }
matcher.getMatchObject(1); // { c: 'b', a: 'd' }

Custom id assignment

By default, the specified ids will be randomly placed into the tournament schedule. However, if a special assignment is required, it is possible to specify an assigner callback

matcher.setAssignerCb(function(ids) {
    return [ ids[1], ids[2], ids[0] ];
});

The assigner callback is called before performing a matching. The order of the ids inside the array returned by the functions determines how the players are assigned to the schedule.

Custom Matcher example

Import the Matcher class into your code.

var Matcher = require('nodegame-client').Matcher;
var matcher = new Matcher();

Generate the tournament table with a given matching algorithm (roundrobin is the only option for now), and pass any extra option.

matcher.generateMatches('roundrobin', 4); 

Set the ids of the players. They will substitute the numbers in the tournament table.

matcher.setIds([ 'a', 'b', 'c', 'd' ])

Match the ids of the players into the round robin tournament schedule. By default, the ids are randomly assigned, but other assignment rules can be defined.

matcher.match();
// The whole tournament schedule is defined as follow:
[ 
  // Round 1.
  [ ['a', 'b'], ['c', 'd'] ],
  // Round 2.
  [ ['c', 'b'], ['a', 'd'] ],
  // Round 3.
  [ ['c', 'a'], ['b', 'd'] ]
] 

Call getMatch to receive the next match.

matcher.getMatch(); // Returns ['a', 'b']
matcher.getMatch(); // Returns ['c', 'd']
matcher.getMatch(); // Returns ['c', 'b']

// When all the matches are exhausted null will be returned

Next Topics

• Return to home