feat(plugins): Make player plugin a factory function (#604)

* feat(plugins): Make player plugin a factory function

This moves the `playerSetup` function out of the game configuration 
object. Instead `PluginPlayer` should be called with the setup function 
as its argument and it will return the plugin object boardgame.io 
expects.

BREAKING CHANGE: The `PluginPlayer` is no longer a plain object that 
looks for game.playerSetup during its setup. Instead, you have to pass 
your `playerSetup` method directly to the plugin.

Closes #603.

* refactor(plugins): Use an options object for player plugin

Author: delucis

docs/documentation/plugins.md

@@ -70,16 +70,38 @@ const game = {
 !> Plugins are applied one after the other in the order
 that they are specified (from left to right).
 
+##### Configuring Plugins
+
+Some plugins may need a user to provide some configuration. The recommended way to do that is to design the plugin as a factory function that takes configuration as its arguments and returns a plugin object.
+
+```js
+import { ConfigurablePlugin } from './plugins';
+
+const game = {
+  name: 'my-game',
+  plugins: [
+    ConfigurablePlugin(options),
+  ],
+}
+```
+
+?> See `PluginPlayer` below for an example of this in practice.
+
 #### Available Plugins
 
 **PluginPlayer**
 
 ```js
 import { PluginPlayer } from 'boardgame.io/plugins';
 
+// define a function to initialize each player’s state
+const playerSetup = (playerID) => ({ ... });
+
 const game = {
-  playerSetup: (playerID) => ({ ... }),
-  plugins: [PluginPlayer],
+  plugins: [
+    // pass your function to the player plugin
+    PluginPlayer({ setup: playerSetup }),
+  ],
 };
 ```
 
@@ -97,7 +119,7 @@ players: {
 }
 ```
 
-The initial values of these states are determined by the `playerSetup` function, which creates the state for a particular `playerID`.
+The initial values of these states are determined by the `setup` function in its options object, which creates the state for a particular `playerID`.
 
 The record associated with the current player can be accessed
 via `ctx.player.get()`. If this is a 2 player game,

src/plugins/plugin-player.test.js

@@ -11,22 +11,23 @@ import { Client } from '../client/client';
 
 describe('default values', () => {
   test('playerState is not passed', () => {
+    const plugin = PluginPlayer();
     const game = {
-      plugins: [PluginPlayer],
+      plugins: [plugin],
     };
     const client = Client({ game });
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[plugin.name].data).toEqual({
       players: { '0': {}, '1': {} },
     });
   });
 
   test('playerState is passed', () => {
+    const plugin = PluginPlayer({ setup: () => ({ A: 1 }) });
     const game = {
-      playerSetup: () => ({ A: 1 }),
-      plugins: [PluginPlayer],
+      plugins: [plugin],
     };
     const client = Client({ game });
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[plugin.name].data).toEqual({
       players: { '0': { A: 1 }, '1': { A: 1 } },
     });
   });
@@ -49,15 +50,15 @@ describe('2 player game', () => {
         },
       },
 
-      plugins: [PluginPlayer],
+      plugins: [PluginPlayer()],
     };
 
     client = Client({ game });
   });
 
   test('player 0 turn', () => {
     client.moves.A();
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[PluginPlayer().name].data).toEqual({
       players: {
         '0': { field: 'A1' },
         '1': { field: 'A2' },
@@ -68,7 +69,7 @@ describe('2 player game', () => {
   test('player 1 turn', () => {
     client.events.endTurn();
     client.moves.A();
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[PluginPlayer().name].data).toEqual({
       players: {
         '0': { field: 'A2' },
         '1': { field: 'A1' },
@@ -96,15 +97,15 @@ describe('3 player game', () => {
         },
       },
 
-      plugins: [PluginPlayer],
+      plugins: [PluginPlayer()],
     };
 
     client = Client({ game, numPlayers: 3 });
   });
 
   test('G.opponent is not created', () => {
     client.moves.A();
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[PluginPlayer().name].data).toEqual({
       players: {
         '0': { field: 'A' },
         '1': {},
@@ -119,8 +120,7 @@ describe('game with phases', () => {
 
   beforeAll(() => {
     const game = {
-      playerSetup: id => ({ id }),
-      plugins: [PluginPlayer],
+      plugins: [PluginPlayer({ setup: id => ({ id }) })],
       phases: {
         phase: {},
       },
@@ -130,7 +130,7 @@ describe('game with phases', () => {
   });
 
   test('includes playerSetup state', () => {
-    expect(client.getState().plugins[PluginPlayer.name].data).toEqual({
+    expect(client.getState().plugins[PluginPlayer().name].data).toEqual({
       players: {
         0: {
           id: '0',

src/plugins/plugin-player.ts

@@ -22,14 +22,21 @@ export interface PlayerAPI {
   };
 }
 
+interface PluginPlayerOpts {
+  setup?: (playerID: string) => any;
+}
+
 /**
  * Plugin that maintains state for each player in G.players.
  * During a turn, G.player will contain the object for the current player.
  * In two player games, G.opponent will contain the object for the other player.
  *
  * @param {function} initPlayerState - Function of type (playerID) => playerState.
  */
-const PlayerPlugin: Plugin<PlayerAPI, PlayerData> = {
+const PlayerPlugin = ({ setup }: PluginPlayerOpts = {}): Plugin<
+  PlayerAPI,
+  PlayerData
+> => ({
   name: 'player',
 
   flush: ({ api }) => {
@@ -63,17 +70,17 @@ const PlayerPlugin: Plugin<PlayerAPI, PlayerData> = {
     return result;
   },
 
-  setup: ({ ctx, game }) => {
+  setup: ({ ctx }) => {
     let players: Record<PlayerID, any> = {};
     for (let i = 0; i < ctx.numPlayers; i++) {
       let playerState: any = {};
-      if (game.playerSetup !== undefined) {
-        playerState = game.playerSetup(i + '');
+      if (setup !== undefined) {
+        playerState = setup(i + '');
       }
       players[i + ''] = playerState;
     }
     return { players };
   },
-};
+});
 
 export default PlayerPlugin;

src/types.ts

@@ -211,7 +211,6 @@ export interface GameConfig {
     action: ActionPayload.MakeMove
   ) => State | typeof INVALID_MOVE;
   flow?: ReturnType<typeof Flow>;
-  [key: string]: any;
 }
 
 type Undo = { G: object; ctx: Ctx; moveType?: string };