MathGrid

A real-time multiplayer maths game for 2+ players. Players race to find three numbers in a line on a 6×6 grid that satisfy a target formula before their opponents do.

Built with Rails 8.1, Hotwire (Turbo Streams + Stimulus), PostgreSQL, and Redis.

---

How the game works

Setup

1. One player creates a game on the home page, enters their name, and chooses how many rounds to play (1–10).
2. A six-character access code is displayed in the lobby. Share it with the other players.
3. Other players join by entering the access code and their name on the home page.
4. The host can optionally enable No Multiplication mode (see below) in the lobby before starting.
5. The host clicks Start Game when everyone is in.

Playing a round

Each round shows:

• A 6×6 grid of numbers (1–9, randomly arranged)
• A target number
• The formula to use: A × B ± C (standard) or A + B ± C (No Multiplication mode)

Select three cells that form a valid line — horizontal, vertical, or either diagonal — where the numbers satisfy the formula and equal the target:

Standard mode:      A × B + C = target   or   A × B − C = target
No Multiplication:  A + B + C = target   or   A + B − C = target

The valid arrangements for the three numbers (a, b, c) along the line are:

• a × b ± c — first times middle, plus or minus last
• b × c ± a — middle times last, plus or minus first

The first player to click a valid three-cell line wins the round and scores a point. A winning formula is shown to all players before the next round begins automatically.

No Multiplication mode

Toggled by the host in the lobby. Uses addition instead of multiplication (A + B ± C), and targets are kept at 25 or below — suitable for younger players.

Solution button

The host has a Solution button during play. Clicking it reveals a valid answer for the current target (highlighting the cells and showing the formula), then generates a fresh target for the same round. The round number does not advance.

End of game

After all rounds are complete, a Final Scores screen is shown with the winner highlighted. Finished games appear on the Leaderboard.

---

Local development setup

1. Homebrew

Install Homebrew if you don't have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Ruby version manager (chruby + ruby-install)

brew install chruby ruby-install

Add chruby to your shell profile (~/.zshrc or ~/.bash_profile):

source $(brew --prefix)/share/chruby/chruby.sh
source $(brew --prefix)/share/chruby/auto.sh

Restart your terminal, then install the required Ruby version:

ruby-install ruby 3.3.10

Open a new terminal in the project directory — chruby will automatically switch to ruby-3.3.10 via the .ruby-version file.

3. PostgreSQL

brew install postgresql@16
brew services start postgresql@16

Add the PostgreSQL binaries to your PATH (add to ~/.zshrc):

export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"

4. Redis

brew install redis
brew services start redis

5. Project setup

bundle install
bin/rails db:create db:migrate

---

Running the app

bin/rails server

Visit http://localhost:3000.

---

Running the CI checks (lint + E2E tests)

The bin/ci script runs ESLint, RuboCop, and the full Playwright end-to-end test suite. PostgreSQL and Redis must be running before you call it.

bin/ci

The script will:

1. Ensure the git pre-push hook is configured
2. Lint JavaScript (ESLint)
3. Lint Ruby (RuboCop)
4. Verify PostgreSQL and Redis are reachable
5. Start a Rails server on port 8844 (separate from your dev server on 3000) if one is not already running there
6. Run all 13 Playwright tests in parallel (Chromium)
7. Stop the server it started (if any) on exit

To override the port:

CI_PORT=9000 bin/ci

---

Running Playwright tests directly

cd e2e
npx playwright test                  # headless, 3 workers
npx playwright test --headed         # watch the browser
npx playwright test --ui             # interactive UI mode
BASE_URL=http://localhost:8844 npx playwright test  # custom server URL

---

GitHub Actions

CI runs on every push to main and on pull requests. The pipeline has four jobs:

Job	What it does
scan_ruby	Brakeman (security) + bundler-audit (vulnerable gems)
scan_js	importmap audit (vulnerable JS packages)
lint	RuboCop
test	Full Playwright suite against a live Rails server with Postgres 16 + Redis 7

The test job spins up Postgres and Redis as service containers, prepares the database, builds assets, starts the Rails server, and then runs all Playwright tests. The Playwright HTML report is uploaded as an artifact on failure.