What If?

AgentSheets®

AgentSheets

Reference Manual

Table of Contents

Introduction

AgentSheets Application Menus

File Menu

New Project...

New Worksheet

Open Project...

Open Worksheet...

Close

Save

Load Background...

Remove Background

Ristretto

Import Agents...

E-mail Project

Submit to Arcade...

Exit

Edit Menu

Preferences...

View Menu

Toolbar

Status Bar

Gallery Menu

New Agent...

Edit Depiction

Edit Behavior

Edit Connectivity

Delete

New Depiction...

Search Depictions on Web

Duplicate Depiction

Run Duplication Script

Tools Menu

Conditions

See

See A

Stacked

Stacked A

Next To

Empty

Key

% Chance

Once Every

Hear

Test

Has Attribute

WWW Read

On Top Of

Direction

Yes or No Dialog

Actions

Move

Transport

Move Random On

Change

New

Erase

Set Color To

Make

Broadcast

Wait

Play Sound

Say

Set

Map

Plot to Window

Plot Attribute

Open URL

Switch to Worksheet

Load Background

Set Direction

Stop Simulation

Reset Simulation

Clear Simulation

Show Message

Triggers

While Running

On

Tool

When Creating A New Agent

Mouse Click

Parameters

Adjacency

Attribute

Class

Color

Comparator

Depiction

Direction

Formula

Formula Syntax

Image File Name

Key

Method Name

Sound

String

Tool

URL

Worksheet File Name

Simulation Properties

Agent Attributes

Generate Report

Conversational Programming

Windows Menu

Web Menu

Bookmarks

Designs

Help Menu

Other AgentSheets Components

Depiction Editor

Depiction Editor Camera Image Capture (Mac Only)

Depiction Editor Menus

File Menu

Import Image

Save

Close

Edit Menu

Undo

Clear

Color Menu

Color Chooser

Mask Color

Worksheet

Valid agent names

Valid attribute and simulation property names

Valid method names

Reference ManualAgentSheets is an agent-based computational thinking tool that enables a wide range of end users (from children to professionals) to create their own games and computational science applications.

The Reference Manual provides important information about the AgentSheets application, including its menus and Visual AgenTalk commands and parameters. Use the Reference Manual along with the Getting Started manual to build your own projects and simulations.

File Menu

Description: The File Menu is used to create and open projects and worksheets; to close and save windows, such as worksheets, behavior editors, and simulation properties editors; to load and remove backgrounds in worksheets; to create Java applets using Ristretto; to import agents from other projects; to share projects via e-mail; to submit your games or simulations to the Scalable Game Design Arcade; and to quit the AgentSheets application.

The File Menu includes the following options:

New Project... New Worksheet Open Project... Open Worksheet... Close Save Save as... Load Background... Remove Background Ristretto... Import Agents... E-Mail Project... Submit to Arcade... Exit

New Project...

Description: The File | New Project... menu option creates a new project. An AgentSheets project is a collection of gallery, worksheet, behavior, simulation properties, and other files, saved in a folder. For a detailed description of the project folder structure, please refer to Anatomy of a Project.

When you choose to create a new project, you will see a dialog box like the one shown below.

The default location for saving newly created projects is the Desktop folder.

Please note that you need to keep your projects somewhere where you have full privileges for writing. We chose the Desktop as the default location because some operating systems (e.g. Windows Vista) or lab setups, do not allow users to save anything in the application folder.

Click OK to create your new project in the default location. If you wish to save it elsewhere, from this dialog box, you can navigate to find a new location in which to store your project. Please make sure you have writing privileges in this new location, otherwise your project will not get saved.

You can cancel the creation of a new project by clicking the Cancel button. Otherwise, type the name of your new project in the File name field and click the OK button.

Now that the new project's name and location have been chosen, you will see a Define Agent Size dialog box like the one shown below. This box is used to determine the size of the agents that will inhabit your new simulation.

If you click on the Agent Size menu in the dialog box, an extended list of options for possible agent sizes will appear as shown below.

The default agent size is 32x32 pixels, the same size as desktop icons. However, different projects require different-sized agents. If your agents are going to have bodies and faces that are discernible, larger sizes will make it easier to see such features. For agents that are more blob-like, with less detailed features, smaller agent sizes can be used. The number of agents in your simulation is another consideration when choosing the agent size. If you are planning on having many agents in a worksheet, a smaller agent size would be more appropriate. Decisions like these are left to the user and are project-dependent. Please note that once an agent size has been determined, it cannot be changed.

It is also possible to specify your own agent size by choosing Custom... from the Agent Size menu. If Custom... is chosen from the menu, the Height and Width fields need to

be set manually by the user. Valid values range from 1 to 128 pixels. Otherwise, these fields will be set automatically according to the predefined sizes of the menu.

After the agent size is determined, click OK and an empty Gallery window will appear as shown below.

To place agents in the gallery, you will use commands from the Gallery Menu or the buttons at the bottom of the Gallery Window. The items in the Gallery Menu will become selectable when the gallery has appeared on the screen.

New Worksheet

Description: The File | New Worksheet menu option creates a worksheet, that is the world that the agents of your game or simulation will inhabit. When you choose to create a new worksheet, a window like the one shown below will appear on your screen.

The worksheet is actually divided into cells that agents can inhabit. Whenever you place an agent in a worksheet it inhabits one cell in that

worksheet.

Once you create a new worksheet you can populate it with agents from the gallery using the worksheet tools. You can also control the simulation using the worksheet buttons. For a detailed explanation of the worksheet tools and buttons, please see the Worksheet section.

When you attempt to save a new worksheet for the first time, a dialog box like the one shown below will prompt you to name your worksheet.

Open Project...

Description: The File | Open Project... menu option opens an existing AgentSheets project. An Open Project dialog box that lists projects in the AgentSheets Projects folder will appear as shown below. Select the folder of the AgentSheets project you wish to open and click the Open button.

Once you have opened a project, the project's gallery will open. Any other windows, such as worksheets, behavior editors, and palettes, will also open if they were open at the time the project was closed. This gives you the ability to control how your project will look like the next time somebody opens it.

An example AgentSheets project is shown in the figure below, which contains 1) the gallery 2) a worksheet 3) a behavior editor for defining agent behaviors 4) a conditions palette and 5) an actions palette. An open project can also contain documentation for the design and use of the project. It can also have simulation properties and agent attributes and create plots out of those attributes and properties.

Open Worksheet...

Description: The File | Open Worksheet... menu option opens a worksheet for the currently opened project. A dialog box will appear (shown below) listing the worksheets associated with the project.

Choose a worksheet and click Open or just double click on a worksheet file to open the specified worksheet.

Please note that the worksheet you are opening needs to belong to the currently opened project. Choosing a worksheet from another project will not work. A worksheet will appear, but it will be empty. If you accidentally open a worksheet not belonging to the current project, make sure you do not save it, because you will destroy its contents.

Close

Description: The File | Close menu option closes the active window (the selected window, which is in the foreground of your screen). The active window can be any type of window, such as a gallery, a worksheet, a behavior editor, or a simulation properties editor. For example, choosing File | Close when a worksheet is active will close that worksheet. Choosing File | Close when the gallery is active will close that gallery. You can also close any type of window by double clicking the upper left close-box on the window.

If, for example, you attempt to close a worksheet window that has been changed since it was last saved, you will see the alert box shown below.

If you would like to close the window without saving the changes that were made since last saving the worksheet, click No. The window will be closed, but changes will not be saved.

If you no longer wish to close the window, click the Cancel button to return back to the worksheet.

If you would like to save all changes made to the window (thereby replacing

the previously saved versions of the window), click Yes.

Save

Description: The File Menu | Save menu option saves changes to the active window. Use this option for saving worksheets, simulation properties, and behavior editors. Note that galleries get saved automatically. If the window you are saving has already been named, all changes will be saved under the current name, replacing the previously saved version. Otherwise, e.g. for a newly created worksheet, the system will prompt you to give a name and save.

Load Background...

Description: The File | Load Background... menu option creates a worksheet background using an existing image file. A worksheet needs to be active for this option to be enabled in the File menu. The following dialog box will appear:

You can navigate around the hard drive to find the desired image file.

Backgrounds are required to be located in the "backgrounds" folder inside the "classes" folder of a project (Please refer to Anatomy of a Project for details on the structure of the project folder). If you load a background that does not already exist in the backgrounds folder, the system will copy it

there for you.

It is important to note that, while the AgentSheets application recognizes GIF, PICT, and PNG file types for background images, Ristretto-generated applets can only load GIF and JPEG files. If you intend to create a Java applet from your AgentSheets simulation, it is best to use a GIF or JPEG background image.

Remove Background

Description: The File | Remove Background menu option removes a background image from a worksheet. A worksheet needs to be active and needs to have a background for this option to be enabled.

Ristretto

Description:

The File Menu | Ristretto... menu option generates a standalone Java applet of the currently active project and embeds it in a web page, ready to be published on the Web.

You can also invoke Ristretto by pressing on the Ristretto button in the Toolbar.

Once Ristretto is invoked, you are asked to specify a location and a name for your Java applet, in a dialog like the one shown below.

The default location for storing the generated applet is the Desktop and the default name is the project's name followed by "Applet".

For customizing how your applet appears in the Web browser, use the More Options... button, to specify the Ristretto preferences you would like to use for your applet generation.

Click Cancel if you wish to cancel the creation of the applet. Otherwise, click OK to continue with the applet generation. While this takes place, a status window (shown below) appears, keeping your informed about the progress of the Ristretto process.

When Ristretto is finished, the complete applet folder appears at the specified location. It contains an index.html file with the Java applet embedded in it and the readme.html as well as any other documentation material, if any were available in the project's folder.

To see the generated applet, double click on the index.html file. A browser will be launched, if one is not already running and the applet will be loaded.

You can then run your simulation in the browser by clicking the Run button.

Import Agents

Description: The File Menu | Import Agents... menu option enables users to import a single or multiple agents from another project into the currently active project.

Once you select Import Agents..., you are asked to choose a project from which you want to import agents in a dialog like the one shown below.

Click Cancel if you wish to cancel importing agents. Otherwise, select the project from which you want to import agents and click Import to continue.

Once you select the source project, the agents it contains that are available for import appear in a dialog (shown below).

Select the agent or multiple agents you wish to import into your project (as shown above) and click Import.

Unless you have agents in the currently active project that have the same names as the ones you are importing, the selected agents appear in your current gallery.

Agents are resized appropriately (shrink or enlarge) to match the size of the agents in the currently active project.

You can use the imported agents as they are or modify their behavior to suit the needs of your current project.

Please note that you will be alerted when an agent you are importing refers to depictions of agents that are not present in your current project. In such a case, the behavior editor of the imported agent opens and you should fix the problematic behavior by replacing the references to the missing agent depictions (shown as a generic grayed out depiction) with agents present in your gallery.

E-Mail Project

Description: The File Menu | E-Mail Project... menu option enables you to send projects to your friends. It packages the currently active project into a zip file and generates an e-mail message with the zip file as an attachment.

Fill out the From and To e-mail address fields and press Send

Please note that if you have not already specified your e-mail address and SMTP server in the Mail preferences, sending the message will not work. Please make sure you fill that information out before trying to email a project.

Submit to Arcade...

Description: The File Menu | Submit to Arcade... menu option generates an archive (Zip file) of the current project (simulation or game) ready to be uploaded to the Scalable Game Design Arcade and shared with others.

Once you choose to submit the project to the Arcade, the system will create an archive (zip file) containing:

● your project folder: the system includes the existing project folder with all its contents in the archive so that people have access to your project's source code. Before using the Submit to Arcade... option, please make sure it does not contain things you do not want uploaded to the Scalable Game Design Arcade and shared with other people.

● a project screenshot: by default the system creates a screenshot of the currently open worksheet to be used as a picture for your arcade entry. Please make sure there is a worksheet open before running Submit to Arcade.... If there is no worksheet open, you will get a warning:

● a Java applet: the system generates a Java applet out of your project to include in the arcade archive file. You will be prompted with the Ristretto Wizard to provide a name for the generated Web page in which your applet will be embedded and a description of your project that will be included in the applet Web page.

You can choose to change the destination of the archive file by clicking on the Choose File button and specifying a new location in the file dialog that appears.

You can also change settings for how your project will appear as an applet by using the Applet Options... button and specifying the Ristretto preferences.

When you click Start, the Ristretto generator runs and creates an applet that then gets incorporated into the arcade archive file.

The resulting Arcade archive file (shown on the left for the Frogger project) will then appear at the location you specified.

At the end of the creation process, the system will ask you to submit your project to the Arcade.

If you choose to submit, the Scalable Game Design Arcade submission page will appear in your browser. If you choose not to submit, you can later go to the arcade yourself and submit your archive.

If you do not already have a user account, you can easily create one at the main Arcade web page. Assuming you are logged in and ready to upload, the submission form will appear. Fill out the form with the title of your game, a short description, and the arcade file you just created, as shown in the example form below with the submission details for Frogger.

Click the Upload button to submit your game. Upon successful submission, you will get a message confirming that your game or simulations has been accepted and when you return to the Open Arcade, you will see your submission as one of the entries there.

You can also get up-to-date information on how to upload to the Arcade from the Upload Tutorial.

Exit

Description: The File | Exit menu option exits the AgentSheets application. The equivalent functionality for the Mac, can be accessed from the AgentSheets | Quit AgentSheets menu option.

If no changes have been made since the opened windows were last saved, AgentSheets will be closed. If there have been changes since any of the windows were last saved, an alert box like the one shown below for a worksheet will appear.

To cancel the exiting process and return to the AgentSheets program, click the Cancel button.

To delete all changes made to the current worksheet since it was last saved, click the No button. The changes made to the worksheet will not be saved and you will exit AgentSheets. The worksheet will remain as it was when last saved.

To save all changes made to the current worksheet and replace the older version of the worksheet, click the Yes button.

Edit Menu

Description: The Edit menu contains items that are used to manipulate Visual AgenTalk commands such as actions, conditions, rules, and methods. It also provides access to the application's Preferences (Windows only).

The commands found in the Edit menu are common to many applications and are described below.

Undo The Edit | Undo menu option undoes the last action performed. If selected repeateadly, it can undo multiple actions. Undoable actions include things such as typing text and copying commands in the behavior editor.

Redo The Edit | Redo menu option redoes the last action that was undone. If selected repeateadly, it can redo multiple actions. Redoable actions include things such as typing text and copying commands in the behavior editor.

Cut The Edit | Cut menu option cuts any highlighted command from the active window and copies it to the clipboard. Commands that have been cut are removed from the active window.

Copy The Edit | Copy menu option copies any highlighted command from the active window to the clipboard. Copied commands are not removed from the active window.

Paste Commands that have been placed on the clipboard can be placed in other windows (or other parts of the same window) using the Edit | Paste menu option.

Power User Shortcuts

Cutting, copying and pasting commands can be also be performed by right-clicking on the specific command. Depending on the command, a pop-up menu will appear that contains, among other things, Cut, Copy and Paste options. For example, right-clicking on a rule in a behavior editor, you will get a pop-up menu like the one shown below.

Preferences... The Edit | Preferences... menu option (Windows) brings up the dialog box shown below, which can be used to set up appearance, e-mail, networking, and Ristretto preferences for the AgentSheets application. The equivalent functionality is accessible from AgentSheets | Preferences... menu option on the Mac.

Preferences

Description: The Preferences dialog can be used to set up appearance of the VAT language pieces, e-mail and network settings, and Ristretto preferences for the AgentSheets application. From Windows, the Preferences can be accessed from the Edit | Preferences... menu item. The equivalent functionality for the Mac is accessible from AgentSheets | Preferences... menu option.

General Preferences

The General preferences allow you to change the font type and size of text, change appearance for Visual AgenTalk commands, and control Conversational Programming on application startup.

The type and size of the font used in the application (for command names, menu items, button text etc.) can be modified according to user preferences.

The appearance of the Visual AgenTalk commands in behavior editors and command palettes can be changed by choosing different UI themes illustrated in the examples below.

Plain Look

Classic Look

Mac Look

Gradient Look

The Conversational Programming On at Startup check box allows you to define whether Conversational Programming is on or off when the application is launched.

Mail Preferences

The Mail preferences allow you to define your e-mail address and SMTP server for sending e-mail, when using the File | E-Mail Project menu option. Check the e-mail application you are using (such as Mail, Outlook Express, or Eudora) for the SMTP server setting.

Network Preferences

The Network preferences are used to define and name proxies, which are relevant for

commands such as the WWW Read condition, a condition which will not work if a proxy is used for network access, but is not set up correctly.

Check the Use Proxy box if your computer is behind a firewall. If you are not sure if this is the case, check your browser's proxy preferences to see if the proxy is enabled.

If you check the Use Proxy check box, the Proxy Server and Proxy Port fields become enabled. Enter the name of the proxy server in the Proxy Server text field and the proxy port number in the Proxy Port text field. Check your browser's settings for proxy host and port number information.

Once the preferences are entered, click OK to return to AgentSheets. Click Cancel to exit preference editing without saving the changes.

Ristretto Preferences

The Ristretto preferences are used to select options for the Java applet generated by Ristretto. It includes preferences for the following:

Worksheet

Use the worksheet title: if checked, a title will appear on top of the worksheet in the applet. This title is specified by the Title preference.

Title: Text used as a title for the worksheet in the applet. Default title is "Worksheet".

Show Menu: if checked, and if the project includes simulation properties, a menu will appear to access the simulation properties editor

Toolbar

Show Toolbar: if checked, the worksheet toolbar will appear in the applet.

Select Tool: worksheet tool that will be selected when the applet is loaded. Please note that you can have a tool selected, even if the toolbar is not shown.

Gallery

Show Gallery: if checked, the gallery will appear in the applet.

Use the gallery title: if checked, a title will appear on top of the gallery (if it is shown) in the applet. This title is specified by the Title preference.

Title: Text used as a title for the worksheet in the applet. Default title is "Worksheet".

Agents

Draggable: if checked, the agents that appear on the worksheet can be dragged using the arrow tool.

Selectable: if checked, the agents that appear on the worksheet can be selected using the arrow tool.

Changeable Depictions: if checked, the agents that appear on the worksheet and the gallery can have their depictions changed using a right-click with the mouse (see power user shortcut in Arrow Tool section of the Worksheet Tools).

Simulation Controls

Show Buttons: if checked, the simulation buttons (Run, Stop, Step, Reset, Clear) will appear in the applet.

Show Speed Control: if checked, the simulation speed control slider will appear in the applet.

Show Message Center: if checked, the worksheet's message area will appear in the applet.

Run simulation after loading: if checked, the simulation will start running as soon as the applet loads. Useful when the simulation buttons are not shown. Notice, however, this option may prevent the applet from becoming the keyboard focus. In that case, click on the applet to make it the focus for user input.

After Generating Ristretto Applet

Open applet in browser: if checked, the applet will be launched in a browser as soon as Ristretto is done generating it.

View Menu

Description: The View menu allows you to toggle the state of the Toolbar and the Status Bar between visible and not visible.

The View menu includes the following options:

Toolbar Status Bar

Toolbar

Description: The Toolbar menu option allows you to toggle the AgentSheets toolbar between the visible and not visible states. The toolbar (shown below) provides shortcuts for opening projects, creating new projects, cutting, copying and pasting, the actions, conditions and triggers palettes, generating Java applets with Ristretto, accessing information about the project on the web, and toggling Conversational Programming on and off.

The toolbar shortcuts are described below:

New Project

The New Project button provides a shortcut for creating new projects. This functionality is also accessible from the File | New Project... menu option. It is only enabled when no project is open.

Open Project

The Open Project button provides a shortcut for opening a project. This functionality is also accessible from the File | Open Project... menu option.

Save

The Save button provides a shortcut for saving active windows, such as worksheets, behavior editors, and the simulation properties editor. This functionality is also accessible from the File | Save menu option. It is only enabled when a project is open and a window requires saving.

Undo

The Undo button provides a shortcut for undoing the last action performed. If clicked repeateadly, it can undo multiple actions. Undoable actions include things such as typing text and copying commands in the behavior editor. This functionality is also accessible from the Edit | Undo menu option. It is only enabled when the last action performed is undoable.

Redo

The Redo button provides a shortcut for redoing the last action that was undone. If clicked repeateadly, it can redo multiple actions. Redoable actions include things such as typing text and copying commands in the behavior editor. This functionality is also accessible from the Edit | Redo menu option. It is only enabled when something has been undone.

Cut

The Cut button provides a shortcut for cutting Visual AgenTalk commands in behavior editors or text in text windows. This functionality is also accessible from the Edit | Cut menu option or the power user shortcuts for cutting. It is only enabled when an item that can be cut is selected.

Copy

The Copy button provides a shortcut for copying Visual AgenTalk commands in behavior editors or text in text windows. This functionality is also accessible from the Edit | Copy menu option or the power user shortcuts for copying. It is only enabled when an item that can be copied is selected.

Paste

The Paste button provides a shortcut for pasting Visual AgenTalk commands in behavior editors or text in text windows. This functionality is also accessible from the Edit | Paste menu option or the power user shortcuts for pasting. It is only enabled when an item that can be pasted has been cut or copied.

Conditions Palette

The Conditions Palette button provides a shortcut for opening the conditions palette. This functionality is also accessible from the Tools | Conditions Palette menu option. It is only enabled when a project is open.

Actions Palette

The Actions Palette button provides a shortcut for opening the actions palette. This functionality is also accessible from the Tools | Actions Palette menu option. It is only enabled when a project is open.

Triggers Palette

The Triggers Palette button provides a shortcut for opening the triggers palette. This functionality is also accessible from the Tools | Triggers Palette menu option. It is only enabled when a project is open.

Ristretto

The Ristretto button provides a shortcut for creating a standalone Java applet of the currently active project. This functionality is also accessible from the File | Ristretto... menu option.

Conversational Programming

The Conversational Programming drop down menu provides functionality for enabling and disabling Conversational Programming. Select "On" or "Off" to enable or disable Conversational Programming respectively. Select "Help" to get further documentation about Conversational Programming and how to use it.

Conversational Programming is a revolutionary patent-pending programming paradigm that helps you create your programs in a conversational manner, with the system talking back to you when you are constructing your program. When enabled, Conversational Programming essentially runs important parts of your program and gives you immediate visual feedback about what will happen, even before your program is finished.

Design

The Design link allows easy one-click access to design descriptions and lesson plans on the Scalable Game Design wiki that have been created for a given project. The provided design include background information about the subject of the game or simulation, how to use it, and in some cases educational content such as links to standards and support material for grading. If no project has been opened, the design button will link to an index of all designs that currently exist.

Status Bar

Description: The Status Bar menu option allows you to toggle the AgentSheets status bar between the visible and not visible states. The status bar provides textual status information about the Ristretto process, opening behavior editors...

Gallery Menu

Description: The Gallery Menu is used to create and edit the appearance, behavior, and connectivity of agents.

If no agents are highlighted in a gallery, then most of the items in the Gallery Menu will not be enabled. If a gallery is active but no agent is highlighted, only the New Agent... menu item will be selectable.

The Gallery Menu includes the following options:

New Agent... Edit Depiction Edit Behavior Edit Connectivity Delete New Depiction... Search Depictions on Web Duplicate Depiction Run Duplication Script

New Agent...

Description: The Gallery | New Agent... menu option creates a new agent in a gallery. You can also create a new agent by clicking on the New Agent button in the gallery. A New Agent dialog box shown below will appear prompting you to name your newly created agent.

Type in a valid name for the new agent and click the OK button. In the gallery of the current project there will now be an agent with a default depiction and the name you have just typed, as seen below with agent "Bob."

The agent definition contains the following parts: the folder tab with the agent's name, the agent's base depiction, the agent's depiction list and a twist-down arrow used to collapse or expand the depiction list.

Edit Depiction

Description: The Gallery | Edit Depiction menu option allows you to edit the selected agent's depiction. Select the agent's depiction in the gallery by single-clicking on it, then choose Gallery | Edit Depiction and a depiction editor, like the one shown below, will appear. You can also double-click on the agent's depiction in the gallery or select it and click the Edit Depiction button in the gallery to edit it.

The depiction editor allows you to easily draw and edit your own agent icons. The toolbar for the editor is located in the upper left corner and contains tools that function similarly to standard tools found in graphics

manipulation programs. For more information on the toolbar, see the section on the depiction editor.

Power User Shortcut

An agent's depiction can be edited by right-clicking the depiction you wish to edit. This will show the following pop-up menu, from which you can select the Edit Depiction menu option.

Edit Behavior

Description: The Gallery | Edit Behavior menu option allows you to edit the selected agent's behavior. Select the agent in the gallery by single-clicking on it, then choose Gallery | Edit Behavior and a behavior editor, like the one shown below, will appear. You can also double-click on the blue part of the agent's definition in the gallery or select the agent and click the Edit Behavior button in the gallery to edit its behavior.

Power User Shortcut

An agent's behavior can be edited by right-clicking the agent whose behavior you wish to edit. This will show the following pop-up menu, from which you can select the Edit Behavior menu option.

Visual AgenTalk (VAT) is the visual programming language of the AgentSheets environment. You program in the Visual AgenTalk language by dragging and dropping conditions and actions into rules in an agent's behavior editor (shown below).

Lists of rules are grouped together into methods. Each method is labeled

with a trigger, the yellow and black striped tag at the upper left corner of the behavior editor shown above. The rule above is located in a method labeled with the While Running trigger. Rules located in the While Running method of an agent will be checked by the AgentSheets scheduler at every simulation cycle . A full list of triggers is housed in the Triggers palette which is accessed via the Tools | Triggers Palette menu option. You can also access the Triggers palette by clicking on the Triggers button in the Toolbar.

The user decides how to define different methods for agents by filling those methods with lists of rules, which in turn are assembled from lists of conditions and actions.

Condition commands are blue and are permanently housed in the conditions palette. They are always dragged into the IF side of a rule. An implicit "and" exists between all conditions in a rule. This means that all the conditions of a rule must be true in order for the actions of that rule to be executed. You can access the conditions palette via the Tools | Conditions Palette menu option. You can also access it by clicking on the Conditions button in the Toolbar.

Action commands are red and are permanently housed in the actions palette. They are always placed in the THEN side of a rule. An implicit "and" also exists between all actions in a rule. This means that all the actions in a rule will be executed if the rule's conditions are true. You can access the actions palette via the Tools | Actions Palette menu option. You can also access it by clicking on the Actions button in the Toolbar.

Power User Shortcuts

A condition can be added to the agent's behavior by right-clicking in the part of the rule where conditions reside. This will show the following pop-up menu, from which you can select the Add Condition menu option and then select the desired condition to add. The example below illustrates the addition of the Next To condition.

An action can be added to the agent's behavior by right-clicking in the part of the rule where actions reside. This will show the following menu, from which you can select the Add Action menu option and then select the desired action to add. The example below illustrates the addition of the Change action.

A trigger can be replaced on an agent's method in the behavior editor by right-clicking on the current trigger. This will show the following menu, from which you can select the Change Trigger menu option and then select the desired trigger. The example below illustrates the change of a trigger to the On trigger.

Behavior Editor Buttons

The New Rule button adds a new rule to the method currently highlighted. A new rule is added right below the currently selected rule. If no particular rule is highlighted, the new rule gets added at the end of the method. If no method is currently highlighted, the new rule is added to the bottom of the While Running method.

The New Method button adds a new method with an On trigger to the list of methods in the behavior editor. New methods are always added at the bottom of a behavior editor.

The Duplicate button makes a copy of a selected rule, condition, or action. You cannot use the Copy button to copy methods.

The Explain button shows a context-sensitive explanation of the selected language component (condition, action, trigger, rule, or method) in an animated tool tip. The system steps through the parts of the language component being explained, while the corresponding piece of explanation gets highlighted. The example below shows how the Change action is explained.

Each parameter of the Change action is highlighted with a red rectangle, while the corresponding explanation text also gets highlighted by turning red. Explanations are context-sensitive as they depend on the currently selected parameters for the language component. For instance, if the direction parameter was set to the right arrow in the Change action, the explanation would show:

The Test button shows the effect that a selected language component has on a particular agent selected in the worksheet. AgentSheets lets you "play" with the language to find out what each component does without having to create a complete program. You can select a single condition or action, a rule or an entire method in the Behavior Editor, select an agent in the worksheet using the Arrow tool, and click the Test button. The selected language component will execute in the specific context. A condition will return true or false depending on the context of execution. An action will execute and show its effect on that agent. A rule will execute by stepping through all the conditions and, if all true, execute all actions; if any condition fails, testing it will reveal which one.

For example, testing the Next To condition on an agent will test if any of the 8 adjacent agents looks like the depiction specified in the condition. A yellow and black striped frame around the condition indicates that the condition is

being tested. If the condition is true then the frame quickly disappears and a sound is played. If the condition is false, the frame begins to blink and a different alert sound is played.

In the situation above, the condition is true since there is one or more adjacent agents that looks like the one specified by the condition.

The Apply button makes the behavior specified in the editor take effect for all instances of the agent and saves the changes to the agent's behavior file, but does not close the behavior editor.

Pressing the Apply button applies any changes in an agent's behavior (i.e. new/changed methods, new/changed rules, new commands, reordered rules, changed parameters etc.). This means that any instances of an agent that own the rule editor where new rules have been applied will act according to those new rules. Pressing the Apply button allows you to change an agent's behavior, and then to check those changes, without closing the rule editor. The Apply button turns blue if changes to the behavior editor that houses them were made since you last saved or applied your rules.

The OK button saves the agent's behavior and closes the behavior editor. When you open the behavior editor again, any changes made since the last time it was saved will have been preserved.

The OK button turns blue if changes to the behavior editor that houses them were made since you last saved or applied your rules.

The Trash Can located on the bottom right of the behavior editor works just like the Recycle Bin on your desktop. You can drag commands, rules, or methods onto the Trash Can to discard them.

Edit Connectivity

Description: The Gallery | Edit Connectivity menu option allows you to modify the connectivity of an agent. The concept of connectivity is useful in simulations that utilize flow. Connectivity patterns facilitate the drawing of icons in worksheets as well as making use of commands associated with connectivity, such as the On Top Of condition, when programming flow between agents. Below is an example of a connectivity editor from the Sustainopolis simulation.

Define the input and output ports of the currently selected agent by clicking the gray area north, south, east, or west of depiction. Click to cycle through input, output, both, and none until you find the desired connectivity mode.

Click Done when you are done editing to save the changes to the agent's connectivity. Click Cancel to cancel editing the agent's connectivity and discard changes.

Power User Shortcut

A depiction's connectivity can be edited by right-clicking on the depiction in the gallery. This will show the following pop-up menu,

from which you can select the Edit Connectivity menu option.

Delete

Description: The Gallery | Delete menu option deletes the selected agent or depiction from the gallery. A dialog box will appear, asking you to confirm the deletion. The dialog box shown below asks you to confirm the deletion of an agent's depiction.

The dialog box shown below asks you to confirm the deletion of an agent.

To cancel deletion, click the No button. If you are sure that you want to delete your agent (including behavior) or your depiction (depending on what you are deleting), choose the Yes button. If you are deleting an agent, your agent and all its behavior will be deleted. If you are deleting a depiction, only the selected depiction will be deleted.

If the selected depiction you are attempting to delete happens to be the base depiction of your agent, you will receive the following warning that deleting the base depiction of an agent is not allowed.

Click OK to return to the gallery.

New Depiction

Description:

The Gallery | New Depiction... menu option creates a new depiction for the selected agent and allows you to edit it and change it as you wish. An agent can have multiple looks. For example, in the Virus Attack, a person needs to have a healthy and a sick look (See the Getting Started manual for more information on the Virus Attack simulation). To create multiple looks, choose the Person agent in the gallery and use Gallery | New Depiction... or click the New Depiction button in the gallery. A dialog box, like the one shown below, prompts you to name the new depiction.

To cancel the creation of a new agent depiction, click the Cancel button. To continue creating a new depiction, type in a valid name, such as Person_Sick, and click the OK button. The new depiction will appear in the gallery, at the end of the depiction list, as shown below. The default depiction for the newly created depiction is the base depiction of the agent. You can use the depiction editor to alter the new look of the agent.

Please note that you are not creating a new agent, but a new depiction, that is a new look, for your base agent. Therefore, the new depiction will have the same behavior as the original agent.

Search Depictions on Web

Description: The Gallery | Search Depictions on Web menu option utilizes Google's image search (accessible directly at http://www.google.com/imghp) to locate relevant images on the Web.

If an agent is selected in the Gallery at the time of the selection of this search facility, the name of the agent becomes the default string to search for. If no agent is selected, a search dialog with an empty text box appears and you can type the string to search for.

In the example shown below, the Compass agent was selected in the Gallery, therefore the text "compass" appears in the text box.

To cancel the search for images on the Web, click the Cancel button. To continue searching for images, click the OK button. A broswer will be launched, if one is not already running, and Google will perform the search you have specified. For the search for "compass" the results are shown below.

Once you find an image that you would like to use in your simulation, you can download the image file it to your disk and then use the Depiction Editor | Import Image menu option to incorporate the downloaded image in your simulation.

Duplicate Depiction

Description: The Gallery | Duplicate Depiction menu option allows you to transform agent depictions by flipping them, rotating them, and manipulating them in more complicated ways (described below).

To transform a depiction, select it in the gallery and then choose a transformation from the Gallery | Duplicate Depiction menu option. You will see the following dialog box prompting you to change the name of the duplicate agent (the original agent selected for this example was called "Brick").

To cancel the transformation of an agent depiction, click the Cancel button.

To continue transforming the depiction, type in a valid name and click OK button. The transformed agent depiction will appear in the gallery at the end of the depiction list.

Please note that you are not creating a new agent, but a new depiction, that is a new look, for your base agent. Therefore, the transformed depiction will have the same behavior as the original agent.

The transformation options are:

● Same... duplicates the depiction with no transformation. ● Flip Vertical... flips the depiction vertically. ● Flip Horizontal... flips the depiction horizontally. ● Flip Both Ways... flips the depiction both vertically and horizontally. ● Rotate 90... rotates the depiction right 90 degrees. ● Rotate 180... rotates the depiction right 180 degrees. ● Rotate 270... rotates the depiction right 270 degrees. ● Buckle Down Right... bends the depiction right hand side sharply

by 90 degrees. ● Bend Down Right... bends the depiction right hand side softly by 90

degrees. ● Fork Right... forks the depiction right hand side: bends one copy 90

up and another copy 90 degrees down. ● Cross... crosses the depiction with a 90 degree rotated copy.

These transformations work on any depiction. Interesting and even grotesque depictions can be formed by transforming realistic or abstract original depictions. You can also achieve interesting effects by transforming transformations.

Power User Shortcut

A depiction can be duplicated by right-clicking on the depiction in the gallery. This will show the following pop-up menu, from which you can select the Duplicate Depiction menu option and then choose the transformation you wish to apply to the depiction.

Run Duplication Script

Description: The Gallery | Run Duplication Script menu option allows you to create new depictions for the agent currently selected in the gallery, using predetermined transformation scripts. The script choices are described below.

Full Connectivity

Connectivity indicators designate input and output directions for a given agent depiction. Such indicators are useful when making simulations that involve some sort of flow, such as cars driving on roads, water flowing in a river, and electricity flowing through wires. Running a Full Connectivity script on an agent depiction will perform a number of transformations on the depiction in an attempt to create pieces that can be connected to form paths in the primary directions of North, South, East, and West.

In performing these transformations, connectivity indicators of flow are generated for the new agent depictions as well. These new connectivity indicators reflect the transformations used to generate the new depictions. The automatically generated names for the new depictions also indicate connectivity.

Full Connectivity scripts serve their purpose most effectively when run on fairly regular and symmetric original path depictions. Once a Full Connectivity script is run on a selected agent, the newly created agents will appear in the gallery as shown below for the Street agent.

Make sure you define the base agent's connectivity using the Gallery | Edit Connectivity menu option before running this script.

4 Rotation

4 Rotation starts with an original depiction and performs three 90 degree rotations on it, generating a new depiction after each rotation, to end up with 4 images, including the original. This duplication script works well on images that have an easily recognizable front and back.

Once the 4 Rotation script is selected, the newly created depictions appear in the gallery as shown below for the Auto agent.

Flipper

The Flipper script performs a number of flips of the original image about the x and the y axes. This script works best for depictions that are located mostly in one quadrant of the a cell.

Once the Flipper script is selected, the newly created depictions appear in the gallery, as shown below for the Figure agent.

Power User Shortcut

A duplication script can be run on a depiction by right-clicking on the depiction in the gallery. This will show the following pop-up menu, from which you can select the Run Duplication Script menu option and then choose the script you wish to apply to the selected depiction.

Tools Menu

Description: The Tools Menu is used to access the palettes containing Visual AgenTalk language pieces such as conditions, actions and triggers. It is used to access the simulation properties editor and agent attributes editors, to generate reports and control Conversational Programming. Most of these options are only enabled when an AgentSheets project is open.

The Tools Menu includes the following options:

Conditions Palette Actions Palette Triggers Palette Simulation Properties Agent Attributes Generate report... Turn Conversational Programming On/Off

Conditions

Definition: Conditions are used to test the circumstances agents are in. Among other things, agents can test for the presence of other agents in the worksheet, attribute values, keyboard input, mouse events and even content of live web pages.

Use the Tools | Conditions Palette menu option or click the Conditions tool in the Toolbar to access the Conditions Palette, which contains the following conditions:

See See A Stacked Stacked A Next To Empty Key % Chance Once Every Hear Test Has Attribute WWW Read On Top Of Direction Yes or No Dialog

Power User Shortcuts

A condition can also be accessed and added to the agent's behavior by right-clicking in the part of the rule where conditions reside. This will show the following pop-up menu, from which you can select the Add Condition menu option and then select the desired condition to add. The example below illustrates the addition of the Next To condition.

See Condition

Definition: The See condition checks if the agent at the cell indicated by the Direction parameter looks like the depiction specified in the Depiction parameter. The dot (.) refers to the agent itself.

If the indicated cell contains the chosen depiction, the condition is true. Otherwise, the condition is false.

Parameters: direction, depiction

Example: The Shark agent in the Fish Tank simulation looks above it to see if there is a Fish agent to eat, and also checks to see if the Shark itself looks like a Shark going left and decides to change directions or move to the left.

See A Condition

Definition: The See A condition checks if the agent at the cell indicated by the Direction parameter is of the Class specified in the Class parameter. This command picks out all the depictions of a given agent class. Use it to identify an agent regardless of the way it looks.

If the indicated cell contains an agent of that class, the condition is true. Otherwise, the condition is false.

Parameters: direction, class

Example: The Counter agent in the Benchmark project checks to see if there is a Digit agent to its left and sends the message to "inc" (increment).

Stacked Condition

Definition: The Stacked condition checks if the agent's location in relation to the agent specified by the depiction matches the adjacency choice; that is, the condition checks whether the agent is immediately above, somewhere above, immediately below, somewhere below, or above or below the agent that is specified by the depiction.

If the agent is adjacent to the chosen depiction as specified with the adjacency parameter, the condition is true. Otherwise, the condition is false.

The difference between the Stacked and the Stacked-A conditions is that the Stacked condition checks for a specific depiction/look and is true only if the agent has that exact depiction, whereas Stacked-A checks for any depiction of the given agent and is true regardless of how the agent looks.

Parameters: adjacency, depiction

Example: The Frog agent in the Frogger game checks to see if it is stacked immediately on top of Water, in which case it drowns. It also checks to see if it has reached the goal/target, and if so, it moves to the next level.

Stacked A Condition

Definition: The Stacked A condition checks if the agent's location in relation to an agent specified of type class matches the adjacency choice; that is, the condition checks whether the agent is immediately above, somewhere above, immediately below, somewhere below, or above or below an agent of type specified by class.

If the agent is adjacent to the chosen depiction as specified with the adjacency parameter, the condition is true. Otherwise, the condition is false.

The difference between the Stacked and the Stacked-A conditions is that the Stacked condition checks for a specific depiction/look and is true only if the agent has that exact depiction, whereas Stacked-A checks for any depiction of the given agent and is true regardless of how the agent looks.

Parameters: adjacency, class

Example: The Frog agent in the Frogger game checks to see if it is stacked immediately on above a tunnel, no matter what the tunnel looks like, in which case it gives a message that walking over the tunnel to cross the road is not permitted (it's cheating!), erases the Frog, and stops the simulation. The same happens when the user tries to navigate the Frog on top of a Log Maker.

Next To Condition

Definition: The Next To condition checks to see how many of the adjacent neighbors have a certain Depiction.

If the executing agent is next to the right number of the specified depictions, the condition is true. Otherwise, the condition is false.

Parameters: comparator, formula, depiction

Example: The Person agent in the Virus Attack project checks if it is next to one or more sick Person agents. If so, it has a 5% chance of acquiring the virus.

Empty Condition

Definition: The Empty condition checks if the neighboring cell specified by the Direction parameter is empty. A cell is empty if it does not contain any agents found in the current Gallery.

If the cell indicated by the Direction parameter is empty, the condition is true. Otherwise, the condition is false.

Parameters: direction

Example: In its search for wood, the Termite agent in the Termites project checks if the area to the right or left is empty and has a certain chance (percentage) of moving to that empty position.

Key Condition

Definition: The Key condition checks if the key displayed in its Key parameter is pressed.

If the key indicated is pressed, the condition is true. Otherwise, the condition is false.

The Key condition can be used to assign real-time control characters on the keyboard. You might also use it to assign "hot key" values to get agents to act out specified actions. To get Key conditions to function as hot keys you will have to place them in rules in a method that is checked at every simulation cycle.

Parameters: key

Example: The Cursor agent in the ABC project detects key strokes and types the corresponding letter. For example, if the A key is pressed on the keyboard, the Cursor will create a Character A agent, advance to the right, and identify the newly created character.

% Chance Condition

Definition: The % Chance condition succeeds with a certain percent chance, as specified by a number or a Visual AgenTalk Formula. For instance, with a value of 50 this condition will succeed, on average, 50% of the time.

The % Chance condition chooses a random number between 1 and 100 whenever it is executed. If this number is less than the number indicated in its number field, the condition is true. Otherwise, the condition is false.

Parameters: formula

Example: The Ball agent in the Counting Pachinko project moves down if it does not encounter any obstacle, but when it moves down it also has a 50% chance of going to the left or to the right.

Once Every Condition

Definition: The Once Every condition checks if N seconds have passed since it was last checked. N is specified by a number or a Visual AgenTalk Formula.

If N seconds have passed, the condition is true. Otherwise, it is false.

The Once Every condition acts as a local timer for an agent. Unlike the Wait action, Once Every can be used to slow down individual agents without stopping other agents.

Parameters: formula

Example: In the Voting Game project, the Counter agent polls the voters once every second.

Hear Condition

Definition: The Hear condition checks the agents in its immediate eight-cell neighborhood to see if any of them is "speaking" the specified text using the Say action.

If at least one neighbor is "speaking" the specified text, then this condition is true. Otherwise, it is false.

Parameters: string

Test Condition

Definition: The Test condition compares the values of two formulae.

If the comparison yields true, then the condition is true. Otherwise, it is false.

Parameters: comparator, formula

Example: In the Bridge Builder project, the Brick drops down if the cell below it is empty, and the force acting on it is less than or equal to 0.3 (and therefore cannot hold it in place).

Has Attribute Condition

Definition: The Has Attribute condition checks if the agent in the direction specified by the Direction parameter has the Attribute named in the condition's text field.

If the specified agent has the Attribute named, the condition is true. Otherwise, it is false.

Parameters: direction, attribute

Example: In the Ultimate Pacman project, the Red Ghost agent checks if the agent above it has the attribute p. It then compares this attribute p to the current maxp (the maximum p) and, if p is greater, sets maxp to p. The Red Ghost then changes its facial expression to look as if it is going upwards. This is part of the behavior for tracking down the Pacman agent (see the Ultimate Pacman "Readme" file for a complete explanation of the tracking behavior).

WWW Read Condition

Definition: The WWW Read command searches an entire web page specified by the URL in the URL parameter for the String specified in the first text field.

If the string is found in the web page, a number following that string is read and stored in the attribute specified by the Attribute parameter. The search string can contain wildcards (e.g., "*").

This command should only be used when you already have a live connection to the Internet. If you use this command without a live connection the AgentSheets environment will try to open a connection for you.

Speed depends on the availability of the server you are trying to access.

Parameters: string, attribute, URL

Example: In the Mountain Biking Advisor project, any of the location agents (such as the Bike-Agent, Rabbit-Mountain-Biking, or Sourdough) takes the current temperature and other weather information, such as wind speed, at the specific location by going to a live weather data Web page, such as the UCAR Weather Information web page for Rabbit Mountain, finding the string "Temperature," and storing it into the temp variable, does the same for Wind, announces the temperature, then analyzes the temperature and wind results based on some criteria and advises you what to do if you are planning on going mountain biking there.

Ristretto Information:

Due to the Java applet security restrictions in some browsers, the WWW Read condition may not work in Ristretto-generated applets.

On Top Of Condition

Definition: The On Top Of condition checks whether the agent is on top of a specified type of agent with output connectivity in the specified direction.

If the agent below has output connectivity in the direction indicated by the Direction parameter, the condition is true. Otherwise, the condition is false.

Parameters: class, direction

Example: In the Sustainopolis project, the Auto agent checks to see if it is on top of a piece of road whose output is right. If it is, the Auto agent moves right.

Direction Condition

Definition: The Direction condition checks if the agent is headed in the direction indicated by the Direction parameter.

If the direction of the executing agent is the same as the direction indicated by the Direction parameter, then the condition is true. Otherwise, it is false.

Parameters: direction

Yes or No Dialog Condition

Definition: The Yes or No Dialog condition lets you write programs that can ask users yes/no questions and act based on their answer. Both the questions asked and the labels for the Yes/No answers can be customized by changing the text fields in the condition.

If the user answers "Yes", the condition is true. If the user answers "No", the condition is false.

Parameters: string

Example: You can get control over the Shark in the Fish Tank project and decide whether the Shark eats the fish or not.

When the Shark encounters the Fish, it asks the user whether it should eat the poor little fishy. If you are feeling mean today, tell him to go for it, but if you want to save the fish, tell the Shark to stay away!

Actions

Definition: Actions are operations performable by agents. Actions allow agents to do things such as moving around in worksheets, changing their depiction, playing a sound, or opening up a web page.

Use the Tools | Actions Palette menu option or click the Actions tool in the Toolbar to access the Actions Palette, which contains the following actions:

Move Transport Move Random On Change New Erase Set Color To Make Broadcast Wait Play Sound Say Set Map Plot to Window Plot Attribute Open URL Switch to Worksheet Load Background Set Direction Stop Simulation Reset Simulation Clear Simulation Show Message

Power User Shortcuts

An action can also be accessed and added to the agent's behavior by right-clicking in the part of the rule where actions reside. This will show the following pop-up menu, from which you can select the Add Action menu option and then select the desired action to add. The example below illustrates the addition of the Change action.

Move Action

Definition: The Move action moves an agent one cell in the direction indicated by the Direction parameter. The dot (.) will leave the agent at its current position.

Parameters: direction

Example: In the Rainy Day simulation, the Rain agent drops down with a slight chance of moving diagonally to simulate wind coming from the left.

When the Rain agent can move down no further, it moves left or right.

Transport Action

Definition: The Transport action moves an agent one cell in the direction indicated by the Direction parameter, and also moves all agents that are stacked above it in the same direction. The dot (.) will leave the agent and anything on top of it at its current position.

Parameters: direction

Example: In the Frogger game, the Log agent transports the Frog to the right, if there is one stacked immediately above it, and there is water for them to move on in that direction.

Move Random On Action

Definition: The Move Random On action lets an agent move randomly onto any of its immediate neighbors that show the Depiction displayed in the Depiction parameter. The agent chooses one of its qualifying neighbors to move onto at random.

Parameters: depiction

Example: In the Virus Attack simulation, the Person agent moves randomly on the background tiles.

Change Action

Definition: The Change action changes the depiction of the agent in the cell indicated by the Direction parameter to the depiction displayed in the command's Depiction parameter. The dot (.) refers to the agent itself.

The Change action is useful for creating animations.

Parameters: direction, depiction

Example: In the Fish Tank simulation, whenever the Fish agent faces forward, there is a 10% chance that it will change to look like the fish going to the left and an 11% chance that it will change to look like the fish going to right.

New Action

Definition: The New action makes a new agent in the cell indicated by the Direction parameter. The new agent has the depiction displayed in the action's Depiction parameter.

Parameters: depiction, direction

Example: The Car-Source agent in the Sustainopolis simulation creates new cars on the roads once every six seconds.

Erase Action

Definition: The Erase action erases the agent located in the cell indicated by the Direction parameter. Executing the Erase action is the same as applying the Eraser tool.

Parameters: direction

Example: The Car agent in the Bridge Builder simulation erases itself if it sees a tunnel to its right, so it will look like it is going into the tunnel.

Set Color To Action

Definition: The Set Color To action colorizes the agent with the color indicated in the action's Color parameter.

The Color parameter on the action expands into a full Color Palette when you click and hold the mouse on it.

Parameters: color

Example: The House agent in the Sustainopolis simulation resets to its original color when it receives the "reset" message.

Make Action

Definition: The Make action sends the message specified in the text field to the agent in the cell indicated by the Direction parameter. The dot (.) refers to the agent itself; in this case, the agent sends a message to itself.

The Make action is used in conjunction with On triggers; the receiver can react to the message via the On trigger. These triggers give names to groups of rules (methods) that can be called using the Make action.

By using Make actions and On triggers, a VAT programmer can divide the functionality of an agent in more meaningful chunks.

Parameters: direction, method name

Example 1: In the Voting Game simulation, the Voter agent sends a message to itself. It makes itself reconsider its political views by choosing a random direction around it and making itself adapt to the political views of the voter in that direction.

Example 2: In the Benchmark simulation, the Digit agent sends a message to another agent. When the Digit agent reaches 9, it changes itself to 0 and sends a message to the adjacent digit to the left to increment itself.

Broadcast Action

Definition: The Broadcast action broadcasts a message to all agents of the class indicated in the action's Class parameter.

The message to be broadcast is indicated in the action's text field and is a method call to all agents of the indicated Class.

The Broadcast action is used in conjunction with On triggers; the receivers can react to the message via the On trigger. These triggers give names to groups of rules (methods) that can be called using the Broadcast action.

Parameters: class, method name

Example: The Scanner agent in the How Does TV Work? simulation broadcasts to the TV Beam and Video-Signal agents the message to turn bright or dark, depending on what it scans.

Wait Action

Definition: The Wait action causes the AgentSheets scheduler to wait the amount of seconds indicated by a number or a Visual AgenTalk Formula before executing its next command. Use it to slow down simulations.

Note: The Wait action halts the entire simulation. Another alternative is to use the Once Every condition to selectively slow down portions of a simulation.

Parameters: formula

Example: The Frog agent in the Frogger game has some delays when getting squished by the car/truck so that the animation with the dead frog depiction is visible before the Frog gets erased.

Play Sound Action

Definition: The Play Sound action plays the sound chosen in its Sound parameter.

The predefined set of sounds that AgentSheets features in its Sound parameter can be extended with user-defined sounds.

In AgentSheets, new sound files should be provided in a .wav (WAVE audio file) format. Adding a .wav file to the Resources->Sounds->wav folder will make the sound available upon relaunching the application.

For sounds to be usable in Ristretto-generated applets, the user needs to provide the .au version of the audio file in the Resources->Sounds->au folder.

Please note that the same name, but different extensions need to be used for both .au and .wav files. For example, if you are adding the "explosion" sound file for use both within AgentSheets and in Ristretto-generated applets, "explosion.wav" needs to be added to the wav folder and "explosion.au" needs to be added to the au folder.

Parameters: sound

Example: The Car agent in the Bridge Builder simulation plays an explosion sound when it drops from the bridge.

Say Action

Definition: The Say action prints the text located in its String parameter in the worksheet's status bar.

Unlike its Macintosh version equivalent, the Say action does not yet speak the specified text, since there is no built-in speech synthesizer in Java.

Parameters: string

Example: The Shark agent in the Fish Tank simulation talks to the Fish agent before eating it.

Set Action

Definition: The Set action sets the value of an Attribute of the agent or the value of a Simulation Property to the computed value of a Formula.

The attribute or the simulation property to be set is displayed in the action's text field. The value to set the attribute to is displayed in the action's Formula parameter.

Parameters: attribute, formula

Example: The Factory agent in the Sustainopolis simulation computes pollution as the average of the pollution of the things around it, plus an additional amount which represents the pollution from the factory itself.

The formula used is [(pollution[left] + pollution[right] + pollution[up] + pollution[down])/4.0 + 0.4

Map Action

Definition: The Map action maps the value of an agent's Attribute, a Simulation Property, or a Visual AgenTalk Formula to a Color that lies between two user-specified colors along the color line. The range of the attribute's values to be mapped to a color is specified with numbers or Visual AgenTalk Formulae.

To understand how this action works, you must first understand a little about color cubes and about how humans see color. In general, humans see colors in a three-dimensional color space. Humans have receptors that see red, green, and blue pigments.

You can create any color visible to a human by mixing different spectrums of red, green, and blue pigments together to form a color. Thus, a color cube has x, y, and z axes which represent amounts of red, green, and blue pigment.

Points in a color cube represent colors containing different amounts of red, green, and blue pigment. Black is the color we see when there is no red, no green, and no blue pigment present. White is the color we see when the maximum amount of pigment our eyes can detect is present for red, green, and blue pigments. An image of a color cube is shown below.

A user specifies points in a color cube using the Color parameter. The two points/colors become endpoints for a color line that stretches between them in the color cube.

A user also specifies minimum and maximum numerical values for the attribute to be mapped using numbers or Visual AgenTalk Formulae. These values are mapped to the color endpoints previously mentioned.

As the values of the chosen attribute pass through the user-specified numerical range, the Map action colorizes the agent with a color that corresponds to a point along the color line between the two color endpoints.

Parameters: attribute, color, formula

Example: The Ground agent in the Ultimate Pacman simulation colorizes the diffusion values. Negative values get mapped to a shade of blue, positive values get mapped to a shade of red.

Plot to Window Action

Definition: The Plot to Window action plots the value of the Attribute or Simulation Property named in the action's text field in the window specified to represent a user-specified quantity between endpoints as specified with numbers or Visual AgenTalk Formulae.The value is plotted using a color displayed in the action's color field.

Attribute values are plotted along the y-axis of a 2-D plot window while time is represented along the plot window's x-axis.

To plot Simulation Properties you can also use the plot functionality on the Simulation Properties window.

Parameters: attribute, formula

Example: The Counter agent in the Predators and Prey simulation counts and plots the number of large and small fish living in a pond. It plots the number of small fish in the Population window using yellow color, with the plot ranging between 0 and 150. It also plots the number of large fish in the Population window using red color, with the plot ranging between 0 and 150.

Plot Attribute Action

Definition: The Plot Attribute action plots the value of the Attribute named in the action's text field between endpoints as specified with numbers or Visual AgenTalk Formulae.

The attribute value is plotted using a color displayed in the action's left color field on a background color specified in the action's right color field.

Attribute values are plotted along the y-axis of a 2-D plot window.

Time is represented along the plot window's x-axis. As time passes, plots are marked to the right of the rightmost pixel marked during the previous time step.

This can be understood metaphorically as "advancing the plot paper" a certain distance at each time step. The number of steps the plot advances the "paper" is specified by a number or a Visual AgenTalk formula.

As the plotter drags across the plot paper rolling underneath it, time is represented as lines drawn from left to right (x-axis) while plotted values are read in a vertical direction (y-axis).

The plot window where plots are drawn replaces the agent's depiction. A plot window is as big as the agent that executes the Plot Attribute action.

Parameters: attribute, formula

Example: The Plotter agent in the Counting Pachinko simulation plots the number of balls hitting it between 0 and 100, using a green color on a black background. Each time it is hit, it advances the plotting "paper" 30 steps to simulate the effect of a bar going up every time it plots.

Open URL Action

Definition: The Open URL action opens the address provided as a parameter. The address specified in the text field of the Open URL command can identify a web address or a local file address, which will open in a browser when the action gets executed. If no browser is running, the system will open the default Web browser.

When you use the Open URL action in an applet, please make sure your browser does not block pop up windows. If your browser is set up to block them, then you will not get the new windows that are supposed to be opened with Open URL.

Parameters: URL

Example: In the Grotesque City project, created by high school students for a Language Arts class, the character navigates around a city and opens the appropriate web pages when he encounters buildings that have stories associated with them (the space bar needs to be pressed).

Switch to Worksheet Action

Definition: The Switch to Worksheet action switches to a worksheet specified by the worksheet file name parameter and changes the focus of the simulation to that. If the simulation was running in the original worksheet, it will start running in the new one as well.

This is a useful command when building games with multiple levels.

Parameters: worksheet file name

Example: When the Frog gets to the target (the grotto) in the classic Frogger arcade game, the player moves to the next level, by switching to the worksheet called "Level 2".

Load Background Action

Definition: The Load Background action loads a file specified by the image file name parameter into a Worksheet as a background graphic.

AgentSheets can recognize GIF, JPEG, and PNG file formats.

Backgrounds are required to be located in the "backgrounds" folder inside the "applet" folder of a project (Please refer to Anatomy of a Project for details on the structure of the project folder). If you load a background that does not already exist in the backgrounds folder, the system will copy it there for you.

Parameters: image file name

Ristretto Information:

The background file must be provided in GIF or JPEG format so that it can be loaded in the applet.

Set Direction Action

Definition: The Set Direction action defines the direction in which the agent is heading. The direction is determined by the Direction parameter.

Note: This action does not actually move the agent.

Parameters: direction

Stop Simulation Action

Definition: The Stop Simulation action stops the simulation if it is running. This has the same functionality as pressing the Stop button on the worksheet.

Parameters: None

Reset Simulation Action

Definition: The Reset Simulation action resets the simulation, that is it resets the worksheet to its last saved version. This has the same functionality as pressing the Reset button on the worksheet.

Parameters: None

Clear Simulation Action

Definition: The Clear Simulation action clears the worksheet that is currently running. This has the same functionality as pressing the Clear button on the worksheet.

Parameters: None

Show Message Action

Definition: The Show Message action shows a user-defined message defined by its string parameter in a dialog like the own shown below for a "Game Over!" message.

Parameters: string

Example: In the Space Invaders simulation, when the Cannon agent is hit by an alien bomb, it changes to the exploding depiction, waits some time, erases itself, brings up the message "Your cannon was destroyed. Game over!" and resets the simulation.

Triggers

Definition: The Triggers Palette contains the following Triggers that label method boxes in the Visual AgenTalk language behavior editors:

While Running On Tool When Creating A New Agent Mouse Click

One of these triggers is at the head of every method and determines when the method will be called. For example, any agent's While Running method will be called at each time step while the agent is running its behavior program.

A behavior editor can contain any number of methods. A method is the combination of a trigger and a set of rules. A new behavior editor comes up with a single method containing the While Running trigger and one empty rule.

While Running Trigger

Definition: The While Running Trigger trigger is called once every simulation cycle while the simulation is running.

Parameters: none

Example: While the Vacuum Cleaner simulation is running, the Vacuum agent picks up dirt if it sees it in the cell below, otherwise it just moves randomly on the floor tile.

On Trigger

Definition: On triggers allow you to name methods that will later be called. The method is called when the appropriate message is sent to the agent via a Make action or a Broadcast action from itself or from another agent. The message sent needs to be a valid method name.

Upon receiving a message, an agent calls the method referred to in the message and carries out the actions associated with the first rule whose conditions are all met.

When programming an agent, it is recommended that you divide the agent's behavior into "chunks." It is natural to do this when describing an agent's activity in words. At different times an agent might walk, run, sit, speak, or act in any number of ways. If you focus on walking, you may wish to create one method to describe how an agent walks. You may even wish to create another method to describe how an agent takes a step. We suggest that you divide groups of rules into named methods that make sense for the agents in your specific simulation.

Parameters:Method Name

Example: In the Pascal's Adding Machine simulation, the On trigger is called when the Digit agent gets the "Digit-Inc" message, which causes the number to increment by one.

Tool Trigger

Definition: The Tool trigger is used to program an agent to respond to clicks with the worksheet tools.

The rules located in a method labeled with a Tool trigger are executed whenever the executing agent senses a click from the designated tool, whether the simulation is running or not.

Warning: If you redefine the Arrow, Eraser, and Pencil tools, you will overwrite system functionality as follows:

Arrow - You will be unable to select the agent in the worksheet, if that agent redefines the Arrow tool.Eraser - You will be unable to erase an agent in the worksheet, if that agent redefines the Eraser tool.Pencil - Clicking on the agent that redefines the Pencil tool will execute the rules you specified under the Tool trigger and will not add the agent selected in the gallery to the worksheet. Clicking anywhere else with the Pencil tool will still allow you to add the agent selected in the gallery to the worksheet.

Parameters: Tool

Example: When the Pencil tool is used on the Cell agent in the Game of Life simulation, it toggles between the dead and alive depictions.

When Creating New Agent Trigger

Definition: The When Creating New Agent trigger executes the enclosed rules whenever a new agent is created in a worksheet. These rules are executed regardless of whether the worksheet in which the new agent is created is running or not.

The When Creating New Agent trigger is usually used to initialize the agent's state.

Parameters: none

Example: In the Ultimate Pacman simulation, when a new Pacman agent is created, it initializes its p value to 1000.

Mouse Click Trigger

Definition: The Mouse Click trigger is used to program an agent to respond to a modified or unmodified mouse click.

The rules located in a method labeled with a Mouse Click trigger are executed whenever the executing agent senses the designated mouse click (modified or unmodified), whether the simulation is running or not. The Mouse Click trigger increases the number of ways in which you can interact with your agents.

Parameters: Mouse Click

Example: In the Number Puzzle simulation, a single mouse click with the Arrow Tool on the Digit agent causes it to swap with the empty space next to it. If the Digit is 15, it also highlights the agent before swapping.

Parameters

Definition: A Parameter is an item of information such as a name, a number, a sound, a color, or a selected depiction which affects the operation of a condition, action or trigger command in Visual AgenTalk. For instance, the Sound parameter in the Play Sound action allows you to select a specific sound to be played. When running AgentSheets use the Help | Show Balloons menu option or the Explain button to explore parameters. The following parameters are available in AgentSheets:

Adjacency Attribute Class Color Comparator Depiction Direction Formula Image File Name Key Method Name Mouse Click Sound String Tool URL

Adjacency Parameter

Definition: The Adjacency parameter contains a list of different adjacency specifiers. These include immediately above, somewhere above, immediately below, somewhere below, and above or below and are used to compare positions in the stack of agents in a particular cell.

An extended Adjacency pop up menu is shown below.

Attribute Parameter

Definition: The Attribute parameter identifies an editable name, e.g., "energy", which refers to an agent characteristic. The attribute name provided needs to be a valid name.

The Attribute parameter (called age ) is shown below as part of the Set action.

Class Parameter

Definition: The Class parameter contains a list of all the agent classes housed in the current Gallery. This corresponds to a list of all Agents in a Gallery.

An example of an extended Class menu is shown below.

Color Parameter

Definition: The Color parameter allows users to select different colors visually.

Choose any color by holding clicking on the color parameter and selecting a color from the 256 colors in the Color Palette that pops up when a color parameter is extended:

The new color is set when you release the mouse button and is shown in the collapsed color parameter.

Comparator Parameter

Definition: The Comparator parameter contains a list of different numerical comparison operators. These operators are often used to compare attribute values within and between agents.

A collapsed Comparator parameter is shown on the left and an extended Comparator pop up menu is shown on the right.

Depiction Parameter

Definition: The Depiction parameter identifies an agent by the way it looks.

When you click on a Depiction parameter, a window containing all the depictions located in the current Gallery pops up.

Choose any depiction by holding down the mouse button and highlighting it. Let go of the mouse button and the highlighted depiction will be displayed in the depiction window of the command.

A collapsed (left) and extended (right) Depiction pop-up menu is shown below:

Direction Parameter

Definition: The Direction parameter specifies a direction. The Direction parameter values correspond to the Moore/8-cell neighborhood model. The dot (.) refers to the agent itself.

Click on the operator in its collapsed state to extend it. Then choose a direction by highlighting the preferred direction. A collapsed (left) and extended (right) Direction pop-up menu is shown below:

If the Direction parameter is used in a Condition, it will specify which neighboring cell of an agent (or itself, if the dot is selected) should be tested when executing a condition check.

If the Direction parameter is used in an Action, it will specify which neighboring cell of an agent (or itself, if the dot is selected) the action will be performed on.

Formula Parameter

Definition: The Formula parameter allows users to create spreadsheet-like formulae.

Within the formula field you can call any mathematical functions supported by AgentSheets and Ristretto. This allows arbitrarily complex relationships to be set up using Mathematical Operators that define relationships between attribute or simulation property values within and between interacting agents.

An example of a Formula parameter is shown below in the context of the Set action, where the pollution attribute is being set to the average of the pollution of the agents around it: pollution = (pollution[left] + pollution[right] + pollution[up] + pollution[down]) / 4

Formula Syntax

Definition: Visual AgenTalk (VAT) Formula Syntax is used to create VAT formulas. The following Formula Syntax is accepted by Ristretto :

Operation Definition Example Result

Arithmetic Operations

x + y x - y x * y x / y

Basic arithmetic operations 3 + 4 7

Agent Attribute Access

attribute Access the value of an agent attribute. An agent can have any number of attributes defined by the user

Diameter Diameter * 3.14

value of the agent attribute "Diameter" value of attribute "Diameter" multiplied by 3.14

Remote Agent Attribute Access

attribute[up] attribute[down] attribute[left] attribute[right] attribute[top] attribute[bottom] attribute[row, col]

Access the value of other agents' attribute using relative coordinates. Valid coordinates are up, down, left, right, top and bottom. Coordinates can also be specified numerically as row, column. Valid values for row and column are -1, 0, 1. Positive row values indicates right, positive column indicates down.

age[left] age[top] Temperature[-1,-1] 0.25 * (Temp[left] + Temp[right]+ Temp[up] + Temp[down])

value of the "Age" attribute of agent to the left value of the "Age" attribute of the agent on top value of the "Temperature" attribute of the agent above to the left The average of the value of the "Temp" attribute of the agents left, right, up and down.

Simulation Property Access

@simproperty Access the value of a global simulation property Simulation Properties are used to share information between agents. Users can inspect and edit the values of simulation properties using the simulation property editor. The "@" sign is used to differentiate the simulation properties from agent attributes.

@Time value of simulation property "Time"

Trigonometric Functions

sin(x) Trigonometric function sine, where x is expressed in radians

sin(3) 0.1411

cos(x) Trigonometric function cosine, where x is expressed in radians

cos(3) -0.9900

tan(x) Trigonometric function tangent, where x is expressed in radians

tan(3) -0.1425

Random Number Generator

random(number) Returns a pseudo random number between zero and number . AgentSheets differentiates between integers and decimal numbers. If the number is an integer (e.g. 4), an integer between 0 and number is returned, whereas if number is a decimal number, a decimal number between 0 and number is returned.

random(4.0) random(4)

returns decimal number between 0 (inclusive) and 4.0 (exclusive) returns either 0.0, 1.0, 2.0, or 3.0

Other x ^^ y Exponentiation function. Raises the base number x to the exponent y

15^^4 50625

sqrt(x) Square root function. Takes the square root of number x, where x is a non-negative integer or a decimal number (x>=0).

sqrt(256) 16

x % y Modulo function. Gives the remainder of the division of x / y.

17 % 4 1

Image File Name Parameter

Definition: The Image File Name parameter specifies an image file name.

An example of the Image File Name parameter is shown below, used to load a background image into a Worksheet .

Key Parameter

Definition: The Key parameter indicates a letter, number symbol, or function key on the keyboard.

To define the key that should be tested, click on the button next to the Key label and press the desirable key on the keyboard.

An example of the Key parameter is shown below in the Key condition where the "space" key must be pressed to satisfy the test.

Method Name Parameter

Definition: The Method Name parameter is a string used to name a group of rules in an agent behavior.

The string must be a valid method name. The method name may be used to send a message to an agent via the Make or the Broadcast action to trigger the corresponding On method.

A Method Name parameter ("animate") is shown below used in the On trigger.

Sound Parameter

Definition: The Sound parameter is a list of prerecorded sound effects available to AgentSheets .

An extended Sound parameter menu is shown below:

String Parameter

Definition: The String parameter identifies a word or phrase.

When the string parameter is used in the Say action, it can contain references to agent Attributes or Simulation Properties. For example, if an agent has an attribute called "age" whose value is currently 11, and the String in the Say action is "I am ~age years old", then the Say command would print "I am 11 years old" in the worksheet's message area.

When the string parameter is used in the WWW Read condition, it is a word or phrase that is used to search the specified web page. The string, in this case, can contain wildcards ("*").

An example of the String parameter ("hello") is shown below as it is used in the Say action:

Tool Parameter

Definition: The Tool parameter identifies a Worksheet Tool.

A collapsed (left) and extended (right) Tool parameter is shown below:

URL Parameter

Definition: The URL parameter identifies a Universal Resource Locator, which is a pointer or address that corresponds with a World Wide Web resource.

The URL may identify a Web address or a local file address:

http://<web page address> file:///<local file address>

An example of the URL parameter is shown below in the Open URL action.

Worksheet File Name Parameter

Definition: The Worksheet File Name parameter specifies a file name for a worksheet.

An example of the Worksheet File Name parameter is shown below, used to switch focus to another worksheet (one called "deepsea.ws").

Simulation Properties

Description: Simulation Properties are used to share information between agents. Unlike Attributes, which are local to each instance of an agent, Simulation Properties are global values accessible by all agents. They can be numbers (integers or decimal) used as inputs or outputs for a simulation.

Users can create, inspect and edit the names and values of simulation properties using the Simulation Property Editor, shown below.

To create a new Simulation Property, press the New button. A Property Name dialog, shown below, will prompt you to provide a name for the new Simulation Property.

Type in a valid name and click the OK button. A property called Total is added to the Simulation Properties editor.

Should you need to edit the name of a Simulation Property, select it and press the Edit button and give it a different name.

You can edit the value of a Simulation Property by editing its Property Value field. You can also use the Up and Down arrows to increase or decrease the value of the selected Simulation Property.

Agents can read and write Simulation Properties. For example, in the Virus Attack project, two Simulation Properties are defined, as shown in the editor below:

● Total: a counter for keeping track of the total number of sick people. Every time a Person agent gets sick, it writes the "Total" Simulation Property using the Set action, incrementing it by 1, as shown in the first rule below.

● Infection_Percentage: the percentage a healthy Person has of acquiring the virus. %Chance reads the Simulation Property and uses its value, as shown in the first rule below:

The "@" sign is used to differentiate Simulation Properties from agent Attributes. Please note that you should not add the "@" sign when you are creating the property in the Simulation Properties editor, but you must use it when you refer to a property in a VAT Formula.

You can plot a Simulation Property, by selecting and pressing the Plot button. A window like the one shown below will appear prompting you to select the plotting settings.

We want to plot the "Total" property. We check the plot check box and we specify the following:

● the name of the window we want to plot in (in this case, "Sick Population")

● what the property represents (in this case the "Total Number of Sick People")

● the range of the plotted values, that is, the minimun and maximun numbers to be represented in the plot (in this case, 0 to 80)

● the color of your plot

After deciding on the plotting settings, click OK. When the simulation runs, a plot window (shown below) will appear, if one does not already exist with the same name.

Please note that you can plot multiple values in a single window. For the Predators & Prey simulation, both the number of large and small fish is plotted in the same Population window (shown below). That way you can see the relationship between and the fluctuations of the two populations.

When a plot window is right-clicked with a mouse the following options are available through the following contextual menu:

Set Min/Max Value... enables you to change the plotting range, that is the minimum and the maximum number to be represented in the plot. The following window appears.

Selecting Goto Time... enables you to jump to a particular time value in your plot. The following window appears.

Selecting Export to Excel... allows you to export the data from the current plot window that can contain any number of values being plotted to an Excel spreadsheet. The Save as Microsoft Excel Workbook file dialog appears for you to specify the name and location of the exported spreadsheet.

Reset clears the plot in the current plot window.

Plot Control: Scrolling in available on a plot so that you can scroll back and forth through time.

To scroll to the right, click on the plot window and drag to the right.

To scroll to the left, click on the plot window and drag to the left.

Plotting can also be done within an agent's behavior using the Plot to Window action.

Agent Attributes

Description: Agent Attributes are used to specify information about an agent. Unlike Simulation Properties, which are global to the entire simulation, Agent Attributes are local to each instance of an agent.

Users can inspect and edit the values of agent attributes properties by selecting an agent in the worksheet and choosing Tools | Agent Attributes. If the selected agent has attributes, they will show up in the Attributes Editor. The one shown below contains an agent attribute called "age" whose value is 27.

If the selected agent does not have attributes, the following message will appear in the Attributes Editor.

You can edit the value of an Agent Attribute by editing its value field. You can also use the Up and Down arrows to increase or decrease the value of a specific Agent Attribute.

You do not have to explicitly define a new Agent Attribute in the editor. You can set it by using the Set action in an agent's behavior. It is advised to use a valid name for your agent attributes.

You can map agent attributes to colors using the Map action or plot them in graph windows using the Plot to Window action or in place (in the worksheet) using the Plot Attribute action.

You can test attributes using the Is condition. For example, in the Bridge Builder project, the Brick drops down if the cell below it is empty, and the force acting on it is less than or equal to 0.3 (and therefore cannot hold it in

place). The force is represented as an agent attribute called "UP", as shown in the behavior editor below.

Generate Report

Description: The Generate Report... menu option is used to create a web page containing a comprehensive report about the current project containing agent descriptions and behavior descriptions for all the agents in a project. When the Generate Report menu option is selected, the following dialog appears, prompting you to wait for the report generation to finish.

Once the generation is complete, the generated report will be opened in a browser as shown below.

The generated report also includes behavior descriptions for each of the agents as shown below for the agents of the Virus Attack project.

Conversational Programming

Description: Conversational Programming is a new, radical, patent-pending programming paradigm to help you with programming. Computationally speaking, Conversational Programming is tracking the state of your program, including user selection, as a context for interpretation and is constantly running your program in order to give you informal feedback.

The basic idea is simple. Imagine, that similar to pair programming for professional programmers, you are creating a program together with your programming expert friend. Your friend does not just take over the mouse and write the program for you. After all, (s)he probably does not really know what kind of program you are planning to write. However, using a conversational style of feedback, that is some kind of non-intrusive, informal feedback, your friend can subtly point out potential problems and opportunities that may be very helpful to you. In essence, you are programming in a conversational style through an informal dialog. You change the program or look at specific aspects of your simulation and get valuable feedback.

Conversational Programming is not about static analysis. Linguistically speaking Conversational Programming is not limited to the syntax of your program but - and this is unique - provides feedback about its semantics and its pragmatics. That is, Conversational Programming uses the current context in the worksheet (simulation or game world) to visualize the meaning of your program. Your conversational programming expert friend observes how you interact with your program as well with the objects that you are programming. Say, if you make the game of Frogger in AgentSheets, you select the Frog in your worksheet and look at the program of the Frog. Conversational Programming will not only look at your selected objects and programs but will actually run parts of your program in order to be able to tell you about the consequences of your program. Is this and that condition true or false right now given then state of your Frog? Would a certain rule of your frog be able to fire given the precise situation your selected frog is in? (see example in Example 2 below) What other conditions from the palette could you use that would be true right now? (see example in Example 1 below). This kind of feedback could save you hours of debugging.

Using Conversational Programming

Turn on Conversational Programming by selecting the "On" option from the Conversational Programming drop down menu on the Toolbar (figure below). Alternatively, toggle Conversational Programming on or off from the Tools menu.

For conversational programming to work, you need to have an agent selected in a worksheet. If you do not have an agent selected, or a worksheet open, or even a project open, you will get a warning to do so.

Examples When conversational programming is on, the conditions and rules will be annotated to help you understand what is happening in your program. Two different things will be annotated:

1) Conditions in the Conditions Palette will show up as green if they are true, red if they are false, as showing in the example below for the Frogger game.

Example 1: Conversational Programming in the Frogger Game: Condition Palettes

2) Rules in an agent's Behavior Editor will have a green background when they would fire in the current situation, a red background when they are false and their regular uncolored background when they are not evaluated. Individual conditions will also be annotated in the behavior editor. In this case, conditions will show up as green if they are true, red if they are false, and unchanged (uncolored) if they are not evaluated.

Example 2: Conversational Programming in the Frogger Game: Frog's behavior editor

Conversational programming, if turned on, will consume considerable computer resources. On older machines this could result in flickering of Conversational Programming annotations in the Conditions palette and on slowing down the running simulation.

Windows Menu

Description: The Windows menu gives you a pull-down menu of windows that are currently opened in the AgentSheets environment. You can activate any of these windows by choosing it from the Windows menu.

Web Menu

Description: The Web menu allows you to access AgentSheets resources available on the internet. It includes the following options:

● Bookmarks: a collection of useful Web addresses.

● Project Designs with background information for existing projects, lesson plans, suggested activities, links to standards.

Bookmarks

Description: AgentSheets comes equipped with web browser "Bookmarks" that connect directly to various internet resources. To connect to any of the internet resources listed below, select and hold the Web | Bookmarks menu option to see the list of bookmarks, then select a bookmark and release the mouse. Your web browser will connect to the chosen website, as shown below.

The AgentSheets bookmarks include:

● The AgentSheets Inc. homepage, the official company web pages.

● The AgentSheets Showcase web page, with example simulations and games.

● Scalable Game Design wiki with information such as tutorials, lesson plans, and experience reports from teachers and students using AgentSheets in public schools. This is the official page of a University of Colorado, Computer Science Department research project funded by the National Science Foundation and conducted in collaboration with AgentSheets Inc.

● Scalable Game Design Arcade, an online repository of user-contributed games and simulations. Upload your creates on the Arcade and share with other AgentSheets users.

● Flip Flop Flyin' Minipops Icons: a repository of icons you can use as agent depictions.

Project Designs

Description: AgentSheets provides integration with online design documents, including lesson plans in some cases, that can be used with simulations and games both in formal and informal educational settings as well as for the casual user in the form of suggested activities on how to use the given simulation or game.

The Designs button on the Toolbar allows easy one-click access to activities and background material that have been created for a given project. If no project has been opened, the design button will link to an index of all designs that currently exist.

The designs reside on the Scalable Game Design wiki. These designs can include background information, suggested activities, lesson plans, links to educational standards and, in some cases, support material for grading.

If a project is currently open in AgentSheets, the link leads to the design for the project that shares the same name as the currently opened project. For instance, if the "Frogger" project is open, the "Frogger Design" link appears. This leads to the existing design page for Frogger as shown below.

Among other things, this Frogger design page includes links to step by step tutorials and videos for building the Frogger game as well as prerequisite skills for building Frogger, objectives of the activity, the computational thinking patterns it uses, and the educational technology standards this activity covers.

If no such design exists for the currently open project, you will have the opportunity to create one on the wiki. The design button will link to a new wiki page, as shown below for a new project called "My new cool game". There, you will be able to begin a collaborative design wiki page for the given project by clicking on "edit this page" (#1 in picture below). Our Scalable Game Design wiki does not support anonymous editing. Please make sure you log in if you already have an account or create a new account on our wiki (#2 in picture below).

If your project has the same name as one with an existing design, and you want a separate design to be linked to that, you can change the name of your project to something unique. You can do this in the Finder (on a Mac) or the Windows Explorer (on a PC) by simply renaming the project folder when your project is closed. Your project folder resides at the default location for projects (the Desktop) or the location you chose to save it at the time you were creating the project.

Help Menu

Description: The Help menu allows you to get access to the documentation of the AgentSheets software.

The Help | Getting Started menu option opens the Getting Started PDF document, which contains among other things a step-by-step tutorial on how to build a simulation from scratch.

The Help | Language Reference menu option opens the Language Reference PDF document, which contains descriptions of all the Visual AgenTalk conditions, actions, triggers and parameters.

On Windows, the Help | About AgentSheets menu option opens a dialog box like the one shown below, with information (such as version number) about the software. On the Mac, this is accessible from AgentSheets | About AgentSheets

Depiction Editor

Description: The depiction editor allows you to easily draw and edit your own agent depictions or import existing artwork and use it as agent depictions. The depiction editor comes equipped with a toolbar along the left side of the editor with standard drawing tools, a menu bar on top and buttons at the bottom.

The depiction editor tools components, such as the Default Color Palette, the Tranparent checkbox, the Depiction Preview, the Tools and the Buttons are described below.

Default Color

Palette

The Default Color Palette (shown below) contains a few basic colors you can use in drawing your depiction without having to use the Color | Color Chooser menu option. To select a color, just click on one with the mouse. The big square on the left shows the currently selected color.

Transparent Checkbox

The Transparent checkbox (shown below) is used to mix colors. When the box is checked, the drawing tools (Pencil, Fill Rectangle, Fill Circle, Draw Rectangle and Draw Circle) will mix the currently selected drawing color with the color already placed within the target area.

Depiction Preview

The Depiction Preview shows you the depiction you are currently editing at its actual size. If the size of the agents exceeds 90x90, the Depiction Preview shows the depiction resized at 90x90.

The Arrow Tool The Arrow Tool drags pixels of the displayed depiction within the depiction editor.

The Pencil Tool The Pencil Tool draws pixels in the editor with the color currently selected in the Ink Color Palette (see below).

The Eraser Tool The Eraser Tool erases parts of a depiction. You can use this tool by clicking on pixels one at a time or by holding down the mouse and dragging the eraser around the screen. The eraser only erases pixels within the confines of the depiction editor.

The Fill Tool The Fill Tool fills in any closed region of a depiction with the color selected in the Ink Color Palette.

The Color-Picker Tool The Color-Picker Tool samples from colors in the depiction. Click with the Color-Picker on any pixel of the depiction. The color of that pixel will appear as the selected color in the Ink Color Palette and will be used as the current drawing color.

The Fill Rectangle Tool The Fill Rectangle Tool fills a rectangular region with the currently selected color. Choose the Fill Rectangle Tool from the toolbar and define a rectangular area to be filled by clicking and holding the mouse while dragging the mouse. The region will be filled by the designated color once the mouse button is released.

The Draw Rectangle Tool The Draw Rectangle Tool draws the outline of a rectangle using the currently selected color. Choose the Draw Rectangle Tool from the toolbar and define a rectangular area by clicking and holding the mouse while dragging the mouse. The rectangular region will be outlined with the designated color once the mouse button is released.

The Fill Circle Tool The Fill Circle Tool fills a circular region with the currently selected color. Choose the Fill Circle Tool from the toolbar and define a circular area to be filled by clicking and holding the mouse while dragging the mouse. The region will be filled by the designated color once the mouse button is released.

The Draw Circle Tool The Draw Circle Tool draws the outline of a circle using the currently selected color. Choose the Draw Circle Tool from the toolbar and define a circular area by clicking and holding the mouse while dragging the mouse. The circular region will be outlined with the designated color once the mouse button is released.

Undo Button

The Undo button reverts the last drawing action.

Clear Button

The Clear button completely erases the current depiction from the depiction editor window.

Done Button

The Done button closes the depiction editor window and saves the changes you have made to the current depiction.

Cancel Button

The Cancel button cancels editing a depiction and closes the depiction editor window without saving any of the changes you have made to the current depiction.

Camera Button ( Mac Only)

The Camera button enables you to capture images from your Mac's built-in or external iSight camera, for use as a depiction.

Depiction Editor Camera Image Capture ( Mac Only)

Description: Click on the Depiction Editor's Camera button and you will get the built-in interface for capturing pictures using your computer's camera, as shown below. Clicking on the Camera button again will countdown and take a picture of you - or whatever else is in front of the camera at the time.

Once you have a image you would like to use, you can use the interface and tools provided to center it and resize it the way you want it. The interface also provides effects you can apply to your picture, by clicking on the Effects button . A list of available effects will pop up and you can select one, if you would like to use it.

Once the image is the way you like, click on the Set button to commit it as a depiction of the agent in the Depiction Editor. Click the Done button and the image is now your agent's new depiction, as shown below for the "Me" agent.

Depiction Editor Menus Description: The depiction editor's menus are used to import images, save the depiction,

close the depiction editor, choose colors, and choose color masks for the depiction.

The depiction editor includes the following menus:

File Menu

Edit Menu

Color Menu

File Menu

Description: The depiction editor's File Menu is used to import images, save the depiction and close the depiction editor.

The depiction editor's File Menu includes the following options:

Import Image... Save Close

Import Image...

Description: The depiction editor's File | Import Image menu option allows you to import artwork created in 3rd-party graphic design tools and use it as your agent's depiction. A dialog like the one below appears, prompting you to choose the image file to import. Please note that you can only import GIF files.

Save

Description: The depiction editor's File | Save menu option saves changes to the current depiction without closing the depiction editor window.

Close

Description: The depiction editor's File | Close menu option closes the depiction editor. You can also close the depiction editor by clicking on the Done button.

If, for example, you attempt to close a depiction editor that contains a depiction that has been changed since it was last saved, you will see the alert box shown below.

If you would like to close the depiction editor without saving the changes that were made since last saving the depiction, click No. The depiction editor will be closed, but changes will not be saved.

If you no longer wish to close the depiction editor, click the Cancel button to return back to the depiction editor.

If you would like to save all changes made to the depiction (thereby replacing the previously saved version), click Yes. The new depiction will replace the old one in the gallery.

Edit Menu

Description: The depiction editor's Edit Menu is used to undo the last painting action or clear the entire image in the depiction editor.

The depiction editor's Edit Menu includes the following options:

Undo Clear

Undo

Description: The depiction editor's Edit | Undo menu option reverts the last change you have made to the current depiction.

You can also undo the last drawing action performed using the Undo button at the bottom of the depiction editor.

Clear

Description: The depiction editor's Edit | Clear menu option clears the depiction image in the depiction editor.

Use this option when you want to delete the entire image, for example, when you want to delete the default depiction of your newly created agent and start drawing your own depiction.

You can also clear the current depiction using the Clear button at the bottom of the depiction editor.

Color Menu

Description: The depiction editor's Color Menu is used to choose colors for drawing your agent's depiction or to define a mask color for the depiction, if necessary.

The depiction editor's Color Menu includes the following options:

Color Chooser Mask Color

Color Chooser

Description: The depiction editor's Color | Color Chooser menu option allows you to select colors to be used in creating your depictions. The following Choose Color dialog appears

You can select the color you would like to use in drawing your depiction by clicking on it and click OK. If you wish to cancel the color selection and close the color chooser, click Cancel. If you wish to reset the color selection and revert to the original color, without closing the color chooser, click Reset.

You can currently use three types of color choosers: the swatches (shown above), the HSB, or the RGB color choosers (shown below).

With the HSB color chooser, you can specify a color using Hue, Saturation and Brightness values.

With the RGB color chooser, you can specify a color in the color cube using Red, Green, and Blue values. See the explanation of the color cube in the Map command.

You can also choose a color from the default color palette, located below the menus in the depiction editor, without using the Choose Color dialog.

Mask Color

Description: The depiction editor's Color | Mask Color menu option allows you to define a mask color for the agent depiction being edited in the depiction editor. Masks are like filters or films of a given color that cover the cell a depiction inhabits. They are useful, if you wish to make part of the agent depiction transparent. Mask Color choices are described below.

None

The Color | Mask Color | None option specifies that the depiction of your agent will have no mask. Agent depictions with no mask completely cover agents below them.

White

The Color | Mask Color | White option specifies that the depiction of your agent will have a white mask. This means that the part of the agent depiction that was white will be transparent. The use of a white mask is good for making simulations where cars drive on roads, for example. Cars travel on top of roads and cover only portions of the road. The rest of the road should be visible underneath the car.

Upper-Left Pixel Color

The Color | Mask Color | Upper-Left Pixel Color option specifies that the depiction of your agent will have a mask of the same color as the upper left pixel of the depiction. Your agent depiction will become transparent at those pixels with the same color as the pixel in the upper left corner of the depiction.

Custom...

The Gallery | Mask Color | Custom.. option allows you to select a mask color for your depiction. A Choose Color dialog will appear (shown below), prompting you to select a color from the available color palette and set it as

the mask color.

Use the Choose Color dialog as you would use it for selecting a color (see Color | Color Chooser menu option)

Worksheet

Description: AgentSheets worksheets come equipped with a toolbar along the left side of the window, a set of buttons at the bottom, and a message area right above the buttons. The tools are described below.

The Arrow Tool The Arrow Tool drags agents around within a worksheet and selects agents. To move an agent, click and hold on the agent and move the mouse to the desired location. Once you release, the agent is in the designated place in the worksheet. Also, use the Arrow Tool to select agents in the worksheet by single-clicking them.

Power User Shortcut

When permissible, you can right-click on an agent in the worksheet using the Arrow Tool to change its depiction, assuming the agent has more than one depictions defined in the gallery. A pop-up menu with the list of available depictions appears as shown below for the Person agent. You can then choose the depiction you wish to change to.

The Pencil Tool The Pencil Tool adds agents to a worksheet. To use the Pencil Tool, select an agent's depiction in the gallery and, in the worksheet, click where you would like the selected agent to be placed.

The Eraser Tool The Eraser Tool erases instances of an agent in the worksheet. Click on an agent with the Eraser Tool to make the agent disappear.

The Hand Tool The Hand Tool is user-defined. Agents can be programmed to respond to the Hand Tool using the Tool trigger found in the Tools | Triggers Palette. If the Hand Tool is not specifically programmed for an agent, applying that tool on that agent just gives a warning in the worksheet's message area: 'I don't know how to respond to the "operate_on" message'.

The Hammer Tool The Hammer Tool is user-defined. Agents can be programmed to respond to the Hammer Tool using the Tool trigger found in the Tools | Triggers Palette. If the Hammer Tool is not specifically programmed for an agent, applying that tool on that agent just gives a warning in the worksheet's message area: 'I don't know how to respond to the "whack" message'.

The Draw Rectangle Tool The Draw Rectangle Tool places multiple agents in a worksheet. Like the Pencil Tool, the Draw Rectangle Tool requires that an agent in the current gallery be selected. The Draw Rectangle Tool creates a box that expands as a user clicks and drags within a worksheet. Once the mouse is released, the designated rectangular area is filled with instances of the selected agent.

The Erase Rectangle Tool The Erase Rectangle Tool erases multiple agents in a worksheet. It creates a box that expands as a user clicks and drags within a worksheet. Once the mouse is released, the top-layer agents in the designated rectangular area are erased.

The Question Mark Tool The Question Mark Tool provides the position and name of the agent on which it is applied. To use the tool, click an agent in the worksheet. You will see the following message appear on the worksheet's message area.

The example is the result of clicking a Digit agent in the Benchmark simulation using the Question Mark Tool and shows the current position of the Digit.

The Stop Button

The Stop button stops the simulation, if it is running in the worksheet.

The Run Button

The Run button starts the simulation, if it is not already running in the worksheet. When the simulation is running, all agents with a While Running method execute the behavior defined in that method.

The Step Button

The Step button executes one simulation cycle each time it is clicked.

The Reset Button

The Reset button resets the worksheet to the last saved version.

The Clear Button

The Clear button clears the worksheet. If the worksheet contains a background, it does not get removed. Use File | Remove Background to remove a background.

Simulation Speed Control Slider

The Simulation Speed Control Slider, shown below, enables you to control the speed with which your simulation is running. Set the slider to "Fast" for running your simulation in full-speed, to "Slow" for the slowest possible execution of your simulation, or to any value in between as you see fit for your simulation.

Worksheet Message Area

The worksheet Message Area, shown below, prints text message from the system (e.g. when a worksheet is loading), from the running simulation (e.g. from the Say action), or from user interactions (e.g. from applying some worksheet tools on agents in the worksheet).

Valid Agent Names

When a new agent is created, you need to make sure that the name you are providing is a valid one. Here are the rules for giving your agents valid names:

● Agent names need to be unique ● An agent name cannot be a number (e.g. "35"), but can contain numbers (e.g. "Bob35") ● Every character in the name needs to be an alphanumeric character (0-9, a-z, A-Z). A

name can also contain dashes (-), underscores (_) ● Spaces or dashes in the name will be replaced with underscores (_) ● The length of agent names should not exceed 20 characters ● Agent names cannot be words that are reserved by AgentSheets (e.g.

__mysimulation__)

AgentSheets will warn you if you violate these rules.

Valid Attribute and Simulation Property Names When a simulation property is created or renamed, or when an attribute is used in an agent's behavior, you need to make sure that the name you are providing is a valid one. Here are the rules for giving valid names to agent attributes and simulation properties:

● Attribute and simulation property names need to be unique ● An attribute or a simulation property name cannot be a number (e.g. "11"), but can

contain numbers (e.g. "Range1") ● Every character in the name needs to be an alphanumeric character (0-9, a-z, A-Z). A

name can also contain underscores (_). Unlike agent names, attribute and simulation property names cannot contain dashes (-), as they will be perceived as the minus arithmetic operator when the attribute or simulation property is used in a VAT formula.

Valid Method Names When a method is named in an On trigger, or a method is called via the Make or the Broadcast action, you need to make sure that the name you are providing is a valid one. Here are the rules for giving valid names to methods:

● Method names need to be unique ● Every character in the name needs to be an alphanumeric character (0-9, a-z, A-Z). A

name can also contain dashes (-), underscores (_) ● Spaces or dashes in the name will be replaced with underscores (_) ● For compatibility with the Macintosh version of AgentSheets, method names cannot be

the same as existing system methods, which should not be overwritten. System methods include some Visual AgenTalk actions, such as "Move" and "Broadcast".

AgentSheets will warn you if you violate these rules.

SimWhatever.

AgentSheets®

Corporate Headquarters AgentSheets Inc. 6560 Gunpark Dr. Suite D Boulder, CO 80301 USA http://www.agentsheets.com Tel: (303) 530-1773 Fax: (303) 530-3018