Every Wavedash game repo has a wavedash.toml at its root. It tells the CLI which game to upload to, where the built files live, and any engine-specific settings.
File location
wavedash.toml is a per-project file. Commit it alongside your game code at the repo root — the CLI looks for ./wavedash.toml by default when you run wavedash dev or wavedash build push. Pass --config <PATH> to point at a different file.
Generate it with wavedash init
The fastest way to create wavedash.toml is to run wavedash init at the root of your game repo. It detects your engine, prompts you to pick or create a team and project, and writes a ready-to-use config.
wavedash initBasic structure
game_id = "YOUR_GAME_ID_HERE"
upload_dir = "./exports/web"
[godot]
version = "4.5-stable"Core fields
| Field | Description |
|---|---|
game_id | Your game's ID from the Developer Portal |
upload_dir | Path to your built game files (relative to the config file) |
entrypoint | The first file Wavedash loads inside upload_dir. Defaults to index.html |
entrypoint is relative to upload_dir and must be an HTML page (.html/.htm) or a JavaScript file (.js); anything else fails wavedash dev and the push. If your build outputs dist/index.html, set upload_dir = "./dist" and entrypoint = "index.html".
A blank value means unset, not "empty string" — game_id = "" is the same missing-field error as leaving the line out entirely, rather than an empty game ID sent to the API.
Overriding fields per run
game_id, upload_dir, entrypoint, and the Godot and Unity versions can each be overridden for a single run by an environment variable, so a committed config can act as the default while CI varies the game or output directory per job:
WAVEDASH_GAME_ID=test_game_id wavedash build push -m "smoke test"The full precedence is --game-id (where the flag exists), then the environment, then this file, then a built-in default. See Environment variables for every variable, what the CLI prints when one applies, and how to run with no wavedash.toml at all.
Engine sections
Five engines have a dedicated section in wavedash.toml. The section is how the build pipeline learns which engine runtime to serve your build with, and which version of it. A config declares at most one — two engine sections is an error.
| Section | Used with | Required | Optional |
|---|---|---|---|
[godot] | Godot | version | — |
[unity] | Unity | version | — |
[jsdos] | js-dos | version, executable | loader_url |
[ruffle] | Ruffle | version, executable | loader_url |
[renpy] | Ren'Py | version, executable | loader_url |
A section that names an engine has to name a version too — the CLI can't pick one for you.
When any engine section is present, the build boots through Wavedash's own entrypoint, so the entrypoint field doesn't apply and is ignored. [jsdos], [ruffle], and [renpy] name the file their runtime loads with executable instead — game.jsdos, game.swf, game.zip. Both executable and, if set, loader_url are paths relative to upload_dir, and each has to exist there or the push fails. [renpy] is the one engine whose build still boots from an HTML page: Wavedash serves the index.html in your upload_dir (under wavedash dev, index.html or the first .html file). The entrypoint field and WAVEDASH_ENTRYPOINT are still ignored or refused, as for the other engines.
With no engine section at all, Wavedash loads your entrypoint directly. See the engine guides for wavedash.toml examples tailored to each engine.
Next steps
With wavedash.toml in place, you can run wavedash dev for a local sandbox or wavedash build push to upload a build.