# Excalibur.js

Build an Excalibur.js game with your bundler of choice and ship it to Wavedash.

Source: https://docs.wavedash.com/engines/excalibur

<GithubLink href="https://github.com/wvdsh/examples/tree/main/example-excalibur" />
<PlaytestLink href="https://wavedash.com/playtest/excalibur-example/12b41045-4ce0-4d96-88f5-f93d22fa746b" />

[Excalibur.js](https://excaliburjs.com/) is a TypeScript-first 2D game engine with built-in WebGL2 rendering, a scene graph, an ECS, physics, and tweens. It works with any JavaScript bundler — Vite, Webpack, Rollup, esbuild, Parcel, and others. This page covers the generic setup. [The example repo](https://github.com/wvdsh/examples/tree/main/example-excalibur) uses Vite.

## Install dependencies

```bash
npm install excalibur
npm install @wvdsh/sdk-js
```

`@wvdsh/sdk-js`'s default export is the live, fully-typed Wavedash SDK singleton.

## Wire up `Wavedash.init()`

In the file where you create `new Engine(...)`, import `Wavedash` and call `init()` once your game has started.

<Urgent>
**Calling `Wavedash.init()` is required.** Your game stays hidden behind the Wavedash loading screen until you do. Call it once your game is ready to play.
</Urgent>

```typescript
import Wavedash from "@wvdsh/sdk-js";
import { Engine, DisplayMode } from "excalibur";

Wavedash.updateLoadProgressZeroToOne(0.3);

const game = new Engine({
  canvasElementId: "game",
  displayMode: DisplayMode.FitScreen,
  width: 1600,
  height: 900,
});

// ...register scenes and actors...

await game.start("main");

Wavedash.init({ debug: true });
```

Call `updateLoadProgressZeroToOne(...)` during async asset loading; `init()` automatically signals load completion, so call it last.

## wavedash.toml

Point `upload_dir` at your bundler's output directory. For Vite and most other bundlers that's `./dist`.

```toml
game_id = "YOUR_GAME_ID_HERE"
upload_dir = "./dist"
```

## Local development

Produce a build, then run `wavedash dev` to serve it through the Wavedash sandbox.

## SDK features

Once initialized, `Wavedash` exposes leaderboards, achievements, stats, and user data:

```javascript
const user = Wavedash.getUser();

const lb = await Wavedash.getLeaderboard("high-scores");
await Wavedash.uploadLeaderboardScore(lb.data.id, score, true);

Wavedash.setAchievement("first_win", true);
```