js2p8

js2p8 is a tool to convert Pico-8 games that have been compiled to JavaScript back into their original .p8 format.

When a Pico-8 game is compiled to JavaScript, the generated code includes specific variables containing the cartridge name and the compressed game data. This program reads those compressed data from the generated .js file, decompresses it, and reconstructs the original .p8 file with the correct header so it can be reopened and edited in Pico-8.

---

Supported Sections

Currently, js2p8 only supports the following sections of the .p8 file:

• __lua__
• __gfx__
• __map__
• __sfx__
• __gff__

Other sections such as __music__, and __label__ are not yet supported.

---

References and Formats

To better understand the .p8 file format, the .p8.png cartridge format, and Pico-8 memory layout, you can consult the official Pico-8 documentation and wiki:

• P8FileFormat
• P8PNGFileFormat
• Memory

These references contain important details about data structure and internal cartridge memory.

---

Expected JavaScript File Format

The JavaScript file passed to js2p8 must contain at least these global variables:

• _cartname: an array containing the .p8 filename.

• _cartdat: an array with the compressed game data.

  var _cartname = [`game.p8`];
  var _cartdat = [
    112, 105, 99, 111, 45, 56, 32, 99, 97, 114, 116, 114, 105, 100, 103, 101,
    // ... more compressed bytes here ...
  ];

These variables are part of the standard compilation output generated by Pico-8 when exporting to JavaScript.

---

How It Works

• The program searches for the _cartname and _cartdat variables inside the .js file.

• Extracts the .p8 filename from _cartname.

• Extracts and decompresses the compressed data stored in _cartdat.

• Creates a .p8 file with the decompressed content, adding the standard Pico-8 header at the beginning:

  pico-8 cartridge // http://www.pico-8.com
  version 0
  __lua__
  

---

Requirements

• Python 3.x
• Pico-8 version v0.2.0+

The generated .p8 file is compatible with Pico-8 starting from version 0.2.0.

---

Usage

Run the script passing the .js file generated by Pico-8 as an argument:

python js2p8.py <game.js>

Example:

python js2p8.py game.js

This will generate a .p8 file with the name defined in _cartname (for example, game.p8).

---

Warnings

• The .js file must be generated by Pico-8 and contain the mentioned variables.
• It is not designed for arbitrary .js files, only those containing Pico-8 game data exports.