Log In  

hi! here is some text for you to read.
some selected carts that I've uploaded here:

the tower

for more, see my itch page or my website

[ :: Read More :: ]

@zep o/

0.2.6b / linux:

  1. launch pico8 executable
  2. run poke(0x5f54,0x80) (in the console)
  3. run reboot
  4. run poke(0x5f54,0x80) (copied from the 0.2.6 release notes)
  5. the executable crashes

Step 2 is optional -- it still crashes in step 5 if you skip step 2
In Step 4, running poke(0x5f54,0x60) instead does not crash.

I'm not sure how to get a stacktrace on my machine, or if it's even possible. this is the best I know how to do:

> coredumpctl debug
           PID: 12604 (pico8)
           UID: 1000 (pancelor)
           GID: 1000 (pancelor)
        Signal: 11 (SEGV)
     Timestamp: Tue 2024-06-18 18:51:34 PDT (3min 17s ago)
  Command Line: /home/pancelor/.config/itch/apps/pico-8/pico-8/pico8 -root_path /run/media/pancelor/data/Users/pancelor/Documents/pancelor/src/pico8/
    Executable: /home/pancelor/.config/itch/apps/pico-8/pico-8/pico8
 Control Group: /user.slice/user-1000.slice/[email protected]/app.slice/app-pico8-b4acdb07c9cf4629b15a6b78f024fa7f.scope
          Unit: [email protected]
     User Unit: app-pico8-b4acdb07c9cf4629b15a6b78f024fa7f.scope
         Slice: user-1000.slice
     Owner UID: 1000 (pancelor)
       Boot ID: bc016245c64e47f1b3755470beec5d96
    Machine ID: 4eec57f899074b4eb49773a72b91be1c
      Hostname: pancelor-manjaro
       Storage: /var/lib/systemd/coredump/core.pico8.1000.bc016245c64e47f1b3755470beec5d96.12604.1718761894000000.zst (present)
  Size on Disk: 10.3M
       Message: Process 12604 (pico8) of user 1000 dumped core.

                Stack trace of thread 12604:
                #0  0x00000000004734e6 n/a (/home/pancelor/.config/itch/apps/pico-8/pico-8/pico8 + 0x734e6)
                ELF object binary architecture: AMD x86-64

Failed to invoke gdb: No such file or directory

tl;dr: SEGV at 0x734e6

P#150091 2024-06-19 01:38

[ :: Read More :: ]

Cart #wutewuwiho-1 | 2024-06-02 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

hi @zep! This cart should not error, but it does (pico8 0.2.6b / linux)

-- wrap everything in func _init to fix it
--function _init()

--uncomment this to fix it

--make this local to fix it
coro = cocreate(function()
  -- uncomment this to fix it
-- local x=1
  for i=0,32000 do
    -- flr() is arbitary here; it's
    -- just a func that should
    -- return only one value
    local rets = pack(flr(i))
    if #rets~=1 then
      local str="flr rvals:"
      for i,v in ipairs(rets) do
        str ..= "\n\t"..i..": "..tostr(v)
      str ..="\nstat(1): "..stat(1)
    -- uncomment this to fix it
--    if flr==flr then end


--remove second param to fix it
assert(coresume(coro, "uh-oh"))

print"no errors"

It seems like the string "uh oh" is being popped from the stack in a completely wrong place.

See also https://www.lexaloffle.com/bbs/?tid=141267 , a picotron coroutine bug. This cart is a modified version of @jesstelford's code there. I'm unsure if the root cause is related, but the result is the same.

Notably, this cart consistently crashes every single time (unlike the picotron version), and seems directly related to stat(1) going over 1.0

I marked a bunch of things you can uncomment to make this test case pass. (there are some very weird things you can do to make it suddenly work)

I'm fuzzy on the details, but it seems like something like this is happening:

  1. coresume(coro, "uh-oh") pushes "uh-oh" to the internal lua/C/lua_State stack, where it stays for a while (because there isn't a yield() that pops that value)
  2. the coroutine takes a long time (stat(1)>1), and pico8 pauses my cart to do its own thing (flip, etc)
  3. pico8 prepares to hand control back to my cart, by restoring the state my cart was in when it got forcibly paused. it restores the stack with "uh-oh" on it, but it does it wrong somehow
  4. my code resumes running, maybe right at the point where flr() returns? (that would be quite a coincidence, but it might explain why irrelevant changes like local x=1 would squash the bug)
  5. flr returns the correct value, but also the rest of the stack, which is "uh oh".
P#149328 2024-06-02 04:59

[ :: Read More :: ]

I'm pretty sure this is a bug; I'm on pico8 0.2.6b / linux

You can turn on character wrapping with 0x5f36 / 24374, but it acts unexpectedly when you move the camera:

poke(0x5f36,0x80) --turn on character wrapping

Expected behavior: both prints should wrap at the edge of the screen.
Actual behavior:

There's a similar issue with p8scii "\^r" wrapping:

msg='\^rf0123456789abcdefghijklmnopqrstuvwxyz' --note p8scii wrap at start
P#148878 2024-05-23 21:45 ( Edited 2024-05-23 21:47)

[ :: Read More :: ]

cart A: (broken)

msg="havent pressed test yet"
menuitem(1,"★test",function() msg="pressed test!" end)

?"\^1\^c" --https://www.lexaloffle.com/dl/docs/pico-8_manual.html#Control_Codes
goto _

cart B: (working)

msg="havent pressed test yet"
menuitem(1,"★test",function() msg="pressed test!" end)

flip()?"\^c" --this line is the only difference
goto _

These two carts should behave the same, but the menuitem function in cart A never runs -- after opening the menu and selecting the menuitem, it still says "havent pressed test yet"

cart B works as expected -- it says "pressed test!"

My system is linux / pico8 0.2.6b

P#148533 2024-05-17 11:49

[ :: Read More :: ]

Cart #make_ten-3 | 2024-06-05 | Code ▽ | Embed ▽ | No License

Select numbers that add to ten, to remove them from the board. How high can you score in just 2 minutes?

An homage to Fruit Box. A FruitBox-like? There are some big differences in this version, the most obvious being the lack of music. (the music in the original is incredible)

How to play

  • Drag your mouse to select groups of numbers that add up to 10.
  • I recommend playing in fullscreen; it's easier to click on larger numbers.
  • In the original game, you're awarded one point per number removed,
  • Get the highest score you can within 2 minutes. Good luck!

This was my submission for TweetTweetJam 9, written in 490 characters of code:

e=1x=stat(32)y=stat(33)if btn(5)do f=mid(16,96,y)if(p==a)p=x q=f?"⁷i6v1c1"
😐=c&min(x,p)⌂=c&min(f,q)♪=c&max(x,p)♥=c&max(f,q)else if(p)p=a if(n==c)e=0?"⁷i7f1a"
n=2for i=32,207do w=z[i]or rnd(9)\1+1u=i%16*8v=c&i\2if(u-😐|♪-u|v-⌂|♥-v>0)w*=e n-=w ⬅️+=➡️&~e
end?"⁶jc1score "..s,-🅾️
if(d==-128)➡️=0g="⁶j8rtime up!"⬇️=🅾️?"⁷v3fg"
goto _

There's a commented version here.

See also: itch | mastodon | cohost

Deluxe edition

Coming soon! Check itch for updates.

P#148268 2024-05-11 11:27 ( Edited 2024-06-05 06:14)

[ :: Read More :: ]

@zep This maybe isn't a bug, but it feels very weird to me:

if (1)<2 print"a"

this prints a b, but I would expect a syntax error instead -- the condition is "1<2" but the if-shorthand parens are only surrounding the 1, instead of the whole condition.

(if you change it to if (1)<0 then it only prints "b", which verifies that the condition isn't being interpreted as just if (1) or something like that)

oh, and my system is pico8 0.2.6b / linux

P#148160 2024-05-09 01:02 ( Edited 2024-05-09 01:16)

[ :: Read More :: ]

Hi @zep!

pico8 0.2.6b / linux:

if (false)?1 --hi

expected output: 2 3
actual output: 3

Here's an altered version that works as expected:

if (false)?1

(this prints 2 3, as expected)

3 things seem required to trigger this bug:

  1. shorthand if
  2. shorthand print on the same line
  3. !! further text after the shorthand print (" --hi", in this example. but just a single trailing space triggers the bug too)

When these are all true, the next line seems to get scooped up into the shorthand line. This can include attaching an else to the wrong if, like in this more complicated example:

if false then
 if (false)?1 --hi

expected output: 2 3 4
actual output: 4

P#148053 2024-05-07 11:54

[ :: Read More :: ]

This is a silent tutorial video; skip to 2:10 for the juicy bit:

This is an animated wallpaper that shows your custom PNG files -- just place them in a particular folder! It also works as a screensaver. It's cpu-friendly, only drawing during transitions.


  • load #photo_carousel
  • mkdir /appdata/system/wallpapers
  • save /appdata/system/wallpapers/photo_carousel.p64
  • run the cart once, to generate the appdata folder
  • cd /appdata/photo_carousel
  • folder
  • using your host OS, copy any PNG files into this folder (don't put them in subfolders)
  • set your wallpaper to photo_carousel in System Settings


Run podtree /appdata/photo_carousel/settings.pod to edit the settings. Be sure to not press enter while editing (this crashes Picotron 0.1.0e) and you must save with the mouse, not ctrl-s (another Picotron bug(?) -- ctrl-s saves the current cart, instead of the settings file)

Set the transition time to 0 to disable transitions


Converting PNGs

This cart uses importpng to convert PNG files into Picotron graphics. It does this once, in the background, and caches the results.

If you edit one of your PNGs, photo_carousel won't notice (afaik it's impossible to get last-edited time of PNGs in Picotron) Rename your file to generate a new cache entry, or delete /appdata/photo_carousel/cache.pod to regenerate the entire cache.

importpng is fast, but it's sometimes lacking in its ability to convert images into Picotron's palette. If you want better colors, you should use an external tool (like Aseprite) to convert your PNG into the base Picotron palette (you'll want the base palette, because the global palette changes to the base palette whenever you focus on some other window)

In the future I may use PNG Frame to get better colors by default, but I haven't done that work yet.


You can add your own transitions -- you can skim through src/subdraw.lua without needing to understand anything else in the cart, and add new entries to the list of "subdraws" (transitions). Its very shadery/demosceney code

Many of the subdraws use some helper functions in src/tools.lua

Post your transition code here!

CPU usage

The cart uses about 0.002 cpu (0.2%) most of the time. During transitions, it can spike up to 25% cpu or so (depending on the transition). If you care, you can disable the transitions as a whole (by editing the settings) or individually (by editing the multi-line comments in src/subdraw.lua)


Here's the cart file. (It won't work here on the BBS, you need to download it)

P#145966 2024-04-07 11:59 ( Edited 2024-04-07 12:20)

[ :: Read More :: ]

hey @zep, I've found a nasty coroutine(?)/multival bug. I'm on Linux + picotron 0.1.0d.

tl;dr: sometimes select("#",tostr(i)) is 2, possibly triggered by calling coresume() with extra args.

I ran into this initially because add({},3,nil) is a runtime error now (it used to work in PICO-8, but now it throws bad argument #2 to 'add' (position out of bounds)). I had some code: add(list,quote(arg)) that was crashing as if quote() was returning a second value for some reason, even though the code for quote() definitely returned just one value. (surrounding it in parens (to only keep the first return value) fixed my bug: add(list,(quote(arg))))

Version A of the code is very short, and trips the assert inside spin maybe 50% of the time? sometimes many runs in a row don't trigger the assert, but sometimes many runs in a row all trigger the assert. (maybe that's just statistics tho). Version B is a bit more complex but always trips the assert instantly for me.

Version A: (short, inconsistent)


function _init()
    local bad,good = cocreate_spin()
    fn = bad
function _draw()
    local _,prog = fn(0.70)
    ?prog or "done"

function cocreate_spin()
    local coro = cocreate(spin)
    return function( cpu_limit)
        if costatus(coro)=="suspended" then
            --this one breaks sometimes
            return assert(coresume(coro,cpu_limit or 0.90))
    end, function()
        if costatus(coro)=="suspended" then
            --this one always works
            return assert(coresume(coro))

local total = 1000000
function spin()
    for i=1,total do
        if i%10000==0 --[[and stat(1)>cpu_limit]] then
        local n = select("#",quote(i))
        if n!=1 then
            assert(false,tostr(n).." retvals?! "..i)

function quote(t)
    return tostr(t)

Version B: (longer, very consistent)


function _init()
    poke(0x5f36,0x80) -- wrap text
        title="import png",
    job = job_importpng()
function _update()
function _draw()

function job_importpng()
    local coro = cocreate(pq_many)
    local job = {
        coro = coro,
        progress = 0.00,
    -- returns true iff job has more work to do
    function job:work( cpu_limit)
        if costatus(self.coro)=="suspended" then
            local _,dat = assert(coresume(self.coro,cpu_limit or 0.90))
            if dat then
                self.progress = dat
                return true -- more work to do
    return job

function pq_many()
    for i=1,1000000 do
        if i&2047==0 then

-- quotes all args and prints to host console
-- usage:
--   pq("handles nils", many_vars, {tables=1, work=11, too=111})
function pq(arg)
    local s= {}
        local n = select("#",quote(arg))
        if n!=1 then
            local second = select(2,quote(arg))
            assert(false,tostr(n).." retvals?: "..quote(arg).." "..tostr(second))
        -- add(s,quote(arg))
    printh(table.concat(s," "))

-- quote a single thing
-- like tostr() but for tables
-- don't call this directly; call pq or qq instead
function quote(t)
    if type(t)~="table" then return tostr(t) end
    local s={}
    for k,v in pairs(t) do
    return "{"..table.concat(s,",").."}"

As noted in Version A, the two coresume-wrapping-functions inside cocreate_spin() act differently -- I've never been able to trip the assert with the "good" version. I've tried versions of this code with no coroutines and haven't been able to trip the assert.

idk what else to say, this bug seems baffling -- sometimes select("#",quote(i)) is 2, despite quote() being a wrapper for tostr()

P#145091 2024-03-30 08:35

[ :: Read More :: ]

Cart #importpng-9 | 2024-04-06 | Embed ▽ | License: CC4-BY-NC-SA


Currently (in Picotron 0.1.0e) it's hard to use a PNG image as a sprite. You can fetch("myimage.png"), but the result isn't in the right image format. So, here's a small tool to convert PNG files into picotron sprites.

Drag any .png or .qoi image into the tool to convert it into a sprite pod on your clipboard. You can paste this into the graphics editor, or into code.

Drag in a .hex file (e.g. from lospec.com) or a .pal file (e.g. from OkPal) before importing your png to change the import palette.


Import speed

This tool prioritizes import speed. Images with only a few unique colors (e.g. an image already in the picotron palette) will import much faster than images with many colors.

Color quantization

You can use any colors, and the tool will try it's best to fit them to the palette. It isn't very smart about converting colors (it uses nearest euclidean distance in RGB space, and doesn't do any dithering). If you want better color conversion, use some external tool and make sure the PNG is in the correct palette before converting it with this tool.

See also PNG Frame, in "Related tools" below.


If you're making a desktop wallpaper, I think you should stick to the default palette. If you use a custom palette, then your colors will change whenever you focus some window besides the desktop, I'm pretty sure.

To make a wallpaper:

  • make sure your wallpaper folder exists (mkdir /appdata/system/wallpapers)
  • save a new cart into that folder with this code:
    function _draw()
        _draw = function() end
  • convert your image using this tool, and copy it into your clipboard
  • paste your image into sprite 1 of the default sprite file

Library usage

This code is organized to make it easy to use as a library in your code. The library is self-contained in lib/importpng.lua, and you interact with it by calling myjob = job_importpng(myimg). The returned "job" is essentially a coroutine, but one that will let you limit its processing time. Call myjob:work(limit) during _update() until the job is done, or call myjob:join() a single time to finish it all at once (likely lagging the game). See the code for more details.

License: CC4-BY-NC-SA

Related tools

  • Cutievirus' PNG Frame -- a similar tool with much better color conversion. If your png is already in the right palette, importpng is faster than PNG Frame. But if you want better color quantization, use PNG Frame.
  • My Aseprite PICO-8/Picotron export extension lets you export Picotron pods directly to your clipboard from Aseprite.
  • My sprite importer lets you import PICO-8 spritesheets into Picotron.
  • My photo carousel uses this importer to show your custom PNGs as an animated wallpaper.
  • drakmaniso's OkPal palette editor.


v0.4 (#importpng-9)

  • add QOI image support - thanks to vebrun for prompting me to add it!

v0.3 (#importpng-7)

  • support for custom palettes
  • make it easy to use importpng as a library

v0.2 (#importpng-6)

  • show image as it imports
  • draw black in preview (not transparent anymore)
  • export to compressed pod format

v0.1 (#importpng-4)

  • initial release
P#144661 2024-03-27 11:24 ( Edited 2024-04-09 01:04)

[ :: Read More :: ]

Cart #p8x8-7 | 2024-05-04 | Embed ▽ | No License

p8x8: convert PICO-8 carts into Picotron carts (some assembly required)

I'm declaring p8x8 good enough for public release! It's a tool to convert pico8 carts to picotron -- it's not perfect and it requires some manual intervention in most cases, but it's magical being able to play a bunch of games on the new system without much effort.

Lots more info (instructions, compatibility notes, CC license, etc) here: https://github.com/pancelor/p8x8/

Teaser video here: https://mastodon.social/@pancelor/112162470395945383


v1.8 (#p8x8-8, unreleased)

  • music/sfx conversion!! just waiting on picotron 010h to add instrument effects

v1.7 (#p8x8-7)

  • fix secret palette
  • add more docs
  • add p8x8_symbol_visual() and p8x8_datastring() alongside p8x8_symbol() to help convert symbols. details

v1.6 (#p8x8-6)

  • speed up dget/dset (batch disk writes)
  • speed up map() (use picotron's builtin map() which does much better camera culling)
  • add support for pico8 "secret palette"

v1.5 (#p8x8-5)

  • custom fonts work now
    • docs + snippet for making custom fonts work even if you set them up with p8scii
  • fix player 2 btn/btnp
  • some progress on porting sfx
  • minor bugfix: prevent crash when input cart has no gfx section

v1.4 (#p8x8-4)

  • bugfixes for add(), rnd()
  • organize github docs
  • fix sfx()/music() (used to be noop; now passthrough to p64)

v1.3 (#p8x8-3)

  • better default fullscreen border
  • better warnings

v1.2 (#p8x8-2)

  • support fullscreen border images
  • easier main.lua tweaking (fullscreen, pause_when_unfocused)
  • more docs / warnings / ux

v1.1 (#p8x8-1)

  • nicer error/warning handling (e.g. when there's no code section)
  • handle windows CRLF carts properly
  • generate warnings much faster (smarter sorting algorithm)

v1.0 (#p8x8-0)

  • public release
P#144532 2024-03-26 14:35 ( Edited 2024-05-11 03:38)

[ :: Read More :: ]

Here's my /appdata/system/startup.lua file (picotron automatically runs it on startup)

-- take str, delete all chars between
-- indices i0 and i1 (inclusive), and
-- insert newstr into that space
local function splice(str,i0,i1, newstr)
    return sub(str,1,max(1,i0)-1)..(newstr or "")..sub(str,i1+1)

-- use str:find to do sed-like file editing.
-- no lua patterns, just literal string matching
-- return str, but replace the first instance of cut with paste
local function _replace(str,cut,paste)
    local i0,i1 = str:find(cut,1,true) -- no pattern-matching
    if not i0 then
        return str,false
    return splice(str,i0,i1,paste),true

local function sedish(fname,mods)
    local src = fetch(fname)
    if not src then
        printh("sedish: couldn't find file "..fname)

    for i,mod in ipairs(mods) do
        local cut,paste = unpack(mod)
        -- printh(cut.." "..paste)
        if not cut or not paste then
            printh("sedish: bad cut/paste data in "..fname)
        local changed
        src,changed = _replace(src,cut,paste)
        if not changed then
            printh("sedish: mod #"..i.." did nothing to "..fname)
        if not src or #src==0 then
            printh("sedish: bad result in "..fname)
    -- printh("storing "..fname..": "..sub(src,1,100):gsub("[\n\r]",""))

    { -- fix alt-tab annoyance (pressing alt-tab inserts tab character into code)
        [[if (keyp("tab")) then]],
        [[if keyp"tab" and not key"alt" then]],

    { -- fix podtree bug (pressing enter crashes the program)
        [[if(key("shift")) return true]],
        [[if(_ENV.key("shift")) return true]],

-- (you need to open a new gfx tab for these gfx.p64 edits to work)
    { -- show pal numbers
        [[pcols[x + y*epr])]],
        [[pcols[x + y*epr])if pal_swatch==1 and x%2==0 then print(pcols[x + y*epr],x*ww+5,y*ww+1,0) end]],
-- sedish("/system/apps/gfx.p64/nav.lua",{
--  { -- display sprite numbers in hex
--      [[string.format("%03d",current_item)]],
--      [[string.format("x%02x",current_item)]],
--  },
-- })
    { -- don't flip when you press ctrl-v (noticeable when undoing)
        [[if (keyp("v"))]],
        [[if (keyp"v" and not key"ctrl")]],

    { -- fix custom key callbacks in gui

-- doesn't work for startup terminal
--   need to wait for it to regenerate, e.g. after running a fullscreen app
    { -- add custom terminal_cd event (to let my z.lua util "run" cd for you)
        [[-- scroll down only if needed]],
        [[on_event("terminal_cd",function(msg) cd(msg.path) end)]],
    { -- show slightly different terminal prompt when in upgraded terminal
        [[return result -- custom prompt goes here]],
        [[return "\f6"..pwd().."\f7 > "]],

printh "sedish done"

what is this

I made this because picotron inserts a tab into my code whenever I alt-tab. I figured out how to edit the code editor itself to not do that, and then I made this script to automatically make the required edits. (you can't just edit the files on disk, because they get regenerated every time picotron boots)

this won't be necessary for too long hopefully, but it works great for now!

(the name "sedish" comes from the (loose) inspiration for this: sed)

post your tweaks

If anyone has other system tweaks like this one (fixing alt-tab), post them here!

P#143638 2024-03-18 04:05 ( Edited 2024-04-24 01:28)

[ :: Read More :: ]

update: there are basically 3 tools that are relevant here:

  • this tool (sprimp) -- maybe still useful, but superceded by p8x8:
  • p8x8: a tool to fully convert PICO-8 carts to Picotron carts (some assembly required) -- this grew out of sprimp
  • my aseprite exporter plugin -- still useful

You probably want to check out p8x8 instead, but I'm leaving this thread as it is since it may still be useful or interesting to some people.

Cart #sprimp-1 | 2024-03-18 | Embed ▽ | License: CC4-BY-NC-SA

tada! now you can import pico8 spritesheets. and map too!

importing a .p8 file

  • put your game.p8 file somewhere inside picotron's file system
    • the filename should not have any dashes ("-"), they generally cause problems currently (picotron 0.1.0b2)
  • run this importer (sprimp)
  • import the p8 cart
    • you can drag-and-drop the cart onto the sprimp window
    • or you can use "Import .p8 file" in the menu (the dialog that pops up says "save as" -- please ignore this. this is the best way I know how to launch a system filepicker)

exporting sprites

  • press "Save gfx..". choose a filename; the default is /ram/cart/gfx/0.gfx (which is the default spritesheet for your current cart)
  • IMPORTANT: if the spritesheet was already open in picotron's gfx editor, you'll need to close the file and reopen it (right click on the tab, close, then press the plus)
  • if you saved to /ram/cart/... save your cart afterwards (ctrl-s)

exporting map

  • (same as exporting sprites, just click "Save map.." instead)
  • for an easy transition from pico8 maps to picotron maps, check out this snippet, which includes mget and mset replacements

other ways to import (copypaste, aseprite)

importing sprite by copy-paste

  • open the pico8 sprite editor
  • copy the entire spritesheet (press tab, ctrl-a, ctrl-c)
  • your clipboard now has a [gfx]... code in it
  • open this tool (sprimp) in picotron
  • past the [gfx]... code into the tool

importing a single sprite

  • you can copy from pico8 and paste into picotron directly, zep made that work already
  • you can even paste your entire spritesheet into a single picotron sprite -- it's sorta wild. but you probably wanted to spread the spritesheet out into individual sprites, right? that's where this tool can help

importing from aseprite

you can use my exporter script for aseprite to export aseprite images into the [gfx]... format, letting you paste them into picotron or sprimp (or even pico8!)

future plans

  • Yes: Make importing sprites/maps easy. (mostly done! still some UI/UX work tho)
  • Done but not yet published: importing p8 code tabs into .lua files. with a big disclaimer that you'll need to do a bunch of manual work to fix the code afterward (edit: this is now published as p8x8)
  • Maybe: sfx/music. I likely won't do this myself. If you have a working sfx/music importer and want to join forces, let me know!
  • No: make it possible to drag-and-drop a pico8 cart into picotron and have everything "just work". this is not meant to be a perfect emulator, just a stepping stone

maybe zep will add improvements to picotron itself, and this whole project will no longer be relevant. that would be great! but whether or not that happens, this was a fun small project for me to learn some basics of picotron tool-making



  • add .p8 import -- thank you @Krystman for the idea!
  • add drag-and-drop support
  • add map import/export


  • sprite import/export
P#143506 2024-03-17 13:58 ( Edited 2024-04-29 13:40)

[ :: Read More :: ]

Cart #susizker-0 | 2024-03-15 | Embed ▽ | License: CC4-BY-NC-SA

just a port of a tweetcart of mine to the new system :)

move this into /system/screensavers/ and it'll show up as an option in your settings

If you run it on its own as a cart, you'll want to run reset() vid(0) in the console afterwards to get things back to normal

edit: if you want it to be permanently available, you need to put it in /appdata/system/screensavers (otherwise, you need to re-add it every time you start picotron). create the folder by copying the system folder: cp /system/screensavers /appdata/system/screensavers

P#143111 2024-03-15 13:37 ( Edited 2024-03-17 07:36)

[ :: Read More :: ]

Cart #ghostpatrol-2 | 2023-10-07 | Code ▽ | Embed ▽ | No License

Oh no, ghosts are approaching the town!

Mayor Wombledon has begged ALFREDO THE GHOUL BANISHER to team up with THE WILY WIZ to protect the town. Can they put aside their differences and work together, or will evil spirits devour the populace?


  • Arrow keys: move
  • Z: swap heroes
  • Enter/P: pause (level select, volume controls)
  • X: next level


  • 1 night protected: You have the villagers' sincere gratitude 🙏
  • 5 nights protected: The villagers are beginning to hope again 😭
  • 10 nights protected: Valiant Heroes 🏆
  • 40 nights protected: Local Deity 🤯


  • Alfredo can dig up graves with his fearsome claws.
  • The Wiz can swap places with nearly anything.
  • You can change levels freely in the pause menu.
  • Never give up; always fight with your full strength.

1024 bytes, made by pancelor for PICO-1K 2023. Thanks to timp + shrinko8 for compression help!

The layouts were randomly generated, but they don't change. My best times for the first 5 levels are 7 / 11 / 15 / 39 / 41.

If you enjoyed this, you might also enjoy my game Hungry Eggbug, or the board game that loosely inspired this game: Ricochet Robots.

P#135418 2023-10-04 21:47 ( Edited 2023-10-07 02:35)

[ :: Read More :: ]

Hi @zep, found a parser bug for ya:

for --[[a]]e=0,1 do print(e) end

expected: 0 1 [nil] (this is what lua 5.4 outputs)
observed: [nil] 0

pico-8's highlighting works correctly, but the runtime seems to see this somehow:



system: linux / pico8 0.2.5g

I ran into this while using shrinko8's annotations (for --[[preserve]]e=0,1 do)

Workaround: add an extra space (for --[[preserve]] e=0,1 do)

edit: ah! this thread has more cases / info: https://www.lexaloffle.com/bbs/?tid=51618

P#135201 2023-10-01 10:22 ( Edited 2023-10-05 04:16)

[ :: Read More :: ]

@zep if you open this cart in pico8 and save it, pico8 inserts an extra byte at the end (0xff) (this is wrong, but additionally it is very confusing because my text editor thinks the text encoding has changed and starts displaying weird unicode everywhere)

pico-8 cartridge // http://www.pico-8.com
version 41

After some minimal testing, the conditions necessary seem to be:

  1. the file ends with a __meta__ section (__gfx__ doesn't trigger the bug)
  2. the file does not have a trailing newline (the last byte of this particular file is 'e', not '\n')

platform: linux / pico8: 0.2.5g

P#135184 2023-10-01 00:14

[ :: Read More :: ]

Bitplanes are powerful, but they can be difficult to understand. How do you use them in PICO-8?

The short version: bitplanes let you draw colors to the screen without completely overwriting the existing colors, making it possible to do effects like shadows, transparency, etc. But be warned: they come with a lot of unintuitive restrictions, like monopolizing half your screen palette or requiring it to be set up in a particular way.

Longer version: PICO-8 colors are 4-bit numbers (0-15). The screen is a 128x128 4-bit image, but you can imagine it as 4 separate 12x128 1-bit images overlaid on top of each other. By poking a particular location in memory, we can tell PICO-8 to draw to these "bit planes" separately. Normally, drawing overwrites any existing colors, but if we selectively disable some of the bitplanes, some bits of the old color will remain onscreen.

Technical version: see "Technical details" below.

This post lists some specific examples and tricks that you can do with bitplanes. I won't attempt to fully explain how bitplanes work, but I'll leave some resources at the end.



  1. set up your screen palette:
    i. 0-7: shadow palette; 0 is the shadow color for 8, 1 is the shadow color for 9, etc
    ii. 8-15: any colors
  2. draw anything
  3. enable bitplane mode 0x08 (clear the 0/8 bitplane)
  4. draw anything -- any pixels "drawn" will instead overwrite colors 8-15 with their shadow colors
  5. disable bitplane mode

Cart #bitplane_shadows-2 | 2023-09-21 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

I used this method in my freecell clone.


  1. set up your screen palette:
    i. 0-7: all identical; e.g. all 0 (black)
    ii. 8-15: any colors
  2. draw your scene using colors 0-7. they will all appear black
  3. enable bitplane mode 0xf8 (only draw the 0/8 bit)
  4. draw a circfill in color 8 -- instead of drawing red, it will add 8 to each color it hits, revealing the image "underneath" the darkness
  5. disable bitplane mode

This cart uses a very similar technique to create an "xray" effect. (They set up their palette differently and use a different bitplane mode, swapping adjacent colors instead of shifting the palette by 8)

1-bit sprite packing

If you have 1-bit sprites, you can store them merged in the 4 bitplanes in the spritesheet, and extract them at runtime using bitplanes. It's essentially another way to do this sprite-layering technique. Here's a tool that does something similar. Neither of these actually use pico8's bitplane feature, but they could be implemented that way to save some tokens and a tiny bit of cpu.

Chromatic aberration

You can create some cool effects (like https://mastodon.social/@zep/109315783011955478) by drawing slightly different images on different bitplanes.

Trippy motion blur

Flashing lights warning, this one can be pretty rough on the eyes. It's a neat trippy effect where each bitplane gets updated every 4 frames, leaving a slightly out-of-date impression onscreen for those other 3 frames, which creates a motion blur of sorts. I find it hard to look at (especially the jelpi example in the replies!) but it looks fascinating and it's very neat how bitplanes make it easy to create this effect in any game. I wonder how this could look with palette specifically designed for it... (the palette from the following "Anti-aliasing" example works decently well!)

(thanks freds72 for finding the link to this! I couldn't remember where I'd seen it)


You can add anti-aliasing by drawing the same thing at slight subpixel offsets, like in this example. (Note that this restricts your palette to 5 colors)

Technical details

Wikipedia has some general info, and the PICO-8 wiki (search "bitplane") has specifics about how they work in PICO-8:

> 0x5f5e / 24414
> Allows PICO-8 to mask out certain bits of the input source color of drawing operations, and to write to specific bitplanes in the screen (there's 4 of them since PICO-8 uses a 4BPP display). Bits 0..3 indicate which bitplanes should be set to the new color value, while bits 4..7 indicate which input color bits to keep.
> For example, poke(0x5f5e, 0b00110111) will cause drawing operations to write to bitplanes 0, 1, and 2 only, with 0 and 1 receiving the color value bits, 2 being cleared, and 3 being unaltered.
> This formula is applied for every pixel written:
> dst_color = (dst_color & ~write_mask) | (src_color & write_mask & read_mask)

If you're not sure what to try, setting the write_mask and read_mask to the same value is often useful.

Other resources

-Bitwise math tutorial
-A simple bitplane example -- three circles rotating in 3D
-My bitplane explorer -- it helps visualize how colors will interact

-The original discovery
-Bitplanes confirmed by zep
-Circular Clipping Masks -- discusses other non-bitplane ways to get shadow and spotlight effects

P#134693 2023-09-21 11:11 ( Edited 2023-09-24 09:27)

[ :: Read More :: ]

PICO-8 supports bitplane drawing; the wiki (search "bitplane") has a description of how they work:

> 0x5f5e / 24414
> Allows PICO-8 to mask out certain bits of the input source color of drawing operations, and to write to specific bitplanes in the screen (there's 4 of them since PICO-8 uses a 4BPP display). Bits 0..3 indicate which bitplanes should be set to the new color value, while bits 4..7 indicate which input color bits to keep.
> For example, poke(0x5f5e, 0b00110111) will cause drawing operations to write to bitplanes 0, 1, and 2 only, with 0 and 1 receiving the color value bits, 2 being cleared, and 3 being unaltered.
> This formula is applied for every pixel written:
> dst_color = (dst_color & ~write_mask) | (src_color & write_mask & read_mask)

This is precise and correct, but I find it a bit hard to understand. So I made this cart to give myself an interactive sandbox where I can play around with bitplanes, to see how they affect drawing.

Cart #bitplane_explorer-1 | 2023-09-21 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

The code is straightforward:

  1. draw the full 16-color palette
  2. enable bitplanes, using the poke shown onscreen
  3. draw a circle, using the circfill shown onscreen

You can change the bitplane settings and the circle's "color" -- the controls are shown onscreen. This interactively shows how drawing any color will interact with any other color under the current bitplane settings.

You'll still need to study the description from the wiki to understand how to use bitplanes, but this cart is a helpful supplement for me when working with bitplanes. I hope you find it helpful too!

P#134692 2023-09-21 02:13 ( Edited 2023-09-21 10:01)

[ :: Read More :: ]

update 2024: the 0.2.6 update improves things! search the update post for menuitem(0x301 for details. (My original menuitem post remains below, unchanged)

PICO-8 has fancy menuitems but there are some gotchas and bugs to be aware of.

Here's an example of what I do by default; the rest of this post will explain how the code works and why I do things this way:

Cart #menuitems-1 | 2023-08-21 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

L/R pitfall

Imagine you want to add a "mute" button to your game's menu. Can you spot the issue with this code?

function _init()
    ismuted=not ismuted
    -- ... play/pause the music
  -- ... other game init

The issue: left/right can be used to change the menuitem, and left/right always leaves the menu open afterward (this may be a bug; it's unclear) so there's no indication to the player that they accidentally muted the game! It's a minor issue... but it's easy to accidentally hit left/right when navigating the menu on a gamepad, which makes this worse.

An easy fix: don't respond to L/R (menuitem(1,"mute",function(bb) if bb>=16 then ... end end)). This is what I'd recommend for games that are short on tokens but willing to spare a few to fix this.

Responsive menu

If you'd like a more responsive menu, you can do this:

function _init()
  menuitem(1,ismuted and "music: off" or "music: on",function()
    ismuted=not ismuted
    -- ... play/pause the music
    -- update the label:
    menuitem(nil,ismuted and "music: off" or "music: on") -- feels like we could save some tokens...
    return true
  -- ... other game init

Now the option shows its status, and updates its label immediately when you change it!

Note the return true -- this keeps the menu open. Without this, if the player presses left (toggling the setting) and then presses enter (trying to close the menu but instead toggling the setting again), they'll wonder why their change isn't sticking. By leaving the menu open, we show them that they actually re-toggled the setting, and they need to choose "continue" instead to resume the game.

Code organization idiom

The repeated ismuted and "music: off" or "music: on" is suspicious -- can we save some tokens? Yes, by setting up each menuitem() again at the end of the callback, just to refresh the labels:

function _init()
  domenuitems() -- setup all menuitem()s
  -- ... other game init
function domenuitems()
  menuitem(1,ismuted and "music: off" or "music: on",function()
    ismuted=not ismuted
    -- ... play/pause the music
    domenuitems() -- refresh the label
    return true
  -- menuitem(2,...
  -- menuitem(3,...

I do this for code-organizing reasons -- it's nice to have all the menuitem code in one place -- but it can also save a few tokens, depending on your setup.

Context-dependent menuitems

Some menuitems should only be show in certain situations -- e.g. don't show "back to title" if we're already on the title screen. You could break each menuitem into its own little setup function (like zep's original LOAD #CUSTOM_MENU cart does -- check it out, it's nice!) or do what I do: menuitem(1,condition and "label",...). This will only show the menuitem when condition is truthy. I call domenuitems() anytime the menu needs changing (e.g. at the end of init_title_screen()) and it all works out.

Recommendations / Summary

I put all my menuitem() calls inside a custom domenuitems() function. Every callback runs domenuitems() at the end, to refresh the labels.

There are three types of menu options I commonly use: commands, toggles, and selectors.

  • For commands (run some code, e.g. return to the title screen), I wrap the callback code in a if bb>=16 then ... end block, to prevent L/R from triggering the command
  • For toggles (e.g. mute/unmute the game), my callback always has return true, leaving the menu open afterward and avoiding the UX issue described above
  • For selectors (choose a number from a range, e.g. change levels), my callback has return bb<16, leaving the menu open only if L/R were used to change the selection. (this is technically unnecessary due to a longstanding bug(?) in PICO-8's menu handling)

Read the code of the example cart at the top of this post for more info!

P#133332 2023-08-21 01:02 ( Edited 2024-03-14 08:32)

View Older Posts