Cosmic Osmo - Revolution converts
by Jacqueline Landman-Gay
Cosmic Osmo
Cosmic Osmo is a commercial HyperCard game created by Cyan Worlds, the makers of the Myst series. Cosmic Osmo was, in fact, the inspiration for Myst and was one of the very earliest in the adventure game genre. It is an expansive universe of discovery, charm, and whimsey spanning nine different worlds where surprises happen with every mouse click. Cosmic Osmo won high accolades when it was released for Macintosh, and recently Cyan decided to bring the Osmo adventure to Windows users too. Since my company specializes in HyperCard conversions, Cyan contacted HyperActive Software to do the port to Windows.
Revolution was an easy choice for Cyan. Not only does Revolution support virtually all HyperTalk syntax, but it can automatically import, convert, and run HyperCard stacks as well. This capability allowed all the stack structures, controls, images, custom cursors, and icons to be immediately transitioned without any effort at all; any other development environment would have required rebuilding all the object structures from scratch. In addition, almost 90% of the code base could be used without alteration, saving a tremendous amount of time and resources. This was a big consideration, since Cosmic Osmo consists of hundreds of cards contained in 22 stacks, several hundred animated movies, almost 1500 sound files, a handful of embedded "mini" games (including a very amusing spin-off of a breakout game,) and five custom XCMDs written in C++. Rewriting all of that in any other language would have been prohibitive and expensive.
Even with 90% of the conversion done automatically by Revolution, the other ten percent represented a fair investment of time and resources, and provided a few challenges.
ship
Use the ship's warp drive to visit all the Osmo worlds. While you travel you can play music on the working tape deck or dial the phone to call other characters, though if you get a wrong number you'll have to listen to the operator and you may get stuck on hold.
Challenges in the Other 90%
XCMD Conversion
The first requirement was to rewrite the aging HyperCard XCMDs as native Revolution handlers. This was relatively simple for the most part; the only reason XCMDs were used in the first place was because of HyperCard's limited animation capabilities and the slower speed of early CPUs. Revolution's native feature set allowed easy conversions of these XCMDs, and speed is not an issue with Revolution's very fast engine. Without exception, dozens of lines of C++ code translated to only a few lines of script in Revolution. The code compression was quite amazing and the resulting handlers ran faster than the original HyperCard XCMDs. We were able to convert all the original XCMDs to Revolution scripts successfully.
The primary XCMD challenge was in rewriting a very old Director XCMD called "playmovie". This was a complex task but Revolution handled it very well and the result was a handler that accepted all the original parameters and performed exactly as the older XCMD did. This compatibility was important, because almost every card in Cosmic Osmo contains at least one animation, and often more. The goal was to keep the original XCMD syntax intact to cut down on conversion costs as much as possible. The XCMD rewrite, which eventually became a handler also named "playMovie", allowed all the existing calls to work just as they did in the HyperCard version, eliminating the need to change hundreds of lines in the original scripts. Revolution performed very well with this.
Animation challenges
The ancient Director animations used by the original "playMovie" XCMD had to be converted to another format for use in Revolution. We opened and exported them from Director, saving each movie as an image sequence in PICT format. The PICT sequences were then converted to animated GIF files, each of which was individually tweaked for performance and cropped as small as possible. Our converted playMovie handler played back these GIF files as needed. However, some of the GIFs were by necessity still very large and loading them on demand proved to be too slow for a smooth interactive experience. Cosmic Osmo requires immediate feedback when a user clicks on an object, and waiting for an animation to load, even briefly, wasn't acceptable.
To solve the problem we contracted with Runtime to create a custom external that could display any frame of an animation instantly on demand. The new external uses a proprietary, compressed file format, which meant that all the GIFs had to be converted yet again, but this was easily automated with a Revolution script and took only a few minutes. The PlayMovie handler was then revised to use the external, looping through frames in sequence, and the speed problem was solved.
We also gained several other advantages by changing to this method. First, almost 20 megabytes of GIF animations were reduced to only 3.3 megabytes in the new format. In addition, the animations were now protected; users could not pull them from the folder and use them outside the program. And finally, we gained the ability to adjust the playback speed via script, simply by passing a parameter that specified the wait between frames inside the playback loop.
Singing Pots
Click a pot and move the mouse to make them sing. The original had no tonal boundaries. After conversion, three octaves are available, which covers the area of the card but not beyond.
Sound and audio issues
Cosmic Osmo is a rich environment filled with sounds and audio feedback, and sound files comprised the bulk of the resource forks in the HyperCard stacks. We exported the sound resources from each HyperCard stack and bulk-converted them to AIFF files. This wasn't a particularly difficult task, and was the only thing necessary for these resources. A custom "playSnd" handler calculates the file location on disk and plays back the audio.
However, Cosmic Osmo contains many sound sequences that are generated dynamically using HyperCard's ability to play scripted musical notation. Tonal variations were often generated depending on various user actions; for example, the flower pots at the top of the castle sing "la la" at different frequencies depending on how the user moves the mouse. Revolution does not have the ability to play scripted note sequences, so some adjustments were necessary. While my company did sponsor a utility that provides scripted musical notation, it only works with the QuickTime instrument set, and Osmo requires custom sounds as "instruments." After some discussion with Cyan, we decided to record as many variations of the scripted music as possible and save them as AIFF files. The scripts were changed to choose an appropriate pre-recorded sound at runtime. While this did somewhat limit the range of audio output in a few cases, there was enough variation that only the most dedicated Osmo fans would notice.
One other adjustment was needed for sound playback. There are many instances where related sound clips are played back sequentially. In HyperCard, simply issuing the "play" command multiple times will automatically queue sounds and play them one after the other without any pause. Revolution does not provide sound queueing, so we wrote a handler to simulate this behavior. The handler checks at frequent intervals to see if the current sound is done and whether there is another sound in a variable that serves as a waiting queue. If so, the next file is played immediately. The result was nearly identical to HyperCard's built-in capability, though occasionally there may be a brief stutter in playback if other actions are occurring simultaneously.
Sink
Fill the sink, wash the dishes, pop the soap bubbles, or...take a trip down the drain.
Script issues
Revolution's excellent compatibility with HyperTalk meant that there were very few scripting issues. Almost all the original scripts ran exactly as they should. (Indeed, the biggest issue was the fact that I had to examine the scripts of thousands of objects, usually only to find that no changes were necessary.) In some cases, I decided to leave less efficient constructs in place, simply to save time and because they ran acceptably well. In other cases, a rewrite was done to either increase compatibility or to cut down on CPU usage. Mainly this involved changing "idle" handlers (of which there were many,) repeat loops (especially those that tracked the mouse position,) and background processes that repeated at intervals. These were changed to use local script variable flags and "send [command] in [time]" or "mouseMove" constructs, which enhanced both performance and reliability. I found that idle handlers in particular were not as dependable in Revolution as they were in HyperCard, as Revolution apparently dispenses with "idle" if anything else is happening. Substituting all instances of "idle" gave a dramatic improvement.
Study
Osmo's pipe puffs smoke randomly and he turns the pages of his book at intervals. If you poke him, he'll respond. You can write your own books and add them to the bookshelf, or toss them in the fireplace where they go up in flames. The musical instruments let you use a working tape deck to record and play back your own tunes.
The Revolution advantage
The conversion to Revolution provided some enhancements automatically without any programming effort at all. The biggest of these was the marked increase in speed of script execution, which makes Cosmic Osmo highly responsive to user input and gives a very realistic feel to the game. Revolution's smooth response gives the impression that you're really there, interacting with real objects. It is easy to lose yourself in the experience. (Even while I was programming it, I found myself reacting to Professor Osmostein as though he were a real component during a game of Blitzlifter.)
Revolution's excellent image handling also allowed us to add a certain surprise to the program which would have been impossible in HyperCard. I'd like to tell you what it is, but you'll have to follow the clues in the game to find out.
Of course, the most important advantage was the very reason Cyan chose Revolution in the first place: the ability to distribute what was once a Macintosh-only program to Windows users.
Cosmic Osmo is currently in the final stages of testing, and will be released on GameTap soon for download. There are currently no plans to re-release a Macintosh version, though if that should change it would be trivial to recompile the main stack for OS X, which is all that would be required.
If you are interested in converting your own HyperCard stacks to Revolution, HyperActive Software provides a tutorial at our web site which covers the most common issues you'll want to consider.
And if you are interested in writing an adventure game like Cosmic Osmo, there is no better vehicle than Revolution. Let the games begin!
Hyperactive
Jacqueline Landman Gay of HyperActive Software began working with scripting languages over 20 years ago with HyperCard's first release, and now works almost exclusively in Revolution, her programming environment of choice.
