AgentSheets
Reference Manual
What If?
AgentSheets®
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 Manual
AgentSheets 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, email 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 singleclicking 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 rightclicking 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 rightclicking 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 VideoSignal 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:
Ristretto
Information:
image file name
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 :
Definition
Example
Result
Arithmetic
Operations
x+y
x-y
x*y
x/y
Operation
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
value of the agent attribute "Diameter"
Diameter * 3.14
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.
age[left]
age[top]
value of the "Age" attribute of agent to the left
value of the "Age" attribute of the agent on top
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.
Temperature[-1,-1]
value of the "Temperature" attribute of the agent above to the left
0.25 * (Temp[left] + Temp
[right]+ Temp[up] + Temp
[down])
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
@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 .
random(4.0)
returns decimal number between 0 (inclusive) and 4.0 (exclusive)
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)
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
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.
returns either 0.0, 1.0, 2.0, or 3.0
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 nonintrusive, 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
Turn on Conversational Programming by selecting the "On" option from
Conversational the Conversational Programming drop down menu on the Toolbar
Programming
(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 usercontributed 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
Transparent
Checkbox
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.
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 (
Description:
Mac Only)
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
. A list of available effects will pop up and you can select one, if you would like to use it.
Effects button
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