Editing Content while Using Scripts
You might sometimes notice that a script "loses track" of a Segment you were using. You try to fire off a routine to play that Segment and you get silence or an older version of the Segment plays. This is most frequently caused by editing a Segment after setting up your script. In order to allow for script routine auditioning within DirectMusic Producer, the script is actually "running" even as you edit it. But when you edit a piece of music that the script was using, DirectMusic Producer has a tough choice — the script could update with each edit to the Segments (which might cause a significant slowdown to edits if the Segment and/or script were large) or the script can just accept that it might get out of sync, at which point the content creator can force a refresh. DirectMusic Producer opts for the latter. You can force the script to resynchronize with all of its source content by hitting the Refresh button above the list of routines. If that is not successful, you can save and reload your script by right-clicking on it, choosing Save, and then again right-clicking and choosing Revert to Saved.
Debugging Scripted Content
Let's take a quick break from scripting to look at how you can debug (find and correct errors in) scripts. As we discussed before, you know your script has some kind of syntax error when the routines disappear from the Routines list in the top-right frame of the Script Designer window. But where was that error? Rather than having to hunt through every line of code, DirectMusic Producer can report errors along with their locations via the Message Window. You can open it from the Add-Ins menu. This window reports syntax errors (errors that occur because the script was typed wrong), as well as run-time errors (errors that occur when the script tries to run a routine).
Let's set up one of each and see how the window responds.
SubExitRoom 'Notice - no space between 'Sub' and 'ExitRoom' RoomAmbience.Stop (AtBeat) End Sub
If the Message Window is open and we click outside of the Source box in the Script Designer (or click the Refresh button above the Routines frame), the Message Window will display this:
Figure 7-7: The Message Window displays errors in your script.
(The line might be different for you depending on whether you started a new script or worked from one of the previous examples.) You can see exactly what line that is by clicking back into your script Source window and looking at the status bar down at the bottom of the DirectMusic Producer window. (If the status bar is hidden, display it by selecting it in the View menu.)
Figure 7-8: The status bar displays the exact line and column number that your cursor is currently on.
For an example of a run-time error, let's use that same routine but try to play a Segment that we haven't added to either of the script's folders (for instance, a typo in the name of the Segment that we intended to play).
Sub ExitRoom 'Try to play a Segment the script doesn't know about SomeOtherSegment.Play (AtBeat) End Sub
Nothing happens when we click away from the Source window, as this is a perfectly legal script routine. But when we try to run it (by double-clicking it in the Routines frame), we get what is shown in Figure 7-9:
Figure 7-9: The Message Window displays an error regarding an unlocatable Segment.
This lets us know that the script didn't know where to find the Segment, so we should add it to the reference or embed the run-time folder.
The Message Window has one additional use; you can place statements in your routines that provide information similar to comment statements but let you know when a routine (or more particularly, a specific portion of a routine) has been run. These commands are known as trace statements. A programmer can actually "listen" for these trace statements in a game if you wanted to provide information (for instance, for karaoke, song title information, and so on).
Going back to our queued-up dialog, we could add a trace statement that lets us know the script routine completed.
Sub IntroduceCharacter 'We trigger this routine whenever our character meets 'other characters. Hello.play MyNameIs.play (AtFinish) Bob.play (AtFinish) Trace "Queued up Bob's introduction." End Sub
When we double-click the routine, we hear all three waves play in order and we also immediately see the following in the Message Window:
Figure 7-10: The routine works!