A look inside The Link @ wiki - User contributions [en]

Riven scripts

2009-05-23T03:05:56Z

BahamutZERO: fixed a typo

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! Event name !! What happened
|-
|0||Mouse down||Mouse button pressed inside the hotspot rect
|-
|1||Mouse still down||Mouse button down, sent to last pressed hotspot (never seen in the game)
|-
|2||Mouse up||Mouse button released inside the hotspot rect
|-
|3||Mouse enter||Mouse entered the hotspot rect (never seen in the game)
|-
|4||Mouse within||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse leave||Mouse left the hotspot rect
|-
|6||Load card||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Close card||Leaving card.
|-
|9||Open card||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display update||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.

==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

Despite its power, command 1 is used on a few scripts only.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. This command has no effect on the active ambient sound group; the sound is mixed with the ambient sounds.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

Refreshes the card, behaving like a "go to <current card>" command. The full handler sequence is executed (see command 2). Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record. A SLST record describes an ambient sound group. The Riven engine can only have one active sound group at any given time (henceforth the "active ambient sound group"). This command sets the active ambient sound group to the specified SLST record. Appropriate fading in and fading out actions are taken based on the SLST record's fade flags. Activating the active ambient sound group has no effect.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Talk:Riven tBMP resources

2009-02-26T07:38:48Z

BahamutZERO:

Aaron, I'm not entirely clear on your recent additions to the tBMP decode algorithms. Are you aware of specific images that exhibit the behaviors you describe to use a test cases, or a decoder implementation which respects those details?

'''[ [[User:TitoDalCanton|TitoDalCanton]] 21:18, 24 February 2009 (CET) ]''' I think I've seen Aaron's effects in some compressed tBMPs. In particular, I recall being surprised by observing duplets repeating themselves, though I don't remember which tBMPs I was inspecting at the time.

'''[ [[User:Aaron|Aaron]] 06:55, 23 February 2009 (CET) ]''' I mean to go back and check specifically for this, but I'm almost completely certain that this is true. Initially, in my algorithm, I used an unsigned integer to represent the number of pixels to look back from where I started, and decremented it each time I copied a pixel. This crippled all my images, and caused weird segfaults when it rolled over after 0. This was fixed when I used a signed integer type (ie let the command copy into newly-written pixels). This is basically an implementation detail, most people would do it a different way where this doesn't matter, or use a signed integer to begin with. [also, I think that pixel-based lookbacks ignore the extra space off the edge, while duplet-based ones do not, but I'm not certain on that. I'll verify that too, but it's too late now.] I didn't realize this was new information, I just thought it was left out.

'''[ [[User:Aaron|Aaron]] 04:21, 24 February 2009 (CET) ]''' OK, I found specific examples. First of all, pixel lookbacks either never happen close enough to new rows to look back into the last row, or they take into account the extra info not in the final image (the bytes per row thing I mentioned in the article), so I'm glad I tried to confirm it before adding it. As for the others, all of these examples are from my original 5-cd riven set, and they're all from b_Data.MHK. tBMPs 99, 101, and 106 (and others) have a higher bytes per row than image width, and only appear correctly when rendered as if they were (bytes per row) wide, then cropped. tBMP 0 (and almost every other compressed image) has many repeat subcommands that ask for more data than there is available at the time. Specifically, byte 165 of the command stream of tBMP 0 is 0xEC followed by 0x08, meaning n = 6 and m = 8, so it needs 12 pixels copied from 8 pixels ago. These images only render correctly when they are allowed to read into themselves. This also happens with repeat command 0xFC. I hope this clarifies things.

'''[ [[User:TitoDalCanton|TitoDalCanton]] 21:18, 24 February 2009 (CET) ]''' I checked my decoder implementation and I can confirm that your interpretation of row bytes is correct. In fact, I decode to a larger buffer (''rowbytes'' pixels wide) and then crop it to ''width'' pixels to get the final image.

'''[ [[bahamutZERO|Jean-Francois Roy]] 23:37, 25 February 2009 (PST) ]''' Thanks everyone for the information. MHKKit also uses a row_bytes * height * bytes_per_pixel for image decoding. If Tito's decoder is "correct", in that it produces correct images, I'll validate MHKKit against it. Perhaps post RGBA checksums for some of those tBMP resources for other people can unit test their decoders. Tito, is the source to maglev that you sent me a while ago still up to date?

Talk:Riven tBMP resources

2009-02-19T19:30:45Z

BahamutZERO: New page: Aaron, I'm not entirely clear on your recent additions to the tBMP decode algorithms. Are you aware of specific images that exhibit the behaviors you describe to use a test cases, or a dec...

Riven scripts

2008-05-05T18:45:34Z

BahamutZERO: /* Command 19: reload card */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! Event name !! What happened
|-
|0||Mouse down||Mouse button pressed inside the hotspot rect
|-
|1||||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse up||Mouse button released inside the hotspot rect
|-
|3||||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse within||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse leave||Mouse leaved the hotspot rect (not sure)
|-
|6||Load card||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Close card||Leaving card.
|-
|9||Open card||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display update||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. This command has no effect on the active ambient sound group; the sound is mixed with the ambient sounds.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable. Based on observations made in Riven X, specifically card jspit 389, the "card load" and "card open" programs should both be re-run by this command. It has not been determined if the "card close" program should be executed as well (e.g. a full card switch sequence).

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record. A SLST record describes an ambient sound group. The Riven engine can only have one active sound group at any given time (henceforth the "active ambient sound group"). This command sets the active ambient sound group to the specified SLST record. Appropriate fading in and fading out actions are taken based on the SLST record's fade flags. Activating the active ambient sound group has no effect.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven SFXE resources

2008-03-27T12:37:10Z

BahamutZERO: /* The header */

{{Riven}}
This document talks about Riven resources controlling where to apply the water special effect.

==What is an SFXE resource?==
SFXE data has to do with the water special effect, which works by taking pixels from the rendered card picture and slightly moving them in periodic motion according to precomputed animation frames. Each frame consists of "displacement commands" that take pixel rows from the original picture and copy them at specified positions over a copy of the same picture. Displacement commands in each frame are arranged in a way that already takes into account periodic motion: the rendering code just loops interpreting frame after frame, blindly copying pixel rows over a copy of the original image.

SFXE data is divided in 4 sections: the header, an unknown and apparently unused section, an offset table and a frame section. The offset table points to frames in the frame section. Everything is in big-endian byte order.

==The header==
First of all comes a 52-byte header:
{| class="structure"
|int8_t||magic[2]
|-
|uint16_t||frame_count
|-
|uint32_t||offset_table_position
|-
| uint16_t ||left, top, right, bottom
|-
| uint16_t ||effect_speed
|-
| uint16_t ||u0
|-
| uint16_t ||alt_top, alt_left, alt_bottom, alt_right
|-
| uint16_t ||u1
|-
| uint16_t ||alt_frame_count
|-
| uint32_t ||u2
|-
| uint32_t ||u3
|-
| uint32_t ||u4
|-
| uint32_t ||u5
|-
| uint32_t ||u6
|}

*''magic'' is the string "SL". Maybe it identifies a known format, but I've found no info;
*''frame_count'' is the number of animation frames;
*''offset_table_position'' seems always 164. Probably it is the position of the offset table relative to the beginning of the resource, which is exactly 52+112=164. Altering this field makes Riven crash.
*''left'', ''top'', ''right'', ''bottom'' define the global rectangle of the effect area within the 608x392 game window. Note that ''right'' and ''bottom'' exceed by 1 pixel (that is, fullscreen SFXE resources have right = 608 and bottom = 392, not 607 and 391);
*''effect_speed'' seems always 15. It controls the speed of the water effect, and seems in units of frames per second;
*''alt_top'', ''alt_left'', ''alt_bottom'', ''alt_right'' is a copy of the previous rectangle. It seems ignored by the engine, changing it doesn't produce effects;
*''u1'' seems always 0;
*''alt_frame_count'' is a copy of frame_count;
*''u2'', ''u3'', ''u4'', ''u5'' seem always 4, 0, 0x19 and 1 respectively;
*''u6'' seems always 0 or 0x10000000;

Altering any of the unknown fields ''u0''...''u6'' produces no apparent change at all, nor makes the engine crash. They look really like a waste of space.

==The unknown section==
This is a 112-byte block of unknown purpose. It seems divided into 8-byte rows, and looks like an encoded mask or a [[Riven tBMP resources|tBMP]] command stream. The values don't change very much between resources and show the same structure. Incredibly enough, altering any of these values doesn't produce observable effects! Well, I've tried only on a few resources, but this behavior is quite disappointing. This data looks like a structure that was discarded in the final version of the engine, but was left in SFXE resources.

==The offset table==
This is just an array of ''frame_count'' unsigned long offsets, relative to the beginning of the resource. Each offset points to a frame in the frame section.

==The frame section==
This section contains ''frame_count'' data blocks, each representing an animation frame. Each block is made of a variable number of commands. Each command is an unsigned short opcode optionally followed by arguments. 3 opcodes have been observed:
*Command 1 has no arguments. It increments ''current_row'' by one pixel; ''current_row'' is a variable that scans the effect area row by row, starting from top. It's used by command 3 to help copying pixel rows. The number of "1" commands inside a frame is equal to the effect area height in pixels, that is, the number of pixel rows affected.
*Command 3 has 4 unsigned short arguments, ''dst_left src_left src_top row_width''. It defines the displacement: take a row of ''row_width'' pixels from the original picture at (''src_left'',''src_top'') and copy it at (''dst_left,''current_row'').
*Command 4 is the last command and ends the frame.

Talk:Riven SFXE resources

2008-03-24T15:21:05Z

BahamutZERO: New page: TIto, I wonder if instead of right and bottom, it should be width and height. It seems odd they would have a one-pixel off situation.

TIto, I wonder if instead of right and bottom, it should be width and height. It seems odd they would have a one-pixel off situation.

Riven scripts

2008-02-23T16:18:34Z

BahamutZERO: /* Command 4: play local tWAV resource */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. This command has no effect on the active ambient sound group; the sound is mixed with the ambient sounds.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record. A SLST record describes an ambient sound group. The Riven engine can only have one active sound group at any given time (henceforth the "active ambient sound group"). This command sets the active ambient sound group to the specified SLST record. Appropriate fading in and fading out actions are taken based on the SLST record's fade flags. Activating the active ambient sound group has no effect.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven scripts

2008-02-23T16:17:03Z

BahamutZERO: /* Command 40: activate SLST record */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. Ambient sounds are not touched; the sound is mixed over them.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record. A SLST record describes an ambient sound group. The Riven engine can only have one active sound group at any given time (henceforth the "active ambient sound group"). This command sets the active ambient sound group to the specified SLST record. Appropriate fading in and fading out actions are taken based on the SLST record's fade flags. Activating the active ambient sound group has no effect.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven scripts

2008-02-23T16:15:24Z

BahamutZERO: /* Command 40: activate SLST record */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. Ambient sounds are not touched; the sound is mixed over them.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record. A SLST record describes an ambient sound group. The Riven engine can only have one active sound group at any given time (henceforth the "active ambient sound group"). This command sets the active ambient sound group to the specified SLST record. Appropriate fading in and fading out actions are taken based on the new SLST record's fade flags. Activating the active ambient sound group has no effect.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven scripts

2008-02-23T16:12:31Z

BahamutZERO: /* Command 3: activate inline SLST record */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST record |command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. Ambient sounds are not touched; the sound is mixed over them.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record, so start ambient sounds. This command seems to have effect just once: it won't restart the same sound if it is already playing (even if the SLST tells not to repeat it). Activating another SLST record works always: the current sound is then stopped and replaced with the new one.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven scripts

2008-02-23T16:11:45Z

BahamutZERO: /* Command 3: play tWAV resource mix */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: activate inline SLST record==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an inline [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if [[#Command 40: activate SLST command|command 40]] had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. Ambient sounds are not touched; the sound is mixed over them.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record, so start ambient sounds. This command seems to have effect just once: it won't restart the same sound if it is already playing (even if the SLST tells not to repeat it). Activating another SLST record works always: the current sound is then stopped and replaced with the new one.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven scripts

2008-02-23T16:10:02Z

BahamutZERO: /* Command 3: play tWAV resource mix */

{{Riven}}
This document talks about the Riven scripting protocol.

==Overview and main data structures==
The Riven engine is programmed using ''scripts'' attached to objects. The architecture resembles the HyperCard philosophy. A script is subdivided in ''handlers''; each handler is associated to an event which may happen to the script's object and it contains the actions to be executed when that event happens. The actions are described by a list of ''commands''. Cards and hotspots are the only entities with attached scripts.

A script is represented by this data block:

{| class="structure"
|unsigned short||handler_count
|-
|variable size||handler list
|}

Each handler is made of this block:

{| class="structure"
|unsigned short||event_type
|-
|unsigned short||cmd_count
|-
|variable size||command list
|}

The following table gives event types identified until now. Types 0 ... 5 are reserved to hotspots, 6 ... 10 are reserved to cards.


{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! event_type !! What happened
|-
|0||Mouse button pressed inside the hotspot rect
|-
|1||Mouse button pressed inside the hotspot rect (never seen in the game)
|-
|2||Mouse button released inside the hotspot rect
|-
|3||Mouse moved, pressed or released inside the hotspot rect (never seen in the game)
|-
|4||Mouse held inside the hotspot rect (the event is sent repeatedly)
|-
|5||Mouse moved inside the hotspot rect (not sure)
|-
|6||Card "loaded". This is the first event sent to a card. Usually cards enable things here. Screen updates are disabled during the execution of this handler, and the display is updated at the end.
|-
|7||Leaving card.
|-
|9||Card opened. This is sent at the end, when the card has been loaded and the display has been updated. Usually cards start movies and ambient sounds here.
|-
|10||Display being updated; for example this event is triggered when the handler for event 6 completes, or by [[#Command 21: enable screen update|command 21]]. The handler is executed before actually updating the display.
|}

In general, each command is an opcode followed by a number of arguments. The same command can be passed a variable number of arguments, though only a few commands actually behave like that. The general structure is:

{| class="structure"
|unsigned short||cmd
|-
|unsigned short||arg_count
|-
|unsigned short||args[arg_count]
|}

The following subsections explain what has been discovered about each command. Unlisted opcodes have never been observed in Riven.
==Command 1: draw tBMP resource==
*'''Argument count:''' 9
*'''Arguments:''' ''tbmp_id left top right bottom u0 u1 u2 u3''

Draw bitmap from tBMP resource ''tbmp_id'' inside the rectangle described by ''left'', ''top'', ''right'', ''bottom''. If the rectangle dimensions do not match the bitmap size, the bitmap will be attached to the top-left corner and clipped to the rectangle. Other arguments are always zero and seem ignored by the engine.

The command will automatically update the display unless [[#Command 20: disable screen update|command 20]] was used before.

==Command 2: go to card==
*'''Argument count:''' 1
*'''Arguments:''' ''id''

Go to card ''id''. In most cases this command is used in very short hotspot scripts containing just a transition command followed by the "go to card" one. In these cases, the following event chain takes place:
*the old card receives [[#Handlers|event 7]];
*the new card receives event 6;
*the new card receives event 10 (because the display is begin updated);
*the transition effect is played and the new card image is displayed;
*the new card receives event 9.

However, it is also used in card event handlers, like 9 or 10. Sometimes it appears multiple times in the same script. The event sequence for these complicated cases is not yet fully understood.

==Command 3: play tWAV resource mix==
*'''Argument count:''' variable
*'''Arguments:''' ''N ids[N] fade_flags loop volume u0 u1 volumes[N] balances[N] u2[N]''

This command is basically an in-code [[Riven SLST resources|SLST]] resource record. All referenced sound resources should be looked-up in the current stack's sound archives. The resulting sound group is made current, as if command 40 had been used.

==Command 4: play local tWAV resource==
*'''Argument count:''' 3
*'''Arguments:''' ''id volume u1''

Play tWAV resource ''id'' from the Mohawk archive containing the script. ''volume'' seems always 256, ''u1'' always 0. Ambient sounds are not touched; the sound is mixed over them.

==Command 7: set variable value==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Set variable ''var'' to value ''value''.

==Command 8: conditional branch==
This doesn't follow the ''command arg_count'' args scheme. It's similar to a C "switch" statement: given a variable, there is a list of possible variable values and a corresponding command list to be executed. The structure of command 8 is:

{| class="structure"
|unsigned short||8
|-
|unsigned short||2
|-
|unsigned short||var
|-
|unsigned short||value_count
|}

Then ''value_count'' blocks follow, each with this structure:

{| class="structure"
|unsigned short||value
|-
|unsigned short||command_count
|-
|colspan="2" style="color:#000"|commands to execute if var contains value
|}

If ''value'' is 0xffff, the block is the "default" block exactly like in the C statement. As an example, let's compare the script syntax with a C-like switch statement:
{| align="center" valign="center"
|
0008 0002 beef 3
0001 0001
a
0002 0001
b
ffff 0002
c
d
|
switch (variable 0xbeef) {
case 1:
a;
break;
case 2:
b;
break;
default:
c;
d;
break;
}
|}

The conditional branch command is used on levers, switches and every place where a variable value makes the difference. It's often used as a simple if-then-else mechanism.

==Command 9: enable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Enable card hotspot with the specified ''hotspot_id''.

==Command 10: disable hotspot==
*'''Argument count:''' 1
*'''Arguments:''' ''hotspot_id''

Disable card hotspot with the specified ''hotspot_id''. A disabled hotspot will not respond to events.

==Command 12==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is 0, 1 or 2. This command is used only a few times, for example near "go to stack" commands like in the "play riven" button. It doesn't seem related to anything special (e.g. movies or sounds). Setting ''u0'' to some other value or replacing the command with others doesn't produce readily observable effects. I suspect it has something to do with variables, but I have yet to realize how to check this.
==Command 13: set mouse cursor==
[[Image:Cursors.png|right|frame|Riven cursor icons and their IDs]]
*'''Argument count:''' 1
*'''Arguments:''' ''cursor''

Set mouse cursor icon to ''cursor'', whose meaning is given on the right.

==Command 14: pause script execution==
*'''Argument count:''' 2
*'''Arguments:''' ms ''u0''

Pause script execution for ''ms'' milliseconds. ''ms'' is signed and the pause is effective only if ''ms'' > 0. ''u0'' is always 0 and its value seems ignored by the engine.

==Command 17: call external command==
*'''Argument count:''' variable, at least 2
*'''Arguments:''' ''cmd count arg1 arg2 ...''

Call an external piece of custom code ("external command"), which is probably hardcoded inside the Riven executable. ''cmd'' tells which external command to call, and ''count'' tells how many arguments to pass to it. Then ''count'' arguments follow. [[Riven NAME resources|NAME]] resource 3 contains the name of each external command: ''cmd'' is the corresponding NAME record index. See the [[Riven external commands|external command list]] for more info on external commands.

==Command 18: transition==
*'''Argument count:''' 1 or 5
*'''Arguments:''' ''code [left top right bottom]''

Schedule a transition effect described by ''code'' (see below for what code means). The transition will actually play when a display update occurs, for example with [[#Command 21: enable screen update|command 21]], [[#Command 39: activate PLST record|39]] or after going to another card (it doesn't seem to work for [[#Command 1: draw tBMP resource|command 1]], however). The optional 4 args ''left'', ''top'', ''right'', and ''bottom'' specify a clip rectangle in pixels, but are never really used in the game.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! code !! Effect
|-
|style="font-family:monospace"|0...15
|Scroll. Bits 0 and 1 control the direction (0=left, 1=right, 2=top, 3=bottom); bit 2 tells if the new image should move (1) or stay fixed (0); bit 3 tells if the old image should move or stay fixed.
|-
|style="font-family:monospace"|16||Dissolve.
|-
|style="font-family:monospace"|17||Seems to behave like 16, rare (t_Data, CARD 155).
|}

Note that Riven uses only transitions from 12 to 17; other effects were discovered by hacking scripts. Maybe there are more.

==Command 19: reload card==
*'''Argument count:''' 0

It's something like "refresh card": it acts like a "go to this card" command. Often used to update the card display after an hotspot script has altered a variable.

==Command 20: disable screen update==
*'''Argument count:''' 0

This seems to disable the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]]. It doesn't work like a "toggle" command: using it multiple times won't re-enable the automatic update (it is re-enabled by command 21 instead). Its effect persists even after the script ends (extending to any successive script, e.g. hotspot ones) but is reset on card switches. Command 20 often precedes [[#Command 18: transition|command 18]].

==Command 21: enable screen update==
*'''Argument count:''' 0

This seems the opposite of [[#Command 20: disable screen update|command 20]]: it re-enables the automatic display update for commands [[#Command 1: draw tBMP resource|1]] and [[#Command 39: activate PLST record|39]], triggers [[#Handlers|event 10]], updates the display and plays the transition effect if one was scheduled before.

Command 21 shows inconsistent behavior if used alone (sometimes it updates the display, sometimes it doesn't, sometimes it skips the transition, etc.); the correct way of using commands 20 and 21 seems to be the following construct, which is also what is usually found in scripts:
#disable screen update
#schedule transition
#activate [[PLST]] records / draw [[tBMP]] resources
#enable screen update

This construct will compose a final picture (by overlaying the specified PLST records and tBMP bitmaps, in the same order as they appear in the script) and then play the specified transition effect from the previously displayed picture to the new one. Note that such a complex effect wouldn't be possible without commands 20/21.

==Command 24: increment variable==
*'''Argument count:''' 2
*'''Arguments:''' ''var value''

Add ''value'' to variable ''var''.

==Command 27: go to stack==
*'''Argument count:''' 3
*'''Arguments:''' ''stack_name code_hi code_lo''

Go to another stack. The destination stack is specified by ''stack_name''; you get the actual stack name string by looking up record ''stack_name'' in [[Riven NAME resources|NAME]] resource 5. The destination card is specified through ''code_hi'' (higher 16 bytes) and ''code_lo'' (lower 16 bytes) which together form an unsigned long [[Riven RMAP resources|RMAP]] card code.

==Command 28==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. It should have something to do with movies: it comes almost always after [[#Command 32: play foreground movie|command 32]] with the same argument. However, changing code or even removing the command itself seem to have no effect neither on the movie nor on anything else. Maybe it purges the memory used by the movie or something like that.

==Command 29==
*'''Argument count:''' 0

Unknown. Seems related to movies since in most cases it comes after [[#Command 32: play foreground movie|command 32]]. Used quite rarely.
==Command 31==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Unknown. Should have something to do with movies, it comes often before [[#Command 33: play background movie|command 33]] with the same argument. Changing code seems to have no effect.

==Command 32: play foreground movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Play a movie listed in the [[Riven MLST resources|MLST]] resource, blocking the script execution until movie ends. code matches the code field of the MLST record that should be played. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead (or nothing will happen at all). If multiple records have that code value, one will be chosen randomly, I guess. Sometimes this command follows [[#Command 33: play background movie|command 33]] with the same parameter: probably it just means "wait until the movie ends" in that case.

==Command 33: play background movie==
*'''Argument count:''' 1
*'''Arguments:''' ''code''

Start a "background" movie from [[Riven MLST resources|MLST]] record with specified code. Script execution will go on (and eventually terminate) while the movie is playing. Often this command follows [[#Command 31|command 31]]. The MLST record must be first enabled with [[#Command 46: activate MLST record|command 46]], otherwise some other random movie will play instead.

==Command 34==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. ''u0'' is always 1.

==Command 36==
*'''Argument count:''' 0

Unknown.

==Command 37==
*'''Argument count:''' 0

Unknown.

==Command 38==
*'''Argument count:''' 5
*'''Arguments:''' ''u1 u2 u3 u4 u5''

Unknown, but should have something to do with movies. ''u1'' seems to refer to a [[Riven MLST resources|MLST]] record code, ''u5'' seems to be a [[Riven SLST resources|SLST]] record index and ''u4'' seems always 40. ''u2'' and ''u3'' seem to form a 32-bit value set to large numbers (4000, 9000...), which I suspect are milliseconds.

This command seems to perform complex actions: if ''u4'' is changed to 0, ''u5'' is interpreted instead as a [[Riven tBMP resources|tBMP]] resource ID and that bitmap is drawn right after the movie.

==Command 39: activate PLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven PLST resources|PLST]] resource, making one of the card bitmaps visible. The actual screen update takes place immediately (with a transition effect, if one was scheduled before) unless [[#Command 20: disable screen update|command 20]] was used before or the command is called from [[#Handlers|handlers 6 or 10]].

==Command 40: activate SLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified [[Riven SLST resources|SLST]] record, so start ambient sounds. This command seems to have effect just once: it won't restart the same sound if it is already playing (even if the SLST tells not to repeat it). Activating another SLST record works always: the current sound is then stopped and replaced with the new one.

==Command 41==
*'''Argument count:''' 1
*'''Arguments:''' ''u0''

Unknown. Should have something to do with movies because it comes often before [[#Command 32: play foreground movie|command 32]] with the same argument. A hypothesis is that it activates a [[Riven MLST resources|MLST]] record like [[#Command 46: activate MLST record|46]], but using its code field rather than the MLST record index.
==Command 43: activate BLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven BLST resources|BLST]] resource, so enable or disable one of the card hotspots (depending on the record info).

==Command 44: activate FLST record==
*'''Argument count:''' 1
*'''Arguments:''' ''record''

Activate the specified record in the [[Riven FLST resources|FLST]] resource, so enable a realtime [[Riven SFXE resources|SFXE]] effect.

==Command 45: do zip mode==
*'''Argument count:''' 0

Find the correct [[Riven ZIPS resources|ZIPS]] record using the hotspot name, get the destination card from the found record and go to that card. Though likely, this behavior has not been confirmed yet.

==Command 46: activate MLST record==
*'''Argument count:''' 2
*'''Arguments:''' ''record u0''

Activate the specified record in the [[Riven MLST resources|MLST]] resource. This command won't actually start the movie; it will only "enable" it for later playing. ''u0'' seems 0 or 1 if the movie is to be played once or looped forever, respectively. This is redundant, since the same info can be found in the MLST record; moreover, ''u0'' seems to be ignored by the engine.

Riven tMOV resources

2008-02-12T14:24:23Z

BahamutZERO:

<noinclude>{{Riven}}</noinclude>
tMOV resources are QuickTime movies. For a complete reference of the format, please see http://developer.apple.com/documentation/QuickTime/QTFF/QTFFPreface/chapter_1_section_1.html.

== Codecs ==

All Riven movies use the Cinepak video codec and the Apple IMA 4:1 audio codec.

Mohawk archive format

2008-02-05T15:56:23Z

BahamutZERO: /* File table */

==General layout==
Mohawk archives are organized in chunks, and this is the chunk layout:
* IFF chunk
** IFF header
** RSRC header
** Resource dir
*** Type table
*** Name tables (one for each resource type)
*** Resource tables (one for each resource type)
*** Resource name list
*** File table
** Actual data (resource contents)
Note that the chunks may be found in a different order: never trust on them being at fixed locations, and use the offsets to reach them.

Every integer is in big-endian (Motorola) byte order.

==IFF header==
This is always at the beginning of the file.
{| class="structure"
|4 bytes||chunk signature (MHWK), identifies Mohawk archive format
|-
|unsigned long||file size in bytes, '''not''' counting this IFF header (that is, file size - 8)
|}

==RSRC header==
I think this is actually the "Resource Dir header". Note that the Dir can be anywhere in file, but this header always follows the IFF Header.
{| class="structure"
|4 bytes||chunk signature (RSRC)
|-
|unsigned long||should be length of RSRC chunk (never bothered to check)
|-
|unsigned long||total file size in bytes
|-
|unsigned long||absolute offset of the Resource Dir
|-
|unsigned short||offset in Resource Dir of the File Table
|-
|unsigned short||File Table size in bytes
|}

==Type table==
It lists resource types in the Mohawk file. This table is always at the beginning of the Resource Dir.

Header:
{| class="structure"
|unsigned short||offset in Resource Dir of the Resource Name List (maybe this should go with the RSRC Header)
|-
|unsigned short||number of resource types in this file
|}

Entry (one for each type):
{| class="structure"
|4 bytes||resource type (tWAV, tBMP, NAME etc.)
|-
|unsigned short||offset in Resource Dir of the Resource Table for this type
|-
|unsigned short||offset in Resource Dir of the Name Table for this type
|}

==Name table==
There is one name table for each resource type. Many types don't have resource names; usually only tBMP, tWAV and tMOV do. Each entry holds the name offset in the name list for a resource.

Header:
{| class="structure"
|unsigned short||number of name entries (can be zero)
|}

Entry:
{| class="structure"
|unsigned short||offset of the name string in Name List
|-
|unsigned short||resource index (equal to the resource's index in File Table)
|}

==Resource table==
Again, there is one resource table for each resource type. The resource table holds crucial information about each resource of this type.

Header:
{| class="structure"
|unsigned short||number of resources for this type (number of table entries)
|}

Entry:
{| class="structure"
|unsigned short||resource ID
|-
|unsigned short||index in file table (starting from 1). Also used to find the matching name table entry
|}

==Resource name list==
This is a simple list of null-terminated strings (C strings), where each string is a resource name. Given a resource, you can get the offset to its name by looking in the name table entry for that resource.

==File table==
This table holds other important data about each resource, notably the location and size of the resource content within the whole Mohawk file. I wonder why this information couldn't go directly inside the resource table entry.

Header:
{| class="structure"
|unsigned long||number of file table entries
|}

Entry:
{| class="structure"
|unsigned long||absolute offset of resource data block
|-
|unsigned short||resource data size, bits 15-0
|-
|byte||resource data size, bits 23-16
|-
|byte||resource flags (unknown)
|-
|unsigned short||unknown (usually zero in Riven files)
|}

It should be noted that the resource data size information is quite often incorrect (at least in Riven archives). One can compensate for this by computing file lengths using the resource offsets.