0.40.0

[delucis]

0.40.0

Contents

Breaking Changes

• Matches in the Lobby API (Issue [API, Lobby] Standardize "room" and "game" terms to "match" #703, PRs fix(api): Expose gameover metadata in rooms endpoints. #666, Fix #703 - Use the term "match" in the API and Lobby #704)
• Match IDs & metadata in clients (Issue Improve consistency around “match” vs “game” #763, PR feat: Improve consistency around “match” instead of “game” #765)
• Passing a custom uuid method to the Lobby API (PR feat(server): Expose API router #698)

New Features

• Timestamp metadata and match filtering in the Lobby API (Issue API: allow to query only active games #735, PR allow to filter listGames query #740)
• Plain JS Lobby Client (PR feat: Add plain JS lobby client #728)
• Expose the server’s API router (PR feat(server): Expose API router #698)

Breaking Changes

Matches in the Lobby API (Issue #703, PRs #666, #704)

Until now, the Lobby API has been slightly inconsistent in how it names an instance of a game, sometimes describing this as a “game” sometimes as a “room”. In release 0.40.0, this is standardised to “match”, making it clearer that you can play a game, like Chess or Tic-Tac-Toe, and the specific instance of a game is a match.

Changes

If you are using the provided React Lobby component, you shouldn’t see any breaking changes, but if you are consuming the Lobby REST API directly, you need to be aware of the following changes.

1. In JSON returned by the games/{name} endpoint:

   • rooms → matches

   • roomID → matchID

   {
   - "rooms": [
   + "matches": [
       {
   -     "roomID": "random-string",
   +     "matchID": "random-string",
         "players": {}        
       }
     ]
   }

2. In JSON returned by the games/{name}/create endpoint:

   • gameID → matchID

   {
   - "gameID": "random-string"
   + "matchID": "random-string"
   }

3. In JSON returned by the games/{name}/{id} endpoint:

   • roomID → matchID

   {
   - "roomID": "random-string",
   + "matchID": "random-string",
     "players": {}
   }

4. In JSON returned by the games/{name}/{id}/playAgain endpoint:

   • nextRoomID → nextMatchID

   {
   - "nextRoomID": "random-string"
   + "nextMatchID": "random-string"
   }

5. If writing Typescript and using the Server types namespace: Server.GameMetadata → Server.MatchData

Migration Help

• If you are writing Typescript, you can import types for the data returned by each of the API endpoints so you can know what shape to expect.

  import type { LobbyAPI } from 'boardgame.io';
  
  async function fetchMatches(gameName: string) {
    const response = await fetch(`http://localhost:8000/games/${gameName}`);
    const matches: LobbyAPI.MatchList = await response.json();
  }

• Even better, we now provide a plain Javascript Lobby API client. For example, you can can do client.listMatches('chess') and get a typed JSON response as in the example above. See under “New Features” below for more details.

Match IDs & metadata in clients (Issue #763, PR #765)

Reflecting the changes in the Lobby API, there are some minor changes to options and props in clients.

1. In React clients:

   • gameID → matchID

   import { Client } from 'boardgame.io/react';
   
   const App = Client({ game });
   
   export default () => (
   - <App gameID="xyz" />
   + <App matchID="xyz" />
   );

2. In plain JS clients:

   • gameID → matchID

   • updateGameID → updateMatchID

   • gameMetadata → matchData

   import { Client } from 'boardgame.io/client';
   
   const client = Client({
   - gameID: 'xyz',
   + matchID: 'xyz',
   });
   
   - client.updateGameID('abc');
   + client.updateMatchID('abc');
   
   - const metadata = client.gameMetadata;
   + const metadata = client.matchData;

3. For React board components, the gameMetadata prop has been renamed:

   • gameMetadata → matchData

   - const Board = ({ gameMetadata }) => (
   + const Board = ({ matchData }) => (
     <ul>
   -   {gameMetadata
   +   {matchData
         .map(player => (
           <li key={player.id}>{player.name}</li>
         ))
       }
     </ul>
   );

Passing a custom uuid method to the Lobby API (PR #698)

By default, boardgame.io uses shortid to generate match IDs and user credentials. Previously this could be customised by passing your own uuid method when running the server. This now has to be done when the server is instantiated, not at run time:

const uuid = () => 'id';

const server = Server({
+ uuid,
});

server.run({
  port: 8000,
- uuid,
});

New Features

Timestamp metadata and match filtering in the Lobby API (Issue #735, PR #740)

Match data now contains createdAt and updatedAt timestamps.

The REST API also supports a query string to filter matches when listing them. Three queries have been added:

• isGameover: allows listing only games that have or have not finished
• updatedBefore: allows filtering games last updated before a specific time
• updatedAfter: allows filtering games last updated after a specific time

An example query URL might look like:

https://lobby.api/games/chess?isGameover=false&updatedAfter=1592400449376

The actual filtering is performed by the storage backend, so if a storage implementation’s listGames method hasn’t been updated to support this yet, the API will continue to return unfiltered results.

Plain JS Lobby Client (PR #728)

The library now provides a lightweight, stateless wrapper around the Fetch API to simplify requests on the client. This is fully typed, so Typescript users should benefit from a better experience and if there are future API changes, these will be easier to refactor for.

Full documentation will be added to the Lobby docs, but here’s a taste:

import { LobbyClient } from 'boardgame.io/client';

const lobbyClient = new LobbyClient({ server: 'http://localhost:8000' });

lobbyClient.listMatches('tic-tac-toe', where: { isGameover: false })
  .then(data => console.log(data.matches));
   // => [
   //   {
   //     matchID: 'xyz',
   //     gameName: 'tic-tac-toe',
   //     players: [{ id: 0, name: 'Alice' }, { id: 1 }]
   //   },
   //   ...
   // ]

Expose the server’s API router (PR #698)

You can now access the Koa router instance used for the Lobby API when creating your server:

import { Server } from 'boardgame.io/server';

const server = Server({/* options */});

server.router.get('/custom-endpoint', (ctx, next) => {
  ctx.body = 'Custom Response'
});

server.run(8000);

[delucis]

@nicolodavis What do you think about merging this now that you’ve released the 0.39.15 patch? I’ve been thinking it may make sense to release 0.40 without the move signature refactor (#662) or other changes we initially planned. There are already enough significant changes here that it may make sense to break that further work into 0.41. Let me know what you think — I’m also happy to take on the move signature refactor when the time comes if you’d like.

Edit: As this updates docs too, I guess we shouldn’t merge this without releasing 0.40 shortly after as well.

[adngdb]

I am currently unable to build this branch locally, I get the following error:

Sorry, I forgot to npm install first. :-(