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 a bunch of info to see what your code is actually doing, and figure out exactly where the code goes offtrack.

PQ is my custom version of PRINTH, details to follow.

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, a better PRINTH

PRINTH itself can be a bit annoying to use, so I built a replacement 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}) just prints "[table]". not very helpful!
  • to print multiple things at once, you need to type printh("xy "..x.." "..y), which is cumbersome.
  • just kidding, that will crash if x is nil (which happens frequently while debugging) What you actually have to type is: printh("xy "..tostr(x).." "..tostr(y)).

These annoyances are fixed by PQ: pq("xy",x,y) is much easier to type and will nicely print each argument, even tables. Being easy to type is very important -- you'll add a lot of these statements temporarily 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


92 tokens:

 
-- pq-debugging v11, by  @pancelor
-- https://www.lexaloffle.com/bbs/?tid=42367
printh'---'

-- quote all args and print to host console
-- usage:
--   pq("handles nils", many_vars, {tables=1, work=22, too=333})
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 res=""
	for ix=1,select("#",...) do
		res..=_quote(select(ix,...),4).." "
	end
	return res
end

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

	local res="{"
	for k,v in next,tab do
		res..=tostr(k).."=".._quote(v,maxdepth-1)..","
	end
	return res.."}"
end

PQ library, minified version


90 tokens:

 
-- pq by pancelor: lexaloffle.com/bbs/?tid=42367
function pq(...)printh(qq(...))return...end
function qq(...)local r=""for i=1,select("#",...)do r..=_q(select(i,...),4).." "end return r end
function _q(t,d)if(type(t)~="table"or d<=0)return tostr(t)
local r="{"for k,v in next,t do r..=tostr(k).."=".._q(v,d-1)..","end return r.."}"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.

alternative: STOP

If you can'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)), or use this helper function:

 
function stopq(...)
    stop(qq(...))
    return ...
end

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
28

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

28
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!

This is my poor man's debugger which can be used to check values during runtime on screen. It is useful when the program is not crushing, but does not do what you want to do, and you don't know why.

 
function debug(infos, x, y)
 x, y = x or 0, y or 0
 local off = 1
 for info in all(infos) do
  for i = -1,1 do
  	for j = -1,1 do
  		print(info[1] .. ":" .. tostr(info[2]), x + i, y + j + off,0)
  	end
  end
  print(info[1] .. ":" .. tostr(info[2]), x, y + off,7)
  off += 8
 end
end

function _init()
	mp = 0
end

function _update()
	mp += 1
end

function _draw()
	cls(1)
	debug({
	{"hp", 19},
	{"mp", mp},
	{"lava"},
	{"lamp", true},
	{"moth","mother"}
	},32,32)
end


[Please log in to post a comment]