The command-line version of breve allows you to run breve simulations from the command-line either with or without graphical display. The command-line version of breve is available for Mac OS X, Linux and Windows.
The command-line version of breve can be used to develop and run breve simulations just like the OS X breve Application or the breveIDE for Linux and Windows, but it is also especially useful for running breve simulations from shell scripts or from other programs. In this way, a breve simulation can be integrated into another program or scripting environment in order to perform some sort of simulation, and return the results.
When the command-line breve starts up in graphical mode, the simulation is paused: press the space-bar to begin the simulation. This behavior can be modified using the "-u" flag described later in this section.
In order to run the command-line breve on Windows or Linux, you'll need to have OpenGL and GLUT libraries installed on your system. If you encounter problems running breve, you may need to install these libraries. They are freely available from the internet.
Before running breve, you'll need to set up the environment variable
BREVE_CLASS_PATH. This variable must
contain the location of the "lib/classes" directory included in the
distribution. Setting this environment is done differently for
different shells and platforms. Some examples are shown below.
path to breve is the location
of the breve distribution folder that you downloaded.
# tcsh users (Linux & OSX):
setenv BREVE_CLASS_PATH /<path to breve>/lib/classes
# bash users (Linux & OSX):
export BREVE_CLASS_PATH=/<path to breve>/lib/classes
# Windows console users:
SET BREVE_CLASS_PATH=C:\<path to breve>\LIB\CLASSES
You may freely move around the files in the breve distribution (to
install them in /usr/local on a UNIX
system, for example), but be sure to set your BREVE_CLASS_PATH accordingly.
Once your BREVE_CLASS_PATH environment
variable is configured, you can get started by running breve with one
of the included simulation files. Assuming that you are in the breve
distribution directory, you can try out the "ArrowSwarm" demo by
typing:
# Linux
% ./bin/breve.sh ./demos/Swarm/ArrowSwarm.tz
# OSX
% ./bin/breve ./demos/Swarm/ArrowSwarm.tz
# Windows
> bin\breve.exe demos\Swarm\ArrowSwarm.tz
This command will open a graphical display window containing the simulation, which is initially paused. To unpause the simulation, hit the space bar. When the simulation is running, the following controls can be useful:
Space bar: pause/unpause the simulation
F1: run simulation forward one iteration step
Left mouse: rotate simulation and select objects (described below)
Right mouse click: display the simulation menu (described below)
Right mouse click (when an object is selected): display a contextual menu for the object (described below)
Control (or F2) + left mouse: zoom in and out of the simulation
Alt (or F3) + left mouse: move the camera
Shift (or F4) + left mouse: select and drag objects in the simulation
Escape: to quit the simulation, or access the breve command prompt
The keys F2, F3 and F4 can be used instead of control, alt and shift, respectively, to allow for easier use on platforms which emulate middle and right mouse buttons using the control, alt or shift keys.
The breve command prompt (which can be accessed using the escape key) can be used to execute commands in running simulations. "steve" commands are typed in at this prompt, and will be executed in the simulation's controller object. The steve language (and the controller object) are described in the next chapter (the section called “Writing breve Simulations With "steve"”).
Users can also interact with a running simulation via the simulation menu and through the contextual menus associated with specific objects, both accessed via the right mouse button. To access the simulation menu, be certain that no object in the simulation is selected, and click the right mouse button. To access a contextual menu for an object in the simulation, use the right mouse button while an object is selected.
By default, the simulation menu and contextual menus are mostly empty. As you begin to customize simulations and construct your own, however, you will be able to add your own custom options to the simulation and contextual menus.
Simulations written in breve use the suffix ".tz" and are regular text files. You can open up the file in your favorite editor to see how it works:
% pico ./demos/Swarm/ArrowSwarm.tz
If this is your first time running breve, it is recommended that you take the time to explore the demos and their code. By exploring the demos, you'll see how a number of breve's features are used and gain a basic understanding of how simulations are written.
If you wish to run a simulation without graphical display, you can use
the command breve -x. Follow the same
setup directions described above (the section called “Setting Up Your Environment”) in order to setup
your environment, and then run the simulation:
% ./bin/breve -x ./demos/Push/PushRegression.tz
Textual output will be printed as usual, but no graphical window is shown. This feature is most useful for collecting data when user interaction and observation is unimportant.