Sign players in

Know who is playing#

After ready(), Velven.user holds the signed-in player, or null for a guest. Use it for display: a name on the title screen, an avatar beside a score.

const environment = await Velven.ready(); // "velven" | "site" | "local"Velven.user; // { id, handle, avatar } or null// Runs on every sign-in: the one known at ready(), and any later one.const stop = Velven.onAuth((user) => showName(user.handle)); // stop() to stop listening

ready() resolves once and never rejects. It usually settles in under a second; the timing is in the reference.

Ask a guest to sign in#

Call signIn() from a button. Inside Velven, a guest sees Velven's sign-in card over your space and signs in without your page reloading. The promise resolves when they have signed in, or chosen to stay a guest.

button.addEventListener("click", async () => {  const result = await Velven.signIn();  if (result.ok) showName(result.user.handle); // also result.token and result.expiresAt  else console.log(result.error);});

A failed ask answers one of these codes:

Check without showing anything#

signIn({ silent: true }) never shows the card. It resolves with the token when the player is signed in, and signed_out otherwise. Use it before a call that needs the token, or to recover when a session ends.

const quiet = await Velven.signIn({ silent: true });

Take an ask back#

Pass an AbortSignal to bring the card down when your own UI moves on, for example when your menu closes. The ask resolves cancelled, which counts as the player staying a guest.

const controller = new AbortController();const asked = Velven.signIn({ signal: controller.signal });controller.abort(); // the card comes down; asked resolves "cancelled"

When the card shows#

• Ask from a button, or at the end of a run the player chose to finish. Never ask on load.
• Within 5 seconds of a player choosing to stay a guest, a plain signIn() resolves signed_out without the card, since no click of theirs could have asked for it.
• Once a player has stayed a guest twice on one page load, the card stops coming back and every plain signIn() resolves signed_out.
• A sign-in is cached. signIn answers from memory while more than a minute of the token's hour is left, then asks Velven again.

When a session ends#

A player can sign out in another tab mid-game. The next call that answers signed_out clears the cached token and sets Velven.user to null. Try signIn({ silent: true }) once; if that answers signed_out too, show your sign-in button again.

Requirements#

• Only a published space with a verified owner can sign players in. An unclaimed space answers unavailable until its creator claims it.
• Sign-in works inside Velven only. On your own site signIn answers unavailable, so a space with accounts of its own keeps using them there.
• Embedded somewhere else as well, such as itch.io or a blog? There the SDK waits up to 7 seconds for Velven before settling on site. Shorten the wait with data-probe-timeout="3000" on the script tag, or createVelven({ probeTimeoutMs }) in a bundle. The floor is 3 seconds, since inside Velven the page around your space can take that long to start on a slow phone.

The token#

The token is for your own server, to prove who scored on a server board. A space without a backend never needs it.