Smash Ladder NA

Live at smash-ladder-na.vercel.app · Community: Discord

A ranked ladder site for the NA Super Smash Bros. Ultimate community. Players sign in with Discord, get matched 1v1 through a lobby queue, self-report best-of-3 results, and climb a seasonal rating. The site also supports casual free-battle matchmaking, community tournaments (bracket hosted on start.gg, with live entrant/standing data pulled in automatically), character leaderboards, and moderation tooling for disputes and conduct reports.

Independent from — and not affiliated with — Japan's Smashmate or other existing Smash matchmaking platforms; this is an unrelated, separately-run project built for the NA scene.

Why this exists

There are existing closed-source matchmaking platforms for Smash in NA. This project's angle is being open-source: the community can inspect, contribute to, and shape the platform directly, and the moderation policies that govern ranked play are transparent rather than a black box.

Features

• Ranked ladder — lobby-based matchmaking, best-of-3 stage striking, self-reported results with a dispute flow when reports disagree, and a per-season rating (Glicko-2 from Season 1 on; Elo before that).
• Free battle — casual matchmaking outside the ranked ladder.
• Tournaments — community-hosted brackets linked to start.gg; entrant count and final standings are fetched live from the start.gg API once configured.
• Character leaderboards — full Ultimate roster (including all DLC).
• Discord integration — sign-in via Discord OAuth, plus optional DM notifications through a Discord bot (match-found pings, dispute updates, and mod messages).
• Moderation — conduct reports with threshold-based suspend/ban actions, and a disputed-game resolution queue for admins/mods.
• Region-aware matchmaking, with an optional launch-region lock for a staged rollout.
• Public ranking export — a read-only, unauthenticated endpoint so a tournament can seed a bracket from the ladder, keyed on start.gg ids. See docs/api.md.

Tech stack

Next.js (App Router) · React · TypeScript · Prisma + PostgreSQL · Auth.js (NextAuth) with Discord OAuth · Tailwind CSS + shadcn/ui · Sentry.

Getting started

No external accounts needed — Docker handles the database and a built-in dev login replaces Discord OAuth.

1. Install dependencies:

   npm install
   

2. Start a local Postgres database:

   docker compose up -d
   

3. Run migrations:

   npx prisma migrate dev
   

4. Generate backend:

   npx prisma generate
   

5. Run the dev server:

   npm run dev
   

   Open http://localhost:3000 — click "Sign in" and enter any username.

The checked-in .env.development file has everything pre-configured for this local setup. If you want to use a remote database or real Discord OAuth instead, copy .env.example to .env.local and fill in the values — it's the highest-precedence file, and Prisma's config reads the env files in the same order Next.js does (see prisma.config.ts), so migrations follow it too.

Once .env.local holds a deployed environment's values, put your local overrides in .env.development.local (gitignored, read before .env.local) so npm run dev keeps pointing at the local database and the local instance.

next build and next start do not read .env.development.local — both run in production mode, where Next.js reads .env.production.local → .env.local → .env.production → .env. So building and serving a production build locally picks up the deployed database and the deployed NEXT_PUBLIC_* values baked in at build time. Use these instead, which load the development files first and refuse to start if DATABASE_URL is not on localhost:

npm run build:local
npm run start:local -- -p 3100

Working with realistic data locally

A fresh local DB only has a handful of seeded test accounts — not enough to build or sanity-check something like a stats page against. If you were handed an anonymized snapshot file (production match/rating/season history with all emails, IPs, and Discord/Twitch/start.gg identities stripped or never included), import it with:

psql "$(grep DATABASE_URL .env.development | cut -d= -f2- | tr -d '"')" < snapshot.sql

This replaces your local dev DB's data entirely. Only the project owner can generate a new snapshot (needs production DB access) via scripts/snapshot-prod-anonymized.sh — ask in the mod channel if you need one regenerated.

Testing

Run the unit tests (pure functions — rank tiers, rating math, regions, etc., no database) with:

npm test

Use npm run test:watch for watch mode during development. Tests live alongside the source files they cover (src/lib/*.test.ts) and run in CI on every push and pull request.

Core flows that touch the database — lobby pairing, rating confirmation, match finalization, and dispute resolution — have integration tests (src/lib/*.integration.test.ts) that run against a real Postgres database instead of mocking it. Locally, point them at a separate database (so they can truncate freely without touching your dev data):

createdb -h localhost -p 5432 -U postgres smashladder_test
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/smashladder_test" \
DIRECT_URL="postgresql://postgres:postgres@localhost:5432/smashladder_test" \
  npx prisma migrate deploy

npm run test:integration

CI runs these against a disposable Postgres service container — no local setup needed there.

Contributing

Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md for how to get set up and what to include. Please also read the Code of Conduct.

Community & moderation

Join the Discord server to hang out, report issues, or reach a mod/admin (e.g. for a ban appeal). Moderation is currently staffed by around 5 people, selected on a volunteer basis — reach out in Discord if you're interested in helping out.

License

MIT