Second Life Scripting: Using the Debug Channel to Find Script Errors

Debugging Messages in LSL Scripts

Script Alert Symbol floating over an Object in Second Life
Ever noticed this little icon in Second Life®, floating above an object?  Often it disappears after a short time.  This is the Script Alert Symbol.  It consists of a paper sheet, a yellow triangle, and an exclamation mark.  It means that a script inside the object has sent a debug or error message.  Clicking on the icon will cause the error message to be displayed in a window.
The Script Alert Symbol is displayed anytime a script causes an error message on the DEBUG_CHANNEL.  This can be a very useful tool when writing scripts.  Continue reading for how to turn on/off these  error messages, and how to make use of this feature for debugging your own scripts.

The Debug Channel

The debug channel is the channel that error messages intended for the script writer or creator are displayed on.  Normal users do not see these messages unless they have their viewer set to show them.  The value “DEBUG_CHANNEL” is a constant used in scripts that represents this specific chat channel.  (The channel number is 2147483647,  or  0x7FFFFFFF.)  This is a special channel reserved for error messages.  Standard practice is to use the constant “DEBUG_CHANNEL” in your script rather than the channel number.  This makes your script much more readable.  DEBUG_CHANNEL must be written in all upper case letters with the underscore character between the words as shown.  I’ll give you some script examples below.
Script writers can use the DEBUG_CHANNEL in their scripts to track the script progress or send low-key error messages.  This is useful when trying to debug a script.  Remember that most users do not have the script debugging set to display, so they will not see these error messages.  Error messages you want the user of an object to see should be sent to the normal chat channel 0 or to the object owner.

How to Turn On/Off Debug Messages

To turn on the display of debug messages in the Second Life Default Viewer, open Me > Preferences, select Advanced tab, and put a check mark in the box next to “Show script errors in: Nearby Chat / Separate window”.  The Script Alert Symbol is not shown if you have your viewer  set to not display script error messages.

How to Use Script Debugging Messages

When writing a script you can send messages to the DEBUG_CHANNEL for use in debugging problems with your scripts.  To create an error message you just sent a message to DEBUG_CHANNEL using the llSay function.
llSay(DEBUG_CHANNEL, "error message");
Here’s an example of an error/debugging routine.  A routine like this can be used to trace progress though a script.  So if a script isn’t doing what you want, you can insert debugging messages into it to try to trace the progress and find out where it is stalling, or if it is skipping over something.  Create a simple box prim and place this script in it. If you have “Show script errors” checked in your Preferences (as noted above) this script will display the Script Alert Symbol above the box and it will show debugging messages to you, and annoy everyone around you with error messages on the default chat channel until you delete it.

// Create a variable to turn debug messages on and off.
// This is an example of how to use debugging messages to trace the progress through a script.  This is very useful for finding where an error is occuring.

integer DEBUG_MODE = TRUE;  //Set to FALSE to turn off debug messages

// Create a function for processing debug messages
debugMessage(string message)
    if (DEBUG_MODE)
        llSay(DEBUG_CHANNEL, message); // shows the message on the debug channel


        debugMessage("The state_entry event just started."); // this is a debugging message
        llSetTimerEvent(10); // makes timer event run every 10 seconds

    touch_start(integer total_number)
        debugMessage("The touch_start event just started."); // this is a debugging message

        debugMessage("The timer was triggered."); // this is a debugging message
        llSay(0, "Opps, loop error in script.  This annoying message will keep repeating until you delete this object!");  // this is an error message for everyone to see