Repository files navigation

👾Deploy Pico-8 Games Anywhere and Everywhere! 👾

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

• 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

This project started because I found pico-8 and started building a small hackathon-style game, calledGet 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 acrossthis 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 gotpicoDeploy.

• 🖥️ Deploy to Windows, Mac, and Linux usingElectron andElectron Builder
• 📱 Deploy to Android, iOS, and Web with all listed features usingIonic
• 🚀 Performant mobile builds usingCrosswalk
• 💾 Save file (Indexedb) listener, with Pub / Sub functionality to perform actions when the save file is changed
• 🎮 Mobile on screen gamepad usingGoogle Material Icons
• 🎮 Usb Gamepad / Xbox 360 controller / PS3 controller support using a modifiedpico8gamepad
• 💦 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 multiplepicoDeployConfig.json files, and copied for the correct build target set in ENV variables.
• ♻️ Compatible with libraries likegreenworks andCordova 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 beforeversion 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.

1. InstallNodejs. I suggest usingnvm.

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

3. Runnpm install in the base directory of the project

4. Runnpm run ionic:serve. And openlocalhost: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! 😊

• Minimum android version is 7.1.1 (sdk version 25). This is due to theWeb 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 weirdAudio Jitter / Crackle. If you are skeptical about any device, visit the new and awesomeplaypico 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 usinggreenworks 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.

(Image from pico8-api)

Additional keyboard (⌨️) commands are:

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

• cart/ - Wherecart.js files are stored.
• config/ - WherepicoDeployConfig.whatever.json files are placed, and thecopyConfig.js file lives to copypicoDeployConfig.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 ofsrc/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. SeeElectron Quick Start
• package.json - Project file to define scripts and dependencies

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

Or just watch these steps in the gif below:

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

All of the scripts should be prepended withnpm run [script name], for instancenpm run ionic:serve

The main scripts you will be using are theionic:x,electron:x, andandroid:x scripts.

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

• clean - The default ionic project clean script
• lint - The default ionic project lint script
• cart - copies to the files within thecart/ folder to the builtwww/cart folder
• config - runs thecopyConfig.js script, to copy the appropriatepicoDeployConfig.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 thecart,config, andbuild scripts to build the complete picoDeploy app
• ionic:serve - runs thecart,config, andbuild scripts to serve / livereload the complete picoDeploy app for development
• android:run - exports Mobile ENV Variables, runscart, andconfig, and then runsionic cordova run android --prod to preview a build of the app on a connected android device, or android emulator
• android:serve - Same functionality asionic:serve, but runs on an android device likeandroid:run
• android:build - Similar toandroid:run, but builds an unsigned apk to be distributed.
• android:deploy - similar toandroid:build, but uses (and requires) a keystore to zipalign and sign built apks, by running theionic-android-deplpoy.sh script
• electron:serve - Runsionic:build, and runs the built files inside an electron container
• electron:serve:nobuild - Similar toelectron:serve, but does not re-build the app. This is useful to testing changes on only themain.js file
• electron:build - Builds the application usingElectron Builder for the current Operating system. This is useful for testing final production builds.
• electron:deploy - Similar toelectron:build, but builds for all desktop platforms (Windows, Mac, and Linux), using the Electron builder configuration outlined in thepackage.json

Example / InlinedpicoDeployConfig.json file with invalid json comment lines to describe each key:

{  "cart": {    "cartName": "getdismoney-community.js" // Name or path of the cart inside the cart/ directory  },  "picosplash": { // Settings reffering to the introduction splash screen that hides pico-8 booting    "enable": true, // Boolean to enable or disable the pico splash    "splashMedia": "assets/picomedia/splash.mp4" // HTML5 compliant image or video file to be displayed over the cart booting  },  "backgroundMedia": false, // HTML5 compliant image or video file to be displayed behind the cart. Set to false to disable  "inactiveToExitDelayInMilli": 300000, // How long before killing the app if left in the background  "defaultSettings": { // Default settings to set on the settings menu    "fullscreen": true, // Start the app in full screen or not by default    "sound": true, // Enable or disable sound by default    "backgroundColor": "#272727", // backgroundColor displayed behind cart if no backgroundMedia    "gamepadColor": "#FFFFFF", // Default color of the gamepad    "stretch": false // Default to stretching the game to match the aspect ratio  },  "dbWatcher": { // Save file watcher config    "enable": true, // Boolean to enable or disable the save file (Indexedb) watcher    "cartDataName": "nocomplygames_letsgetdismoney_communitty_edition_v1" // String passed to cartdata() to be found in the Indexedb  }}

A list of example project can be found at:The Example Projects .md

For development,npm run ionic:serve will provide as a great place to test your carts, or any changes you make to the project. It offers livereloading for the project. However, for cart or config changes, this command will have to be re-run.

Simply runningnpm run ionic:build should give you a good desktop build. The built website should be located in thewww/ folder. Which can then be opened directly from your web browser, or uploaded to a site likeitch.io. I haven't personally tested this, but it should all workin theory 🤔. Please run at your own discretion.

For Development, runnpm run electron:serve, which simply runsnpm run ionic:build, and wraps the built project in an electron shell. This is really useful for testing changes to yourmain.js or desktop specific. Otherwise usenpm run ionic:serve.

To test builds for desktop, runnpm run electron:build. This really is just packing you www/ directory into an electron app that can be distributed. However theelectron:build command will only build for the current OS and architecture. Which means it is great for ensuring that your electron builds are building correctly, and running great. Please notes, that my builds forGet Dis Money, come out to be about ~200MB. Built files can be found in thedist/ directory.

To build production builds for all platforms to be distributed and downloading on places likeitch.io or your own distribution platform, runnpm run electron:deploy. This will build for all available OS and architectures to be run by your users. Built files can be found in thedist/android directory.

For Icons and Backgrounds of builds, please refer to theElectron Builder Icons Guide. I know it sates that for the Icons on Linux, it can optionally share the same Icon as macOS. However, It gave me strange builder errors, and I highly suggest just adding your linux icon asresources/icons/512x512.png. Like it states in the guide.

For any additional help, I'd highly suggest looking through theElectron Builder Documentation, for anything you may be trying to achieve.

First, you will need toadd the android platform. However, you will need to set some paths in you.bashrc, which are outlined inthis guide. This can be done withionic cordova platform add android@6.3.0. If you notice, we are specifying cordova android 6.3.0. If you Google around, I guess there are some weird conflicts with Ionic, Cordova, and Crosswalk on Android 7.0, therefore I am specifying the version here. Use other versions at your own discretion. This should automatically add cordova plugins likeCrosswalk. From there, you should now be able to run the android commands like,npm run android:build.

For generating icons and resources, please follow theIonic Docs on generating resources.

For development, runnpm run android:serve, which will run your app inside the android Ionic shell, with livereloading. Similar tonpm run ionic:serve, for cart or config changes, this command will have to be re-run. This is great for testing changes to the gamepad, or anything mobile specific. Otherwise usenpm run ionic:serve.

To test builds, runnpm run android:build, this will give you an unsigned development apk that you can install on your device manually. However, you need to enableUnknown Sources on your android device. Though, newer android version will just prompt you for it. This apk cannot be placed on Google Play, as it needs to be signed and things. Built files can be found in thedist/android directory.

For production builds, runnpm run android:deploy. This requires that you follow theIonic Deployment Guide, and create a keystore for signing apks. This will run theionic-android-deploy.sh script. And you will need to edit the script inside of thepackage.json, and insert the path to your keystore, and your keystore password (Please note, you may just want to run theionic-android-deploy.sh script manually, if you are building your application publicly. As you should be very wary of uploading / sharing your keystore or password). Built files can be found in thedist/android directory. These built apks may be uploaded and distributed on Google Play.

If things aren't working, please refer to theIonic Deployment Guide as it should relatively be the same for this project.

Personally, I do not have access to an iOS developer account, the fees are pretty high, or a physical iOS device. I could test this on my Mac iOS simulator, but I like testing on real hardware. Please feel free to write up some instructions for this, and contribute them to the project.

In the meantime, I'd suggest simply following theIonic Deployment Guide As it should relatively be the same for this project. Also, You will have to add theios platform, similar to android.

For generating icons and resources, please follow theIonic Docs on generating resources.

Adding support for google play games is not too bad. Simply add theCordova Plugin Play Games Services, which is outlined on in its README on the repo I just linked. Then, refer to thePlatformSdkWrapper for usage in the project.

This requires a Steamworks account, and application ID ready to be used. For information on getting your game on steam,see here.

Okay, this one is quite a doozy. To add support for Steam, you will need to useGreenworks. You may want to start by reading through thegreenworks Docs, but here is how I got everything working on my game,Get Dis Money.

First, You need to have a specifc version of Electron and Greenworks to use the prebuilt Greenworks builds. Currently, I am runningElectron v1.8.1, the node version specified by [the electron NODE_MODULE_VERSION](node, and theprebuilt greenworks node addons v0.11.0.

Once you have that all correctly installed, you need to download the.zip files for each OS and architecture you want to target. Each.zip will have agreenworks.js file, and alib/ folder containing a.node file. You want to make agreenworks/ directory at the base of the picoDeploy project. For instance:~/source/picoDeploy/greenworks/. And then add thegreenworks.js file to yourgreenworks/ folder, as well as add the.node file to alib/ folder you should create in yourgreenworks folder.

Then, as it states in thegreenworks docs, "Copysteam_api.dll/libsteam_api.dylib/libsteam_api.so (based on yourOS, e.g.dll for windows) from<steam_sdk_path>/redistributable_bin/[win64|linux32|linux64|osx32] to<greenworks_path>/lib/". Please note for this step, linux32 and linux64 have the same file name. Therefore, you need to run two seperate build cycles for each architecture. And because of this, I decided not to release my game for linux32 😛.

In the end, yourgreenworks folder should have something looking like this:

Next, we need to create ourSteam App Id file. Create a file in the base picoDeploy directory calledsteam_appid.txt. All it should contain is the appid to your game. That is it, nothing crazy, just those numbers. What this does is allow us to test our game with steam running, to allow us to fire off acheivements and things. However, please note that this file can only work when the game is run on macOS, run with an installed windows version of the game, or the.zip linux build type. Since the file needs to be copied to where the electron executable is running from, and some build types wont allow this. However, don't worry, when you launch the game from steam itself, it will handle this for us, and will not throw any errors when trying to do this.

Next, you need to add some things to the"build": {} key of yourpackage.json. You just need to state yourextra resources, and should be placed underneath the"files": [] array. You need to add the greenworks directory, with glob matching, and thesteam_appid.txt. For instance:

... package.json stuff here ..."files": [  "www/**/*",  "picoDeployConfig.json",  "main.js",  "!**/node_modules/**/*",  "!.editorconfig",  "!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,__pycache__,thumbs.db,.gitignore,.gitattributes,.flowconfig,.yarn-metadata.json,.idea,.vs,appveyor.yml,.travis.yml,circle.yml,npm-debug.log,.nyc_output,yarn.lock,.yarn-integrity}",  "!**/._*",  "!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}"],"extraResources": [  "greenworks/**/*",  "steam_appid.txt"],... package.json stuff here ...

Awesome! Next, let's add some helper scripts to ourpackage.json"scripts": {} object to make things easier. Be sure not to copy the... other scripts here ... part!

... package.json stuff here ..."scripts": {  ... Other scripts here ...  "steam:serve": "export DEV=\"true\" && export STEAM=\"true\" && npm run ionic:build --prod && ./node_modules/.bin/electron .",  "steam:serve:nobuild": "export DEV=\"true\" && export STEAM=\"true\" && ./node_modules/.bin/electron .",  "steam:build": "export DEV=\"false\" && export STEAM=\"true\" && npm run ionic:build --prod && electron-builder",  "steam:deploy": "export DEV=\"false\" && export STEAM=\"true\" && export MOBILE=\"false\" && npm run ionic:build --prod && electron-builder -mw --x64 --ia32 && electron-builder -l --x64"},... package.json stuff here ...

These scripts will simply run the sameelectron:x commands but, will set aSTEAM ENV variable that we can utilize. in both ourcopyConfig.js (optional), or ourmain.js. Which we will move on to next.

Let's go ahead and get greenworks to start the Steam api when we run the app. This needs to be done in themain.js file. Simplycopy and paste themain.greenworks.js file, into your projectsmain.js file.

To test, open up Steam, and runnpm run steam:serve, and see if the Steam UI reacts by saying that your Steam game is running. If it is, congrats! If not, please open an issue to let me know, as I wrote this on the top of my head, and will probably need some debugging. Worst comes to worse, your best bet is to follow thegreenworks Docs, but in particular, try going the NW.js route instead of the electron, since we are using prebuilts, and not electron version specific builds.

Lastly, to make builds, runnpm run steam:deploy, and go ahead use the built files inside ofdist/ toupload your game using Steampipe.

This project is built on top of the following projects:

• Ionic for Mobile Builds
• Crosswalk for a more performant modern webview
• Electron for Desktop Builds
• Electron Builder for Deployable Desktop Builds
• pico8gamepad for Desktop Controller Support

This project could not exist without these projects, and I would like to give a huge shoutout to them for their amazing work 💕. A lot of problems can be resolved by referring to these projects issues and stackoverflow answers, and troubleshooting there.

For problems with Crosswalk please refer tothis guide that I followed and theCrosswalk repo.

Feel free to fork the project, open up a PR, and give any contributions! I'd suggest opening an issue first however, just so everyone is aware and can discuss the proposed changes 🤘.

LICENSE underApache 2.0 🐦.