feat: Add endStage and setStage events (#458)

* refactor: Move `activePlayers` reset logic to reuseable function

This moves the logic that resets an empty `activePlayers` to next, 
previous or `null` values into `UpdateActivePlayers`, so that it can be 
called from an `EndStage` event and not just inside `ProcessMove`.

* feat: Add `startStage` and `endStage` events

* test: Fix failing tests with new events

* test: Write basic tests for `setStage` and `endStage`

* feat: Add hypothetical move limit logic

If `arg.moveLimit` could reach `UpdateStage` this logic would update 
`ctx` appropriately.

* test: Add failing test for move limit with `setStage`

* feat: Bail out of `UpdateStage` early if `arg` is undefined

* feat: Allow `setStage` event to receive object argument

Supports `moveLimit` with an object argument: `setStage({ stage, 
moveLimit })`

* test: Update `setStage` move limit test with object syntax

* test: Add test for `setStage` object syntax without move limit

* test: Test how `setStage` & `endStage` mutate `_activePlayersNumMoves`

* test: Add test for `endStage` with more than one currently active player

* refactor: Use `EndStage` to simplify `ProcessMove`

Allow a `playerID` to be passed to `EndStage` and `UpdateStage` so they 
can be used to end/update any player in `activePlayers`. They default to 
`ctx.currentPlayer` when called from the client, which could need 
changing once any active player can call events.

* test: Increase `setStage`/`endStage` coverage

* refactor: Rename `UpdateActivePlayers` to `UpdateActivePlayersOnceEmpty`

* refactor: Don’t call no-op `UpdateStage` when `arg` is undefined

* group event defaults

* remove redundant statement

Author: delucis

src/client/client.test.js

@@ -335,7 +335,12 @@ describe('event dispatchers', () => {
   test('default', () => {
     const game = {};
     const client = Client({ game });
-    expect(Object.keys(client.events)).toEqual(['endTurn', 'setActivePlayers']);
+    expect(Object.keys(client.events)).toEqual([
+      'endTurn',
+      'setActivePlayers',
+      'endStage',
+      'setStage',
+    ]);
     expect(client.getState().ctx.turn).toBe(1);
     client.events.endTurn();
     expect(client.getState().ctx.turn).toBe(2);
@@ -355,6 +360,8 @@ describe('event dispatchers', () => {
       'setPhase',
       'endGame',
       'setActivePlayers',
+      'endStage',
+      'setStage',
     ]);
     expect(client.getState().ctx.turn).toBe(1);
     client.events.endTurn();
@@ -367,6 +374,7 @@ describe('event dispatchers', () => {
         endPhase: false,
         endTurn: false,
         setActivePlayers: false,
+        endStage: false,
       },
     };
     const client = Client({ game });

src/core/flow.js

@@ -9,6 +9,7 @@
 import {
   SetActivePlayersEvent,
   SetActivePlayers,
+  UpdateActivePlayersOnceEmpty,
   InitTurnOrderState,
   UpdateTurnOrderState,
   Stage,
@@ -208,10 +209,12 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
   if (events.setActivePlayers === undefined) {
     events.setActivePlayers = true;
   }
+  if (events.endStage === undefined) {
+    events.endStage = true;
+    events.setStage = true;
+  }
   if (events.endPhase === undefined && phases) {
     events.endPhase = true;
-  }
-  if (events.setPhase === undefined && phases) {
     events.setPhase = true;
   }
   if (events.endTurn === undefined) {
@@ -498,6 +501,43 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
     return state;
   }
 
+  function UpdateStage(state, { arg, playerID }) {
+    if (typeof arg === 'string') {
+      arg = { stage: arg };
+    }
+
+    let { ctx } = state;
+    let {
+      activePlayers,
+      _activePlayersMoveLimit,
+      _activePlayersNumMoves,
+    } = ctx;
+
+    if (arg.stage) {
+      if (activePlayers === null) {
+        activePlayers = {};
+      }
+      activePlayers[playerID] = arg.stage;
+      _activePlayersNumMoves[playerID] = 0;
+
+      if (arg.moveLimit) {
+        if (_activePlayersMoveLimit === null) {
+          _activePlayersMoveLimit = {};
+        }
+        _activePlayersMoveLimit[playerID] = arg.moveLimit;
+      }
+    }
+
+    ctx = {
+      ...ctx,
+      activePlayers,
+      _activePlayersMoveLimit,
+      _activePlayersNumMoves,
+    };
+
+    return { ...state, ctx };
+  }
+
   ///////////////
   // ShouldEnd //
   ///////////////
@@ -631,6 +671,63 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
     return { ...state, G, ctx, deltalog, _undo: [], _redo: [] };
   }
 
+  function EndStage(state, { arg, next, automatic, playerID }) {
+    playerID = playerID || state.ctx.currentPlayer;
+
+    let { ctx } = state;
+    let { activePlayers, _activePlayersMoveLimit } = ctx;
+
+    if (next && arg) {
+      next.push({ fn: UpdateStage, arg, playerID });
+    }
+
+    // If player isn’t in a stage, there is nothing else to do.
+    if (activePlayers === null || !(playerID in activePlayers)) {
+      return state;
+    }
+
+    // Remove player from activePlayers.
+    activePlayers = Object.keys(activePlayers)
+      .filter(id => id !== playerID)
+      .reduce((obj, key) => {
+        obj[key] = activePlayers[key];
+        return obj;
+      }, {});
+
+    if (_activePlayersMoveLimit) {
+      // Remove player from _activePlayersMoveLimit.
+      _activePlayersMoveLimit = Object.keys(_activePlayersMoveLimit)
+        .filter(id => id !== playerID)
+        .reduce((obj, key) => {
+          obj[key] = _activePlayersMoveLimit[key];
+          return obj;
+        }, {});
+    }
+
+    ctx = UpdateActivePlayersOnceEmpty({
+      ...ctx,
+      activePlayers,
+      _activePlayersMoveLimit,
+    });
+
+    // Add log entry.
+    const action = gameEvent('endStage', arg);
+    const logEntry = {
+      action,
+      _stateID: state._stateID,
+      turn: state.ctx.turn,
+      phase: state.ctx.phase,
+    };
+
+    if (automatic) {
+      logEntry.automatic = true;
+    }
+
+    const deltalog = [...(state.deltalog || []), logEntry];
+
+    return { ...state, ctx, deltalog };
+  }
+
   /**
    * Retrieves the relevant move that can be played by playerID.
    *
@@ -683,57 +780,11 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
     let conf = GetPhase(state.ctx);
 
     let { ctx } = state;
-    let {
-      activePlayers,
-      _activePlayersMoveLimit,
-      _activePlayersNumMoves,
-      _prevActivePlayers,
-    } = ctx;
+    let { _activePlayersNumMoves } = ctx;
 
     const { playerID } = action;
 
-    if (activePlayers) _activePlayersNumMoves[playerID]++;
-
-    if (
-      _activePlayersMoveLimit &&
-      _activePlayersNumMoves[playerID] >= _activePlayersMoveLimit[playerID]
-    ) {
-      activePlayers = Object.keys(activePlayers)
-        .filter(id => id !== playerID)
-        .reduce((obj, key) => {
-          obj[key] = activePlayers[key];
-          return obj;
-        }, {});
-      _activePlayersMoveLimit = Object.keys(_activePlayersMoveLimit)
-        .filter(id => id !== playerID)
-        .reduce((obj, key) => {
-          obj[key] = _activePlayersMoveLimit[key];
-          return obj;
-        }, {});
-    }
-
-    if (activePlayers && Object.keys(activePlayers).length == 0) {
-      if (ctx._nextActivePlayers) {
-        ctx = SetActivePlayers(ctx, ctx._nextActivePlayers);
-        ({
-          activePlayers,
-          _activePlayersMoveLimit,
-          _activePlayersNumMoves,
-          _prevActivePlayers,
-        } = ctx);
-      } else if (_prevActivePlayers.length > 0) {
-        const lastIndex = _prevActivePlayers.length - 1;
-        ({
-          activePlayers,
-          _activePlayersMoveLimit,
-          _activePlayersNumMoves,
-        } = _prevActivePlayers[lastIndex]);
-        _prevActivePlayers = _prevActivePlayers.slice(0, lastIndex);
-      } else {
-        activePlayers = null;
-        _activePlayersMoveLimit = null;
-      }
-    }
+    if (ctx.activePlayers) _activePlayersNumMoves[playerID]++;
 
     let numMoves = state.ctx.numMoves;
     if (playerID == state.ctx.currentPlayer) {
@@ -744,14 +795,18 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
       ...state,
       ctx: {
         ...ctx,
-        activePlayers,
-        _activePlayersMoveLimit,
-        _activePlayersNumMoves,
-        _prevActivePlayers,
         numMoves,
+        _activePlayersNumMoves,
       },
     };
 
+    if (
+      ctx._activePlayersMoveLimit &&
+      _activePlayersNumMoves[playerID] >= ctx._activePlayersMoveLimit[playerID]
+    ) {
+      state = EndStage(state, { playerID, automatic: true });
+    }
+
     const G = conf.turn.onMove(state.G, state.ctx, action);
     state = { ...state, G };
 
@@ -772,6 +827,14 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
     return ProcessEvents(state, events);
   }
 
+  function SetStageEvent(state, arg) {
+    return ProcessEvents(state, [{ fn: EndStage, arg }]);
+  }
+
+  function EndStageEvent(state) {
+    return ProcessEvents(state, [{ fn: EndStage }]);
+  }
+
   function SetPhaseEvent(state, newPhase) {
     return ProcessEvents(state, [
       {
@@ -802,6 +865,8 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
   }
 
   const eventHandlers = {
+    endStage: EndStageEvent,
+    setStage: SetStageEvent,
     endTurn: EndTurnEvent,
     endPhase: EndPhaseEvent,
     setPhase: SetPhaseEvent,
@@ -823,6 +888,10 @@ export function Flow({ moves, phases, endIf, turn, events, plugins }) {
   if (events.setActivePlayers) {
     enabledEvents['setActivePlayers'] = true;
   }
+  if (events.endStage) {
+    enabledEvents['endStage'] = true;
+    enabledEvents['setStage'] = true;
+  }
 
   return FlowInternal({
     ctx: numPlayers => ({