David I. Bell
February 15, 1998

Mac OS X Port

Ron Hayter

[Note: Except in this paragraph, every "I" in this document is David speaking. David spent many hours learning about saved Riven games and writing the original RivHack. He deserves all the credit for this program. I (Ron) merely spent a few minutes porting his program and adapting his instructions to Mac OS X. Thanks, David!]

[Update (2012-06-20): Riven stopped working as of Mac OS X 10.5 (Leopard). For the adventurous, there are ways to revive Riven on recent versions of OS X, perhaps the best of which is Riven X. Riven X, however, does not (yet?) support Riven's saved game files, so cannot be used with RivHackMac.]

Download RivHackMac.


RivHackMac is a Mac OS X program to display or modify values from a saved Riven game. It is a trivial port of the original Windows version. The combinations to the domes, telescope, and prison cell are easily shown, as is the player's position in the game. The states of many other variables in the game are also shown, such as the ladder in the lagoon being lowered.

All of the displayed values can also be modified. This enables you to change the combinations, open the doors, and teleport yourself to any point in the game.

Great fun can be had by modifying the state of the saved game in ways that are illegal in normal game play. This results in interesting effects when the game is resumed. Several saved games are supplied to demonstrate these.

Firstly, I wish to thank the creators of Riven for producing such a beautiful and interesting game. I have had much fun playing it, looking at it, and now hacking and understanding it!


RivHackMac is a simple program without a graphics interface. The source to the program is provided, as is a pre-built executable made from that source. You need to run it in a Terminal window so that you can type the appropriate command lines to it.

The interaction between Riven and RivHackMac is simple (but cumbersome, I admit). First, copy RivHackMac into the folder where Riven has been installed, for example, into /Applications/Riven. Start Terminal (in the /Applications/Utilities folder) and set the current directory to Riven's folder by typing:

cd /Applications/Riven

If you have the CD version of Riven, you can also copy the 3 included .rvn files into Riven's folder. Unfortunately, these saved game files are not compatible with the DVD version of Riven.

Next, select a file name that you want to use to communicate between Riven and RivHackMac, start Riven, and save the game to that file name. Then click at the top of the display to make the menu bar visible, type Command-Tab to switch to the Terminal window, and start RivHackMac using the command:

RivHackMac filename.rvn -prompt

where filename.rvn is the saved file name. The RivHackMac program will then enter its interactive mode, and you can supply commands to it to display or modify the values in the filename.rvn file. After you have made some changes you wish to apply, use Command-Tab to switch back to Riven, then use Riven's File menu to Open the changed filename.rvn file. The RivHackMac program opens and closes the saved file for each command, so changes are immediately applied.

You can switch back and forth as necessary between Riven and RivHackMac. Just remember to Save the game in Riven before examining values in RivHackMac, and then Open the saved file again after making changes using RivHackMac. (If you had only displayed values using RivHackMac, you can just continue playing Riven after saving the file.) If you had changed the position in the saved game to a different island, Riven will prompt you to change the CD as normal.

You can alternatively run RivHackMac one command at a time from Terminal, supplying the filename as necessary for each command. When doing this, the commands are prefixed with a dash, as shown on the usage line. This form of execution might be useful when you want to manipulate values from multiple save files, or use the program from within a shell script.


The following commands are available to RivHackMac:

listvar, listpos, show, set, pos, dome, quit, help.

The listvar command displays the list of all of the Riven variable names that are known to the RivHackMac program, or just those variable names which contain any of the specified list of words either in their names or in their descriptions.

For example, the command:

listvar door gate

describes variables that contain the words "door" or "gate" somewhere in their name or description.

Variables are either global, or are specific to an island. Island-specific variables have names beginning with a single letter and a dash, as follows:

Temple Island t-
Jungle Island j-
Boiler Island b-
Spike Island s-
Prison Island p-
Moiety Island m-
Gehn Island g-

Variables are printed as decimal values. Boolean values have the values 0 or 1. State variables have values 0, 1, 2, 3, and so on. A few values are encoded in more complicated ways (e.g, dome combination, stones lowered, telescope combination.) The initial value of most variables is 0. Dumping all of the variables of a saved file right after starting the game will show you the initial values of the variables.

The listpos command shows all of the positions that have been entered specially into the RivHackMac program, or just those positions which contain any of the specified list of words either in their name or in their description. For example, the command:

listpos office

describes a position having to do with Gehn's office on Boiler Island. Positions encode the island and location (including viewpoint) of the player. Most positions which are near to interesting things are present in the table. As with variables, the positions start with a single letter and a dash to identify the Islands that the positions are on.

The show command will display the values of the specified Riven variable names, or all of the variable values if no names are supplied. For example, The command:

show t-dome-spin j-dome-spin b-dome-spin s-dome-spin p-dome-spin

will show which of the domes are spinning and which are stopped.

The set command will change the values of the specified variables to have the specified values. Arguments to the command come in pairs, where the first argument is the variable name and the second argument is the decimal value. No range checking is performed on the values. For example, the command:

set j-ladder 1

will set the ladder in the lagoon on Jungle island to be lowered.

The pos command is used to display or set the position of the player. A position is composed of two variable values, the island number and the island location. This command is just a shortcut method of setting these two variables together. If no argument is given, the current location of the player is displayed, both as numeric values and (if known) as a named position. If an argument is given, the position is set to the specific named position, which is one of those listed by the listpos command. (Unlisted positions can be set by changing the island-num and island-pos variables directly using the set command.)

The dome command is used to display or set the combination to the domes. If no arguments are given, the combination to the domes is displayed as five decimal numbers. If arguments are given, they must be the five numbers of the combination to be set, and must be legal. This command is just a shortcut method of referencing the dome-comb variable. You can set illegal dome combinations by using the set command directly.

The quit and help commands are used to quit from the program, or to describe a very quick summary of the commands.

Riven Notes

I have deduced some of the inner workings of Riven while using this program. But other parts of the game are still obscure, and may never be known to those without access to the Riven sources or developers.

The save file seems to consist of two parts. The first part of the file contains a number of variables, each at a pre-defined offset. The second part of the file has an unknown purpose to me, but might be some sort of history buffer of locations visited in order to support the zip feature.

The values used in the RivHackMac program were obtained by the slow process of setting up a situation in the Riven game, saving the game, performing just one action, saving the game again into another file, and then comparing the two saved games. If I was lucky, then just one byte in the files differed, and so I assumed that this byte encoded the result of the action I performed. In this way, the offsets of the state of various switches, doors, and so on was found.

Some values which I would like to know change many locations in a single action, and so I was not able to decode them. Fortunately, these are rare, and are unimportant or only occur right near the end of the game. Examples of this are the flag which enables the lady underground in Spike Island to appear and run away, and the flag which indicates that Catherine has been released from her prison.

Most values are stored in 16 bit words, starting at even offsets in the file. But the range of most values is small, and so one of the two bytes in a word is always zero. The values I know of are only a small subset of the space used in the save file. I have no idea what stuff is stored in the rest of the save file, if anything.

Boolean values have the values 0 or 1. Multi-valued values usually have states starting from 0 and running upwards to the highest state used. The great majority of the states are set to 0 when the game starts. A few values start in nonzero states. You can start a new game, save it, and list all the variables to see what the initial states are.

Luckily the Riven save file is not encrypted or checksummed. So it can be freely modified without the game detecting anything wrong. Because of this, you can have fun creating situations which are unknown in normal play.

I haven't tried to see what happens when a variable is given a illegal value. I assume that either the game will simply act as if some particular legal value was present, or else will crash. Which of these events occurs is probably dependant on the variable, according to how its usage was programmed in the game. Maybe something really miraculous can happen, but I don't know.

More interesting things result in the combinations of variable values, each of which is individually legal, but where the combination is illegal. I have three saved games which demonstrate the strange effects you can get from this process. (Unfortunately, these games almost exhaust the possibilities too, since Riven's puzzles are not too complicated.)

There are several important concepts to know about how Riven works. Firstly, there is no "physics" in the game. Do not think that the game simulates a universe, and so has logic which calculates how something should "behave", or be affected by other things. It doesn't do this. Instead, it is just a big state machine. If the game is in a certain state, and you prod the mouse in a particular location on the screen, then some fixed code changes the state in a particular way. That's all that happens.

An example of this lack of physics is that when the submarine is lowered, it somehow magically passes through the extended platform below it, and ends up at the bottom of the lagoon underneath the platform. In reality, perhaps this would break the platform. But since there is no physics, there is no interaction between these two objects. The sub just changes from being raised to being lowered, and is the result of just one state variable changing from 0 to 1.

The second important thing to remember is that there is no "motion" of the player. All of those nice looking rides and lifts are illusionary. are are in fact no more different than simply taking one step. The only extra feature of the rides is that a movie is played between the old and new positions of the player. Typing the space character to terminate a movie makes this clearer.

Steps and turns are no different from each other, and are no different than the rides, or using the books. The bottom line is that the game is dependent on the player's "position", which is a number which identifies grossly what the player can see and do at a particular point in the game. A position corresponds to a particular "view" by the player. Like in a real movie made up of individual frames which are independent of each other but which happen to be shown in a particular sequence, in Riven the player moves through individual positions which are independent of each other but which can only be reached in particular sequences. So one position being "near" or "far" from another position is totally irrevelant. It is only in your own mind that the player travels a short way, turns, looks up, looks down, or is magically teleported to another island. To the game, all position changes are the same.

The player's position is encoded using two variables. The first one is the island number, and the second one is the position within that island. The game uses the island number to determine which CD needs to be inserted into the drive. So when you change positions, and the island number changes, the program will eject the old CD and ask for the new one to be inserted. This is convenient, since you can teleport between islands from any point to any other point, and the CD's will be changed normally. (The game could have been coded to only change CD's at the legal island changing positions such as when a ride was used.)

The final important thing to remember is that the picture you see and the actions you can perform at a particular position are dependent on the state of the variables, but NOT on all of them at any particular position. The game designers only check variable values in the situations in which they can affect the display or actions of the player. The views you see are those which have been rendered according to the set of variables which are legal for that view. The game CANNOT show you a "correct" view in situations in which you can't get to in normal play. This is where the fun comes in in playing modified Riven save files, to see wierd effects occur as you move around.

For example, many doors in Riven shut themselves automatically when you move away from them. This is not just a convenience for the player. More importantly, it limits the number of different views that must be rendered and stored. As an example of this, the front gate to the jungle is initially closed, and can only be opened when you are right next to it. As soon as you move away from the location where you opened it, the gate shuts. Because of this, there are only two views that had to be rendered showing the gate opened. From a distance, the gate is always shut. Therefore, distant views of the gate can ignore whether or not the gate is opened, since in normal play the gate must be shut at those positions.

By using the RivHackMac program, you can force the gate to be opened even when you are not next to it. The strange effect this causes is that as you walk up to the gate, it looks closed. But as soon as you come up next to the closed gate, it magically seems to disappear. This is because only in that close view is the open/shut status of the gate used to select the proper view. As you walk away from the gate, it shuts normally and then appears properly from then on.

The state of the rides in Riven is strange, and once again shows the lack of "physics" in the game. The floating cars which connect the Islands do not have a real location. Instead, flags simply indicate whether or not the car appears present at each island. Because of this, a car might appear to be on both islands, or on neither island, depending on how the state is changed. Moving from one island to another simply involves moving the player position, clearing the present flag from the source island, and setting the present flag from the destination island.

Some rides don't use flags, and are always magically present. One example of this is the cart ride from Temple to Jungle Island. No matter which end of the track you get to, the cart is there waiting to take you to the other end. Similarly, the underwater cage lift on Spike Island is always ready to take you from underground to above ground.

The submarine does have a position, but this position is only used to select the view from outside it and to indicate whether or not you can enter the sub from a particular platform. It is possible to teleport to any position that the sub can be at, and the sub will "be there" ready for you to control it and will run correctly. Being on the sub is no different to the game than simply being on a path somewhere and taking a step. It is just another change of position along with the playing of a nice looking movie between the positions.

The view you have at a particular position, the differing ways to change the views (such as using the mouse on a handle), and the movies between positions, combine to create a powerful illusion that something "real" and "physical" is going on. As a powerful example of this, the lift in the idol does not exist. It is just three positions that can be gotten to by using the handle. I tried several times to find the location in the save file which stored the "position" of the idol lift, but it doesn't exist! The lift in the idol is always there at your level when you need it.

There are a few variables in Riven which are not saved explicitly in the save file, but which are generated from other values in the save file. During play, they can then be modified by the player, but the modifications are lost if the game is saved and restored. Fortunately, the number of such variables is small. The best example of this I know of is the power source for the books in Gehn's hideout. Once Gehn is captured, you can turn off and on the power source to enable and disable the books. But if you save the game and restore it, you will find that the power is always turned on again. This variable is set depending on whether Gehn has been captured, and is not an independent variable. So you can't have fun by trying to enable the books before Gehn first arrives.

The game also "cheats" slightly. You can determine what the combination is to Cathherine's prison, and teleport yourself to the lock for the cell, but the combination will not work. It only works once Gehn has been captured. (Most unfair:) So there was never any point trying to guess the combination in legal play and trying to release her before capturing Gehn.

The code which selects the view for a position, and the code which selects the actions allowed to the player at a position, appear to be independent of each other. That is, the selection of a view does not directly select the actions allowed to a player. In almost all cases this isn't apparent. But there is one place which this distinction is visible. The door on the boiler can be either shut or opened, and the water inside can be either boiling or calm. The normal game doesn't have a case where the water is boiling and the door is opened. If you create this situation, though, then an interesting fact is discovered. The view shows the door as shut and the indicator as red, because the selection of the view first notices that the water is boiling, and so the door MUST be seen as shut. But the mouse handling logic ignores the boiling water flag, and only checks whether the door is opened. So you can click on the door area in the view, and enter the boiler through the closed door. Everywhere else in the game the view and the available actions appear to match.

Finally, there are a few locations in the game which are actually dynamically "rendered". For these cases, the game seems to overlay smaller pictures on top of the main picture to create the final view. This is necessary when the number of possible static views is obviously to many to be practical. The best example of this is the fire beads. There are many possible positions for the beads, and so the program has to manually draw each bead over the main picture. Other examples of this are the dome combination locks, and the stones in the stone room. Actually, almost all of the differing views in the game could be done in the same way by overlaying smaller pictures over a base picture. This would save room on the CD-ROM. But the number of possibilities isn't too large in most cases, and so individual rendered full views could be stored. It doesn't really matter for the purposes of this program.

Stone Room Fun

I have supplied a modified game which demonstrates some fun with the stone room behind the prison in Jungle Island. It is called stonefun.rvn, and can be played by simply opening it in Riven. It starts by being in the stone room looking at the linking book to the hidden Moiety village. Do NOT use the book, but instead leave and go outside. If you want the most fun, stop reading this section and simply play it slowly and carefully, and notice the strange effects which occur.

When you turn around and leave the book, and then look back, the book will have vanished, and the water will be back on the the wall covering it.

Many more stones in the room will be down than is normally allowed, and they aren't the ones that enabled the book to be shown.

When you walk down the hall, the door in the passage to the stone room will be opened, and the lights will be on in the passage beyond. But as soon as you pass through the door, the lights will go out, and the door will be shut.

As you head to the secret sliding door behind the prison, it will be shut as you expect. But as soon as you get close to it, it will instantly spring open so that you can pass through.

When you enter the prison room, the room will be empty and the door to the outside will be open, and the grate in the floor will be closed. But when you look closely at the grate, it will instantly spring open.

When you walk outside through the round prison door and turn around, the door will be instantly closed, and the prisoner will be lying inside the prison.

Finally, you will notice that you are up on the walkway, but the trapeze is opened and the ladder is pulled up, so you could not have gotten up there in the first place.

Boiler Fun

I have supplied a modified game which demonstrates some fun with the boiler in Boiler (or Paper) Island. It is called boilerfun.rvn, and can be played by simply opening it in Riven. It starts by being at the end of the pipe from the boiler looking out over the ocean. Do NOT climb down out of the pipe, but turn around and go back to the boiler. If you want the most fun, stop reading this section and simply play it slowly and carefully, and notice the strange effects which occur.

As you go back through the pipe, it is nice and empty and dry, even when you leave the pipe and first enter the boiler. The platform is raised off of the bottom of the boiler. You can look all around and see the empty boiler below the platform. But when you climb the ladder, all of the sudden the boiler is full of calm unboiling water, and you can't go back down.

When you turn around, the boiler door is closed. As you get next to it, the door opens, and you can then walk through it. When you turn around, the door is instantly shut, and the tube is red indicating that the water inside is boiling.

Even though the door is shut, try to go through it, and you can! Then you will be inside again to see the calm unboiling water filling the boiler, and the platform raised. When you turn around again, the door is opened, and you can go through it again. You can go back and forth through the open/shut door as often as you wish.

If you move away from the door on the outside, you hear it close and you can't go back through it anymore. When you go to the boiler controls, you can see the water inside is boiling, and the platform is lowered.

Door Fun

I have supplied a modified game which demonstrates some fun with the doors and other objects in Riven. It is called doorfun.rvn, and can be played by simply opening it in Riven. It starts at the normal starting point in the game. Just play normally, but notice the occasional weird effects. If you want the most fun, stop reading this section and simply play it slowly and carefully, and notice the strange effects which occur.

Doors and gates will magically spring open when you get near them. Inside Gehn's office on Boiler Island, many items will magically change as you examine them.

Frustrating Fun

I haven't supplied modified games which demonstrate dead-ends in the game, but you can easily create them yourself. Here are several examples which I haven't tried, and which might not actually work:

  • You can retract the platform for the submarine, so that it is useless. For example, you can retract the platform at the Control station, so that there is no way to extend the playform needed to get up the Trapeze cage.
  • You can be positioned on the walkway between the big dome on Temple Island and the back door of the rotating room, but having the walkway lift lowered and the inner door closed.
  • You can be on Prison Island, with the fire beads powered off.
  • You can set an illegal combination so that something won't unlock.