RNG collection web app based on real osu! players. Users log in with osu! OAuth, roll for players, earn luck/items via active play, complete daily quests/milestones, track collections, view global discoveries, and compete on leaderboards.
- Frontend: React + Vite (
client/) - Backend: Node.js + Express (
server/, serverless-ready viaapi/index.js) - Database: Neon/Postgres when
DATABASE_URLis set, or local SQLite (node:sqlite) when not (server/db/) - Game logic: centralized config in
config/gameConfig.js, server-side services inserver/services/ - Auth: osu! OAuth2, server-side sessions stored in DB (cookie
osurng_sid)
Prereqs: Node.js 22+ (uses node:sqlite), npm.
npm installandnpm --prefix client installcopy .env.example .envand set values (see below). LeaveDATABASE_URLunset for SQLite.npm run migrate- Seed player pool:
node scripts/seedMockPlayers.js(or seed from osu! rankings with creds) npm run dev→ serverhttp://localhost:3000, clienthttp://localhost:5173npm test(unit + integration) /npm run buildthennpm startfor production.
See docs/DEPLOY-NEON-VERCEL.md for step-by-step instructions:
- Create Neon project and copy
DATABASE_URL - Configure osu! OAuth callback for your Vercel domain
- Push repo and import into Vercel (
vercel.jsonincluded) - Set environment variables (
DATABASE_URL,CLIENT_URL,OSU_*,SESSION_SECRET,ADMIN_SECRET, etc.) - Deploy, seed player pool, verify
DATABASE_URL– Neon/Postgres connection string; if unset uses SQLite atDB_PATH(./data/osurng.db)PORT,NODE_ENV,CLIENT_URL(comma-separated allowed),SESSION_SECRETOSU_CLIENT_ID,OSU_CLIENT_SECRET,OSU_REDIRECT_URI(must match osu! OAuth app)OSU_API_BASE,OSU_AUTHORIZE_URL,OSU_TOKEN_URLTIMEZONE(UTC default),ADMIN_SECRET(protects admin seed in production)
- Balance/config:
config/gameConfig.js,docs/BALANCE.md - Rarity: rank+pp thresholds → tier; base weights roll distribution.
- Luck:
finalLuck = min(cap, baseLuck*(1+permanentBonus)*temporaryMultiplier), applied to normalized rarity probabilities (sum 100%). - DB schema auto-migrates (Postgres or SQLite variants). Seed:
node scripts/seedMockPlayers.jsorPOST /api/admin/seed-rankings?pages=Nwithx-admin-secret.
- Rolls, luck, inventory, quests, and stats are server-side and persisted in DB.
- osu! passwords never handled by the app (OAuth only).
- For Vercel/serverless, in-memory cooldown is per-instance; DB remains source of truth.