I hang out in the pico-8 discord's #help channel, and I see a lot of questions that boil down to "my code isn't doing what I want, and I don't know what to do. help?" If you feel completely lost when your code doesn't work, this tutorial is for you!

PRINTH is the single most helpful tool I know for pico-8 debugging. When programming, your head can get out of sync with the computer, and you won't understand what it's doing. The best way I know to bring them back in sync is to slap down some PRINTHs all over the place! Print some info to see what your code is actually doing, and figure out exactly where the code starts to go off-track.

setup

Here's a video showing how to launch pico-8 with an attached console on Windows. You'll need to do this somehow, because PRINTH messages are only visible in the attached console.

The first 30 seconds of the video show how to create a shortcut to pico8.exe, and then edit that shortcut's "target" so that it will run from a console. After making it, you can move this shortcut anywhere you want.

The rest of the video walks through a simple debugging scenario, and ends by showing off PQ (see explanation below)

PQ

PRINTH itself can be a bit annoying to use, so I built a function called PQ that's nicer to use. You're free to copy it into any of your projects. If you find my functions helpful and you'd like to credit me, I'd appreciate it! but that's not required; feel free to use the functions for whatever you want.

PRINTH annoyances

PQ library

-- pq-debugging, by pancelor

-- quotes all args and prints to host console
-- usage:
--   pq("handles nils", many_vars, {tables=1, work=11, too=111})
function pq(...)
  printh(qq(...))
  return ...
end

-- quotes all arguments into a string
-- usage:
--   ?qq("p.x=",x,"p.y=",y)
function qq(...)
  local args=pack(...)
  local s=""
  for i=1,args.n do
    s..=quote(args[i]).." "
  end
  return s
end

-- quote a single thing
-- like tostr() but for tables
-- don't call this directly; call pq or qq instead
function quote(t, depth)
  depth=depth or 4 --avoid inf loop
  if type(t)~="table" or depth<=0 then return tostr(t) end

  local s="{"
  for k,v in pairs(t) do
    s..=tostr(k).."="..quote(v,depth-1)..","
  end
  return s.."}"
end

-- like sprintf (from c)
-- usage:
--   ?qf("%/% is %%",3,8,3/8*100,"%")
function qf(fmt,...)
  local parts,args=split(fmt,"%"),pack(...)
  local str=deli(parts,1)
  for ix,pt in ipairs(parts) do
    str..=quote(args[ix])..pt
  end
  if args.n~=#parts then
    -- uh oh! mismatched arg count
    str..="(extraqf:"..(args.n-#parts)..")"
  end
  return str
end
function pqf(...) printh(qf(...)) end

printh_helpers

Cart File | Forum Post |

	More cartridges by pancelor

More Cartridges [View All]

 

printh_helpers

by pancelor

Cart #printh_helpers-2 | 2022-08-07 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

20

Let me know if you found this helpful!

Excellent tutorial! I'm surprised it's so easy to do, I'd expect you'd have to make some PICO-8 game to receive it.

This is quite useful thanks!

Can this be done on a mac?

yes, sometimes I use a mac and I open Terminal in the folder where pico8 lives and run ./pico8 (I'm unsure what the exact name is). then the Terminal window stays open and the printh output is shown in that terminal.

I'm not happy with that setup, there's probably a more convenient way to do it. but I'm hardly ever on mac -- someone else would be able to make better instructions than me

pq() is super useful, was looking for something like this. Thanks!