DukeScript

DukeScript is a textual file format used by Duke Nukem II to implement help/info screens, the main story cutscene, and all of the menus. The story sequences shown after defeating a boss don't use DukeScript, and no in-game functionality is using it either.

Structure of a DukeScript file

A DukeScript file contains a collection of named scripts. A named script is introduced by stating its name on a single line, followed by an empty line. Each script consists of a list of commands, with each command occupying a single line starting with //. The command //END completes each named script. Here is an example file:

ExampleScript

//FADEIN
//END

AnotherExampleScript

//FADEOUT
//DELAY 600
//LOADRAW MESSAGE.MNI
//END

The example file above declares two scripts, named ExampleScript and AnotherExampleScript, with the first one containing only one command (FADEIN), and the 2nd one containing 3 commands.

Commands and command execution

Commands consist of a command name identifying the command to run, and optionally one or more parameters. FADEIN and FADEOUT in the example above are commands without arguments. DELAY and LOADRAW are commands with one argument. The type and number of arguments depends on the command. Arguments are separated by a space.

Commands are usually executed in linear fashion from top to bottom, although there are some mechanisms for more complex execution sequences. But let's focus on regular commands first.

Many commands are displaying images or text on screen. With most commands, this will be drawn on top of what's already visible on screen, which makes it possible to build up an image out of smaller elements.

What's important to understand is how commands work with/affect the palette used to display graphics on screen. Duke Nukem II is running a 16-color VGA display mode, which means that the pixels in images don't contain color values, but indices into a palette of color values instead. The same image can appear differently depending on which palette is loaded.

Two types of graphics can be displayed using DukeScript: Full-screen images (LOADRAW command) come with a matching palette, and will thus always appear the same. Actor-based images (XYTEXT command) don't have a palette associated with them, so their appearance depends on the currently active palette. Full-screen images change the palette for all subsequent actor-based images as well. If a script doesn't use full-screen images, it can use the GETPAL command instead to load a specific palette.

With all of this in mind, let's have a look at some of the available commands.

General drawing commands

FADEOUT - does a fade-out of the whole screen. The screen will remain dark until a FADEIN command is issued. But other drawing commands still work while the screen is black, there won't be anything visible immediately but they still draw to the canvas. This makes it possible to compose an image out of several elements by issuing various drawing commands, and then making everything visible at once with a fade-in.

FADEIN - does a fade-in of the whole screen.

LOADRAW <filename> - loads full-screen image and palette from the given file, draws the image onto the screen (replacing anything previously visible), and sets the palette for any subsequent drawing commands.

GETPAL <filename> - loads a palette from the given file. Any subsequent actor-based image and text drawing commands will use this palette.

XYTEXT <x> <y> <text_or_image_spec> - displays text, or an actor-based image, at the position specified by x and y. The unit for positions is tiles, i.e. blocks of 8x8 pixels. Position 0,0 is at the top-left of the screen. By default, this draws the text given in the 3rd argument (rest of the line) at the specified position, but there are special "markup" bytes that make it possible to draw larger text or an image instead.

Large text is triggered by a character with a value >= 0xF0. Any text following this marker byte will be drawn with a larger font, and colorized according to the low nibble of the marker byte, which is treated as an index into the color palette. E.g. a marker byte of F5 will use the color index 5. The marker byte can occur at the beginning of the text (entire text is drawn large) or in the middle of the text (text preceding the marker byte is drawn normally, all text afterwards is drawn large). The position of the large text will be offset to the right by 2 tiles from the specified position.

Drawing images/sprites is triggered by starting the text with a character value of 0xEF. The remaining text is then interpreted as a sequence of 2 numbers. The first always has 3 digits and indicates the actor ID (index into ACTORINFO.MNI). The next 2 digits make up the second number, which indicates the animation frame to draw for the specified actor's sprite. There is no space between these two numbers.

Specialized drawing commands

PAK - Press Any Key - this is a shorthand for displaying actor nr. 146, which is an image of the text "Press any key to continue", at position 0,0. It is meant to be used with the full-screen background image MESSAGE.MNI, which has a little menu navigation legend down at the bottom of the image. The "Press Any Key" actor image is designed to seamlessly replace this navigation legend.

KEYS - shows the currently configured key names for movement, jumping and shooting, as 6 lines of text. Very specific to the options menu, where it's used. The position of the text cannot be specified.

GETNAMES <selected_index> - shows the names of all saved games as 8 lines of big text. The line corresponding to the given selected index will be drawn in a brighter color. The positions of the lines are hardcoded.

BABBLEON <duration>

BABBLEOFF