
	       Tileworld (The X Window System Version!) 
				Copyright 1990, Martha E. Pollack

			     USER'S GUIDE

The Tileworld system was designed and developed at SRI International,
Menlo Park, CA, by Martha E. Pollack, Michael P. Frank, and Marc
Ringuette.  This User's Guide was written by Michael P. Frank.
		   

CONTENTS (Search for these strings)
-----------------------------------
Introduction
A Simple Demo
Basic Usage
Displaying on Different Hosts
Loading Experiment Files
Game, Set, Match
The Experiment Control window
The World Parameters window
The Agent Parameters window
The Tile World window
The Object Information window
Experiment files


Introduction
------------

Tileworld is an interactive facility for running simulations of
different agent architectures operating in a simple environment called
the Tile World.  The program shows a graphic X-windows display of the
simulation while it is running, accompanied by windows showing data
about the simulation.  The user can start and stop the simulation at
will, change parameters of the agent and world on the fly, and load
and save experiment-files specifying entire sets of parameters to use.
Tileworld can also run long sets of experiments, automatically
recording results with no user intervention.  Tileworld's
user-interface is easy to use, and its displays look equally good on
either a black-and-white or a color monitor (meaning, they're
black-and-white).


A Simple Demo
-------------

If tileworld has been installed properly, all you'll need to do to see
a simple demo is:
(1) Invoke Lisp from the directory containing the Tileworld system.
In this document we call this the "~tile" directory, but this should not
imply that one needs a "tile" user.  Details about which version of
Lisp is needed are given in the Installation Guide.
(2) Type (load "tw")
	to load the Tileworld system
(3) Type (run)
	to begin a demonstration of a simple default experiment
After you've done this, a bunch of windows will appear.  Move the
windows around, using your favorite window manager, until you can see
the window titled, "Experiment Control."  Click a mouse button on the
little raised bump that is labeled "Start or Continue Game."  Now move
things around until you can see the window labeled "Tile World."
There should be a little circle with an arrow on it, moving around in
the grid, pushing the square tiles around and filling up the indented
holes with them.  That's the agent, playing a Tileworld game!  When
you've seen enough, go back to the Experiment Control window and click
on "Quit Tileworld System", and everything will go away.  If you want,
you can then type (run) again to Lisp to bring 
Tileworld back up with the default settings again.


Basic Usage
-----------

Tileworld's user-interface is controlled by only two different
mechanisms (with one exception, see the Tile World Window).  These
are: (1) Buttons, and (2) Editable fields.  Both of these items may be
found in dialog boxes, which are the three small windows with the dark
grey background that appear when tileworld is started.  Currently, the
only buttons are in the Experiment Control dialog window.  Buttons are
rectangles that look like raised bumps on the background and have
identifying text written in them.  Fields, on the other hand, may be
found in all of the dialog boxes.  A field consists of text in a black
rectangle that looks indented, to the left of which there is some text
that identifies the field.  

To use a button, position the mouse pointer over it and click any
mouse button, exactly once.  The text in the button will flash briefly
in response.  Sometimes there may be a delay in the response, but this
does not mean your click was not registered.  There is no reason to
repeat your click while waiting for a response.

To use an editable field, click anywhere on the text in the black box.
A rectangular cursor will appear at the end of the text.  You may use
backspace or delete (depending on your keyboard) to erase the text in
the field, and you may type non-shifted characters to add text to the
field.  Currently, the shift keys are not supported, so there is no
way to get uppercase letters and shifted special symbols into a field.
Do not hit shift or the text "LEFT-SHIFT" or "RIGHT-SHIFT" will appear
in the field.  (We plan to fix all this soon, so never fear.)  When the
text is like you want it, hit Return (or Enter or whatever).  If the
text you entered in that field was acceptable, the text cursor will
disappear.  If the cursor does not disappear, then the text you
entered was invalid in some way, and you will have to try a different
value.  (In future versions, there will be more detailed feedback.)

Note: the text cursor will not appear in more than one editable field
at once.  This means that as long as the cursor is still showing in
one field, you will not be able to select another.  Enter a good value
in the first field, press return, and then click the mouse on the
other field.

Tileworld basically has only two modes: stopped, and running.  When
you first '(run)' tileworld, it normally comes up in the stopped
state.  To control what state tileworld is in, use the buttons in the
Experiment Control window labeled "Start or Continue Game" and "Stop
(Pause) Game".  These do what they claim.  Also, whenever you select a
field for editing while tileworld is running, tileworld will stop
temporarily, so that there will be better response-time for the
text-editing.  Tileworld will resume activity as soon as you enter an
acceptable value for the text field.  For certain fields, the new
value may take effect instantly.


Displaying on Different Hosts
-----------------------------

Since X-windows is network-transparent, Tileworld may be executing on
one machine while displaying on another - even if the two machines
have different display characteristics, or are on opposite sides of
the continent!  (This has actually been tested.)

To tell Tileworld where to display, go to the machine that will be
running Tileworld, and set the environment variable DISPLAY to the
internet name of the machine on which to display.  Most X programs
require that DISPLAY be followed by a colon and the display number and
screen number.  However, tileworld will ignore everything after the
colon.  Set DISPLAY before running lisp so that the environment
variable will be present in the Lisp process.  On the machine with the
display you will be using, execute the xhost command, and give it, as
an argument, the internet name of the machine running Tileworld.  If
the display machine has more than one display or more than one screen,
Tileworld will always just use the default ones.

An alternative way to tell Tileworld what the host is, that does not
require exiting Lisp, is to type (setf xtile::*hostname* "foo") - if
the hostname is "foo" - to a Lisp prompt before, typing (run).  You
must also still do the 'xhost' on the displayer host.


Loading Experiment Files
------------------------

The '(run)' function may be given an optional single argument, which
is a string naming an experiment file to load.   An experiment file
is a lisp file that tells tileworld how to set up the parameters for
the world and agent for the various games that make up the experiment.
If the argument is not provided, run defaults to the filename it
was given on the previous run, or to "default.exper" if no filename
has ever been given (since lisp started).

Tileworld always searches for experiment files in the directory
named by xtile::*experiment-dir-name*, which by default is set
to the ~tile/xtile/experiments directory in the tileworld system.

Another way to load an experiment file is to enter its name in
the "Load:" field of the Experiment Control window, and then click
on the "Reload Experiment File" button.


Game, Set, Match
----------------

In executing long series of experiments, there are three different
levels on which we can identify parts of the simulation.  We have
informally adopted the terms "Game", "Set", and "Match" from tennis to
identify these three levels, because they are terms whose relationship
is already understood.

A "Game" is the smallest unit of simulation, a single run of the
simulation with a single set of parameters and a single configuration
of obstacles.  A game is the thing that ends when the "Time Remaining"
field in the "World Parameters" dialog runs to zero.

A "Set" is a contiguous series of games that only differ from each
other in the configuration of holes and obstacles in the world, due to
the presence of a different random-number seed.  A set ends when the
"Seeds Remaining" field in the "World Parameters" dialog runs to zero
and the final game ends.  A set may contain only one game if the
"Seeds Remaining" field is zero.

A "Match" is a bunch of sets that are meant to be played together, and
are usually loaded together all at once from a single, large
experiment file.  The sets in a match may all have different
parameters, but it is intended that there be some rationale for the
grouping together of the sets - perhaps they represent a group of
variations on some basic experiment.  A Match may contain only one
set, if only one set of settings was saved.



The Experiment Control Window
-----------------------------

Currently there are 9 fields and 6 buttons in the Experiment Control
window.  All these fields are saved along with agent and world
parameters when the "Save Current Settings" button is pressed, except
for the "Save Time" field, which is different every time you save.

Save Time: - This field shows the timestamp associated with the
	current set of parameters, indicating the time at which that
	set of parameters was saved.  It is in the form of a list
	containing numbers representing the year, month, day, hour,
	minute, and second, in that order.  This field may not be
	changed.  It's also not saved, in that each saving creates a
	new value for the field.

Load: - The name to use to load experiment-specification files, if the
	"Reload Experiment File" button is pressed.  The file must be
	in the directory named by xtile::*experiment-dir-name*.  If
	the file is named "foo.lisp", either "foo" or "foo.lisp" are
	sufficient for loading the file.

Save: - The name to use to save experiment-specification files, if the
	"Save Current Settings" button is pressed.  The file will be
	saved in the directory named by xtile::*experiment-dir-name*.
	Since the file saved is actually a file readable by lisp, it
	is recommended (but not necessary) that the name in the "Save"
	field have a ".lisp" extension.

Keep History? - This yes-or-no field indicates whether to record a
	trace of the agent's mind for every game in the current set.
	Upon every game, the old version of the history file is
	renamed to a non-colliding name, and the new game's history
	data goes into the history file.  For a change to this field
	to take effect, the current game must be reset, or a new game
	must start.

History: - The name of the file (in the directory named by xtile::
	*experiment-dir-name*) in which to save history data.  For a
	change in this field to take effect, the current game must be
	reset, or a new game must start.

Keep log? - Yes-or-no value indicating whether to record a log of
	parameters and scores for every game in the set, together with
	an average score for all games in the set, when the set ends.
	A change to this parameter will take effect every time
	something is logged, which usually occurs when a game is
	completed.

Log: - The name of the file (in xtile::*experiment-dir-name*) in which
	to record logging data.  A change takes effect instantly.

Series: - Just a place to notate the name of, or a comment about, the
	current match.

Experiment: - A place to notate the name of, or a comment about, the
	current set.

Start or Continue Game - This button causes the simulation to start
	running, or to continue wherever it left off, if it was
	paused.  This state of running may continue from game to game,
	or may require pressing this button to start every game,
	depending on the "Wait between seeds?" and "Wait after all
	seeds?" fields in the World Parameters dialog box.

Stop (Pause) Game - Simply pauses the simulation until Start is
	pressed.

Reset to Beginning of Game - Resets the state of the simulation to the
	state it was in at the start of the current game.  Notices new
	settings for "Keep History?" and "History:".  Resets "Time
	Remaining" to "Game Length" in the World Parameters window.

Save Current Settings - Saves the values of all the fields in the
	Experiment Control, World Parameters, and Agent Parameters
	windows (this determines an entire "set" of games) into the
	file named by the "Save:" field of the Experiment Control
	window.  The file is put in the directory named by
	xtile::*experiment-dir-name*.  If the file already exists, the
	current settings will be appended onto the end, so that when
	the file is loaded in it will specify an entire "Match" of
	sets.

Reload Experiment File - Loads all the parameter-sets that are
	specified in the file named by the "Load:" field, in the
	directory named by xtile::*experiment-dir-name*.  Currently,
	the sets in the file are loaded in reverse order, so that the
	last one specified in the file is the first one played, and so
	on.  This may change in the future if needed.

Quit Tileworld System - Quits the program, without saving any parameters.
	Log files and history files will be closed.  Tileworld will
	exit to Lisp, where the user can type (run) again to restart
	the system.


The World Parameters Window
---------------------------

The World Parameters window currently contains 11 fields.

World name: - An optional name or short comment about the world
	settings, intended to help the user remember the significance
	of the particular choices for the parameters.

Speed: - The relative speed of the world, currently, the rate of
	appearance and disappearance of holes.  This must be
	a floating-point number.  The default, normal speed is 1.0.
	2.0 would mean twice as fast as 1.0.  The units are not
	absolute.  Changes take effect instantly.

Score range: - A pair of numbers of the form "25-75", or more
	generally, "nn-nn", indicated the lower and upper bounds on
	the range of score values, number of points, that a hole in
	the world may be "worth."  Actual score values are chosen at
	random from within this linear range of values.  Currently,
	only positive values are accepted for the two integers.
	Changes take effect whenever a new hole is created or the game
	is reset.

Size range: - Same as score range, except it determines the number
	of grid squares that holes may cover, such as "1-4".

Game length: - Determines the total length of the game, in simulated
	milliseconds or something.  If it is changed, Time Remaining
	will change accordingly, depending on the time elapsed so
	far in the game.

Time remaining: - Time left before the end of the game, in simulated
	milliseconds.  This should change continuously while the
	simulation is running.  It may be changed interactively during
	the game to make the game longer or shorter.  It is better to
	change Game Length, though, because if Time Remaining is
	changed directly, Game Length will no longer be correct.

Score: - The score earned by the agent so far in the current game.
	This may not be changed by the user.

Current seed: - The random-number seed used to generate the appearance
	and behavior of the world in the current game.  Changes take
	effect when the game is reset or a new game starts.  When the
	game ends, if there are "Seeds Remaining", tileworld
	automatically increments the number in this field.

Seeds remaining: - How many seeds to use after the current one, i.e.,
	how many games to play after the current one, before the end
	of the set.  Changes take effect right away.  Must be zero
	or positive.

Wait between seeds? - A yes-or-no value indicating whether tileworld
	should automatically pause the simulation whenever a new
	seed is chosen, i.e., whenever a new game starts.

Wait after all seeds? - A yes-or-no value indicating whether tileworld
	should automatically pause the simulation whenever a new
	set starts, i.e., when all the seeds run out.


The Agent Parameters Window
---------------------------

Currently there are only four fields in the Agent Parameters window.

Agent name: - An optional name or short comment, intended to help the
	user remember the significance of the particular parameter
	values that follow.

Speed: - The agent's relative speed of operation.  The normal, default
	speed is 1.0.  2.0 would be twice as fast.  These are not
	absolute values.  However, they do correspond to world speeds.
	For a realistic simulation, world and agent speeds would be
	the same.  The value must be a floating-point number.
	Changes take effect immediately.

Eval-func: - The name of the lisp function that the agent will use for
	evaluating different plans.  Currently only two values are
	allowed: simple-evaluate and seu-evaluate.  Changes take
	place instantly.

Threshold: - An integer representing how much better than the
	currently- best hole a newly-appearing hole must be to catch
	the attention of the agent.  May be positive or negative.
	Changes take effect immediately.


The Tile World Window
---------------------

The Tile World window displays the current state of the tileworld
game.  A grid of fine black lines covers the window.  Empty
grid-squares appear as a plain grey (actually a black-and-white
stipple pattern) background.  Obstacles appear as lighter raised
bumps.  Holes appear as darker indentations.  The hole's score-value
appears in the hole.  A hole may cover several grid cells, but the
score will appear in only one cell, to indicate that the score is
earned for filling the entire hole.  If the grid cell containing the
score is filled in, the score jumps to another cell making up the
hole.  (There is a bug that causes the score to appear more than once
if the agent falls into the part of the hole containing the score.)
If two holes appear adjacent to each other, a thin white line will
appear between them to distinguish the two.  (This line unfortunately
may not always disappear when one of the two holes disappears.)  Tiles
appear as smaller raised bumps the same color as the background.  The
agent appears as a white circle with a grey center, overlaid with a
black arrow indicating direction of movement, when the agent is moving
instead of thinking.

The size of the Tile World window is flexibly derived from the size of
the font being used to display scores inside the holes.  Three
functions are provided that can be called before typing (run) in order
to set up the font, and thus the world window, to be three different
sizes.  These functions are (small), (medium), and (large).  E.g., to
get a smaller world window, type (small) and then type (run) to start
tileworld in that smaller size.


The Object Information Window
-----------------------------

More information may be found out about certain objects in the world
(currently limited to hole objects) by clicking the mouse button on
the object.  A small window will appear showing various data about the
object.  Clicking in this small window or clicking on the Tile World
background will make the small window go away.  Clicking on another
hole will put that hole's data into the window.  For holes, this
information includes the time (in simulated milliseconds) that the
hole will remain in the world before disappearing.


Experiment Files
----------------

In addition to being loaded and saved from within Tileworld,
experiment-specification files may be concatenated together to produce
whole series of experiments, or edited by the user to allow more
direct manipulation of parameters.  The important part of the
experiment-specification file is a lisp "progn" form containing a
bunch of "setf" forms that set the values of various global variables
in the "XTILE" package.  These globals correspond to the fields in the
various dialog boxes, and are fairly self- explanatory.  The values
assigned to these globals may be edited using your favorite editor.

When experiment files are loaded, they actually prepend their
parameter-sets onto the beginning of a global list of parameter-sets.
Tileworld executes the experiments in this list in forward order,
i.e., from the most recently added parameter-set to the least-recently
added.  When all the experiments in the most recently loaded experiment
file have been run, tileworld will continue with the experiments
in the previously-loaded experiment file.

To prevent this, and execute only a single experiment-file, the user
may want to clear the global experiment-list before running tileworld
on his experiment file (using (run "filename")).  This may be done by
the following command:

	(setf xtile::*experiment-list* nil)

In the future, the option to do this may be added as a button in the
Experiment Control dialog window.  But for now, it's not a crucial
feature.


