Skip to content

Quick start

In five minutes you will have a two-player tic-tac-toe game running on your machine, and you will have changed one of its rules. You need Node.js 22 or newer.

The scaffolder copies the tic-tac-toe template into my-game/ and installs its dependencies.

Terminal window
npm create shoehive@latest my-game

Run the commands the scaffolder prints at the end:

Terminal window
cd my-game
npm run dev

This runs the web app with hot reload and the game server, which restarts whenever you change the game.

Open http://localhost:5173 in two browser windows, and make one of them private, so that each window is a different guest player. Create a table in one window and take a seat, then take the other seat in the second window. Play.

File What it is
src/game.ts The rules: state, actions, turns and when the game ends
test/game.test.ts Tests for the rules, run without a server or a browser
src/server.ts The game server: the WebSocket endpoint and the built app
web/App.tsx The React app: lobby, seats and board, using shoehive/react

The whole game is one defineGame call in src/game.ts. It has a starting state (setup), a turn order, and one action, place.

Make the first move unable to take the centre cell. In src/game.ts, add two lines to the place action:

src/game.ts
place: {
input: z.object({ cell: z.number().int().min(0).max(8) }),
run({ state, seat, input, ctx }) {
if (ctx.turn.seat !== seat) reject('NOT_YOUR_TURN');
if (state.board[input.cell]) reject('CELL_TAKEN');
const firstMove = state.board.every((cell) => cell === null);
if (firstMove && input.cell === 4) reject('CENTRE_ON_FIRST_MOVE');
state.board[input.cell] = seat === 0 ? 'X' : 'O';
state.winner = winnerOf(state.board);
if (state.winner) ctx.end({ winner: state.winner });
else ctx.turn.next();
},
},

reject() stops the action. Nothing it changed is kept, and the player gets the error code. Save the file: the game server restarts by itself. Start a new table and try the centre.

Add a test to test/game.test.ts. It plays the game in memory, with no server and no browser:

test/game.test.ts
it('does not allow the centre on the first move', async () => {
const t = await createTestTable(ticTacToe, { players: 2 });
await expect(t.act(0, 'place', { cell: 4 })).rejects.toMatchObject({
code: 'CENTRE_ON_FIRST_MOVE',
});
await t.act(0, 'place', { cell: 0 });
await t.act(1, 'place', { cell: 4 }); // fine after the first move
expect(t.state.board[4]).toBe('O');
});

Run the tests:

Terminal window
npm test

When the game server starts, it prints a devtools link. Open it to see every table's state, what each seat's view contains, and the action log, including your rejected centre move.

Command What it does
npm run dev Web app with hot reload, plus the game server in watch mode
npm test Runs the tests with Vitest
npm run typecheck Type-checks everything
npm run build Builds the web app for production
npm start Serves the built app and the game server on http://localhost:3000
  • The six concepts: the ideas behind what you just changed.
  • Tutorial: tic-tac-toe in 20 minutes: build this game from an empty file, including the React UI.
  • npm create shoehive@latest my-game -- --template blank starts from a minimal one-action game instead.