# PICO-8

Export PICO-8 carts to the web and ship them to Wavedash.

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

<GithubLink href="https://github.com/wvdsh/examples/tree/main/example-pico8" />
<PlaytestLink href="https://wavedash.com/playtest/pico-8-example/42bb6c82-c80c-459d-8596-5063c64c2c6c" />

[PICO-8](https://www.lexaloffle.com/pico-8.php) exports carts to a single self-contained HTML file that embeds the p8.js runtime alongside your cart data. Wavedash hosts that file directly.

## Export the cart

From the PICO-8 console:

```
load mygame.p8
export mygame.html
```

PICO-8 writes `mygame.html` and `mygame.js` next to the cart. You can also use `-p` to customise the HTML shell template. By default the export is standalone — no assets to fetch at runtime.

Move the two files into an upload directory of your choice (the example repo uses `./build/`).

## SDK integration

PICO-8 Lua can't call JavaScript directly, so the SDK has to run inside the exported HTML shell. Open the generated `mygame.html` and add the following just before `</body>`:

<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>

```html
<script>
  (async () => {
    try {
      const Wavedash = window.Wavedash;
      // Stream mygame.js so the loading bar reflects real bytes.
      const r = await fetch("mygame.js");
      const total = +r.headers.get("Content-Length") || 0;
      if (total && r.body) {
        const reader = r.body.getReader();
        let received = 0;
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          received += value.length;
          Wavedash.updateLoadProgressZeroToOne((received / total) * 0.95);
        }
      }
      Wavedash.updateLoadProgressZeroToOne(1.0);
      Wavedash.init({ debug: true });
    } catch (e) { console.warn("[wavedash] init failed:", e); }
  })();
</script>
```

PICO-8 regenerates the HTML on every export, so either re-paste after each export or use a custom shell template:

```
export mygame.html -p my-template.html
```

Where `my-template.html` is a copy of PICO-8's default export template (`pico-8/plates/template.html` inside the PICO-8 install directory) with the SDK snippet already embedded. PICO-8 will substitute your cart data into the template on every export.

## wavedash.toml

```toml
game_id = "YOUR_GAME_ID_HERE"
upload_dir = "./build"
entrypoint = "index.html"
```

<Note>
Rename the exported `mygame.html` → `index.html` so the Wavedash sandbox finds it at the entrypoint path. The matching `mygame.js` filename is referenced from within the HTML, so don't rename that one.
</Note>

## Controls

PICO-8's web player maps controls to keyboard by default:

| PICO-8 button | Keyboard |
|---|---|
| ⬅ / ➡ / ⬆ / ⬇ | Arrow keys |
| O (action) | `Z` / `C` |
| X (action) | `X` / `V` |
| Pause | `Enter` / `P` |