VR-Lab PS-ERT Primer - Scenario
written by pilardi 11/01
last updated by pilardi 12/01
Back to overview
What is a scenario?
The scenario is the heart of a PS-ERT program. It contains all the
characters, character properties, objects, lights, cameras, and environmental
properties loaded in from scenario files (*.pss). In this
lab, we are only interested in the first two. All of the others should
be controlled through Performer.
The scenario is controlled through a scenario pointer of type psScenario.
See psScenario class below for how to obtain and use this pointer.
What is a scenario file?
Scenario files are text based files created by PeopleShop software.
PeopleShop only runs on NT based machines. The documentation for
PeopleShop is located in $BDI_PEOPLESHOP/doc/PeopleShop_15_User_Manual.pdf
or here.
In PS-ERT version 1.5, characters can only be loaded into the scenario
through scenario files, though this may change in the future (see
create_character
in the scenario part). It is fairly easy to create a simple scenario
file by hand. The following scenario file is a minimal file containing
two characters:
scenario the_scenario
version = 1.5.20
appearance_filename = peopleshop/appearances.psi
scenario_character bob
character_type = male_pedestrian
scenario_character alan
character_type = suspect2
appearance = alan_exface_no_gun
See the character part of the primer to understand
what the parts of the character mean.
A scenario file can be much more elaborate that this, containing preset
character paths and actions, camera angles, lights, objects, environments,
etc. For greater flexability, I suggest using a minimal scenario
files and controlling everything through calls to PS-ERT and Performer.
Although if you would like an environment with a large number of characters
doing non-interactive behaviours, using PeopleShop to create the scenario
file might be the best idea.
psScenario class
Link to official doc.
psScenario is a C++ class containing general PS-ERT functions.
This pointer can be access using the PSERT::sp() in psert_util.
Otherwise, if you are not using that class the psScenario pointer is returned
by the call to peopleshop_create_scenario().
All methods return 0 on success and -1 on failure, unless otherwise
specified.
Important methods
(in the order they are likely to be called)
-
set_graphics_attach_ptr(perf_scene)
Used to attach Performer scene (pfScene*) to PS-ERT. (described
in overview).
-
load("scenario.pss")
This loads the given scenario file into the scenario. This should only
be called once. If you would like to load in multiple scenario files, use
load
for the first one and merge for all the rest.
-
merge("scenario.pss")
Adds the given scenario file into the current scenario. This should
be called once for each additional scenario file.
-
int get_num_characters()
Returns the number of characters loaded into the current scenario.
Meaning all the characters in all the scenarios files loaded so far. This
function, in conjunction with get_character_at_index() and
get_name()
can be used to list the names of the characters in the scenario.
-
psScenarioCharacter*get_character_at_index(n)
Whenever a scenario is loaded or merged, each of the characters in
the scenario are given an index. The first character has index 1, etc...
This method returns a pointer to the character at index
n. See
the character part of the primer to learn
how to use that pointer. psert_util::get_char(...) can be
used instead of this method.
-
psScenarioCharacter* find_character("name")
In the scenario file, each character is given a name. Use this method
to retrieve the character by that name. psert_util::get_char(...)
can be used instead of this method.
-
LOD Functions
These functions allow you to change the Level-Of-Detail
of the characters. The default values seem good. But changing these values
might help framerate.
-
update(float t)
This is what keeps time rolling. This should be called once per frame
after all PS-ERT related changes have been made. It should be passed the
time from Performer. Hmm... Scaling t might make for some interesting
slow motion effects. psert_util::update(...) can be used
instead of this method.
Unused methods and reasons why
-
get_current_scenario()
Since the scenario pointer is returned during initialization, this
function is not very useful. It could be used to retrieve the scenario
pointer in function without passing it, but that usually leads to confusing
and hard to read code.
-
apply_environment_settings()
The documentation claims that this method is required for changing
camera view, applying fog settings, and changing lighting settings. However,
the only thing it seems to do is slow down the frame rate. I suggest to
avoid this method at all costs.
-
draw...()
When using PS-ERT within a Performer environment, none of these functions
need to be called. Drawing is taken care of directly by Performer.
-
psScenarioCharacter* create_character(...)
As of version 1.5, this is a PS-ERT Level 2 function. Meaning this
is a function that has yet to be fully implemented. It will hopefully eventually
allow using the PS-ERT without scenario files. Unfortunately, it doesn't
yet work well enough to be useful. It seems to work at first, but crashes
if you try to give the character an action.
-
Camera Functions
These functions are used to control and switch between scenario cameras.
It is much better to allow to use Performer functions to control the camera.
-
Other Functions
Most of the other functions have Performer equivalents or are related
to complex scenario playback. I suggest using Performer calls where possible.