FirstPersonScience ApplicationThe FirstPersonScience application (FPSci for short) is a tool for conducting user studies on first person shooter (FPS) style tasks.
You can get a stand alone version of FPSci compiled for Windows 10 here. In order to use this build, you will also need to install the x64 version (and possibly the x86 version) of the Microsoft Visual C++ Redistributable found at this link.
FPSci depends on the G3D innovation engine which is a prerequisite for building FPSci. Installation instructions.
If you install G3D using its installg3d.cmd installer, then this will automatically install Python, Visual Studio Community Edition, and Subversion for you.
If you manually check out G3D, you'll need some data files from the research and game subdirectories so you can't just checkout the common subdirectory. The current version of FPSci requires at least G3D revision r7217 for the visual studio version upgrade, but most of the code will work withe earlier versions of G3D as well.
The solution file (FirstPersonScience.sln) can build and run using Visual Studio 2022.
FirstPersonScience implements a simple mouse-controlled view model with a variety of parameters controllable through various .Any files (more on this below). The scene, weapon, target size/behavior, and frame rate/latency controls are all available via this interface.
When running, the keypad - button can be pressed to exit the application, or you can press TAB or ESC to toggle the user configuration menu, which has a "quit" button in it.
Since FirstPersonScience was developed for use in scientific studies it adopts somewhat standard experimental terminology from psychophysics for much of its organization. This section describes the various levels of control in the application and provides the terminology by which they will be referred to for the remainder of this documentation.
The experiment is the highest level "grouping" of tasks in the application. An experiment is defined by a set of parameters specified in an experimentconfig.Any which include information about included sessions, as well as more general scene, weapon, and timing configurations.
A session is the next level of task grouping in the application. A session can reconfigure many of the (global default) properties setup in the experiment (it is assumed some property of interest is typically varied between sessions) as well as list of trials to include in this session along with their counts.
A trial is the lowest level grouping of task in the application. From a user-perspective the trial represents one or more targets being spawned, traveling, and either being shot or missed within a given time period. In specifying trials the developer enters trial groups, which are sets of trials specified using a target type id and count for one or multiple target types.
For more general information related to FirstPersonScience check out the documentation directory.
.Any FilesAs mentioned above a variety of .Any files (similar to JSON file format) are used to control the behavior of the application. These files are as follows:
startupconfig.Any is a simple configuration file for setting the playMode (debug feature) and pointing to the experiment and user configsexperimentconfig.Any is the primary configuration for the experiment. It includes scene, target, and weapon information and also establishes the sessions to take place during the experimentuserconfig.Any holds user information for (multiple) users including mouse sensitivity and DPIuserstatus.Any keeps track of both the session ordering and the completed sessions for any given userweaponconfig.Any can be optionally included (using the #include("filename") option in the .Any format) to allow quick swap of weapons across multiple configssystemconfig.Any optionally configures an attached hardware click-to-photon monitor and provides (as output) specs from the system the application is being run onAll configuration files referenced above can be found within the data-files directory.
One reason for using the modular .Any file configuration structure shown above is the ability to track multiple experiments/sessions/trials without a need to perform major edits on the files. For example, an experimentconfig.Any file can either be renamed or can make use of the #include("[filename]") syntax provided by G3D's .Any parsing to include entire .Any files as sections in a larger file.
This allows users to create .Any files for a wide variety of experiments, weapons, users, and even system configurations, then swap between these at runtime by simply changing filenames or #include statements.
A quick guide is provided below to this repository structure:
source holds the FirstPersonScience c++ source filesdata-files holds scene and model files as well as the .Any files to configure the experimentdocs contains documentation to aid experiment designersscripts contains some useful scripts for developers including some basic data analysisresults is created when executing FirstPersonScience and holds the results .db files from each experimentThe source files (located in the source directory) implement a fairly typical G3D application structure with additional classes/files for many peripheral features. We outline the purpose of each of these source files below.
All graphics and scene-related routines are in App.cpp and its affiliated header file. The App class inherits GApp from G3D and thus controls all rendering. Unlike many other applications this App class overrides the oneFrame() method from within GApp to allow us to reorder the render loop to reduce latency.
Several helper classes/files have been created to assist with application-level tasks.
PhysicsScene class/file is borrowed (w/ some modifications) from the G3D simpleGame example. This class extends the typical Scene by adding support for a tree based collision model, using a sphere as a proxy for the player.PlayerEntity class/file is also borrowed from the G3D simpleGame example. The class provides a controllable player-entity (rather than no-clip camera) that works well with the PhysicsSceneTargetEntity class/file is a custom class implementing different target types that inherit a common, generic TargetEntity (which in turn inherits G3D's VisibleEntity)GuiElements class/file contains some custom GUI menus designed to work specifically with this applicationDialogs.h file contains some generic dialog box classes that are used for asking questions of the user following a session.PyLogger.h file encapsulates the calls used to launch the LDAT-R python logging tools from within the application when running FPSci with an LDAT-R device present.The majority of experiment/session level management occurs within Session.cpp and it's affiliated header file. This includes configuring sessions, controlling the per-trial/session state, and logging results.
Experiment/session-level helpers include:
Logger.cpp / Logger.h which manage logging for the sessionExperimentConfig.h which contains the .Any serializable classes for all session/experiment controlParam.h which is used as a sort of dynamically typed dictionary to help consolidate parameter passing