WorldBuilder
User Manual
(for Version 1.1.6)
Introduction
The WorldBuilder application is a tool for creating Apex simulation worlds. It takes a set of HTML files as input and produces a Lisp file for Apex as output. The HTML files specify objects for the simulation world in a storyboard format. This manual provides the following information for WorldBuilder:
· A walk-through for using the application
· A discussion of storyboard contents
· A guide to troubleshooting errors
The WorldBuilder Walk-through
This section covers a basic walk-through for using the WorldBuilder application. It assumes that a valid, error-free storyboard is used for input so that the application runs to completion. The figures are taken from the Macintosh platform. With the exception of Step 1 in the walk-through, all other differences between WorldBuilder running on the Macintosh and Windows platforms are cosmetic in nature. Also, a number of known odd behaviors are listed at the end of the walk-through. It is important to be familiar with this list in case one of the items should happen while using WorldBuilder.
1. (Macintosh)
After downloading and unpacking the WorldBuilder distribution, open the
WorldBuilder folder. This folder
contains an icon for the WorldBuilder application as shown in Figure 1. Double-click on this icon to start the
WorldBuilder application.
Figure 1 – The WorldBuilder Icon
(Windows) After downloading and unpacking the WorldBuilder
distribution, use Windows Explorer to navigate to the directory containing the
extracted files. Double-click on
worldbuilder.jar to start the application.
If Windows requests a program required to run this application, click
the “Other…” button and select javaw.exe from the \bin directory where you
installed Java.
If started successfully, WorldBuilder will display the “Convert Storyboard”
dialog shown in Figure 2.
Note
to Macintosh users: Using the Apple or
Help menus will not produce any results.
Figure 2 – The “Convert Storyboard” Dialog
2. At this point, a storyboard can be entered either by
typing directly into the “Storyboard Source File:” text box or by clicking on
the “Browse” button located next to that text box. Each storyboard should contain an Overview file (covered in the
Storyboards section of this manual).
This is the file that should be entered/selected at this time. Figure 3 shows the file selection dialog
that results from using the “Browse” button.
Windows users should expect the traditional Windows file dialog in this
situation.
Figure 3 –
The File Selection Dialog
3. If the “Browse” button was used to select the
Storyboard Source File, then WorldBuilder will indicate an output file by
default. This output file is called
“initialize.lisp” and it will be located in the same folder as the storyboard. This is shown in Figure 4. This file may be relocated either by typing
in the “Output File:” text box or by using the “Browse” button located next to
that text box. The filename
“initialize.lisp” is specific to Apex and should always be used to name the
output file if you want Apex to be able to use it directly.
Figure 4 –
Default Output File
4. Once a storyboard and output file are selected, click
on the “Process” button. WorldBuilder
will then attempt to read through the storyboard and produce the output
file. If all goes well, a dialog
containing a message similar to Figure 5 should appear. If WorldBuilder encountered any problems,
this dialog will contain a message about the error (covered more fully in the
Troubleshooting section of this manual).
In either case, click the “Continue” button on this dialog to convert
another storyboard or click the “Exit” button to quit the WorldBuilder
application.
Figure 5 –
Successful Storyboard Conversion
Known
Odd Behaviors
The following is a list of things that have sometimes occurred while using Apex:
·
On the Macintosh
platform, if a user selects the Overwrite button on the Confirm File Overwrite
dialog, there may be a brief period where the screen shows the Convert
Storyboard dialog without any files selected.
This appears to be some sort of screen refresh problem while
WorldBuilder processes the storyboard that was selected prior to hitting the
Overwrite button. It has no effect on
the results of storyboard processing.
·
On the Windows platform,
if a user browses for the Storyboard Source File, sometimes the Process button
on the Convert Storyboard dialog does not become enabled upon completion of the
Browse operation. If this happens, the
user must click the mouse into the Output File text box, then type and delete a
new character. This action should cause
the Process button to become enabled.
Storyboards
Two
sets of storyboard files are being distributed with this document as examples
of the expected content and format of storyboard files. The example storyboards are called ATMWorld
and TaskOpenApplication. This section
summarizes the important aspects of storyboard construction by highlighting
portions of those files.
The
Overview File
First,
any storyboard must begin with an Overview file. For the most part, this file contains textual notes concerning
the creation and purpose of the storyboard.
In addition, this file also allows the storyboard author to select
agents and interface devices for the Apex simulation by changing the desired
items in the list to bold text. The
following example shows the difference between bold and normal text as seen in
non-rendered HTML.
<p><b>Mouse</b></p>
<p>Keyboard</p>
In this example, the text between the <b> … </b> tags is will be rendered in bold. Finally, the Overview file must contain a link to the next file in the storyboard. The non-rendered HTML looks something like this:
<p><a
href="ATM.html">Go to Step1 in this task</a></p>
The
important area is that the text enclosed in quotation marks following “href=”
must be the filename for the next file in the storyboard.
The
Storyboard Proper
The
remainder of the storyboard consists of images and “hot spots” that focus a
storyboard reader on specific portions of the image. The “hot spots” may or may not lead the storyboard reader to
another file in the storyboard. When
processing the storyboard, WorldBuilder will collect all of these “hot spots”
from the storyboard and create an initialization for Apex simulation objects
from them.
To
begin, the storyboard file should contain an image. This appears in non-rendered HTML as follows:
<img src="atm.jpg"
width="431" height="333" usemap="#Map"
border="0">
The
only important aspect of this line is the text enclosed in quotation marks
following “usemap=”. This text should
correspond to a block of HTML within <map> … </map> tags as
follows:
<map
name="Map">
<area shape="rect"
coords="26,189,83,213" href="#"
alt="Withdraw-button" title="Withdraw-button">
</map>
The text enclosed in quotation marks following “name=” for the <map> tag should match the text following “usemap=” for the <img> tag (ignoring the “#” character). There should be some number of <area> tags within the <map> … </map> tags. The <area> tags define the “hot spots”. The following attributes for the <area> tags must have values for WorldBuilder to work properly:
shape WorldBuilder currently only calculates position and dimensions for a shape of “rect”.
coords For a shape of “rect”, the first two numbers are the (x, y) coordinates of the upper left corner of the object and the second two numbers are the (x, y) coordinates of the lower right corner of the object. WorldBuilder calculates position as the centroid of the rectangle formed by these coordinates.
title WorldBuilder names the Apex simulation object using the title attribute for the “hot spot”.
href The href attribute may either be “#” (indicating no link to another file) or a filename for the next file in the storyboard.
These are some notes about the behavior of WorldBuilder when it processes a storyboard:
· WorldBuilder only creates one instance of an Apex simulation object. An Apex simulation object is uniquely represented by its name (taken from the title attribute of an <area> tag). If two or more instances of an <area> tag with the same title attribute occur in the storyboard, then WorldBuilder creates an Apex simulation object from the first instance it finds and ignores the other occurrences (regardless if the other attributes are different).
· WorldBuilder processes a storyboard until it exhausts all of the links that lead to storyboard files that WorldBuilder has not processed. This means that the storyboard may contain links to previous files in the storyboard.
Troubleshooting
For
any number of reasons, WorldBuilder may not be able to successfully process a
storyboard. In most cases, it will
report an error related to the failure.
This section contains a list of the error messages reported by
WorldBuilder along with further information on how to debug the problem. The list begins on the next page. It has been oriented in Landscape to aid in
readability.