The Veduta Server

Everything Veduta hands out comes from one place, https://veduta.roomve.it: the veduta tool and its updates, the VS Code extension, VedutaOS and its updates, the games the console's MARKET lists, the accounts, friends and chat, and this documentation. The engine's source repository is private; the server is the channel.

What comes from it

Everything but the documentation needs an account.

The account

One account works everywhere: in the tool, on the console and on the website. Create it from the installer (it asks the first time), with veduta register, or on the website. See Installation for where the tool keeps the token.

A new account is a user. To publish games, log in on the website and choose Pubblica → Chiedi di diventare publisher; an administrator approves it. Nothing changes on your machine when that happens: the same token can publish from then on.

The token veduta login keeps is issued for a device and does not expire in practice. It stops working when you change your password or an administrator revokes your sessions: veduta login again. A login on the website lasts a month.

Channels

Every release of the tool and of VedutaOS is on one of two channels:

• stable: final versions only (v1.4.1);
• beta: also release candidates (v2.0.0-rc.22).

Beta sees everything, so a machine on beta also lands on a newer stable. Until v2.0.0 is out, Lua games need the beta channel (see Installation). veduta update --channel beta switches once; "channel": "beta" in the tool's settings keeps it (the tool settings reference).

Publishing a game

The whole path is on Publishing to the Console. In short:

veduta login            # once per machine
veduta publish v1.0.0   # checks, builds the archives, uploads them

What the server does with an upload:

• The first publish of a name creates the game, owned by you: nobody else can upload its versions. The title comes from veduta.json.
• Each version holds <name>_v1.0.0.tar.gz (a Lua game; a Go game has an archive per architecture), checksums.txt and icon.png.
• The MARKET offers the newest version, when it has an archive for the console.
• If the upload has no icon.png, the one in the archive's <name>/ folder is used; if the game has no description, the first paragraph of its README's ## The game (or ## About) section becomes it. A description written on the website is never replaced.

On the website, under Pubblica, you can hide a game from the MARKET or delete it with all its versions. The API can also change its title and description and delete one version.

From CI, the workflow veduta init writes uploads with curl and the repository secret VEDUTA_TOKEN: the token field of your auth.json.

Another server

The server is a small program (Node, SQLite, files on disk) that anyone can run. To point the tool at another one, set "server" in the tool settings, or VEDUTA_SERVER for one run; the installers read VEDUTA_SERVER too. A game project's CI reads the repository variable VEDUTA_SERVER.

The API

For your own scripts: every call but login and register takes Authorization: Bearer <token>; answers are JSON, errors are {"error": "..."}.

POST /api/auth/login          {nickname, password, device: "console"} -> {token, user}
GET  /api/me                  -> {user}
GET  /api/releases/engine?channel=beta   -> {latest: {tag, assets: [{name, url, sha256}]}}
GET  /api/games?arch=arm64    -> {games}
GET  /api/games/<name>        -> {game, versions}
POST /api/games/<name>/versions   multipart: the field "tag" first, then the files
GET  /dl/games/<name>/<tag>/<file>

In a multipart upload the fields must come before the files: the server reads the body once, as it arrives, and needs the tag to know where the files go.

When something goes wrong