jace-games
by Jace OfficialJace Games: quick browser games with Sign in with Jace and scores synced to your Jace account. Snake, Memory Match, 2048, Minesweeper and more.
Jace Games
Quick browser games from Jace. Sign in with your Jace account to keep your scores, including the Snake and Memory Match scores from the old Jace site, and compete on leaderboards shared across Jace.
Next.js 16 (App Router), TypeScript and Tailwind 4, deployed on Vercel.
Games
| id | Game | Score | Better |
|---|---|---|---|
snake | Snake | Food eaten | Higher |
memory | Memory Match | Moves to clear | Lower |
2048 | 2048 | Points | Higher |
tetris | Block Stacker | Points | Higher |
minesweeper | Minesweeper | Seconds (9×9, 10 mines) | Lower |
flappy | Flappy Jace | Pipes passed | Higher |
breakout | Breakout | Points | Higher |
wordle | Word Guess | Guesses used (wins only) | Lower |
reaction | Reaction Time | Average of 5, in ms | Lower |
typing | Typing Speed | WPM over 30 s | Higher |
snake and memory keep the ids the original Jace site used, so old scores carry over. Never change an existing id.
Every game works with a keyboard (arrow keys/WASD, Enter to restart) and on a touchscreen (swipes, taps, on-screen pads).
Adding a game
- Add an entry to
GAMESinlib/games.ts: id, name, description, icon,better("higher"or"lower"), how to format the score,addedAt(shows a "New" badge for a month), andlimitsfor server-side validation. - Write the component in
components/games/. It receives{ onFinish(score, durationMs), best }and callsonFinishonce when a game ends. - Register it in
components/games/index.ts.
Setup
You need Node.js 20.9 or newer.
npm install
cp .env.example .env.local
Fill in .env.local, then run npm run dev and open http://localhost:3000.
Environment variables
| Name | Required | What it is |
|---|---|---|
JACE_CLIENT_ID | yes | The OAuth client id from Jace. |
JACE_CLIENT_SECRET | yes | The OAuth client secret from Jace. Server only, never sent to the browser. |
SESSION_SECRET | yes | 32+ random characters used to encrypt the session cookie. Generate with openssl rand -base64 32. Changing it signs everyone out. |
APP_URL | no | This app's public URL, used to build the redirect URI <APP_URL>/api/auth/callback. Defaults to the URL of the incoming request. Set it in production if you use more than one domain. |
JACE_URL | no | The Jace base URL. Defaults to https://jaceo.vercel.app. |
Put the same variables in Vercel → Project → Settings → Environment Variables. None of them use the NEXT_PUBLIC_ prefix, so none reach the client bundle. .env* files are gitignored (except .env.example).
Registering Jace Games in Jace
- Sign in to https://jaceo.vercel.app as the site owner (this makes it an official app, which skips the consent screen and can use the
scoresscope). - Go to profile → Manage account → Developer and register an app named "Jace Games".
- Add the redirect URIs, which must match exactly:
https://<your-vercel-domain>/api/auth/callbackhttp://localhost:3000/api/auth/callback(for local development)
- Copy the client id and secret into
JACE_CLIENT_IDandJACE_CLIENT_SECRET.
How it works
Sign in with Jace
Plain OAuth 2.0 authorization code flow (no OIDC):
/api/auth/signinstores a randomstatein a short-lived encrypted cookie and redirects toGET /oauth/authorize?scope=profile scores./api/auth/callbackchecksstate, exchanges the code atPOST /api/oauth/tokenwith the client secret (on the server), and callsGET /api/oauth/userinfo.- The access token and profile go into one HTTP-only, AES-256-GCM-encrypted cookie (
jg_session). Seelib/session.ts.
Every page load re-checks userinfo through /api/session. If Jace says banned, the person is signed out and sees "This Jace account is banned." A 401 from any Jace call also signs them out.
Scores
- Every finished game is saved to
localStoragefirst, with a UUID as itsexternal_id(lib/localScores.ts). - When signed in, pending scores go to
POST /api/scores. The server validates each score against the game'slimits(whole number, in range, and a plausible game length) before forwarding it to Jace's import endpoint. Becauseexternal_idmakes the import idempotent, retries never create duplicates. - Failed uploads stay pending and retry when the browser comes back online, when the tab becomes visible, and every minute (
components/ScoresProvider.tsx). - On sign-in, the player's Jace scores for every game (including old-site ones) are fetched and merged with local ones, deduplicated by id or by game, score and time.
- Scores played signed out are kept on the device. After signing in, the app offers to upload them to the Jace account.
- Leaderboards come from Jace (
/api/leaderboard→GET /api/oauth/leaderboard,order=ascfor lower-is-better games). Jace's API needs a user token, so signed-out players see their own device's best instead.
Before Jace ships the scores API
The scores scope and the /api/oauth/scores and /api/oauth/leaderboard endpoints are a contract Jace hasn't shipped yet. Until it does, those calls return 404, the app shows "Sync with Jace is coming soon", and scores stay on the device as pending. They upload on their own once the endpoints are live. If someone signed in before Jace accepted the scores scope (Jace answers 403 insufficient_scope), the app asks them to sign in again.
Testing against a mock Jace
scripts/mock-jace.mjs implements the whole contract locally, with an account ("oldplayer") that already has old Snake and Memory Match scores:
node scripts/mock-jace.mjs
JACE_URL=http://localhost:4000 npm run dev
The mock's authorize endpoint signs you in straight away. Start it with MOCK_SCORES=off to behave like Jace today (scores endpoints return 404), or MOCK_BANNED=1 to test the banned path.
Scripts
npm run dev: development servernpm run build: production buildnpm run lint: ESLintnpm run typecheck: TypeScript
Links
Versions
No versions published yet.