Simplify Random API (#119)

* run random ops directly

* make Random use global state to store / restore the PRNG state

* move seed initialization to Game

* inline fast-shuffle to fix Rollup issues

* set Die default to D6 to avoid returning null

Author: nicolodavis

docs/random.md

@@ -19,36 +19,22 @@ This poses interesting challenges regarding the implementation.
   and thus must be pure. Calling `Math.random()` and other functions that
   maintain external state would make the game logic impure and not idempotent.
 
-## Using Randomness in Games
-
-[boardgame.io]() takes a rather unusual approach to randomness: It disallows getting random variables directly.
-Instead, a game can ask the engine to generate random numbers, and the engine will inject those into the game on the next move.
+### Using Randomness in Games
 
 ```js
 import { Random } from 'boardgame.io/core';
 
-const SomeGame = Game({
+Game({
   moves: {
     rollDie(G, ctx) {
-      // G.diceValue will contain the requested
-      // die value at the end of this move.
-      return Random.D6(G, 'diceValue');
-    },
-  },
-
-  flow: {
-    onMove: G => {
-      const dice = G.diceValue;
-      // do something...
-      return { ...G };
+      return { ...G, dice: Random.D6() };
     },
   },
-  // ...
 });
 ```
 
-This will place a request to a D6 dice roll inside `G`.
-While processing the move, the request gets evaluated and the result placed into `diceValue`, where it can be used.
+!> The PRNG state is maintained inside `ctx._random` by the `Random`
+package automatically.
 
 ### Shuffles
 
@@ -67,33 +53,28 @@ const SomeGame = Game({
   }),
   moves: {
     shuffleDeck(G) {
-      return Random.Shuffle(G, 'deck');
+      return { ...G, deck: Random.Shuffle(G.deck) };
     },
   },
 });
 ```
 
-## Seed
+### Seed
 
-The library uses a `seed` in `ctx` that is stripped before it
+The library uses a `seed` in `ctx._random` that is stripped before it
 is sent to the client. All the code that needs randomness uses this
 `seed` to generate random numbers.
 
-You can override the initial `seed` in the `flow` section like this:
+You can override the initial `seed` like this:
 
 ```js
 Game({
+  seed: <somevalue>
   ...
-
-  flow: {
-    seed: <somevalue>
-
-    ...
-  }
 })
 ```
 
-## Background
+### Background
 
 There is an interesting background article by David Bau called [Random Seeds, Coded Hints, and Quintillions](http://davidbau.com/archives/2010/01/30/random_seeds_coded_hints_and_quintillions.html).
 Despite its age, this article gives insight on topics about randomness, like differentiating _local_ and _network_ entropy.

…ples/modules/shuffle/components/board.js …mples/modules/random/components/board.jsexamples/modules/shuffle/components/board.js renamed to examples/modules/random/components/board.js examples/modules/shuffle/components/board.js renamed to examples/modules/random/components/board.js

@@ -19,7 +19,7 @@ const App = Client({
 
 const SingleView = () => (
   <div style={{ padding: 50 }}>
-    <App gameID="Shuffle" />
+    <App gameID="Random" />
   </div>
 );
 

…mples/modules/shuffle/components/view.js …amples/modules/random/components/view.jsexamples/modules/shuffle/components/view.js renamed to examples/modules/random/components/view.js examples/modules/shuffle/components/view.js renamed to examples/modules/random/components/view.js

@@ -8,16 +8,18 @@
 
 import { Game, Random } from 'boardgame.io/core';
 
-const Shuffle = Game({
+const RandomExample = Game({
   name: 'shuffle',
 
   setup: () => ({
     deck: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'],
   }),
 
   moves: {
-    shuffle: G => Random.Shuffle(G, 'deck'),
+    shuffle: G => ({ ...G, deck: Random.Shuffle(G.deck) }),
+    rollDie: (G, ctx, value) => ({ ...G, dice: Random.Die(value) }),
+    rollD6: G => ({ ...G, dice: Random.D6() }),
   },
 });
 
-export default Shuffle;
+export default RandomExample;

examples/modules/shuffle/game.js examples/modules/random/game.jsexamples/modules/shuffle/game.js renamed to examples/modules/random/game.js

@@ -10,8 +10,8 @@ import View from './components/view';
 
 const routes = [
   {
-    path: '/shuffle/cards',
-    text: 'Shuffle Cards',
+    path: '/random/main',
+    text: 'Examples',
     component: View,
   },
 ];

examples/modules/shuffle/index.js examples/modules/random/index.jsexamples/modules/shuffle/index.js renamed to examples/modules/random/index.js

@@ -10,7 +10,7 @@ import tic_tac_toe from './tic-tac-toe';
 import chess from './chess';
 import phases from './phases';
 import liars_dice from './liars-dice';
-import shuffle from './shuffle';
+import random from './random';
 
 const routes = [
   {
@@ -30,8 +30,8 @@ const routes = [
     routes: liars_dice.routes,
   },
   {
-    name: 'Shuffle',
-    routes: shuffle.routes,
+    name: 'Random API',
+    routes: random.routes,
   },
 ];
 

examples/modules/shuffle/routes.js examples/modules/random/routes.jsexamples/modules/shuffle/routes.js renamed to examples/modules/random/routes.js

@@ -109,7 +109,6 @@
     "webpack": "^3.5.5"
   },
   "dependencies": {
-    "fast-shuffle": "^1.0.4",
     "koa": "^2.3.0",
     "koa-router": "^7.2.1",
     "koa-socket": "^4.4.0",

examples/modules/routes.js

@@ -32,7 +32,6 @@ const globals = {
   'react-json-view': 'ReactJson',
   mousetrap: 'Mousetrap',
   'socket.io-client': 'io',
-  'fast-shuffle': 'shuffle',
 };
 
 export default [
@@ -61,8 +60,6 @@ export default [
 
   {
     input: 'packages/core.js',
-    external: ['fast-shuffle'],
-    globals: { 'fast-shuffle': 'shuffle' },
     output: { file: 'dist/core.js', format: 'umd' },
     name: 'Core',
     plugins: plugins,