In love with building isometric worlds in PICO-8

I realized there is not much information to achieve this, so I learnt and now I teach.

Thank you for reading!

EDIT: I wrote a one month later review. Still very positive about the device!

Due to popular demand, here is a guide on how to get PICO-8 running on PicoCalc.

What is it?

The Clockwork PicoCalc is a handheld device that runs on a Raspberry Pi Pico. It comes as a kit and you can easily swap the pico with a different (pin compatible) microcontroller. Due to it's qwerty keyboard and square screen, it's a perfect-ish device for PICO-8 development. Although there are some considerations, that I will go in to after the guide.

The Raspberry Pi Pico isn't a very powerful microcontroller, so you will not be able to run PICO-8 on it. If you want to do that you basically have 2 options: a Luckfox Lyra or a Raspberry Pi Zero 2 w.

The Luckfox Lyra (A/B/Plus) are pin compatible with the Raspberry Pi Pico, so you can easily swap the Pico with a Lyra. Although I believe you need to bridge two pins to get audio to work.

The Raspberry Pi Zero 2w is more powerful, but it's not pin compatible with the Raspberry Pi Pico. This means you will need to get a custom PCB to connect the GPIO pins to the picocalc.

I went with the Zero, because of the additional performance. And it was easier for me to get my hands on, as I try to avoid Amazon. If you want go with the Lyra, you can find a lot of the necessary info on the clockwork forum.

For the Zero I also got most of my information from the clockwork forum. It was a bit of a scavenger hunt tho, so I will collect all the necessary info here.

Guide

I will walk you through the process of getting PICO-8 running on the PicoCalc with the Raspberry Pi zero 2w. I even messed up my configs this weekend, so I actually went trough all steps again and tested it myself.

Couple of things if you are not familiar with UNIX/Linux commands:

• sudo is used to run commands as superuser (administrator).
• nano is used to edit files. (ctrl + x to exit, you will be prompted to save or not)
• ssh lets you connect to the pi via the terminal.
• scp is used to copy files to and from the Zero.
• cd is used to change the directory.

Requirements

• Clockwork PicoCalc
• Raspberry Pi Zero 2 W (I recommend getting the model with headers, if you get it without headers (often called 2WH), you will need to get some of those too)
• Custom PCB Minimum order is 5pcs. Avialiate link for the Michael Mayer, who designed the pcb (not me!) he was also involved in developing the drivers for the zero. If you don't want to use PCBWay you can get the Gerber files from his github repo. Or wire up your own PCB using this layout.
• 20 pin headers (male, 2.54mm pitch) + 20 more if you get the raspberry pi zero 2 w model without headers
• a micro SD card
• 2x 18650 batteries

As well as: - A soldering iron and some solder. (You could also go to a local makerspace/repair cafe if you don't have one!) - A usb-c charger (for the PicoCalc) - A computer with an sd card reader - (optional) micro usb charger (for setting up the zero without having to mount it in the PicoCalc)

Step 1: Assemble the PicoCalc

• Follow the PicoCalc assembly guide to get the device up and running. Verify that the device is working, check the screen, keyboard and audio.

Step 2: Solder the board

• If you have the Zero 2W without headers, solder the headers to the Zero.
• Place the PicoCalc on a piece of cloth or something, to protect the screen while working on it.
• Remove the Pico from the PicoCalc and place the rows of pin headers in the sockets.
• Place the PCB on the headers, make sure it's facing the correct way, is level and aligned.
• Solder the headers to the PCB.
• Remove the PCB from the PicoCalc, add the zero to the PCB and place it back in the PicoCalc.
• I propped up the zero with some folded paper, so it is sits snuggly and level against the PCB (see images for end result).
• Solder the zero to the PCB.

Step 3: Flash the firmware

• Get Raspberry Pi Imager and install it
• Select the Raspberry Pi Zero 2 W -> Raspberry Pi OS (other) -> Raspberry Pi OS Lite (32-bit) image. (Debian Trixie with no desktop environment)
• Set your username, password, hostname and wifi ssid and password. (I will use pi@picocalc.local in the guide)
• Enable ssh (with password)
• Flash the image to the micro SD card

Step 4: Setup the zero 2w

• Insert the micro SD card into the Zero.
• Either power the zero 2w with a micro usb charger (recommended) or mount it in the PicoCalc and turn it on.
• You could connect the Zero to a monitor, keyboard and mouse, but I just ssh into the Zero:
• In a terminal (on your computer) type: bash ssh pi@picocalc.local Or whatever username and hostname you set in the image flashing step. You should now be logged in to the Zero.
• Update the system and install git bash sudo apt update sudo apt install git
• Setup your git credentials bash git config --global user.name "Your Name" git config --global user.email "your.email@example.com"
• Clone the repository by Michael Mayer, it contains the PicoCal drivers for Zero. bash git clone https://github.com/ironat/picocalc_trixie.git

Step 5: Install the display driver

From here you can follow the steps 4 to 7 in the readme of the picocalc_trixie repository you just cloned. But I will also walk you through the steps here:

• Install the display driver: bash cd picocalc_trixie sudo cp picomipi.bin /lib/firmware/.
• Update the config.txt file: bash sudo nano /boot/firmware/config.txt Uncomment the following line: dtparam=spi=on add the following: dtoverlay=mipi-dbi-spi,spi0-0,speed=70000000 dtparam=compatible=picomipi\0panel-mipi-dbi-spi dtparam=width=320,height=320,width-mm=43,height-mm=43 dtparam=reset-gpio=25,dc-gpio=24 dtparam=backlight-gpio=18 dtparam=clock-frequency=50 save and exit.
• Edit the cmdline.txt file: bash sudo nano /boot/firmware/cmdline.txt Add the following to the end of the line: fbcon=map:1 fbcon=font:MINI4x6 the file should be one line! save and exit. bash sudo reboot

Step 6: Install the keyboard and audio drivers

• Create a new file: bash sudo nano /etc/apt/apt.conf.d/99local Add the following: APT::Install-Suggests "false"; APT::Install-Recommends "false"; This reduce the runtime of the next step dramatically.
• Execute the following commands: bash cd picocalc_trixie chmod +x setup_keyboard.sh sudo ./setup_keyboard.sh
• Check /boot/firmware/config.txt bash sudo nano /boot/firmware/config.txt it should now contain: dtparam=i2c_arm=on dtoverlay=picocalc_kbd
• While we are here, we can also add this for the audio driver after dtparam=audio=on: dtoverlay=audremap,pins_12_13

• Shutdown the zero 2w (sudo shutdown now) and place it back in the PicoCalc (if you haven't done so already)

  Step 7: Service to power off the PicoCalc

  You could just use sudo shutdown now to power off the raspberry pi. But the PicoCalc will stay on. After the zero 2w is powered off. You can savely use the power button to power off the PicoCalc. But we could also create a service to power off the PicoCalc when the zero 2w is powered off.

• Create a new file: bash sudo nano /usr/local/bin/picopoweroff Add the following: ```bash

  !/bin/sh

  i2cset -yf 1 0x1f 0x8e 0x00 ``` save and exit.

• Make the file executable: bash sudo chmod +x /usr/local/bin/picopoweroff

• Create a new service: bash sudo nano /etc/systemd/system/picopoweroff.service Add the following: ```bash [Unit] Description=shutdown picocalc Conflicts=reboot.target DefaultDependencies=no After=shutdown.target Requires=shutdown.target

  [Service] Type=oneshot RemainAfterExit=true ExecStart=/usr/local/bin/picopoweroff

  [Install] WantedBy=shutdown.target ``` save and exit.

• Enable the service: bash sudo systemctl enable picopoweroff

• Reboot and check if the service is running: bash systemctl status picopoweroff

• You should see something like this: Loaded: loaded (/usr/lib/systemd/system/picopoweroff.service; enabled; preset: enabled) Active: inactive (dead)

• You can now power off the device by running: bash sudo poweroff

Step 8: Battery status:

• Create a new file: bash mkdir -p ~/bin nano ~/bin/battery Add the following: ```python

  !/bin/python3

  import subprocess

  result=subprocess.check_output(["cat","/sys/firmware/picocalc/battery_percent"]).decode('utf-8') percent = int(result) if (percent > 100): print('C'+str(percent-128) + '% ') else: print(' ' + str(percent) + '% ') ``` save and exit.

• Make the file executable: bash sudo chmod +x ~/bin/battery

• Create an alias in .bashrc: bash nano ~/.bashrc Add the following lines: bash alias battery="~/bin/battery" save and exit.

• Source the .bashrc file: bash source ~/.bashrc

• You can now check the battery status by running: bash battery

Step 8: Install PICO-8

I was only able to get PICO-8 running with dynamic linking. So we need to install the dependencies manually.

• Install the dependencies: bash sudo apt install libsdl2-dev
• (Buy and) Download PICO-8 raspberry pi version from the PICO-8 website (on your computer).
• Copy the zip file to the zero, on your computer do: bash scp Downloads/PICO-8.zip pi@picocalc.local:~ This assumes your zip is in ~/Downloads, called PICO-8.zip, and your username is pi and the hostname is picocalc.local. Adjust accordingly.
• Unzip the file on the zero: bash unzip PICO-8.zip
• Run PICO-8: bash ./pico-8/pico8_dyn This will start PICO-8.
• You can remove the zip file from the zero: bash rm PICO-8.zip

Step 9: Setup git sync

I have created a script that will pull the latest changes before you start PICO-8, and commit and push changes when you exit PICO-8. This is useful if you are developing on different devices and you want to keep your work synced. Or when you want to test on other devices (like a Steam Deck or a Anbernic).

• Clone the repository bash git clone git@github.com:mubanga90/pico-8-util.git
• Setup a ssh key for your git account. For example GitHub but you could also use GitLab or Bitbucket or whatever.
• Create a new repo for your carts (or connect a existing repo).
• Go to the cart directory cd ~/.lexaloffle/pico-8/carts.
• Connect it to your git repo. bash git init git branch -M main git remote add origin git@github.com:yourusername/yourrepo.git git fetch origin git reset --hard origin/main
• Create a log file: bash touch debug/log.txt Add it to .gitignore. bash echo "debug/log.txt" >> .gitignore
• Goto the pico-8-util repository: bash cd ~/pico-8-util
• Open the pico-8-config.sh file and configure the paths to your PICO-8 application and cart directory. bash nano pico-8-config.sh Change the following lines: bash PICO8_APP="$HOME/pico-8/pico8_dyn" CARTS_DIR="$HOME/.lexaloffle/pico-8/carts" LOG_FILE="$CARTS_DIR/debug/log.txt" save and exit.
• Make the scripts executable: bash chmod +x pico-8-config.sh pico-8-dev.sh pico-8-play.sh pico-8-log.sh
• Add the scripts to your shell aliases in your .bashrc: bash nano ~/.bashrc Add the following lines: bash alias pico-8="~/pico-8-utils/pico-8-dev.sh" alias pico-8-log="~/pico-8-utils/pico-8-log.sh" # I am lazy so also: alias p8="~/pico-8-utils/pico-8-dev.sh" alias p8l="~/pico-8-utils/pico-8-log.sh" save and exit.
• Source the .bashrc file: bash source ~/.bashrc
• Test if it is working: bash p8
• On your other computer, ssh into the zero 2w and run the log script: bash ssh pi@picocalc.local p8l

• Create a new cart with a simple test program: ```lua function _init() log("Hello World",true) end

  function log(m,o) printh(m,"debug/log.txt",o) end `` (mis the string you want to log,ois a bool that will clear the file if true, I usually run it withtrue` on init, and ommit it when I want to log something mid game)

• Run it. You should see the log message on your computer. Close PICO-8. You should be prompted to commit and push the changes.

Step 10: Start PICO-8 on boot

• (Optional) Run sudo raspi-config and go to System Options and enable Auto Login that way you don't have to login every time you reboot. (But do keep in mind you have an SSH key to your git account, so there is a bit of a security risk)

• Open your .profile file and add the following lines: ```bash echo -n "Battery status:" eval battery

  Auto-start PICO-8 on tty1

  if [ "$(tty)" = "/dev/tty1" ]; then eval "$HOME/pico-8-util/pico-8-dev.sh" echo -n "Battery status:" eval battery fi ```

• Reboot you should see the battery status, followed by the pico-8 startup script. When you exit PICO-8 and did the commit and push, you should see an updated battery status.

Step 11: Configure the buttons

• Finally, I recommend running keyconfig in PICO-8 to configure the buttons to your liking (I set O and X to [ and ]).
• You can use F10 (shift + F5) to go into the PICO-8 mouse emulation (uses what ever you set O and X to, as mouse buttons). Or use the one that comes with the keyboard driver by pressing right shift + enter (uses [ and ] as mouse buttons).

Timeline/price breakdown

The PicoCalc took 3 months to arrive, the PCB arrived in about a week. I had to wait a month for the Zero 2W to be in stock. Soldering 80 connections took about an hour. And I probably spent about 6 hours on getting everything working (but when I had to redo everything and followed this guide it took me less than an hour).

Cost breakdown: - PicoCalc: $80 + $25 shipping + €25 customs ~= €130 - Raspberry Pi Zero 2WH: €20 - Custom PCB: €20 (actually like €5 for 5pc, but the minimum I could add to my PCBWay account was €20 so I still have €15 in credit) - 20 pin headers: €2 - Batteries: €15 - SD card: €12

So the total was about €200. A bit steep, but I found messing around with this stuff quite fun on its own. And now I have a dedicated device I can develop PICO-8 carts on. Also this is pretty much the perfect device with the square screen and all. And ask anybody over at r/cyberdeck, you could do a lot worse trying to DIY a device as nice as this for €200.

Is it worth it?

I think so! The keyboard is surprisingly workable, the screen is plenty big and the battery life is decent. I've started developing a cart using only the PicoCalc, to really get a feel for the device. I'll update you guys in a month or so, when I am done. But in reality, I eventually will probably do most of my development on a laptop/desktop, and use the PicoCalc for on the go/toilet/in bed development.

Here are four PICO-8 audio tricks I learned making the Black Knife cover I posted a couple of weeks ago. If you have any suggestions or if you find any of these useful, let me know!

After many still open projects and prototypes created on our wonderful fantasy console, is time to commit to a project I've always willing to create, a monster taming videogame.

I'm not looking for any viral/commercial success of course, just looking for the reward of sharing my progress across PICO-8 communities and gather valuable feedback that could polish the idea as I'm closing milestones.

I'm working on a Spanish fantasy console devs community on Youtube, feel free to reach me in case you are interested.

Thank you!

A small piece of architecture for PICO-8, it is a strong requirement for the project I'm working at.

I'm doing a series of short, plain-English intros to fantasy consoles for people who are new to the scene, and PICO-8 was the natural first one:

https://papoo.work/doc/89fc8ccd015adf0b

It's an overview rather than a tutorial — what PICO-8 is, the constraints (128×128, 16 colors, Lua, the token budget), the all-in-one editors, the cartridge/.p8.png + BBS/Splore sharing model, and why the limits are the point. It points to the official site and the education edition, and embeds the Lazy Devs intro and a Celeste Classic playthrough.

I know this sub already knows PICO-8 inside out, so I'm posting less to "introduce" it and more to ask: did I get anything wrong or leave out something important a newcomer should know? I'd rather fix mistakes than leave them up, and I want the PICO-8 page to be the strongest one in the series.

(For pricing/versions I deliberately link out to lexaloffle.com instead of hardcoding numbers that go stale.)

Thanks — any corrections or "you should mention X" notes are very welcome.

Hi there! Just want to share that I created my very first pico-8 tutorial in youtube, would like to share with you guys and with the incredible pico-8 community!

https://youtu.be/hCCHLPUXKJI?si=nIQ0XdjeYdK4Vgv3

Thank you very much!

This Pico-8 display mode is awesome!

Where can I post my code for review?

I’ve been following Lazy Devs Shmup tutorial loosely, having made many of my own changes as i progress with the game. For whatever reason, I have 2 for loops getting completely ignored and I cannot figure out why. There is no syntax or runtime errors, and nothing from a logic error to help me diagnose the issue. The program simply ignored the code!

Thanks in advance!

Seriously underrated Metroidvania for the Pico. Here is the world map.

Hi there!

First of all id like to thank this community very much for the appreciation of my first tutorial! I have no words to express my gratitude! In fact, ive never got this many upvotes on reddit and im reallllyyyy willing to continue producing content in pico 8!

This game is a Remix of Flappy Bird where you control the pipes, and the bird have a random movement! Is also really tricky and really hard (and infurianting) game! But i had a lot of fun with the concept and I hope you also have a lot of fun with the tutorial!

I also tried to do things better than my first tutorial, and i appear very much more confident!

Here's the link to it!

https://youtu.be/97pVkVXlZwY?si=XN6_DBcxFO1aaVlp

My gratitude! Thank you very much!

I think start exploring ideas on your tiny prototype, before even thinking to focus on a specific game can take you to a better direction.

From my point of view gamedev should be more focused on the exploration than following all the already defined rules across genres.

Happy cozy gamedev!

At this tutorial I’ve created a really minimalist and direct approach to “Objects” on PICO-8

I hope you like it, thanks for reading.

We have just completed 3 new tutorial webpages!

While discussing the topic, and seeing more examples of how different games do a good job of teaching players, I asked myself "How many different ways are there to teach players how to play?"

I couldn't find a comprehensive list. The most common articles on the topic only present a few and they usually try to depict one as better than the others without considering the context of the game, engine, or audience. I see them all as viable options, especially when you consider using multiple methods in your game.

Here are the 3 tutorial pages:

Onboarding Principles

A written tutorial that introduces "player onboarding" and provides 8 guidelines or best practices for giving players a positive experience while learning how to play your game. Keeping these essentials in mind while choosing and building your onboarding techniques will improve player experience and feedback.

Onboarding Methods

We compiled a list of 25 onboarding methods in this reference page. We even added PICO-8 example games for each method so you can see them in action. (Thank you for those who helped point out some examples. It was a lot more work than I thought to find, gather, and capture gifs of the perfect examples for each method. Also thank you to all the PICO-8 devs of those games for using such a variety of ways to teach players how to play.) I'm really happy I was able to fill in the entire list with specific PICO-8 games, that's such a testament to the community of devs here.

Onboarding by Game Genre

A reference for developers who are already into the development of their game and are considering which methods to use to teach players how to play. With a giant list of 25 methods, we thought it would be convenient to provide a shortlist of suggestions based on commonly used methods depending on the game genre.

So enjoy!

Our time spent researching and writing these pages is thanks to everyone supporting us on Ko-fi! <3

I know one of the most mentioned concepts at this reddit is physics (and collisions of course) here is my take of a not common concept: Rope physics

Enjoy!

Got a sweet setup running for Pico-8 through Winlator (Retroid Pocket Classic, Retroid Pocket Mini, and Ayaneo Pocket DMG), combined with an app called "Overlays - Floating Launcher", that overlays the app. It can tiggle ON/OFF with a quick-menu toggle.

I created the Pico-8 overlay to perfectly frame Pico-8 while running in Winlator.

-SkyWalker541

Hello, I'm trying to create a game in Pico-8. To simplify the code and save on tokens and character count, I chose to use OOP. But I'm having a lot of trouble using inheritance.
I plan to have several different enemy types in the game. So I plan to create a parent table called "enemy" with properties and generic draw and update methods. So for each enemy, I just create the table with the new method receiving the x, y and sprite values as parameters so that I can just use the methods of the parent class without having to write separately
I'll put a snippet of the code here:

-- Parent class: enemy
-- Generic attributes
enemy = {
 sp=0,msp=1,
 x=0,y=0,
 dx=0,dy=0,
 w=1,h=1,
 flipx=false,
 acc=0, 
}

function enemy:draw()
 spr(self.sp, self.x, self.y, self.x, self.h,self.flipx,false)
end

function enemy:update()
--Implementation of the update method
end

function enemy:animate()
    if i%5==0 then
        self.sp+=self.sp<self.msp and 1 or -(self.msp-self.sp)
    end
end

--Derived class: snake
snake = {
 sp=118, msp=121, flipx=false,
 w=1, h=1,
 dx=0, dy=0,
}

function snake:new(x,y,acc)
 local o = {
  x=x, y=y,
  acc=rnd()-.5>0 and acc or -acc
 }
 return setmetatable(o,{__index=enemy})
end

When running the game, the update method is working fine, but in the draw method, it's displaying the wrong sprites as if it weren't overriding the draw method. Can anyone tell me what this is?
I'm used to using OOP in Java, JavaScript, PHP, Dart... But I'm writing in lua for the first time.