Saving a User's State from a Shockwave Movie

June 1, 1999
by Mike Weiland

As long as there have been computer games and the like, programmers have been saving the user's current state when their applications are quit. This is so that the next time the user returns, they either automatically start from where they left off or have the option to start a new game. Games have been doing this for decades and Web Based Training (WBT) and Web games created in Shockwave now have the same mechanisms for saving out crucial environment variables into bookmark files to allow the user to return to the exact same location as they left.

If you've played games and were somewhat curious as to how the programmers were able to return you to the exact location with the exact inventory as you had when you quit the night before at 2:30 A.M., then you might have noticed text files saved to your system. These text files are the game's current state files or bookmarks. Upon opening the files in a text editor you will notice a bunch of numbers and text that makes little sense. These text files are what the game uses to return the game state to the way it was left. It does this by reading in the text file and converting the numbers and letters into what the game can understand. Currently, Director can do this for projector deliverables via the FileIO Xtra. Using the FileIO Xtra you can save and open your bookmark files. Unfortunately, Shockwave cannot use the FileIO Xtra as it opens too many security holes, so the fine engineers at Macromedia came up with the setPref and getPref commands for Shockwave. (These commands happen to work for projector files as well.)

The setPref command will take a string that you pass it and save it to the user's hard drive with the file name that you also pass to the setPref command. The setPref command does not have the power to write the preference file to anywhere except the Prefs folder inside the Plug-In Support folder of the browser. This way a malicious Shockwave can not overwrite system files. Also, the setPref command can only save text files with the .TXT or .HTM extensions.

Doing just the opposite, the getPref command will read in the file that is passed to it. If the file does not exist it returns VOID. Like the setPref command, the getPref command can only read in a text file with a .TXT or .HTM extension. There is no need to specify a path for the file to be read, getPref automatically assumes that the file will be residing in the Prefs folder.

In this exercise we will create a simple behavior to store the entry of a field named "NameField" into our preference file. Start by creating a new Director movie and put an editable field on the stage and name it NameField. Next put a button on the stage and type Create Bookmark as the title of the button and create a behavior with this (to create a new behavior open the Behavior Inspector from the Window Menu and click on the + . Select New Behavior. Name your new behavior Create Bookmark..):


on mouseUp me
  setPref "DOUGexample.txt", the text of field "NameField"
end

Save and run your sample from your browser. Enter your name and press the Create Bookmark button. On the outside nothing seemed to happen. Locate your Prefs folder and open the DOUGexample.txt file (Default PC location: C:\WINDOWS\SYSTEM\MACROMED\Shockwave\Prefs, default Mac location: Macintosh HD:System Folder:Extensions:Macromedia:Shockwave:Prefs). The first line of the DOUGexample.txt file should be the name that you entered.

We now have to get the contents of the DOUGexample.txt file into our Shockwave movie. This is where the getPref command comes in handy. Create a new button and title it Get Bookmark. Create a new behavior with this script to the button:


on mouseUp
  set bookmark = getPref( "DOUGexample.txt" )
  alert "The bookmark contains:" && bookmark
end

Save and run your movie in a browser. Press the Get Bookmark button, an alert should pop-up with the text "The bookmark contains:" and the name you typed into the field in the previous example. Let's move on to something a little more complex.

Create a new Director movie. Place this script into a Movie Script (to create a new Movie Script, find a blank cast member in your cast and click on it to select it, choose Script from the Window Menu):


on prepareMovie
  global gX, gY 
  -- X & Y coordinate values for the circle
  
  -- see if there is a bookmark
  set bookmark = getPref( "DOUGexample2.txt")
  
  if bookmark = VOID or bookmark = EMPTY then
    -- No bookmark was found
    set gX = 160
    set gY = 120
  else
    -- Bookmark found, parse the bookmark file
        -- convert the string value to an integer
    set gX = value( line 1 of bookmark )
    set gY = value( line 2 of bookmark )
  end if
  
end

The prepareMovie above will read in the preference file into the variable bookmark. It then checks to see if there is a bookmark. If no bookmark is found than it manually sets the global variables gX and gY. If a bookmark file is found, then it sets gX and gY to the values that were saved in the file.

Next create a bitmap circle, place it on the stage and attach this behavior to the newly created circle:


global gX, gY
on beginSprite me
  set the loc of sprite the spriteNum of ¬
    me = point( gX, gY )
end
on mouseDown me
  repeat while the mouseDown
    set the loc of sprite the spriteNum of ¬
      me = point( the mouseH, the mouseV )
    updateStage
  end repeat
  set gX = the locH of sprite the spriteNum of me
  set gY = the locV of sprite the spriteNum of me
  
end

The mouseDown handler makes the circle moveable when the mouse button is pressed and the cursor is moved. The beginSprite handler sets the circle to the global variables gX and gY. The values for gX and gY are set in the startMovie handler. Now create a "Create Bookmark" button with the script of:


global gX,gY
on mouseUp me
  setPref "DOUGexample2.txt", gX & RETURN & gY
end

Save this movie and play it in your browser. Move the circle around the screen and press the Create Bookmark button. Move the circle again to another spot on the screen and click the Refresh button in your browser, this will force the Shockwave to restart. When it restarts the circle is placed in the spot where it was when you pressed the Create Bookmark button.

This should get you started with enough knowledge to create a bookmarking system for your Shockwave movies. There are many possibilities with a bookmark file, like saving the frame the user was on when they exited or answers that they typed. There are a few things to watch out for. There is no way to delete a preference file that you create in the Prefs folder. What I do is write out an EMPTY bookmark file if nothing is bookmarked. Another caveat is the naming convention that you use for your bookmark files. If you name your bookmark file bookmark.txt and if I also name my bookmark file bookmark.txt, then there is potential for confusion! Try to make your bookmark files as unique as possible or create a unique key as the first entry in the bookmark file. If the first line does not match your unique key, then you know it is not your bookmark.

Sample movies are available for download in Mac or PC format.

Mike Weiland is the Director of Technology for Wasatch Interactive Learning, an educational software company in Salt Lake City, UT. He can be reached at mike@wasatchnet.com, website http://www.wasatchnet.com/.