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.

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.

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