velven
Docs
Menu

Player content

Velven.content stores what your players make, levels, replays, maps, and lets everyone in your space find and download the public ones. Velven keeps the data and never shows it on its own pages: your space lists and draws it.

View guide as Markdown

Upload an item

An upload needs a signed-in player. data is a string, an ArrayBuffer, a typed array or a Blob:

JavaScript
const up = await Velven.content.upload({  kind: "level",            // level, replay, map or other  title: "Castle one",      // 1 to 80 characters  data: JSON.stringify(level),  visibility: "public",     // the default; "private" keeps it to the uploader});if (up.ok) shareCode(up.item.id); // item: { id, kind, title, visibility, size, createdAt, by: { id, handle, avatar } }
  • An item is 5 MB at most, checked before anything is sent: too_large. A player's items in one space are 50 MB at most: quota_exceeded.
  • A public item is listed for everyone in the space. A private one is listed and downloaded only by its uploader, such as a draft or a ghost run.
  • A wrong kind, a title out of range or empty data throws a TypeError before anything is sent.

List and download

JavaScript
const page = await Velven.content.list({ kind: "level", search: "castle" }); // { items, cursor }, 20 a page, newest firstconst more = await Velven.content.list({ kind: "level", cursor: page.cursor });  // cursor is null on the last pageconst mine = await Velven.content.list({ by: Velven.user.id });const got = await Velven.content.download(page.items[0].id); // { item, data }: a string for text, an ArrayBuffer for bytes

list takes kind, by (a player's id), search (words in the title, up to 80 characters) and cursor (from the page before). Reading needs no sign-in.

Warning: Content is other players' data. Parse it defensively, never run it as code, and draw titles and handles as text (textContent, never innerHTML).

Attach it to a score

Name an item on a score with contentId, and every read of the board answers it on the row, so a player can watch the run behind a rank. Keep a replay with a score has the code.

Remove and report

JavaScript
await Velven.content.remove(itemId);            // its uploader, the space's creator, or Velvenawait Velven.content.report(itemId, "offensive"); // offensive, spam, harassment, cheating or other

An uploader removes their own items, and you, as the space's creator, remove any in your space. A report goes to Velven's team, not to you; the content policy says what is not allowed. Give players a way to report what your space shows.

Error codes

Code
too_large
Meaning
Over 5 MB. Answered before anything is sent.
Code
quota_exceeded
Meaning
The player's items in this space would pass 50 MB. Removing old ones makes room.
Code
not_found
Meaning
No such item, or a private one of someone else's.
Code
forbidden
Meaning
Only its uploader, the space's creator or Velven may remove it.
Code
signed_out, unavailable, banned, rate_limited, failed
Meaning
As for scores.

On localhost content lives in memory until a reload. Local testing has the rest.