Wild Cards Go
Have your Savage Worlds characters with you anywhere!
A character sheet app that works offline and syncs across devices once you sign in. It is a Savage Worlds fan product under Pinnacle's Fan License: the footer carries the required notice and the Fan License logo, which must stay unaltered in size.
Offline-first
The browser is the source of truth. Characters live in IndexedDB and MongoDB is the sync target, so the app keeps working without a connection.
- Every edit is written to IndexedDB at once and the character is marked as changed. About 600 ms after the last edit, the sync engine pushes it to the server.
- Each character carries a version that only the server assigns. A push sends the version it was based on. If another device saved first, the server answers
409 and the sheet asks Keep mine or Use theirs.
- The client pulls characters changed since its last pull: on startup, when the tab regains focus or comes back online, and every 30 seconds.
- The pull cursor trails server time by 30 seconds, so a write that commits late is never skipped. Recent rows are re-sent, and the client ignores ones it already has.
- Deletes are versioned writes too, so other devices learn about them.
- Portraits are stored as blobs and synced through their own endpoint, so editing a character never re-sends image bytes.
- If the server is unreachable or returns 5xx, sync backs off (5 s, 15 s, 30 s, 60 s). If the server rejects a character with another 4xx, only that character is marked, and it is retried after its next edit or with the badge's sync button.
- Only one tab syncs at a time (Web Locks).
- A service worker built by Serwist precaches the app shell, so pages load offline. It is registered in production builds; set
NEXT_PUBLIC_ENABLE_SW=1 to register it under next dev after a bun run build. Otherwise next dev unregisters any worker left from an earlier production run.
API
| Method | Path | Purpose |
|---|
GET | /api/characters?since=<ms> | Characters changed at or after the cursor |
PUT | /api/characters/:id | Versioned write: { baseVersion, deleted, data } |
GET/PUT | /api/characters/:id/portrait?rev=<rev> | Portrait bytes (JPEG, PNG or WebP), up to 2 MiB |
Every /api/characters request needs a session and an X-WCG-Store-Owner header naming the account whose local store it syncs. A missing session, or a header that doesn't match the signed-in user, answers 401. Another user's character answers 404. A store whose account was deleted answers 410, and the client wipes it.
Accounts
Sign-in uses Better Auth with Google, Discord and email links. Users and sessions live in the same MongoDB. Signing in only turns sync on: the app works fully signed out, and characters made signed out can be added to an account later.
Deleting an account (account menu → Delete account…) emails a link to /delete-account, which confirms with one more click in a browser signed in to that account, offering sign-in first if needed. Confirming deletes the account's characters and portraits, then the user, sessions and linked logins. Only the deleted user's random id is kept, in deletedUsers, so the account's other devices get 410 on their next sync and wipe their local copy. Hidden account stores on a device (signed out, or another account open) are checked the same way once per app start.
Each account has its own local store (wcg-u-<userId>); signed-out characters live in wcg. Signing out hides the account's characters on that device until it signs in again.
| Variable | Purpose |
|---|
BETTER_AUTH_SECRET | Session signing (openssl rand -base64 32) |
BETTER_AUTH_URL | Public base URL, e.g. http://localhost:3000 |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Optional; Google sign-in shows only when both are set |
DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET | Optional; Discord sign-in shows only when both are set |
SMTP_URL, EMAIL_FROM | Email links over SMTP; off in production without them |
AUTH_PASSWORD=1 | Username and password accounts (no email needed) |
AUTH_PASSWORD_MIN_LENGTH | Shortest password for new accounts; default 8 |
SIGNUP_INVITE_CODE | New accounts need this code, by any sign-in method |
SIGNUP_OPEN=1 | Self-hosted only: anyone may create an account |
DATABASE_PATH | SQLite file, used when MONGODB_URI is unset; one of the two is required |
Each sign-in method is on when its settings are, and the server refuses to start in production when none is. Sign-up stays open on MongoDB; with SQLite it needs SIGNUP_INVITE_CODE or SIGNUP_OPEN=1.
Sign-in and account-deletion emails are HTML with a plain-text part, sent over SMTP, so any provider works: SMTP_URL=smtp://<login>:<key>@<host>:587 (URL-encode @ in the login as %40). EMAIL_FROM must use a domain verified with that provider. In development without SMTP_URL, sign-in links print to the server console; in production, email sign-in is off without both.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
