Add adaptive difficulty sections to documentation

README.md

@@ -14,6 +14,7 @@ You may need to [download the drivers](https://www.gaming.tobii.com/getstarted/)
 
 Documentation for each mini-game is provided under [`docs/`](/docs/) covering:
 - how to edit important values during play testing.
+- how adaptive difficulty works for each mini-game
 - the save data each mini-game produces
 
 ## Developing

docs/rocket-launch.md

@@ -17,6 +17,10 @@ then a timer decrements until launch time is achieved.
     - Gaze Tolerance - the allowable gaze standard deviation to be steady. Smaller number will require steadier gaze. This may be reduced by the adaptive difficulty settings below.
     - Target Object if this is set you are required to look at that object, if not gaze can be anywhere on screen but must be steady.
 
+  - **Adaptive difficulty variables**
+    - Max previous games: The maximum number of previous games to retrieve to determine experience based difficulty
+    - Adaptive difficulty: integer describing level of adaptive difficulty - higher numbers are more difficult.
+
   - **User Interface Items**:
     - Count down sprites: A list of sprites to use for the count down code display.
     - Instructions Text: A text box to place the instruction text.
@@ -28,10 +32,24 @@ then a timer decrements until launch time is achieved.
     - Use Mouse For Tracker: Can be used for debugging when no Tobii eye tracker is available.
     - Gaze and Speed Status Text: Text boxes where we can write debugging information to screen.
 
-- **FlameController**: Attached to the flame object, which is a child of the rocker object.
+- **FlameController**: Attached to the flame object, which is a child of the rocket object.
   - Flicker Amplitude and frequency. At rest the flame will flicker slightly to match the aesthetics of other levels. Amplitude and frequency can be altered.
   - Flame Speed Scale: The size of the flame will increase as the head speed increases. Increasing the scale will create a bigger flame.
   - Flame Speed move: As the flame grows we also need to move it down relative to the rocket in order to prevent the flame appearing to come out of the top of the rocket. Faster head speeds or a larger flame speed scale will require a larger value for flame speed move.
 
 - **SmokeController**: Attached to ground left/right emitter.
   - Smoke Emission Scale: A larger value will increase the amount of smoke emitted for a given head speed.
+
+
+## Adaptive difficulty
+
+Difficulty is increased between games by reducing the size of the gaze target, reducing the gaze tolerance, and increasing the overall launch time (explained below). Note: all parameters mentioned below can be adjusted on `LaunchControl`. 
+
+At the start of each game, a scaling factor is calculated as: 
+
+`adaptiveDifficulty` * ( (`maxPreviousGames` + `nGames`) / `maxPreviousGames`) 
+
+`nGames` is the total number of rocket launch games completed by the player so far (up to a maximum of `maxPreviousGames`). The scaling factor is then applied:
+- the size of the gaze target (the box displaying the launch code numbers) is divided by the scaling factor. This makes it smaller after more games have been played.
+- the gaze tolerance (i.e. the tolerance in unity coordinates that gaze needs to stay within) is divided by the scaling factor. This means the player must keep their gaze closer to the target after more games have been played.
+- the launch time is multiplied by the scaling factor. This means the player must move their head while looking at the target for longer to launch the rocket.

docs/space-walking.md

@@ -28,6 +28,18 @@ The space walking mini-game scores the player on completed steps (up / down / le
   - Label text for the arrow
   - Colour of arrow fill
 
+## Adaptive difficulty
+
+Difficulty is increased between games by increasing the overall time limit, and adding head turns in between each step.
+
+Progression is as follows (all mentioned parameters are configurable on `SpaceWalkingManager`):
+- games start with a time limit of `minTimeLimit` and no head turns
+- a difficulty upgrade occurs when the player has completed `nGamesToUpgrade` games _in a row_ with:
+  - the same time limit 
+  - an average of `upgradeRate` steps per second (one step = one step out and back to the centre)
+- For each upgrade, the time limit is increased by `timeLimitIncrement` (up to a maximum of `maxTimeLimit`). After `maxTimeLimit` is reached, the next upgrade adds head turns between the steps.
+- From then on, all games use the `maxTimeLimit` and include head turns. 
+
 ## Save data
 
 Data is saved to `SpaceWalkingScores.csv`, with one row per played game. Values are:

docs/star-collector.md

@@ -22,6 +22,32 @@ top of the screen.
 
 - **Ship**: values related to ship movement
   - The amount the ship moves per degree of head movement (X By Degrees)
+
+## Adaptive difficulty
+
+Difficulty is increased in two ways:
+- within each game the star fall speed adapts to player performance
+- between games, the overall game time limit increases
+
+### Within game (star speed)
+
+Note: all mentioned parameters can be adjusted on `StarGenerator` / `StarCollectorManager`.
+
+- Every game, stars start falling at the same rate of `baseStarSpeed`.
+- Every `difficultyWindowSeconds`, the star fall speed either increases or decreases by `speedIncrement`:
+  - If the player collects more than `speedUpgradePercent` of the stars that fell in the last `difficultyWindowSeconds`, it increases.
+  - Otherwise it decreases.
+- Star speed is capped between `minStarSpeed` and `maxStarSpeed`.
+
+### Between games (time limit)
+
+Progression is as follows (all mentioned parameters are configurable on `StarCollectorManager`):
+- games start with a time limit of `minTimeLimit`
+- a difficulty upgrade occurs when the player has completed `nGamesToUpgrade` games _in a row_ with:
+  - the same time limit 
+  - more than `timeLimitUpgradePercent` of all stars in the game collected
+- For each upgrade, the time limit is increased by `timeLimitIncrement` (up to a maximum of `maxTimeLimit`).
+- From then on, all games use the `maxTimeLimit`. 
 
 ## Save data
 

docs/star-map.md

@@ -20,6 +20,28 @@ or opposite order.
   - Colour for correct selection
   - Colour for incorrect selection
 
+## Adaptive difficulty
+
+Difficulty is increased in two ways:
+- within each game, the length of the sequence adapts to player performance
+- between games, the size of the constellation may increase
+
+### Within game (sequence length)
+
+Note: all mentioned parameters can be adjusted on `Constellation`.
+
+- Every game, the first sequence contains `minSequenceLength` stars.
+- On each correct guess, the length of the sequence increases by one star (up to a maximum of the number of stars in the constellation).
+- If the player repeats a sequence of a certain length incorrectly `maxIncorrectSequence` times, the sequence length is reduced by one star.
+- If the sequence length has been reduced, the game will end the next time the player correctly repeats a sequence.
+
+### Between games (constellation size)
+
+Progression is as follows (all mentioned parameters are configurable on `StarMapManager`):
+- games start with the small constellation (5 stars total)
+- if the player completes a total of `maxScoreGames` _in a row_ with the maximum score (i.e. they repeated a sequence of length == the number of stars in the small constellation), the size is upgraded to the large constellation (10 stars)
+- From then on, all games use the large constellation. 
+
 ## Save data
 
 Data is saved to `StarMapScores.csv`, with one row per trial (i.e. one row per attempt at repeating a sequence of stars). This means there may be _multiple_ rows per played game. Values are:

docs/star-seek.md

@@ -21,6 +21,18 @@ The star seek mini-game uses gaze + head position to collect stars that appear a
   - Time required to collect a star (with both gaze + head pose crosshair aligned)
   - Level of bloom (glow) for a star with a single or double lock
 
+## Adaptive difficulty
+
+Difficulty is increased between games by increasing the overall time limit.
+
+Progression is as follows (all mentioned parameters are configurable on `StarSeekManager`):
+- games start with a time limit of `minTimeLimit`
+- a difficulty upgrade occurs when the player has completed `nGamesToUpgrade` games _in a row_ with:
+  - the same time limit 
+  - an average of `timeLimitUpgradeRate` stars collected per second
+- For each upgrade, the time limit is increased by `timeLimitIncrement` (up to a maximum of `maxTimeLimit`).
+- From then on, all games use the `maxTimeLimit`. 
+
 ## Save data
 
 Data is saved to `StarSeekScores.csv`, with one row per played game. Values are:

docs/zero-gravity.md

@@ -18,4 +18,9 @@ The zero gravity mini-game asks the player to copy various poses, and awards poi
 
 - **PoseAvatar**: values related to display of poses
   - Sprites for each pose
-  - Text explanations for each pose
+  - Text explanations for each pose
+
+
+## Adaptive difficulty
+
+Zero gravity has no adaptive difficulty. The poses, time limits and so on are the same for every game.

projects/AstroBalance/Assets/Scripts/SpaceWalking/SpaceWalkingManager.cs

@@ -82,7 +82,7 @@ void Start()
 
     /// <summary>
     /// Load previous game data (if any), and choose time limit + whether head turns are active
-    /// for this game based on prior perfomance.
+    /// for this game based on prior performance.
     /// </summary>
     private void ChooseGameDifficulty()
     {