- Returns a description of the current call stack as a string.
- Optionally get the stack trace for a coroutine. Defaults to the current one or the main thread.
- Adds the given string to the top of the trace report. Defaults to blank.
- Number of levels of the stack to skip. Defaults to 1, to skip the trace() call's own level.
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
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
Here's a simple program that counts up to 30, prints the stack trace to the host console, then calls
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