-
Notifications
You must be signed in to change notification settings - Fork 15
GettingStarted
1. Prerequisites
2. Building SteerSuite
1. Compiling for Unix Platforms
2. Compiling for Windows Platforms
3. Introduction to SteerSim
1. Running SteerSim the First Time
2. Basic Options and GUI Controls
3. Optional Configuration File
4. SteerSim Modules
3. Prerequisites
SteerSuite source code can be downloaded from the SteerSuite web page.
In most cases, there are no dependencies to download/install before
using SteerSuite. Most of the SteerSuite dependencies are already widely
available on most platforms. GLFW, TinyXML, and an implementation of the
Mersenne Twister algorithm are already provided (legally) with the
SteerSuite download under their own licenses, and integrated into the
SteerSuite build process.
For Unix platforms (including Mac OS X), the build process uses premake4, gmake, and g++. These tools are already available on most systems. If necessary, other shells, make programs, and compilers can be used after modfying the build script and makefiles accordingly.
SteerSuite has been tested on g++ versions 3.4 and 4.3. There is a good chance that earlier/later versions of g++ will also work.
For Max OS X, the build process requires OS X version 10.5 or greater. This is because we use the g++ rpath setting that is not supported prior to OS X 10.5. Unofficially, earlier versions of OS X should work by adding the directory where SteerLib (libsteer.so) exists into the LD_LIBRARY_PATH environment variable, but this is currently untested.
For Windows, the build process uses Visual Studio 2012. It is suggested that users also download and install Cygwin to provide a unix-like command-line environment. This documentation is written assuming you are using Unix or Cygwin. If you prefer to use a different command prompt, such as Windows built-in command shell, you will need to modify the command-line examples described in this documentation accordingly.
In addition to a command-line interface, there is a graphical interfaces (GUI) provided for steersim. GLFW is already included with the SteerSuite download, under its own license. It provides a fast, simple OpenGL window, and supports keyboard and mouse interaction. More information about GLFW, including the original code and latest updates, can be found at the GLFW home page.
Compiling for Unix Platforms
SteerSuite provides a simple script, buildall, to compile all components on Unix platforms. Essentially this script sets some temporary environment variables and uses gmake to build each component. To compile SteerSuite, enter the build/ directory and run:
./buildall \<platform\> [Debug|**Release**]The possible target platforms can be listed by running the buildall script with no arguments. The possible platforms include: linux, osx, solaris (untested), and simics (also untested).
**Note:**
Make sure you are in the build/ directory. The buildall script will not run properly if it is executed from a different location.
All components should compile without errors or warnings. If you compiled SteerSuite with the default options, there will be several new directories:
build/bin/
contains the executable binaries,
build/lib/
contains the SteerLib shared library,
You may want to modify build options, in particular to enable the Qt user interface, or to "install" SteerSuite to a more permanent location on your system. To do this, modify the variables at the top of the buildall script. Each option is explained by comments in the script.
SteerSuite provides Visual Studio 2012 solution and project files. The top-level solution file is located in the build/win32/ directory. Open this solution file with Visual Studio 2012, choose whether you want to compile in Debug mode or Release mode, and select Build → Build Solution (F7). All components should compile successfully without warnings. After compiling, all binaries (including SteerLib shared library and SteerSim plugins) will be located in build/win32/Debug/ or build/win32/Release/. Note: You will need to manually change to Release mode when you first open the SteerSuite solution. Visual Studio uses Debug mode by default, and the preference between Debug or Release seems to be stored in the automatically generated user options file that we cannot control. Unless you plan on debugging, it is strongly recommended that you choose Release mode for better performance.
steersim
is a modular framework for running simulations, usually with a GUI to
visualize the simulation. It consists of a core simulation engine, which
loads any number of modules to do the real work. The functionality of
modules can be almost anything, from providing more elaborate
visualizations to post-analysis of agent behaviours. Some of the modules
provided with SteerSuite include:
The testCasePlayer module simulates a test case. The user specifies the test case to
simulate and the module that will provide steering AI agents, and the
testCasePlayer will load everything and run the simulation.
The recFilePlayer module loads and replays an existing recording of a simulation.
The simpleAI
module is an example plugin module. It provides very simple AI agents
just as a code example for those interested in creating their own
steering AI plugin. Modules like this one, with steering AI, are usually
used by the
testCasePlayer
module.
The
pprAI
module is another example plugin module that provides more intelligent
steering agents.
The
steerBench
and
metricsCollector
modules run an online benchmarking process, while the simulation takes
place. In some cases this can be more useful than the
steerbench
command-line utility, for example, if storing the recording would be
impractical or if you want to observe metrics of an agent's behaviors in
real-time for debugging.
Refer to the Reference Manual for a complete list of modules and more
detailed descriptions.
Running SteerSim the First Time
From a Unix or Cygwin command line prompt, go to the directory where you
compiled the executables (most likely,
build/bin/
on Unix, or
build/win32/Release
on Windows) and run:
./steersim -testcase simple-1.xml
steersim
will try to find the test case
simple-1.xml
in the default search path and the current directory. If the test case
is in a different location, you can specify the full path to the test
case, or you can use the
-testCaseSearchPath
option to specify the directory where test cases can be found. If you
receive an error that looks similar to:
ERROR: exception caught in main: Could not find test case simple-1.xml.
then
steersim
could not find the test case in the path you specified, so double-check
that you entered the correct path.
If it worked successfully, a window should appear, showing a grid and
the initial conditions of the
simple-1.xml
test case. Any agents should appear black and green, which is the color
of the default "dummy" agents. These agents have no steering AI, and
will not do anything even if the simulation is actually running. To use
a different steering AI, refer to
Section 3.1, “Simulating a Test Case using SteerSim”
.
Here are some of the default mouse and keyboard controls for steersim:
ESC
quits the simulation.
Spacebar
pauses and unpauses the simulation.
Ctrl-left-click
enables camera rotation as you drag the mouse around.
Ctrl-right-click
enables camera zoom as you drag the mouse up and down
Ctrl-middle-click
enables camera translation as you drag the mouse around.
Here are some of the command-line options for
steersim:
-commandline
specifies to run steersim without a GUI, useful if used in an automated script or a architecture
simulator.
-numframes <n>
tells the engine to simulate only n frames.
-testcase <testCaseName>
loads the testCasePlayerModule with the specified test case.
-testcasesearchpath <directory>
specifies the directory to search for test cases.
-ai <moduleName>
tells the testCasePlayer module to use the moduleName to create AI agents.
-module <moduleName>
tells the engine to load the module
moduleName
. See the sections below for more details.
-modulesearchpath <directory>
specifies the directory to search for modules.
-generateconfig <filename>
dumps an XML configuration file to filename.
-config <filename>
tells steersim to load options from the specified XML configuration file.
For a complete list of controls and options, refer to the Reference Manual. ----------------------------------------------------------------------------------------------------------- Note There are three main sources of options: (1) command line, (2) configuration file, (3) hard-coded defaults for options that are not specified. Options from all three sources are merged. If an option is specified on the command line, it will override the same option specified in the configuration file.
steersim has many more options than the few that can be specified through the
command line. To customize these options, you will need to provide
steersim with a configuration file. At first you may not have a
configuration file. You can generate a configuration file using the
-generateconfig
command-line option. For example, to create a config file named
myConfig.xml
, run:
./steersim -generateconfig myConfig.xml
This will create an XML file containing a categorized list of all
options, with comments explaining each option. Edit this file with your
favorite text or XML editor to fit your preferences.
Then, to use this configuration file with steersim, use the
-config
option. For example:
./steersim -config myConfig.xml
Anything useful in
steersim
is done through modules. Modules can be directly built into
steersim
or plugins that are dynamically loaded at runtime. Built-in modules will
not have a .o or .dll library file associated with it.
steersim
can list all modules that it finds by using the
-listmodules
option, as follows:
./steersim -listmodules
The engine treats all modules in the same way, regardless of being
built-in or plugin.
Eventually you will want to control what modules are loaded, and give
options to each module. This can be done in two main ways. The first way
is to edit an XML configuration file, as described in the previous
section, to specify which modules should be loaded on startup. Also in
the configuration file, you can specify options to modules, whether they
are designated to be loaded on startup or not. The second way is to
specify a module and its options from the command line. This is done
using the
-module
option, followed by a single contiguous string containing the module
name and an (optional) comma-separated list of options:
./steersim -module moduleName,option1=value1,option2=value2
Several examples of this syntax are given in the next chapter.
The module name is case-sensitive. Behind the scenes, if the engine
knows this module name, it will instantiate the built-in module
directly. Otherwise, the engine will try to find a dynamic library of
the same name, automatically managing library name extensions, and
searching in the modules directories that it knows about.
For a complete list of the modules, module options, and command-line
options in
steersim
, refer to the Reference Manual.