Scummbler v2

Scummbler is a program that compiles text scripts into a binary format suitable for use in Lucasarts games (which uses a bytecode scripting language called Script Creation Utility for Maniac Mansion, or SCUMM). Currently, it only supports creating scripts for V5 of the SCUMM scripting engine.

Scummbler has been designed to parse text files from ScummVM's descumm tool. This allows you to easily convert back and forth between bytecode and human-readable code.

Because Scummbly is quite low level (it is merely a human readable version of the SCUMM bytecode), I don’t think it’s appropriate for creating any new games; instead, it is more suited for modifying the scripts of existing games to extend their functionality. If you’re looking to make your own SCUMM-based adventure game, you should investigate ScummC and ScummGen.

Before you dive into Scummbly, it might be wise to check out the technical reference for the SCUMM engine on the ScummVM wiki. Also, Alban Bedel, the author of ScummC, has some great info on his website, although it focuses on SCUMM V6.

For the purposes of this document, I will refer to the textual script as Scummbly, and the bytecode script as SCUMM. Any oddities in the textual script that are artifacts of descumm’s output, I will refer to as descumm.

Run Scummbler from the command line, passing in one or more filenames of the scripts you want to parse.

The resulting file will be named as the input file, with either .out.LSCR or .out.SCRP appended to the filename (depending on whether it’s a local or global script). For example, campfire_intro.txt becomes campfire_intro.txt.out.LSCR.

This section describes the base elements that make up Scummbly.

Constants can be either bytes or words in size; this will depend on the instruction you are using.

You can also define aliases for variables or constants (see Compiler Directives).

Variables are specified by their type and an index. They can be global word variables, local script variables, or bit variables.

There is a limit to the number of each variable type that can be used; this is defined within the game’s index file (*.000).

Variables can have indirect pointers:

The first example has an offset of 8, the second example has an offset of whatever the contents of Var[28] are. If Var[28] contains the value 8, it will reference the same variable that Var[26 + 8] would (i.e. Var[34]).

There are a number of global variables that are reserved for use by the SPUTM engine; these can be found in scummbler_vars.py, and are also listed in Appendix A. You can substitute any of these names for the appropraite variable.

Note that variable names are case sensitive; unnamed variables must begin with a capital, and named variables must be in uppercase.

You can also define aliases for variables or constants (see Compiler Directives).

Generally, when a function requires a large number of values, it will take them in a list. This list is a series of values (constants or variables, sometimes both and sometimes only one type depending on the instruction), surrounded by square brackets.

String literals are surrounded by quotes.

Strings may contain the the karat character ^. This can have two meanings: - if followed by a series of digits, the digits are interpreted as a number and treated as an escape character/raw byte. - otherwise, the SPUTM engine uses the ^ character to represent & display three ellipses ... .

Each line in Scummbly is considered its own instruction, with the exception of if blocks (discussed later). Instructions can be categorised into four basic types:

1) Inline operations - basic mathematical operations that act on a single variable

2) Expression mode - complex, chained mathematical operations that can also call other functions

3) Boolean expressions - functions used in if statements and unless instructions.

4) Functions - performs complex actions

Arguments for functions are seperated by commas.

There are also complex functions that can have sub-instructions. Sometimes these sub-instructions are part of the grammar for the function, other times they stand as a seperate function.

Scummbly uses C-style comments.

Labels are used to define targets for any jumping instructions (unless or goto instructions). They appear at the start of a line and are contained within square brackets.

Instead of labels as such, descumm outputs the hex offset of each instruction in the script. Scummbler will interpret these offsets as labels.

You cannot have two labels with the same name.

To maintain compatibility with descumm, Scummbly will successfully parse but ignore a few extra things. These are:

*Note that the opcode is required for the startScript function, see its entry for more information.

Scummbly supports if/else branches, and do/while, while and C-style for loops.

Behind the scenes, these blocks are just nice looking unless/goto statements; you can have an empty block which acts as a jump when a certain condition is met. You can get some funny output from descumm, when it thinks a conditional jump is an if blog. Also, scripts originally written in SCUMM have dummy jumps at the end of every block in an else if construct; descumm comments them out, so if you take a script from SCUMM → descumm → Scummbler, you will not get an output script that is identical to the original SCUMM script.

In for loops, the initialiser and counting expressions are optional, and can be any Inline Operation. The loop test expression can be any Boolean Expression.

The last instruction in a script must always be the stopObjectCode instruction. You can optionally include the text END (this is to maintain compatibility with descumm).

These directive must appear at the start of the script, before any instructions.

You can specify a script number; if you do, the output file will be a considered a local script, and output with the appropriate header information.

You can define aliases for constants and variables using the #define keyword. The names can be composed of any alphanumeric character and underscores. To use them within the script, you need to prepend the $ character.

Note that type information is lost when using #define, so you can easily end up using a word in an instruction that only accepts a variable!

All inline operations act on a target variable and an argument (either a variable or a word constant).

Expression mode is a way to chain mutliple operations together. You can perform any mathematical operations (excluding logical AND, logical OR, increment and decrement), and can also call any functions that return a value. Each operation and pair of values must be surrounded by parentheses.

When including a function, it must be surrounded by angular brackets, and must move the returning value into VAR_RESULT.

These are specific instructions that set a flag in the SPUTM engine, indicating whether the tested condition is true or false. Most boolean operations must test a variable (you can’t have statements like if (1)...).

You can test for zero equality or inequality by just having the variable name.

These are your standard mathematical comparisons.

Compares the class of the given object number (var or word) against a list of class numbers, returns true if the object matches all of the given classes.

descumm forgets to add a closing parenthesis to this instruction.

Branches if the given actor (var or byte) is in the given box (var or byte).

Sets the camera to follow the given actor.

Returns the actor located at the given co-ordinates.

A dummy case, does nothing (in ScummVM).

Sets the actor’s costume.

Sets the actor’s walking speed for x and y.

Associates a sound with the actor (footsteps?)

Sets the current frame of the walking animation.

Sets the start and stop frames of the talking animation.

Sets the current frame of the standing animation.

Unknown; seems to be unused (at least in ScummVM).

Initializes actor.

Sets the actor’s elevation to the given value.

Initializes the actor’s animation frames.

Sets the colour at the given index to a new value (another entry in the colour lookup table/CLUT). Index must be between 0 and 31 (the number of colours in a costume).

Sets the actor’s talk colour.

Sets the actor’s name to the given string.

Sets the current frame of the initial animation.

Sets the actor’s width.

Sets the actor’s X and Y scales.

Turns off all Z-clipping for the actor.

Forces the actor’s Z-clipping for the given Z-plane.

Ignores boxes, turns off Z-clipping, and puts actor somewhere if the actor is in the current room?

Follows boxes, turns off Z-clipping, and puts actor somewhere if the actor is in the current room?

Sets the animation speed.

Sets the shadow mode.

Starts the given animation for the given actor.

Deschedules the currently running thread. Execution continues at the next instruction when the thread’s next timeslot comes around.

Replaces the currently running script with another one. The current script is terminated immediately and the new script (determined by the given script ID), is executed in the same thread. The new script has its local variables initialised to the list args. Uninitialised variables have undefined values.

Turns the cursor on.

Turns the cursor off.

Enables user input.

Disables user input.

Increments the cursor’s state?

Decrements the cursor’s state?

Increments "user input" counter (when greater than 0, user input is enabled).

Decrements "user input" counter (when 0 or less, user input is disabled).

Changes the cursor image to a new one, based on image in a character set. Only used in Loom.

Changes the hotspot of a cursor. Only used in Loom.

Note that it starts with a lowercase letter.

Changes the current cursor. Must be between 0 and 3 inclusive.

Initializes the given character set.

Initializes the character set data & colours to the given arguments? Must have 16 arguments?

??? If required, runs a script passing the given arguments. Cutscene data given by the first argument in the list?

Passes the parameter to the interpreter’s debugger. What this does is entirely platform-specific (and may do nothing).

descumm outputs a question mark in the function name, but this is optional in Scummbly.

Suspends the current thread for the appropriate number of 1/60ths of a second. The Delay argument is a 24-bit constant.

var is dereferenced and the current thread suspended for that number of 1/60ths of a second.

Performs a verb sentence action, e.g. "Use monkey on hydrant". If verb is STOP, the current sentence script is stopped, status cleared etc.

Draws a solid box on the backbuffer from (left, top) to (right, bottom) in the given colour.

Adds the object to the drawing queue. descumm adds an extra closing parenthesis.

Moves the given object to the given co-ordinates, and adds it to the drawing queue.

Sets the state of the object, adds it to the drawing queue.

V5 specific - The KIXX XL release of Monkey Island 2 (Amiga disk) used this opcode as a dummy, in order to remove copy protection and keep level selection.

Ends the cutscene, performing cleanup if necessary.

descumm outputs this instructions without a trailing semi-colon.

Tells actor to face object (presumably based on X/Y co-ordinates).

Searches for all objects owned by owner (an actor or object), and returns the one at the given index (offset).

Returns the first "touchable" local object at the given co-ordinates. Will not match on the bottom or right-hand edges of an object.

descumm checks for words here while ScummVM looks for bytes; Scummbler looks for bytes.

Freezes all scripts (by setting the high bit on each script’s status). If flag is >= $80, all freeze resistent scripts will also be frozen. If flag is 0, all scripts are unfrozen. Freezing effects are cumulative - i.e. if script A is frozen twice, and unfrozen once, it will still be frozen until it is unfrozen a second time.

Returns the actor’s current costume.

Returns the actor’s current elevation.

Returns the current direction the actor is facing.

Returns the actor’s moving status (0 or 1).

Returns the room the actor currently occupies.

Returns the actor’s current scale.

Returns the actor’s walkbox.

Returns the actor’s width.

Returns the actor’s current X co-ordinate.

Returns the actor’s current Y co-ordinate.

Returns the actor’s animation counter.

Returns the object closest to the actor. Items that are more than 255 units (pixels in SCUMM V5) away from the actor will not be detected.

Returns the distance between two actors/objects (objA and objB).

Returns the number of items in an actor’s inventory.

Returns the owner of an object.

Returns the state of the object.

Returns a new random number based on the given seed.

Gets the length of the string pointed to by strptr (either a variable or direct byte), stores the returned value in result.

Returns the entry point for the response code/script for when the given verb is applied to the given object. i.e. gets the start of the script to run for the specific user interaction.

Returns 1 if the given script is running, 0 if it’s not.

Returns 1 if sound is running, returns 0 if sound is not running or if the given sound is 0.

If arg3 is 0, the current lights variable is set to arg1. If arg3 is 1, the size of the flashlight light is determined by arg1 and arg2, for width and height in stripes (which are equivalent to 8 pixels each).

Loads the given room into memory.

Places the Ego actor in room at object’s position. If x is not -1, Ego will start moving towards the given x and y co-ordinates. If object is not in the given room an error will occur.

Sets the box’s flags to the given value.

Sets the box’s scale.

Sets the box’s scale to ((val - 1) OR $8000).

Initializes the matrix of boxes, by determining the distances and shortest paths between boxes.

beginOverride must be immediately followed by a goto instruction.

Overrides are used by cutscenes; after a beginOverride instruction, if a cutscene is skipped (e.g. if the user presses the ESC key), the script will jump to the instruction pointed to by the goto that follows beginOverride (not necessarily the location of endOverride).

descumm omits the parentheses for both instructions.

Sets text properties for the given actor and displays dialogue.

Sets text properties for the player character (VAR_EGO) and displays dialogue.

Sets the position of the text that follows.

Sets the colour of the text.

Clips the text’s right-hand side (possibly for wrapping).

Erases characters (not used in ScummVM).

Centres the text.

Left-aligns the text.

Overhead-aligns the text.

Prints the text string that follows. text can contain escape characters (escaped with the ^ character).

Resources are bytes. You can pass the special text IG instead of any values in the list.

Puts the actor at the given co-ordinates.

Puts the actor at the given object’s position. If the object can not be found, a default position is returned (the centre of the screen in ScummVM).

Puts the actor in the given room.

Loads the given resource.

Obliterates the resource from memory.

Locks the resource.

Unlocks the resource.

Clears the heap.

Loads the given character set into memory.

Obliterates the given character set from memory.

Loads an object from the given room resource.

Clamps the given arguments so scrolling does not extend past the width of the room or screen.

Initialises a screen.

descumm outputs an extra closing parenthesis for RoomIntensity, SetScreen, SetPalColor and possibly others.

Starts the room shaking.

Ends the room shaking.

Lightens/darkens the room’s palette.

descumm outputs an extra closing parenthesis for RoomIntensity, SetScreen, SetPalColor and possibly others.

Saves temporary state of the room/game (possibly autosave).

If effect is 0, fades in the room. Otherwise, fades out with the given effect (taken from the high byte of effect).

Starts colour cycling with given delay between changes. index is between 0 and 16

Adjusts the room’s palette.

descumm outputs an extra closing parenthesis for RoomIntensity, SetScreen, SetPalColor and possibly others.

Sets the room’s y scales (given slot may be 1 greater than actual slot).

Unused is what descumm calls SetRoomScale. They are the same function.

Lightens/darkens the room’s palette, with different scales for red, green and blue.

Lightens/darkens the shadow palette, with different scales for red, green, and blue.

Saves a string resource to the given file?

Loads a string resource from a given file?

Manipulates palettes, strings?

descumm outputs some functions with question marks in the name; these are optional.

For all verbs between start and end, sets the "saveid" to mode.

For all verbs between start and end and matching mode, kills any existing verb, sets the saveid to 0 and generally inits the verb.

For all verbs between start and end and matching mode, kills any existing verb.

Sets the camera’s x position.

Makes object inherit from all of the given classes. A class of "0" will clear all of the object’s existing class data.

Sets the given object’s name.

Sets the owner of the object.

Sets the state of the object.

This assigns a list of values to a range of variables.

Values can be either bytes or words, but not both, and is determined by the maximum value present.

descumm outputs the number of values in the list as numvalues, this is optional.

The above instructions are the same, the second instruction just explicitly states the number of values in the list that follows. After running this instruction, the affected variables will look like this:

soundKludge adds instructions to the queue for the iMUSE dynamic music system. If the first item in the list is -1, the existing sound queue is processed. Otherwise, the list of instructions is added to the queue. The instructions are just normal variables or constants.

Alban Bedel, the author of ScummC, has some info on iMUSE at his website: http://alban.dotsec.net/15.html

Adds the music into the queue to be played.

Starts the object’s script (OBCD blocks), passing the given arguments.

Spawns a new thread running the code in script script. The new script has its local variables initialised to the list args. Uninitialised variables have undefined values.

The R and F flags indicate whether the script is recursive and/or freeze resistent.

descumm does not output these flags, so Scummbler will look at the opcode value. However, you should not include both the opcode and the flags, as they will conflict and lead to ambiguity as to the intended meaning.

Both of the above instructions start script 124 normally.

Both of the above instructions start script 124 with the freeze resistent flag set.

This will start script 124 with both freeze resistent and recursive flags set, even though the freeze resistent flag has not been specified in the function call, as the flag is present in the original opcode.

Adds the given sound to the sound queue to be played.

Stops all sounds.

Marks the calling script as dead, to be later pruned from the thread pool. Cleans up residual arrays. This must always be the last instruction in every script.

Marks the given object script as dead, to be later pruned from the thread pool. Cleans up residual arrays.

Marks the given script as dead, to be later pruned from the thread pool. Cleans up residual arrays.

Stops the given sound.

Loads the string into the resource slot given by resID.

Creates a duplicate of the string at sourceID into destinationID. The old string at destinationID is lost.

Writes char at the given position index of the string resource located at slot resID. Out of bounds accesses cause undefined behaviour.

Reads a byte (an ASCII character) at the given position index of the string resource located at slot resID, and writes it to result. Out of bounds accesses cause undefined behaviour.

Allocates or frees a string resource, located at resource slot resID. The string length is initialised to size; if size is zero, the string is freed.

operation must be:

RESTART, PAUSE, and QUIT are special tokens and should not be enclosed in quotes.

Assigns an image (object) to a verb.

Assigns the name to the verb slot.

Sets the colour of the verb.

Sets the highlight colour of the verb.

Sets the verb’s top-left co-ordinates.

Makes this verb active.

Makes this verb inactive.

Kills this verb.

Creates a verb in the slot for the given verb. If the slot is 0 (verb doesn’t already exist), will add it to the next unusued slot; if this exceeds the global maximum number of verbs an error will be raised.

Sets the dim colour of the verb.

Dims this verb.

Sets the key code associated with this verb.

Centres the verb.

Loads the given string resource into the verb’s slot. If either the string resource or verb slot is not found (0), the verb resource is nuked.

Assigns an object from the given room to the verb (if the object’s image is not already the given object).

Sets the background colour of the verb.

If the given actor is moving, breaks this script’s execution and resumes at this instruction again.

If the global variable VAR_HAVE_MSG (Var[3]) is not zero, breaks this script’s execution and resumes at this instruction again.

If the camera has not reached its destination x position, breaks this script’s execution and resumes at this instruction again.

If there is a sentence present, breaks this script’s execution and resumes at this instruction again

Sets the actor to begin walking to the given position.

Walks walkingactor towards targetactor by the given distance.

Sets the actor to begin walking to the given object’s position.

This is the campfire cutscene from the beginning of Monkey Island 2, as decompiled by descumm.

The very first line tells us that this is a local script; that is, it is stored within a room container, and cannot be called from any other room.

So, what can we do? Let’s give Guybrush a new story to tell. First, let’s define a few values for convenience. If you load up Monkey Island 2, you will discover that Fink says the line "I think I know how he must have felt.", and Bart says the line "Yeah, if I hear this story one more time, I’m gonna be crying myself.". If we look at the calling code…

Now, let’s insert our new conversation, making use of these define values.

Our final script now looks like this:

Because Scummbler treats the bits in square brackets as labels, we preserve the existing jump at [000A] that goes to [049D], even though the number of instructions between them has increased.