Automatic Completion and Status Detection

This tutorial describes a technique to automatically detect the end of the task of a simulation.

= Overview =

Many games and simulations have a clear concept of an ending. For example, the game of Sokoban ends when all of the boxes have been moved onto their proper box container positions in the simulated warehouse. It would be nice if the simulation could detect this and announce completion of the task. This can be done by establishing a counter that is periodically updated by the box containers themselves, indicating that a box has been positioned above them. When there are no longer any empty box containers – that is, when they are all full – the task is completed and the simulation ends.

= The Counter =

We use a simulation property called “boxempty” to keep track of the empty boxes:



The initial value of this counter is zero; however, as will be seen, the value maintained in it by the box containers is the number of empty box containers. As soon as simulation begins, the simulation property will indicate number of empty box containers, in this example, six:



Below is the beginning worksheet for a modified version of the Sokoban game that is taken from the AgentSheets demonstration projects, and from which this tutorial was constructed. As can be seen, there are six boxes scattered around the worksheet, corresponding to the six empty box containers indicated in the “boxempty” simulation property:



As the game progresses and boxes are pushed onto the box containers in the lower right portion of the worksheet, the “boxempty” simulation property indicates fewer empty containers. Here is the simulation property window matching the worksheet below it, in which three boxes have been moved onto box containers and three empty containers remain:

= How It Works =

To accomplish the tracking of remaining empty boxes requires communication to the box containers to instruct them to “check in” with their status. This communication is initiated periodically in the “pusher” agent; in this example it happens every 0.5 second. This is accomplished using an additional rule in the “While Running” method, shown below. In this rule, the “boxempty” simulation property is first set to zero, after which a message (“checkin”) is broadcast to all “redbox” agents, which are the box containers in this simulation. The “redbox” behavior will be examined later. In summary, each “redbox” agent increments the “boxempty” simulation property IF there is not box that has been moved above it. If there are no empty box containers, the “boxempty” simulation property will become zero. The final action of the new rule in the “pusher” agent is to call upon the “checkdone” method to determine whether “boxempty” is zero, and, if so, to terminate the simulation. Below is a snapshot of the worksheet, simulation property window, and the congratulatory message at the completion of the simulation. The final “boxempty” simulation property value is zero, indicating there are no remaining empty “redbox” container agents.

= How the “Checkin” Method Works =

When the “pusher” agent broadcasts the “checkin” message to the “redbox” (container) agents, a two-step process occurs. The behavior for the “redbox” agent is shown below. First, note that there is no behavior in the “While Running” method; all behavior is initiated via messages broadcast from the “pusher” agent.

There are two rules in the “checkin” method. The first one tests whether there is a box above the “redbox” container agent. If so NO ACTION is taken. If the condition in this rule fails, then the next rule, which is unconditional, executes, incrementing the “boxempty” simulation property. Thus, every “redbox” container agent which does NOT have a box above it will increment the “boxempty” simulation property. It takes only one to prevent the “pusher” agent from declaring the simulation complete.

It is natural to ask, “Why not ask if there is no box above the ‘redbox’ agent?” The answer is that there is no condition which tests for the absence of something above or below an agent; rather, only the presence is testable. However, the pair of rules shown accomplishes the same effect. This is a useful technique to remember: testing for the opposite of what one wants and having a null action for success, followed by specific, unconditional action for failure.