Replace player with currentPlayer option in setActivePlayers (#523

)

* feat(core): Use currentPlayer argument in setActivePlayers

Instead of using a `player` argument inside `setActivePlayers`, use `currentPlayer`. This makes
`setActivePlayers` more predictable when used across hooks etc.

BREAKING CHANGE: Anyone who is using a `player` argument inside `setActivePlayers` will need to
adapt their usage to either `currentPlayer`, or if they require the `player` behaviour, replace
`player: 'stage'` with `value: { [ctx.playerID]: 'stage' }`.

* test(core): Update tests to use `currentPlayer` in `setActivePlayers`

* test(ai): Update tests to use `currentPlayer` in `setActivePlayers`

* docs: Update stages documentation

docs/documentation/stages.md

@@ -89,8 +89,8 @@ We use the `setActivePlayers` event for this:
 
 ```js
 setActivePlayers({
-  // Move the player that called the event to a stage.
-  player: 'stage-name',
+  // Move the current player to a stage.
+  currentPlayer: 'stage-name',
 
   // Move every other player to a stage.
   others: 'stage-name'
@@ -163,7 +163,7 @@ setStage({ stage: 'stage-name', moveLimit: 3 });
 
 ```js
 setActivePlayers({
-  player: { stage: 'stage-name', moveLimit: 2 },
+  currentPlayer: { stage: 'stage-name', moveLimit: 2 },
   others: { stage: 'stage-name', moveLimit: 1 },
   value: {
     '0': { stage: 'stage-name', moveLimit: 4 },
@@ -235,10 +235,10 @@ exactly one move before they are removed from the set of active players.
 
 ##### OTHERS
 
-Similar to `ALL`, but excludes the player from the set
+Similar to `ALL`, but excludes the current player from the set
 of active players.
 
 ##### OTHERS_ONCE
 
-Similar to `ALL_ONCE`, but excludes the player from the set
+Similar to `ALL_ONCE`, but excludes the current player from the set
 of active players.

src/ai/ai.test.js

@@ -131,7 +131,7 @@ describe('Step', () => {
         },
 
         turn: {
-          activePlayers: { player: 'stage' },
+          activePlayers: { currentPlayer: 'stage' },
         },
       },
 
@@ -183,7 +183,7 @@ describe('Simulate', () => {
         },
       },
       turn: {
-        activePlayers: { player: Stage.NULL },
+        activePlayers: { currentPlayer: Stage.NULL },
       },
       endIf: G => G.moved,
     });
@@ -311,7 +311,7 @@ describe('MCTSBot', () => {
         },
       },
       turn: {
-        activePlayers: { player: Stage.NULL },
+        activePlayers: { currentPlayer: Stage.NULL },
       },
       endIf: G => G.moves > 5,
     });

src/core/flow.js

@@ -310,7 +310,7 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
     if (currentPlayer) {
       ctx = { ...ctx, currentPlayer };
       if (conf.turn.activePlayers) {
-        ctx = SetActivePlayers(ctx, ctx.currentPlayer, conf.turn.activePlayers);
+        ctx = SetActivePlayers(ctx, conf.turn.activePlayers);
       }
     } else {
       // This is only called at the beginning of the phase

src/core/flow.test.js

@@ -488,7 +488,7 @@ describe('stage events', () => {
       let flow = Flow({
         moves: { A: () => {} },
         turn: {
-          activePlayers: { player: 'A' },
+          activePlayers: { currentPlayer: 'A' },
         },
       });
       let state = { G: {}, ctx: flow.ctx(2) };
@@ -515,7 +515,7 @@ describe('stage events', () => {
     });
 
     test('empty argument ends stage', () => {
-      let flow = Flow({ turn: { activePlayers: { player: 'A' } } });
+      let flow = Flow({ turn: { activePlayers: { currentPlayer: 'A' } } });
       let state = { G: {}, ctx: flow.ctx(2) };
       state = flow.init(state);
 
@@ -529,7 +529,7 @@ describe('stage events', () => {
     test('basic', () => {
       let flow = Flow({
         turn: {
-          activePlayers: { player: 'A' },
+          activePlayers: { currentPlayer: 'A' },
         },
       });
       let state = { G: {}, ctx: flow.ctx(2) };
@@ -558,7 +558,7 @@ describe('stage events', () => {
       let flow = Flow({
         moves: { A: () => {} },
         turn: {
-          activePlayers: { player: 'A' },
+          activePlayers: { currentPlayer: 'A' },
         },
       });
       let state = { G: {}, ctx: flow.ctx(2) };
@@ -574,7 +574,7 @@ describe('stage events', () => {
     test('sets to next', () => {
       let flow = Flow({
         turn: {
-          activePlayers: { player: 'A1', others: 'B1' },
+          activePlayers: { currentPlayer: 'A1', others: 'B1' },
           stages: {
             A1: { next: 'A2' },
             B1: { next: 'B2' },
@@ -940,7 +940,7 @@ describe('activePlayers', () => {
       turn: {
         stages: { A: {}, B: {} },
         activePlayers: {
-          player: 'A',
+          currentPlayer: 'A',
           others: 'B',
         },
       },

src/core/turn-order.js

@@ -32,11 +32,11 @@ export const Pass = (G, ctx) => {
 /**
  * Event to change the active players (and their stages) in the current turn.
  */
-export function SetActivePlayersEvent(state, playerID, arg) {
-  return { ...state, ctx: SetActivePlayers(state.ctx, playerID, arg) };
+export function SetActivePlayersEvent(state, _playerID, arg) {
+  return { ...state, ctx: SetActivePlayers(state.ctx, arg) };
 }
 
-export function SetActivePlayers(ctx, playerID, arg) {
+export function SetActivePlayers(ctx, arg) {
   let { _prevActivePlayers } = ctx;
 
   const _nextActivePlayers = arg.next || null;
@@ -60,19 +60,19 @@ export function SetActivePlayers(ctx, playerID, arg) {
     activePlayers = value;
   }
 
-  if (arg.player !== undefined) {
+  if (arg.currentPlayer !== undefined) {
     ApplyActivePlayerArgument(
       activePlayers,
       _activePlayersMoveLimit,
-      playerID,
-      arg.player
+      ctx.currentPlayer,
+      arg.currentPlayer
     );
   }
 
   if (arg.others !== undefined) {
     for (let i = 0; i < ctx.playOrder.length; i++) {
       const id = ctx.playOrder[i];
-      if (id !== playerID) {
+      if (id !== ctx.currentPlayer) {
         ApplyActivePlayerArgument(
           activePlayers,
           _activePlayersMoveLimit,
@@ -152,7 +152,7 @@ export function UpdateActivePlayersOnceEmpty(ctx) {
 
   if (activePlayers && Object.keys(activePlayers).length == 0) {
     if (ctx._nextActivePlayers) {
-      ctx = SetActivePlayers(ctx, ctx.currentPlayer, ctx._nextActivePlayers);
+      ctx = SetActivePlayers(ctx, ctx._nextActivePlayers);
       ({
         activePlayers,
         _activePlayersMoveLimit,
@@ -238,7 +238,7 @@ export function InitTurnOrderState(G, ctx, turn) {
   const currentPlayer = getCurrentPlayer(playOrder, playOrderPos);
 
   ctx = { ...ctx, currentPlayer, playOrderPos, playOrder };
-  ctx = SetActivePlayers(ctx, currentPlayer, turn.activePlayers || {});
+  ctx = SetActivePlayers(ctx, turn.activePlayers || {});
 
   return ctx;
 }

src/core/turn-order.test.js

@@ -522,7 +522,7 @@ describe('setActivePlayers', () => {
         },
 
         turn: {
-          activePlayers: { player: 'stage', moveLimit: 1 },
+          activePlayers: { currentPlayer: 'stage', moveLimit: 1 },
         },
       };
 
@@ -548,7 +548,7 @@ describe('setActivePlayers', () => {
           moves: {
             A: (G, ctx) => {
               ctx.events.setActivePlayers({
-                player: 'stage2',
+                currentPlayer: 'stage2',
                 moveLimit: 1,
                 revert: true,
               });
@@ -557,7 +557,7 @@ describe('setActivePlayers', () => {
           },
 
           turn: {
-            activePlayers: { player: 'stage1' },
+            activePlayers: { currentPlayer: 'stage1' },
           },
         };
 
@@ -595,7 +595,7 @@ describe('setActivePlayers', () => {
           moves: {
             A: (G, ctx) => {
               ctx.events.setActivePlayers({
-                player: 'stage2',
+                currentPlayer: 'stage2',
                 moveLimit: 1,
                 revert: true,
               });
@@ -605,7 +605,7 @@ describe('setActivePlayers', () => {
 
           turn: {
             activePlayers: {
-              player: 'stage1',
+              currentPlayer: 'stage1',
               moveLimit: 3,
             },
           },
@@ -672,13 +672,13 @@ describe('setActivePlayers', () => {
 
         turn: {
           activePlayers: {
-            player: 'stage1',
+            currentPlayer: 'stage1',
             moveLimit: 1,
             next: {
-              player: 'stage2',
+              currentPlayer: 'stage2',
               moveLimit: 1,
               next: {
-                player: 'stage3',
+                currentPlayer: 'stage3',
               },
             },
           },
@@ -692,10 +692,10 @@ describe('setActivePlayers', () => {
         activePlayers: { '0': 'stage1' },
         _prevActivePlayers: [],
         _nextActivePlayers: {
-          player: 'stage2',
+          currentPlayer: 'stage2',
           moveLimit: 1,
           next: {
-            player: 'stage3',
+            currentPlayer: 'stage3',
           },
         },
       });
@@ -706,7 +706,7 @@ describe('setActivePlayers', () => {
         activePlayers: { '0': 'stage2' },
         _prevActivePlayers: [],
         _nextActivePlayers: {
-          player: 'stage3',
+          currentPlayer: 'stage3',
         },
       });
 
@@ -772,7 +772,7 @@ describe('setActivePlayers', () => {
       const game = {
         turn: {
           activePlayers: {
-            player: { stage: 'play', moveLimit: 2 },
+            currentPlayer: { stage: 'play', moveLimit: 2 },
             others: { stage: 'play', moveLimit: 1 },
           },
           stages: {