Document Random and Context

.github/workflows/static.yml

@@ -0,0 +1,43 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/CNAME

@@ -1 +1 @@
-boardgame.io
+bg.oc.is

docs/documentation/api/Context.md

@@ -0,0 +1,105 @@
+# Context
+
+Here are some examples on what the `ctx` Context parameter contains:
+
+## Simple Beginning Game
+
+This would be the context of a simple two player game without phases or stages that has just started:
+
+```js
+{
+  /** Number of players in the game */
+  numPlayers: 2,
+  /** List of player IDs in play order */
+  playOrder: ["A", "B"],
+  /** Current position in the play order */
+  playOrderPos: 0,
+  /**
+   * If there are stages, this is an Object containing all currently active players with their playerIds as fields and the stage they are in as content.
+   *
+   * Will be `null` if there are no stages.
+   * */
+  activePlayers: null,
+  /** playerID of the player that is acting right now */
+  currentPlayer: "A",
+  /** Number of moves that have been taken in the game already */
+  numMoves: 0,
+  /** Turn number of the current turn */
+  turn: 0,
+  /**
+   * Contains the return value of the `endIf` function in the `Game` object if the game is over.
+   *
+   * Is empty if the game is not over.
+   */
+  phase: null,
+}
+```
+
+## Simple In Progress Game
+
+This would be the context of the same game after it has just ended
+
+```js
+{
+  /** Number of players in the game */
+  numPlayers: 2,
+  /** List of player IDs in play order */
+  playOrder: ["A", "B"],
+  /** Current position in the play order */
+  playOrderPos: 1,
+  /**
+   * If there are stages, this is an Object containing all currently active players with their playerIds as fields and the stage they are in as content.
+   *
+   * Will be `null` if there are no stages.
+   * */
+  activePlayers: null,
+  /** playerID of the player that is acting right now */
+  currentPlayer: "B",
+  /** Number of moves that have been taken in the game already */
+  numMoves: 6,
+  /** Turn number of the current turn */
+  turn: 6,
+  /** Active phase of the game or `null` if there are no phases */
+  phase: null,
+  /**
+   * Contains the return value of the `endIf` function in the `Game` object if the game is over.
+   *
+   * Is empty if the game is not over.
+   */
+  gameOver: {
+    winner: "B",
+  },
+}
+```
+
+## Game with Phases and Stages
+
+This would be the context of a more complex game with phases and stages:
+
+```js
+{
+  /** Number of players in the game */
+  numPlayers: 4,
+  /** List of player IDs in play order */
+  playOrder: ["A", "B", "C", "D"],
+  /** Current position in the play order */
+  playOrderPos: 1,
+  /**
+   * If there are stages, this is an Object containing all currently active players with their playerIds as fields and the stage they are in as content.
+   *
+   * Will be `null` if there are no stages.
+   * */
+  activePlayers: {
+    A: "Choose Opponent",
+    B: "Choose Opponent",
+  },
+  /** playerID of the player that is acting right now */
+  currentPlayer: "B",
+  /** Number of moves that have been taken in the game already */
+  numMoves: 4,
+  /** Turn number of the current turn */
+  turn: 2,
+  /** Active phase of the game or `null` if there are no phases */
+  phase: "Building",
+}
+```

docs/documentation/events.md

@@ -51,9 +51,10 @@ This event ends the game. If you pass an argument to it,
 then that argument is made available in `ctx.gameover`.
 After the game is over, further state changes to the game
 (via a move or event) are not possible.
+In order to enable the included Bot/AI logic, you must specify the winner in the `endGame` event.
 
 ```js
-endGame();
+endGame({ winner: '2' });
 ```
 
 #### setStage

docs/documentation/multiplayer.md

@@ -144,6 +144,8 @@ Local({
 
 ## Remote Master
 
+// TODO icorporate our server setup
+
 You can also run the game master on a separate server. Any boardgame.io
 client can connect to this master (whether it is a browser, an Android
 app etc.) and it will be kept in sync with other clients in realtime.

docs/documentation/phases.md

@@ -8,8 +8,8 @@ entering a playing phase, for example.
 Each phase in [boardgame.io](https://boardgame.io/) defines a set
 of game configuration options that are applied for the duration
 of that phase. This includes the ability to define a different
-set of moves, use a different turn order etc. Turns happen
-inside phases.
+set of moves, use a different turn order etc. **Turns happen
+inside phases**.
 
 ### Card Game
 
@@ -20,19 +20,19 @@ two moves:
 - play a card from your hand onto the deck.
 
 ```js
-function DrawCard({ G, playerID }) {
+function drawCard({ G, playerID }) {
   G.deck--;
   G.hand[playerID]++;
 }
 
-function PlayCard({ G, playerID }) {
+function playCard({ G, playerID }) {
   G.deck++;
   G.hand[playerID]--;
 }
 
 const game = {
   setup: ({ ctx }) => ({ deck: 6, hand: Array(ctx.numPlayers).fill(0) }),
-  moves: { DrawCard, PlayCard },
+  moves: { drawCard, playCard },
   turn: { minMoves: 1, maxMoves: 1 },
 };
 ```
@@ -74,9 +74,7 @@ const game = {
 ```
 
 !> A phase that doesn't specify any moves just uses moves from
-the main `moves` section in the game. However, if it does,
-then the `moves` section in the phase overrides the global
-one.
+the main `moves` section in the game. 
 
 The game doesn't begin in any of these phases. In order to begin
 in the "draw" phase, we add a `start: true` to its config. Only
@@ -86,7 +84,7 @@ one phase can have `start: true`.
 phases: {
   draw: {
     moves: { DrawCard },
-+   start: true,
+    start: true,
   },
 
   play: {
@@ -102,8 +100,8 @@ empty.
 phases: {
   draw: {
     moves: { DrawCard },
-+   endIf: ({ G }) => (G.deck <= 0),
-+   next: 'play',
+    endIf: ({ G }) => (G.deck <= 0),
+    next: 'play',
     start: true,
   },
 

docs/documentation/sidebar.md

@@ -20,6 +20,7 @@
   - [TypeScript](typescript.md)
 - **Reference**
   - [Game](api/Game.md)
+  - [Context](api/Context.md)
   - [Client](api/Client.md)
   - [Server](api/Server.md)
   - [Lobby](api/Lobby.md)

docs/documentation/stages.md

@@ -1,6 +1,7 @@
 # Stages
 
-A stage is similar to a phase, except that it happens within a turn.
+Stages are a way to break a turn into smaller parts. They are useful
+when you want to restrict the set of moves that a player can make.
 A turn can be subdivided into many stages, each allowing a different
 set of moves during that stage.
 
@@ -40,7 +41,7 @@ const game = {
   turn: {
     stages: {
       discard: {
-        moves: { DiscardCard },
+        moves: { discardCard },
       },
     },
   },
@@ -144,16 +145,16 @@ Let's go back to the example we discussed earlier where we
 require every other player to discard a card when we play one:
 
 ```js
-function PlayCard({ events }) {
+function playCard({ events }) {
   events.setActivePlayers({ others: 'discard', minMoves: 1, maxMoves: 1 });
 }
 
 const game = {
-  moves: { PlayCard },
+  moves: { playCard },
   turn: {
     stages: {
       discard: {
-        moves: { Discard },
+        moves: { discard },
       },
     },
   },