Publishing to the Console

The console runs VedutaOS from its SD card. Games live on the same card, in the games folder, one folder per game. A Lua game is copied as it is: its scripts, its assets and its card. The console's runtime runs the scripts, so the same folder plays on every console.

Straight to the card

1. Switch the console off and take out its SD card.
2. Put the card in the PC. It appears as a drive named VEDUTAOS (or VEDUTA).

3. In VS Code run Veduta: Deploy to the Console's Card, or in the project:

   veduta deploy

   The tool finds the card by its label; name a folder to use another place (veduta deploy E:\).

4. Eject the card, put it back and switch the console on. The dashboard lists the game by its title: A plays it, Home comes back.

The console keeps each game's saves on the card in saves/<name>/, apart from the game: deploying again never touches them.

deploy writes games/<name>/ with the .lua files, assets/ (without the compiled cache), veduta.json, README.md, the icon and a card.json carrying the version (from git describe). Deploying again replaces the folder, so it is also how to update a game on the card.

The dashboard's card

card.json in the project tells the dashboard what to show:

{
  "veduta": "card/1",
  "title": "Gem Cave",
  "name": "gemcave"
}

For an icon beside the title, put a PNG in the project (outside assets/) and name it in veduta.json with "icon": "icon.png". Without one the dashboard draws a placeholder.

To the market

The console's MARKET lists the games the Veduta server holds, and installs them onto the card by itself. Publishing a game is an upload to that server, which needs the account token veduta login keeps in ~/.config/veduta/auth.json and an account allowed to publish (ask for it once; the server decides).

veduta login                      # once per machine
veduta publish v1.0.0             # checks, builds the archives, uploads them
veduta publish v1.0.0 --dry-run   # builds them and says what it would upload

publish runs the same checks a release runs and this can still be sure of — a clean git tree, veduta test, veduta cook — and then builds exactly what the release workflow builds:

• a Lua game: <name>_v1.0.0.tar.gz, the same archive on every console;
• a Go game: <name>_v1.0.0_linux_arm64.tar.gz for the console and <name>_v1.0.0_linux_amd64.tar.gz for any other Linux machine with a framebuffer;
• checksums.txt, and the icon as icon.png, which is the picture the market shows.

Each archive unpacks to a <name>/ folder that is a game card as it is, with card.json carrying the version being published. Without a version on the command line, publish takes the tag of the current commit. --out DIR leaves the archives where you want them (they go under out/publish otherwise), --notes FILE sends the release notes.

The game is registered on the server the first time it is published, with the title from veduta.json and, as its description, the first paragraph of the README's ## The game (or ## About) section.

Releases from CI

A project created by veduta init has a GitHub Actions workflow (.github/workflows/release.yml) that builds those same files whenever a version tag is pushed and uploads them with curl. Add the account token as the repository secret VEDUTA_TOKEN (and, for another server, the repository variable VEDUTA_SERVER); the workflow needs nothing else, not even the veduta tool. veduta release runs the checklist first and pushes the tag only when everything passes:

veduta release v1.0.0 --dry-run   # the checklist only
veduta release v1.0.0             # checklist, CHANGELOG entry, commit, tag, push

The checklist: a clean git tree, veduta test passing (scenarios and goldens), every asset compiling, a frame rendering, every script compiling, a valid card.json and a workflow that publishes the console's archive.

Pre-release versions (v1.0.0-rc.1) are refused by veduta release: tag them by hand (git tag v1.0.0-rc.1 && git push origin v1.0.0-rc.1), or publish them straight from here with veduta publish v1.0.0-rc.1.

Players with VedutaOS's tool can also put an archive on a card themselves: vedutaos card E:\ --game gemcave_v1.0.0.tar.gz (the card's drive or mount point first).

API levels

Each runtime has a Lua API level: engine.api in a script, 1 in Veduta v2.0. When a later engine adds functions, the level goes up. A game that uses them says so in veduta.json:

{ "veduta": "project/1", "name": "gemcave", "engine": "v2.1.0", "script": "main.lua", "api": 2 }

A console whose runtime has a lower level lists the game with UPDATE VEDUTAOS and does not start it, instead of failing in the middle of play on a missing function. Leave api out while the game uses only level 1.

Before publishing

• veduta doctor checks the project against the console: manifest, card, workflow, versions.
• veduta bench --scenario tests/scenarios/<a long one>.vscenario shows how much of the 50 ms tick budget the game uses. Keep a wide margin: the console is much slower than a PC. See Debugging and Performance.
• Play it on the console itself when you can: the panel's colours are 16-bit, and a gradient that is smooth on a monitor may band on the panel (the simulator shows the panel's colours too).