Log In  



I often see questions in the pico-8 discord's #help channel, 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! Or anyone really -- I personally use PRINTH/PQ constantly and it makes programming about a hundred times easier.

PRINTH ("print to host console") 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 out some info to see what your code is actually doing, and figure out exactly where the code starts to stray from what you intended.

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)

Linux/Mac:


You can make this work on Linux or Mac too of course, but making tutorials is work. Here's some tips to get you started:

Linux

Run pico8 from a terminal. Or, add Terminal=true to your pico8.desktop file -- that's my current setup!

Mac

Run pico8 from a terminal. If anyone knows a way to make a double-clickable mac application that launches with a terminal, let me know! Saving this file as pico8.command (and chmod-ing it to be executable) might work, but I haven't tested it:

 
#!/bin/bash

/full/path/to/pico8.app

(You'll need to edit that to use the program's actual path)

PQ

PRINTH itself can be a bit annoying to use, so I built a function called PQ that's nicer to use. Feel 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!

PRINTH annoyances

  • printh({x=1,y=3}) prints "[table]" - not very helpful!
  • to print multiple things at once, you need to type printh("x="..x..",".."y="..y), which is cumbersome
  • actually, that won't even work if x is nil (which happens frequently while debugging) -- you have to type printh("x="..tostr(x)..",".."y="..tostr(y)) instead

These annoyances are fixed by PQ: pq("x=", x, "maybenil=", maybenil, {tables=1, work=11, too=111}) is much easier to type and will nicely print each argument. Being easy to type is very important -- these are temporary statements you add while debugging, to be removed after you figure out the problem. Reducing friction as much as possible lets you fix the problem faster. This is also why it's named "pq" -- it's easy to type and easy to search for (to remove afterwards)

PQ library code

 
-- pancelor's pq-debugging

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

-- quote all arguments into a string
-- usage:
--   x=2 y=3 ?qq("x=",x,"y=",y)
function qq(...)
  local s,args="",pack(...)
  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

why not just PRINT?

Why go to the trouble of setting up a host console and printing there with PRINTH/PQ instead of just printing to the screen with PRINT? A few reasons:

  • If you PRINT during the _UPDATE half of your game, those prints will be overwritten by the CLS at the start of your _DRAW function.
  • Your game has bugs that you're trying to track down, that's why you're debugging. Are you sure that those bugs aren't somehow preventing or overwriting your PRINT statements?
  • You can PRINTH the same thing on multiple frames then scroll through the history in the host console.

There's just too much extra stuff that happens between PRINT and when your eyes see the results. You want to be confident that your debugging system doesn't itself have bugs, so dumping the text as fast as possible (to the host console) is perfect.

If you can't/won't set up a host console for some reason, STOP is an ok alternative to PRINTH. Call stop("x="..tostr(x)) or stop(qq("x=",x)), then type r to resume your game after it hits the STOP statement.

example cart

This cart isn't too interesting to play, but I put it here to make it easy to download (load #printh_helpers)

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

Alright that's it, my One Secret Trick for programming/debugging. Let me know if you found this helpful!

24
1

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.
1

This is quite useful thanks!

Can this be done on a mac?
1

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
1

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

I finally made an account purely to be able to comment that this is a game changer, thank you so much for putting this together. Just making my way through a tutorial and got stuck on a bit - haven't worked out what exactly is wrong yet, but I have so much more visibility about what's happening under the hood!
1

Very useful. Thank you!



[Please log in to post a comment]