Difference between revisions of "SCUMM/V6 opcodes"

From ScummVM :: Wiki
Jump to navigation Jump to search
(lor, lt, mul from http://www.scummvm.org/docs/specs/scrp-v6.php)
m (behaviour -> behavior)
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Currently all entries from the reference on the [http://www.scummvm.org/docs/specs/scrp-v6.php main ScummVM website] have been transferred - please proofread and fix formatting where applicable.
=SCUMM V6 opcodes=
=SCUMM V6 opcodes=
The following conventions are used in the encoding descriptions.
The following conventions are used in the encoding descriptions.
Line 242: Line 245:
Performs a division operation on the stack. Note the order.
Performs a division operation on the stack. Note the order.


An attempt to divide by zero will cause undefined behaviour, and may cause the interpreter to crash.
An attempt to divide by zero will cause undefined behavior, and may cause the interpreter to crash.


==MM 83 doSentence==
==MM 83 doSentence==
Line 254: Line 257:
'''Stack'''
'''Stack'''


''( left , top , right , bottom , colour : -)''
''( left , top , right , bottom , color : -)''


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


==dup==
==dup==
Line 426: Line 429:
If value is any of arg1 .. argn , bool := 1, otherwise bool := 0
If value is any of arg1 .. argn , bool := 1, otherwise bool := 0


Tests to see if value is equal to any of the passed in arguments. If n is less than the number of entries on the stack, undefined behaviour will result.
Tests to see if value is equal to any of the passed in arguments. If n is less than the number of entries on the stack, undefined behavior will result.


==MM 98 isSoundRunning==
==MM 98 isSoundRunning==
Line 575: Line 578:


==neq==
==neq==
'''Encoding'''
''0F''
'''Stack'''
''( value1 , value2 : bool )''
'''Operation'''
If value1 value2 , set bool to 1, otherwise set it to 0
Tests the top two values on the stack to see if they are not equal.


==MM 78 panCameraTo==
==MM 78 panCameraTo==


==pickOneOf==
==pickOneOf==
'''Encoding'''
''CB''
'''Stack'''
''( index ,  arg0 ,  arg1 ,  arg2 , ...,  argn ,  n  :  value )''
'''Operation'''
value := arg[index]
Returns the index th argument on the stack. If n is less than the number of entries on the stack or index is out of range, undefined behavior will result, usually involving the interpreter shutting down.


==pickOneOfDefault==
==pickOneOfDefault==
'''Encoding'''
''CC''
'''Stack'''
''( index ,  arg0 ,  arg1 ,  arg2 , ...,  argn ,  n ,  default  :  value )''
'''Operation'''
If index is in the range 0.. n , value  :=  arg[index] ; otherwise value  :=  default .
Returns the index th argument on the stack. If index is out of range, default is returned instead. If n is less than the number of entries on the stack, undefined behavior will result, usually involving the interpreter shutting down.


==MM 84 pickupObject==
==MM 84 pickupObject==
Line 599: Line 641:


==pushByte==
==pushByte==
'''Encoding'''
''00 value^8
'''Stack'''
''(- : value )''
'''Operation'''
Pushes ''value'' onto the stack. It is not sign extended.


==pushByteVar==
==pushByteVar==
'''Encoding'''
''02 pointer^8''
'''Stack'''
''(- : value )''
'''Operation'''
Dereferences ''pointer'' and pushes the result onto the stack. Note that because pointer is encoded as a byte, it can only point to a word variable in the range 0000-00FF. Use pushWordVar for a more general version of this instruction.


==pushWord==
==pushWord==
'''Encoding'''
''01 value^16''
'''Stack'''
''(- : value )''
'''Operation'''
Pushes ''value'' onto the stack.


==pushWordVar==
==pushWordVar==
'''Encoding'''
''03 pointer^16''
'''Stack'''
''(- : value )''
'''Operation'''
Dereferences ''pointer'' and pushes the result onto the stack.


==MM 80 putActorAtObject==
==MM 80 putActorAtObject==
Line 611: Line 701:


==quitPauseRestart==
==quitPauseRestart==
This instruction varies according to the form.
'''Encoding'''
pause:
''AE 9E''
quit:
''AE A0''
'''Stack'''
''(- : -) (both forms)''
'''Operation'''
Pauses and quits the game. [TODO: Details!]


==MM 9B resourceRoutines==
==MM 9B resourceRoutines==
Line 645: Line 754:


==startScript==
==startScript==
'''Encoding'''
''5F''
'''Stack'''
''( script ,  arg0 ,  arg1 ,  arg2 , ...,  argn ,  n  : -)''
'''Operation'''
A new thread is started, running the code in the script whose resource number is ''script''. arg0 .. argn form the thread's initial local variables; unspecified variables are not initialised to any specific value.
The new thread starts executing immediately and the current thread is put into the PENDING state until the new thread is descheduled.


==MM 5E startScriptEx==
==MM 5E startScriptEx==
Line 665: Line 788:


==sub==
==sub==
'''Encoding'''
''15''
'''Stack'''
''( in1  in2:  out)''
'''Operation'''
''out:=in1-in2''
The top two items on the stack are popped off, the first subtracted from the second, and the result pushed back on the stack. Note the order.


==MM BA talkActor==
==MM BA talkActor==
Line 679: Line 815:


==wordArrayDec==
==wordArrayDec==
'''Encoding'''
''5B arrayp^16''
'''Stack'''
''( index  : -)''
'''Operation'''
''arrayp [0,  index ] :=  arrayp [0,  index ] - 1''
Increments the value at offset (0, ''index'') in the array whose resource number is pointed to by ''arrayp''.


==wordArrayInc==
==wordArrayInc==
'''Encoding'''
''53 arrayp^16''
'''Stack'''
''( index  : -)''
'''Operation'''
''arrayp [0,  index ] :=  arrayp [0,  index ] + 1''
Increments the value at offset (0,  index) in the array whose resource number is pointed to by ''arrayp''.


==wordArrayIndexedRead==
==wordArrayIndexedRead==
'''Encoding'''
''0B arrayp^16''
'''Stack'''
''( indexx , indexy : value )''
'''Operation'''
''value  :=  arrayp [ indexx ,  indexy ]''
Reads the value at offset (''indexx'', ''indexy'') from the array whose resource number is pointed to by ''arrayp''. The array can be a byte or word array; byte values are not sign extended.


==wordArrayIndexedWrite==
==wordArrayIndexedWrite==
'''Encoding'''
''4B arrayp^16''
'''Stack'''
''( indexx , indexy , value : -)''
'''Operation'''
''arrayp [ indexx ,  indexy ] := value''
Writes value to the array whose resource number is pointed to by ''arrayp'' at offset (''indexx'', ''indexy''). The array can be a byte or word array; when writing to a byte array, value is truncated.


==wordArrayRead==
==wordArrayRead==
'''Encoding'''
''07 arrayp16''
'''Stack'''
''( index : value )''
'''Operation'''
''value := arrayp [0,  index ]''
Reads the value at offset (0, ''index'') from the array whose resource number is pointed to by ''arrayp''. The array can be a byte or word array; byte values are not sign extended.


==wordArrayWrite==
==wordArrayWrite==
'''Encoding'''
''47 arrayp^8''
'''Stack'''
''( index value : -)''
'''Operation'''
''arrayp [0,  index ] := value''
Writes value to the array whose resource number is pointed to by ''arrayp'' at offset (0, ''index''). The array can be a byte or word array; when writing to a byte array, value is truncated.


==wordVarDec==
==wordVarDec==
'''Encoding'''
''57 pointer^16''
'''Stack'''
(- : -)
'''Operation'''
''* pointer := * pointer - 1''
Decrements the variable pointed to by ''pointer''.


==wordVarInc==
==wordVarInc==
'''Encoding'''
''4F pointer^16''
'''Stack'''
(- : -)
'''Operation'''
''* pointer := * pointer + 1''
Increments the variable pointed to by ''pointer''.


==writeByteVar==
==writeByteVar==
'''Encoding'''
''42 pointer^8''
'''Stack'''
( ''value'' : -)
'''Operation'''
''* pointer := value''
Writes ''value'' to the variable pointed to by ''pointer''. Note that as ''pointer'' is encoded as a byte, it can only point to word variables in the range 0x0000 to 0x00FF. For a more general form of this instruction, use writeWordVar.


==writeWordVar==
==writeWordVar==
'''Encoding'''
''43 pointer^16''
'''Stack'''
''( value : -)''
'''Operation'''
''* pointer := value''
Writes ''value'' to the variable pointed to by ''pointer''.


==zero==
==zero==
'''Encoding'''
''0D''
'''Stack'''
( ''value''  :  ''bool'' )
'''Operation'''
If ''value'' = 0, set ''bool'' to 1, otherwise set it to 0
Tests the value on the stack to see if it compares to zero.




''All material © 2000-2002 David Given, unless where stated otherwise.''
''All material © 2000-2002 David Given, unless where stated otherwise.''

Latest revision as of 03:06, 23 January 2011

Currently all entries from the reference on the main ScummVM website have been transferred - please proofread and fix formatting where applicable.


SCUMM V6 opcodes

The following conventions are used in the encoding descriptions.

$AB The constant hexadecimal byte 0xAB.
value[8] A constant byte value.
value[16] A constant word LE value.

The following conventions are used in the stack descriptions:

(in1, in2, in3 : out1, out2)

Indicates that the opcode is called with three items on the stack (the most recently pushed being in3) and replaces them with two items on the stack (the most recently pushed being out2).

abs ($C4)

Stack

(in : out)

Operation

out := abs(in)

The absolute value of the top-most item on the stack is calculated. (The absolute value being the value with the sign bit stripped off.)

actorFollowCamera ($79)

actorSet ($9D)

add ($14)

Stack

(in1, in2 : out)

Operation

out := in1 + in2

Performs a division operation on the stack.

animateActor ($82)

arrayOps (This instruction varies considerably according to the form.)

Encoding

load array:

   A4 CD arrayp16 

define array:

   A4 D0 arrayp16 data... 

set array:

   A4 D4 arrayp16 

Stack

...todo...

6.4.7 MM 95 beginOverride

MM 6C breakHere

MM CA breakMaybe

MM 5A byteArrayDec

MM 52 byteArrayInc

byteArrayIndexedRead

Encoding

0A arrayp8

Stack

( indexx , indexy : value )

Operation

value := arrayp [ indexx , indexy ]

Reads the value at offset ( indexx , indexy ) from the array whose resource number is pointed to by arrayp . The array can be a byte or word array; byte values are not sign extended. Note that because arrayp is encoded as a byte, it can only point to a word variable in the range 0000 to 00FF. Use wordArrayIndexedRead for a more general form.

byteArrayIndexedWrite

Encoding

4A arrayp8

Stack ( indexx , indexy , value : -)

Operation arrayp [ indexx , indexy ] := value

Writes value to the array whose resource number is pointed to by arrayp at offset ( indexx , indexy ). The array can be a byte or word array; byte when writing to a byte array, value is truncated. Note that because arrayp is encoded as a byte, it can only point to a word variable in the range 0000 to 00FF. Use wordArrayIndexedWrite for a more general form.

byteArrayRead

Encoding

06 arrayp8

Stack

( index : value )

Operation

value := arrayp [0, index ]

Reads the value at position (0, index ) from the array whose resource number is pointed to by arrayp . The array can be a byte or word array; when writing to an array, byte values are not sign extended. Note that because arrayp is encoded as a byte, it can only point to a word variable in the range 0000 to 00FF. Use wordArrayRead for a more general form.

byteArrayWrite

Encoding

46 arrayp8

Stack

( index value : -)

Operation

arrayp [0, index ] := value

Writes value to the array whose resource number is pointed to by arrayp at offset (0, index ). The array can be a byte or word array; when writing to a byte array, value is truncated. Note that because arrayp is encoded as a byte, it can only point to a word variable in the range 0000 to 00FF. Use wordArrayWrite for a more general form.

MM 56 byteVarDec

MM 4E byteVarInc

MM 9A createBoxMatrix

MM 6B cursorCommand

MM 68 cutScene

delay

Encoding

B0

Stack

( delay : -)

Operation

Prevents the current thread from being rescheduled until delay ticks have passed. Deschedules immediately.

delayLonger

Encoding

B1

Stack

( delay : -)

Operation

Prevents the current thread from being rescheduled until delay× 60 ticks have passed ( delay seconds). Deschedules immediately.

delayVeryLong

Encoding

B2

Stack

( delay : -)

Operation

Prevents the current thread from being rescheduled until delay× 3600 ticks have passed ( delay minutes). Deschedules immediately.

dim

Encoding BC type8 arrayp16

Stack ( max : -)

Operation

Allocates or frees an array.

If type is CC, then the array whose resource number is pointed to by arrayp is freed. Otherwise, a new one-dimensional array with a maximum index of max (i.e., max is one less than the size) is allocated and the resource number written to arrayp .

When allocating an array, if type is C7 then the array will contain words; if it is CB, then it will contain bytes. All other values are undefined. [Currently they all produce a byte array. What are they?]

dim2

Encoding

C0 type8 arrayp16

Stack

( maxx , maxy : -)

Operation

Allocates an array.

A new two-dimensional array is allocated and the resource number is written to arrayp . The new array will have a maximum X index of maxx and a maximum Y index of maxy (i.e., maxy is one less than the size).

When allocating an array, if type is C7 then the array will contain words; if it is CB, then it will contain bytes. All other values are undefined. [Currently they all produce a byte array. What are they?]

MM C5 distObjectObject

MM C6 distObjectPt

MM C7 distPtPt

div

Encoding

17

Stack

( in1 , in2 : out )

Operation

out := in1 / in2

Performs a division operation on the stack. Note the order.

An attempt to divide by zero will cause undefined behavior, and may cause the interpreter to crash.

MM 83 doSentence

drawBox

Encoding

A6

Stack

( left , top , right , bottom , color : -)

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

dup

Encoding 0C

Stack ( value  : value , value )

Operation Duplicates the top-most item on the stack.

MM 67 endCutScene

MM 96 endOverride

eq

Encoding

0E

Stack

( value1 , value2  : bool )

Operation

If value1=value2 , set bool to 1, otherwise set it to 0

Tests the top two values on the stack to see if they are equal.

MM 81 faceActor

MM 92 findInventory

MM A0 findObject

freezeUnfreeze

Encoding

6A

Stack

( bool  : -)

Operation

bool=0 :

   Thaw all currently frozen threads. 

0<bool<$80 :

   Freeze all threads that are not marked as unfreezable. 

bool³ $80 :

   Freeze all threads, even those that are marked as unfreezable. 

Freezing is a nestable operation; a thread which is frozen twice must be thawed twice before it becomes runnable again.

ge

Encoding

13

Stack

( value1 value2  : bool)

Operation

If value1³ value2 , set bool to 1, otherwise set it to 0

Compares the top two values on the stack. Note the order.

MM AB getActorAnimCounter1

MM 91 getActorCostume

MM A2 getActorElevation

MM 9F getActorFromXY

MM 8A getActorMoving

MM 8C getActorRoom

MM AA getActorScaleX

MM 90 getActorWalkBox

MM A8 getActorWidth

MM 93 getInventoryCount

MM 8F getObjectDir

MM 8D getObjectX

MM 8E getObjectY

MM 72 getOwner

getRandomNumber

Encoding

87

Stack

( max  : result )

Operation A random number in the range 0 to max inclusive is calculated, and the result pushed onto the stack. The result is also written to the RandomNumber word variable (see 6.5).

getRandomNumberRange

Encoding 88

Stack ( min , max , : result )

Operation A random number in the range min to max inclusive is calculated, and the result pushed onto the stack. The result is also written to the RandomNumber word variable (see 6.5).

MM 8B getScriptRunning

MM 6F getState

MM A3 getVerbEntryPoint

MM 94 getVerbFromXY

gt

Encoding

10

Stack

( value1 , value2  : bool )

Operation

If value1 > value2 , set bool to 1, otherwise set it to 0

Compares the top two values on the stack. Note the order.

MM6D ifClassOfls

MM AF isActorInBox

isAnyOf

Encoding

AD

Stack

( arg1 , arg2 , arg3 , ..., argn , n , value  : bool )

Operation

If value is any of arg1 .. argn , bool := 1, otherwise bool := 0

Tests to see if value is equal to any of the passed in arguments. If n is less than the number of entries on the stack, undefined behavior will result.

MM 98 isSoundRunning

MM 73 jump

Encoding

73 offset^16

Stack

(- : -)

Operation

pc := pc + offset

offset is added to the current program counter after the instruction has been decoded.

jumpFalse

Encoding

5D offset^16

Stack

( bool  : -)

Operation

if bool = 0, pc := pc + offset

Pops the top value off the stack. If zero, then offset is added to the current program counter after the instruction has been decoded.

jumpTrue

Encoding

5C offset^16

Stack

( bool  : -)

Operation

if bool 0, pc := pc + offset

Pops the top value off the stack. If non-zero, then offset is added to the current program counter after the instruction has been decoded.

kill

Encoding

1A

Stack

( value  : -)

Operation

Pops the top value off the stack and discards it.

land

Encoding

18

Stack

( in1 in2  : out)

Operation

out:=in1 && in2

Performs a logical and operation on the stack (not a bitwise and). Note the order.

The boolean values are as in C, with 0 for false and non-zero for true.

le

Encoding

12

Stack

( value1 value2  : bool)

Operation

If value1£ value2 , set bool to 1, otherwise set it to 0

Compares the top two values on the stack. Note the order.

MM 7B loadRoom

MM 85 loadRoomWithEgo

lor

Encoding

19

Stack

( in1 in2  : out)

Operation

out:=in1 || in2

Performs a logical or operation on the stack (not a bitwise or). Note the order.

The boolean values are as in C, with 0 for false and non-zero for true.

lt

Encoding

11

Stack

( value1 value2  : bool)

Operation

If value1<value2 , set bool to 1, otherwise set it to 0

Compares the top two values on the stack. Note the order.

MM C9 miscOps

mul

Encoding

16

Stack

( in1 in2  : out)

Operation

out:=in1× in2

Performs a multiplication operation on the stack. Note the order.

neq

Encoding

0F

Stack

( value1 , value2 : bool )

Operation

If value1 value2 , set bool to 1, otherwise set it to 0

Tests the top two values on the stack to see if they are not equal.

MM 78 panCameraTo

pickOneOf

Encoding

CB

Stack

( index , arg0 , arg1 , arg2 , ..., argn , n  : value )

Operation

value := arg[index]

Returns the index th argument on the stack. If n is less than the number of entries on the stack or index is out of range, undefined behavior will result, usually involving the interpreter shutting down.

pickOneOfDefault

Encoding

CC

Stack

( index , arg0 , arg1 , arg2 , ..., argn , n , default  : value )

Operation

If index is in the range 0.. n , value  := arg[index] ; otherwise value  := default .

Returns the index th argument on the stack. If index is out of range, default is returned instead. If n is less than the number of entries on the stack, undefined behavior will result, usually involving the interpreter shutting down.

MM 84 pickupObject

MM B8 printActor

MM B9 printEgo

MM B4 print0

MM B5 print1

MM B6 print2

MM B7 print3

MM A1 psuedoRoom

pushByte

Encoding

00 value^8

Stack

(- : value )

Operation

Pushes value onto the stack. It is not sign extended.

pushByteVar

Encoding

02 pointer^8

Stack

(- : value )

Operation

Dereferences pointer and pushes the result onto the stack. Note that because pointer is encoded as a byte, it can only point to a word variable in the range 0000-00FF. Use pushWordVar for a more general version of this instruction.

pushWord

Encoding

01 value^16

Stack

(- : value )

Operation

Pushes value onto the stack.

pushWordVar

Encoding

03 pointer^16

Stack

(- : value )

Operation

Dereferences pointer and pushes the result onto the stack.

MM 80 putActorAtObject

MM 7F putActorInRoom

quitPauseRestart

This instruction varies according to the form.

Encoding

pause:

AE 9E

quit:

AE A0

Stack

(- : -) (both forms)

Operation Pauses and quits the game. [TODO: Details!]

MM 9B resourceRoutines

MM 9C roomOps

MM BF runScriptQuick

MM BE runVerbCodeQuick

MM A5 saveRestoreVerbs

MM 99 setBoxFlags

MM 7A setCameraAt

MM 6E setClass

MM 97 setObjectName

MM 61 setObjectState

MM 62 setObjectXY

MM 71 setOwner

MM 70 setState

MM AC soundKludge

MM 76 startMusic

MM 60 startObject

startScript

Encoding

5F

Stack

( script , arg0 , arg1 , arg2 , ..., argn , n  : -)

Operation

A new thread is started, running the code in the script whose resource number is script. arg0 .. argn form the thread's initial local variables; unspecified variables are not initialised to any specific value.

The new thread starts executing immediately and the current thread is put into the PENDING state until the new thread is descheduled.

MM 5E startScriptEx

MM 74 startSound

MM 69 stopMusic

MM 65 stopObjectCode

MM 66 stopObjectCode

MM 77 stopObjectScript

MM 7C stopScript

MM B3 stopSentence

MM 75 stopSound

sub

Encoding

15

Stack

( in1 in2: out)

Operation out:=in1-in2

The top two items on the stack are popped off, the first subtracted from the second, and the result pushed back on the stack. Note the order.

MM BA talkActor

MM BB talkEgo

MM 9E verbOps

MM A9 wait

MM 75 walkActorTo

MM 7D walkActorToObj

wordArrayDec

Encoding

5B arrayp^16

Stack

( index  : -)

Operation

arrayp [0, index ] := arrayp [0, index ] - 1

Increments the value at offset (0, index) in the array whose resource number is pointed to by arrayp.

wordArrayInc

Encoding

53 arrayp^16

Stack

( index  : -)

Operation

arrayp [0, index ] := arrayp [0, index ] + 1

Increments the value at offset (0, index) in the array whose resource number is pointed to by arrayp.

wordArrayIndexedRead

Encoding

0B arrayp^16

Stack

( indexx , indexy : value )

Operation

value  := arrayp [ indexx , indexy ]

Reads the value at offset (indexx, indexy) from the array whose resource number is pointed to by arrayp. The array can be a byte or word array; byte values are not sign extended.

wordArrayIndexedWrite

Encoding

4B arrayp^16

Stack

( indexx , indexy , value : -)

Operation

arrayp [ indexx , indexy ] := value

Writes value to the array whose resource number is pointed to by arrayp at offset (indexx, indexy). The array can be a byte or word array; when writing to a byte array, value is truncated.

wordArrayRead

Encoding

07 arrayp16

Stack

( index : value )

Operation

value := arrayp [0, index ]

Reads the value at offset (0, index) from the array whose resource number is pointed to by arrayp. The array can be a byte or word array; byte values are not sign extended.

wordArrayWrite

Encoding

47 arrayp^8

Stack

( index value : -)

Operation

arrayp [0, index ] := value

Writes value to the array whose resource number is pointed to by arrayp at offset (0, index). The array can be a byte or word array; when writing to a byte array, value is truncated.

wordVarDec

Encoding

57 pointer^16

Stack

(- : -)

Operation

* pointer := * pointer - 1

Decrements the variable pointed to by pointer.

wordVarInc

Encoding

4F pointer^16

Stack

(- : -)

Operation

* pointer := * pointer + 1

Increments the variable pointed to by pointer.

writeByteVar

Encoding

42 pointer^8

Stack

( value : -)

Operation

* pointer := value

Writes value to the variable pointed to by pointer. Note that as pointer is encoded as a byte, it can only point to word variables in the range 0x0000 to 0x00FF. For a more general form of this instruction, use writeWordVar.

writeWordVar

Encoding

43 pointer^16

Stack

( value : -)

Operation

* pointer := value

Writes value to the variable pointed to by pointer.

zero

Encoding

0D

Stack ( value  : bool )

Operation

If value = 0, set bool to 1, otherwise set it to 0

Tests the value on the stack to see if it compares to zero.


All material © 2000-2002 David Given, unless where stated otherwise.