Script Command Details

Scripts can affect a disc’s playback in one of two ways:

Most scripts use several commands to perform these functions. Often, one script may use values placed in a GPRM by a different script that ran earlier.

Each of the ten commands has unique settings and uses. Some provide memory read and write functions, some control jumping to elements within the title, and others control how the script executes. These commands can be accessed at the top of the Script Command Inspector.

In addition to the command configurations, each can also use a compare operation that provides a conditional execution function.

Compare Function

You can use the compare function to determine whether or not a command executes (also known as a conditional instruction execution). For example, you might set a jump command to go to a track, but use the compare function to make sure the DVD player supports its aspect ratio. If the compare function is not satisfied, the command is skipped and the script moves down to the next command.

A compare function compares a specified element, which you select, with a value in a specified GPRM. You choose how to compare the two elements from a list of operations (equal to, greater than, and so on).

Figure. Compare section of the Script Command Inspector, showing the various controls.
To configure a compare
  1. In the Script Command Inspector, select the Compare Command checkbox to activate the compare settings.

  2. Choose the GPRM location to compare to the selected element from the “Execute if” pop-up menu.

  3. Choose the compare operation type from the “is” pop-up menu.

  4. Choose the type of elements to compare from the “to” pop-up menu.

  5. Choose the actual element to compare to the GPRM from the “with value” pop-up menu.

Element Types to Compare

You can choose from five different elements to be compared to the selected GPRM.

Figure. Compare section of the Script Command Inspector, showing the to pop-up menu.
  • GPRM: Allows you to select any of the available GPRMs to compare.
  • SPRM: Allows you to select any of the 24 SPRMs to compare. See System Parameter Register Memories Details for a list of SPRMs.
  • Immediate: Allows you to enter a decimal value, whose range depends on the size of the selected GPRM register, to compare.
  • Jump Target: Allows you to select from all available project elements (menus, tracks, stories, slideshows, and scripts) to compare.
  • Special: Allows you to choose from Current Item, Last Item, and Last Track to compare.
    • Current Item: This is this script, unless this is a pre-script. If this is a pre-script, the Current Item is the project element (menu, track, slideshow, or story) the script is assigned to.
    • Last Item: This is the project element that started this script running.
    • Last Track: This is the last track that was played, even if this script was started by a button on a menu.

Note: Jump Target and Special require the selected GPRM to be a 16-bit GPRM register. If you choose a partitioned GPRM with the “Execute if” pop-up menu before choosing the element type, Jump Target and Special will not be available. If you choose Jump Target or Special as the element type before choosing the “Execute if” GPRM, partitioned GPRMs will not be available.

GPRMs To Be Compared To

You can select one of the GPRMs to be compared to the selected element. For the values in a GPRM to be meaningful, you must first load something into it with a previous command in this script or from a different script run earlier. This is often done using the set command, but there are several other ways to load a value into a GPRM.

Compare Operations

There are seven compare operations that you can use to compare the selected element to the selected GPRM.

Figure. Compare section of the Script Command Inspector, showing the compare operation pop-up menu.
  • = (equal): Executes the command if the two values are the same.
  • != (not equal): Executes the command if the two values are not the same.
  • > = (greater or equal): Executes the command if the selected GPRM is larger or the same as the selected element.
  • > (greater): Executes the command if the selected GPRM is larger than the selected element.
  • <= (smaller or equal): Executes the command if the selected GPRM is smaller or the same as the selected element.
  • < (smaller): Executes the command if the selected GPRM is smaller than the selected element.
  • & (and): Performs a bit-wise “and” operation between the two values and executes the command if the bits set to 1 in the selected GPRM are also set to 1 in the selected element. See Using Bit-Wise Operations for information on bit-wise operations.

Note: You need to have a basic understanding of working with binary numbers to be able to use these operations.

Nop Command

The Nop (no operation) command provides a placeholder function. Anytime you add or insert a new step into a script, it is set to Nop. If a script encounters a Nop command while running, it immediately skips to the next command. If the Nop command is the last command, the script stops running and the title stops playing.

Note: When a script is run as a pre-script, it reacts differently to having a Nop as the last command line. With a pre-script, if the last command is a Nop, it is treated as if it were an exit pre-script command, and the element the pre-script is assigned to displays as normal.

Jump Command

Jump commands are usually the last step executed in a script, because they result in another element (menu, track, or script) starting to play.

Note: Being the last step executed is not the same as being the last step in the script. A script might have multiple jump commands in it, with other commands determining which jump to execute.

Figure. Script Command Inspector for configuring a jump command.
To configure a jump command
  1. In the Script Command Inspector, choose Jump from the Command pop-up menu.

  2. Choose the project element to jump to from the Jump To pop-up menu.

Figure. Script Command Inspector for configuring a jump command, showing the project element pop-up menu.

GPRM-Based Checkbox

A jump normally goes to a specific part of an element; for example, to button 3 on menu 2. Jumps also have the ability to use a value from a GPRM to determine which button or marker they should go to. This is useful if, instead of jumping to a set location, you want to jump to a place that is flexible, based on a value that a previous script writes to a GPRM.

To jump to a GPRM-based location
  1. In the Script Command Inspector, select the GPRM Based checkbox to enable the GPRM selection pop-up menu.

  2. Choose the element to jump to from the Jump To pop-up menu. Specific buttons and markers will be unavailable—you can only choose the basic elements (a menu, track, story, and so on).

  3. Choose the GPRM to use from the GPRM pop-up menu.

When jumping to menu buttons, you can load the GPRM with the actual button number (1 through 36).

When jumping to markers, you must enter the marker number (1 through 99). Any values you enter above 99 result in the first marker being selected.

Start At Loop Point Checkbox

You can add a loop point to your motion menu that defines when the highlights appear and where the menu jumps back to when it reaches the end. A jump to a motion menu normally goes to its start point and begins playing from there. There are times, however, when you might want the jump to go to the loop point instead, ensuring the highlights appear immediately and avoiding forcing the viewer to sit through the first part of the menu.

Selecting the Start At Loop Point checkbox configures the jump to play the menu from the loop point. See About the Motion Settings for more information. See Jumping to a Menu’s Loop Point for an example script using this feature.

Set GPRM Command

The set GPRM command is used to determine a value that is then placed in a GPRM location. There are four elements to set:

  • The operation type: There are 11 operations you can choose from, ranging from a simple move to a “bit-wise exclusive or.” See Operation Types for details on using these operations.
  • The source type: You choose from five possible source element types that can be used as the source. See Source Element Types for details on the element types.
  • The source value: Once you choose the source element type, you can then choose the actual element. For example, if you choose an SPRM element type, you use this setting to choose the specific SPRM to use as the source.
  • The GPRM target: You choose a GPRM location where the value gets written. Depending on the operation you choose, this GPRM location may also be the second value in a math operation. For example, if you choose a subtraction operation, the source value is subtracted from the current target value and the result is written to the target location.
    Figure. Script Command Inspector for configuring a Set GPRM command.
To configure a set command
  1. In the Script Command Inspector, choose the operation from the Operation pop-up menu.

  2. Choose the source element type from the Source Type pop-up menu.

  3. Choose the actual source element from the Source Value pop-up menu. The list of elements is determined by the source element type selection set in step 2.

  4. Choose the GPRM target from the Target pop-up menu.

Operation Types

There are 11 operations you can choose from to control how the source and target values are handled. There are limitations you need to keep in mind when using these operations:

  • Registers have no overflow or underflow flags.

  • If the script tries to store a value smaller than 0 or larger than 65535, no error message is given; instead, the value “wraps around.” For example, if you subtract 7 from 3, you would normally get –4. But if you do this in a script, 65532 is stored. If you add 6 to 65534 in a script, 4 is stored instead of 65540.

    Figure. Script Command Inspector for configuring a Set GPRM command, showing the Operation pop-up menu.

The operation types are:

  • mov: Moves the source value to the target location, overwriting the existing value in the target.
  • swp: Swaps the source value with the target value. The source value is written to the target location, and the target value is written to the source location. This is the only operation that writes to the source location.
  • add: Adds the source and target values together and writes the result in the target location.
  • sub: Subtracts the source value from the target value and writes the result in the target location.
  • mul: Multiplies the source value by the target value and writes the result in the target location.
  • div: Divides the target value by the source value and writes the result in the target location.
  • mod: Divides the target value by the source value and writes the remainder (modulo) in the target location.
  • ran: Generates a random value between 1 and the source value and writes the result in the target location.
  • and: Performs a “bit-wise and” operation between the 16 individual bits of the source and the target values, and writes the result in the target location. The bits that are set (value of 1) in both values are left set. Bits that are not set in one or the other value are reset (value 0).
  • or: Performs a “bit-wise or” operation between the 16 individual bits of the source and the target values, and writes the result in the target location. The bits that are set (value of 1) in either value are left set. Bits that are not set in both of the values are reset (value 0).
  • xor: Performs a “bit-wise exclusive or” operation between the 16 individual bits of the source and the target values, and writes the result in the target location. The bits that are set (value of 1) in one or the other value (but not both) are left set. Bits that are or are not set in both of the values are reset (value 0).

Source Element Types

You choose from five different elements to be used as the source type.

Figure. Script Command Inspector for configuring a Set GPRM command, showing the Source Type pop-up menu.
  • GPRM: Allows you to select any of the available GPRMs as the source.
  • SPRM: Allows you to select any of the 24 SPRMs as the source. See System Parameter Register Memories Details for a list of SPRMs.
  • Immediate: Allows you to enter a decimal value, whose range depends on the size of the selected GPRM register, as the source.
  • Jump Target: Allows you to select from all available project elements (menus, tracks, stories, slideshows, and scripts) as the source.
  • Special: Allows you to choose from Current Item, Last Item, and Last Track as the source.
    • Current Item: This is this script, unless this is a pre-script. If this is a pre-script, the Current Item is the project element (menu, track, slideshow, or story) the script is assigned to.
    • Last Item: This is the project element that started this script running.
    • Last Track: This is the last track that was played, even if this script was started by a button on a menu.

Note: Jump Target and Special require the target to be a 16-bit GPRM register.

Goto Command

The goto command provides a way to jump to a specific line in a script. This is usually used in conjunction with a compare function, with the result determining whether the goto command executes, or whether the script moves on to the next line.

Goto is useful when you build multiple jump commands into your script, because it allows you to choose which jump command to execute by forcing the script to its line.

Figure. Script Command Inspector for configuring a Goto command.

The only entry (other than the compare settings) is the Line Number value, which is a number from 1 to 124.

Set System Stream Command

The set system stream command provides an easy way to set the audio, subtitle, and video angle streams. You can choose to enable one, two, or all of the three streams. In the case of the subtitle stream, you also choose whether or not it appears.

You choose between two modes to set the stream values:

  • Immediate Value: Choose the streams directly using their pop-up menus. (Pop-up menu values that say “not set” indicate that no assets are currently assigned to that stream.)
    Figure. Script Command Inspector for configuring a Set System Stream command with Immediate Value selected.
  • GPRM Based: Choose a GPRM register from each stream’s pop-up menu.
    Figure. Script Command Inspector for configuring a Set System Stream command with GRPM Based selected.

    Note: You can only choose 16-bit GPRM registers.

To configure the set system stream command
  1. In the Script Command Inspector, select either the Immediate Value or GPRM Based modes for stream selection by clicking the appropriate button.

  2. Select the streams you want to control by clicking their checkboxes.

  3. For each stream you select, use the pop-up menu to choose the stream (Immediate mode) or GPRM register (GPRM mode).

  4. If you select the subtitle stream, select the View checkbox to force the subtitle to appear.

Resume Command

The resume command works like the Resume button on a DVD player’s remote control—when executed as a step in a script, the disc starts playing from where it last left off.

Note: When the resume command is executed from a pre-script, the result may not match your expectations. Instead of playing the last menu or track that the viewer saw, the track or menu that had the pre-script assigned to it plays instead (which, even though the viewer had not seen it, was the last element “viewed”).

GPRM Mode Command

Each 16-bit GPRM register can be set to function as a memory location or as an incrementing counter. By default, all GPRM registers, including those partitioned to smaller registers than 16-bits, are set to be memory registers.

Figure. Script Command Inspector for configuring a GPRM Mode command.
  • Counter mode: The value loaded into the register increments once per second. This mode can be a useful way to determine how far into the track the viewer has played.
  • Register mode: A value written to a register remains there until a new value is written or the disc is ejected.
To configure the GPRM mode command
  1. In the Script Command Inspector, click either the Counter or Register Mode button to set the selected GPRM’s mode.

  2. Choose the GPRM register to configure with the Set To pop-up menu.

    Only 16-bit GPRM registers appear in the pop-up menu. See Setting a GPRM’s Mode for more information.

Exit Command

The exit command provides a way to stop the title from playing back. If, while a script is running, an exit command is encountered, the script stops running and you are prevented from playing the title. For example, you may want to do this in response to the player’s region setting.

Exit Pre-Script Command

A pre-script executes as soon as an element is selected. Depending on the purpose of the pre-script, you will often want to have that element display as normal once the pre-script is finished running. The exit pre-script command provides a way to end a pre-script and display the element as normal.

Note: When a script is run as a pre-script, it reacts differently to having a Nop as the last command line. With a regular script, if the last command line is a Nop and the script encounters it while running, the script stops and the title will no longer play. With a pre-script, if the last command is a Nop, it is treated as if it were an exit pre-script command, and the element the pre-script is assigned to displays as normal.

Jump Indirect Command

With the normal jump command, you must specify an element (menu, track, story, slideshow, or script) to jump to, even when using the GPRM Based Button setting.

The jump indirect command provides a way to jump to an element that is entirely determined by a value stored in a GPRM. For example, you could have a script that uses the set command write the current menu’s value to a GPRM, and then later on have a second script use the jump indirect command to jump to that same menu by reading that GPRM.

Note: You can only select from the 16-bit GPRM registers.

Figure. Script Command Inspector for configuring a Jump Indirect command.