SCUMM/V5 opcodes

From ScummVM :: Wiki
< SCUMM
Revision as of 06:27, 20 March 2009 by Jestar jokin (talk | contribs) (→‎SCUMM V5 opcodes: Formatting, added basic branches, arithmetic)
Jump to navigation Jump to search

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)
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.
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.
target[16] A 16-bit contstant (a word LE), relative offset after this value, measured in bytes. Used in all comparison operations, jumpRelative, etc.
(term) An optional term.

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

actorFollowCamera ($52)

actorFromPos ($15)

actorSet ($13)

actorSetClass ($5D)

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)

arrayOp ($27)

parameters depend on auxilary 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)

cutScene ($40)

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 pointer[16]

Operation

pointer is dereferenced and the current thread suspended for that number of 1/60ths of a second. Note that pointer is an inline constant, not a parameter.

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)

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 colour colour.

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

drawObject ($05)

dummy ($67)

endCutScene ($C0)

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.

expression ($AC)

faceActor ($09)

findInventory ($3D)

findObject ($35)

freezeScripts ($60)

getActorCostume ($71)

getActorElevation ($06)

getActorFacing ($63)

getActorMoving ($56)

getActorRoom ($03)

getActorScale ($3B)

getActorWalkBox ($7B)

getActorWidth ($6C)

getActorX ($43)

getActorY ($23)

getAnimCounter ($22)

getClosestObjActor ($66)

getDist ($34)

getInventoryCount ($31)

getObjectOwner ($10)

getObjectState ($0F)

getRandomNumber ($16)

getScriptRunning ($68)

getVerbEntryPoint ($0B)

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)

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)

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.

lights ($70)

loadRoom ($72)

loadRoomWithEgo ($24)

matrixOp ($30)

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.

overRide ($58)

panCameraTo ($12)

pickupObject ($25)

print ($14)

printEgo ($D8)

pseudoRoom ($CC)

putActor ($01)

putActorAtObject ($0E)

putActorInRoom ($2D)

quitPauseRestart ($98)

resourceRoutines ($0C)

roomOp ($33)

saveRestoreVerbs ($AB)

setCameraAt ($32)

setObjectName ($54)

setOwnerOf ($29)

setState ($07)

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.

soundKludge ($4C)

startMusic ($01)

startObject ($37)

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

startSound ($1C)

stopMusic ($20)

stopObjectCode ($00)

stopObjectScript ($6E)

stopScript ($62)

stopSound ($3C)

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.

animateActor ($11)

wait ($AE)

walkActorTo ($1E)

walkActorToActor ($0D)

walkActorToObject ($36)

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