Merge 3506bd8 into c93b316

benchmark/index.js

@@ -14,7 +14,7 @@ import { makeMove, gameEvent } from '../src/core/action-creators';
 
 const game = {
   moves: {
-    A: (G) => G,
+    A: ({ G }) => G,
   },
   endIf: () => false,
 };

docs/documentation/api/Game.md

@@ -10,7 +10,7 @@
   // Function that returns the initial value of G.
   // setupData is an optional custom object that is
   // passed through the Game Creation API.
-  setup: (ctx, setupData) => G,
+  setup: ({ ctx, ...plugins }, setupData) => G,
 
   // Optional function to validate the setupData before
   // matches are created. If this returns a value,
@@ -20,12 +20,12 @@
 
   moves: {
     // short-form move.
-    A: (G, ctx, ...args) => {},
+    A: ({ G, ctx, playerID, events, random, ...plugins }, ...args) => {},
 
     // long-form move.
     B: {
       // The move function.
-      move: (G, ctx, ...args) => {},
+      move: ({ G, ctx, playerID, events, random, ...plugins }, ...args) => {},
       // Prevents undoing the move.
       undoable: false,
       // Prevents the move arguments from showing up in the log.
@@ -43,7 +43,7 @@
   // Everything below is OPTIONAL.
 
   // Function that allows you to tailor the game state to a specific player.
-  playerView: (G, ctx, playerID) => G,
+  playerView: ({ G, ctx, playerID }) => G,
 
   // The seed used by the pseudo-random number generator.
   seed: 'random-string',
@@ -53,16 +53,19 @@
     order: TurnOrder.DEFAULT,
 
     // Called at the beginning of a turn.
-    onBegin: (G, ctx) => G,
+    onBegin: ({ G, ctx, events, random, ...plugins }) => G,
 
     // Called at the end of a turn.
-    onEnd: (G, ctx) => G,
+    onEnd: ({ G, ctx, events, random, ...plugins }) => G,
 
     // Ends the turn if this returns true.
-    endIf: (G, ctx) => true,
+    // Returning { next }, sets next playerID.
+    endIf: ({ G, ctx, random, ...plugins }) => (
+      true | { next: '0' }
+    ),
 
-    // Called at the end of each move.
-    onMove: (G, ctx) => G,
+    // Called after each move.
+    onMove: ({ G, ctx, events, random, ...plugins }) => G,
 
     // Prevents ending the turn before a minimum number of moves.
     minMoves: 1,
@@ -91,13 +94,13 @@
   phases: {
     A: {
       // Called at the beginning of a phase.
-      onBegin: (G, ctx) => G,
+      onBegin: ({ G, ctx, events, random, ...plugins }) => G,
 
       // Called at the end of a phase.
-      onEnd: (G, ctx) => G,
+      onEnd: ({ G, ctx, events, random, ...plugins }) => G,
 
       // Ends the phase if this returns true.
-      endIf: (G, ctx) => true,
+      endIf: ({ G, ctx, random, ...plugins }) => true,
 
       // Overrides `moves` for the duration of this phase.
       moves: { ... },
@@ -109,7 +112,7 @@
       start: true,
 
       // Set the phase to enter when this phase ends.
-      // Can also be a function: (G, ctx) => 'nextPhaseName'
+      // Can also be a function: ({ G, ctx }) => 'nextPhaseName'
       next: 'nextPhaseName',
     },
 
@@ -123,11 +126,11 @@
 
   // Ends the game if this returns anything.
   // The return value is available in `ctx.gameover`.
-  endIf: (G, ctx) => obj,
+  endIf: ({ G, ctx, random, ...plugins }) => obj,
 
   // Called at the end of the game.
   // `ctx.gameover` is available at this point.
-  onEnd: (G, ctx) => G,
+  onEnd: ({ G, ctx, events, random, ...plugins }) => G,
 
   // Disable undo feature for all the moves in the game
   disableUndo: true,

docs/documentation/concepts.md

@@ -41,7 +41,7 @@ immutability is handled by the framework.
 
 ```js
 moves: {
-  drawCard: (G, ctx) => {
+  drawCard: ({ G, ctx }) => {
     const card = G.deck.pop();
     G.hand.push(card);
   },
@@ -78,7 +78,7 @@ onClick() {
 
 ### Events
 
-These are framework-provided functions that are analagous to moves, except that they work on `ctx`. These typically advance the game state by doing things like
+These are framework-provided functions that are analogous to moves, except that they work on `ctx`. These typically advance the game state by doing things like
 ending the turn, changing the game phase etc.
 Events are dispatched from the client in a similar way to moves.
 

docs/documentation/debugging.md

@@ -25,8 +25,8 @@ It can sometimes be helpful to surface some metadata during a move.
 You can do this by using the log plugin. For example,
 
 ```js
-const move = (G, ctx) => {
-  ctx.log.setMetadata('metadata for this move');
+const move = ({ log }) => {
+  log.setMetadata('metadata for this move');
 };
 ```
 

docs/documentation/events.md

@@ -82,12 +82,13 @@ for more details.
 
 You can trigger events from a move or code inside
 your game logic (a phase’s `onBegin` hook, for example).
-This is done through the `ctx.events` object:
+This is done through the `events` API in the object passed
+as the first argument to moves:
 
 ```js
 moves: {
-  drawCard: (G, ctx) => {
-    ctx.events.endPhase();
+  drawCard: ({ G, ctx, events }) => {
+    events.endPhase();
   };
 }
 ```

docs/documentation/immutability.md

@@ -16,7 +16,7 @@ A traditional pure function just accepts arguments and then
 returns the new state. Something like this:
 
 ```js
-function move(G, ctx) {
+function move({ G }) {
   // Return new value of G without modifying the arguments.
   return { ...G, hand: G.hand + 1 };
 }
@@ -33,7 +33,7 @@ immutability principle. Both styles are supported interchangeably,
 so use the one that you prefer.
 
 ```js
-function move(G, ctx) {
+function move({ G }) {
   G.hand++;
 }
 ```
@@ -42,7 +42,9 @@ function move(G, ctx) {
 In fact, returning something while also mutating `G` is
 considered an error.
 
-!> `ctx` is a read-only object and is never modified in either style.
+!> You can only modify `G`. Other values passed to your moves
+   are read-only and should never be modified in either style.
+   Changes to `ctx` can be made using [events](events.md).
 
 ### Invalid moves
 
@@ -57,7 +59,7 @@ Tic-Tac-Toe.
 import { INVALID_MOVE } from 'boardgame.io/core';
 
 moves: {
-  clickCell: function(G, ctx, id) {
+  clickCell: function({ G, ctx }, id) {
     // Illegal move: Cell is filled.
     if (G.cells[id] !== null) {
       return INVALID_MOVE;

docs/documentation/phases.md

@@ -20,18 +20,18 @@ two moves:
 - play a card from your hand onto the deck.
 
 ```js
-function DrawCard(G, ctx) {
+function DrawCard({ G, playerID }) {
   G.deck--;
-  G.hand[ctx.currentPlayer]++;
+  G.hand[playerID]++;
 }
 
-function PlayCard(G, ctx) {
+function PlayCard({ G, playerID }) {
   G.deck++;
-  G.hand[ctx.currentPlayer]--;
+  G.hand[playerID]--;
 }
 
 const game = {
-  setup: ctx => ({ deck: 6, hand: Array(ctx.numPlayers).fill(0) }),
+  setup: ({ ctx }) => ({ deck: 6, hand: Array(ctx.numPlayers).fill(0) }),
   moves: { DrawCard, PlayCard },
   turn: { minMoves: 1, maxMoves: 1 },
 };
@@ -58,7 +58,7 @@ list of moves, which come into effect during that phase:
 
 ```js
 const game = {
-  setup: ctx => ({ deck: 6, hand: Array(ctx.numPlayers).fill(0) }),
+  setup: ({ ctx }) => ({ deck: 6, hand: Array(ctx.numPlayers).fill(0) }),
   turn: { minMoves: 1, maxMoves: 1 },
 
   phases: {
@@ -102,7 +102,7 @@ empty.
 phases: {
   draw: {
     moves: { DrawCard },
-+   endIf: G => (G.deck <= 0),
++   endIf: ({ G }) => (G.deck <= 0),
 +   next: 'play',
     start: true,
   },
@@ -134,8 +134,8 @@ You can also run code automatically at the beginning or end of a phase. These ar
 ```js
 phases: {
   phaseA: {
-    onBegin: (G, ctx) => { ... },
-    onEnd: (G, ctx) => { ... },
+    onBegin: ({ G, ctx }) => { ... },
+    onEnd: ({ G, ctx }) => { ... },
   },
 };
 ```
@@ -170,7 +170,7 @@ You can also end a phase by returning a truthy value from its
 phases: {
   phaseA: {
     next: 'phaseB',
-    endIf: (G, ctx) => true,
+    endIf: ({ G, ctx }) => true,
   },
   phaseB: { ... },
 },
@@ -188,7 +188,7 @@ state at the end of the phase:
 ```js
 phases: {
   phaseA: {
-    next: (G, ctx) => {
+    next: ({ G }) => {
       return G.condition ? 'phaseC' : 'phaseB';
     },
   },

docs/documentation/plugins.md

@@ -34,9 +34,9 @@ A plugin is an object that contains the following fields.
   // wrapper can modify G before passing it down to
   // the wrapped function. It is a good practice to
   // undo the change at the end of the call.
-  fnWrap: (fn) => (G, ctx, ...args) => {
+  fnWrap: (fn) => ({ G, ...rest }, ...args) => {
     G = preprocess(G);
-    G = fn(G, ctx, ...args);
+    G = fn({ G, ...rest }, ...args);
     G = postprocess(G);
     return G;
   },
@@ -70,11 +70,9 @@ import { PluginA, PluginB } from 'boardgame.io/plugins';
 const game = {
   name: 'my-game',
 
-  moves: {
-    ...
-  },
-
   plugins: [PluginA, PluginB],
+
+  // ...
 };
 ```