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