Saturn Flytrap

The keyword when dealing with the Saturn Flytrap is "branches." Now, whereas I'm aware of the pun, I must insist that you accept that it is by necessity, not intention. In this case, the "branches" in question lie in the sub-routines. We'll get to that momentarily. For now, what's important are the object's extensive use of the "Stack Obj's Attribute" variables. The following is a table detailing each attribute and what it represents.

4: Keeps track of the "state" of the object. 0 ="Healthy," 1 ="Thirsty," 2 = "Hungry," 3 = "Dying," 4 = "Dead," and 5 = "Eating," which isn't really a "state" per se but needs distinction for the animation branch to be discussed later.
0: While "4" keeps track of the state of the object, "0" keeps track of which animation is playing while the object is in those states. This will be discussed to greater detail in the BHAV explanations below.
1: This one keeps track of how many hours have passed since the last time the plant was watered.
2: And this one keeps track of how many hours have passed since the last time the plant was fed.
3: If the plant has been neither watered in 24 hours nor fed in 48 hours, it begins to knock on death's door. This variable keeps track of how long the plant has been lingering in such a state.
5: This one just helps to make sure that the thirst counter isn't increased more than once per hour. More on this in the BHAV explanations.
6: Same as above, but for hunger.
7: Same as above again, but for death.

And with that, we move on to the more daunting topic of BHAVs. Unless popular outcry demands otherwise, I'm only going to go over some of the key BHAVs that make the object tick. Any questions regarding the other BHAVs or more details involving those covered below can be asked via the "@" symbol on the main page of the repository.

Animation Branch
This is the "hub" BHAV for all animations. It reads "Stack Obj's Attribute 4" and determines which sub-branch it should call.
Healthy Animations
While Stack Obj's Attribute 4 is set to "0," this BHAV calls a random number from 0 to 9 and then chooses an animation to play based on the result. If the result is "1," the plant will open its mouth. If "2," it will turn its head left. If "3," it will turn its head to the right, and if "4" it will rock back and forth. Any number from 5 to 9 will cause it to bob up and down.
Healthy Bob
This is one of the five "healthy" animations, and is the one that I consider to be the default. Therefore, it will be called 5 out of 10 times, whereas each of the others is called 1 out of 10 times. When it or any of the other "healthy" animations (which include "Look Left," "Look Right," "Open Mouth" and "Rock") has finished playing, it will return Stack Obj's Attribute 0 back to "0" so that the die may be cast again.
Hungry Animations
Similar to "Healthy Animations," this BHAV calls a random number from 0 to 4 while Stack Object's Attribute 4 is set to "2," thereby declaring that the plant is hungry. One out of four times, the plant will stop bobbing up and down and instead play the "hungry" animation, then set Stack Object's Attribute 0 back to "0" and re-randomize.
Certain animation frames need to hang a bit longer than the others, and when those frames are displayed, this BHAV sends the object into "idle" mode for an extra moment or two. It's an effective if inelegant solution; it's better than adding more duplicate drawgroups.
Thirst Countdown
It would be more accurate to call this a "thirst countup, but nobody really says that. Anyway, this BHAV checks to see whether an hour has passed and then adds "1" to Stack Obj's Attribute 1 if it has. When Stack Obj's Attribute 1 has reached "24," it will set Stack Obj's Attribute 4 to "1" if it had previously been "0," which means that it is now merely "dry" after having been "healthy." If, however, Stack Obj's Attribute 4 had previously been "2," that means that the plant had previously been "hungry," and is now both "hungry" and "thirsty," and sets Stack Obj's Attribute 4 to "3," which means that the plant is "dying."

"Hunger Countdown" and "Death Countdown" have similar jobs, except that when the "Death Countdown" reaches "12," the plant will drop dead!
Dry Animations
Though it's similar to "Healthy Animations" and "Hungry Animations," this one is worth explaining just because it uses Stack Obj's Attribute 0 in a slightly different manner, being that if its value is "0," then the BHAV knows that the animation used to show the plant drying up has not yet played. When the animation (handled by the BHAV "Dry Up") has reached its last frame, Stack Obj's Attribute 0 is set to "1" and from then on, "Dry Animations" knows to play the "Dry Bob" animations without further deviation.
Process Status
This is the BHAV that branches out to the Countdown BHAVs. The only reason I didn't have them all linked directly from the "main" loop was that I didn't want the "hungry" or "thirsty" counters to keep counting when the object had already reached those states, and I didn't want the "death" counter to start until it had reached both of them.
Both "Feed" and "Water" handle the sim's animations for feeding and watering the plant respectively. "Feed" is of more note, though, because it does other things as well. In order to animate the plant "eating" the food that the sim is providing, Stack Obj's Attribute 4 had to be altered, so I set it at "5" and updated the "Animation Branch" BHAV to handle this value. However, after the plant has been fed, it also needs to be set to the appropriate state, so Stack Obj's Attribute 4 needed to be temporarily stored. I used Stack Obj's Attribute 0 for this purpose; it takes on Attribute 4's value before it can be set to "5," and only if it's not already equal to "5."
Eat Branch
As you may expect, this BHAV branches out to two different eating animations, "Eat" and "Dry Eat." The difference between the two is that if the plant is healthy, it's green... and if the plant is dry, it's brown. It wouldn't make sense for a brown plant to suddenly be green while eating, or vice-versa. "Eat Branch" determines which one of the two animations is appropriate at the time by looking at Stack Obj's Attribute 0, which you'll recall was set to the value of Stack Obj's Attribute 4 in the "Feed" BHAV.
Refresh State (From Watering)
After the plant is fed or watered, it must be reset to an appropriate state. For instance, if the plant was dying, but then it was watered, it would still be hungry but not dry. If the plant was just dry, it would now be healthy. It's also possible to water the plant when it's not yet dry, so the status wouldn't change... but the "Thirst Countdown" would still need to be set to "0." "Refresh State (From Feeding)" does the same thing for the plant's "hunger," but "(From Watering)" also sets Stack Obj's Attribute 0 to "10" if the plant had indeed been dry. It's worth noting that "(From Feeding)" uses Stack Obj's Attribute 0 to re-set Stack Obj's Attribute 4.

You may have noticed in "Hungry Animations" and "Healthy Animations" that there is a BHAV "Refresh" called if Attribute 0 is set to "10." This tells the object to play the "Refresh" animation (which shows the plant fading from brown back to a healthy green color) before carrying on with the regular animations from the branches. This works because the "Refresh" animation resets Stack Obj's Attribute 0 back to "0" when it reaches its final frame.
Hour of Thirst
This BHAV's job is simply to make sure that the Thirst Countdown is only increased once every hour. We determine that an hour has passed when the "minute" value in the game clock is at "00," but the main loop can run quite a few times inside of one minute. However, we can set Stack Obj's Attribute 5 to the game clock's current hour at the end of the loop and then only allow the increase on loops in which the game clock's hour value and Stack Obj's Attribute 5 are unequal.

"Hour of Hunger" and "Hour of Death" use the same trick, but with Stack Obj's Attribute 6 and Stack Obj's Attribute 7.

And there you have the high points of the Saturn Flytrap's series of BHAV routines. I hope that you have found this document helpful and informative, or at least somewhat entertaining. If you have any questions, comments or criticism, please refer to the "@" symbol on the main page and send me an email.

Thanks for reading!
~ Candall