AgentCubes Troubleshooting Session Guide with solutions

From Scalable Game Design wiki
Revision as of 22:28, 29 May 2015 by Kyuhan (talk | contribs) (Part B: Key queuing (Windows systems))

Jump to: navigation, search

You can follow along as the examples are demonstrated and use the margins to annotate your solutions. For each problem please try to answer: What happens, why, and what is a solution? Except where noted, these examples have companion demonstration AgentCubes projects with the same name as the problem number. There is a final section with questions unrelated to specific example projects, also without a companion project.

World Disappears

(Note: There is no example project for this problem.) The student starts playing the game

Problem 01 a.JPG

The student moves the frog to the goal and receives the congratulatory message

Problem 01 b.JPG

The student then taps ‘OK’ and sees this:

Problem 01 c.JPG

What happened and why?

Discussion: This is a classic example of the student creating a world, playing the game, which reloads the world when the game ends, and a blank world appears. The reason is that the student failed to save the world before running the simulation. Unlike changes to agent behavior or appearance (shape editing), which are immediately saved, changes to the world are saved only when deliberately done via the ‘save’ button.

Conversely another classic error is running the simulation and then saving the world without first reloading the world. The consequence is at that point the starting state of the world has been changed to be the finished, or end-of-game state.

Summary: While constructing a world – AND ONLY WHILE CONSTRUCTING A WORLD – it is important to save early and save deliberately; that is, when you have made some changes you want to keep, save the world, even if you are not done with the construction. That way, if you make a mistake and/or accidently play/test the simulation, you can easily return to the last saved state. Finally, when receiving the prompt that the world has changed when attempting to close the project, resist the natural semi-automatic tendency to save. Instead, think carefully about whether saving is really what you want!

Frog won't move in all directions

After completing all the rules for moving the frog and ending the game, the student finds that the frog only moves in one direction; that is, the frog does not respond to the other arrow keys. Why?

Discussion: In general, blank rules cause problems. The only “normal” place for a blank rule is in the “While Running” method of an agent that has no active behavior, such as the river or the road in the Frogger project. AgentCubes evaluates the “While Running” method behavior of EVERYagent in the world sequentially, then repeats this process continuously while the simulation is running. When evaluating an agent’s behavior, rules are examined from first to last in the While Running method. When a rule with all conditions satisfied is encountered, the actions in that rule are executed, and no further rules in that agent’s behavior are examined until the next cycle. A blank rule has no conditions. Therefore, if a blank rule is encountered in a method (e.g., above), no rules below the blank rule will EVER be examined! In the above example, because the blank rule precedes all rules with key conditions except for the left arrow key, only that arrow key will cause frog movement.

Problem 02 solution.JPG

Problem 02 solution 2.JPG

To see this graphically, click on the agent with the arrow tool in the world and observe, via the color-coding of Conversational Programming the blank rule is colored green, indicating the rule will always execute, as shown in the image below. All rules below the blank rule are uncolored, which means they will not be examined and, therefore, can never execute.

Summary: Blank rules embedded in agent behavior disable all rules below them. They are a common cause of agent behavior not working as the user expects.

Trucks stuck on top of right tunnel

Truck are stacked on top of tunnel

You see the following after running the simulation for a short time. Why?

Problem 03.JPG

Truck on tunnel PLUS truck traffic jam

You see the following after running the simulation for a short time. Why?

Problem 03C.JPG

Discussion: Examining the behavior of the truck we see the following:

Problem 03A.JPG

As can be seen, the only rule prescribes that the truck moves every 0.5 second to the right. There is no rule with a condition to stop the movement, so it moves until it reaches the edge of the world. What is desired is for the truck to disappear when it reaches (i.e., be “absorbed by”) the right tunnel. The simplest approach is to insert a rule in the truck behavior to erase itself if it “sees” the right tunnel to its right:


Note that the absorption rule is moved FIRST in the behavior. This is to ensure that the tunnel is “seen”. Although in this particular situation, it is improbable that the truck would miss “seeing” the tunnel on the right after it has moved to the that position, because it would take a half second to elapse before the truck would be able to move again. In that time, AgentCubes would have visited the truck agent again, in which case the rule with the timer would not run, and the tunnel would be observed. That said, it is always good programming practice to put “exceptional” situations first in the list of rules, simply to preclude possible missed events due to a timer event occurring.

Note, also, that the Frogger tutorial on the Scalable Game Design Wiki describes a more formal behavior for the truck which helps students identify problems like this earlier. For example, see: Technically speaking, the truck should only move to the right if there is empty road to the right. Thus, the rule for movement should include an addition condition requiring that the truck “see” road to the right. If this were the case, then even without the tunnel absorption rule, the student would see the problem as the trucks ‘stacking up’ to left of the right tunnel. This would motivate the student to consider a rule which allows the truck to be absorbed by the tunnel. Here is revised behavior for the truck that includes this:

Problem 03B.JPG

Summary: Here are some programming lessons from these examples:
• First things first! As in life, it is important to put the most important priorities first. In the case of programming agent behavior, that usually means placing rules that hand exceptional conditions – that is, events that happen relatively infrequently compared with other rules – first in the behavior. Good examples are simulation-ending rules, such as winning or losing the game, and rules which cause a change in an agent’s status, such as the truck disappearing.
• Include all of the conditions that relate to a given action or set of actions. In this example, the conditions for truck movement are empty road and a periodic timer. It may be possible that the appears simulation to “work” without all of the conditions most of the time; however, conservative programming both eliminates uncertainties and allows for catching other problems (such as the trucks layered on top of the right tunnel).

Sound in Loop, Message In Loop

Run the simulation and move the frog in front of a truck. Then try moving the frog onto the water. Finally move the frog onto the flag. What happens and why? How is the third problem above different from the other two? What are the implications in schools for with PCs with the Task Manager locked down?

Problem 04 example.JPG

Discussion: One of the most important concepts in handling a game ending situation is TO END THE GAME! While this seems like an obvious statement, it is very common for students to forget the most important aspect of accomplishing this, which is to stop the simulation, either by using the “Reload World” or “Stop Simulation” action. Examine the rules associated with the three situations posed in this problem:
Problem 04A.JPG

Problem 04 solution.JPG

Remember that while the simulation is running, AgentCubes is continuously examining the “While Running” method of every agent. If a rule in that method of an agent has all of its conditions satisfied, the actions of that rule will be performed. In a game-ending situation, the conditions will remain satisfied, so that unless the simulation is stopped, the actions will be repeatedly performed ad infinitum. In the above examples conversational programming is enabled by having clicked on the Frog agent just before the situation occurred, and having the Frog’s behavior window open. Note that the rules are green, indicating that the winning condition – stacked immediately above the flag agent, for example – is satisfied – permanently. Programmers affectionately call this situation an “infinite loop”.

Recovering from this can be as simple as clicking on the “Stop Simulation” red button on the world. Or it can require logging off from the computer and logging back in.

In the first two examples, AgentCubes will repeatedly initiate the honk sound or text-to-speech translation of the phrase in the “Say” action. It may sound like a stuttering noise. This is a rather obnoxious sound, but simply clicking on the “Stop Simulation” button will stop the simulation and end the sound.

The third example is much more problematic. Because the “Show Message” action causes a dialog to pop up, it suspends the simulation until the user clicks on the “OK” button in the dialog window. Unfortunately, because computers process very fast, once the user does click “OK”, the dialog window will immediately pop up. Terminating this situation requires very good hand-to-eye coordination, two hands, and luck. What the user must do with one hand is to press the “Return” or “Enter” key, which closes the dialog, and at essentially the same time click with the mouse on the “Stop Simulation” button. The latter must occur before AgentCubes can re-process the “Show Message” action. The faster the computer, the less likely one will be able to accomplish this. In such situations, one must manually terminate the entire AgentCubes process, either via the Task Manager on a Windows system or via Force Quit on a Macintosh. Unfortunately, since this capability is often restricted to only administrator logins, a student may then be required to logoff and log back in in order to close AgentCubes. As with having to re-create an entire world, most students will remember this lesson with only a single occurrence!

Summary: The most important action in a game-ending or simulation-ending rule is to end the game or simulation! A good practice to teach students is to put the simulation-ending action – “stop simulation” or “reload world” – into the rule first. Then test that the simulation works as desired; that is, the conditions for ending the simulation do, in fact, occur and the simulation stops or reloads. Finally, insert other actions, such as sounds and dialogs. Failure to follow this approach can result in a loop from which it is difficult to recover without forcing AgentCubes to quit.

Early game play difficulties

Stuck in loop after frog–truck collision

In this example, shortly after the simulation starts, the behavior of the frog colliding with the truck occurs (honk sound and world reloading) repeatedly until the stop simulation button is tapped. All you see is the starting screen:

Problem 04.JPG

Extra frogs appear

Alternatively, after starting the simulation and pressing an arrow key one or more additional frogs appear in the world.

Problem 05A.JPG

What is happening and why?

Discussion: First some background is in order. These two examples typify the most common mistake that beginning users of AgentCubes encounter: inadvertent layering of agents. This occurs because users incorrectly treat the world as a “canvas” instead of a construction, or layering platform. In a typical “paint” program, coloring over a section of the canvas essentially eliminates the original colored pixels and replaces them with pixels of the new color. In the AgentCubes world placing one agent on top of another simply adds the second agent; it does not remove the original agent. If the agent shapes use the full depiction size (i.e., 32x32 pixels for the default agent size) and no transparency, then the original agent will not be visible, at least until simulation begins. If the buried agents do not move around as part of their behavior, they will remain buried, but can still interact with the simulation. If the buried agents do move, they will appear to suddenly “pop up” from beneath their covering agents. Obviously, neither situation is desirable.
In these examples, there is a frog agent buried beneath the road. When simulation begins, nothing happens immediately. But very quickly there is a honking sound and the simulation restarts. The reason is that the buried frog under the road can still “see” the oncoming truck to its left.

Remember that conditions like “see” always refer to the top agent in a stack. Just as a frog on top of the road can see a truck to its left on top of the road, a frog that is buried under the road can still see a truck on top of the road to its left. The consequence of all this is that the buried frog sees the truck, makes a sound, changes its shape to the squashed frog, waits briefly, then reloads the world. As a consequence, the user can’t see the buried frog change its depiction. If you want to experiment with seeing what is going on, first use the erase tool on the world to remove the top layer of agents to find the buried frog. Doing so will yield the following world contents:

Problem 05B.JPG

Next, reload the world and open the frog behavior. Change the rule handling the frog-truck collision to replace the “reload world” with “stop simulation”. Then run the simulation and when you hear the honk sound and the simulation stops, use the erase tool to remove the road covering the buried frog. You will see the “squashed” frog agent shape:

Problem 05C.JPG

Trucks appear more frequently than expected

You start the game and huge numbers of trucks start appearing on the road. Why?

Problem 05D.JPG

Discussion: In this example, the buried/layered agents are the several layers of tunnels on the left ends of the roads. Using the eraser tool, you can remove several layers of tunnels on the left. Since each tunnel operates independently, as long as there is empty road on the right, and within the time and probability limits, any tunnel can generate a truck to its right. With several layers of tunnels, there is bound to be one in each stack that at almost any time is ready to generate a truck if there is empty road. So immediately the road fills with trucks. One way this kind of situation occurs is a student who incorrectly makes a new tunnel on top of itself instead of a new truck to its right. This goes unnoticed, while the student tries to find the problem of no trucks appearing. If the student ever saves the world with many layers of tunnel on top of themselves, the world will now be in the state of this example.

Problem 05E.JPG

This is a good ‘teachable moment’ in terms of students learning the consequences of improperly constructing a world. However, it can also be such a moment in terms of using tools to resolve the problem. An example would be to temporarily add a rule to the tunnel agent that erases itself if it is stacked above another tunnel agent. Then, using the single-step function on the tool bar, all of the tunnels except for the bottom layer will erase themselves. Afterward, the rule can be removed. Be sure to save the world after completing this correction!

Summary: Beginning users often treat the world as a paint palette rather than a layered structure. Even with 3D shapes, it may not be apparent that there are buried agents by just viewing the world without running the simulation. When unexpected behavior occurs, buried agents are a common cause. Sometimes, reconstructing a world is required; however, it is also possible in some situations, such as stacked agents of the same class, to use temporary rules to clear the excess agents.

Once Every and % chance combinations

We want the island and bridge agents to generate new log and turtle agents, respectively, 50% of the time once every 0.6 seconds, which means an average of about every 1.2 seconds, but with some randomness. When we run the simulation, we see that log generation seems to be working properly; that is, there is random spacing between logs. However, turtles seem to be generated much more regularly and with little spacing. Why?

Problem 06.JPG

Discussion: In the sample problem, the log and turtle generators have the same conditions in terms of timing and % chance, but the two conditions are reversed. See the screen shot below.
Problem 06 solution.JPG

The log generator agent (log_maker -- bridge shape) has the rule shown in the top image; whereas, the turtle generator agent (turtle_maker -- palm tree shape) has the rule shown in the lower image. The turtle_maker generates turtles regularly every 0.6 seconds with no variation; whereas, the log_maker generates logs with some degree of randomness. Why? Here it is important to understand how the AgentCubes simulation engine works. As has been noted earlier, AgentCubes continuously examines every agent in the world. Computers run very quickly – billions of cycles per second. This means that the AgentCubes simulation engine can examine all of the agents in a world many times per second.

Now a little more on condition evaluation. In addition to examining an agent’s While Running rules in order from top to bottom, AgentCubes also examines the conditions within a rule from top to bottom. If a condition is satisfied, AgentCubes examines the next condition until it finds that all conditions are satisfied, in which case, the actions of the rule are performed, or until a condition fails to be true. In the latter case, AgentCubes moves on to examine the next rule in that agent or the next agent if there are no more rules. The important thing to remember is that, just as AgentCubes ignores all rules below one whose conditions are all true, AgentCubes ignores all conditions below one that is false.

Let us first consider the first rule above (log_maker agent). What its conditions specify is that every 0.6 second, AgentCubes will then make a probability calculation (50%). This means that half the time, or about every other 0.6 second interval (assuming there is river on the right) a new log will be generated. Because it is probabilistic, sometimes there will be a log generated and sometimes there won’t. As with flipping coins, there may be several logs generated in a row or several “spaces” where no logs are generated. But in the long run, there will be logs generated on the average about once every 1.2 seconds, with some randomness.

Now consider the second rule above (turtle_maker agent). It looks almost the same, but it is fundamentally different in its output. In this case, the probability calculation is being done first. How often does this happen? As noted above, the computer is running billions of instructions per second, which means AgentCubes is evaluating all the agents hundreds of times per second or more. If the probability is 50% it means that about half the time, this condition will be true. Once every 0.6 second the timer event will occur. Within a small fraction of a second, the probability event will become true, so that essentially every 0.6 second the agent will generate a turtle. Just as rule order is often critical, so, too, can condition order be important for proper agent behavior.

The solution: simply switch the order of the timer and % chance conditions in the turtle_maker agent to match the order in the log_maker agent.

Summary: Condition order within a rule can be critically important, just as can rule order within an agent’s behavior. This is particularly important when both timing and probability are used in the same rule. In general, the timing condition (“once every”) should precede the probability condition (“ % Chance”).

Clock problems

A “once every” example

Will this agent’s color change back and forth between red and green? If not, why not, and can you fix it?

Problem 07.JPG Problem 07 solution a.JPG

Discussion: These are examples of the consequence of having multiple timers with the same timer frequency. It helps to understand how timer events work. A “once every” condition can be interpreted like this: “Has this amount of time since the last time this condition was true?” Once the appropriate amount of time has elapsed, the condition remains true until the “once every” condition in that agent’s “While running” method is evaluated. Once that happens, the condition is no longer true. Thus, if the condition is evaluated, regardless of whether any other conditions in that same rule are true, the condition is now false for other rules below that rule. In the above example, therefore, every 0.5 second, the timer event will be true and the first rule’s condition will be satisfied, so the agent’s depiction will change to the green square. The second rule will never be reached.
There are multiple ways to address this situation. One way is to insert a condition BEFORE the “once every” condition to create the decision of which change should occur. For example:

Problem 07 solution a 2.JPG

In this example, the “see” condition will be true based on the current color of the agent. Therefore, once the timer event is true (“once every” condition satisfied), then only the rule that shows the proper current color will have its “see” condition satisfied, resulting in changing to the opposite color.

Another solution is to use a method to decide how to change the agent. Here is an example (it uses different agents in the sample problem, which is why the colors are different):

Problem 07 solution b 2.JPG

Note that in this case, there is only one rule with a “once every” condition. Once that condition is true, the decision for color change is completed in a separate method, which makes the decision based only on what the current color is, switching to the opposite color. Note that there is no timer condition in the “Decide” method. That is another mistake that students often make: putting timers in other than the While Running method.

Another “once every” example

Which way will the Mover agent move every second? What do you think the intent of this behavior is? Will it work? If not, can you fix it?

Problem 07.JPG Problem 07 solution c.JPG

The probable intent of this agent behavior was for the agent to move back and forth like a clock pendulum. However, because the same time interval is used for both rules, the second rule will never have its action invoked, and the agent will move to the left every second. How can this be changed? In this case, since the agent does not change appearance, it is not possible to use that as a decision-making tool. Different agent shapes essentially carry “state” information about the agent; that is, the state of the agent is to have one shape or another. This means that the shape information can be used for decision making. In this current example, however, there is only one shape. In some project designs, there might be some other adjacent agent that can help discriminate between the two rules. However, in this example, there is no other information for such a determination.

One way to resolve this is to use an agent attribute, which serves as the information bearer about the state of the agent. When the desired direction is to the left, for example, the attribute will have one value; it will have another value for the opposite direction. The default for an agent attribute before it is ever referenced or changed is zero. Below are two ways to use an agent attribute to effect the pendulum-like behavior for the “Mover” agent. The first technique uses the agent attribute as the condition preceding the “once every” timer event in the same way as the agent color was used in the preceding example:

Problem 07 solution c 3.JPG

The other technique uses a separate method to handle the manipulation of the agent attribute:

Problem 07 solution c 2.JPG

As with the separate method in the color agent example, it is important to NOT place a timer condition inside the Decide method.

Summary: The concept of a timer is often difficult to explain to beginners. What seems like a clock interval is actually an event. Because of the way conditions are processed, once the event is examined, it is no longer “true.” The consequence of this is that having multiple timers, especially with the same time interval (or one that is a multiple of the other), can disable rule evaluation. A preferred technique is to use a single timer rule in the “While Running” behavior, and to create a separate method to handle the decision regarding the actions to be taken. If multiple timer rules are used in the “While Running” method, then it is almost imperative to include additional conditions which must precede the timer conditions in each rule, to ensure that the timer event is examined only when all other conditions in that rule are met.

Changing to different agent doesn't work

Problem 08.JPG

Suppose we have two frog agents a “Frog” and “Superfrog”, and a pellet agent, as seen in the project agent list at the left. The pellet allows the frog to become a superfrog.

When the frog eats (sees to its right) a pellet we want the frog to become a superfrog. So, we write the rule in the frog behavior.

Problem 08.solution 1.JPG

The Superfrog can swim in water and can’t be killed by trucks etc. (See Superfrog behavior below.)

We write the rule shown below in the frog behavior. When the simulation runs, the frog seems to change into a superfrog, but when the frog moves in front of a truck or jumps on the water, it dies? The superfrog behavior rules are 100% correct. You can test this if you use the pencil tool to place a superfrog in front of a truck or on the water, it does not die.

What is happening and why? How can this be corrected?

Superfrog behavior:

Problem 08 superfrog behavior.JPG

Discussion: This example illustrates what the “Change” action does: it changes the way an agent looks; it does NOT change one agent to another agent. It is a very common mistake that beginning students make when they want an agent to “morph” into another agent. One way to help students understand this is to use the analogy of a mask: does donning a mask of a famous person transform someone into that person? Obviously not. It only gives the appearance of that other person. The person wearing the mask still has all of the internal characteristics he/she possessed before donning the mask. So it is if an agent takes on the appearance, or shape of another agent. In this example, although the frog now looks like the superfrog, the frog is still just a frog, vulnerable to all the hazards as a normally appearing frog agent. In order to accomplish the desired transformation, it is necessary to actually create a new superfrog agent and remove (erase) the original agent as shown below.

Problem 08.solution 3.JPG

'New agent ‘remembers’ key strokes: As an aside, when testing this, you might notice that if you press quickly on the right arrow key, the newly created superfrog continues to move onto the pellet, even though the original frog is supposed to simply be erased and replaced by the new superfrog at the same position. If the pellet is at the edge of the world, this might not be noticeable. Try moving the pellet to the left a few columns and then quickly tap the right arrow key. The new superfrog will usually move a few cells to the right of the pellet after it is created. Why is this?

'The explanation requires understanding how AgentCubes handles keyboard input. Because AgentCubes does not know a priori which agents respond to a specific keyboard input, the simulation processor retains the keyboard input long enough to allow each agent in the world to examine each keystroke. If the user presses keys quickly, it is possible for a newly created agent (as a result of keyboard-directed activity) to be presented with the keyboard input. If avoiding this “key queuing” phenomenon is important to the operation of the simulation, it may require some additional programming, as well as careful attention to world construction to minimize the effect.

'One technique is to construct the world like that in the example above, so that even though there are residual keystrokes, they do not have a noticeable effect on the behavior.

'Another technique is to “throttle” the rate at which an agent is permitted to respond to keystrokes. In the example below, a timing condition (once every 0.2 second) is inserted in the rule that responds to the right arrow key. This limits how often the frog agent can receive the right arrow key. With this behavior (in both the frog and superfrog agents), the extra keystrokes that are entered very quickly will be ignored.

Problem 08.solution 4.JPG

Summary: The “Change” action merely changes the way an agent appears, not the way it behaves. If the simulation requires that an agent assume the behavior of a different agent, then the original agent must be removed (“erase” action) and a new instance of the desired agent be created (“new” action). If the original and/or newly created agent responds to keyboard input, then attention must be paid to prevent unwanted movement of the newly created agent, such as by using a timer condition in the rules that respond to keyboard input.

Unexplained Method Not Found error message

Method not found

Examine the behavior snapshot below.

Problem 09 solution 1.JPG

When the simulation runs, AgentCubes reports the message below. What specifically is this message describing? Why? What other similar problems can occur with other behavior conditions and actions?

Problem 09 solution 0.JPG

Discussion:A careful examination of the name specified in the “Message” action and that in the actual method reveals the number “0” in the former and a letter “O” in the latter. Spelling counts!

Problem 09 solution 3.JPG

AgentCubes has a better capability for preventing this kind of spelling error, but it is not infallible. Once a method name or variable name (agent attribute or simulation property) is defined via certain actions, such as the “set” first operand or the “message” second operand, the user has a menu from which to choose the name in subsequent actions. The “method” name field (the second operand field of the “message” action, and the first operand field of the “set” action) display a menu of existing defined names for messages, methods and variables, as shown in the image below. The final entry in the list provides the ability to define a new name.

Problem 09 solution 2.JPG

Note that in this example there are actually two method names, V0 and Vo. These can be seen by using the pull-down menu on either the message action name or the method name, as shown in the example to the left. In this case, the user at some point must have selected the “Add new method” option and created each one. An attentive user will notice the existence of the first created name and, hopefully, continue to select it in subsequent references in “message” and “broadcast” actions, thus making this problem less likely.

However, the “test” condition operands and second operand of the “set” action, for example, permit free-form input, in which the user has the “opportunity” for misspelling! This kind of problem is more difficult to detect. After the simulation has run, using the pull-down menu of the “set” action may display the current list of agent attribute and simulation property names, which will reveal names that are similarly spelled. However, this is not guaranteed if the additional name is not actually modified via a “set” action.

One final note: AgentCubes ignores upper/lower case when defining and referring to variable names and method names.

Simulation doesn’t end

Examine the behavior snapshot below. Run the simulation. Why doesn’t it stop?

Problem 09B.JPG

Discussion: In this example, the user references the “clock_1” agent attribute in the first rule to determine when to end the simulation: when the value exceeds 10. However, in the second rule, the user has defined the agent attribute “Clock_L” and used it to do the actual counting . In the agent attribute window, it is clear that the counter is being incremented and exceeds 10. However, because the first rule does not refer to the counter, but instead to a different agent attribute name. Using the pull-down menu of the set action, as shown below, there is only one agent attribute that is defined, namely the “Clock_L” attribute. It requires careful scrutiny to notice the subtle difference in the spelling of the two variable names. Sometimes, depending on whether the second agent attribute (“clock_1”) is used in a “set” action, both names might appear in the pull-down menu; but not always.

Problem 09B solution 1.JPG

Note that, defining an agent attribute, simulation property, or method name, AgentCubes automatically capitalizes the first letter of the name and makes all other letters lower case. If the name has portions separated by underscores, then the first letter of each portion is capitalized. Note, also that, depending on the display font, lower case “L” (“l”) and the number one (“1”) look nearly or actually identical. The same similarity may exist between the number zero (“0”) and the capital letter “O”. Note, also, that AgentCubes does not adjust the case of names that are referenced in the “test” condition fields, nor the second operand of the “set” action.

Summary: Spelling counts! It is particularly important to pay attention to spelling when referring to agent attributes and simulation properties in the “test” condition and the “set” action (second operand). Because these are free-form entry, it is possible to misspell a name and inadvertently refer to (or implicitly create) a variable other than the one desired. In this case, after the simulation has run, it may be possible to see both the desired and undesired names in the list of names by using the pull-down menu in the “set” action (first operand). However, there is no guarantee; if the second name is not used in the second operand of a “set” action, like the “Clock_L” attribute, it may not appear in the list.

Other AgentCubes problems

Note: all problems in this section used the same sample project

Backwards operation

Open the project and run the simulation in each of these three worlds. Use the arrow keys to move the frog toward the river.

New world_1:

Problem 10 new world 1.JPG

New world_2:

Problem 10 new world 2.JPG

Standard world:

Problem 10 standard world.JPG

What do you observe? What is happening? Why? How did it get that way?

Discussion: In ‘new world_1’, the up-arrow and down-arrow keys move the frog in the wrong direction. In addition, the frog seems to move under the road. In ‘new world_2’, all of the arrow keys seem to work backwards from what is expected; however, the frog move on top of the road, ground, and river. In ‘standard world’, the arrow keys work in the expected way, and the frog moves normally on other agents in the world. Note that it is the same frog agent in all three worlds. Therefore, the behavior is identical. That must mean there is something fundamentally different about the worlds, rather than a problem with the agent.
The problems in the first two worlds are typical of new students, particularly those who are “button pushers” – experimenters – who sometimes start playing without reading instructions or listening to instructors. When they first create a world, they might start investigating the tools on the tool bar. Quickly they discover the camera positioning tools, which change the perspective from which the world is viewed. Later, when it is time to construct their world, they begin placing objects on the world, without first reloading the world to restore it to its original starting state. If they have rotated or flipped the world upside down, they will construct a world in which the movement directions are reversed.

In the first world tested (“new world_1”), the world was flipped over from top to bottom before placing the river and frog agents. The consequence is that what appears as the “up” direction in the world view is actually down with respect to movement actions. In addition, the agents placed on the world are actually being viewed from below the plane of the world. Note that placing the agents still occurs vertically in the true upward direction (from a layer perspective). If you try to place a few agents in a cell, you will see that they seem to stack downward, rather than what would seem to be on top of each other. However, in initial world construction, such as is shown in the example, this might be missed.

In the second world tested (“new world_2”), the world was rotated 180 degrees in the same plane. The consequence is that all four directions are reversed, but the agents are still stacked properly vertically.

Unfortunately, there is no way to simply “flip” or rotate the world and have the agents move to the desired locations. Usually, resolution requires clearing the world and rebuilding it.

As an aside, there is a good troubleshooting lesson in this example: make a new world and test only the agents that are involved in the problem being investigated.

Summary: Beginning users sometimes play with the camera control tools before completing construction of a world and inadvertently flip or twist the world, then unwittingly create the world in a reverse perspective. A good practice is NOT to change the world perspective until sufficient agents have been placed so as to provide a natural proper perspective of up and down.

Key queuing (Windows systems)

Re-open the project from the previous example and, for ease of viewing, select “standard world” for this experiment:

Problem 10 standard world.JPG

Run the simulation and move the frog into the river. After the frog disappears, continue to press one of the arrow keys at least 10 times or until the following window appears:

Key queue full message 1.jpg

What is happening?

Discussion:First, notice that the simulation is no longer running after the frog disappears (erases itself) when it is stacked above the water. However, keystrokes are still being queued by AgentCubes. Eventually the key queue buffer is filled, causing the warning message. Usually, reloading the world will clear the key queue; however, the warning window will not disappear. It can be minimized; however, it is not a good idea to close it. The reason is that doing so creates a situation if the key queue fills again and AgentCubes will crash. To avoid this situation, one can simply close the project and quit/restart AgentCubes. This, however, does not close the warning window. Instead, there will be a final message written to the window:
Key queue full message 2.jpg

At this point you can close the window and then restart AgentCubes.

Summary: Even though a simulation is stopped, the AgentCubes program continues to run. This permits AgentCubes to implement conversational programming, for example. The consequence is that sometimes, if the user continues to “play” a game after it has stopped, AgentCubes may be queuing the keyboard inputs. If the queue limit is reached, AgentCubes will display a warning. Usually in this case, it is advisable to close AgentCubes and subsequently the warning window to preclude a crash later on.

Part C: Opening a project with AgentCubes running (Windows), Exporting a project

First open AgentCubes and then open any project in the Chooser window. Next locate any project on your computer, such as one on the desktop or in your Documents folder. If you do not have any project folders other than those in the Chooser’s “container,” export any project by selecting the tools (gear icon at the bottom of the Chooser window. Navigate to a convenient folder in which file storage is permitted. When you select ‘Export Project’ you will see a successful completion message:

Exported project message.jpg

Close the message window and find the newly exported project folder. Open the folder and then try to open the project by double-clicking the index.project file. You will see the following message:

AC project already running on Windows.jpg

The AgentCubes application will close. Note that this does not occur on Macintosh systems. How does this affect teaching students how to open an AgentCubes project?

Discussion: As noted, this operation is unique to Windows. Because of this, is a good idea to teach students always to open projects from within the AgentCubes Chooser window, especially if they are attempting to open multiple projects concurrently, such as for copying agent behavior between projects. Failure to open the second project from within the AgentCubes Chooser window will result in AgentCubes terminating.

Summary: A good practice to teach students is to open projects via the AgentCubes file/open or Chooser functions, rather than to open a project folder and double-click the index.project file. Although the latter technique works, it can cause problems on Windows system when a user does this while AgentCubes is already running. In addition to this potential problem, users sometimes inadvertently modify project folders, such as moving files in or out. Avoiding opening project folders minimizes this possibility.