Riven external commands

Riven scripts make use of "external commands" to perform complex actions. External commands are code blocks living outside Mohawk files (hence "external"); probably they are part of the engine executable itself. Many complex devices in the game are implemented with external commands (for example the domes and the fire marbles puzzle); this is bad news because no reverse-engineering can be done on them easily. An alternative engine would have to implement custom code for those devices.

This is the first step in understanding the role of each external command. This list has been put together by looking into NAME 3 resources, which store external command names used within each stack. Arguments have been found or guessed by reading scripts.

Each command is reported in a way similar to C functions: command_name(argument1, argument2...). Names without trailing '()' have not yet been investigated.

a_Data

xastartupbtnhide()

Used in the main menu card. Hides the "setup" (or "play riven") button by filling the hotspot rectangle with black and disabling the hotspot.

xasetupcomplete()

Called when clicking the "continue" button in the "volume adjustment" card.

xaatrusopenbook()

Called after loading Atrus's journal card.

xaatrusbookback(), xaatrusbookprevpage(), xaatrusbooknextpage()

Called when clicking hotspots in Atrus's journal card.

xacathopenbook()

Called after loading Catherine's journal card.

xacathbookback(), xacathbookprevpage(), xacathbooknextpage()

Called when clicking hotspots in Catherine's journal card.

xtrapbookback(), xatrapbookclose(), xatrapbookopen()

Called when clicking hotspots in the trap book card.

b_Data

xblabopenbook()

Called by the display update handler of card 278 (Gehn's lab journal). It must display the correct picture since the script doesn't.

xblabbooknextpage(), xblabbookprevpage()

Called by two hotspots of card 278 (Gehn's lab journal). They must handle the correct variable (probably blabbook) and update the display accordingly, since the script does nothing.

xsoundplug()

Called by several cards in their load handler (e.g. card 282, 284, 286, 288, 289).

xbchangeboiler(a,b)

Used by hotspots in cards 282 and 284 when acting on the boiler controls. It can have one or two args, both taking small numbers (1 to 4).

xbupdateboiler()

Used by hotspots in card 284 when acting on the boiler controls. The command is invoked towards the end of the scripts. Among other things it probably reloads (or redraws) the card to reflect the updated controls, as the scripts don't.

xbsettrap()

Called by the open handler for card 372 if the expression (bytramtime==0 && bytrap==1 && bbait==1) is true.

xbcheckcatch(a)

Called by the open handler for card 372 if bytramtime is not 0. a is 0.

xbait()

Triggered by mouse down events in the bait (card 372).

xbfreeytram()

Called when opening the ytram trap in card 372, if bytrapped is 1. Probably it just needs to play the movie showing the escaping ytram.

xbaitplate()

Triggered by mouse down events in the bait plate (card 372).

xbisland190_opencard

xbisland190_resetsliders

xbisland190_slidermd

xbisland190_slidermw

xbscpbtn

xbisland_domecheck

xvalvecontrol()

Reacts to mouse movements to let the user control the steam valve at the center of the lake (card 415). It must set variable bvalve accordingly.

The mouse tracking algorithm looks very complicated.

xbchipper()

Called by the chipper lever hotspot (card 498) when the steam is correctly directed to the chipper. It must play the MLST record with code=2. Why an external?

g_Data

xflies(u0, u1)

Start the "flies" realtime effect. u0 seems always 0, u1 is a small number (< 10).

The effect is quite complicated as it randomly moves "flies", which look like tiny icons, around the card. Depending on parameters, their number seems to vary and different kinds of flies may be introduced (e.g. blinking ones).

xgresetpins()

xgrotatepins()

xgpincontrols()

xgisland25_opencard()

xgisland25_resetsliders()

xgisland25_slidermd()

xgisland25_slidermw()

xgscpbtn()

xgisland1490_domecheck()

xgplateau3160_dopools()

xgwt200_scribetime()

xgwt900_scribe()

xgplaywhark()

xgrviewer()

xgwharksnd()

xglview_prisonoff()

xglview_villageoff()

xglviewer()

xglview_prisonon()

xglview_villageon()

j_Data

xflies(u0, u1)

See g_Data.

xjplaybeetle_600

xjplaybeetle_950

xjtunnel103_pictfix

xreseticons()

Called by an hotspot in card 191. Probably it resets the rebel puzzle icons.

xicon(a)

Called by the load handler for some cards (e.g. 246, 247, 248).

xcheckicons(), xtoggleicon(a)

Called by hotspots in cards belonging to the rebel puzzle icons (e.g. 217, 220, 221, 222...). Maybe a is an icon ID.

xjtunnel105_pictfix(), xjtunnel106_pictfix(), xjtunnel104_pictfix()

Called by display update handlers for cards 216, 219 and 229 respectively. Probably they "fix" the picture by drawing the pressed icons.

xvga1300_carriage()

Called by an hotspot in card 277.

xjdome25_resetsliders

xjdome25_slidermd

xjdome25_slidermw

xjscpbtn

xjisland3500_domecheck

xhandlecontroldown()

Called when clicking on the handle inside the jungle elevator, when the elevator is at the top. It must track mouse movements, play the elevator movie and set involved variables.

Apparently, the algorithm is triggered by a single mouse movement, directed towards the bottom.

xhandlecontrolmid()

Called when clicking on the handle inside the jungle elevator, when the elevator is at ground level. It must track mouse movements, play the elevator movie and set involved variables.

Apparently, the algorithm is triggered by single mouse movements, directed towards the top or the bottom.

xhandlecontrolup()

Called when clicking on the handle inside the jungle elevator, when the elevator is underground. It must track mouse movements, play the elevator movie and set involved variables.

Apparently, the algorithm is triggered by a single mouse movement, directed towards the top.

xjplaybeetle_1450()

Called in the load handler for card 372.

xjplaybeetle_1050()

Called in the load handler for card 408.

xjplaybeetle_550

xjlagoon700_alert()

Called by the open handler for card 627. It handles the sunner reaction to the player presence.

xjlagoon800_alert()

Called by the open handler for card 629. It handles the sunner reaction to the player presence.

xjlagoon1500_alert()

Called by the open handler for card 632. It handles the sunner reaction to the player presence.

xschool280_playwhark()

Called when using the whark toy in the school (card 769). It must take care of playing the correct movies and all. Apparently it uses the jwharkpos variable to know the toy position.

o_Data

xorollcredittime()

xooffice30_closebook()

xbookclick(movie_sref, start_time, end_time, u0)

xobedroom5_closedrawer()

xogehnopenbook()

xogehnbookprevpage()

xogehnbooknextpage()

xgwatch()

p_Data

xpisland990_elevcombo(button)

xpscpbtn()

xpisland290_domecheck()

xpisland25_opencard()

xpisland25_resetsliders()

xpisland25_slidermd()

xpisland25_slidermw()

r_Data

xrcredittime()

Called in the open card handler for card 2. It must handle the scrolling credits and everything after that.

xrhideinventory()

Called by the mouse down handler of a hotspot covering the whole screen (card 11).

xrshowinventory()

Called by the mouse down handler of the journal hotspot in card 11.

xrwindowsetup()

Called in the load card handler for card 21.

t_Data

xtexterior300_telescopedown(), xtexterior300_telescopeup()

Called when hitting the telescope button in card 137. Which external will be called depends on the state of variable ttelehandle (0→up, 1→down). The externals must

• inspect ttelecover, ttelepin, ttelescope, ttelevalve and ttelehandle
• increment/decrement ttelescope if needed
• play the correct movie span and the correct sound
• take care of playing the ending sequence if the variables are set correctly.

xtisland390_covercombo(button)

Called when clicking the telescope cover buttons. button is the button number (1...5).

xtatrusgivesbooks(), xtchotakesbook(), xthideinventory()

Called in this sequence in the "open card" handler for card 155, which is where the intro movie sequence takes place.

xt7500_checkmarbles()

Called by the waffle activation button (card 221). It must check that the fire-marbles are placed correctly and set apower to 1 if this is the case, 0 otherwise.

xt7600_setupmarbles()

Called on display update of card 223: it must draw the marbles at the correct locations in the waffle plate. This is not trivial since prespective must be applied! The marble icons are located in separate tBMP resources (IDs 526-531 in the CD version).

xt7800_setup()

Called in load handler of card 225. Probably it takes care of moving the marble hotspots to the right locations.

xdrawmarbles()

Called on display update of card 225. Probably it takes care of drawing the waffle plate with the marbles at the right locations.

xtakeit()

Called by marble hotspots in card 225, on mouse down. It must track mouse movements until mouse up, determine the new marble location, set any involved variable and load the card.

xtscpbtn()

Apparently it must only play the dome scope button movie.

xtisland4990_domecheck()

Used in the dome scope button click handler to determine if the button was hit at the right time. Sets variable domecheck to 1 if this is the case.

xtisland5056_opencard()

Called when opening card 386. It must display the slider to reflect its actual settings.

xtisland5056_resetsliders()

Called when hitting the dome button or closing the card (all in card 386). It must play the "slider reset" animation (with the ticking sound), bring back the sliders and maybe other things.

xtisland5056_slidermd(), xtisland5056_slidermw()

Both called by an hotspot laid over the whole dome slider, in its mouse down and mouse within handlers respectively (card 386). They must track mouse movements, play the ticking sound, set the slider value accordingly and enable/disable the two hotspots laid over the dome button if the combo is correct or incorrect.