README.md

p8-to-js

Convert .p8 files to .js files for use in other projects.

This simple command-line converter is intended to be used in build pipelines, CLI tools, and any other context where converting from .p8 to .js is useful.

CLI Usage

With npx:

npx p8-to-js cart.p8 cart.js

Using npm install:

npm install -g p8-to-js
p8-to-js cart.p8 cart.js

CLI Options

--export

You can export ready-to-use JavaScript in a variety of different styles -- pick the one that best suits your codebase from the list below.

(If none of these options meets your needs, you might consider using the API instead of the CLI -- see the API documentation below.)

Default Export (default)

Command line:

npx p8-to-js cart.p8 cart.js
npx p8-to-js cart.p8 cart.js --export default

Output:

export default { gfx: '....', lua: '....', sfx: '....', music: '....' };

Usage:

import Cart from './cart';

Named export (custom constant)

Command line:

npx p8-to-js cart.p8 cart.js --export Cart

Output:

export const Cart = { gfx: '....', lua: '....', sfx: '....', music: '....' };

Usage:

import { Cart } from './cart';

CommonJS (nodejs/require style)

Command line:

npx p8-to-js cart.p8 cart.js --export commonjs

Output:

module.exports = { gfx: '....', lua: '....', sfx: '....', music: '....' };

Usage:

const Cart = require('./cart');

JSON

Command line:

npx p8-to-js cart.p8 cart.json --export json

Output:

{
  "gfx": "....",
  "lua": "....",
  "sfx": "....",
  "music": "...."
}

Usage:

const Cart = require("./cart.json");

--encoding

Specify hex or base64 encoding. Hex is the default (the output looks exactly like the .p8 file).

Note: choosing base64 encoding means the output strings will be the base64-encoded versions of the binary string represented by the original hex string. That is, if the gfx section is "000000", then the base64 representation is "AAA". Once unencoded, this is "\u0000\u0000\u0000".

--sections

Specify one or more sections to include in the output (use commas to specify more than one).

For example, to export only the sfx and music sections:

npx p8-to-js cart.p8 cart.js --sections sfx,music

API Usage

Convert a file (async):

const p8tojs = require('p8-to-js');

await p8tojs.convertFile('cart.p8', 'cart.js');

Convert a file (sync):

const p8tojs = require('p8-to-js');

p8tojs.convertFileSync('cart.p8', 'cart.js');

Convert a PICO-8 cartridge string into JavaScript output:

const p8tojs = require('p8-to-js');

console.log(p8tojs.convert(fs.readFileSync('cart.p8')));

API Options

All of the options supported by the CLI are available in the API. For example:

const p8tojs = require('p8-to-js');

let input = fs.readFileSync('cart.p8');
let output = p8tojs.convert(input, {
    export: 'Song',
    encoding: 'base64',
    sections: ['sfx', 'music']
});

console.log(`
// Generated by my fancy build script.
${output}
`);

The output:

// Generated by my fancy build script.
export const Song = { sfx: 'ARaplo532AARRJara3==', music: 'ARJvvAAAAAAAA=' };

Contributing

Pull requests welcome!

To run unit tests locally:

npm install
npm test