Using Hidden Debugging Tools

October 18, 2000
by Gary Rosenzweig

Think that the Lingo debugger takes care of all your debugging needs? Think again. The hardest bugs to figure out are the ones that don't show themselves when running your movie in Director, but only appear in Projectors or Shockwave. How does this happen? Simple. Shockwave and Projectors are a different environment than Director. Some things do not work, or do not work quite as well, once you leave the comfort of Director. Other things change, such as the location of your movie or linked files.

Here are some common reasons why a movie that works in Director may give you an error in Shockwave:

Streaming is turned on, and the cast members that Lingo expects to be present are not present as streaming is still taking place
An Xtra is missing, or is incompatible with Shockwave
The memory make-up of Shockwave is different than Director - I have seen cases where the new cast member command fails in Shockwave, but not in Director
An external cast library or other file is not where Director expects it to be
You are using new Director 8 sound Lingo, which is not compatible with Windows NT Shockwave (strange, but true!)

Here are some reasons why a movie that works in Director may give you and error as a Projector on a CD-ROM:

Linked files placed down in folders do not have the same relative path from the Projector as they did from Director
An Xtra is missing
The CD-ROM is a session CD (allowing you to write multiple times to the same CD until it is full), which for some reason creates problems
The Mac memory size of the Projector is not set as high as the memory size of Director

These are just a few of the possibilities, all of which can cause Lingo script errors. This doesn't seem to make sense in some cases, but it is true. In these odd cases, Shockwave or a Projector should actually be giving a more useful error, like "Out of Memory" or "Your NT Sound Setup is Incompatible with Shockwave" rather than "Script Error." To debug these sorts of problems, which usually have workarounds, you need to place debugging statements into your code. A simple one is to place an alert message, which will work in Shockwave and Projectors to tell you something about how the program is progressing. Here is an example:

alert("Debug 17:" && gMyGlobal && myLocal)

I use things like "Debug 17" so that when I have multiple alerts, I know exactly which one I am looking at. Another thing I do is to place several alerts around a section of code to be able to track down which one is causing the problem. Something like this:

add list, 17
alert("A")

if getProp(otherlist,#a) = 7 then
  alert("B")
  go to frame 7
  alert("C")
end if

alert("D")
r = cos(x)*78/q

alert("E")

Now, when I run the program, if I see alerts "A" and "D" and then get a script error, I know that the if statement was FALSE, and that the error must be on the "r =" line. When placing alerts like this, it is sometimes possible to put too many, especially if there is a loop involved. For instance, if you loop 1000 times and perform a calculation each time, you don't want to have 1000 alerts appear. Instead, you can have the alerts appear every so often. For example:

repeat with i = 1 to 1000

if (i mod 50) = 1 then alert string(i)
sendSprite(list[i],#myHandler)

end repeat

This handler will throw up an alert every 50 iterations. Then, if you see that the error occurs right after "201" appears, you know the problem is between 201 and 251. Then, you can narrow it down like this:

repeat with i = 1 to 1000

if i > 200 then alert string(i)
sendSprite(list[i],#myHandler)

end repeat

You'll eventually have the exact item that causes the problem. Another conditional debugging technique I use is the shift key. I would do something like this:

if the shiftDown then alert("Debug 1" & gMyGlobal)

This way, the alert is never seen by anyone except me and someone that accidentally has the shift key depressed. It's not a good idea for a final project, but it's good for beta tests or showing off something to a client. I hope that this gives you some good ideas about how to debug past the debugger. If you are really into this stuff, you can also try to learn about the alertHook, which offers some useful techniques. However, as far as I am concerned, the most powerful debugging tool remains a simple alert statement, properly placed and hidden.

Gary Rosenzweig's two most recent books are: "Special Edition Using Director 8" -- The most comprehensive guide to Director ever, including tons of examples and demo movies. It's suitable for novices and experts alike. "Advanced Lingo for Games" -- How to make games with Director 7 and 8. This book comes complete with full source code for more than 20 complete games. More information about these books can be found at http://clevermedia.com/resources/bookstore/. They can be purchased there, or in your local bookstore.

Gary Rosenzweig is the Chief Engineer, founder, and owner of CleverMedia, a game and multimedia development company in Denver, Colorado. He is the author of ten books on Macromedia Director and Flash, including his latest, Special Edition Using Director MX.