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

Mohawk Bitmaps

2009-11-28T10:27:21Z

Tahg: /* RLE8 Compression */ edited for clarity

{{Myst}}
{{Riven}}
All observed Mohawk games use a common bitmap format, besides Myst (which uses [[WDIB]] and [[Myst PICT resources|PICT]] images). Mohawk bitmaps are always stored with a tBMP tag. All values are in big endian order. tBMP resources are divided into three chunks: the header, the palette, and the image. Note that the palette is not always present (such as non-Riven 8bpp images and Riven 24bpp images).

== Bitmap Header ==
{| class="structure"
|unsigned short||bitmap width
|-
|unsigned short||bitmap height
|-
|unsigned short||bytes per row
|-
|unsigned short||compression details
|}

* ''bitmap width'' is the width of the bitmap in pixels.
* ''bitmap height'' is the height of the bitmap in pixels.
* ''bytes per row'' is the pitch of the image (bytes in a scan line).
* For ''compression details'', see the next section.

'''Note''': Both ''bitmap width'' and ''bitmap height'' are only valid for the bottom 10 bits (val & 0x3ff, in C). ''bytes per row'' is also the same, but has to remain even (val & 0x3fe, in C).

=== Compression Details ===
''compression details'' is split up into different sections, depending on their purpose.

==== Bits 0-2 (Bits Per Pixel) ====
The lower three bits represent the images' bit depth. It is chosen from this table.

{| border="1"
|- style="background:silver"
|Value||Bits Per Pixel
|-
|0||1
|-
|1||4
|-
|2||8
|-
|3||16
|-
|4||24
|}

Other values are undefined.

==== Bit 3 (Palette) ====
Bit 3 represents whether or not a palette will occur. However, this is very unreliable, as Riven never has this bit set. If the game is Riven, and the bit depth is 8, you should assume there is a palette.

==== Bits 4-7 (Secondary Compression) ====
Bits 4-7 represent the secondary compression on the image.

{| border="1"
|- style="background:silver"
|Value||Secondary Compression
|-
|0||None
|-
|1||RLE8
|-
|3||Another (still unknown) RLE variant
|}

For none, the image is raw pixels. However, there are ''bytes per row'' bytes per row, so you have to skip remaining bytes at the end of the row. In Riven, there is always no secondary compression. On the contrary, in almost all other games' images, the compression is RLE8.

==== Bits 8-11 (Primary Compression) ====
Bits 8-11 represent the primary compression on the image.

{| border="1"
|- style="background:silver"
|Value||Secondary Compression
|-
|0||None
|-
|1||LZ
|-
|2||Another (still unknown) LZ variant
|-
|4||Riven
|}

For none, there is nothing to do at this stage. See details later for the LZ and Riven compression schemes.

== Palette ==
While bit 3 should represent whether a palette exists or not, all 8bpp Riven images have a palette regardless. The palette starts with a short header:

{| class="structure"
|unsigned short||table_size
|-
|byte||bits_per_color
|-
|byte||color_count
|}

* ''table_size'' is the size of the table, including the four byte header.
* ''bits_per_color'' is the bits that each color is (seems to be always 24)
* ''color_count'' is the amount of colors that the table contains (seems to be always 0xff)

Following the header is ''color_count'' blocks:

{| class="structure"
|byte||blue_component
|-
|byte||green_component
|-
|byte||red_component
|}

== Image ==

The rest of the tBMP resource is made up of the image. To decode the image, you must first use the primary decompression and then the secondary decompression to have the correct output image.

=== Primary Decompression ===

If the image has no primary decompression you can skip this step.

==== LZ Decompression ====

The stream consists of two parts, the header and the compressed data.

===== LZ Header =====

{| class="structure"
|unsigned long||uncompressed_size
|-
|unsigned long||compressed_size
|-
|unsigned short||dictionary_size
|}

* ''uncompressed_size'' is the size of the data after decompressing.
* ''compressed_size'' is the size of the data before decompressing.
* ''dictionary_size'' is the size of the ring buffer to use in the decompressor. However, it is '''''always''''' 0x400, and if it's not 0x400, it should be thrown out.

===== LZ Compression =====
Thanks to Petroff Heroj and Ron Hayter for working out this compression.

Until the end of the resource, each run begins with a byte. Each bit of this byte defines what to do next, starting from the least significant one.
* A 1 means an absolute byte follows. Read a byte from the compressed data and store it directly into the uncompressed buffer.
* A 0 means a length/offset pair follows. Read two bytes ''b1'' and ''b2'' from the compressed data. The most significant 6 bits of ''b1'' represent the length of the run minus 3. The 2 least significant bits of ''b1'' and the whole ''b2'' form together a 10-bit offset into the ring buffer, minus 0x42. At this point copy ''length'' bytes from the ring buffer, starting at ''offset'', to the uncompressed buffer. If ''offset'' is over 0x400 make sure to subtract 0x400 after adding the 0x42, i.e. loop around to the beginning of the ring buffer.
The ring-buffer should be initialized to all zeroes. Remember to store the uncompressed bytes in the ring buffer as well, looping to the beginning after 0x400 bytes.

For example:
<pre>
0xf7 // decoder byte (11110111b)
0x87 // absolute byte
0x73 // absolute byte
0x27 // absolute byte
0x0b // byte 1 of the run data: length = 2 + 3 = 5 (first 6 bits + 3)
0xa9 // byte 2 of the run data: offset = 0x3a9 + 0x42 = 0x3eb
0x27 // absolute byte
0x32 // absolute byte
0x00 // absolute byte
0x4e // absolute byte
</pre>

==== Riven Decompression ====
In compressed tBMP bitmaps, pixels are encoded as a data stream made of variable length commands. Pixels are always decoded in duplets: each command generates at least 2 pixels. The encoding is heavily based on what comes before each command, so even a little decoding bug can cripple the whole image. The commands can appear in any order inside the data stream. The first 4 bytes of the data stream are unknown and can be ignored. Many thanks to Arthur Muller for his precious help in decoding this format.

Like the uncompressed format, sometimes duplets are generated beyond the edge of the image. Use the ''bytes per row'' value to see how many duplets are in each row.

===== Main Commands =====

They are all 1-byte commands, followed by a variable number of arguments.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! Command !! Action
|-
|style="font-family:monospace"|0x00||End of stream: when reaching it, the decoding is complete. No additional bytes follow. I think some bitmaps don't have this, so just stop when you have decoded enough pixels to fill the image.
|-
|style="font-family:monospace"|0x01 -0x3f||Output ''n'' pixel duplets, where ''n'' is the command value itself. Pixel data comes immediately after the command as 2*''n'' bytes representing direct indices in the 8-bit color table.
|-
|style="font-family:monospace"|0x40-0x7f||Repeat last 2 pixels ''n'' times, where ''n'' = ''command_value'' & 0x3F. No additional bytes follow.
|-
|style="font-family:monospace"|0x80-0xbf||Repeat last 4 pixels ''n'' times, where ''n'' = ''command_value'' & 0x3F. No additional bytes follow.
|-
|style="font-family:monospace"|0xc0-0xff||Begin of a subcommand stream. This is like the main command stream, but contains another set of commands which are somewhat more specific and a bit more complex. This command says that ''command_value'' & 0x3F subcommands will follow. It doesn't generate pixels itself.
|}

===== Subcommands, part 1: arithmetic operations =====
Subcommands are not simply 1-byte values, but are somewhat mixed with their arguments, so the full byte pattern is reported.
{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! Command !! Byte pattern !! Action
|-
|style="font-family:monospace"|0x01-0x0f
|style="font-family:monospace"|0000mmmm
|Repeat duplet at relative position -''m'', where ''m'' is given in duplets. So if ''m''=1, repeat the last duplet.
|-
|style="font-family:monospace"|0x10
|style="font-family:monospace"|0x10 p
|Repeat last duplet, but change second pixel to ''p''.
|-
|style="font-family:monospace"|0x11-0x1f
|style="font-family:monospace"|0001mmmm
|Output the first pixel of last duplet, then pixel at relative position -''m''. ''m'' is given in pixels.
|-
|style="font-family:monospace"|0x20-0x2f
|style="font-family:monospace"|0010xxxx
|Repeat last duplet, but add ''x'' to second pixel.
|-
|style="font-family:monospace"|0x30-0x3f
|style="font-family:monospace"|0011xxxx
|Repeat last duplet, but subtract ''x'' to second pixel.
|-
|style="font-family:monospace"|0x40
|style="font-family:monospace"|0x40 p
|Repeat last duplet, but change first pixel to ''p''.
|-
|style="font-family:monospace"|0x41-0x4f
|style="font-family:monospace"|0100mmmm
|Output pixel at relative position -''m'', then second pixel of last duplet.
|-
|style="font-family:monospace"|0x50
|style="font-family:monospace"|0x50 p1 p2
|Output two absolute pixel values, ''p1'' and ''p2''.
|-
|style="font-family:monospace"|0x51-0x57
|style="font-family:monospace"|01010mmm p
|Output pixel at relative position -''m'', then absolute pixel value ''p''.
|-
|style="font-family:monospace"|0x59-0x5f
|style="font-family:monospace"|01011mmm p
|Output absolute pixel value ''p'', then pixel at relative position -''m''.
|-
|style="font-family:monospace"|0x60-0x6f
|style="font-family:monospace"|0110xxxx p
|Output absolute pixel value ''p'', then (second pixel of last duplet) + ''x''.
|-
|style="font-family:monospace"|0x70-0x7f
|style="font-family:monospace"|0111xxxx p
|Output absolute pixel value ''p'', then (second pixel of last duplet) - ''x''.
|-
|style="font-family:monospace"|0x80-0x8f
|style="font-family:monospace"|1000xxxx
|Repeat last duplet adding ''x'' to the first pixel.
|-
|style="font-family:monospace"|0x90-0x9f
|style="font-family:monospace"|1001xxxx p
|Output (first pixel of last duplet) + ''x'', then absolute pixel value ''p''.
|-
|style="font-family:monospace"|0xa0
|style="font-family:monospace"|0xa0 xxxxyyyy
|Repeat last duplet, adding ''x'' to the first pixel and ''y'' to the second.
|-
|style="font-family:monospace"|0xb0
|style="font-family:monospace"|0xb0 xxxxyyyy
|Repeat last duplet, adding ''x'' to the first pixel and subtracting ''y'' from the second.
|-
|style="font-family:monospace"|0xc0-0xcf
|style="font-family:monospace"|1100xxxx
|Repeat last duplet subtracting ''x'' from first pixel.
|-
|style="font-family:monospace"|0xd0-0xdf
|style="font-family:monospace"|1101xxxx p
|Output (first pixel of last duplet) - ''x'', then absolute pixel value ''p''.
|-
|style="font-family:monospace"|0xe0
|style="font-family:monospace"|0xe0 xxxxyyyy
|Repeat last duplet, subtracting ''x'' from first pixel and adding ''y'' to second.
|-
|style="font-family:monospace"|0xf0 and 0xff
|style="font-family:monospace"|0xfx xxxxyyyy
|Repeat last duplet, subtracting ''x'' from first pixel and ''y'' from second.
|}

===== Subcommands, part 2: repeat operations =====

Sometimes these repeat commands will try to copy more than what is available when the command is read. In those cases, the command repeats the available segment of data until the number of duplets needed is copied. Or, equivalently, the command starts copying data that it wrote earlier.

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! Command !! Byte pattern !! Action
|-
|various
|style="font-family:monospace"|1x1xxxmm mmmmmmmm
|
{| border=1 cellspacing=0 style="float:right;border:none;border-collapse:collapse;padding:0px 3px;"
|- style="background:#CCC"
! Command !! n !! r
|-
|style="font-family:monospace"|0xa4 - 0xa7||2||0
|-
|style="font-family:monospace"|0xa8 - 0xab||2||1
|-
|style="font-family:monospace"|0xac - 0xaf||3||0
|-
|style="font-family:monospace"|0xb4 - 0xb7||3||1
|-
|style="font-family:monospace"|0xb8 - 0xbb||4||0
|-
|style="font-family:monospace"|0xbc - 0xbf||4||1
|-
|style="font-family:monospace"|0xe4 - 0xe7||5||0
|-
|style="font-family:monospace"|0xe8 - 0xeb||5||1
|-
|style="font-family:monospace"|0xec - 0xef||6||0
|-
|style="font-family:monospace"|0xf4 - 0xf7||6||1
|-
|style="font-family:monospace"|0xf8 - 0xfb||7||0
|}
Repeat n duplets from relative position -''m'' (given in pixels, not duplets). If ''r'' is 0, another byte follows and the last pixel is set to that value. ''n'' and ''r'' come from the table on the right.
|-
|style="font-family:monospace"|0xfc
|style="font-family:monospace"|0xfc nnnnnrmm mmmmmmmm (p)
|Repeat n+2 duplets from relative position -''m'' (given in pixels, not duplets). If ''r'' is 0, another byte ''p'' follows and the last pixel is set to absolute value ''p''.
|}

=== Secondary Decompression ===
In all Riven images, and some other images, there is no secondary decompression. Instead, the remaining data is just the pixels. For 24bpp images, the pixels are in BGR order. For 8bpp images, there are ''bytes per row'' pixels, so you will have to cut off the remaining bytes at the end of the data (''bytes per row'' - ''bitmap width'').

However, many non-Riven images use the RLE8 compression.

==== RLE8 Compression ====
The RLE8 compression is a rather simple form of RLE. The decoder works by decoding one row at a time, so there will be ''bitmap height'' chunks of data. Each chunk '''''always''''' decodes one row of data.

Per Row:

{| class="structure"
|unsigned short||byte_count
|}

* ''byte_count'' is the amount of bytes that will be used to decode the current row.

The ''byte_count'' should be ignored until later. Until you have completed a row's length of pixels, you must continue decompressing the RLE data.

Each RLE command starts with a byte. The high bit of the data represents whether or not to repeat a pixel or output direct pixels. The bottom 7 bits are the ''run_length'' minus one.

If the high bit is set, read in another byte which represents the pixel to repeat and then output the pixel ''run_length'' times. If the high bit is not set, output ''run_length'' absolute pixels from the input stream.

Once you have outputted the correct amount of pixels, you should move ''byte_count'' bytes from the start of the row in the compressed stream.

Riven debug shell

2009-06-08T00:08:23Z

Tahg: fixed help command

The original Riven engine features a built-in debug shell with useful capabilities.

It can be activated by typing the string b3hn in the game and then pressing ctrl+tab. A green prompt should appear in the bottom left corner of the game window. This prompt accepts several commands, listed below. After each command the prompt disappears, but it comes out again by just pressing ctrl+tab.

* g <id>: go to card <id>
* gc <id>: go to card, using its RMAP identifier
* gs <stack> [<id>]: go to stack <stack> (e.g. tspit) and to card <id>, if specified
* get <variable>: get the value of a variable
* set <variable> <value>: set the value of a variable
* undo: undoes actions on cur card (autosave must be enabled)
* enable <id>: enable an hotspot
* disable <id>: disable an hotspot
* p: purges all purgeable blocks
* c: compacts entire heap
* pc: purges, then compacts
* mem: returns total free memory
* free: returns physical free memory (excludes virtual)
* debug: toggles a line with useful debug info
* hs: toggle hotspot display
* autosave: toggles autosave-every-card feature
* dump: saves the current card picture to a bmp file
* ipmm: toggles impatient PM mode
* slideshow: show the images from b2_data.mhk with captions
* pleh: shows the list of commands available (They don't make this easy do they)

See also the [http://www.mystcommunity.com/board/lofiversion/index.php/t19142.html original source].

Riven VARS resources

2009-06-05T13:37:18Z

Tahg: updated type field

<noinclude>{{Riven}}</noinclude>
The VARS resource is found in Riven saved game files (there is just one). It stores the state of every game variable. The data is just an array of 12-byte records, each representing a variable, with this structure:
{| class="structure"
|unsigned long||u0||
|-
|unsigned long||type||class="comment"|0 = unknown, 1 = integer
|-
|unsigned long||value||class="comment"|Saved variable value
|}

''u0'' starts from 2, and seems to grow when going on with the game.

Fortunately, saved games contain a [[Riven NAME resources|NAME]] resource that labels most variables in the VARS resource. The VARS record index simply matches the NAME one.

The number of records is not constant. If you save different games in different places then new records will appear, usually with ''u1'' = 0 and strange values. However, "known" variables (dome combination, telescope levers state etc) are always at the same record.

Riven scripts

2009-05-23T17:19:00Z

Tahg: /* Command 18: transition */

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

<span id="Handlers"></span>
{| 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"
! !!width="19%"|Left!!width="19%"|Right!!width="19%"|Up!!width="19%"|Down
|-
!style="background:#CCC"|Wipe||0||1||2||3
|-
!style="background:#CCC"|Scroll||4||5||6||7
|-
!style="background:#CCC"|Scroll Away||8||9||10||11
|-
!style="background:#CCC"|Pan||12||13||14||15
|-
!style="background:#CCC"|Blend||colspan="4"|16, 17(only seen on t_data, CARD 155)
|}

Notes:
Types 0 - 15 are various types of scrolling. 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.
Riven uses effects 0 to 3 internally for turning pages. It uses effects 12 to 16 in scripts. Effect 17 is the same case as effect 16.

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

Riven engine overview

2009-05-23T00:19:46Z

Tahg: added trap book card switch

{{Riven}}

A Riven scenario is made of virtual objects called ''stacks'' and each stack is a list of virtual objects called ''cards''. This may remember HyperCard: it's the same approach. Each card has an associated ''script'', a sequence of commands to be executed in response of events happening to the card (for example, card creation). The player interacts with the game by means of invisible buttons, placed within cards and called ''hotspots''. Hotspots have associated scripts too, responding to events different than cards (for example, mouse clicks). Within cards can also be placed bitmaps and movies. Finally, sounds can be played.

Riven stacks are named
*aspit (main menu, books, setup screens)
**a_Data.mhk
**a_Sounds.mhk
*ospit (Gehn's office)
**o_Data.mhk
**o_Sounds.mhk
*pspit (prison island)
**p_Data.mhk
**p_Sounds.mhk
*gspit (garden island)
**g_Data.mhk
**g_Sounds.mhk
*rspit (rebel age)
**r_Data.mhk
**r_Sounds.mhk
*tspit (temple island).
**t_Data.mhk (Riven 5CD/Demo)
**t_Data1.mhk, t_Data2.mhk (Riven DVD)
**t_Sounds.mhk
*jspit (jungle island)
**j_Data.mhk (Riven Demo)
**j_Data1.mhk, j_Data2.mhk (Riven 5CD/DVD)
**j_Sounds.mhk
*bspit (boiler island)
**b_Data.mhk
**b_Sounds.mhk

Physically, a stack is described by a set of data blocks called ''resources''. Resources are identified by a 4-char ''type'' and an integer ''ID''. Optionally they can also have a name, but it seems completely ignored by the engine. The resource type tells what kind of data is stored in the resource; see the [[Riven_resources|resource type list]] for types used in Riven.

Resources belonging to a certain stack are archived inside an arbitrary number of [[Mohawk_archive_format|Mohawk files]] (listed above under their respective stacks). The file "riven.cfg" tells which files compose each stack by associating stack and file names.

Saved games are Mohawk archives too, and they contain additional resource types as described in the [[Riven_resources|resource type list]].

The Riven engine has a secret, interesting [[Riven_debug_shell|debug shell]].

==Notes on stack switching==
The current stack can be changed from scripts using [[Riven scripts#Command 27: go to stack|script command 27]]. For example, when the player activates a MagLev, first the car movie is played, and then command 27 is called to change the current stack to the new island. This command is also used in the "Play Riven" button. However, most linking books actually change stack simply by moving to another card which has no buttons and no scripts. Apparently, there is some hardcoded mechanism inside the engine which triggers the stack change when one of these "special" cards is entered. These cards are listed here.

=== CD Version ===
{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! Stack !! Card ID !! Target stack !! Target card
|-
|bspit||447||ospit||1
|-
|gspit||178||ospit||1
|-
|jspit||228||rspit||3
|-
|jspit||344||ospit||1
|-
|ospit||58||pspit||43
|-
|ospit||62||jspit||341
|-
|ospit||67||gspit||175
|-
|ospit||72||bspit||444
|-
|ospit||76||tspit||387
|-
|pspit||46||ospit||1
|-
|rspit||13||jspit||215
|-
|tspit||392||ospit||1
|}

=== DVD Version ===
{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! Stack !! Card ID !! Target stack !! Target card
|-
|aspit||8||ospit||9
|-
|bspit||447||ospit||1
|-
|gspit||178||ospit||1
|-
|jspit||228||rspit||3
|-
|jspit||343||ospit||1
|-
|ospit||58||pspit||43
|-
|ospit||62||jspit||340
|-
|ospit||67||gspit||175
|-
|ospit||72||bspit||444
|-
|ospit||76||tspit||393
|-
|pspit||46||ospit||1
|-
|rspit||13||jspit||215
|-
|tspit||398||ospit||1
|}

== Stack ID's in Saved Games ==
In saved games, the "[[Riven variables#currentstackid|currentstackid]]" variable holds what the current stack is by a number. This table shows what stack each number represents:

{| border=1 cellpadding=4 cellspacing=0 style="border:1px #000 solid;border-collapse:collapse;"
|- style="background:#CCC"
! ID !! Stack
|-
|1||ospit
|-
|2||pspit
|-
|3||rspit
|-
|4||tspit
|-
|5||bspit
|-
|6||gspit
|-
|7||jspit
|-
|8||aspit
|}

Such association seems to be defined in the Riven.ini file, in particular from its "StackNumber" section.

Riven scripts

2009-05-18T14:55:09Z

Tahg: updated mouse events

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

<span id="Handlers"></span>
{| 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||Mose 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.