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.
Create a project
Section titled “Create a project”The scaffolder copies the tic-tac-toe template into my-game/ and installs its dependencies.
npm create shoehive@latest my-gamepnpm create shoehive my-gameyarn create shoehive my-gamebun create shoehive my-gamePlay it
Section titled “Play it”Run the commands the scaffolder prints at the end:
cd my-gamenpm run devThis 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.
What is in the project
Section titled “What is in the project”| 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.
Change a rule
Section titled “Change a rule”Make the first move unable to take the centre cell. In src/game.ts, add two lines to the
place action:
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.
Test it
Section titled “Test it”Add a test to test/game.test.ts. It plays the game in memory, with no server and no
browser:
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:
npm testLook inside
Section titled “Look inside”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.
Scripts
Section titled “Scripts”| 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 |
Next steps
Section titled “Next steps”- 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 blankstarts from a minimal one-action game instead.
