# How to add analytics to a Pico-8 game

> Track a Pico-8 web export: the cart writes event codes to the 128 GPIO bytes, and JavaScript in a custom HTML shell queues, sends and retries them.

By Yos Riady. Updated 2026-11-18. Published 2026-11-18. Canonical URL: https://manalens.dev/blog/pico-8-analytics

Pico-8 has no networking, so analytics needs the HTML export. The cart writes small event codes to the GPIO area, 128 bytes at 0x5f80, and the PICO-8 manual says HTML exports expose those pins as the JavaScript array pico8_gpio. JavaScript in your HTML shell then queues the events and posts them to /v0/events.

## Key points

- A Pico-8 cart can send analytics only from the HTML export, where the 128 GPIO bytes at 0x5f80 reach JavaScript as pico8_gpio.
- Pico-8 carts on the Lexaloffle BBS and native Pico-8 binaries send no events, because the JavaScript bridge and networking are missing there.
- The HTML shell keeps the Pico-8 player ID and a queue of up to 1,000 events in localStorage, and the cart keeps only the consent flag.

## Which route fits a Pico-8 game?

A bridge through GPIO in a web export. The PICO-8 manual maps the bytes 0x5f80 to 0x5fff to GPIO pins that the cart can POKE() and PEEK(). In an HTML export, the shell page defines var pico8_gpio = Array(128), and JavaScript there reads the same pins.

Native exports (Windows, macOS, Linux and Raspberry Pi binaries) have no route: the manual says the SERIAL() stdout and file channels are not available while running a BBS or exported cart. printh() writes to a file or the host console, which helps only while you develop.

So the cart sends tiny event codes, and the shell does the rest: the player ID, the JSON envelope, the queue, the retries and the HTTP request with the x-publishable-key header.

Sources: PICO-8 manual v0.2.7, GPIO, SERIAL and PRINTH.

## What must every Pico-8 event contain?

One JSON envelope, the same one the Godot and Unity SDKs send. POST it to /v0/events on your collector with two headers: x-publishable-key and Content-Type: application/json. The body is {"events": [...]} with 1 to 50 events. A good request returns {"accepted":N}.

- type "track", an event name in snake_case, channel "app" and version (your tracker version, up to 32 characters).
- message_id: a new UUID version 4 for each event. Keep it on a retry. The collector counts each message_id once.
- anonymous_id: one UUID version 4 per install, saved on the device. The collector checks the version digit, so a random hex string of the same length is refused.
- session_id: 1 to 64 characters of letters, digits and . _ : -. Start a new one after 30 minutes without play.
- original_timestamp: the time of the event in ISO 8601 UTC, such as 2026-11-09T10:00:00Z. It can be up to 7 days old, and at most 10 minutes in the future.
- context.app.platform (windows, macos, linux, web, android, ios or other) and engine "other". Add storefront, app_version and build to filter reports by build.
- properties: a flat object of strings, numbers, booleans or null.

Sources: Manalens app events documentation.

## What does the cart send?

One small message at a time. Byte 0 at 0x5f80 is a ready flag: the cart sets it to 1 and the shell sets it back to 0. Byte 1 is the event code, bytes 2 and 3 hold a 16 bit value written with POKE2(), and byte 4 mirrors the consent flag.

The consent flag is saved with CARTDATA() and DSET(), which keep 64 numbers (256 bytes) per cart. A pause menu item from MENUITEM() lets the player change it. Keep the cart side small: the manual sets a limit of 8,192 code tokens.

``` PICO-8 Lua (cart)
-- cart: call mana_update() from _update()
cartdata("mygame_ua")
pending = {}

function mana_consent(on) dset(0, on and 1 or 2) end
function track(code, val)
  if dget(0) == 1 then add(pending, {code, val or 0}) end
end
menuitem(1, "analytics on/off", function() mana_consent(dget(0) != 1) return true end)

function mana_update()
  poke(0x5f84, dget(0))                  -- consent: 1 yes, 2 no, 0 not asked
  if #pending > 0 and peek(0x5f80) == 0 then
    local e = deli(pending, 1)
    poke(0x5f81, e[1])                    -- event code
    poke2(0x5f82, e[2])                   -- value, 16 bit
    poke(0x5f80, 1)                       -- ready
  end
end

-- gameplay: track(1, level) on level complete, track(2, score) on game over
```

Sources: PICO-8 manual v0.2.7, GPIO, CARTDATA, DGET and DSET, MENUITEM, POKE2 and Specifications.

## How do I send the events from the HTML shell?

Export with a custom plate, the HTML template that the manual lets you pass with EXPORT -P, and add this script to it. It polls the GPIO pins every 50 ms, turns each code into a named event, and keeps the queue and the ID in localStorage. Map your own codes in NAMES.

crypto.randomUUID() gives the version 4 UUIDs and new Date().toISOString() gives the UTC time, because PICO-8 numbers are 16.16 fixed point and cannot hold a Unix time.

``` JavaScript (custom HTML plate)
<script>
var pico8_gpio = Array(128).fill(0);
(function () {
  var URL = 'https://YOUR_COLLECTOR_ENDPOINT/v0/events', KEY = 'YOUR_PUBLISHABLE_KEY';
  var NAMES = { 1: 'level_complete', 2: 'game_over' };
  var WEEK_MS = 7 * 24 * 3600 * 1000;
  var store = {
    get: function (k) { try { return localStorage.getItem(k); } catch (e) { return null; } },
    set: function (k, v) { try { localStorage.setItem(k, v); } catch (e) {} },
    del: function (k) { try { localStorage.removeItem(k); } catch (e) {} } };
  var queue = JSON.parse(store.get('mana_queue') || '[]');
  var anon = store.get('mana_anon'), session = crypto.randomUUID(), started = false;
  var sending = false, retryAt = 0, backoff = 2000;
  function save() { store.set('mana_queue', JSON.stringify(queue.slice(-1000))); }
  function track(event, props) {
    queue.push({ type: 'track', event: event, channel: 'app', version: '0.1.0',
      message_id: crypto.randomUUID(), anonymous_id: anon, session_id: session,
      original_timestamp: new Date().toISOString(), properties: props || {},
      context: { app: { platform: 'web', storefront: 'itch', app_version: '1.4.0', build: '571', engine: 'other' },
        locale: navigator.language, library_name: 'my-game', library_version: '1.4.0' } });
    save();
  }
  function flush() {
    if (sending || !anon || Date.now() < retryAt) return;
    queue = queue.filter(function (e) { return Date.now() - Date.parse(e.original_timestamp) < WEEK_MS; });
    var batch = queue.slice(0, 50);
    if (!batch.length) return;
    sending = true;
    fetch(URL, { method: 'POST', body: JSON.stringify({ events: batch }),
      headers: { 'Content-Type': 'application/json', 'x-publishable-key': KEY } })
      .then(function (r) { return r.status; }, function () { return 0; })
      .then(function (s) {
        sending = false;
        if ((s >= 200 && s < 300) || (s >= 400 && s < 500 && s !== 408 && s !== 429)) {
          queue.splice(0, batch.length); save(); backoff = 2000;
        } else { retryAt = Date.now() + backoff; backoff = Math.min(backoff * 2, 300000); }
      });
  }
  setInterval(function () {
    var consent = pico8_gpio[4];
    if (consent === 1 && !started) {
      var first = !anon;
      if (first) { anon = crypto.randomUUID(); store.set('mana_anon', anon); store.set('mana_first', new Date().toISOString()); }
      started = true;
      track('game_open', { is_first_open: first, first_open_at: store.get('mana_first') });
      track('session_start');
    } else if (consent === 2 && anon) {
      anon = null; started = false; queue = []; ['mana_anon', 'mana_first', 'mana_queue'].forEach(store.del);
    }
    if (pico8_gpio[0] === 1) {
      if (anon) track(NAMES[pico8_gpio[1]] || 'event_' + pico8_gpio[1], { value: pico8_gpio[2] + pico8_gpio[3] * 256 });
      pico8_gpio[0] = 0;
    }
  }, 50);
  setInterval(flush, 10000);
  document.addEventListener('visibilitychange', function () { if (document.hidden) flush(); });
})();
</script>
```

Sources: PICO-8 manual v0.2.7, EXPORT and GPIO; MDN, fetch(), Crypto.randomUUID() and Window.localStorage.

## How do the player ID, the offline queue and consent work?

The anonymous_id is a UUID in localStorage under mana_anon, created by the shell when the cart reports consent 1. The queue is under mana_queue, capped at 1,000 events, so events from an offline session go out on the next visit. The cart keeps only the consent flag, in cartdata slot 0.

Keep the batch and wait longer before each retry after a network error or a 5xx, 408 or 429 response. Drop it after any other 4xx, because the collector refused the data and a retry gets the same answer. The flush also drops events older than 7 days, because one old event refuses the whole batch with 400.

Until the cart reports consent 1, the shell sends nothing and writes no ID. Consent 2 deletes the ID and the queue. Whether your game needs consent is a decision for you and your legal advisers.

Sources: PICO-8 manual v0.2.7, CARTDATA; MDN, Window.localStorage; Manalens app events documentation.

## What changes for web and desktop exports?

Only the HTML export can send events. Plan your analytics around the web build.

- HTML export on itch.io: the manual describes uploading the exported files as a zip. itch.io serves HTML games from itch.zone hosts, and *.itch.zone is allowed by default, so the CORS preflight that the x-publishable-key header causes gets an answer.
- Your own site: the collector answers the CORS preflight for your project domain and its subdomains. Add other hosts under Allowed origins.
- Lexaloffle BBS: carts there run in the Lexaloffle player page, not in your HTML shell, so the shell script does not exist and no events are sent.
- Native binaries: no networking and no stdout channel in an exported cart, so no events.
- crypto.randomUUID() needs a secure context. It works on https pages such as itch.io, but not on file:// or plain http:// test pages. Test from https or from localhost.

Sources: PICO-8 manual v0.2.7, Exporters and SERIAL; MDN, Crypto.randomUUID() and Preflight request; Manalens app events documentation.

## What are the Pico-8 gotchas?

Most of these come from the size of the machine.

- The GPIO area is 128 bytes, not 256. Send small codes and numbers, not strings. The 256 bytes in the manual are the cartdata limit.
- Numbers are 16.16 fixed point, from -32768 to about 32767. A frame counter overflows after about 18 minutes, the manual warns. Keep times and large counts in JavaScript.
- POKE2() writes 16 bits in little-endian order, so the shell reads byte 2 plus byte 3 times 256.
- CARTDATA() can be called once per run, and the ID allows only a to z, 0 to 9 and underscores, up to 64 characters.
- SERIAL() stdout and file channels are not available in a BBS or exported cart, so they cannot carry events in a shipped game.

Sources: PICO-8 manual v0.2.7, GPIO, Numbers, POKE2, CARTDATA and SERIAL; MDN, Crypto.randomUUID().

## How do I check that Pico-8 events arrive?

Send one batch from a development build and read the response status. In the browser developer tools, watch pico8_gpio change when you trigger an event, and check that the OPTIONS preflight and the POST succeed.

1. Create a test project in Manalens and copy its Publishable key.
2. Export with EXPORT -P and your plate, then serve the folder from localhost (add localhost to Allowed origins) or upload a draft to itch.io.
3. Send game_open and session_start from the Pico-8 build, then check that the response is {"accepted":2}.
4. Open the activity feed and check that platform, build and engine are set on the events.
5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
6. Replace the test key with the production Publishable key before you ship.

Sources: Manalens app events documentation.

## How do I start?

Manalens is the analytics and growth engine built for games. Add the GPIO bridge to your cart and plate, ask for consent in the pause menu, and use the Game KPIs board to see how far players get in your web build.

- [All installation options](https://manalens.dev/docs/install)

Sources: Manalens product documentation.

## Frequently asked questions

### Can a Pico-8 cart send HTTP requests?

No. PICO-8 has no networking functions. In an HTML export, the cart can write to the 128 GPIO bytes at 0x5f80, and JavaScript in the HTML shell reads them as the pico8_gpio array. That script builds the events and sends them to /v0/events with your Publishable key.

### Do Pico-8 carts on the Lexaloffle BBS send analytics?

No. A cart on the BBS runs in the Lexaloffle player page, not in your HTML shell, so the JavaScript bridge is not there. Analytics works only for the HTML export that you host yourself or upload to a site such as itch.io, with your own plate.

### How much data can the cart send at once?

Very little. The GPIO area is 128 bytes, so send one small message at a time: a ready flag, an event code and a 16 bit value. PICO-8 numbers are 16.16 fixed point, so let JavaScript add the timestamp, the player ID and the session.

### Where is the Pico-8 player ID stored?

In the browser, in localStorage under mana_anon, created by the HTML shell after the cart reports consent. The cart keeps only the consent flag, in cartdata slot 0. If the player clears site data, the shell creates a new ID, which counts as a new player.

## Sources

- [PICO-8 manual v0.2.7 (Lexaloffle) (read 18 November 2026)](https://www.lexaloffle.com/dl/docs/pico-8_manual.html)
- [MDN Web Docs: Crypto.randomUUID() (read 18 November 2026)](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)
- [MDN Web Docs: Window.fetch() (read 18 November 2026)](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)
- [MDN Web Docs: Window.localStorage (read 18 November 2026)](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
- [itch.io documentation: Uploading HTML5 games (read 18 November 2026)](https://itch.io/docs/creators/html5)

## Related guides

- [Game marketing measurement guide](https://manalens.dev/blog/game-marketing-measurement-guide)
- [Engine analytics compared: Unreal, Godot, GameMaker, Construct, Phaser](https://manalens.dev/blog/game-engine-analytics-compared)
- [How to add analytics to a LÖVE (Love2D) game](https://manalens.dev/blog/love2d-analytics)
- [How to add analytics to a Phaser game](https://manalens.dev/blog/phaser-analytics)
- [Track an itch.io game](https://manalens.dev/integrations/itch-io)
- [Player analytics guides](https://manalens.dev/blog/topic/player-analytics)
- [Best game telemetry tools in 2026](https://manalens.dev/blog/best-game-telemetry-tools)
- [Build vs buy a game analytics pipeline](https://manalens.dev/blog/build-vs-buy-game-analytics-pipeline)
- [How to add analytics to a HaxeFlixel game](https://manalens.dev/blog/haxeflixel-analytics)
- [How to add analytics to a GameMaker game](https://manalens.dev/blog/gamemaker-analytics)
