Multiple Levels Tutorial

Overview
One of the first things that many students want to do to enhance their game projects is to create a more difficult “level” to play. Multiple levels are common in every video game, so it is a natural next step. The easiest implementation of multiple levels is the use of multiple worksheets. AgentSheets provides an action mechanism for switching simulation among worksheets (“Switch to Worksheet”).

Example Implementation
In the example implementation of multiple levels, reaching a goal triggers switching from one worksheet to another. Here is the starting worksheet:



The task is simple: using the arrow keys, move the agent starting in the upper left onto the goal in the lower right. When the task is complete, a dialog window will open, and upon closing the dialog, simulation will automatically transfer to the next level (“Level 2”). Displayed below is the behavior in the “While Running” method of the main agent (in this demonstration named “Fred”) that detects completion of the task and initiates the decision to switch worksheets. Note that there is more to the behavior, specifically, rules to handle the other arrow keys, for example.



When the agent moves immediately above the goal, a sound is made and the method “checkwin” is invoked to determine the next step:



In the first rule, the simulation property “level” is examined. (Recall that referencing a simulation property within a rule requires use of the “@” prefix to the simulation property name in order to distinguish a simulation property from an agent attribute.). Below is the value of the simulation property at the start of simulation:



As part of creating the behavior, it is important to create the simulation property “level” in the Tools/Simulation Properties window, set the value to “1”, and SAVE it! As with worksheet changes, it is important to save the simulation properties whenever you make changes you wish to retain, and NOT after a simulation has been run. Otherwise, you will have saved the properties in an interim state, rather the desired starting state for the beginning of simulation. Although simulation properties are not part of the worksheets, per se, they are reset to their last saved values whenever a worksheet – any worksheet in the project – is reset.

Returning to the behavior discussion, the first time the “checkwin” method is invoked, the “level” simulation property will have the value “1”, the initial value. As a result, the condition in the first rule will be true, so its actions will be performed. The first action is to erase the main agent. The reason for this will be explained later. The next action is to display a congratulatory message:



Once the “OK” button is clicked, the next action occurs, the “Switch to Worksheet”, with the “Level 2.ws” as the target worksheet. It is worth noting here that the way to choose the target worksheet for this action is NOT to enter the name manually. Rather, simply click on the operand field and choose the appropriate worksheet from the file menu list that is subsequently displayed. Finally, AFTER switching to the target worksheet, the “level” simulation property is set to “2”. At this point, the “Level 2” worksheet will be displayed. In addition, the Simulation Properties window, if open, will show the updated “level” simulation property:





When the target worksheet is opened, simulation will automatically transfer control to the target worksheet. Now suppose that the main agent follows the maze and moves to the goal in the lower right of this worksheet. Once, again, the behavior in the “While Running” method will detect completion and invoke the “checkwin” method. This time, however, the “level” simulation property will be 2, so the condition in the first rule will not be satisfied, causing the second rule, which has no conditions, to execute. This will display a different simulation completion message (see below), followed by a simulation reset once the completion message is acknowledged by the user:



More about multiple levels
Several points were mentioned above with probably less than satisfying explanation. So here is the rest of the story.

Why erase the agent on the originating worksheet when transferring to another worksheet?
When the “Switch to worksheet” action occurs, simulation transfers from one worksheet to another; that is, the “play” of the simulation stops on the originating worksheet and begins (or resumes) on the destination worksheet. However, it is possible to manually select the originating worksheet and then click on “play” to resume the simulation. If the condition causing the transfer is still valid, this can cause undesirable results, such as continued repeating of a sound action. Most often, an agent moving onto or near a goal on the originating worksheet triggers the switch action. Therefore, if, as part of the actions in the rule that causes the switch, the agent erases itself, the “infinite loop” possibility is prevented. Of course, if there are other conditions that trigger the switch, this simple (and somewhat simplistic) approach will not suffice. However, the point of this discussion is to consider the consequences of resuming simulation on the worksheet from which the switch occurred.

Why order the “set” action to change the simulation property AFTER the “switch” action?
In the tutorial above, it was emphasized that the action to set the value of the “level” simulation property should be placed AFTER the action to switch to the destination worksheet. The reason is that AgentSheets on a Macintosh resets simulation properties when a “Switch to worksheet” action is invoked. Therefore, if one changes the value of the “level” simulation property before the switch occurs, it will be reset to its initial value. AgentSheets on a PC does not reset the simulation properties during a “Switch to worksheet” action. Therefore, to ensure consistent operation across platforms, one should set simulation properties that are to be carried forward to the next worksheet after the switch action. Note that this has implications for additional for additional work if there are several simulation properties that are being maintained, for example, as counters. One technique would be to save each simulation property as an agent attribute, invoke the switch action, then restore the simulation properties from the temporarily stored agent attributes.

Does it matter if the destination worksheet is loaded prior to switching to it?
If the worksheet that is the target destination of a “Switch to worksheet” action is not loaded at the time of the switch action, it will be loaded automatically in its initial (reset) state. If the worksheet is already loaded, then it will simply become the active worksheet. Note that in the latter case, if the destination worksheet is not in its initial state, it will NOT be reset; rather, simulation will simply resume in at whatever state the worksheet exists. Therefore, if the simulation allows “toggling” between two worksheets, it is important to recognize that returning to the original worksheet will resume simulation where it stopped when the first switch occurred.

Worksheet size considerations for conversion to Java applets
AgentSheets provides the capability to convert a project to a Java applet format, which can then be run in a web browser without the requirement for the AgentSheets development software. This conversion is routinely performed whenever a project is uploaded to the Scalable Game Design Arcade (SGDA). Anyone who browses the arcade, with or without a login ID, can run any of the simulations posted to the SGDA, as long as Java is installed on his/her computer. In order to allow the user to view and use multiple worksheets in the applet version, one must insure that all such worksheets are open at the time the project is converted to an applet (i.e., submitted to the SGDA). In addition, the worksheet that is the active window at the time of applet creation will be the worksheet that is displayed and active when a user runs the applet. The user has the capability of manually selecting any of the worksheets that the designer permits by having them open at the time of applet creation, in addition to the applet’s capability to switch among worksheets as part of simulation activity.

The one consideration the designer must be aware of is that the window size for ALL worksheets in an applet is the size chosen for the initially active worksheet. If, for example, an initial level worksheet is smaller than a second level, as is the case in the tutorial above, if the initial level is chosen as the starting point when the applet is created, only part of the second worksheet will be visible, as shown below:



Therefore, if an initial game level has a small worksheet and a higher level is a larger worksheet, the larger worksheet must be active when creating the applet. Unfortunately, this will necessitate that the user of the applet manually first select the other worksheet before running the simulation. A better alternative is to make all worksheets the same size, even if the “easier” worksheet simply has a large blank border, if it is planned to make the project capable of running as an applet.

Alternative to multiple worksheets to implement multiple layers
As noted at the outset, multiple worksheets is probably the most straightforward technique to implement multiple levels of a simulation. However, it is possible to design a multi-level project within a single worksheet, by overlaying agents from one level on agents of successively “higher” levels. Then, the behavior of top level agents must be such that upper layer agents erase themselves in order to expose the next level in the sequence. This is certainly non-trivial programming; however, it does accomplish the task of containing a multi-level project within a single worksheet.