Trace

trace( [coroutine,] [message,] [skip] )

Returns a description of the current call stack as a string.

coroutine

Optionally get the stack trace for a coroutine. Defaults to the current one or the main thread.

message

Adds the given string to the top of the trace report. Defaults to blank.

skip

Number of levels of the stack to skip. Defaults to 1, to skip the trace() call's own level.

Undocumented feature

This article describes a feature that is not mentioned in the official Pico-8 documentation. The feature was known to work at the time the article was written, but it may be removed or changed in a future version.

The trace() function returns a description of the current call stack as a string. This string is long, and is only useful when printed to a terminal window with printh().

Note that, despite the expected Lua practice of only being able to leave out trailing arguments, the first argument, for the coroutine, can be left out while still supplying the message and skip arguments.

Note that the message argument is useful for inserting the exception string returned from a failed coroutine. See coresume() for details on how to do this.

As of PICO-8 v0.1.6, the string includes useless information referring to internal details. For example, if the cart uses the game loop, this stack trace includes the hidden _mainloop function.

Examples

Here's a simple program that counts up to 30, prints the stack trace to the host console, then calls stop().

v = 0

function next_tick()
  if v > 30 then
    printh(trace("final tick reached!"))
    stop()
  end
  return v + 1
end 

function _update()
  v = next_tick()
end

function _draw()
  cls()
  print(v, 0, 0, 7)
end

As of PICO-8 v0.1.12c, the host console shows the trace as follows:

final tick reached!
stack traceback:
	[string "-- pico-8 header..."]:7: in function 'next'
	[string "-- pico-8 header..."]:14: in function '_update'
	[string "-- pico-8 header..."]:31: in function '_mainloop'
	[string "-- pico-8 header..."]:38: in main chunk

See also

• Lua
• assert()
• coresume()
• stop()