Trial includes a variety of tools to aid in the inevitable debugging process.


Trial relies on the Verbose logger framework to print various status messages to its log. You can, of course, make use of all of Verbose's features yourself as well. You should add a local nickname for org.shirakumo.verbose (as v) to your package definitions for that.

When deployed, Trial will also automatically capture Verbose's log to a logfile that can be used for debugging crashes and other issues.

Trial also offers a number of useful shorthand macros:


You can add a watchpoint for the result of a function with the observe function, or of an expression with the observe! macro. To remove the watchpoint again, you can use stop-observing.

In order for the watches to show up, you must have a display-controller in your scene. Typically you'll want to do this by using (enter (make-instance 'display-controller) scene) in your setup-scene.

You can also use an fps-counter instance to only observe the frame count. The fps-counter in particular is written to be as low latency as possible, and should have almost zero overhead.


In order to debug visual information, you can use the following functions:

All of these are copying, meaning they won't update if their arguments are modified and they'll stick around until cleared away. All of the functions also accept the following arguments:

Note that all drawing calls are synchronised to the render thread. Meaning that if the call occurs outside of the render thread, it is scheduled asynchronously to run on it.


Special mention should be made of the Renderdoc tool. While Trial allows redefinition of shaders at runtime, sometimes being able to capture the entire pipeline state and inspect it can be invaluable to figure out weird graphical issues. Renderdoc is ideal for this situation and works fine with Trial, as long as the underlying lisp process is called via Renderdoc.

To do so, create a small script like so:

(ql:quickload :swank)
(ql:quickload :my-project)

Then you can configure your implementation as a launch option in Rendedoc:

Launching it like that should allow you to connect via Slime on port 4005, and capture snapshots of the running process via Renderdoc.