Trial-level configuration

data-files/samples/trials.Experiment.Any

@@ -0,0 +1,142 @@
+{ 
+    description = "trials"; 
+    frameRate = 120; 
+    showHUD = true;
+    renderWeaponStatus = true;
+    cooldownMode = "ring";
+    cooldownColor = Color4(0.7,1.0,0.9,0.75);
+
+    weapon = { 
+        id = "2hit"; 
+        firePeriod = 0.3;
+        damagePerSecond = 2;
+        autoFire = false;
+    }; 
+    sessions = ( 
+        { 
+            // This session tests out different weapon cooldowns and cooldown indicators while maintaining 2 hits to kill
+            id = "1target_cd"; 
+            description = "1 target cooldown"; 
+            trials = ( 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                }, 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                    cooldownMode = "box";
+                }, 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                    cooldownMode = "box";
+                    weapon = { 
+                        id = "2hit"; 
+                        firePeriod = 0.5;
+                        damagePerSecond = 1.1;
+                        autoFire = false;
+                    }; 
+                }, 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                    cooldownMode = "box";
+                    weapon = { 
+                        id = "2hit"; 
+                        firePeriod = 0.5;
+                        damagePerSecond = 1.1;
+                        autoFire = false;
+                    }; 
+                }, 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                    cooldownMode = "box";
+                    weapon = { 
+                        id = "2hit"; 
+                        firePeriod = 0.1;
+                        damagePerSecond = 5.5;
+                        autoFire = false;
+                    }; 
+                }, 
+                { 
+                    count = 2; 
+                    ids = ( "static"); 
+                    cooldownMode = "box";
+                    weapon = { 
+                        id = "2hit"; 
+                        firePeriod = 0.1;
+                        damagePerSecond = 5.5;
+                        autoFire = false;
+                    }; 
+                }, 
+            ); 
+
+        }, 
+        { 
+            // This one assumes the 120 Hz limits for the values below 8.33 ms and creates a nearly 2 frame stutter periodically for most trials
+            id = "2targets_frames"; 
+            description = "2 targets frame timing"; 
+            trials = ( 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static"); 
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static"); 
+                    frameTimeArray = (0.008, 0.016);
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static"); 
+                    frameTimeArray = (0.008, 0.008, 0.008, 0.016);
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static"); 
+                    frameTimeArray = (0.008, 0.008, 0.008, 0.008, 0.008, 0.008, 0.008, 0.016);
+                }, 
+            ); 
+
+        }, 
+        { 
+            // This session varies the latency
+            id = "5targets_latency"; 
+            description = "5 targets latency"; 
+            trials = ( 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static", "static", "static", "static"); 
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static", "static", "static", "static"); 
+                    frameDelay = 1;
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static", "static", "static", "static"); 
+                    frameDelay = 2;
+                }, 
+                { 
+                    count = 5; 
+                    ids = ( "static", "static", "static", "static", "static"); 
+                    frameDelay = 4;
+                }, 
+            ); 
+
+        }, 
+    ); 
+
+    targets = ( 
+        { 
+            id = "static"; 
+            destSpace = "player"; 
+            speed = ( 0, 0 ); 
+            visualSize = ( 0.05, 0.05 ); 
+        }, 
+    ); 
+
+} 

data-files/samples/trials.Status.Any

@@ -0,0 +1,11 @@
+{ 
+    currentUser = "Sample User"; 
+    sessions = ( "1target_cd", "2targets_frames", "5targets_latency"); 
+    settingsVersion = 1; 
+    users = ( 
+        { 
+            id = "Sample User"; 
+            sessions = ( "1target_cd", "2targets_frames", "5targets_latency"); 
+        } ); 
+
+} 

docs/experimentConfigReadme.md

@@ -33,9 +33,11 @@ In addition to these general parameters each session also has a few unique param
     * `session id` is a short name for the session
     * `description` is used to indicate an additional mode for affiliated sessions (such as `real` vs `training`)
     * `closeOnComplete` signals to close the application whenever this session (in particular) is completed
+    * `randomizeTrialOrder` determines whether trials are presented in the order they are listed or in a randomized order
     * `blockCount` is an integer number of (repeated) groups of trials within a session, with the block number printed to the screen between "blocks" (or a single "default" block if not provided).
     * `trials` is a list of trials referencing the `trials` table above:
-        * `ids` is a list of short names for the trial(s) to affiliate with the `targets` or `reactions` table below, if multiple ids are provided multiple target are spawned simultaneously in each trial
+        * `id` is an (optional) trial ID that (if specified) is used for logging purposes. If unspecified the `id` defaults to the (integer) index of the trial in the `trials` array.
+        * `targetIds` is a list of target names (`id` fields from within `targets` array elements) to spawn in this trial, if multiple target ids are provided multiple targets are spawned simultaneously in each trial
         * `count` provides the number of trials in this session (should always be an integer strictly greater than 0)
 
 #### Session Configuration Example
@@ -52,22 +54,25 @@ An example session configuration snippet is included below:
         "trials" : [
             {
                 // Single target example
-                "ids" : ["simple_target"],
+                "targetIds" : ["simple_target"],
                 "count": 20,
             },
             {
                 // Multi-target example
-                "ids" : ["simple_target", "world-space paramtetric", "example_target", "example_target"],
-                "count" : 5
+                "targetIds" : ["simple_target", "world-space paramtetric", "example_target", "example_target"],
+                "count" : 5,
             }
-        ]
+        ],
     },
     {
         "id" : "minimal-session",       // This session inherits all settings from the experiment above it
         "trials" : [
-            "ids" : ["simple_target", "destination-based"],
-            "count" : 10
-        ]
+            {
+                "id": "example trial",
+                "targetIds" : ["simple_target", "destination-based"],
+                "count" : 10,
+            }
+        ],
     },
 ],
 ```

docs/general_config.md

@@ -312,6 +312,7 @@ These flags control whether various information is written to the output files.
 |`logOnChange`                      |`bool` | `result.db` | Enable/disable for logging values to the `Player_Action` and `Target_Trajectory` tables only when changes occur (smaller file size when `true`) |
 |`logToSingleDb`                    |`bool` | `result.db` | Enable/disable for logging to a unified output database file (named using the experiment description and user ID)  |
 |`sessionParametersToLog`           |`Array<String>`| `result.db` | A list of other config parameters (by name) that are logged on a per-session basis to the `Sessions` table |
+|`trialParametersToLog`     |`Array<String>`| A list of additional parameter names (from the config) to log with each `Trials` table entry |
 |`logSessionDropDownUpdate`         |`bool`         | `log.txt`   | Controls whether session drop-down updates are written to `log.txt`  |
 
 ```
@@ -324,7 +325,8 @@ These flags control whether various information is written to the output files.
 "logOnChange" = false,                  // Log every frame (do not log only on change)
 "logToSingleDb" = true,                 // Log all sessions affiliated with a given experiment to the same database file
 "sessionParametersToLog" = ["frameRate", "frameDelay"],        // Log the frame rate and frame delay to the Sessions table
-"logSessionDropDownUpdate" : false,
+"trialParametersToLog": [],             // Don't log any trial-level parameters by default
+"logSessionDropDownUpdate" : false,     // Don't log changes in the session drop down
 ```
 
 *Note:* When `logToSingleDb` is `true` the filename used for logging is `"[experiment description]_[current user]_[experiment config hash].db"`. This hash is printed to the `log.txt` from the run in case it is needed to disambiguate results files. In addition when `logToSingleDb` is true, the `sessionParametersToLog` should match for all logged sessions to avoid potential logging issues. The experiment config hash takes into account only "valid" settings and ignores formatting only changes in the configuration file. Default values are used for the hash for anything that is not specified, so if a default is specified, the hash will match the config where the default was not specified.

scripts/package/fpsci_packager.sh

@@ -52,6 +52,8 @@ cp ./data-files/samples/weapons.Status.Any dist/samples/
 cp ./data-files/samples/weapons.Experiment.Any dist/samples/
 cp ./data-files/samples/targets.Status.Any dist/samples/
 cp ./data-files/samples/targets.Experiment.Any dist/samples/
+cp ./data-files/samples/trials.Status.Any dist/samples/
+cp ./data-files/samples/trials.Experiment.Any dist/samples/
 cp ./data-files/samples/spheres.Status.Any dist/samples/
 cp ./data-files/samples/spheres.Experiment.Any dist/samples/
 cp ./data-files/samples/sample.User.Any dist/samples/

source/ExperimentConfig.cpp

@@ -58,9 +58,9 @@ void ExperimentConfig::init() {
 	}
 	else {
 		// Targets are present (make sure no 2 have the same ID)
-		Array<String> ids;
+		Array<String> targetIds;
 		for (TargetConfig target : targets) {
-			if (!ids.contains(target.id)) { ids.append(target.id); }
+			if (!targetIds.contains(target.id)) { targetIds.append(target.id); }
 			else {
 				// This is a repeat entry, throw an exception
 				throw format("Found duplicate target configuration for target: \"%s\"", target.id);
@@ -74,15 +74,15 @@ void ExperimentConfig::init() {
 		sess60.id = "60Hz";
 		sess60.description = "60Hz trials";
 		sess60.render.frameRate = 60.0f;
-		sess60.trials = Array<TrialCount>({ TrialCount(Array<String>({ "static", "moving", "jumping" }), 2) });
+		sess60.trials = Array<TrialConfig>({ TrialConfig(Array<String>({ "static", "moving", "jumping" }), 2) });
 
 		sessions.append(sess60);
 
 		SessionConfig sess30;
 		sess30.id = "30Hz";
 		sess30.description = "30Hz trials";
 		sess30.render.frameRate = 30.0f;
-		sess30.trials = Array<TrialCount>({ TrialCount(Array<String>({ "static", "moving", "jumping" }), 2) });
+		sess30.trials = Array<TrialConfig>({ TrialConfig(Array<String>({ "static", "moving", "jumping" }), 2) });
 
 		sessions.append(sess30);
 	}
@@ -144,7 +144,7 @@ Array<Array<shared_ptr<TargetConfig>>> ExperimentConfig::getTargetsByTrial(int s
 	// Iterate through the trials
 	for (int i = 0; i < sessions[sessionIndex].trials.size(); i++) {
 		Array<shared_ptr<TargetConfig>> targets;
-		for (String id : sessions[sessionIndex].trials[i].ids) {
+		for (String id : sessions[sessionIndex].trials[i].targetIds) {
 			const shared_ptr<TargetConfig> t = getTargetConfigById(id);
 			targets.append(t);
 		}
@@ -158,7 +158,7 @@ Array<shared_ptr<TargetConfig>> ExperimentConfig::getSessionTargets(const String
 	Array<shared_ptr<TargetConfig>> targets;
 	Array<String> loggedIds;
 	for (auto trial : sessions[idx].trials) {
-		for (String& id : trial.ids) {
+		for (String& id : trial.targetIds) {
 			if (!loggedIds.contains(id)) {
 				loggedIds.append(id);
 				targets.append(getTargetConfigById(id));
@@ -178,8 +178,8 @@ bool ExperimentConfig::validate(bool throwException) const {
 	for (SessionConfig session : sessions) {
 		Array<String> sessionTargetIds;
 		// Build a list of target ids used in this session
-		for (TrialCount trial : session.trials) {
-			for (String id : trial.ids) { if (!sessionTargetIds.contains(id)) sessionTargetIds.append(id); }
+		for (TrialConfig trial : session.trials) {
+			for (String id : trial.targetIds) { if (!sessionTargetIds.contains(id)) sessionTargetIds.append(id); }
 		}
 		// Check each ID against the experiment targets array
 		for (String targetId : sessionTargetIds) {
@@ -219,11 +219,11 @@ void ExperimentConfig::printToLog() const{
 			sess.id.c_str(), sess.render.frameRate, sess.render.frameDelay);
 		// Now iterate through each run
 		for (int j = 0; j < sess.trials.size(); j++) {
-			String ids;
-			for (String id : sess.trials[j].ids) { ids += format("%s, ", id.c_str()); }
-			if (ids.length() > 2) ids = ids.substr(0, ids.length() - 2);
+			String targetIds;
+			for (String id : sess.trials[j].targetIds) { targetIds += format("%s, ", id.c_str()); }
+			if (targetIds.length() > 2) targetIds = targetIds.substr(0, targetIds.length() - 2);
 			logPrintf("\t\tTrial Run Config: IDs = [%s], Count = %d\n",
-				ids.c_str(), sess.trials[j].count);
+				targetIds.c_str(), sess.trials[j].count);
 		}
 	}
 	// Iterate through trials and print them