Creating a Script

The first step to building our script is to create a new one in DirectMusic Producer. As with other file types, you can create a new script via the File menu by selecting New… and then choosing Script in the dialog that opens.

Figure 7-1: An empty script as displayed in the project tree.

The first thing we notice is that a script looks an awful lot like a DirectMusic container file, with separate embed and reference folders. In fact, script files are a specialized kind of container file. A script is able to act on any other file that it knows about, as well as manipulate parameters for the global DirectMusic engine (tempo, groove level, and so on). With files placed in the Embed Runtime folder, the content will actually be saved within the Script file when it is run-time saved, just as they were in a container's Embed Runtime folder. Meanwhile, any files placed in the Reference Runtime folder are files that the composer intends to save out and deliver for application integration separately but that the script is still aware of and can use. Files can be placed in the two folders by dragging them onto the folders, or right-clicking on one and choosing Add/Remove Files….

Figure 7-2: The Add/Remove Files dialog provides a quick way to add many files to a script's container at once.

We discuss more implications of embedding versus referencing later in the chapter. For now, let's use the Reference Runtime folder, remembering that when it comes time to integrate our content into the application, we need to separately deliver all of the files that the script uses.

One of the nice things about DirectX Audio Scripting is that waves and Segments can be mixed together, just as they can by a programmer. Of course, wave files don't give you much in the way of variability nor do you get any tempo or measure information without building a Segment first. But for some scenarios (for instance, non-varying dialog), basic wave files are quite useful in scripts, as we can see in our first set of examples. We're going to reference a few wave files, named for the dialog they contain — "Hello," "My Name Is," and "Bob" (if you've authored these wave files separately, don't forget to insert them into the project via the File menu's Insert Files into Project option). We also have some background music handy in a pair of Segments called RoomAmbience and ActionMusic.

Figure 7-3: The setup for our upcoming examples. Our two Segments happen to refer to their own DLS Collections, but they could also (or instead) use General MIDI instruments.

Note first off that the wave My Name Is is referenced by the script as MyNameIs — without the spaces. The name a script uses to reference an object is not allowed to contain any spaces, so these were removed. Other restrictions to be aware of are that a script object cannot begin with a number, and you can't have two waves/Segments with the same name (if you do, DirectMusic Producer will automatically add a number to the end of the name of the second one inserted).

Now let's take a look at the Script Designer window. If it isn't already open, double-click on the script in the project tree.

Figure 7-4: An empty script.

There are three frames in the Script Designer. The Source frame is where we type in the actual routines for this script. When we want to try out these routines, we double-click them over in the Routines frame. This simulates the exact function that the programmer will perform when they "trigger" a script routine. The Variables frame will show any variables that our script uses along with their current values. Again, we can click on these to update them just as the programmer would in the actual application.