☝️ Press the image on mobile to try the demo ☝️
PICO-8 Mobile Template
(PI)CO-8 ❖ (R)eact ❖ (P)rogressive Web App ❖ (PIRP Stack)
Imagine this scenario.
You meet someone new, and they ask the inevitable question:
What do you do in your spare time?
You, being the consummate PICO-8 user that you are, respond:
Well, I make video games. I use this thing called PICO-8, which is a fantasy console that uses Lua, and it has a built-in pixel art editor, and–
Your new friend's eyes glaze over. Heck, maybe they aren't even a new friend anymore.
Wouldn't it be better if you could say this?
Well, I make video games. If you take out your phone and go to
https://funnydomain.name/, you can play it right now!
Your new friend whips out their phone, visits https://funnydomain.name/ as directed, and starts playing your game right in their mobile browser.
Woah, that's so badass! You have an awesome hobby.
PICO-8 Mobile Template enables that kind of conversation.
PICO-8 Mobile Template provides a starting point for porting your PICO-8 game to mobile devices. It uses two key technologies: React.js and Progressive Web App (PWA) features.
-
React.js is an industry-standard JavaScript library that enables you to build user interfaces in a modular, component-based fashion.
-
Progressive Web App (PWA) is a development philosophy, where you want your app to behave as closely as possible to a mobile app. Concretely, this means that a user can install your app on their mobile device, and play your app as if it were a standalone mobile app.
The second point is especially important, as PICO-8 currently lacks export options for iOS and Android. We must export to web, and make things work on mobile web.
Clone your generated git repository locally. Then, to start the development web server, run the command:
$ make serve
Note: If you're on Windows,
make servemay not work.But you basically need to start a web server so you can serve the repo's files locally.
Open a browser and navigate to http://localhost:8000/. You can also use a helper command, which does the same thing:
$ make open
If you are using Google Chrome, you should configure your Developer Tools such that Chrome displays the site in phone resolution:
At this point, feel free to play around with the app.
Click around. Examine the project's files. Tweak the code, refresh the browser, and study any changes in the webpage's behavior.
Once you have your bearings, we can load the game on an actual mobile device.
Note: Please install
ngrokbefore proceeding below.
To do this, I opt for using ngrok to expose our locally-running web server publicly. Run the following command:
# You can also run `make ngrok` for convenience, which does the same thing.
$ ngrok http 8000
Note the URLs in ngrok's terminal display:
Then, navigate to the https:// URL above (https://486f2bce.ngrok.io/ in this case) on your mobile device.
This is important: you will not be able to "Add to Home Screen" if accessing an http:// (not https://) site.
In landscape mode, the site should resemble the image below:
If you click the "Share" button (whose appearance depends on your mobile operating system and browser), you can verify that the "Add to Home Screen" button appears:
Upon clicking the "Add to Home Screen" button, you'll be able to see the game as a true, standalone app in your Home Screen:
Pretty cool, eh?
Try pressing on your standalone app's icon. Note that everything is customizable: the splash screen, the game shell, the touch controls. You can tweak to your heart's content later.
For now (pun intended), let's deploy the game to a more permanent public address.
To deploy, one only needs to host the repository's files somewhere, and serve the files over https://.
There are many static file hosts. I like Zeit's now, but feel free to use your preferred host.
If you have Zeit's now command-line program installed, you can deploy as follows:
$ now
Which will output something like the following:
$ now
> NOTE: Deploying to Now 2.0, because no Dockerfile was found. More: https://zeit.co/docs/version-detection
> Deploying ~/Repositories/progressive_web_app_test under jasontu
> Using project progressive_web_app_test
> Synced 2 files [139ms]
> NOTE: This is the first deployment in the progressive_web_app_test project. It will be promoted to production.
> NOTE: To deploy to production in the future, run `now --prod`.
> https://progressivewebapptest-68b5vw2ag.now.sh [1s]
⠏ Queued...> Ready! Deployed to https://progressivewebapptest.jasontu.now.sh [in clipboard] [3s]
And voilà!
You deployed your game to a web host, and you can share your game's URL (in this case, https://progressivewebapptest.jasontu.now.sh/) with anyone who wants to play your game.
PICO-8 Mobile Template provides a rough starting point; it is not plug-and-play. You should study the included files, and modify the code to suit your desired user experience.
I left many code comments, which should hopefully ease understanding. Also, below is a description of the file structure:
.
├── Makefile # Helper commands for convenience. Requires `make` to be installed.
├── app.css # Your app's CSS stylesheet. Controls your app's visual appearance.
├── app.js # Your app's JavaScript. Contains the game shell's React.js components.
├── images # Your app's icon images. Customizable through `manifest.json`.
│ ├── icon_128x128.png
│ ├── icon_144x144.png
│ ├── icon_152x152.png
│ ├── icon_192x192.png
│ ├── icon_256x256.png
│ ├── icon_32x32.png
│ ├── icon_512x512.png
│ └── pico8_logo_vector.png
├── index.html # Your app's HTML page.
├── jelpi.js # The JavaScript exported by `export <your game>.js` in PICO-8. You should replace this file, and update the filename in `app.js`.
├── manifest.json # Progressive Web App configuration.
└── service_worker.js # Customize offline caching behavior here.
Please open a GitHub issue if something is unclear.
While I'll try my best to respond, please remember that I have a full-time job, as well as general adult time commitments!
Hold Ctrl (Windows) or Command (Mac), then click here to open a GitHub issue
@nucleartide is the online alias of Jason Tu.
As of this writing, I work at @segment by day, and hack on PICO-8 projects by night. I love PICO-8, and I think its creative constraints suit time-strapped people very well.
For more quips about PICO-8, please follow me on Twitter at @nucleartide.
Team Avocado: https://teamavocado.co/
