Collector Game Status Test

October 24, 1999
by Pat McClellan

Dear Multimedia Handyman,

I am creating a game based on your article called Lists for Item collection in a Game . Is there a way to create an alert dialog box, eg. alert "good job", if you have successfully put all the item in the list?

Steven

Dear Steven,

No sweat! There are lots of situations where you need to periodically check the user's status to figure out if they've completed a task or series of tasks. The Lingo is easy to do, but it's important to think about the process. Specifically, the questions are these:

When do we need to check the status?
Which of the possible states lead to which consequences?

Lingo is "event based", which means that things happen based on certain cues. For example, when the play head moves from one frame to the next, several "events" happen: exitFrame, prepareFrame, and enterFrame are three obvious events. You can take advantage of those events by attaching instructions to them, which get executed when the event happens. These three events happen automatically, but many events are user driven, such as mouse events like mouseDown/mouseUp and keyboard events like keyDown and keyUp.

In this game demo I created for the previous article, items are collected by clicking on them. Therefore, this mouse event is probably the best place to insert the status test. Note that the convention is to use the mouseUp (instead of mouseDown) event for things like this. That allows for the possibility that the user might mouseDown on an object or button, change her mind and roll off of the button before the mouseUp. In this case mouseUp events attached to that object or button would not execute. (You would use mouseDown events for situations where the user needs to drag an object or where you need to store the mouseDown location and compare it to the mouseUp location.)

Now that we've decided to put the status test on the mouseUp event attached to each object, let's figure out what the status test must evaluate. In the demo above, I set it up so that there is a property list stored in a global variable called myList. When the movie starts (prepareMovie event), the list is initialized like this:

on prepareMovie
  global myList
  if voidP(myList) then
    initializeList
  end if
end prepareMovie
on initializeList
  global myList
  set myList = [#key:0, #flask:0, #potion:0, #cloak:0, #gold:0]
end initializeList

Each of the items that you can collect are included as properties in the list, and the initial values associated with each of these items is 0. When you click on an item, the value for the corresponding item in the list is set to 1, or in the case of #gold, you can set that to any value you want. For this first example, that's irrelevant.

I can set up a simple status test that goes through each item in the list, checking to see if the value of that item is zero. As soon as the status test encounters a zero value, then we can stop the test immediately and exit the handler. However, if we make it through the entire list without happening upon a zero, then we know that all of the items are collected and we can trigger our own custom event called "gameWinner". Here's what the status test behavior looks like (attach it to all of the sprites which can be collected.)

-- statusTest (simple)
-- copyright © 1999, ZZP Online, LLC
-- free use for DOUG readers

global myList
on mouseUp me
  howManyItems = myList.count
  
  repeat with whichItem = 1 to howManyItems
    if myList[whichItem] = 0 then
      exit
    end if
  end repeat
  
  gameWinner me
  
end mouseUp
on gameWinner me
  alert "Good job!"
  -- do whatever else (reset game?)
end

Notice that the command "gameWinner me" is in the mouseUp handler and it is not inside of an if-then statement. Why doesn't it get executed everytime the mouseUp handler executes? Because of the command "exit". I'm testing for the negative situation; I'm checking to see if any of the items are NOT collected. If I encounter any item which is NOT collected (has a value of 0), then the command to exit the handler is executed before the gameWinner command.

That takes care of the simplest status test. But what if we want to make if more complex. For example, what if you only get the good job message if you've collected all the non-monetary items and accumulated exactly 13 pieces of gold (out of a possible 15 pieces). Now, testing the gold property in the list becomes more complex. We can't just test to see if it is NOT 0. We'll need to evalute the actual value and make sure that it is not 13, else we'll exit before calling gameWinner. Let's do that by simply adding another condition to our previous statusTest.

A sample movie in available for download in Mac or PC format. This is a Director 7 movie.

-- statusTest (with gold)
-- copyright © 1999, ZZP Online, LLC
-- free use for DOUG readers
global myList
on mouseUp me
  howManyItems = myList.count
  
  repeat with whichItem = 1 to howManyItems
    if myList[whichItem] = 0 then
      exit
    end if
  end repeat
  
  if myList.gold <> 13 then
    exit
  end if
  
  gameWinner me
  
end mouseUp
on gameWinner me
  alert "Good job!"
  -- do whatever else (reset game?)
end

In this case I've hard-coded the value for the gold to 13, but you could change that to be a property which is set in the getPropertiesDescriptionList. That way you could re-use it with different values each time.

You can include many other conditions in your status test. For example, if you've included some kind of a quiz in your game, they might need a score which is greater than a specified amount. Or you could add a time limit. The possibilities are infinite, but the concept is the same. Good luck with your game.

Patrick McClellan is Director Online's co-founder. Pat is Vice President, Managing Director for Jack Morton Worldwide, a global experiential marketing company. He is responsible for the San Francisco office, which helps major technology clients to develop marketing communications programs to reach enterprise and consumer audiences.