Counters and Timers Tutorial

From Scalable Game Design wiki
Jump to: navigation, search

Using a Frogger project as a base, we implement counters in three ways:

  • Using an agent attribute
  • Using a simulation property
  • Using an on-screen display


In this example, we keep track of the number of arrow keystrokes that move the frog. Within the frog, for each of the rules that handle the arrow keys, an internal counter (the agent attribute “c”) is incremented. This agent attribute is used to determine when the game ends by exceeding the number of allowed moves. In addition, the simulation property “moves” ( “@moves” when referenced in the operand of a condition or action) is incremented. This property is not used in the example for control, per se; it is implemented merely to show how to maintain a “global” counter. The message “inc” is broadcast to the “score” agent to increment the display on the worksheet. NOTE: it is not necessary to implement all three counting actions. This example simply illustrates the three techniques. There are different motivations for using each technique, depending on the needs of the simulation.

Frog behavior additions

Here are the additional actions in the frog rule for moving the frog when the left arrow key is pressed:

Frogger counter key behavior1.jpg

The two Set actions increment the “c” agent attribute and the “moves” simulation property. The former can be viewed in the “Agent Attributes” window, which is selectable in the “Tools” menu; the latter can be viewed in the “Simulation Properties” window, also selectable in the “Tools” menu.

The Broadcast action sends an increment (“inc”) message to the Score agent, which controls the display visible in the worksheet, and which is described later. The Make action sends a message to the “decide” method, which determines when the game is over.

Note that all four actions are replicated in each of the other three rules for moving the frog in the other three directions.

End of game detection

The “decide” method examines the “c” agent attribute to determine if the game has ended due to reaching the allowed number of moves:

Frogger counter end game decide.jpg

The rule in this method checks to see if the agent attribute “c” exceeds 10. If so, the actions taken show the end of the game. Note that this means that the game ends on the eleventh move. Here’s why: When an agent attribute is first used, its initial value is zero. The behavior described earlier increments the attribute each time an arrow key is pressed. The condition in the counter requires that “c” be greater than 10, which means that the game ends on the eleventh move. By viewing the agent attribute display, one can observe the “c” attribute being incremented with each move.

This raises a caution about saving worksheets. As a rule, it is a good idea to save a worksheet ONLY WHEN YOU HAVE A MADE A CHANGE THAT YOU WISH TO KEEP. When you save a worksheet, agent attributes are saved, as well. If you save a worksheet after a simulation has run, without resetting it, agent attributes will be saved with interim values.

How the “Digit” and “Score” agents work

Digit and Score depictions in the Gallery.
Below are images of the “Digit” and “Score” agent depictions and behavior. The Score agent receives an “inc” message to increment the visible Digit counter, and transmits it to the Digit agent to its left. The behavior of the decrement (“dec”) function in both the Digit and Score agents is similar to that described for the increment function. Note that the depictions of the different digits are all part of the Digit agent class. Thus, they all have the same behavior (see the images following the Score behavior).

In summary, when a digit receives a message to increment or decrement, it simply changes its depiction to the next higher or lower digit, based on its current appearance. Note the special behavior for the digit 9 when incrementing, and the corresponding digit 0 when decrementing.

Note that there is no “While running” behavior for either the Score or Digit agents; they simply respond to messages to increment or decrement.

Score behavior:

Score behavior.jpg

Digit behavior" A digit receives a message to increment (“inc”) or decrement (“dec”). For digits not at the extreme end of the range (9 for increment or 0 for decrement), the behavior is simply to change its depiction to the next higher (or lower) digit.

Digit methods overview.jpg

For the increment message when the digit is at “9”, if there is an existing digit to the left of the digit receiving the “inc” message, the message will be essentially forwarded to the digit to the left, causing it to increment itself, as well. This increment propagation will continue if there is a series of “9” digits. If there is not a digit to the left, a new “1” is created, thus automatically expanding the length of the counter field. This means one must plan for the maximum size the counter is expected to reach during a simulation run.

Digit increment method.jpg

Digit decrement behavior: This behavior is similar to the increment behavior, except in reverse. The major difference is the endpoint for determining whether to communicate with the digit to the left, which is now when decrementing from 0, instead of incrementing from 9. Note the effect if there is no digit to the left: the counter essentially ‘wraps’, rather than go negative. Implementing behavior to accommodate negative numbers requires more work!

Digit decrement method.jpg


The Frogger project is an example using the counters mentioned above using Agent Attributes and Simulation Properties. Below is a screen capture at the end of a simulation run when the 11th arrow key has been pressed, showing the Agent Attribute and Simulation Properties windows, as well as the on-worksheet counter display and the final “game over” message.

Frogger counters and end of game timer message.jpg

Final notes on multiple counters and timers

Clock timer

The “decide” method in the frog determines when the game ends due to exceeding the allowed moves. To implement an actual clock timer one would implement, either in the frog or a separate “timer” agent, a method to increment either an agent attribute or simulation property to increment a count. This method would be invoked via either a “make” action within the same agent or a “broadcast” action from another agent using a “once every 1 second” condition in that agent’s While Running method. Thus, rather than a keystroke event driven incrementing of the counter, the incrementing would occur regularly based on the “once every” condition.

Multiple agent attribute counters

Suppose one must strike an alien invader in Space Invaders multiple times before it is destroyed. This could be implemented using an agent attribute and a decision method within the invader’s behavior – like the “c” attribute and the “decide” method in the Frogger example above. Since agent attributes are unique to each agent occurrence on the worksheet, each invader has its own “hits” counter, and would require multiple hits before being destroyed. Similarly, there could be separate counters within the Defender and Mothership agents to allow for multiple “hits” before each is destroyed.

Multiple simulation property counters

As with agent attributes, there can be multiple simulation properties to control the simulation. However, unlike agent attributes, simulation properties apply to the entire simulation, rather than to individual agents. Simulation properties can be used to keep track of global information, such as the total number of infected “person” agents in a virus simulation, or the number of simulated deaths and recoveries that have occurred. Simulation properties can be used to determine end of game conditions, such as when a timer has been exceeded. The advantage of having a simulation property for this instead of an agent attribute is that the simulation properties window shows simulation properties without having to select the particular agent which has the appropriate agent attribute used as the timer (as in the Frogger example above). Another advantage is that, since the simulation property is accessible by all agents, it can be updated by multiple agents. This technique is used to determine the end of game condition in the Sokoban demonstration project, among others.

Multiple counters displayed on the worksheet

As with the other forms of counters, it is possible to have multiple counters displayed on the worksheet. For example, suppose one wants an on-screen display of the number of “hits” both the Defender and the Mothership have received in a Space Invaders game. One would need the additional equivalents of the Score agent to received broadcast increment or decrement messages when either Defender or Mothership receives a hit. However, the same Digit agent can be used for all of the on-worksheet displays, since they respond only to increment and decrement messages received from the Score (and equivalent) agents. This makes the design of multiple on-screen displays very easy to implement, since the behavior of the multiple Score agents can be easily replicated.

Deciding on what kind of counter to implement: agent attribute or simulation property?

In many situations, one could use either type of counter to accomplish the task. Such is the case in the Frogger example above. Although the Decide method used the “c” agent attribute to determine the end of the game, it could just as easily use the “@moves” simulation property, since both counters were being maintained in the example. The decision as to which approach to use is sometimes dictated by the simulation architecture. For example, keeping track of the number of remaining agents on a worksheet to determine the end of the simulation would necessitate using a simulation property: once an agent is erased, so are its agent attributes. However, keeping track of how many “hits” an agent has received before destruction necessitates an agent attribute approach, since each agent must account for its own hits. Note that the on-worksheet display cannot be used to control the simulation. None of the digits keeps track of the overall value of the set of digits making up a multi-digit counter. Thus, there is no intelligence in the digit display; it is simply there as an aesthetic for the simulation user.


The Digit and Score agent depictions and behavior were imported from the AgentSheets “Ultimate Pacman” demonstration project. A somewhat different implementation is the “Digit” and “Counter” agents in the “Bridge Builder” demonstration project. The increment and decrement behavior for both are the same as is described here. However, both agents have additional logic to allow dynamic determination of the number of bricks in the bridge, using a polling method similar to the Sokoban project.