picoDeploy

👾 Deploy Pico-8 Games Anywhere and Everywhere! 👾

Example .gifs show the jelpi demo cart. Included cart is different.

Table Of Contents 📚

• Introduction
• Features
• Getting Started
• Key Gotchas and Caveats
• Keyboard Controls
• Project Layout
• Usage
  • To add your own carts
  • Npm Scripts / CLI
  • picoDeployConfig.json
• Example Projects
• Building and Deploying for Web
• Building and Deploying for Desktop
• Building and Deploying for Android
• Building and Deploying for iOS
• Adding Support for Game Distribution Platforms
  • Google Play
  • Steam (Greenworks)
• Parent Projects and Dependencies
• Contributing
• LICENSE

Introduction

This project started because I found pico-8 and started building a small hackathon-style game, called Get Dis Money, for a local meetup called Code && Coffee, Long Beach. I was used to building games in Unity, but wanted to try something less serious and more fun. After showing the game to some friends, and writing more and more code for the game. I thought, what if I actually tried to write a deployable version of the game? Then I came across this article by josefnpat, and figured why not. I have been developing Javascript (Node.js) for about 4 years, and have built plenty of Electron apps in the past. However, I also wanted to build for mobile, (Android and iOS), and at the time pico-8 only deployed to web. I thought I'd take it even further, and commit the ultimate web developer sin 😈. I have been using Ionic since when it was still in beta (before v1), and thought, why not just put Ionic inside of electron? I mean this whole project was all for fun, why not make the write-it-once-and-literally-deploy-anywhere wrapper for pico-8? And that is how we got picoDeploy.

Features

• 🖥️ Deploy to Windows, Mac, and Linux using Electron and Electron Builder
• 📱 Deploy to Android, iOS, and Web with all listed features using Ionic
• 🚀 Performant mobile builds using Crosswalk
• 💾 Save file (Indexedb) listener, with Pub / Sub functionality to perform actions when the save file is changed
• 🎮 Mobile on screen gamepad using Google Material Icons
• 🎮 Usb Gamepad / Xbox 360 controller / PS3 controller support using a modified pico8gamepad
• 💦 Splashscreen / Video to hide the Pico 8 boot screen (Not to be mistaken with Ionic mobile app splash screen)
• 📺 Background image or video to be displayed behind your game
• ⚙️ Settings screen, with support for turning sound on / off, fullscreen for desktop, customizable gamepad color, customizable background color (if not background media), Stretch the game to full resolution, and dropdown credits.
• 🛠️ Build System to support multiple picoDeployConfig.json files, and copied for the correct build target set in ENV variables.
• ♻️ Compatible with libraries like greenworks and Cordova Plugin Play Games Services. That can be plugged into a commented PlatformSdkWrapper service, which taps into the Save file listener I mentioned above

P.S I totally started this project before version 0.1.11 which included binary exports for Windows, Mac, and Linux. However, this project still offers a great amount of functionality for deploying and building games, that binary exports do not offer currently.

Getting Started

1. Install Nodejs. I suggest using nvm.

2. Download this project as a zip, or fork it. This is a base project that yours project will be based upon.

3. Run npm install in the base directory of the project

4. Run npm run ionic:serve. And open localhost:8100 if it does not open it for you.

5. If a game starts running in your browser, then you are ready to go. Enjoy! 😊

Key Gotchas and Caveats

• Minimum android version is 7.1.1 (sdk version 25). This is due to the Web Audio API and how around Android version 7, android replaced their webview with Mobile Chrome. Games can technically be played on Android versions below this, but there will be a weird Audio Jitter / Crackle. If you are skeptical about any device, visit the new and awesome playpico on the device to test the audio. Please feel free to click the previous link to join the discussion, or open an issue if you feel you may have a solution. I can confirm on my Pixel 2, and Nexus 5X the audio was fine. But on my roomate's LG G4, the audio jitters 😞.

• Adding support for Steamworks using greenworks will have many missing steam features, and can be quite finnicky. For instance, the Steam UI cannot be opened, even with mentioned hacks within the projects issues. However, most functionality such as logging into steam, and launching achievements should work.

Keyboard Controls

(Image from pico8-api)

Additional keyboard (⌨️) commands are:

• o for settings (options)
• p for pause
• CMD + q to quit

Project Layout

• cart/ - Where cart.js files are stored.
• config/ - Where picoDeployConfig.whatever.json files are placed, and the copyConfig.js file lives to copy picoDeployConfig.json to the base of the project to be used by the application.
• resources/ - Where app icons for Electron Builder and Ionic are stored
• src/ - Where the source code for the Ionic application lives.
• src/app - The main app component
• src/assets - Where asstets for the application lives. Please take note of src/assets/picomedia where the splashscreen and things are stored
• src/components - Where The application components are stored. Such as the cart, and gamepad components
• src/pages - Where the Home and Settings page components are stored
• src/providers - Where the services are stored. Such as the Save file listener provider, and the Settings provider.
• config.xml - Ionic / Cordova Config for building the application
• ionic-android-deploy.sh - Script for easing the proccess of building signed android apks to upload to the Google Play Store.
• main.js - Electron Main process Javascript file. See Electron Quick Start
• package.json - Project file to define scripts and dependencies

Usage

To add your own carts

1. open pico-8
2. load your cart 🛒
3. export your cart with CART_NAME.html

Or just watch these steps in the gif below:

4. Copy the .js file that was export into picoDeploy/cart.
5. edit the picoDeployConfig.json file to include your cart instead of the included one.
6. Run npm run ionic:serve, and ensure that your cart is now the one being loaded!

Npm Scripts / CLI

All of the scripts should be prepended with npm run [script name], for instance npm run ionic:serve

The main scripts you will be using are the ionic:x, electron:x, and android:x scripts.

The android scripts will require you to set up your android environment, outlined in Building and Deploying for Android.

• clean - The default ionic project clean script
• lint - The default ionic project lint script
• cart - copies to the files within the cart/ folder to the built www/cart folder
• config - runs the copyConfig.js script, to copy the appropriate picoDeployConfig.json according to the ENV variables
• build - runs the default ionic project build script
• serve - runs the default ionic project build script
• ionic:build - runs the cart, config, and build scripts to build the complete picoDeploy app
• ionic:serve - runs the cart, config, and build scripts to serve / livereload the complete picoDeploy app for development
• android:run - exports Mobile ENV Variables, runs cart, and config, and then runs ionic cordova run android --prod to preview a build of the app on a connected android device, or android emulator
• android:serve - Same functionality as ionic:serve, but runs on an android device like android:run
• android:build - Similar to android:run, but builds an unsigned apk to be distributed.
• android:deploy - similar to android:build, but uses (and requires) a keystore to zipalign and sign built apks, by running the ionic-android-deplpoy.sh script
• electron:serve - Runs ionic:build, and runs the built files inside an electron container
• `electron:serv