- REBOOT PICO-8 to clear memory to defaults.
- Open the music editor.
- Navigate to pattern 63, then select it.
- Activate the fourth channel. Set its sfx to 63.
- SAVE NONEMPTY.P8
- LOAD NONEMPTY.P8
- Navigate to pattern 63.
Expected: Pattern 63's fourth channel should still be active and set to 63.
Actual: It is empty.
Expected: The .p8 file contains a music section with 63 default patterns and one non-default pattern.
Actual: There is no music section.
This appears to be a bug in the P8 section truncation logic that omits trailing default (empty) lines of each section. This does not happen when saving as .p8.png. I can set earlier channel patterns and see them show up in the .p8 while the last one is still missing. At some point my messing around restores intended behavior, so I don't know how that works internally. But I can repro with the steps above.
The audio print control code can take a number to refer to a specific sfx slot. Given only the number, it plays the sfx in that slot:
-- plays sfx 12 (silent if the slot is empty) ?"\a12"
When followed by a space and additional print material, I expect it to play the given sfx as above. Instead, it plays the standard beep as if no number is present. I can further confirm that it actually stores the system beep in the numbered slot, overriding whatever sfx data was there previously.
-- beeps (expected: play sfx 12) ?"\a12 sup yall" -- beeps sfx(12)
When followed by note data, this works as documented: it stores the note data in the given sfx slot, plays it, and prints the rest of the string.
-- stores note data in sfx 12 and plays it ?"\a12s4Xxc1egc2egc3egc4" -- plays sfx 12 ?"\a12" -- plays sfx 12 sfx(12) -- beeps (expected: play sfx 12) ?"\a12 sup yall" -- beeps sfx(12)
The Clockwork DevTerm is a small portable computer with ultra-wide screen, miniature keyboard, built-in gamepad keys, and a thermal printer. You can buy one configured with a Raspberry Pi core that can run PICO-8 (among other things). I recently live-tweeted my unboxing and set-up. This post is a summary of my review of the device, and PICO-8 set-up instructions.
Clockwork also makes the GameShell, a portable Game Boy-like gaming device. Both DevTerm and GameShell are designed as modular kits that you assemble. As with GameShell, the hardware designs and software for DevTerm are open source. The parts are high quality, the modules are well designed for reuse and expansion, and assembly instructions are easy and clear. The modular design, the breezy assembly process, and the iconic side knobs set the tone: this is your machine, and you can open it at any time.
Stock warning: As of this writing, you can buy the RaspPi version of DevTerm for $219 USD, but this does not include the RaspPi CM3+ Lite core. These seem to be difficult to find at the moment, probably due to the infamous pandemic chip shortage. DevTerm does nothing without this core, so know what you're buying.
You will also need two (2) 18650 rechargeable batteries, a USB charger capable of outputting 2 watts, and a cable with a USB-C connector. The batteries charge while inside the unit.
Both DevTerm and GameShell can run PICO-8. A while back I wrote a PICO-8 on GameShell tutorial that Clockwork subsequently semi-automated and built into their launcher app (thanks Clockwork!). DevTerm doesn't have PICO-8 specific software, but it runs PICO-8 cleanly due to being based directly on a Raspberry Pi core. I have included some details below.
DevTerm is a fully capable Raspberry Pi machine. The reams of RaspPi support material on the Internet make it easy to learn how to do things with your DevTerm. Whether the hardware is up to your favorite RaspPi tasks is another question.
The DevTerm hardware
(Photo credit: Clockwork)
The most important thing to know about DevTerm is that it is small: 7-3/4" wide, 6" deep, and 1-1/2" tall at its highest point. The wide screen and two-tone design of the case recall the vintage Tandy TRS-80 M100 portable (1983), which was famous for its comfortable keyboard. In terms of size, DevTerm is not that. Most official photos do not include other objects that indicate scale, though credit to Clockwork for posting this photo set back in June 2021. To get a sense of the size of the keys from the photos, look at the gamepad buttons in the upper right of the keyboard, and notice that the letter keys are about the same size.
As miniature keyboards go, DevTerm's keyboard is great. The keys are responsive for typing purposes and satisfying to press. I manage to use both hands to type, though at a fraction of my usual speed due to the cramped size. I have minor quibbles with the layout: the tab and enter keys are under-sized and dominated by the escape and backspace keys, and the meta keys are small and inset. In this form factor, you want to use meta keys for text editing and keyboard navigation of apps, so putting Ctrl fully left would have been useful.
For mousing, DevTerm has a trackball and several mouse-button keys. Performance is reasonable for selecting windows and icons. I found it unreliable for drawing art, but it'll do in a pinch. I'd pack a portable external mouse for extended sessions. With default settings, mouse travel is pretty slow and it takes some tedious effort to get the pointer from one side of the screen to the other.
Just above the typing keys are gamepad buttons: four directional buttons on the left, and four action buttons (ABXY) on the right. Here again the layout just misses expectations. I would prefer a traditional D-pad rocker to the bifurcated square thing, and the action buttons are not in a cross orientation. The gamepad buttons are more comfortable for playing games than the letter keys, so I'm glad they're there.
I made brief demo videos of typing, mousing, and gaming on the DevTerm keyboard so you can get a sense of it (Twitter will make you scroll down to see these, sorry):
The screen is amusingly wide at 1280x480 pixels, enough for PICO-8 on one side and VS Code, a YouTube tutorial, or the Wiki on the other side. Viewing angles are good, including the most important angle of keeping the device flat on a table surface while seated. The unavoidable geometric distortion does make me wish it had about 10 more degrees of tilt. Maybe I'm getting old, but small type and low contrast color combinations are difficult to read. In a sense, PICO-8 is great for this because its letters are big and chunky compared to some apps at default font sizes.
I have two minor concerns with the display: glare and fingerprints. You'll want to control what light sources are in front of you that might reflect into your eyes. And you might want to carry a microfiber cloth to wipe away smudges. I wonder if a screen protector cut to size might help, though I'd worry about the impact on viewing angle.
You get three USB-A ports, a charging-only USB-C port, a micro HDMI port for an external display, and a standard 1/8" stereo headphone jack. I haven't tested the HDMI port. The headphone jack sounds great. It also has little built-in speakers, with the performance you'd expect for their size. There's no hardware volume control, but X Windows has a volume slider in the menu bar.
The power button is on the front, with subtle lights indicating whether it is turned on or charging. The power button is smart enough to shut down the machine without confusing the OS into thinking it crashed, like some RaspPi power switches do. The default start-up sequence is unceremonious with no Clockwork logo or splash screen, and you might think it didn't work for a few seconds, but after that it boots impressively quickly into X Windows.
All software lives on a 16 GB microSD card that's included with the kit and pre-formatted with Raspian Linux. I was very pleased that I didn't need to mess with writing an OS image to the card as with most Raspberry Pi set-ups. You can turn DevTerm on with USB power the moment you finish assembly.
For one last charming flourish, DevTerm includes a built-in 2-1/4" thermal printer. It takes standard calculator thermal paper. Clockwork has a CUPS driver for the printer that you can install so that it works with all standard Linux software. The distinctive orange paper holder is removable and has its own storage cap, and a door covers its access port. Once the novelty of the printer has worn off, you can disconnect it and pretend it isn't there.
DevTerm and PICO-8
Does DevTerm run PICO-8? Of course it does!
You install PICO-8 like you would with any other Raspberry Pi system.
- Open a web browser. (It's the "globe" icon in the Raspian menu bar.)
- If you purchased PICO-8 directly from Lexaloffle, visit https://www.lexaloffle.com/ and sign in with your account. Click your username to open the menu, select Downloads. Locate the PICO-8 Raspberry Pi version, then click "zip" to download. (If you purchased PICO-8 from Humble Bundle, Itch.io, or another vendor, follow their instructions to download the latest Raspberry Pi version.)
- Open the file explorer (the "folder" icon in the Raspian menu bar), then navigate to Downloads to find the file you downloaded. Double-click to open the .zip file, then click the Extract files button and follow the prompts to select a location for the pico-8 folder. I keep mine in the pi home folder.
To launch PICO-8, navigate to the pico-8 folder, double-click the pico8 icon, then click Execute. (The process for adding PICO-8 to the Application menu or the Application Launch Bar is a bit involved, so I won't go into that here.)
Alternatively, you can start PICO-8 from the command line by executing the pico8 command:
Note: The rest of these instructions assume some familiarity with the Linux command line. To get to a command prompt, click the "terminal window" icon in the Raspian menu bar.
PICO-8 full screen and windowed modes
By default, PICO-8 opens to take up the full screen. You can press Alt+Tab to switch between applications while PICO-8 is running. You can close PICO-8 by giving it the SHUTDOWN command, or by pressing Alt+Space to open the window menu then selecting Close.
It is important to remember that PICO-8 hides the mouse cursor when it is full screen and in console mode or game playing mode. In other modes, it'll show the cursor, but only if the cursor is positioned in PICO-8's square display area. This is a special problem for DevTerm because the mouse could be anywhere on its wide screen, and the trackball moves it so slowly that it can be frustrating to find it just by moving it blindly. Instead, press Alt+Space to open the window menu and reveal the cursor, move the cursor into the PICO-8 area, then press Escape to close the menu.
To have PICO-8 open in a window instead of full screen, you can use a command line option when starting PICO-8, like so:
~/pico-8/pico8 -windowed 1
You can tell PICO-8 to open in a window every time by updating its configuration file. This file is located at the path ~/.lexaloffle/pico-8/config.txt. (It is not in the pico-8 directory with the app.) Open this file in a text editor, such as the pico editor (no relation) that's included with Raspian:
pico -w ~/.lexaloffle/pico-8/config.txt
I recommend the following settings for running PICO-8 windowed on DevTerm. This puts the window on the right side of the screen and obscures the borders.
window_size 478 478 windowed 1 window_position 808 -26
To position the window centered on the screen with the window bar visible, use this window_position:
window_position 430 0
Save the file then exit the editor: in the pico editor, save with Ctrl-O and press enter when prompted for a filename, then exit with Ctrl-X. Quit PICO-8 if it is running, then restart it to pick up the new settings.
When PICO-8 uses the automatic window size (0 0) and position (-1 -1), Raspian opens a window that's a bit too big for DevTerm. Moreover, the window borders are obscured, so you can't drag them to resize! To reposition the PICO-8 window when this happens:
- Press Alt+Space to open the window menu, then select Move.
- Use the trackball to move the window down so you can see the window bar, then click the left mouse button to release the window.
- Drag a corner to resize the window.
Setting up the gamepad buttons
The DevTerm gamepad buttons work with PICO-8, but not out of the box. You must configure them with the SDL controllermap utility and PICO-8's controller configuration file.
Execute these commands in a Terminal window to download, build, and run the controllermap utility:
wget http://libsdl.org/release/SDL2-2.0.7.tar.gz tar -zxvf SDL2-2.0.7.tar.gz cd SDL2-2.0.7/test ./configure make controllermap ./controllermap 0
The last command runs the tool and opens a graphical interface. Press the indicated buttons for the directional pad and action buttons, and press Space for the rest.
The tool prints the configuration line to the Terminal window then exits. It looks something like this:
Copy the entire line (select with the mouse, then Shift+Ctrl+C). Open the PICO-8 controller configuration file in an editor:
pico -w ~/.lexaloffle/pico-8/sdl_controllers.txt
Move to the bottom of the file then paste the line (Shift+Ctrl+V). Save and exit. Quit and restart PICO-8, if needed.
Try it with Splore! Type SPLORE (or just S) at the PICO-8 command prompt and play some games.
Setting up... the printer?
You can print to the thermal printer from any app that knows how to print. To download and install the CUPS printer driver, run the following commands:
sudo apt -y install libcups2-dev git clone https://github.com/clockworkpi/DevTerm.git cd DevTerm/devterm_thermal_printer_cups make sudo make install lpoptions -d devterm_printer
You can test print a simple message like so:
echo "Hi DevTerm!" | lp
PICO-8 does not have any built-in printing capability. OR DOES IT?? (video)
... Not exactly. For this little hack I wrote a Python script that runs in the background and waits for you to EXPORT XXX.LUA.PNG from PICO-8. When you do this, PICO-8 generates a PNG image of the contents of the source code editor in the PICO-8 font and colors. The Python script does some processing of the image to convert it to black text on a white background, then sends it to the thermal printer.
This hack works even if the contents of the source code editor isn't actually code, so you could use it to print grocery lists or whatever from PICO-8. You can experiment with the script to get different results. I chose elements such as the scaling (180%) mostly for visibility in the tweet video. This method cuts off the page about 1-1/2" in.
A small warning: during my experiments I had the thermal printer trying to print large blocks of dark color (black and grey). Not only is it lousy at this—the paper advance is not very accurate—it tends to trip the power fault circuitry and shut off the DevTerm. Stick to text and sparse images, or at least save your work.
- To list pending print jobs: lpstat -o
- To kill a specific print job: cancel <jobid>
- To kill all pending print jobs: cancel -a devterm_printer
It's difficult to describe the Clockwork DevTerm as much more than a toy. But for nerds like me (and probably you) it's a fun toy. I'm looking forward to carrying this thing around town and doing nerdy nonsense with it. I like that it's a non-serious computer, so I'm encouraged to do non-serious things with it.
The non-seriousness of the thing makes it a serious contender as a PICO-8 development terminal. I wouldn't write prose on this keyboard, but I'd punch out short bursts of code and iterate on gameplay. The trackball isn't enough for major pixel art or map design, but add a portable USB mouse and you're good. It feels just right for PICO-8 music, if you use headphones. Now if only I could take the PICO-8 devkit tabs and spread them out across the ultra-wide screen...
There are dozens of RaspPi-based computer kits targeted at kids. I own several. I'd put DevTerm near the top of the list, if only because I can imagine someone with smaller hands getting more out of the keyboard. And unlike some others, DevTerm actually holds up as portable, compact, and even robust.
I'm excited about expansion capabilities. The open modular design is always rife with possibility, though it takes outside commitment to realize that potential. With a ribbon cable from the RaspPi GPIO connector out the back to a breakout board, DevTerm could become the centerpiece of a fully portable electronics experimentation kit, or a physics/biology/meteorology data gathering kit, or a computer architecture kit, or an appliance repair kit, or a wearable tech programming rig. Or you can use it to make games, that's good too.
For more photos including unboxing and assembly steps (and a few minor misadventures), see this Twitter thread.
Erroneous-looking interaction between draw y offset and character height in PICO-8 0.2.2c:
poke(0x5f5b, 0x62) -- draw y=6, x=2 print("shifted\n\n") -- prints 6 down, 2 over, full text visible poke(0x5f5b, 0x72) -- draw y=7, x=2 print("shifted\n\n") -- prints 7 down, 2 over; text cut off vertically after first row of pixels -- expected full text visible poke(0x5f5b, 0x62) -- draw y=6, x=2 print("shifted\n\n") -- prints 6 down, 2 over; text cut off vertically after first two rows -- expected full text visible poke(0x5f59, 0xa4) -- char size y=10, x=4 print("shifted\n\n") -- prints 6 down, 2 over, full text visible
Setting draw y offset to 6 works as expected. Setting draw y offset to 7 appears to change some kind of state that cuts off characters vertically at a fixed height. Setting it back to 6 shows this state persists. Changing character height appears to clear this state.
I also experimented with different character height settings and noticed a character height of 6 prints no pixels, but 7 prints all pixels, and only after I had messed with the draw y offset as above. (The following have the expected effect from a clean reboot.)
poke(0x5f59, 0x64) print("shifted\n\n") poke(0x5f59, 0x74) print("shifted\n\n")
In macOS (Big Sur but possibly others), there are a few bugs related to the selected system audio output device.
A) PICO-8 uses the audio output device selected by the OS at start-up time, and does not change when a different output device is selected while PICO-8 is running.
- Select an audio output device, such as the laptop speakers.
- Open PICO-8.
- Test that audio is played from the laptop speakers. (E.g. draw then play a sfx.)
- Change the audio output device, such as headphones, using System Preferences or the Audio taskbar menu.
- Retry the audio test.
Expected: Audio should be emitted out of the new output device (headphones) and not the original device (laptop speakers).
Actual: Audio continues to be emitted by the original device.
B) If the output device that PICO-8 detects during start-up is no longer available, audio stops working entirely. In the SFX editor, the note playback indicator is also affected, which might hint at a cause.
- In macOS, select a removable audio device, such as Bluetooth headphones.
- Open PICO-8, then open the SFX editor.
- Draw a sound and test playback with the spacebar. The sound plays and the note indicator moves.
- Disconnect the removable audio device, thereby changing the OS default output device.
- Press spacebar.
Expected: The sound plays as normal through the new audio output device.
Actual: No sound is played. The note indicator highlights the currently selected note, but does not move. Pressing the spacebar again to stop playback restores the note indicator back to the cursor. sfx(1) from the command prompt also does nothing after #3, but it does return.
Workaround for both issues: Save your work and restart PICO-8 after changing audio output devices.
PICO-8 0.2.1b, macOS Big Sur 11.0.1.
Harvard University's CS50 Games course has a free online version on edX. It's a great class for beginners with some coding experience, and uses Love2D and Lua. Nearly all of the concepts apply to PICO-8 development.
It's not too difficult to translate in-class code to PICO-8 equivalent code, but it might be easier to stick with Love2D for the course, then figure out PICO-8 equivalents later. In-class code uses Lua standard library features, all with PICO-8 equivalents. Spreading code across multiple files could be done with code tabs or "#include" instead of "require". They also use a simple third-party object-oriented class package to teach OO concepts. This could be ported to PICO-8 but hasn't been yet.
If there's interest, I'm sure we could pull together a set of support materials for bridging CS50 and PICO-8. For now I'm just recommending the course.
I'm noticing crackling or popping noises during music playback in the 0.2.0i web player, either on the BBS or standalone web. I cannot reproduce the noise for the same carts in PICO-8 native. For me this is noticeable and unpleasant, discovered in both the recent Pico Driller and Star Anise Chronicles.
Anyone else hearing this? I can try to record it if that helps.
Chrome 81.0.4044.138, macOS 10.15.4.
Please add volume controls.
This is actually two requests: volume controls for the PICO-8 native apps, and volume controls for the web player (exported and BBS). BBS games in particular are always at full volume, and I rely on web media players to give me a volume setting I can adjust on a per-player basis.
I'm seeing some new people picking up PICO-8 with the 0.2 release announcements (welcome!) and some discussion of the new visible tabs feature is giving the config.txt workflow some attention. People are tripping on the fact that PICO-8 overwrites config.txt on exit without testing for changes.
I'd like a smarter merge of in-memory and on-disk properties. The app should remember last loaded properties so it can calculate "dirty in memory" and "dirty on disk." DiM only? Update disk. DiD only? Update memory. Both DiM and DiD? Tricky, but maybe this is avoidable if PICO-8 always merges on every in-memory change.
I assume PICO-8 already has logic for preserving comments and resolving weird cases like a property appearing more than once, or not at all, in the file. :)
I like how I can indent/dedent a block selection with tab/shift-tab, and I like the behavior where it operates on every line with at least one character selected. I notice an edge case that should be addressed: if the first line is indented and I have the intend spaces selected, when I dedent the space goes away but my selection start moves up to the previous line. If I dedent further now the previous line is getting included in the dedent.
I like the new feature where shift-enter auto-indents. It also adds an "end" statement which is useful for closing blocks.
I'm wondering if it should always do this, or if it could do something more context sensitive. A full IDE would be running a full parser in the background which is probably overkill. A simpler behavior would just scan the current line for block starter keywords and only indent+end if it finds one.
I'd prefer this because I'm likely to get into the habit of shift+enter, enough to do it by accident, and if it always does what I want that'd be better than having to undo and try again.
Snowy has skates and wants to help his friend Bunny decorate his tree! Skate the lake to find five ornaments for the tree.
- Hold X and a direction to accelerate.
- Press Z ("O") while moving to jump.
Tip: Hold Z ("O") for longer before letting go to jump longer.
Tip: If you get stuck in water, try jumping your way out. Snowy isn't a strong swimmer, but he's a great jumper!
This is my and TimSwast's contribution to PICO-8 Advent 2019. Thanks to everyone who participated, and everyone who played!
I've thrown all my 32-bit games overboard and upgraded to macOS Catalina. I notice that the current PICO-8 binary (0.1.12c) asks for broad keyboard permissions (read keystrokes in all applications). I assume this permission isn't actually needed (I can deny it and everything seems to work) and this is a side effect of an older SDL macOS interaction. It'd be nice if the app can be configured to not ask for the permission.
If it is used for something I'd enjoy knowing what it is.
This is a bit obscure and possibly a limitation of SDL, but I notice as of 0.1.12c that if my default audio output device changes while PICO-8 is running, PICO-8 will continue to use whatever output device was the default when PICO-8 started for output, instead of switching to the new device.
For example, if I start PICO-8, then connect headphones, PICO-8 will continue to use the speakers. The rest of the system (at least for apps that don't have this issue) will use the headphones. To get PICO-8 to use the headphones in this case, I have to restart PICO-8.
The PICO-8 built-in editor supports up to 8 tabs. These are represented in the .p8 file as a single Lua code block delimited with -->8 comments. If I am editing the .p8 file with an external editor but still want to establish tabs for the internal editor, I add -->8 comments manually. If I add more tabs than the internal editor can handle (8 or more delimiters), code beyond the 8th tab is ignored.
It's a pretty edgy edge case to want both external editing and tabs for the internal editor, but I found this behavior surprising enough that I humbly request a tad more thought to it. I would agree that evaluating code that isn't displayed in the internal editor is not the right fix, nor is adding UI to support unlimited tabs. My preference would be to fail to load the file as if it didn't parse, with an explicit error message, or just consider everything beyond the 8th tab as part of the 8th tab.
The inline code syntax matcher is too greedy. A single instance runs past the closing backtick to the end of the paragraph:
One `two three` four five
One two three four five
Multiple instances in a paragraph help to illuminate what's happening: the styled span starts at the opening backtick but closes at the end of the paragraph, so multiple instances produces nested spans:
One `two` three `four` five
One two three four five
Chrome 76.0.3809.132, macOS 10.14.6. Cannot repro in Safari. Not sure when this started, but all of the web players on the BBS are blurry. Anyone else seeing this?
Web export from 0.1.12c still works fine, so I assume the BBS web player has an upgraded player with this regression.
Chrome 71 (December 2018) implements the new autoplay audio policy for the Web Audio API, which affects the Pico-8 web player. The BBS is OK because it implements a "curtain" that the user clicks on to start the player, which does the Web Audio enable interaction. But this breaks the exported web player as of Pico-8 0.1.11g: If I export a game to its own page then load the page, Pico-8 starts immediately and is disallowed sound. No interaction enables sound after this point.
One fix is for the exported web player to implement a curtain similar to the BBS. I don't know if that meets everyone's needs but would resolve the issue for the exported page. I assume we can work around this by implementing our own player curtain.
Interesting side note: This appears to affect stat() calls regarding sound as well. I have a cart that paused on stat(24) != 0, to wait for music to finish playing. The web export with sound disabled never gets past this point. I added a timeout for the pause to get around this, though I still don't have sound in this case.
I notice that the YouTube field of the BBS profile only accepts alphanumeric characters, and whatever is entered becomes a link of the form www.youtube.com/<alphanumericfield>. I'm mostly ignorant of how this part of YouTube works, but my understanding is that not everyone can reserve a youtube.com/<alphanumericfield> URL. You need a certain number of followers, have qualifying channel art, etc. Everyone gets a www.youtube.com/channel/<randomlyassignedalphanumeric> channel URL, but I can't enter that into my BBS profile and get a working link.
There's some history with G+ URLs that I've forgotten the details of. It looks like anyone can reserve a www.youtube.com/c/<alphanumericfield> URL. At least I have one, not sure how. But I can't enter that in either.
I think the YouTube profile field needs to accept more values and/or provide hints in the profile form on how to link a profile to a channel.
The BBS fails silently when I attempt to attach an image whose filename contains spaces. The upload appears to be successful, but it doesn't appear in the list of available images.
I remember this bug from the previous version of the BBS, so it's not new.
View Older Posts