Test locally

How it works#

The SDK runs in the local environment on localhost, 127.0.0.1 and [::1], or on any host with ?velven_local=1. At the top of a window it decides at once, so nothing waits. In a frame it first looks for Velven, so a game served by velven dev reaches the Velven page that frames it; with no answer it settles local after the probe's wait.

• Scores go to an in-memory board per key, ranked by your page's own block: sort, mode, min, max and cooldown all apply. 3 fake players are seeded so the board has rows to draw. Nothing survives a reload.
• Boards roll over as they do on Velven: daily at 00:00 UTC, weekly on Monday. bucket and season read past periods and seasons. Only the current bucket is seeded.
• A score your page submits to a server board is taken, with one console note that Velven would answer server_only, so you can build a game that posts scores from its server before that server exists.
• Velven.data saves to localStorage under velven:data:local:alice for ?velven_user=alice, or velven:data:local:guest without it, so changing the query string switches saves. It survives a reload; clear it from the browser's storage panel.
• With no block on the page, or one that does not parse, score calls answer no_board and the console says why, once. The same warning appears in every environment.
• Velven.game.start() and Velven.game.stop() log each change to the console. Without ?velven_muted=1, an onMute handler is never called.
• Achievements and stats come from your block and live in memory: an unlock reaches onAchievement, and a stat reaching a trigger unlocks it. Content lives in memory until a reload.
• A room holds only the local player: chat and setData come back to you as they would from the relay, send reaches nobody. A friends read is your own row, ranked 1. presence.set and rooms.invite log to the console.

Query parameters#

Choose what the fakes answer by adding these to the page's address:

?velven_user=alice

Signs in a fake player, { id: "local-alice", handle: "alice", avatar: null }, with a fake token good for an hour. Without it, signIn answers signed_out, as for a guest.

?velven_token=expired

Makes the token already expired, so your refresh path runs and your server refuses it.

?velven_seed=120000,40000,9000

Sets the 3 seeded players' values, so the board looks like your game's. ?velven_seed=none seeds nobody.

?velven_strict=1

Refuses a score your page submits to a server board with server_only, as Velven does.

?velven_slow=800

Waits that many milliseconds before every answer, so your loading states show.

?velven_muted=1

Calls every onMute handler with true right after you register it, as for a player who has turned the sound off.

?velven_local=1

Uses the local environment on any host.

Previews and velven dev#

A preview of a hosted space (velven publish, and its preview link) and velven dev (your folder, served on your machine and framed by https://velven.ai/dev) run inside Velven's page in sandbox mode: sign-in, boards, saves, achievements, stats, content and rooms all work, on the real API, but everything they write goes to your space's sandbox. The live space never sees it, and Velven.sandbox is true.

• Anyone signed in who holds a preview link can play there, so you can test a room with a friend.
• velven reset clears the sandbox by kind (--scores, --saves, --achievements, --content, --rooms) or for one --player. Sandbox data is deleted 30 days after its last write.
• The token a sandbox player gets carries "sbx": true; your server can tell it apart with verifyToken.