TypeScript needs a compile step. The simplest path is esbuild — one devDep, one CLI command. Wavedash injects WavedashJS into the page; there is no npm package to install.
Setup
my-game/
├── wavedash.toml
├── package.json
├── tsconfig.json
├── src/main.ts # source
└── web/
├── index.html # loads ./main.js
└── main.js # esbuild output (gitignored)
package.json
{
"name": "my-game",
"private": true,
"scripts": {
"build": "esbuild src/main.ts --bundle --format=esm --target=es2022 --outfile=web/main.js"
},
"devDependencies": {
"esbuild": "^0.24.0",
"typescript": "^5.8.3"
}
}
src/main.ts
Declare the SDK shape inline (or extend as you use more features), then await the global Promise:
interface WavedashSDK {
init(options?: { debug?: boolean }): void;
updateLoadProgressZeroToOne(progress: number): void;
}
declare global {
interface Window {
WavedashJS: Promise<WavedashSDK>;
}
}
const WavedashJS = await window.WavedashJS;
// ... game setup ...
WavedashJS.updateLoadProgressZeroToOne(1);
WavedashJS.init({ debug: true });
// start main loop
Call updateLoadProgressZeroToOne(...) with intermediate values during async asset loading. init() automatically signals load completion, so call it last.
web/index.html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My Game</title>
<style>
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: #111; }
#gameCanvas { width: 100%; height: 100%; display: block; }
</style>
</head>
<body>
<canvas id="gameCanvas"></canvas>
<script type="module" src="./main.js"></script>
</body>
</html>
Build and run
npm install
npm run build
wavedash dev
wavedash.toml
game_id = "YOUR_GAME_ID_HERE"
upload_dir = "./web"
SDK features
Extend the WavedashSDK interface as you call more methods:
interface WavedashSDK {
init(options?: { debug?: boolean }): void;
updateLoadProgressZeroToOne(progress: number): void;
getUser(): { id: string; username: string } | null;
uploadLeaderboardScore(id: string, score: number, keepBest: boolean): Promise<unknown>;
setAchievement(id: string): void;
storeStats(): Promise<unknown>;
}
const user = WavedashJS.getUser();
await WavedashJS.uploadLeaderboardScore("high-scores", score, true);
WavedashJS.setAchievement("first_clear");
await WavedashJS.storeStats();