Repository navigation
Player Accounts
The Player Accounts website is for players, not for developers. A player uses it to manage their global player account outside the game. The website is at /v1/players/account/ on your GG Scale server. Link to it from your game or your support pages.
The website is on by default. To remove it, set PLAYERS_ENABLED=false. The website sends codes by email, so set up email delivery. See Configuration Reference.
For the link between a global account and the players in each Game Project, see Authentication and Players.
A player can sign in with an email and a password. To make an account, the player opens /v1/players/account/signup. The player gives an email, a password of 8 to 72 bytes, and an optional display name. Then the player types the code from the verification email. A player who forgets the password can reset it from the sign-in page.
A player can also have an account from the game. When a player verifies an email in your game, GG Scale makes the global account for that email if no verified account exists. The account gets the password that the player has in the game at that time.
When Google sign-in is on, the sign-in page shows a Google button:
- On first Google sign-in, GG Scale makes a new account. The Google account must have a verified email.
- If an account with that email exists, Google sign-in stops. The player must sign in with the password, then link Google on the account page.
- To link or unlink Google, the player must give the current password. If the account has no password, the player must give a two-factor code, if two-factor authentication is on.
- A player cannot unlink Google if it is the only sign-in method.
To turn on Google sign-in, see Single Sign-On.
A player can turn on two-factor authentication at /v1/players/account/2fa. It uses an authenticator app that makes TOTP codes.
- When the player turns it on, the website shows 10 backup codes one time. Each backup code works one time. Tell players to keep the codes in a safe place.
- After a correct password or Google sign-in, the website asks for a code. An authenticator code or a backup code is accepted.
- The player can select "Remember this device for 30 days". That device then skips the code for 30 days.
- After 5 wrong codes, the code check locks for 15 minutes.
- To make new backup codes, the player gives the password and an authenticator code. A backup code is not accepted for this. The new codes replace the old codes.
- To turn off two-factor authentication, the player gives the password and a code.
- When the player turns two-factor authentication on or off, the website signs out the other sessions and removes all trusted devices.
The server encrypts the TOTP secrets with TWO_FACTOR_ENC_KEY. Read Security before you set or change that key.
The account page lists each Game Project where the player has a linked player. A link starts when the player verifies an email in a game, or accepts an email invite from a Game Project team.
- Unlink removes the link to one Game Project. The game data stays. A new invite from that Game Project links the player again.
- The player cannot unlink a Game Project while a data deletion is pending for it.
- Delete data requests deletion of the player data in one Game Project. The player can cancel the request on the same page before the purge. A player cannot cancel a request from the Game Project team. See Player Disable and Data Deletion for the deletion rules.
At /v1/players/account/friends, a player can send a friend request by email or display name. The player can accept, reject, unfriend, block, and unblock. The website shows the same message when the target does not exist, so it does not show which accounts exist. Friends are on the global account, so they apply in all your games. See Friends and Presence.
At /v1/players/account/remote-addrs, a player can save a maximum of four addresses: a LAN IP, a public IP, a DNS name, and an iroh address. Your game can read the addresses of an accepted friend with GET /v1/friends/{player_id}/remote-addrs.
- Overview