end phase when a turn order runs out

Author: darthfiddler

docs/turn-order.md

@@ -74,9 +74,10 @@ A `TurnOrder` object has the following structure:
 }
 ```
 
-The implementation above shows the default round-robin order.
-If you want to skip over every other player (for example), do
-something like this:
+!> The phase ends if `next()` returns `undefined`.
+
+The implementation above shows the default round-robin order that
+repeats indefinitely. If you want to skip over every other player (for example), do something like this:
 
 ```js
 import { Game } from 'boardgame.io/core';
@@ -95,7 +96,7 @@ Game({
 }
 ```
 
-You may also set `actionPlayers` from a `TurnOrder` object by
+!> You may also set `actionPlayers` from a `TurnOrder` object by
 returning an object of type `{ playOrderPos, actionPlayers }`.
 
 ```js

src/core/flow.js

@@ -459,8 +459,19 @@ export function FlowWithPhases({
       return { ...state, G, ctx: { ...ctx, gameover } };
     }
 
+    let endPhase = false;
+
     // Update turn order state.
-    ctx = UpdateTurnOrderState(G, ctx, conf.turnOrder, nextPlayer);
+    {
+      const { endPhase: a, ctx: b } = UpdateTurnOrderState(
+        G,
+        ctx,
+        conf.turnOrder,
+        nextPlayer
+      );
+      endPhase = a;
+      ctx = b;
+    }
 
     // Update turn.
     const turn = ctx.turn + 1;
@@ -473,11 +484,15 @@ export function FlowWithPhases({
     };
 
     // End phase if condition is met.
-    const end = shouldEndPhase(state);
-    if (end) {
+    const endPhaseArg = shouldEndPhase(state);
+    if (endPhaseArg) {
+      endPhase = true;
+    }
+
+    if (endPhase) {
       return this.dispatch(
         { ...state, G, ctx },
-        automaticGameEvent('endPhase', [end], this.playerID)
+        automaticGameEvent('endPhase', [endPhaseArg], this.playerID)
       );
     }
 

src/core/turn-order.js

@@ -95,7 +95,8 @@ export function InitTurnOrderState(G, ctx, turnOrder) {
 export function UpdateTurnOrderState(G, ctx, turnOrder, nextPlayer) {
   let playOrderPos = ctx.playOrderPos;
   let currentPlayer = ctx.currentPlayer;
-  let actionPlayers;
+  let actionPlayers = ctx.actionPlayers;
+  let endPhase = false;
 
   if (ctx.playOrder.includes(nextPlayer)) {
     playOrderPos = ctx.playOrder.indexOf(nextPlayer);
@@ -104,27 +105,33 @@ export function UpdateTurnOrderState(G, ctx, turnOrder, nextPlayer) {
   } else {
     const t = turnOrder.next(G, ctx);
 
-    if (t && t.playOrderPos !== undefined) {
-      playOrderPos = t.playOrderPos;
+    if (t == undefined) {
+      endPhase = true;
     } else {
-      playOrderPos = t;
-    }
+      if (t.playOrderPos !== undefined) {
+        playOrderPos = t.playOrderPos;
+      } else {
+        playOrderPos = t;
+      }
 
-    currentPlayer = getCurrentPlayer(ctx.playOrder, playOrderPos);
+      currentPlayer = getCurrentPlayer(ctx.playOrder, playOrderPos);
 
-    if (t && t.actionPlayers !== undefined) {
-      actionPlayers = t.actionPlayers;
-    } else {
-      actionPlayers = [currentPlayer];
+      if (t.actionPlayers !== undefined) {
+        actionPlayers = t.actionPlayers;
+      } else {
+        actionPlayers = [currentPlayer];
+      }
     }
   }
 
-  return {
+  ctx = {
     ...ctx,
     playOrderPos,
     currentPlayer,
     actionPlayers,
   };
+
+  return { endPhase, ctx };
 }
 
 export const TurnOrder = {
@@ -147,6 +154,8 @@ export const TurnOrder = {
    * first / next can also return an object of type
    * { playOrderPos, actionPlayers }
    * in which case they can also set actionPlayers simultaneously.
+   *
+   * The phase ends if next() returns undefined.
    */
 
   /**
@@ -159,6 +168,21 @@ export const TurnOrder = {
     next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.playOrder.length,
   },
 
+  /**
+   * ONCE
+   *
+   * Another round-robin turn order, but goes around just once.
+   * The phase ends after all players have played.
+   */
+  ONCE: {
+    first: () => 0,
+    next: (G, ctx) => {
+      if (ctx.playOrderPos < ctx.playOrder.length - 1) {
+        return ctx.playOrderPos + 1;
+      }
+    },
+  },
+
   /**
    * ANY
    *

src/core/turn-order.test.js

@@ -15,16 +15,39 @@ import { CreateGameReducer } from './reducer';
 describe('turnOrder', () => {
   test('default', () => {
     const flow = FlowWithPhases({
-      phases: [{ name: 'A' }],
+      phases: [{ name: 'A' }, { name: 'B' }],
     });
 
-    let state = { ctx: flow.ctx(10) };
+    let state = { ctx: flow.ctx(2) };
+    state = flow.init(state);
+    expect(state.ctx.currentPlayer).toBe('0');
+    expect(state.ctx.actionPlayers).toEqual(['0']);
+    state = flow.processGameEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('1');
+    expect(state.ctx.actionPlayers).toEqual(['1']);
+    state = flow.processGameEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('0');
+    expect(state.ctx.actionPlayers).toEqual(['0']);
+    expect(state.ctx.phase).toBe('A');
+  });
+
+  test('once', () => {
+    const flow = FlowWithPhases({
+      turnOrder: TurnOrder.ONCE,
+      phases: [{ name: 'A' }, { name: 'B' }],
+    });
+
+    let state = { ctx: flow.ctx(2) };
     state = flow.init(state);
     expect(state.ctx.currentPlayer).toBe('0');
     expect(state.ctx.actionPlayers).toEqual(['0']);
     state = flow.processGameEvent(state, gameEvent('endTurn'));
     expect(state.ctx.currentPlayer).toBe('1');
     expect(state.ctx.actionPlayers).toEqual(['1']);
+    state = flow.processGameEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('0');
+    expect(state.ctx.actionPlayers).toEqual(['0']);
+    expect(state.ctx.phase).toBe('B');
   });
 
   test('custom', () => {
@@ -247,17 +270,17 @@ describe('UpdateTurnOrderState', () => {
   };
 
   test('without nextPlayer', () => {
-    const t = UpdateTurnOrderState(G, ctx, TurnOrder.DEFAULT);
+    const { ctx: t } = UpdateTurnOrderState(G, ctx, TurnOrder.DEFAULT);
     expect(t).toMatchObject({ currentPlayer: '1' });
   });
 
   test('with nextPlayer', () => {
-    const t = UpdateTurnOrderState(G, ctx, TurnOrder.DEFAULT, '2');
+    const { ctx: t } = UpdateTurnOrderState(G, ctx, TurnOrder.DEFAULT, '2');
     expect(t).toMatchObject({ currentPlayer: '2' });
   });
 
   test('with actionPlayers', () => {
-    const t = UpdateTurnOrderState(G, ctx, TurnOrder.ANY);
+    const { ctx: t } = UpdateTurnOrderState(G, ctx, TurnOrder.ANY);
     expect(t).toMatchObject({
       currentPlayer: '1',
       actionPlayers: ['0', '1', '2'],