SCUMM/V5 opcodes

SCUMM V5 opcodes

The following conventions are used in the encoding descriptions.

opcode	The instruction's opcode, with the appropriate bits set according to the parameters.
result	A result pointer. (A standard word pointer, always a LE word.)
var	A var pointer. Same as above, but is not written to. Because this is always a var, the opcode is not affected like with normal parameter/pointers.
value[8]	An 8-bit constant (a byte).
value[16]	A 16-bit constant (a word LE).
value[p8]	An 8-bit parameter. This may be encoded as a word LE if it's a pointer, or a byte if it's a constant.
value[p16]	A 16-bit parameter. This is always encoded as a word LE, and may be a pointer or constant.
value[v16]	A variable number of word LE parameters. These are encoded as a sequence of aux[8] param[p16]; param; aux contains the parameter bit to describe param. A byte of $FF terminates the sequence.
value[o]	The offset word for parameter value. This is only encoded if needed, but always at the position indicated. If not specified, the offset word occurs immediately after the parameter.
value[s]	A null-terminated ASCII string.
(term)	An optional term.
term...	One or more terms.

Of course, due to the non-orthogonality of the opcodes, there are lots of exceptions.

actorFollowCamera ($52)

Encoding

opcode actor[p8]

Operation

Sets the camera to follow the given actor?

actorFromPos ($15)

Encoding

opcode result x[p16] y[p16]

Operation

Returns the actor located at the given co-ordinates.

actorOps ($13)

parameters depend on auxiliary opcode; terminated by $FF

Encoding

opcode actor[p8] sub-opcode... $FF

sub-opcode can be any of the following:
$01 costume[p8]
$02 xspeed[p8] yspeed[p8]
$03 sound[p8]
$04 walkframe[p8]
$05 starttalk[p8] endtalk[p8]
$06 standframe[p8]
$07 arg1[p8] arg2[p8] arg3[p8]
$08
$09 elevation[p16]
$0A
$0B index[p8] value[p8]
$0C colour[p8]
$0D name[s]
$0E initframe[p8]
$10 width[p8]
$11 xscale[p8] yscale[p8]
$12
$13 zplane[p8]
$14
$15 animspeed[p8]
$16 mode[p8]

Operation

Miscellaneous actions on actors.

Opcode	Meaning	Description
$00	dummy	A dummy case, does nothing (in ScummVM).
$01	SO_COSTUME	Sets the actor's costume.
$02	SO_STEP_DIST	Sets the actor's walking speed for x and y.
$03	SO_SOUND	Associates a sound with the actor (footsteps?)
$04	SO_WALK_ANIMATION	Sets the current frame of the walking animation.
$05	SO_TALK_ANIMATION	Sets the start and stop frames of the talking animation.
$06	SO_STAND_ANIMATION	Sets the current frame of the standing animation.
$07	SO_ANIMATION	Unknown; seems to be unused in ScummVM.
$08	SO_DEFAULT	Initializes actor.
$09	SO_ELEVATION	Sets the actor's elevation to the given value.
$0A	SO_ANIMATION_DEFAULT	Initializes the actor's animation frames. Init frame = 1 Walk frame = 2 Stand frame = 3 Talk start frame = 4 Talk stop frame = 5
$0B	SO_PALETTE	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).
$0C	SO_TALK_COLOR	Sets the actor's talk colour.
$0D	SO_ACTOR_NAME	Sets the actor's name to the given null-terminated string.
$0E	SO_INIT_ANIMATION	Sets the current frame of the initial animation.
$10	SO_ACTOR_WIDTH	Sets the actor's width.
$11	SO_ACTOR_SCALE	Sets the actor's X and Y scales.
$12	SO_NEVER_ZCLIP	Turns off all Z-clipping for the actor.
$13	SO_ALWAYS_ZCLIP	Forces the actor's Z-clipping for the given Z-plane?
$14	SO_IGNORE_BOXES	Ignores boxes, turns off Z-clipping, and puts actor somewhere if the actor is in the current room?
$15	SO_FOLLOW_BOXES	Follows boxes, turns off Z-clipping, and puts actor somewhere if the actor is in the current room?
$16	SO_ANIMATION_SPEED	Sets the animatino speed
$17	SO_SHADOW	Sets the shadow mode.

Variants

In SCUMM V4, sub-opcode $11 (SO_ACTOR_SCALE) only takes one parameter, so X and Y scaling is done at a 1:1 ratio.

actorSetClass ($5D)

Encoding

opcode object[p16] classes[v16]...

Operation

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

add ($5A)

Encoding

opcode result value[p16]

Operation

result := result + value

The variable pointed to by result is read, value is added to it, and the result written back.

and ($17)

one parameter, uses result

Encoding

opcode result value[p16]

Operation

result := result and value

The variable pointed to by result is read, logically ANDed with value, and the result written back.

animateActor ($11)

Encoding

opcode actor[p8] anim[p8]'

Operation

Starts the given animation for the given actor.

arrayOp ($27)

parameters depend on auxiliary opcode

Encoding

opcode $01 array[p8]
opcode $02 dest[p8] src[p8]
opcode $03 array[p8] index[p8] data[p8]
opcode $04 result array[p8] index[p8]
opcode $05 array[p8] size[p8]

Operation

Miscellaneous actions on Arrays (referred to by resource number).

Opcode	Meaning	Description
$01	load array	Ensures that the Array is loaded into memory. [I don't know what this does.]
$02	copy array	Creates a duplicate of src at resource number dest. The old Array at dest is lost.
$03	write entry	Writes the byte data at offset index of Array array. Out of bounds accesses cause undefined behaviour.
$04	read entry	Sets result to the byte of data at offset index of Array array. Out of bounds accesses cause undefined behaviour.
$05	create entry	Allocates or frees an Array. The Array array is initialised to size size; if size is zero, the Array is freed.

breakHere ($80)

no parameters

Encoding

opcode

Operation

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

chainScript ($42)

one parameter plus varargs

Encoding

opcode script[p8] args[v16]...

Operation

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

cursorCommand ($2C)

parameters depend on auxiliary opcode

Encoding

opcode sub-opcode

sub-opcode can be any of the following: $01
$02
$03
$04
$05
$06
$07
$08
$0A cursornum[p8] charletter[p8]
$0B index[p8] x[p8] y[p8]
$0C cursor[p8]
$0D charset[p8]
$0E colours[v16]...

Operation

Miscellaneous actions on cursors & charsets.

Opcode	Meaning	Description
$01	SO_CURSOR_ON	Turns the cursor on.
$02	SO_CURSOR_OFF	Turns the cursor off.
$03	SO_USERPUT_ON	??? Becomes 1
$04	SO_USERPUT_OFF	??? Becomes 0
$05	SO_CURSOR_SOFT_ON	Increments the cursor's state?
$06	SO_CURSOR_SOFT_OFF	Decrements the cursor's state?
$07	SO_USERPUT_SOFT_ON	??? Incremented
$08	SO_USERPUT_SOFT_OFF	??? Decremented
$0A	SO_CURSOR_IMAGE	Changes the cursor image to a new one, based on image in a character set. Only used in Loom.
$0B	SO_CURSOR_HOTSPOT	Changes the hotspot of a cursor. Only used in Loom.
$0C	SO_CURSOR_SET	Changes the current cursor. Must be between 0 and 3 inclusive.
$0D	SO_CHARSET_SET	Initializes the given character set.
$0E	SO_CHARSET_COLORS	Initializes the character set data & colours to the given arguments? Must have 16 arguments?

Variants

In SCUMM V3, sub-opcode $0E performs a different function, possibly initializing a character set.

cutScene ($40)

Encoding

opcode args[v16]...

Operation

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

debug ($6B)

one parameter, no result

Encoding

opcode param[p16]

Operation

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

decrement ($C6)

no parameters, uses result

Encoding

opcode result

Operation

result := result - 1

Reads the variable pointed to by result, decrements it, and writes it back.

delay ($2E)

one constant parameter

Encoding

opcode param[24]

Operation

Suspends the current thread for the appropriate number of 1/60ths of a second. Yes, that really is a 24-bit LE constant.

delayVariable ($2E)

one constant parameter

Encoding

opcode var

Operation

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

divide ($5B)

one parameter, uses result

Encoding

opcode result value[p16]

Operation

result := result / value

The variable pointed to by result is read, divided by value, and the result written back. If value is zero, the result is undefined (and the interpeter may halt with an error).

doSentence ($19)

Encoding

opcode verb[p8] objectA[p16] objectB[p16]

Operation

Performs a verb sentence action. If verb is $FE, the current sentence script is stopped, status cleared etc.

drawBox ($3F)

two parameters, does not use result, supplementary opcode byte with three more subsequent parameters

Encoding

opcode left[p16] top[p16] auxopcode[8] right[p16] bottom[p16] colour[p8]

Operation

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

The only part of auxopcode that is relevant are the parameter bits. The rest of the opcode is ignored.

dummy ($A7)

Encoding

opcode

Operation

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.

Variants

In SCUMM V3 and V4, this opcode is used for the saveLoadVars instruction.

endCutScene ($C0)

Encoding

opcode'

Operation

Ends the cutscene, performing cleanup if necessary.

equalZero ($28)

jumps

Encoding

opcode var target[16]

Operation

unless (var == 0) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

faceActor ($09)

Encoding

opcode actor[p8] object[p16]

Operation

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

findInventory ($3D)

Encoding

opcode result x[p8] y[p8]

findObject ($35)

Encoding

opcode result x[p8] y[p8]

freezeScripts ($60)

Encoding

opcode script[p8]

Operation

Freezes given script. Unfreezes all scripts if script is 0.

getActorCostume ($71)

Encoding

opcode result actor[p8]

Operation

Returns the actor's current costume.

getActorElevation ($06)

Encoding

opcode result actor[p8]

Operation

Returns the actor's current elevation.

getActorFacing ($63)

Encoding

opcode result actor[p8]

Operation

Returns the current direction the actor is facing.

getActorMoving ($56)

Encoding

opcode result actor[p8]

Operation

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

getActorRoom ($03)

Encoding

opcode result actor[p8]

Operation

Returns the room the actor currently occupies?

getActorScale ($3B)

Encoding

opcode result actor[p8]

Operation

Returns the actor's current scale.

Variants

In Indy3, this opcode is used for waitForActor.

getActorWalkBox ($7B)

Encoding

opcode result actor[p8]

Operation

Returns the actor's walkbox.

getActorWidth ($6C)

Encoding

opcode result actor[p8]

Operation

Returns the actor's width.

getActorX ($43)

Encoding

opcode result actor[p16]

Operation

Returns the actor's current X co-ordinate.

getActorY ($23)

Encoding

opcode result actor[p16]

Operation

Returns the actor's current Y co-ordinate.

getAnimCounter ($22)

This opcode is used for saveLoadGame in SCUMM V3.

Encoding

opcode result actor[p8]

Operation

Returns the actor's animation counter.

getClosestObjActor ($66)

Encoding

opcode result actor[p16]

Operation

Returns the object closest to the actor. Items that are more than 255 units (pixels in newer games, characters in older games) away from the actor will not be detected.

getDist ($34)

Encoding

opcode result objA[p16] objB[p16]

Operation

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

getInventoryCount ($31)

Encoding

opcode result actor[p8]

Operation

Returns the number of items in an actor's inventory?

getObjectOwner ($10)

Encoding

opcode result actor[p16]

Operation

Returns the owner of an object.

getObjectState ($0F)

This opcode behaves differently in small header V5 games.

Encoding

opcode result object[p16]

Operation

Returns the state of the object.

Variants

In small header games, the encoding becomes: opcode object[p16] state[p8] target[16] operation becomes unless (getState(object) == state) goto target

getRandomNumber ($16)

Encoding

opcode result seed[p8]

Operation

Returns a new random number based on the given seed.

getScriptRunning ($68)

Encoding

opcode result script[p8]

Operation

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

getStringWidth ($67)

Encoding

opcode result strptr[p8]

Operation

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

getVerbEntryPoint ($0B)

Encoding

opcode result object[p16] verb[p16]

Operation

Returns the entry point for the response code/script for when the given verb is applied to the given object?

ifClassOfIs ($1D)

jumps

Encoding

opcode value[p16] args[p16]...

Operation

unless (value.class is one of [args.class]) goto target

Compares the value's class with all classes given in args.

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

increment ($46)

no parameters, uses result

Encoding

opcode result

Operation

result := result + 1

Reads the variable pointed to by result, increments it, and writes it back.

isActorInBox ($1F)

Encoding

opcode actor[p8] box[p8] target[16]

Operation

If the actor's co-ordinates are not within the bounds of the given box, jump to target.

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isEqual ($48)

Encoding

opcode var value[p16] target[16]

Operation

unless (value == var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isGreater ($78)

Encoding

opcode var value[p16] target[16]

Operation

unless (value > var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isGreaterEqual ($04)

Encoding

opcode var value[p16] target[16]

Operation

unless (value >= var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isLess ($44)

Encoding

opcode var value[p16] target[16]

Operation

unless (value < var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isNotEqual ($08)

Encoding

opcode var value[p16] target[16]

Operation

unless (value != var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

isSoundRunning ($7C)

Encoding

opcode result sound[p8]

Operation

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

jumpRelative ($18)

jumps

Encoding

opcode target[16]

Operation

PC := PC + target

The inline constant target is read as a signed word and added to the program counter after the instruction has been read. Therefore, if target is zero, the instruction will do nothing; if target is -3, an infinite loop will result.

lessOrEqual ($38)

jumps

Encoding

opcode var value[p16] target[16]

Operation

unless (value <= var) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

move ($1A)

Encoding

opcode result value[p16]

Operation

result := value

Value is moved into result.

multiply ($1B)

Encoding

opcode result value[p16]

Operation

result := result * value

The variable pointed to by result is read, multiplied by value, and written back.

notEqualZero ($A8)

Encoding

opcode var target[16]

Operation

unless (var != 0) goto target

Target is a byte offset (measured from after this instruction), which will be added to the instruction pointer.

or ($57)

one parameter, uses result

Encoding

opcode result value[p16]

Operation

result := result or value

The variable pointed to by result is read, logically ORed with value, and the result written back.

setVarRange ($26)

non-standard encoding

Encoding

opcode result number[8] values[8]...
or
opcode result number[8] values[16]...

Operation

This sets a number of variables to the given parameters. The starting variable is given as "result", and the number of variables to modify is given as "number". This is followed by the same number of values, which will be put into the variable locations. The values are constants, and can be either 16-bit, if the highest bit of the opcode is set, i.e. $A6; or 8-bit, if the highest bit of the opcode is not set, i.e. $26. Note that all values are affected by the opcode's high bit; you can't mix 8 and 16-bit values.

descumm example

setVarRange(Var[178],9,[0,0,0,0,0,0,0,0,0]);

This sets variables 178 to 186 (inclusive) to 0.

startScript ($0A)

one parameter plus varargs, extra encoding in opcode

Encoding

opcode script[p8] args[v16]...

Operation

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 opcode carries extra information:

7	6	5	4 0
P1	Q	F	$0A

subtract ($3A)

Encoding

opcode result value[p16]

Operation

result := result - value

The variable pointed to by result is read, value is subtracted from it, and the result written back.

Table of Parameters

This is a work in progress and is missing opcodes.

This table shows a summary of the opcodes and their parameters in a concise fashion. The information has been gleaned from the descumm source code, so some instruction names might not match those listed above.

Currently it is missing:

comparisons (lessThan, greaterThanEqual, equalZero etc)
drawObject
do_resource
do_if_state_code (comparisons)
do_print_ego
do_varset_code
do_unconditional_jump
loadRoomWithEgo
do_cursor_command
doSentence
do_expr_code
do_load_code_to_string (sub-opcode of 0x27)
do_actorops
do_pseudoRoom(buf)
do_room_ops(buf)
do_verbops(buf, opcode)
setVarRange
do_matrix_ops(buf, opcode)

Some instructions listed here are actually sub-opcodes, i.e. "WaitForCamera" is actually the "Wait" opcode with a sub-opcode representing "For Camera".

Argument types:

• V = variable
• B = byte
• W = word
• L = list
• J = jump (used by almost all boolean expressions, comparisons)
• D = delay; 24-bit constant (only used by delay instruction, funnily enough)
• A = ASCII (0-terminated string?); used by "setObjectName"
• V|B or V|W = either a variable or a byte/word
• None, if it does not take that argument.

If an instruction returns a value, the result pointer follows immediately after the opcode and before any arguments.

Instruction	Returns a Value	Arg 1	Arg 2	Arg 3
actorFollowCamera	False	V|B	None	None
actorFromPos	True	V|W	V|W	None
animateCostume	False	V|B	V|B	None
beginOverride	False	None	None	None
breakHere	False	None	None	None
chainScript	False	V|B	L	None
classOfIs	False	V|W	L	J
CopyString	False	V|B	V|B	None
CreateString	False	V|B	V|B	None
cutscene	False	L	None	None
debug?	False	V|W	None	None
delay	False	D	None	None
delayVariable	False	V	None	None
deleteVerbs	False	V|B	V|B	V|B
dummy	False	None	None	None
endCutscene	False	None	None	None
endOverride	False	None	None	None
faceActor	False	V|B	V|W	None
findInventory	True	V|B	V|B	None
findObject	True	V|W	V|W	None
freezeScripts	False	V|B	None	None
getActorCostume	True	V|B	None	None
getActorElevation	True	V|B	None	None
getActorFacing	True	V|B	None	None
getActorMoving	True	V|B	None	None
getActorRoom	True	V|B	None	None
getActorScale	True	V|B	None	None
getActorWalkBox	True	V|B	None	None
getActorWidth	True	V|B	None	None
getActorX	True	V|W	None	None
getActorY	True	V|W	None	None
getClosestObjActor	True	V|W	None	None
getDist	True	V|W	V|W	None
getInventoryCount	True	V|B	None	None
getObjectOwner	True	V|W	None	None
getObjectState	True	V|W	None	None
getRandomNr	True	V|B	None	None
GetStringChar	True	V|B	V|B	None
getStringWidth	True	V|B	None	None
getVerbEntryPoint	True	V|W	V|W	None
isActorInBox	False	V|B	V|B	J
isScriptRunning	True	V|B	None	None
isSoundRunning	True	V|B	None	None
lights	False	V|B	B	B
loadRoom	False	V|B	None	None
oldRoomEffect-fadein	False	V|W	None	None
oldRoomEffect-set	False	V|W	None	None
panCameraTo	False	V|W	None	None
pickupObject	False	V|W	V|B	None
putActor	False	V|B	V|W	V|W
putActorAtObject	False	V|B	V|W	None
putActorInRoom	False	V|B	V|B	None
restoreVerbs	False	V|B	V|B	V|B
saveLoadGame	True	V|B	None	None
saveVerbs	False	V|B	V|B	V|B
setCameraAt	False	V|W	None	None
setClass	False	V|W	L	None
setObjectName	False	V|W	A	None
setOwnerOf	False	V|W	V|B	None
setState	False	V|W	V|B	None
SetStringChar	False	V|B	V|B	V|B
soundKludge	False	L	None	None
startMusic	False	V|B	None	None
startObject	False	V|W	V|B	L
startScript	False	V|B	L	None
startSound	False	V|B	None	None
stopMusic	False	None	None	None
stopObjectCode	False	None	None	None
stopObjectScript	False	V|W	None	None
stopScript	False	V|B	None	None
stopSound	False	V|B	None	None
systemOps	False	B	None	None
WaitForActor	False	V|B	None	None
WaitForCamera	False	None	None	None
WaitForMessage	False	None	None	None
WaitForSentence	False	None	None	None
walkActorTo	False	V|B	V|W	V|W
walkActorToActor	False	V|B	V|B	B
walkActorToObject	False	V|B	V|W	None