Difference between revisions of "SCUMM/V5 opcodes"

Jump to navigation Jump to search
9,276 bytes added ,  07:09, 25 March 2009
→‎SCUMM V5 opcodes: Entered about half the instructions, based on script_v5.cpp
m (some line breaks)
(→‎SCUMM V5 opcodes: Entered about half the instructions, based on script_v5.cpp)
Line 9: Line 9:
|result||A result pointer. (A standard word pointer, always a LE word.)
|result||A result pointer. (A standard word pointer, always a LE word.)
|-
|-
|var||A var pointer. (Same as above, but is not written to)
|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[8]||An 8-bit constant (a byte).
Line 17: Line 17:
|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[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[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[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[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)||An optional term.
|-
|term...||One or more terms.
|}
|}


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


==actorFollowCamera ($52)==
==actorFollowCamera ($52)==
===Encoding===
''opcode actor[p8]''
===Operation===
Sets the camera to follow the given actor?


==actorFromPos ($15)==
==actorFromPos ($15)==


==actorSet ($13)==
===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:<br>
''$01 costume[p8]''<br>
''$02 xspeed[p8] yspeed[p8]''<br>
''$03 sound[p8]''<br>
''$04 walkframe[p8]''<br>
''$05 starttalk[p8] endtalk[p8]''<br>
''$06 standframe[p8]''<br>
''$07 arg1[p8] arg2[p8] arg3[p8]''<br>
''$08''<br>
''$09 elevation[p16]''<br>
''$0A''<br>
''$0B index[p8] value[p8]''<br>
''$0C colour[p8]''<br>
''$0D name[s]''<br>
''$0E initframe[p8]''<br>
''$10 width[p8]''<br>
''$11 xscale[p8] yscale[p8]''<br>
''$12''<br>
''$13 zplane[p8]''<br>
''$14''<br>
''$15 animspeed[p8]''<br>
''$16 mode[p8]''<br>
 
===Operation===
Miscellaneous actions on actors.
 
{| border="1" cellpadding="2" width=100%
|- style="background:silver"
|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.<br>Init frame = 1<br>Walk frame = 2<br>Stand frame = 3<br>Talk start frame = 4<br> 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)==
==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)==
==add ($5A)==
Line 45: Line 156:


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


==and ($17)==
==and ($17)==
one parameter, uses result
one parameter, uses result


Line 57: Line 168:


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


==animateActor ($11)==
==animateActor ($11)==
===Encoding===
''opcode actor[p8] anim[p8]'''
===Operation===
Starts the given animation for the given actor.


==arrayOp ($27)==
==arrayOp ($27)==
 
parameters depend on auxiliary opcode
parameters depend on auxilary opcode


===Encoding===
===Encoding===
Line 88: Line 206:
|$05||create entry||Allocates or frees an Array. The Array array is initialised to size size; if size is zero, the Array is freed.
|$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)==
==breakHere ($80)==
no parameters
no parameters


Line 98: Line 216:
===Operation===
===Operation===
Deschedules the currently running thread. Execution continues at the next instruction when the thread's next timeslot comes around.
Deschedules the currently running thread. Execution continues at the next instruction when the thread's next timeslot comes around.


==chainScript ($42)==
==chainScript ($42)==
one parameter plus varargs
one parameter plus varargs


Line 108: Line 226:
===Operation===
===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.
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)==
==cursorCommand ($2C)==
parameters depend on auxiliary opcode
===Encoding===
''opcode sub-opcode''
sub-opcode can be any of the following:
''$01''<br>
''$02''<br>
''$03''<br>
''$04''<br>
''$05''<br>
''$06''<br>
''$07''<br>
''$08''<br>
''$0A cursornum[p8] charletter[p8]''<br>
''$0B index[p8] x[p8] y[p8]''<br>
''$0C cursor[p8]''<br>
''$0D charset[p8]''<br>
''$0E colours[v16]...''<br>
===Operation===
Miscellaneous actions on cursors & charsets.
{| border="1" cellpadding="2" width=100%
|- style="background:silver"
|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)==
==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)==
==debug ($6B)==
one parameter, no result
one parameter, no result


Line 122: Line 304:
===Operation===
===Operation===
Passes the parameter to the interpreter's debugger. What this does is entirely platform-specific (and may do nothing).
Passes the parameter to the interpreter's debugger. What this does is entirely platform-specific (and may do nothing).


==decrement ($C6)==
==decrement ($C6)==
no parameters, uses result
no parameters, uses result


Line 134: Line 316:


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


==delay ($2E)==
==delay ($2E)==
one constant parameter
one constant parameter


Line 144: Line 326:
===Operation===
===Operation===
Suspends the current thread for the appropriate number of 1/60ths of a second. Yes, that really is a 24-bit LE constant.
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)==
==delayVariable ($2E)==
one constant parameter
one constant parameter


===Encoding===
===Encoding===
''opcode pointer[16]''
''opcode var''


===Operation===
===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.
var is dereferenced and the current thread suspended for that number of 1/60ths of a second.
 


==divide ($5B)==
==divide ($5B)==
one parameter, uses result
one parameter, uses result


Line 166: Line 348:


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).  
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)==
==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)==
==drawBox ($3F)==
two parameters, does not use result, supplementary opcode byte with three more subsequent parameters
two parameters, does not use result, supplementary opcode byte with three more subsequent parameters


Line 177: Line 366:


===Operation===
===Operation===
Draws a solid box on the backbuffer from (left, top)-(right, bottom) in the colour colour.
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.  
The only part of auxopcode that is relevant are the parameter bits. The rest of the opcode is ignored.  


==drawObject ($05)==
==drawObject ($05)==


==dummy ($67)==
 
==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)==
==endCutScene ($C0)==
===Encoding===
''opcode'''
===Operation===
Ends the cutscene, performing cleanup if necessary.


==equalZero ($28)==
==equalZero ($28)==
Line 198: Line 406:


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


==expression ($AC)==
==expression ($AC)==


==faceActor ($09)==
==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)==
==findInventory ($3D)==
===Encoding===
''opcode result x[p8] y[p8]''


==findObject ($35)==
==findObject ($35)==
===Encoding===
''opcode result x[p8] y[p8]''


==freezeScripts ($60)==
==freezeScripts ($60)==
===Encoding===
''opcode script[p8]''
===Operation===
Freezes given script. Unfreezes all scripts if script is 0.


==getActorCostume ($71)==
==getActorCostume ($71)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the actor's current costume.


==getActorElevation ($06)==
==getActorElevation ($06)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the actor's current elevation.


==getActorFacing ($63)==
==getActorFacing ($63)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the current direction the actor is facing.


==getActorMoving ($56)==
==getActorMoving ($56)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the actor's moving status (0 or 1).


==getActorRoom ($03)==
==getActorRoom ($03)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the room the actor currently occupies?


==getActorScale ($3B)==
==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)==
==getActorWalkBox ($7B)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the actor's walkbox.


==getActorWidth ($6C)==
==getActorWidth ($6C)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the actor's width.


==getActorX ($43)==
==getActorX ($43)==
===Encoding===
''opcode result actor[p16]''
===Operation===
Returns the actor's current X co-ordinate.


==getActorY ($23)==
==getActorY ($23)==
===Encoding===
''opcode result actor[p16]''
===Operation===
Returns the actor's current Y co-ordinate.


==getAnimCounter ($22)==
==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)==
==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)==
==getDist ($34)==
===Encoding===
''opcode result objA[p16] objB[p16]''
===Operation===
Returns the distance between two actors/objects (objA and objB).


==getInventoryCount ($31)==
==getInventoryCount ($31)==
===Encoding===
''opcode result actor[p8]''
===Operation===
Returns the number of items in an actor's inventory?


==getObjectOwner ($10)==
==getObjectOwner ($10)==
===Encoding===
''opcode result actor[p16]''
===Operation===
Returns the owner of an object.


==getObjectState ($0F)==
==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)==
==getRandomNumber ($16)==
===Encoding===
''opcode result seed[p8]''
===Operation===
Returns a new random number based on the given seed.


==getScriptRunning ($68)==
==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)==
==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)==
==ifClassOfIs ($1D)==
Line 260: Line 645:


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


==increment ($46)==
==increment ($46)==
Line 272: Line 658:


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


==isActorInBox ($1F)==
==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)==
==isEqual ($48)==
Line 284: Line 680:


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


==isGreater ($78)==
==isGreater ($78)==
Line 294: Line 691:


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


==isGreaterEqual ($04)==
==isGreaterEqual ($04)==
Line 304: Line 702:


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


==isLess ($44)==
==isLess ($44)==
Line 314: Line 713:


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


==isNotEqual ($08)==
==isNotEqual ($08)==
Line 324: Line 724:


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


==isSoundRunning ($7C)==
==isSoundRunning ($7C)==
===Encoding===
''opcode result sound[p8]''
===Operation===
Returns 1 if sound is running, returns 0 if sound is not running given sound is 0.


==jumpRelative ($18)==
==jumpRelative ($18)==
Line 338: Line 746:


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.  
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)==
==lessOrEqual ($38)==
Line 350: Line 759:


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


==lights ($70)==
==lights ($70)==


==loadRoom ($72)==
==loadRoom ($72)==


==loadRoomWithEgo ($24)==
==loadRoomWithEgo ($24)==


==matrixOp ($30)==
==matrixOp ($30)==


==move ($1A)==
==move ($1A)==
Line 368: Line 782:


Value is moved into result.
Value is moved into result.


==multiply ($1B)==
==multiply ($1B)==
Line 378: Line 793:


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


==notEqualZero ($A8)==
==notEqualZero ($A8)==
Line 388: Line 804:


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


==or ($57)==
==or ($57)==
Line 400: Line 817:


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


==overRide ($58)==
==overRide ($58)==


==panCameraTo ($12)==
==panCameraTo ($12)==


==pickupObject ($25)==
==pickupObject ($25)==


==print ($14)==
==print ($14)==


==printEgo ($D8)==
==printEgo ($D8)==


==pseudoRoom ($CC)==
==pseudoRoom ($CC)==


==putActor ($01)==
==putActor ($01)==


==putActorAtObject ($0E)==
==putActorAtObject ($0E)==


==putActorInRoom ($2D)==
==putActorInRoom ($2D)==


==quitPauseRestart ($98)==
==quitPauseRestart ($98)==


==resourceRoutines ($0C)==
==resourceRoutines ($0C)==


==roomOp ($33)==
==roomOp ($33)==


==saveRestoreVerbs ($AB)==
==saveRestoreVerbs ($AB)==


==setCameraAt ($32)==
==setCameraAt ($32)==


==setObjectName ($54)==
==setObjectName ($54)==


==setOwnerOf ($29)==
==setOwnerOf ($29)==


==setState ($07)==
==setState ($07)==


==setVarRange ($26)==
==setVarRange ($26)==
Line 451: Line 886:


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


==soundKludge ($4C)==
==soundKludge ($4C)==


==startMusic ($01)==
==startMusic ($01)==


==startObject ($37)==
==startObject ($37)==


==startScript ($0A)==
==startScript ($0A)==
Line 476: Line 915:
|P1||Q||F||$0A
|P1||Q||F||$0A
|}
|}


==startSound ($1C)==
==startSound ($1C)==


==stopMusic ($20)==
==stopMusic ($20)==


==stopObjectCode ($00)==
==stopObjectCode ($00)==


==stopObjectScript ($6E)==
==stopObjectScript ($6E)==


==stopScript ($62)==
==stopScript ($62)==


==stopSound ($3C)==
==stopSound ($3C)==


==subtract ($3A)==
==subtract ($3A)==
Line 498: Line 944:


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


==animateActor ($11)==
==animateActor ($11)==


==wait ($AE)==
==wait ($AE)==


==walkActorTo ($1E)==
==walkActorTo ($1E)==


==walkActorToActor ($0D)==
==walkActorToActor ($0D)==


==walkActorToObject ($36)==
==walkActorToObject ($36)==
126

edits

Navigation menu