allow calling setActionPlayers via TurnOrder objects

Author: nicolodavis

docs/CHANGELOG.md

@@ -61,6 +61,32 @@ endTurnIf: () => ({ next: playerID })
 6. The semantics of enabling / disabling events has changed
    a bit: see https://boardgame.io/#/events for more details.
 
+7. TurnOrder objects now support `setActionPlayers` args.
+   Instead of returning `actionPlayers` in `first` / `next`,
+   add an `actionPlayers` section instead.
+
+```
+// old
+{
+  first: (G, ctx) => {
+    playOrderPos: 0,
+    actionPlayers: [...ctx.playOrder],
+  },
+
+  next: (G, ctx) => {
+    playOrderPos: ctx.playOrderPos + 1,
+    actionPlayers: [...ctx.playOrder],
+  },
+}
+
+// new
+{
+  first: (G, ctx) => 0,
+  next: (G, ctx) => ctx.playOrderPos + 1,
+  actionPlayers: { all: true },
+}
+```
+
 ## v0.26.3
 
 #### Features

docs/turn-order.md

@@ -120,11 +120,20 @@ A `TurnOrder` object has the following structure:
 
 ```js
 {
-  // Get the initial value of playOrderPos,
+  // Get the initial value of playOrderPos.
+  // This is called at the beginning of the phase.
   first: (G, ctx) => 0,
 
-  // Get the next value of playOrderPos when endTurn is called.
+  // Get the next value of playOrderPos.
+  // This is called at the end of each turn.
   next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.numPlayers,
+
+  // If this section is present, setActionPlayers is called
+  // at the beginning of the phase with the object below as
+  // argument.
+  actionPlayers: {
+    ...
+  },
 }
 ```
 
@@ -150,28 +159,6 @@ Game({
 }
 ```
 
-You may also set `actionPlayers` from a `TurnOrder` object by
-returning an object of type:
-
-```js
-{
-  playOrderPos, actionPlayers;
-}
-```
-
-```js
-{
-  // Get the initial value of playOrderPos,
-  first: (G, ctx) => { playOrderPos: 0, actionPlayers: ['0'] }
-
-  // Get the next value of playOrderPos when endTurn is called.
-  next: (G, ctx) => {
-    const playOrderPos = (ctx.playOrderPos + 1) % ctx.numPlayers;
-    const actionPlayers = ['0', '1'];
-    return { playOrderPos, actionPlayers };
-}
-```
-
 ### endTurn / endTurnIf
 
 You can also specify the next player during the `endTurn` event.

src/core/flow.js

@@ -7,7 +7,7 @@
  */
 
 import {
-  SetActionPlayers,
+  SetActionPlayersEvent,
   InitTurnOrderState,
   UpdateTurnOrderState,
   TurnOrder,
@@ -673,7 +673,7 @@ export function FlowWithPhases({
     endTurn: endTurnEvent,
     endPhase: endPhaseEvent,
     endGame: endGameEvent,
-    setActionPlayers: SetActionPlayers,
+    setActionPlayers: SetActionPlayersEvent,
   };
 
   let enabledEvents = {};

src/core/turn-order.js

@@ -47,34 +47,33 @@ export const Pass = (G, ctx) => {
  *                       // (after which they're pruned from actionPlayers).
  *   }
  */
-export function SetActionPlayers(state, arg) {
+export function SetActionPlayersEvent(state, arg) {
+  return { ...state, ctx: setActionPlayers(state.ctx, arg) };
+}
+
+function setActionPlayers(ctx, arg) {
   let actionPlayers = [];
 
   if (arg.value) {
     actionPlayers = arg.value;
   }
   if (arg.all) {
-    actionPlayers = [...state.ctx.playOrder];
+    actionPlayers = [...ctx.playOrder];
   }
 
   if (arg.allOthers) {
-    actionPlayers = [...state.ctx.playOrder].filter(
-      nr => nr !== state.ctx.currentPlayer
-    );
+    actionPlayers = [...ctx.playOrder].filter(nr => nr !== ctx.currentPlayer);
   }
 
   if (Array.isArray(arg)) {
     actionPlayers = arg;
   }
 
   return {
-    ...state,
-    ctx: {
-      ...state.ctx,
-      actionPlayers,
-      _actionPlayersOnce: arg.once,
-      _actionPlayersAllOthers: arg.allOthers,
-    },
+    ...ctx,
+    actionPlayers,
+    _actionPlayersOnce: arg.once,
+    _actionPlayersAllOthers: arg.allOthers,
   };
 }
 
@@ -94,26 +93,16 @@ function getCurrentPlayer(playOrder, playOrderPos) {
  * @param {object} turnOrder - A turn order object for this phase.
  */
 export function InitTurnOrderState(G, ctx, turnOrder) {
-  let playOrderPos;
-  let actionPlayers;
-
-  const t = turnOrder.first(G, ctx);
-
-  if (t.playOrderPos !== undefined) {
-    playOrderPos = t.playOrderPos;
-  } else {
-    playOrderPos = t;
-  }
-
+  const playOrderPos = turnOrder.first(G, ctx);
   const currentPlayer = getCurrentPlayer(ctx.playOrder, playOrderPos);
 
-  if (t.actionPlayers !== undefined) {
-    actionPlayers = t.actionPlayers;
+  if (turnOrder.actionPlayers !== undefined) {
+    ctx = setActionPlayers(ctx, turnOrder.actionPlayers);
   } else {
-    actionPlayers = [currentPlayer];
+    ctx = { ...ctx, actionPlayers: [currentPlayer] };
   }
 
-  return { ...ctx, currentPlayer, playOrderPos, actionPlayers };
+  return { ...ctx, currentPlayer, playOrderPos };
 }
 
 /**
@@ -141,20 +130,13 @@ export function UpdateTurnOrderState(G, ctx, turnOrder, endTurnArg) {
   } else {
     const t = turnOrder.next(G, ctx);
 
-    if (t == undefined) {
+    if (t === undefined) {
       endPhase = true;
     } else {
-      if (t.playOrderPos !== undefined) {
-        playOrderPos = t.playOrderPos;
-      } else {
-        playOrderPos = t;
-      }
-
+      playOrderPos = t;
       currentPlayer = getCurrentPlayer(ctx.playOrder, playOrderPos);
 
-      if (t.actionPlayers !== undefined) {
-        actionPlayers = t.actionPlayers;
-      } else {
+      if (turnOrder.actionPlayers === undefined) {
         actionPlayers = [currentPlayer];
       }
     }
@@ -179,9 +161,9 @@ export function UpdateTurnOrderState(G, ctx, turnOrder, endTurnArg) {
  * begins, and also a function `next` to determine who the
  * next player is when the turn ends.
  *
- * first / next can also return an object of type
- * { playOrderPos, actionPlayers }
- * in which case they can also set actionPlayers simultaneously.
+ * Objects can also contain an actionPlayers section which
+ * is passed to SetActionPlayers above at the beginning of
+ * the phase.
  *
  * The phase ends if next() returns undefined.
  */
@@ -217,16 +199,9 @@ export const TurnOrder = {
    * currentPlayer switches around in round-robin fashion, but any player can play on each turn.
    */
   ANY: {
-    first: (G, ctx) => {
-      return {
-        actionPlayers: [...ctx.playOrder],
-        playOrderPos: ctx.playOrderPos,
-      };
-    },
-    next: (G, ctx) => {
-      const playOrderPos = (ctx.playOrderPos + 1) % ctx.playOrder.length;
-      return { actionPlayers: [...ctx.playOrder], playOrderPos };
-    },
+    first: (G, ctx) => ctx.playOrderPos,
+    next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.playOrder.length,
+    actionPlayers: { all: true },
   },
 
   /**

src/core/turn-order.test.js

@@ -324,7 +324,7 @@ describe('UpdateTurnOrderState', () => {
     currentPlayer: '0',
     playOrder: ['0', '1', '2'],
     playOrderPos: 0,
-    actionPlayers: ['0'],
+    actionPlayers: ['0', '1', '2'],
   };
 
   test('without next player', () => {