pico-build v0.0.2
pico-build
An all-purpose command-line tool for building PICO-8 games. Write your game as multiple lua files, and have them compiled into tabs within your .p8
cart.
In watch mode, you can launch your cart in PICO-8 from the command line. Calls to printh()
in your game will be logged in the terminal. PICO-8 will automatically reload when you change a file (currently MacOS only).
Quickstart
$ npm i -g pico-build
$ mkdir my-game && cd my-game
$ pico-build init
$ pico-build build --watch
Installation
To install pico-build
, you will need either npm or yarn.
$ npm install --global pico-build
or
$ yarn global add pico-build
Usage
build
$ pico-build build --src ./src --cart ./my-cart.p8 --watch
Builds the lua files in ./src
into a cart named my-cart.p8
.
Options
--src
/-s
- The folder containing your lua files. It will concatenate these files in order alphabetically. I recommend naming them '0.foo.lua', '1.bar.lua', '2.baz.lua', etc. The files will be separated into tabs within the PICO-8 editor.--cart
/-c
- The output cart file. If the file does not exist, it will create one. If it does exist, it will replace the code in the cart and leave the rest of it untouched.--watch
/-w
- Enables watch mode. Will automatically rebuild the cart when any of the lua files change. From watch mode, you can open PICO-8, and (on MacOS) the game will automatically reload on rebuilds.--executable
/-e
- The path to yourpico-8
executable file.pico-build
will try finding this on its own, but you can specify it if it is not in the standard place for your OS.
extract
$ pico-build extract --src ./src --cart ./my-cart.p8
Extracts the code from my-cart.p8
into lua files in ./src
. If the code in the cart contains tabs, each tab will be extracted into its own file.
init
$ pico-build init
Creates a starter PICO-8 project in the current folder. pico-build
will prompt you for the game's name, version, description, and author name. It will create the following files:
pico.toml
- The config file for the project. Thepico.toml
format is described below.[game-name].p8
- The PICO-8 cart for your game.src/0.init.lua
- The entry point for your lua code.
Config File
pico-build
can read from a configuration file so you don't have to specify every option in the command line. It will search for either pico.toml
(using toml) or pico.json
. The following properties are supported:
src_dir
string - The folder containing lua filescart
string - The path to your.p8
filewatch
boolean - Enables watch modeopen_pico
boolean - Opens your cart in PICO-8 on buildexecutable
string - The path to yourpico-8
executablename
string - The name of your game. Currently unused.description
string - The subtitle of your game. Currently unused.version
string - The version of your game (ex: '1.0.0')author
string - The name of the game's author(s)
Here is an simple example config file:
# pico.toml
src_dir = 'src'
cart = 'my_game.p8'
watch = false
open_pico = true