The game begins with unparameterised SJ_START (1) and ends with SJ_END (19) followed by SJ_ENDSCREEN_CONTINUE (7). The game also is considered to have ended if the begin code for any other mini-game occurs. The game comprises multiple iterations of three phases: the maze task (which can be used as a measure of executive function), the Embedded Figures Test (where reaction times measure perceptual disembedding), and the "Sally-Anne" test of theory-of-mind.

Each level of the maze task begins with parameterised SJ_START (2) and ends with parameterised SJ_END (19). Each level of the maze task is interrupted by invocations of the Embedded Figures Test, and punctuated by an invocation of the Sally-Anne test. These latter two tests also can be invoked directly from the menu, without going through the maze test.

The Embedded Figures Test begins with SJ_EFT_START (49) and ends with SJ_EFT_END_FAIL (44) or SJ_EFT_END_SUCCESS (50).

The Sally-Anne test begins with SJ_SAT_START (52) and ends with SJ_SAT_END (53).

Following is a list of all the event codes, then a summary of the relevant behavioural and electrophysiological derived measures to extract:

<table BORDER="1">
<caption>Event codes (see <tt>autism_collaborative/Game/StarJack/EventCode.cs</tt>, <tt>autism_collaborative/Game/StarJack/Screen/SallyAnneScreen.cs</tt>), <tt>autism_collaborative/Game/StarJack/HackingPhase/HackingPhaseScreen.cs</tt>, <tt>autism_collaborative/Game/StarJack/Dungeon/DungeonScreen.cs</tt></caption>
<tr><td> 1
</td><td> SJ_START
</td><td> The game has begun.
</td></tr>

<tr><td> 2
</td><td> SJ_START     Level=Level_M|tutorialLevel Room=Room_N
</td><td> The player has entered a new maze level.
 Note that distinct numeric event codes (1 and 2) but one and the same string event descriptor (SJ_START) is used to denote the start of the game as a whole and to denote the start of an individual level of the maze within the game. The difference is the presence or absence of the parameters.
</td></tr>

<tr><td> 7
</td><td> SJ_MENU_INPUT_MouseClick
</td><td> The player has clicked the mouse to select a sub-portion of the game.
</td></tr>

<tr><td> 7
</td><td> SJ_ENDSCREEN_CONTINUE
</td><td> The player has clicked the mouse to continue past the game end screen, exiting the game.
 (Note same numeric code as SJ_MENU_INPUT_MouseClick above.)

</td></tr>

<tr><td COLSPAN="3">Maze Task Events</td></tr>

<tr><td> 9
</td><td> SJ_Cloak_Start
</td><td> In the maze, the player's avatar has activated the invisibility cloak.
</td></tr>

<tr><td> 10
</td><td> SJ_Cloak_End

</td><td> In the maze, the player's invisibility cloak has deactivated on reaching the end of its allowed time.
</td></tr>

<tr><td> 11
</td><td> SJ_TrapPlaced
</td><td> In the maze, the player's avatar has set a trap for the guards.
</td></tr>

<tr><td> 12
</td><td> SJ_GuardTrapped     (X, Y)=display coordinates

</td><td> A trap previously set by the player has captured a guard.
</td></tr>

<tr><td> 13
</td><td> SJ_Caught_TeleportToStart
</td><td> The player has been seen and caught by a guard or a camera, and teleports back to the starting position.
</td></tr>

<tr><td> 14
</td><td> SJ_INPUT_Esc
</td><td> The player has pressed the ESCAPE key to pause the game.

</td></tr>

<tr><td> 15
</td><td> SJ_MENU_INPUT_Enter
</td><td> The player has pressed the enter key to select a sub-portion of the game.
</td></tr>

<tr><td> 19
</td><td> SJ_END     Level=LevelN

</td><td> In the maze, the player has reached the end of the current level.
</td></tr>

<tr><td> 23
</td><td> SJ_INPUT_Move_Up
</td><td> In the maze, the player has pressed the up-arrow to move up.
</td></tr>

<tr><td> 24
</td><td> SJ_INPUT_Move_Down
</td><td> In the maze, the player has pressed the down-arrow to move down.

</td></tr>

<tr><td> 25
</td><td> SJ_INPUT_Move_Right
</td><td> In the maze, the player has pressed the right-arrow to move right.
</td></tr>

<tr><td> 26
</td><td> SJ_INPUT_Move_Left
</td><td> In the maze, the player has pressed the left-arrow to move left.
</td></tr>

<tr><td> 33
</td><td> SJ_INPUT_Interact
</td><td> In the maze, the player is interacting with an object or entity.
</td></tr>

<tr><td> 34
</td><td> SJ_INPUT_LeftClick     (X, Y)=display coordinates
</td><td> The player has clicked the left mouse button at the given display coordinates.

</td></tr>

<tr><td COLSPAN="3">Embedded Figures Test Events</td></tr>

<tr><td> 38
</td><td> SJ_EFT_Stimulus_Presented     Key=KeyN Figure=FigureM
</td><td> In the Embedded Figures Test, the player has been presented with a pair comprising a complex search figure and a smaller search target.

</td></tr>

<tr><td> 39
</td><td> SJ_EFT_HIT
</td><td> In the Embedded Figures Test, the SJ_EFT_INPUT_Match event immediately preceding was a correct response.
</td></tr>

<tr><td> 40
</td><td> SJ_EFT_REJECT
</td><td> In the Embedded Figures Test, the SJ_EFT_INPUT_NoMatch event immediately preceding was a correct response.
</td></tr>

<tr><td> 41
</td><td> SJ_EFT_FALSE_ALARM
</td><td> In the Embedded Figures Test, the SJ_EFT_INPUT_Match event immediately preceding was an incorrect response.
</td></tr>

<tr><td> 42
</td><td> SJ_EFT_MISS
</td><td> In the Embedded Figures Test, the SJ_EFT_INPUT_NoMatch event immediately preceding was an incorrect response.
</td></tr>

<tr><td> 44
</td><td> SJ_EFT_END_FAIL
</td><td> The player has given incorrect responses on three trials, ending the Embedded Figures Test.
</td></tr>

<tr><td> 46
</td><td> SJ_EFT_INPUT_NoMatch
</td><td> In the Embedded Figures Test, the player has indicated that the target does not occur within the given figure.
</td></tr>

<tr><td> 47

</td><td> SJ_EFT_INPUT_Match
</td><td> In the Embedded Figures Test, the player has indicated that the target occurs within the given figure.
</td></tr>

<tr><td> 48
</td><td> SJ_EFT_INPUT_Proceed
</td><td> The player has started a trial within the Embedded Figures Test.
</td></tr>

<tr><td> 49
</td><td> SJ_EFT_START

</td><td> The Embedded Figures Test has begun.
</td></tr>

<tr><td> 50
</td><td> SJ_EFT_END_SUCCESS
</td><td> The player has completed the Embedded Figures Test with fewer than three incorrect responses.
</td></tr>

<tr><td COLSPAN="3">Theory-of-Mind Task Events</td></tr>

<tr><td> 52

</td><td> SJ_SAT_START
</td><td> The theory-of-mind test (a.k.a. the "Sally-Anne test") has begun.
</td></tr>

<tr><td> 53
</td><td> SJ_SAT_END
</td><td> The theory-of-mind test (a.k.a. the "Sally-Anne test") has ended, after feedback has been given to the player.
</td></tr>

<tr><td> 55
</td><td> SJ_SAT_Video_Stop

</td><td> The currently active video has ended, and the player is being prompted to have it repeated or to continue.
 See details of the <A HREF="http://www.AutismCollaborative.org/wiki_aux/SJ_SAT_video_timecodes.txt">video event timings.
</td></tr>

<tr><td> 56
</td><td> IGNORE (VideoReplay)
</td><td> (This code should not be being transcribed onto the parallel port and thus should not be appearing in the EEG log.)
</td></tr>

<tr><td> 58

</td><td> SJ_SAT_INPUT_Continue
</td><td> The player has pressed the space bar, signalling readiness to view the next video stimulus. (This same numeric code also can appear with the notation "IGNORE" in which case it should not be being transcribed to the parallel port and this should not be appearing in the EEG log.)
</td></tr>

<tr><td> 59
</td><td> SJ_SAT_VideoStart_CargoDrop     Planet={TOP, RIGHT, BOTTOM, LEFT}
</td><td> The video showing the friendly space captain depositing the cargo on one of the planets has started.

</td></tr>

<tr><td> 60
</td><td> SJ_SAT_VideoStart_Pirate_Drop     Planet={TOP, RIGHT, BOTTOM, LEFT}
</td><td> The video showing the pirate depositing the cargo on another planet has started. The PLANET parameter will always differ from that of the previous SJ_SAT_VideoStart_Pirate_Theft.
</td></tr>

<tr><td> 61

</td><td> SJ_SAT_VideoStart_Pirate_Theft     Planet={TOP, RIGHT, BOTTOM, LEFT}
</td><td> The video showing the pirate's theft of the cargo has started. The PLANET parameter will always be the same as that of the previous SJ_SAT_VideoStart_CargoDrop.
</td></tr>

<tr><td> 62
</td><td> SJ_SAT_VideoStart_Pirate_NoTheft     Planet={TOP, RIGHT, BOTTOM, LEFT}

</td><td> The video showing the pirate's scan (but no theft) of the cargo has started. The PLANET parameter will always be the same as that of the previous SJ_SAT_VideoStart_CargoDrop.
</td></tr>

<tr><td> 64
</td><td> SJ_SAT_INPUT_Response_Top
</td><td> In response to a request to plot an intercept course, the player has pressed the up-arrow key, indicating a course to the TOP planet.
</td></tr>

<tr><td> 65

</td><td> SJ_SAT_INPUT_Response_Bottom
</td><td> In response to a request to plot an intercept course, the player has pressed the down-arrow key, indicating a course to the BOTTOM planet.
</td></tr>

<tr><td> 66
</td><td> SJ_SAT_INPUT_Response_Left
</td><td> In response to a request to plot an intercept course, the player has pressed the left-arrow key, indicating a course to the LEFT planet.
</td></tr>

<tr><td> 67
</td><td> SJ_SAT_INPUT_Response_Right

</td><td> In response to a request to plot an intercept course, the player has pressed the right-arrow key, indicating a course to the RIGHT planet.
</td></tr>

<tr><td> 68
</td><td> SJ_SAT_FirstOrder_NoTheft_Correct
</td><td> In the control condition in which no theft has occurred (probability 1/3), the player's response to the first-order question ("Where will you send a ship to meet up with the captain?") has correctly indicated the planet on which the cargo was originally cached by the captain (and on which it remains cached).
 Note that the numeric event code associated correctly with this event, 68, also is used by SJ_SAT_FirstOrder_NoTheft_Incorrect below. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 68
</td><td> SJ_SAT_FirstOrder_NoTheft_Incorrect

</td><td> In the control condition in which no theft has occurred, the player's response to the first-order question ("Where will you send a ship to meet up with the captain?") has indicated a planet other than that on which the cargo was originally cached by the captain (and on which it remains cached).
 Note that the numeric event code associated with this event, 68, is incorrect and ought to be 69. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 70
</td><td> SJ_SAT_FirstOrder_Scan_Correct
</td><td> In the scenario in which the admiral scans the pirate stealing and re-caching the cargo (probability 1/3), and reports this information to the captain, the player's correct response to the first-order question ("Where will you send a ship to meet up with the captain?") actually indicates higher-order theory-of-mind: the captain believes that the pirate believes that the captain believes that the cargo remains in the planet where the captain had originally cached it, thus the player's answer indicating the same PLANET as in the preceding SJ_SAT_VideoStart_CargoDrop and SJ_SAT_VideoStart_Cruiser_View_Theft is correct.
 Note that the numeric event code associated with this event, 70, is incorrect and ought to be 73. This error is the result of a bug in SallyAnneScreen.cs.

</td></tr>

<tr><td> 70
</td><td> SJ_SAT_FirstOrder_Theft_Correct
</td><td> In the scenario in which the pirate steals and re-caches the cargo (and the admiral cannot scan this activity and thus can't report anything to the captain) (probability 1/3), the player has correctly responded to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating that the captain will go to the planet on which she originally cached the cargo — that is, the same PLANET as in the preceding SJ_SAT_VideoStart_CargoDrop.
 Note that the numeric event code associated correctly with this event, 70, also is used by SJ_SAT_FirstOrder_Scan_Correct above. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 71
</td><td> SJ_SAT_FirstOrder_Theft_IncorrectTrueLocation
</td><td> In the scenario in which the pirate steals and re-caches the cargo (and the admiral cannot scan this activity and thus can't report anything to the captain), the player has responded incorrectly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating the true location of the cargo rather than the location believed by the captain.
</td></tr>

<tr><td> 72
</td><td> SJ_SAT_FirstOrder_Theft_IncorrectOtherLocation
</td><td> In the scenario in which the pirate steals and re-caches the cargo (and the admiral cannot scan this activity and thus can't report anything to the captain), the player has responded incorrectly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating one of the two planets that harbours neither the captain's original cache nor the pirate's subsequent cache. (This should hardly ever happen, and when it does happen it's as likely to be a consequence of keypress error as any other factor.)
</td></tr>

<tr><td> 74

</td><td> SJ_SAT_FirstOrder_Scan_IncorrectFakeLocation
</td><td> In the scenario in which the admiral scans the pirate stealing and re-caching the cargo, and reports this information to the captain, the player has responded incorrectly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating the captain's original hiding place (as though the admiral had not reported to the captain the pirate's new hiding place).
</td></tr>

<tr><td> 75
</td><td> SJ_SAT_FirstOrder_Scan_IncorrectOtherLocation
</td><td> In the scenario in which the admiral scans the pirate stealing and re-caching the cargo, and reports this information to the captain, the player has responded incorrectly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating one of the two planets that harbours neither the captain's original cache nor the pirate's subsequent cache. (This should hardly ever happen, and when it does happen it's as likely to be a consequence of keypress error as any other factor.)
</td></tr>

<tr><td> 76
</td><td> SJ_SAT_SecondOrder_NoTheft_Correct

</td><td> In the control condition in which the pirate scans but does not steal the cargo, the player has responded correctly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating the planet on which the captain cached the cargo.
 Note that the numeric event code associated correctly with this event, 76, also is used by SJ_SAT_SecondOrder_NoTheft_Incorrect below. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 76
</td><td> SJ_SAT_SecondOrder_NoTheft_Incorrect
</td><td> In the control condition in which the pirate scans but does not steal the cargo, the player has responded incorrectly to the first-order question ("Where will you send a ship to meet up with the captain?") by indicating one of the three planets that did not harbour the cargo.

 Note that the numeric event code associated with this event, 76, is incorrect and ought to be 77. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 78
</td><td> SJ_SAT_SecondOrder_Scan_Correct
</td><td> In the scenario in which the admiral scans the pirate stealing and re-caching the cargo, and reports this information to the captain, the player has responded correctly to the second-order question ("Where will you send a ship to intercept the pirate?") by indicating the planet on which the captain had originally cached the cargo. Because the pirate wants to find the captain, and the pirate believes (incorrectly) that the captain believes that the cargo remains where the captain originally cached it, the pirate will indeed go to the planet where the cargo was originally cached.
 Note that the numeric event code associated with this event, 78, is incorrect and ought to be 81. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 78
</td><td> SJ_SAT_SecondOrder_Theft_Correct

</td><td> In the scenario in which the pirate steals and re-caches the cargo (and the admiral cannot scan this activity and thus can't report anything to the captain), the player has responded correctly to the second-order question ("Where will you send a ship to intercept the pirate?") by indicating the planet on which the captain had originally cached the cargo. Because the pirate wants to find the captain, and the pirate believes (correctly) that the captain believes that the cargo remains where the captain originally cached it, the pirate will indeed go to the planet where the cargo was originally cached.
 Note that the numeric event code associated correctly with this event, 78, also is used by SJ_SAT_SecondOrder_Scan_Correct above. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 79
</td><td> SJ_SAT_SecondOrder_Theft_IncorrectTrueLocation
</td><td> In the scenario in which the pirate steals and re-caches the cargo (and the admiral cannot scan this activity and thus can't report anything to the captain), the player's response to the second-order question ("Where will you send a ship to intercept the pirate?") incorrectly reports the planet to which the cargo was moved by the pirate, instead of the planet on which the captain originally cached the cargo. Although the captain wants to find the cargo, the pirate wants to find the captain. Thus the pirate will move not to the planet on which he cached the cargo, but to the planet that he (correctly) believes that the captain believes the cargo is on, that is, the planet on which the captain originally cached the cargo.

<tr><td> 82

</td><td> SJ_SAT_SecondOrder_Scan_IncorrectTrueLocation
</td><td> In the scenario in which the admiral scans the pirate stealing and re-caching the cargo, and reports this information to the captain, the player's response to the second-order question ("Where will you send a ship to intercept the pirate?") incorrectly reports the planet to which the cargo was moved by the pirate, instead of the planet on which the captain originally cached the cargo. Although the captain wants to find the cargo, the pirate wants to find the captain. Thus the pirate will move not to the planet on which he cached the cargo, but to the planet that he (incorrectly) believes that the captain believes the cargo is on, that is, the planet on which the captain originally cached the cargo.
</td></tr>

<tr><td> 83
</td><td> SJ_SAT_SecondOrder_Scan_IncorrectOtherLocation
</td><td> n the scenario in which the admiral scans the pirate stealing and re-caching the cargo, and reports this information to the captain, the player's response to the second-order question ("Where will you send a ship to intercept the pirate?") incorrectly reports one of the two planets that harbours neither the captain's original cache nor the pirate's subsequent cache. (This should hardly ever happen, and when it does happen it's as likely to be a consequence of keypress error as any other factor.)
</td></tr>

<tr><td> 84
</td><td> SJ_SAT_FirstOrder_Question_Presented SJ_SAT_SecondOrder_Question_Presented
</td><td> After the explanatory text ("The captain wants to pick up the cargo. She will steer her ship to the planet where she thinks the cargo is. The pirate wants to find the captain. He will steer his ship to wherever he thinks the captain will go."), the first-order question ("Where will you send a ship to meet up with the captain?") or the second-order question ("Where will you send a ship to intercept the pirate?") has just been asked.
 Note that the same numeric event code, 84, is used for both SJ_SAT_FirstOrder_Question_Presented and SJ_SAT_SecondOrder_Question_Presented.
</td></tr>

<tr><td> 85
</td><td> SJ_SAT_VideoStart_Cruiser_View_Theft     Planet={TOP, RIGHT, BOTTOM, LEFT}

</td><td> The video showing the admiral's viewing of the theft has started. The PLANET parameter will always be the same as that of the previous SJ_SAT_VideoStart_CargoDrop.
 Note that the numeric event code associated with this event, 85, is incorrect and ought to be 86. This error is the result of a bug in SallyAnneScreen.cs.
</td></tr>

<tr><td> 85
</td><td> SJ_SAT_VideoStart_Cruiser_NoScan
</td><td> In the scenario in which the pirate has stolen and re-cached the cargo, and the admiral cannot scan this activity and thus can't report anything to the captain, the video showing only noise and interference on the admiral's viewscreen has started.
 Note that the numeric event code associated correctly with this event, 85, also is used by SJ_SAT_VideoStart_Cruiser_View_Theft above. This error is the result of a bug in SallyAnneScreen.cs.

</td></tr>

<tr><td> 87
</td><td> SJ_SAT_VideoStart_Cruiser_View_NoTheft     Planet={TOP, RIGHT, BOTTOM, LEFT}
</td><td> In the control condition in which no theft has occurred, the video showing the admiral's view of the pirate's scanning but not stealing the cargo has started.
</td></tr>

</table>

After deletion of codes 255 and greater, and alignment of the behavioural and EEG event sequences just as was done for Maritime Defender, processing should continue by correcting (both in the behavioural log file and in the EEG log file) the numeric event codes that are associated with the following string event descriptors in the behavioural log file (see notes in the table above):
 SJ_SAT_FirstOrder_NoTheft_Incorrect
 SJ_SAT_FirstOrder_Scan_Correct
 SJ_SAT_SecondOrder_NoTheft_Incorrect
 SJ_SAT_SecondOrder_Scan_Correct
 SJ_SAT_SecondOrder_Question_Presented
 SJ_SAT_VideoStart_Cruiser_View_Theft

SJ_EFT_INPUT_Match and SJ_EFT_INPUT_NoMatch events should be re-coded as context-free events based on the success flags (SJ_EFT_HIT, SJ_EFT_REJECT, SJ_EFT_FALSE_ALARM, SJ_EFT_MISS) that follow each of them. The success flags themselves then can be deleted, as they do not mark any actual events distinct from the SJ_EFT_INPUT_Match SJ_EFT_INPUT_NoMatch that they follow.

Similarly, SJ_SAT_INPUT_Response_{Top, Bottom, Left, Right} events should be re-coded as context-free events based on the success flags (SJ_SAT_FirstOrder_{*} and SJ_SAT_SecondOrder_{*}). In the re-coded events, both the four possible locations of the response (Top, Bottom, Left, Right) and the four possible correctness conditions of the response (Correct, IncorrectTrueLocation, IncorrectFakeLocation, IncorrectOtherLocation) should be preserved, thus there will be 4x4 = 16 possible codes. The success flags themselves then can be deleted, as they do not mark any actual events distinct from the SJ_SAT_INPUT_Response_{*} events that they follow.

''Behavioural measures related to executive function''

As simple behavioural measures of executive function, the software can compute - for each level separately and for all levels cumulatively - the total number of moves, the total time elapsed from start to finish (excluding time spent in EFT and SAT subtests), and the mean and standard deviation of the time between successive moves. Other measures are possible; if you think of one, try it!

''Behavioural measures related to perceptual disembedding''

d' ("d prime") should be computed from tallies of EFT hits, misses, false alarms and correct rejections. If the tally for any one of these four categories of responses is zero, that tally can be changed to 1 so as to estimate d'.

Mean and standard deviation of EFT reaction time, for correct responses only, should be computed. Also list out the single-trial reaction times.

''Behavioural measures related to theory-of-mind''

Single-trial data should be extracted and listed out for first-order and second-order questions in all trials. Three types of trials exist: the first-order control condition in which the pirate scans but does not steal the cargo (probability 1/3, and note that in this case it doesn't matter whether or not the admiral observes the pirate; the observed and unobserved cases can be collapsed into a single bin), the first-order theory-of-mind conditions in which the pirate steals the cargo but is not observed by the admiral (probability 1/3), and the second-order theory-of-mind condition in which the pirate steals the cargo but the admiral observes this theft and tells the captain (probability 1/3). The single-trial data should be listed first for the no-theft condition, then separately for the unobserved theft condition, then separately for the observed theft condition. The data for each trial comprise three timings and two correctness values: the time taken for the whole trial (SJ_SAT_END minus SJ_SAT_START), the reaction time for response to the first-order question (SJ_SAT_INPUT_Response_{*} minus SJ_SAT_FirstOrder_Question_Presented) and the correctness condition (Correct, IncorrectTrueLocation, IncorrectFakeLocation, IncorrectOtherLocation) of that response, and the reaction time for response to the second-order question (SJ_SAT_INPUT_Response_{*} minus SJ_SAT_SecondOrder_Question_Presented) and the correctness condition of that response.

Summaries of correctness conditions for each of the two question types (first order, second order) for each of the three theft conditions (no theft, unobserved theft, observed theft) should be given both as tallies and as percentages.

For correct responses only, means and standard deviations (where computable) should be given for the following reaction-time differences:

''First-order question:''
 Unobserved Theft minus No Theft
 Unobserved Theft minus Observed Theft
 Unobserved Theft minus (No Theft or Observed Theft, pooled)

''Second-order question:''
 Observed Theft minus Unobserved Theft
 Observed Theft minus No Theft
 Observed Theft minus (Unobserved Theft or No Theft, pooled)

''Independent Components Analysis''

ICA can be applied separately to epochs from the Embedded Figures Test, epochs from the Sally-Anne test, and perhaps continuous EEG for the maze task.

Remember not to include the skin-conductance channel (the greatest-numbered channel) in the ICA!

''Physiological measures related to perceptual disembedding''

Standard ERP and ERSP analyses can be constructed round the SJ_EFT_Stimulus_Presented event and corresponding SJ_EFT_INPUT_{*} response events.

''Physiological measures related to theory-of-mind''

Some possible fMRI-based contrasts:

Gaze perception (blink events or gaze aversion intervals versus direct gaze intervals)

Facial expression perception (scowl intervals versus neutral intervals)

Scene perception (egocentric view of person's face, versus allocentric view of person's hands on console, versus external view of spaceships)

Perception of body movements (hands) or gestures (nods)

Also note that, because these stimuli are cinematic, useful information can be gleaned from applying Uri Hasson's approach of correlating individual subjects' voxelwise activation time series against the group mean. This model-free procedure can identidy consistent activations, localised temporally and anatomically, across subjects. The timings of such consistent activities then can be correlated with the video timecodes (see link in the table above).

For EEG analyses, given the temporally extended nature of these stimuli spectral and other quantitative-EEG methods may be more appropriate than ERP's.

''Physiological measures related to executive function''

Here again, quantitative-EEG methods may be most appropriate. In addition, specific time-locked events may generate specific ERP's of interest, for example error-related negativity on SJ_INPUT_Move_{*} events that immediately precede SJ_Caught_TeleportToStart events.

Data analysis - StarJack

2011-06-07T10:57:00Z

Belmonte: new page, added all event codes

Functional specifications

2011-06-07T10:37:01Z

Belmonte: Inserted a link to 'Data Analysis - StarJack'

Welcome to this game's functional spec table of contents. There are two major parts: the colony simulator and the minigames.

[[Important Neuroscientific Considerations in Game Design for Autism]]

[[Data analysis - Maritime Defender]]

[[Data analysis - StarJack]]

'''Colony Simulator'''

[[Colony Mode]]

[[Factions]]

[[Structures]]

[[Consumables]]

[[Tasks]]

'''Minigames'''

[[Meteor Madness]] / Maritime Defender

[[Star Jack]] / Starjack

[[Stellar Prospector]]

[[Face Off]]

[[Factory Frenzy]] (Deprecated)

[[Mini Game Rewards]]

[[Mini Game Scenarios]]

Data analysis - Maritime Defender

2011-05-16T13:54:38Z

Belmonte: Added details on event codes, event code translations, and derived behavioural and electrophysiological measures

'''Maritime Defender'''

The game begins with MD_MaritimeDefenderGameBegin (41) and ends with MD_DotCoherenceEstimate (6). The game also is considered to have ended if the begin code for any other mini-game occurs. The game comprises multiple iterations of two phases, the shooter phase (testing go/no-go inhibition) and the navigation phase (testing motion coherence perception). The shooter phase begins with MD_ShooterPhaseBegin (13) and ends with either MD_DotPhaseBegin (1) or MD_BossPhaseBegin (32). The navigation phase begins with MD_DotPhaseBegin (1) and ends with either MD_ShooterPhaseBegin (13) or MD_BossPhaseBegin (32). Any phase also can be terminated with an End_of_log (0) code, which appears in the behavioural log file but not in the EEG log file. Following is a list of all the event codes, then a summary of the relevant behavioural and electrophysiological derived measures to extract:

<table BORDER="1">
<tr><td> 1
</td><td> MD_DotPhaseBegin
</td><td> The navigation phase (comprising many motion coherence trials) of the game has begun
</td></tr>

<tr><td> 2
</td><td> MD_DotTrialBegin
</td><td> One individual motion coherence trial (within the navigation phase) has begun
</td></tr>

<tr><td> 3
</td><td> MD_DotTrialExpire
</td><td> A motion coherence trial has timed out without any behavioural response
</td></tr>

<tr><td> 4
</td><td> MD_DotTrialUserRespondLeft
</td><td> The player has pressed the left arrow during a motion coherence trial
</td></tr>

<tr><td> 5

</td><td> MD_DotTrialUserRespondRight
</td><td> The player has pressed the right arrow during a motion coherence trial
</td></tr>

<tr><td> 6
</td><td> MD_DotCoherenceEstimate
</td><td> At the end of a navigation phase, the maximum-likelihood estimator has recalculated the psychophysical perceptual threshold for motion coherence
</td></tr>

<tr><td> 7
</td><td> MD_ShipIdentifierTestBegin

</td><td> At the beginning of the game, the friend-or-foe ship identifier dialogue has begun
</td></tr>

<tr><td> 8
</td><td> MD_ShipIdentifierSelectLeft
</td><td> During the friend-or-foe ship identifier dialogue, the player has pressed the left arrow
</td></tr>

<tr><td> 9
</td><td> MD_ShipIdentifierSelectRight
</td><td> During the friend-or-foe ship identifier dialogue, the player has pressed the right arrow

</td></tr>

<tr><td> 10
</td><td> MD_ShipIdentifierConfirmSelection
</td><td> During the friend-or-foe ship identifier dialogue, the player has pressed the return key to confirm their selection
</td></tr>

<tr><td> 11
</td><td> MD_ShipIdentifierTestEndSuccess
</td><td> The player's response in the friend-or-foe ship identifier dialogue is correct
</td></tr>

<tr><td> 12
</td><td> MD_ShipIdentifierTestEndFailure
</td><td> The player's response in the friend-or-foe ship identifier dialogue is incorrect
</td></tr>

<tr><td> 13
</td><td> MD_ShooterPhaseBegin
</td><td> The shooter phase (comprising many go/no-go trials) of the game has begun
</td></tr>

<tr><td> 14
</td><td> MD_ShooterActivateOpenWormholeBeam
</td><td> During the shooter phase, the player has depressed the up-arrow to activate the wormhole-opener beam
</td></tr>

<tr><td> 15
</td><td> MD_ShooterCeaseOpenWormholeBeam
</td><td> During the shooter phase, the player has released the up-arrow to cease the wormhole-opener beam
</td></tr>

<tr><td> 16

</td><td> MD_ShooterOpenWormholeSuccess
</td><td> During the shooter phase, the wormhole-opener beam has opened the wormhole
</td></tr>

<tr><td> 17
</td><td> MD_ShooterActivateMovePort
</td><td> During the shooter phase, the player has depressed the left-arrow to begin moving clockwise
</td></tr>

<tr><td> 18
</td><td> MD_ShooterCeaseMovePort

</td><td> During the shooter phase, the player has released the left-arrow to cease moving clockwise
</td></tr>

<tr><td> 19
</td><td> MD_ShooterActivateMoveStarboard
</td><td> During the shooter phase, the player has depressed the right-arrow key to begin moving anticlockwise
</td></tr>

<tr><td> 20
</td><td> MD_ShooterCeaseMoveStarboard
</td><td> During the shooter phase, the player has released the right-arrow key to cease moving anticlockwise

</td></tr>

<tr><td> 21
</td><td> MD_ShooterPresentFriendly
</td><td> During the shooter phase, a friendly ship has emerged from an opened wormhole
</td></tr>

<tr><td> 22
</td><td> MD_ShooterPresentEnemy
</td><td> During the shooter phase, a hostile ship has emerged from an opened wormhole
</td></tr>

<tr><td> 23
</td><td> MD_ShooterPresentWormhole
</td><td> During the shooter phase, a wormhole has appeared
</td></tr>

<tr><td> 24
</td><td> MD_ShooterActivateFireWeapon
</td><td> During the shooter phase, the player has depressed the space bar to begin firing
</td></tr>

<tr><td> 25
</td><td> MD_ShooterCeaseFireWeapon
</td><td> During the shooter phase, the player has released the space bar to cease firing
</td></tr>

<tr><td> 26
</td><td> MD_ShooterPlayerWeaponFired
</td><td> During the shooter phase, the weapon has fired (Multiple WeaponFired events can occur between an ActivateFireWeapon and a CeaseFireWeapon, as the space bar is held down for continuous fire)
</td></tr>

<tr><td> 27

</td><td> MD_ShooterEnemyWeaponFired
</td><td> During the shooter phase, a hostile ship has fired at the player
</td></tr>

<tr><td> 28
</td><td> MD_ShooterCollectibleSpawned
</td><td> During the shooter phase, a collectible has emerged from a destroyed asteroid or from a friendly ship
</td></tr>

<tr><td> 29
</td><td> MD_ShooterPlayerCollectibleCollision

</td><td> During the shooter phase, the player's ship has picked up a collectible
</td></tr>

<tr><td> 30
</td><td> MD_ShooterMeteorExplosion
</td><td> During the shooter phase, an asteroid has exploded
</td></tr>

<tr><td> 31
</td><td> MD_ShooterPlayerGetsHit
</td><td> During the shooter phase, the player's ship has been hit by hostile fire or by an asteroid

</td></tr>

<tr><td> 32
</td><td> MD_BossPhaseBegin
</td><td> The 'boss phase' has begun - no scientifically important events here, just entertainment and reward for completing the level
</td></tr>

<tr><td> 33
</td><td> MD_GameSuccess
</td><td> The player has successfully completed the boss phase, beating the game

</td></tr>

<tr><td> 34
</td><td> MD_GameFailure
</td><td> During any game phase (shooter, navigation, or boss), the player's last of three ships has been destroyed, losing the game
</td></tr>

<tr><td> 35
</td><td> MD_DialogSkip
</td><td> The player has skipped a dialogue

</td></tr>

<tr><td> 36
</td><td> MD_MenuSelect
</td><td> The player has selected an item in the menu
</td></tr>

<tr><td> 37
</td><td> MD_MenuCancel
</td><td> The player has cancelled the menu
</td></tr>

<tr><td> 38
</td><td> MD_Pause
</td><td> The player has paused the game
</td></tr>

<tr><td> 39
</td><td> MD_Unpause
</td><td> The player has unpaused the game
</td></tr>

<tr><td> 40
</td><td> MD_OpenConsole
</td><td> The player has opened the console
</td></tr>

<tr><td> 41
</td><td> MD_MaritimeDefenderGameBegin
</td><td> The game has begun
</td></tr>

<tr><td> 42
</td><td> MD_CockpitDamageFeedback
</td><td> During the navigation phase, the cockpit shakes, indicating damage and loss of energy, following a non-response or an incorrect response
</td></tr>

<tr><td> 43
</td><td> MD_TutorialStart
</td><td> The optional tutorial has begun
</td></tr>

<tr><td> 44
</td><td> MD_Section1
</td><td> This and the next several codes define the times of entry into the tutorial's several successive sections:
</td></tr>

<tr><td> 45
</td><td> MD_Section2
</td><td></td></tr>

<tr><td> 46
</td><td> MD_Section3

</td><td></td></tr>

<tr><td> 47
</td><td> MD_Section4
</td><td></td></tr>

<tr><td> 48
</td><td> MD_Section5
</td><td></td></tr>

<tr><td> 49
</td><td> MD_Section6

</td><td></td></tr>

<tr><td> 50
</td><td> MD_Section7
</td><td></td></tr>

<tr><td> 51
</td><td> MD_Section8
</td><td></td></tr>

<tr><td> 52
</td><td> MD_Section9

</td><td></td></tr>

<tr><td> 53
</td><td> MD_Section10
</td><td></td></tr>

<tr><td> 54
</td><td> MD_Section11
</td><td></td></tr>

<tr><td> 55
</td><td> MD_Section12

</td><td></td></tr>

<tr><td> 56
</td><td> MD_Section13
</td><td></td></tr>

<tr><td> 57
</td><td> MD_Section14
</td><td></td></tr>

<tr><td> 58
</td><td> MD_Section15

</td><td></td></tr>

<tr><td> 59
</td><td> MD_Section16
</td><td></td></tr>

<tr><td> 60
</td><td> MD_TutorialEnd
</td><td> The tutorial has ended
</td></tr>
</table>

The processing software should delete all existing event codes greater than or equal to 255. These codes are inserted by the BioSemi EEG recording hardware and are not needed.

The processing software then must align (both by sequence and by specific temporal offset) the event codes in the EEG record with the event codes in the game log. The game log is the master copy of the event codes; codes transmitted to the EEG recorder can sometimes be erroneously dropped or, more rarely, erroneously replicated.

Lastly, the processing software must translate context-sensitive event codes (for example, a stimulus, contextualised by either an incorrect behavioural response or a correct behavioural response following) into context-free event codes as detailed below. Events that already are context-free should simply be transcribed as is. All events - both those that are being translated and those that are being transcribed - should be renumbered so that their codes are greater than 255 and in a range dedicated to each mini-game separately. This constraint could be implemented, for example, by adding 1000 to the transcribed event codes for Maritime Defender, adding 2000 to those for Stellar Prospector, and so on, creating a separate, non-overlapping range of event codes for each mini-game.

These event code translations, and all derived behavioural data as detailed below, should be integrated into Keith Yoder's Astropolis Processing Toolkit so that they are fully automated and can be performed at the touch of a button by a user who knows nothing of computer programming.

''Independent Components Analysis''

For the shooter phase, ICA can be applied to epochs beginning with MD_ShooterOpenWormholeSuccess and ending with MD_ShooterActivateFireWeapon, MD_ShooterEnemyWeaponFired, or MD_ShooterCollectibleSpawned, whichever comes first.

For the navigation phase, ICA can be applied to the entire continuous EEG record from the first MD_DotTrialBegin after the MD_DotPhaseBegin, up till the first event that is NOT any of MD_DotTrialBegin (2), MD_DotTrialExpire (3), MD_UserRespondLeft (4), MD_UserRespondRight (5), or MD_CockpitDamageFeedback (42).

Remember not to include the skin-conductance channel (the greatest-numbered channel) in the ICA!

''Potentials related to behavioural inhibition''

Go trials and no-go trials each can be successful or unsuccessful; there are therefore four categories of events each beginning with an MD_ShooterPresentFriendly (21) which signals a no-go trial or an MD_ShooterPresentEnemy (22) which signals a go trial. The analysis software should use the context provided by subsequent events to translate these two codes into four codes as follows:

At an MD_ShooterPresentFriendly (21), if there is no MD_ShooterActivateFireWeapon (24) until the next MD_ShooterCollectibleSpawned (28) or until 5 seconds have elapsed, whichever is sooner, then code this event as MD_ShooterNoGoSUCCEED. Otherwise code MD_ShooterNoGoFAIL. This new event code replaces the originally logged MD_ShooterPresentFriendly, and is inserted into the data at the time time stamp as the originally logged event.

At an MD_ShooterPresentEnemy (22), if there is no MD_ShooterActivateFireWeapon (24) until the next MD_ShooterEnemyWeaponFired (27) or until 5 seconds have elapsed, whichever is sooner, then code this event as MD_ShooterGoFAIL. Otherwise code MD_ShooterGoSUCCEED. This new event code replaces the originally logged MD_ShooterPresentFriendly, and is inserted into the data at the time time stamp as the originally logged event.

MD_ShooterActivateFireWeapon events within MD_ShooterNoGoFAIL sequences should be re-coded as MD_ShooterWeaponFALSE_ALARM. MD_ShooterActivateFireWeapon events within MD_ShooterGoSUCCEED sequences should be re-coded as MD_ShooterWeaponHIT.

The following behavioural measures can be computed: 
1. Reaction time: The mean and standard deviation of reaction time for MD_ShooterGoSUCCEED can be calculated from the intervals between the relevant MD_ShooterPresentEnemy and MD_ShooterActivateFireWeapon events. 
2. Accuracy: d' can be calculated where hits are MD_ShooterGoSUCCEED, misses are MD_ShooterGoFAIL, false alarms are MD_ShooterNoGoFAIL, and correct rejections are MD_ShooterNoGoSUCCEED.

''Motor and preparatory potentials''

For the events MD_ShooterActivateMovePort (17), MD_ShooterActivateMoveStarboard (19), and MD_ShooterActivateOpenWormholeBeam (14), both the bereitschaftspotential (readiness potential, from supplementary motor area) ERP and the event-related desynchronisation of the mu rhythm near the hand area (lateral central electrodes) can be computed.

The interval between MD_ShooterOpenWormholeSuccess (16) and MD_ShooterGoSUCCEED will evoke a Contingent Negative Variation at frontocentral electrodes which resolves into a motor execution. The interval between MD_ShooterOpenWormholeSuccess (16) and MD_ShooterNoGoSUCCEED will evoke the same Contingent Negative Variation, followed by a further inhibition-related negativity instead of by motor execution. Both the CNV beginning at the time of MD_ShooterOpenWormholeSuccess and the response-related activities time-locked to MD_ShooterGoSUCCEED and MD_ShooterNoGoSUCCEED are of interest.

The following behavioural measures can be computed:
1. Between each pair of MD_ShooterPresentWormhole (23) and MD_ShooterOpenWormholeSuccess (16): 
1A. Elapsed time (mean and SD) 
1B. Number of distinct movement commands (MD_ShooterActivateMovePort (17) or MD_ShooterActivateMoveStarboard (19)), and also the mean and SD of this quantity after Anscombe transformation or other Poisson-to-normal transformation. 
2. A detailed curve, with a sequence number (1, 2, 3, ...) of the wormhole event on the x axis and the number of movement commands on the y axis; does the player improve as time goes on?

''Potentials related to attention and context updating''

P3 on MD_ShooterNoGoSUCCEED, and separately on MD_ShooterGoSUCCEED: mean half-integral amplitude and latency.

Frontal negativity following MD_ShooterNoGoSUCCEED (contrast to the same following MD_ShooterGoSUCCEED).

P1 on MD_ShooterNoGoSUCCEED and MD_ShooterGoSUCCEED pooled.

''Potentials related to motion perception''

Leftward-drifting trials and rightward-drifting trials each can be successful or unsuccessful; there are therefore four categories of events each beginning with an MD_DotTrialBegin (2). The analysis software should use the context provided by subsequent events to translate this code into six codes as follows:

At an MD_DotTrialBegin Direction=Left followed by MD_UserRespondLeft as the very next event, code MD_DotLeftHIT, and similarly at an MD_DotTrialBegin Direction=Right followed by MD_UserRespondRight as the very next event, code MD_DotRightHIT.

At an MD_DotTrialBegin Direction=Left followed by MD_UserRespondRight as the very next event, code MD_DotLeftFALSE_ALARM, and similarly at an MD_DotTrialBegin Direction=Right followed by MD_UserRespondLeft as the very next event, code MD_DotRightFALSE_ALARM.

At an MD_DotTrialBegin Direction=Left whose next event is neither MD_UserRespondLeft nor MD_UserRespondRight is an MD_DotLeftMISS, and similarly an MD_DotTrialBegin Direction=Right whose next event is neither MD_UserRespondLeft nor MD_UserRespondRight is an MD_DotRightMISS.

MD_UserRespondLeft events following MD_DotLeftHIT, and MD_UserRespondRight events following MD_DotRightHIT, should be re-coded as MD_DotResponseHIT.

MD_UserRespondRight events following MD_DotLeftFALSE_ALARM, and MD_UserRespondLeft events following MD_DotRightFALSE_ALARM, should be re-coded as MD_DotResponseFALSE_ALARM.

MD_CockpitDamageFeedback events immediately following MD_DotResponseFALSE_ALARM events should be re-coded as MD_DotFeedbackFALSE_ALARM. MD_CockpitDamageFeedback events immediately following MD_DotTrialBegin events should be re-coded as MD_DotFeedbackMISS.

ERPs and ERSPs time-locked to each of the six MD_Dot stimulus onset events can be compared; pilot data indicate that the ERSPs would show event-related desynchronisations in occipital generators. (There might not be sufficient FALSE_ALARM events for reliable averaging, in which case just the HIT and MISS events can be compared.) Likewise, ERPs and ERSPs time-locked to each of the three (or two, if there are insufficient numbers of false alarms) MD_DotResponse events can be compared.

''Potentials related to reward''

MD_ShooterCollectibleCollision (29) and MD_ShooterMeteorExplosion (30) both can be examined for a cingulate negativity related to reward value which occurs between 250 and 350 ms post-stimulus; see Yeung et al. http://dx.doi.org/10.1093/cercor/bhh153

Skin conductance response (recorded on the highest-numbered channel) may also be of particular interest during these events.

''Potentials related to error processing''

MD_ShooterWeaponFALSE_ALARM events should generate a cingulate error-related negativity; this error-related negativity can be most straightforwardly visualised by computing a difference wave: subtract the ERP associated with MD_ShooterWeaponHIT events from the ERP associated with MD_ShooterWeaponFALSE_ALARM events.

During the navigation phase, a couple of strategies might be applied to discern the error-related negativity associated with erroneous responses: The right way to do it, if there were enough MD_DotResponseFALSE_ALARM events available for reliable ERP averaging, would be to subtract the ERP associated with MD_DotResponseHIT events from the ERP associated with MD_DotResponseFALSE_ALARM events. But there probably won't be sufficient numbers of false-alarm responses for that. Instead of false alarms, subjects who are unable to discern the motion direction probably will generate misses - that is, no overt behavioural response at all. So we can look at the ERP associated with MD_DotFeedbackMISS (without any subtraction).

Skin conductance response (recorded on the highest-numbered channel) may also be of particular interest during these events.

Important Neuroscientific Considerations in Game Design for Autism

2011-05-16T04:07:53Z

Belmonte: add a caution on repetitive behaviours

'''Neuroscientific Considerations in Game Design for Autism'''

'''If there's a way to use a game feature as an object of repetitive behaviour, a player with autism will find it..''' Players with autism often find predictable sensory contingencies more rewarding than unpredictable, surprising events. So whereas non-autistic players could be expected to self-motivate to 'level up' or in general to proceed through the game narrative, autistic players often are more content to keep on repeating the same feature, or causing the game to produce the same sound or visual effect. These purely sensory effects can be much more salient and motivating to a person with autism than the less tangible and immediate, more abstract and future-oriented effect of, say, a game score or a power-up. So, for instance, an autistic player might become fascinated with the sound effect that takes place when their avatar is destroyed, and therefore keep 'dying' on purpose, just to hear the sound effect - clearly a strategy that thwarts the intended game mechanic! When designing and implementing a game, put yourself in the place of the player with autism, asking yourself, "What sensory aspects of this game could a person become fixated on?" Try to move the player through the game, nudging them away from such repetitive behaviours and into new experiences. At the same time, though, you can use limited, rationed opportunities for repetitive behaviour as a reward and a motivation for moving through the game - e.g. a game structure that allows a player ten (and only ten) repetitions of their favourite sound effect once they've done the hard work of reaching the next level.
 In his memoir There's a Boy in Here, Sean Barron describes his own autistic fascination with repetition and predictability:
 ‘I loved repetition. Every time I turned on a light I knew what would happen. When I flipped the switch, the light went on. It gave me a wonderful feeling of security because it was the same each time…. Even when I knew, it was thrilling to do it over and over. It was always the same.'
 ‘People bothered me. I didn’t know what they were for or what they would do to me. They were not always the same and I had no security with them at all….'

'''Avoid timed events; give the player control of when things happen; whenever possible, prompt the player.'''
People with autism have difficulty with executive function, that is, in rapidly planning and executing actions in response to sensory inputs. They have a great deal of skill and often exceed the performance of people without autism -- but it's a intensely studied and considered, deliberate style of skill, often not expressed under time pressure. So it's important to make certain that the timing of events is controlled not by the computer (except in cases where the experiment requires it) but by the player. Small additions such as a "next" button or a "ready" button can make all the difference. (An example of the event-driven rather than time-driven structure is the use of the up-arrow key to connect with the wormhole in the Maritime Defender mini-game.)

'''Do not depend on a player's memory for instructions; prompt the player every time.'''
A corollary of the executive planning problem is that the player may have trouble remembering a sequence of steps. Even if (s)he has learnt in a tutorial that key A triggers action X and key B triggers action Y, these arbitrary associations might not be remembered, unless the player has had a chance to practise these actions actively, many times over.

Another corollary of this memory problem: '''Do not make input-output mappings depend on the game state.''' You might be tempted to hide functions inside submenus, access to which depends on the player's clicking on the right primary menu, or to make a drag of the mouse do something different after a click than after no click (or even worse, something different after a left-click than after a right-click). Avoid such sequential logic in the user interface. Wherever possible, use purely combinational logic. Some sequential logic is of course unavoidable -- otherwise we wouldn't be able to have separate mini-games! -- but it ought to be used sparingly and only when absolutely required.

'''Instead of a sequence of actions, ask for one action at a time.'''
Rapid actions can be difficult enough by themselves, but when people with autism face the additional demand of performing several of these actions rapidly and in the proper sequence thay can feel very much overwhelmed. (See the previous entries on executive function and memory.) Instead of requiring sequences of inputs in response to a single prompt, try to prompt separately for each input.

'''Use pictures, not words.'''
Most people with autism tend to think in pictures rather than words. Instructions presented as text might not be comprehended -- not because the player is incapable of comprehending but because (s)he's concentrating so much on decoding the individual words that (s)he can't spare much effort to put those words together into the meanings of complete sentences and narratives. Sometimes text is unavoidable; if text is used, avoid verbosity and don't clutter the display with words. Reading can be slow; see the entry on ''timed events'' above about waiting and prompting the player to continue.

'''Players should learn by doing, not just by observing or reading or listening.'''
In this regard, people with autism are no different from people without autism: we all learn best when we can be active rather than passive learners. The challenges faced by people with autism make it even more crucial that game activities involve learning-by-doing, rather than depending on learning-by-reading or learning-by-listening. This is particularly true of the game tutorials.

'''Avoid depending on simultaneous or near-simultaneous events in different perceptual channels (e.g. different places on the screen, or different senses such as video with audio).'''
People with autism focus intensely and exclusively on one perceptual channel at a time. When focusing on one point or area of the display, events away from this spatial focus of attention may not register. Anathema for a person with autism would be a cockpit display with many gauges indicating different quantities which all need to be observed simultaneously -- or a visual display that needs to be observed at the same time as a spoken or other auditory signal. (Background music is okay because it doesn't need to be attended; players can just let it go on whilst they focus on the visual display.) Instead, either information should be displayed in one region of the display or one sensory channel, or ample time should be allowed to shift attention between points in visual space or between sensory channels. Shifts of attention can take 2 to 3 seconds for people with autism, whereas people without autism take 0.2 to 0.3 seconds. Think about what it would be like to be looking at the display through a long telescope that magnifies a small area but shuts out the periphery.

'''Avoid evoking unnecessary anxiety.'''
People with autism are '''much''' more prone to anxiety than people without autism -- especially when faced with a new and unpractised task, or with a timed task, or with an interactive situation that's out of their control. (See entries above on avoiding timed events and giving prompting, pictures, and practice.) Do everything possible to make certain that the player, not the computer, is the one controlling what happens next, and that the player has every opportunity to practise and to become comfortable with the demands of the game.

'''For repeating events, vary the timing slightly so that the time between two successive instances of the event is not constant.'''
This consideration actually isn't about accommodating people with autism; rather, it's about accommodating EEG analysis. Those of you who know something about signal processing will be familiar with the phenomenon of '''aliasing''' in which a discrete sampling of a high-frequency signal at too low a sampling rate produces an artefactual low-frequency oscillation. The problem here has a lot in common with aliasing. Consider as an example the situation that exists when the firing button is pressed and held: the weapons will fire at a certain rate, say, once every 500 ms. Suppose that we're interested in the brain response to the combined auditory and visual effects associated with weapons firing. Suppose also, though, that there is an ongoing, endogenous (that is, internally driven) 10 hz oscillation in the player's brain that has nothing to do with these exogenous stimuli. Since 500 ms is an integral multiple of the 100 ms period of this oscillation, when we sample the exogenous brain response to each weapons firing we're going to end up also sampling the endogenous oscillation at the same point in its phase every time, and we will thus misattribute the endogenous signal as an exogenous response to the weapons firing. To forestall this ambiguity in EEG analysis, we can add a small amount of temporal jitter to the intervals between firings - not so much as to make them seem unnaturally jittery to the player, but enough to get rid of this phase artefact. The exact amount depends on what seems natural given the event separation; in this example of a 500 ms event we might deem that any variation more than 10% of the interval in either direction would seem unnatural, so we might then choose to vary the intervals over a uniform distribution from 450 ms to 550 ms. Given the frequencies of the signals in which we're interested, it isn't ever necessary to add more than 150 ms (that is, 75 ms in either direction) of temporal jitter. Add as much temporal jitter as you can, up to this 150 ms limit - but don't sacrifice playability.

'''Log event codes for everything - absolutely everything.'''
This is another consideration for EEG analysis. Did the weapons just fire (even though the firing key is being held down constantly)? That's an event. Did some sort of motion start or stop or change speed? That's an event. Absolutely everything that happens in the game should be reported with an event code. (See "Game/Engine/Logger.cs".) We can always ignore event codes if we decide that they aren't of interest in our analysis. What we can't do is go back and insert event codes after the data have been recorded. So put everything in.

'''SEE ALSO'''

http://www.gamasutra.com/view/feature/3538/designing_games_that_are_.php

"Designing Games that are Accessible to Everyone" by Eitan Glinert

Data analysis - Maritime Defender

2011-03-19T16:27:39Z

Belmonte: New page: '''Maritime Defender''' The game begins with MD_MaritimeDefenderGameBegin (41) and ends with MD_DotCoherenceEstimate (6). The game also is considered to have ended if the begin code for ...

'''Maritime Defender'''

The game begins with MD_MaritimeDefenderGameBegin (41) and ends with MD_DotCoherenceEstimate (6). The game also is considered to have ended if the begin code for any other mini-game occurs.

''Independent Components Analysis''

For the shooter phase, ICA can be applied to epochs beginning with MD_ShooterOpenWormholeSuccess and ending with MD_ShooterActivateFireWeapon, MD_ShooterEnemyWeaponFired, or MD_ShooterCollectibleSpawned, whichever comes first.

For the navigation phase, ICA can be applied to the entire continuous EEG record from the first MD_DotTrialBegin after the MD_DotPhaseBegin, up till the first event that is NOT any of MD_DotTrialBegin (2), MD_DotTrialExpire (3), MD_UserRespondLeft (4), MD_UserRespondRight (5), or MD_CockpitDamageFeedback (42).

''Potentials related to behavioural inhibition''

Go trials and no-go trials each can be successful or unsuccessful; there are therefore four categories of events each beginning with an MD_ShooterPresentFriendly (21) which signals a no-go trial or an MD_ShooterPresentEnemy (22) which signals a go trial. The analysis software should use the context provided by subsequent events to translate these two codes into four codes as follows:

At an MD_ShooterPresentFriendly (21), if there is no MD_ShooterActivateFireWeapon (24) until the next MD_ShooterCollectibleSpawned (28) or until 5 seconds have elapsed, whichever is sooner, then code this event as MD_ShooterNoGoSUCCEED. Otherwise code MD_ShooterNoGoFAIL. This new event code replaces the originally logged D_ShooterPresentFriendly, and is inserted into the data at the time time stamp as the originally logged event.

At an MD_ShooterPresentEnemy (22), if there is no MD_ShooterActivateFireWeapon (24) until the next MD_ShooterEnemyWeaponFired (27) or until 5 seconds have elapsed, whichever is sooner, then code this event as MD_ShooterGoFAIL. Otherwise code MD_ShooterGoSUCCEED. This new event code replaces the originally logged D_ShooterPresentFriendly, and is inserted into the data at the time time stamp as the originally logged event.

MD_ShooterActivateFireWeapon events within MD_ShooterNoGoFAIL sequences should be re-coded as MD_ShooterWeaponFALSE_ALARM. MD_ShooterActivateFireWeapon events within MD_ShooterGoSUCCEED sequences should be re-coded as MD_ShooterWeaponHIT.

As a behavioural measure, the mean and standard deviation of reaction time for MD_ShooterGoSUCCEED can be calculated from the intervals between the relevant MD_ShooterPresentEnemy and MD_ShooterActivateFireWeapon events. Also, d' can be calculated where hits are MD_ShooterGoSUCCEED, misses are MD_ShooterGoFAIL, false alarms are MD_ShooterNoGoFAIL, and correct rejections are MD_ShooterNoGoSUCCEED.

''Motor and preparatory potentials''

For the events MD_ShooterActivateMovePort (17), MD_ShooterActivateMoveStarboard (19), and MD_ShooterActivateOpenWormholeBeam (14), both the bereitschaftspotential (readiness potential, from supplementary motor area) ERP and the event-related desynchronisation of the mu rhythm near the hand area (lateral central electrodes) can be computed.

The interval between MD_ShooterOpenWormholeSuccess (16) and MD_ShooterGoSUCCEED will evoke a Contingent Negative Variation at frontocentral electrodes which resolves into a motor execution. The interval between MD_ShooterOpenWormholeSuccess (16) and MD_ShooterNoGoSUCCEED will evoke the same Contingent Negative Variation, followed by a further inhibition-related negativity instead of by motor execution. Both the CNV beginning at the time of MD_ShooterOpenWormholeSuccess and the response-related activities time-locked to MD_ShooterGoSUCCEED and MD_ShooterNoGoSUCCEED are of interest.

As a behavioural measure, between each pair of MD_ShooterPresentWormhole (23) and MD_ShooterOpenWormholeSuccess (16), both the elapsed time and the number of distinct movement commands (MD_ShooterActivateMovePort (17) or MD_ShooterActivateMoveStarboard (19)) can be computed.

''Potentials related to motion perception''

Leftward-drifting trials and rightward-drifting trials each can be successful or unsuccessful; there are therefore four categories of events each beginning with an MD_DotTrialBegin (2). The analysis software should use the context provided by subsequent events to translate this code into six codes as follows:

At an MD_DotTrialBegin Direction=Left followed by MD_UserRespondLeft as the very next event, code MD_DotLeftHIT, and similarly at an MD_DotTrialBegin Direction=Right followed by MD_UserRespondRight as the very next event, code MD_DotRightHIT.

At an MD_DotTrialBegin Direction=Left followed by MD_UserRespondRight as the very next event, code MD_DotLeftFALSE_ALARM, and similarly at an MD_DotTrialBegin Direction=Right followed by MD_UserRespondLeft as the very next event, code MD_DotRightFALSE_ALARM.

At an MD_DotTrialBegin Direction=Left whose next event is neither MD_UserRespondLeft nor MD_UserRespondRight is an MD_DotLeftMISS, and similarly an MD_DotTrialBegin Direction=Right whose next event is neither MD_UserRespondLeft nor MD_UserRespondRight is an MD_DotRightMISS.

MD_UserRespondLeft events following MD_DotLeftHIT, and MD_UserRespondRight events following MD_DotRightHIT, should be re-coded as MD_DotResponseHIT.

MD_UserRespondRight events following MD_DotLeftFALSE_ALARM, and MD_UserRespondLeft events following MD_DotRightFALSE_ALARM, should be re-coded as MD_DotResponseFALSE_ALARM.

MD_CockpitDamageFeedback events immediately following MD_DotResponseFALSE_ALARM events should be re-coded as MD_DotFeedbackFALSE_ALARM. MD_CockpitDamageFeedback events immediately following MD_DotTrialBegin events should be re-coded as MD_DotFeedbackMISS.

ERPs and ERSPs time-locked to each of the six MD_Dot stimulus onset events can be compared; pilot data indicate that the ERSPs would show event-related desynchronisations in occipital generators. (There might not be sufficient FALSE_ALARM events for reliable averaging, in which case just the HIT and MISS events can be compared.) Likewise, ERPs and ERSPs time-locked to each of the three (or two, if there are insufficient numbers of false alarms) MD_DotResponse events can be compared.

''Potentials related to reward''

MD_ShooterCollectibleCollision (29) and MD_ShooterMeteorExplosion (30) both can be examined for a cingulate negativity related to reward value which occurs between 250 and 350 ms post-stimulus; see Yeung et al. http://dx.doi.org/10.1093/cercor/bhh153

''Potentials related to error processing''

MD_ShooterWeaponFALSE_ALARM events should generate a cingulate error-related negativity; this error-related negativity can be most straightforwardly visualised by computing a difference wave: subtract the ERP associated with MD_ShooterWeaponHIT events from the ERP associated with MD_ShooterWeaponFALSE_ALARM events.

During the navigation phase, a couple of strategies might be applied to discern the error-related negativity associated with erroneous responses: The right way to do it, if there were enough MD_DotResponseFALSE_ALARM events available for reliable ERP averaging, would be to subtract the ERP associated with MD_DotResponseHIT events from the ERP associated with MD_DotResponseFALSE_ALARM events. But there probably won't be sufficient numbers of false-alarm responses for that. Instead of false alarms, subjects who are unable to discern the motion direction probably will generate misses - that is, no overt behavioural response at all. So we can look at the ERP associated with MD_DotFeedbackMISS (without any subtraction).

Functional specifications

2011-03-19T16:26:47Z

Belmonte:

Welcome to this game's functional spec table of contents. There are two major parts: the colony simulator and the minigames.

[[Important Neuroscientific Considerations in Game Design for Autism]]

[[Data analysis - Maritime Defender]]

'''Colony Simulator'''

[[Colony Mode]]

[[Factions]]

[[Structures]]

[[Consumables]]

[[Tasks]]

'''Minigames'''

[[Meteor Madness]] / Maritime Defender

[[Star Jack]] / Starjack

[[Stellar Prospector]]

[[Face Off]]

[[Factory Frenzy]] (Deprecated)

[[Mini Game Rewards]]

[[Mini Game Scenarios]]

Functional specifications

2011-03-19T13:15:38Z

Belmonte: added a link to a new section on data analysis

Welcome to this game's functional spec table of contents. There are two major parts: the colony simulator and the minigames.

[[Important Neuroscientific Considerations in Game Design for Autism]]

[[Analysis of behavioural and physiological data from game play]]

'''Colony Simulator'''

[[Colony Mode]]

[[Factions]]

[[Structures]]

[[Consumables]]

[[Tasks]]

'''Minigames'''

[[Meteor Madness]] / Maritime Defender

[[Star Jack]] / Starjack

[[Stellar Prospector]]

[[Face Off]]

[[Factory Frenzy]] (Deprecated)

[[Mini Game Rewards]]

[[Mini Game Scenarios]]

End-user Setup

2011-03-05T10:33:21Z

Belmonte: added details on where to find individual users' experiment logs

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

===Lab, Home and Debug configurations===

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

(When the game is being run from within the debugger, a third configuration script, DebugConfig.script, is used.)

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.UseFlickering = true;
* Determines whether or not to use flickering

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

===Audio Stimuli Experiment===

Tones will played at intervals based on the sound delay (AS_SOUND_DELAY) and max jitter (AS_MAX_JITTER) as specified in the config file, in floating-point units of seconds. The stimulus onset asynchrony between tones is calculated by adding AS_SOUND_DELAY to a random number in the range of 0 to AS_MAX_JITTER. The tone is the same each time, but the volume is chosen at random from the volumes specifiend in the config file.

Volumes are in arbitrary units on a linear (not dB) scale between 0 and 1.0. Experimenters should calibrate these units using a sound level meter to measure actual volumes in dB SPL produced by their sound card and speaker system, and modify AS_VOLUME1, AS_VOLUME2, AS_VOLUME3 and AS_VOLUME4 so that they produce the desired levels.

Each time a tone is played, an event is written to the log. See the next section for all possible event codes and formats.

Event Codes

AS_START

AS_TONE_PLAYED Volume=[volume] Tone=[tone # refers to the number n in the AS_VOLUMEn parameter]

AS_END

Config File Format

AS_SOUND_DELAY = [stimulus onset asynchrony, in seconds]

AS_MAX_JITTER = [maximum range of random jitter added AS_SOUND_DELAY]

AS_MAX_PLAYS = [total number of times that each tones is played]

AS_VOLUME1 = [volume]

AS_VOLUME2 = [volume]

AS_VOLUME3 = [volume]

AS_VOLUME4 = [volume]

AS_SOUND = [80dBl_Right or 80dBlLeft]

Important Notes:

- All spaces in the config file are necessary for the program to parse

- Make sure there is no white space after the final line

- all volumes must be expressed in double format (must include decimal, ex. 1.0 is correct, 1 is not)

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

Although it may seem natural to look in the "LogFiles" directory, the user-specific log file containing each individual's log data is instead found in each individual user's subdirectory within the "Users" directory:

Users\[AstropolisUserName]\LogFiles\ExperimentLog.txt

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

If the computer has a parallel port, the 8-bit numeric event codes in the log file are also placed on the parallel port as 5ms pulses (bounded by 5ms of zeroes on all eight data lines). Codes then can be read from a physiological or behavioural data recorder such as an EEG recorder, an MRI scanner, or a gaze tracker, and the full record from the log file can be synchronised to the event-code sequence in the data recorder, allowing examination of physiological or behavioural events as a function of stimuli and responses that occur during game play. The parallel port is used in compatibility mode only; enhanced mode is not used.

End-user Setup

2011-02-26T06:34:29Z

Belmonte: added parallel-port information

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

===Lab, Home and Debug configurations===

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

(When the game is being run from within the debugger, a third configuration script, DebugConfig.script, is used.)

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.UseFlickering = true;
* Determines whether or not to use flickering

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

===Audio Stimuli Experiment===

Tones will played at intervals based on the sound delay (AS_SOUND_DELAY) and max jitter (AS_MAX_JITTER) as specified in the config file, in floating-point units of seconds. The stimulus onset asynchrony between tones is calculated by adding AS_SOUND_DELAY to a random number in the range of 0 to AS_MAX_JITTER. The tone is the same each time, but the volume is chosen at random from the volumes specifiend in the config file.

Volumes are in arbitrary units on a linear (not dB) scale between 0 and 1.0. Experimenters should calibrate these units using a sound level meter to measure actual volumes in dB SPL produced by their sound card and speaker system, and modify AS_VOLUME1, AS_VOLUME2, AS_VOLUME3 and AS_VOLUME4 so that they produce the desired levels.

Each time a tone is played, an event is written to the log. See the next section for all possible event codes and formats.

Event Codes

AS_START

AS_TONE_PLAYED Volume=[volume] Tone=[tone # refers to the number n in the AS_VOLUMEn parameter]

AS_END

Config File Format

AS_SOUND_DELAY = [stimulus onset asynchrony, in seconds]

AS_MAX_JITTER = [maximum range of random jitter added AS_SOUND_DELAY]

AS_MAX_PLAYS = [total number of times that each tones is played]

AS_VOLUME1 = [volume]

AS_VOLUME2 = [volume]

AS_VOLUME3 = [volume]

AS_VOLUME4 = [volume]

AS_SOUND = [80dBl_Right or 80dBlLeft]

Important Notes:

- All spaces in the config file are necessary for the program to parse

- Make sure there is no white space after the final line

- all volumes must be expressed in double format (must include decimal, ex. 1.0 is correct, 1 is not)

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

If the computer has a parallel port, the 8-bit numeric event codes in the log file are also placed on the parallel port as 5ms pulses (bounded by 5ms of zeroes on all eight data lines). Codes then can be read from a physiological or behavioural data recorder such as an EEG recorder, an MRI scanner, or a gaze tracker, and the full record from the log file can be synchronised to the event-code sequence in the data recorder, allowing examination of physiological or behavioural events as a function of stimuli and responses that occur during game play. The parallel port is used in compatibility mode only; enhanced mode is not used.

Important Neuroscientific Considerations in Game Design for Autism

2009-08-05T01:34:50Z

Belmonte:

'''Neuroscientific Considerations in Game Design for Autism'''

'''Avoid timed events; give the player control of when things happen; whenever possible, prompt the player.'''
People with autism have difficulty with executive function, that is, in rapidly planning and executing actions in response to sensory inputs. They have a great deal of skill and often exceed the performance of people without autism -- but it's a intensely studied and considered, deliberate style of skill, often not expressed under time pressure. So it's important to make certain that the timing of events is controlled not by the computer (except in cases where the experiment requires it) but by the player. Small additions such as a "next" button or a "ready" button can make all the difference. (An example of the event-driven rather than time-driven structure is the use of the up-arrow key to connect with the wormhole in the Maritime Defender mini-game.)

'''Do not depend on a player's memory for instructions; prompt the player every time.'''
A corollary of the executive planning problem is that the player may have trouble remembering a sequence of steps. Even if (s)he has learnt in a tutorial that key A triggers action X and key B triggers action Y, these arbitrary associations might not be remembered, unless the player has had a chance to practise these actions actively, many times over.

Another corollary of this memory problem: '''Do not make input-output mappings depend on the game state.''' You might be tempted to hide functions inside submenus, access to which depends on the player's clicking on the right primary menu, or to make a drag of the mouse do something different after a click than after no click (or even worse, something different after a left-click than after a right-click). Avoid such sequential logic in the user interface. Wherever possible, use purely combinational logic. Some sequential logic is of course unavoidable -- otherwise we wouldn't be able to have separate mini-games! -- but it ought to be used sparingly and only when absolutely required.

'''Instead of a sequence of actions, ask for one action at a time.'''
Rapid actions can be difficult enough by themselves, but when people with autism face the additional demand of performing several of these actions rapidly and in the proper sequence thay can feel very much overwhelmed. (See the previous entries on executive function and memory.) Instead of requiring sequences of inputs in response to a single prompt, try to prompt separately for each input.

'''Use pictures, not words.'''
Most people with autism tend to think in pictures rather than words. Instructions presented as text might not be comprehended -- not because the player is incapable of comprehending but because (s)he's concentrating so much on decoding the individual words that (s)he can't spare much effort to put those words together into the meanings of complete sentences and narratives. Sometimes text is unavoidable; if text is used, avoid verbosity and don't clutter the display with words. Reading can be slow; see the entry on ''timed events'' above about waiting and prompting the player to continue.

'''Players should learn by doing, not just by observing or reading or listening.'''
In this regard, people with autism are no different from people without autism: we all learn best when we can be active rather than passive learners. The challenges faced by people with autism make it even more crucial that game activities involve learning-by-doing, rather than depending on learning-by-reading or learning-by-listening. This is particularly true of the game tutorials.

'''Avoid depending on simultaneous or near-simultaneous events in different perceptual channels (e.g. different places on the screen, or different senses such as video with audio).'''
People with autism focus intensely and exclusively on one perceptual channel at a time. When focusing on one point or area of the display, events away from this spatial focus of attention may not register. Anathema for a person with autism would be a cockpit display with many gauges indicating different quantities which all need to be observed simultaneously -- or a visual display that needs to be observed at the same time as a spoken or other auditory signal. (Background music is okay because it doesn't need to be attended; players can just let it go on whilst they focus on the visual display.) Instead, either information should be displayed in one region of the display or one sensory channel, or ample time should be allowed to shift attention between points in visual space or between sensory channels. Shifts of attention can take 2 to 3 seconds for people with autism, whereas people without autism take 0.2 to 0.3 seconds. Think about what it would be like to be looking at the display through a long telescope that magnifies a small area but shuts out the periphery.

'''Avoid evoking unnecessary anxiety.'''
People with autism are '''much''' more prone to anxiety than people without autism -- especially when faced with a new and unpractised task, or with a timed task, or with an interactive situation that's out of their control. (See entries above on avoiding timed events and giving prompting, pictures, and practice.) Do everything possible to make certain that the player, not the computer, is the one controlling what happens next, and that the player has every opportunity to practise and to become comfortable with the demands of the game.

'''For repeating events, vary the timing slightly so that the time between two successive instances of the event is not constant.'''
This consideration actually isn't about accommodating people with autism; rather, it's about accommodating EEG analysis. Those of you who know something about signal processing will be familiar with the phenomenon of '''aliasing''' in which a discrete sampling of a high-frequency signal at too low a sampling rate produces an artefactual low-frequency oscillation. The problem here has a lot in common with aliasing. Consider as an example the situation that exists when the firing button is pressed and held: the weapons will fire at a certain rate, say, once every 500 ms. Suppose that we're interested in the brain response to the combined auditory and visual effects associated with weapons firing. Suppose also, though, that there is an ongoing, endogenous (that is, internally driven) 10 hz oscillation in the player's brain that has nothing to do with these exogenous stimuli. Since 500 ms is an integral multiple of the 100 ms period of this oscillation, when we sample the exogenous brain response to each weapons firing we're going to end up also sampling the endogenous oscillation at the same point in its phase every time, and we will thus misattribute the endogenous signal as an exogenous response to the weapons firing. To forestall this ambiguity in EEG analysis, we can add a small amount of temporal jitter to the intervals between firings - not so much as to make them seem unnaturally jittery to the player, but enough to get rid of this phase artefact. The exact amount depends on what seems natural given the event separation; in this example of a 500 ms event we might deem that any variation more than 10% of the interval in either direction would seem unnatural, so we might then choose to vary the intervals over a uniform distribution from 450 ms to 550 ms. Given the frequencies of the signals in which we're interested, it isn't ever necessary to add more than 150 ms (that is, 75 ms in either direction) of temporal jitter. Add as much temporal jitter as you can, up to this 150 ms limit - but don't sacrifice playability.

'''Log event codes for everything - absolutely everything.'''
This is another consideration for EEG analysis. Did the weapons just fire (even though the firing key is being held down constantly)? That's an event. Did some sort of motion start or stop or change speed? That's an event. Absolutely everything that happens in the game should be reported with an event code. (See "Game/Engine/Logger.cs".) We can always ignore event codes if we decide that they aren't of interest in our analysis. What we can't do is go back and insert event codes after the data have been recorded. So put everything in.

'''SEE ALSO'''

http://www.gamasutra.com/view/feature/3538/designing_games_that_are_.php

"Designing Games that are Accessible to Everyone" by Eitan Glinert

Important Neuroscientific Considerations in Game Design for Autism

2009-08-05T01:34:10Z

Belmonte: added a corollary on avoiding sequential logic in the UI

'''Neuroscientific Considerations in Game Design for Autism'''

'''Avoid timed events; give the player control of when things happen; whenever possible, prompt the player.'''
People with autism have difficulty with executive function, that is, in rapidly planning and executing actions in response to sensory inputs. They have a great deal of skill and often exceed the performance of people without autism -- but it's a intensely studied and considered, deliberate style of skill, often not expressed under time pressure. So it's important to make certain that the timing of events is controlled not by the computer (except in cases where the experiment requires it) but by the player. Small additions such as a "next" button or a "ready" button can make all the difference. (An example of the event-driven rather than time-driven structure is the use of the up-arrow key to connect with the wormhole in the Maritime Defender mini-game.)

'''Do not depend on a player's memory for instructions; prompt the player every time.'''
A corrollary of the executive planning problem is that the player may have trouble remembering a sequence of steps. Even if (s)he has learnt in a tutorial that key A triggers action X and key B triggers action Y, these arbitrary associations might not be remembered, unless the player has had a chance to practise these actions actively, many times over.

Another corollary of this memory problem: '''Do not make input-output mappings depend on the game state.''' You might be tempted to hide functions inside submenus, access to which depends on the player's clicking on the right primary menu, or to make a drag of the mouse do something different after a click than after no click (or even worse, something different after a left-click than after a right-click). Avoid such sequential logic in the user interface. Wherever possible, use purely combinational logic. Some sequential logic is of course unavoidable -- otherwise we wouldn't be able to have separate mini-games! -- but it ought to be used sparingly and only when absolutely required.

'''Instead of a sequence of actions, ask for one action at a time.'''
Rapid actions can be difficult enough by themselves, but when people with autism face the additional demand of performing several of these actions rapidly and in the proper sequence thay can feel very much overwhelmed. (See the previous entries on executive function and memory.) Instead of requiring sequences of inputs in response to a single prompt, try to prompt separately for each input.

'''Use pictures, not words.'''
Most people with autism tend to think in pictures rather than words. Instructions presented as text might not be comprehended -- not because the player is incapable of comprehending but because (s)he's concentrating so much on decoding the individual words that (s)he can't spare much effort to put those words together into the meanings of complete sentences and narratives. Sometimes text is unavoidable; if text is used, avoid verbosity and don't clutter the display with words. Reading can be slow; see the entry on ''timed events'' above about waiting and prompting the player to continue.

'''Players should learn by doing, not just by observing or reading or listening.'''
In this regard, people with autism are no different from people without autism: we all learn best when we can be active rather than passive learners. The challenges faced by people with autism make it even more crucial that game activities involve learning-by-doing, rather than depending on learning-by-reading or learning-by-listening. This is particularly true of the game tutorials.

'''Avoid depending on simultaneous or near-simultaneous events in different perceptual channels (e.g. different places on the screen, or different senses such as video with audio).'''
People with autism focus intensely and exclusively on one perceptual channel at a time. When focusing on one point or area of the display, events away from this spatial focus of attention may not register. Anathema for a person with autism would be a cockpit display with many gauges indicating different quantities which all need to be observed simultaneously -- or a visual display that needs to be observed at the same time as a spoken or other auditory signal. (Background music is okay because it doesn't need to be attended; players can just let it go on whilst they focus on the visual display.) Instead, either information should be displayed in one region of the display or one sensory channel, or ample time should be allowed to shift attention between points in visual space or between sensory channels. Shifts of attention can take 2 to 3 seconds for people with autism, whereas people without autism take 0.2 to 0.3 seconds. Think about what it would be like to be looking at the display through a long telescope that magnifies a small area but shuts out the periphery.

'''Avoid evoking unnecessary anxiety.'''
People with autism are '''much''' more prone to anxiety than people without autism -- especially when faced with a new and unpractised task, or with a timed task, or with an interactive situation that's out of their control. (See entries above on avoiding timed events and giving prompting, pictures, and practice.) Do everything possible to make certain that the player, not the computer, is the one controlling what happens next, and that the player has every opportunity to practise and to become comfortable with the demands of the game.

'''For repeating events, vary the timing slightly so that the time between two successive instances of the event is not constant.'''
This consideration actually isn't about accommodating people with autism; rather, it's about accommodating EEG analysis. Those of you who know something about signal processing will be familiar with the phenomenon of '''aliasing''' in which a discrete sampling of a high-frequency signal at too low a sampling rate produces an artefactual low-frequency oscillation. The problem here has a lot in common with aliasing. Consider as an example the situation that exists when the firing button is pressed and held: the weapons will fire at a certain rate, say, once every 500 ms. Suppose that we're interested in the brain response to the combined auditory and visual effects associated with weapons firing. Suppose also, though, that there is an ongoing, endogenous (that is, internally driven) 10 hz oscillation in the player's brain that has nothing to do with these exogenous stimuli. Since 500 ms is an integral multiple of the 100 ms period of this oscillation, when we sample the exogenous brain response to each weapons firing we're going to end up also sampling the endogenous oscillation at the same point in its phase every time, and we will thus misattribute the endogenous signal as an exogenous response to the weapons firing. To forestall this ambiguity in EEG analysis, we can add a small amount of temporal jitter to the intervals between firings - not so much as to make them seem unnaturally jittery to the player, but enough to get rid of this phase artefact. The exact amount depends on what seems natural given the event separation; in this example of a 500 ms event we might deem that any variation more than 10% of the interval in either direction would seem unnatural, so we might then choose to vary the intervals over a uniform distribution from 450 ms to 550 ms. Given the frequencies of the signals in which we're interested, it isn't ever necessary to add more than 150 ms (that is, 75 ms in either direction) of temporal jitter. Add as much temporal jitter as you can, up to this 150 ms limit - but don't sacrifice playability.

'''Log event codes for everything - absolutely everything.'''
This is another consideration for EEG analysis. Did the weapons just fire (even though the firing key is being held down constantly)? That's an event. Did some sort of motion start or stop or change speed? That's an event. Absolutely everything that happens in the game should be reported with an event code. (See "Game/Engine/Logger.cs".) We can always ignore event codes if we decide that they aren't of interest in our analysis. What we can't do is go back and insert event codes after the data have been recorded. So put everything in.

'''SEE ALSO'''

http://www.gamasutra.com/view/feature/3538/designing_games_that_are_.php

"Designing Games that are Accessible to Everyone" by Eitan Glinert

End-user Setup

2009-02-23T03:29:30Z

Belmonte: corrected inaccuracies and resolved ambiguities

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

===Lab, Home and Debug configurations===

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

(When the game is being run from within the debugger, a third configuration script, DebugConfig.script, is used.)

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.UseFlickering = true;
* Determines whether or not to use flickering

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

===Audio Stimuli Experiment===

Tones will played at intervals based on the sound delay (AS_SOUND_DELAY) and max jitter (AS_MAX_JITTER) as specified in the config file, in floating-point units of seconds. The stimulus onset asynchrony between tones is calculated by adding AS_SOUND_DELAY to a random number in the range of 0 to AS_MAX_JITTER. The tone is the same each time, but the volume is chosen at random from the volumes specifiend in the config file.

Volumes are in arbitrary units on a linear (not dB) scale between 0 and 1.0. Experimenters should calibrate these units using a sound level meter to measure actual volumes in dB SPL produced by their sound card and speaker system, and modify AS_VOLUME1, AS_VOLUME2, AS_VOLUME3 and AS_VOLUME4 so that they produce the desired levels.

Each time a tone is played, an event is written to the log. See the next section for all possible event codes and formats.

Event Codes

AS_START

AS_TONE_PLAYED Volume=[volume] Tone=[tone # refers to the number n in the AS_VOLUMEn parameter]

AS_END

Config File Format

AS_SOUND_DELAY = [stimulus onset asynchrony, in seconds]

AS_MAX_JITTER = [maximum range of random jitter added AS_SOUND_DELAY]

AS_MAX_PLAYS = [total number of times that each tones is played]

AS_VOLUME1 = [volume]

AS_VOLUME2 = [volume]

AS_VOLUME3 = [volume]

AS_VOLUME4 = [volume]

AS_SOUND = [80dBl_Right or 80dBlLeft]

Important Notes:

- All spaces in the config file are necessary for the program to parse

- Make sure there is no white space after the final line

- all volumes must be expressed in double format (must include decimal, ex. 1.0 is correct, 1 is not)

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

System Specifications and Testing

2009-02-21T05:44:27Z

Belmonte: updated Thinkpad T43 versus T43p

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">


<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>

<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>

<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>

<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>

<tr><td>Lenovo Thinkpad T61p</td><td>Windows XP SP2</td><td>Intel Core 2 Duo T7500, 2.2 GHz</td><td>nVidia Quadro FX 570M</td><td>2 GB</td></tr>

<tr><td>IBM Thinkpad T43p</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility FIRE GL V3200</td><td>128 MB</td></tr>

<tr><th colspan="5">SLOW</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>

<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>

<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>

<tr><th colspan="5">NOT FUNCTIONAL</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>

<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>

<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>

</table>

System Specifications and Testing

2009-02-05T21:17:21Z

Belmonte: /* Tested Hardware */

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">


<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>

<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>

<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>

<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>

<tr><td>Lenovo Thinkpad T61p</td><td>Windows XP SP2</td><td>Intel Core 2 Duo T7500, 2.2 GHz</td><td>nVidia Quadro FX 570M</td><td>2 GB</td></tr>

<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>

<tr><th colspan="5">SLOW</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>

<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>

<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>

<tr><th colspan="5">NOT FUNCTIONAL</th></tr>

<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>

</table>

System Specifications and Testing

2009-02-05T21:13:01Z

Belmonte: /* Tested Hardware */

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">
<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Lenovo Thinkpad T61p</td><td>Windows XP SP2</td><td>Intel Core 2 Duo T7500, 2.2 GHz</td><td>nVidia Quadro FX 570M</td><td>2 GB</td></tr>
<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>
<tr><th colspan="5">SLOW</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>
<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>
<tr><th colspan="5">NOT FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>
</table>

System Specifications and Testing

2009-02-05T21:11:06Z

Belmonte: moved rows

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">
<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>
<td>nVidia Quadro FX 570M</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Lenovo Thinkpad T61p</td><td>Windows XP SP2</td><td>Intel Core 2 Duo T7500, 2.2 GHz</td><tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>
<tr><th colspan="5">SLOW</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>
<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>
<tr><th colspan="5">NOT FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>
</table>

System Specifications and Testing

2009-02-05T21:09:49Z

Belmonte: added Lenovo T61p

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">
<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>
<tr><td>Lenovo Thinkpad T61p</td><td>Windows XP SP2</td><td>Intel Core 2 Duo T7500, 2.2 GHz</td><td>nVidia Quadro FX 570M</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>
<tr><th colspan="5">SLOW</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>
<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>
<tr><th colspan="5">NOT FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>
</table>

System Specifications and Testing

2009-02-05T20:57:41Z

Belmonte: corrected Mac Pro details

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">
<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Mac Pro 3,1</td><td>Windows XP SP2</td><td>dual Quad-Core Intel Xeon, 2.8 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>
<tr><th colspan="5">SLOW</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>
<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>
<tr><th colspan="5">NOT FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>
</table>

System Specifications and Testing

2009-02-05T15:40:01Z

Belmonte: updated list of tested hardware

== System Requirements ==
=== Windows XP or Vista ===

Hardware:
o A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

Software:
o DirectX End-User Runtime or newer.
o Microsoft .NET Framework Version 2.0 or newer.
o Microsoft XNA Framework Redistributable 2.0

=== Development ===

Software:
o Microsoft XNA Game Studio 2.0
o Tortoise SVN or other Subversion Client

== Tested Hardware ==
<table border="1">
<tr><th colspan="5">FULLY FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Mac Pro</td><td>Windows XP SP2</td><td>dual Intel Core 2 Duo, 2.4 GHz</td><td>nVidia GeForce 8800 GT</td><td>32 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>Dell Inspiron 1720</td><td>Windows Vista Ultimate</td><td>Intel Core 2 Duo, 2 GHz</td><td>nVidia GeForce 8600M GT</td><td>2 GB</td></tr>
<tr><td>IBM Thinkpad T43</td><td>Windows XP SP2</td><td>Intel Pentium-M, 2 GHz</td><td>ATI Mobility Radeon X300</td><td>64 MB</td></tr>
<tr><th colspan="5">SLOW</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>Dell Inspiron e1505</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.83 GHz</td><td>ATI Mobility Radeon X1400</td><td>2 GB</td></tr>
<tr><td>MacBook Air 1,1</td><td>Windows XP SP2</td><td>Intel Core 2 Duo, 1.6 GHz</td><td>Intel GMA X3100 integrated graphics</td><td>2 GB</td></tr>
<tr><th colspan="5">NOT FUNCTIONAL</th></tr>
<tr><th>Model</th><th>System</th><th>Processor</th><th>Graphics</th><th>RAM</th></tr>
<tr><td>IBM Thinkpad T41</td><td colspan="2"></td><td>ATI Mobility Radeon 7500</td><td></td></tr>
</table>

Code How To's

2009-01-28T20:32:18Z

Belmonte: /* Write to the Experiment Log */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Go to http://www.AutismCollaborative.org/bugs/
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are used by only one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declarations or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

For a step by step tutorial with code examples, see [[How_to_Make_a_Mini-Game]]

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewMiniame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from GameScreen
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = gameTime.ElapsedGameTime;
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
** Be sure to call each entity's Draw and Update methods. Optional: Register all entities with the XNA game object.
This will have XNA automatically call their Draw and Update functions at appropriate times.
** Consider using a generalized render-queue such as GenericWorldSpace '''(not yet implemented as of October 2007)'''
** Use the Raise function to place the minigame gamescreen on the stack based game system.
* End the mini-game using Done function. This will pop the mini-game off the game stack, returning the game to the previous state.
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Show the score

==Use Images==

XNA supports most common types of images, including JPEG, GIF, DDS, etc.

===Load a Texture===

Before you can load a texture in code, though, you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right-click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory using the XNA content manager:

Texture2D myTexture = Content.Load(@"General\myTexture");

The XNA content manager defaults to the content folder of the project, so all addresses can be relative from there. Also, the name of the image should be the same as the asset name. This can be set in the properties window.

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are created using the AnimatedSprite class. Here's an example:

//Declare Animated Sprite
//Parameters: Game object, SpriteSheet as a Texture2D object, Position as Vector2, FrameSize as Vector2, Number of Frames
AnimatedSprite testAnimation = new AnimatedSprite(this, Content.Load<Texture2D>("TestSpriteSheet"), new Vector2(200, 300), new Vector2(64, 64), 16);
//Pass a reference to the SpriteBatch that the AnimatedSprite will use
testAnimation.SpriteBatch = spriteBatch;
//Turn on the Animation
testAnimation.Animate(true);
//Turn off the Animation
testAnimation.Animate(false);

*Do not forget to call the draw and update methods of the AnimatedSprite explicitly, or to add them to the XNA game.components array so as to allow XNA to call them.

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.Mouse) because tAC_Engine does a lot of caching and logging behind the scenes. Use the InputHandler instead.

===Keyboard Example===

// Bind the 'A' Key to the event 'PressedA'
mInputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)EventCodes.PressedA);
...
InputEvent inputEvent = mInputHandler.GetNextEvent();
if (inputEvent.EventCode == (int)EventCodes.PressedA)
{
// The A key was pressed
}

===Loading Keybinds from a file===

// Load Bindings from 'keybindings.dat'
mInputHandler.LoadBindings(typeof(EventCodes), RootDirectory + @"\keybindings.dat");

The Bindings file is a plain text, human-editable file that takes the following form:

"Event Name" (tab*) "Key Name" (tab*) (flags*)

====Keybinding Examples====

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text==

First you must import the desired font:

* Create an xml spritefont file for the new font called FontName.spritefont and set the desired values.

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
SpriteFont = cm.Load<SpriteFont>(@"FontName");

sb.Begin();
sb.DrawString(SpriteFont, "Some Text!", new Vector2(10.0F, 10.0F), Color.Azure);
sb.End();

==Use Sound==

===Import a new Audio File===

** Run the XACT tool from Microsoft DirectX SDK
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open AudioProject.xap file for the Minigame to which you wish to add a sound.
* Expand Wave Banks and double-click Wave Bank in the panel on the left
* Expand Sound Banks and double-click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import i.e."@/MiniGame/Content/Audio/MySound.wav" and click OK.
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Assign the audio file to be either a Music or Effect sound
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right-click the Sounds folder and select Add->Existing Item...
* Select "MySound.wav" and click OK

=== Load an Audio Project ===
This needs to be done before you play any sound or effect.
SoundManager.LoadAudioProject("AudioProject.xgs");

===Play an Effect===

SoundManager.PlayEffect("Pew"); // No file extension

===Play Music ===

SoundManager.PlayMusic("MyMusic");

==Use the Particle Engine==

Particles are handled by the TACParticleEngine, a separate library that uses the AC_GraphicsEngine that has been modified to better fit the needs of the Autism Game. Features are added to it on an as-needed basis so if a new feature needs to be added and any problems arise in its integration into the current particle engine contact Brian Murphy.

Quick layout of TACParticleEngine:

The ParticleManager contains references to all loaded ParticleEngines.
ParticleEngines contain a series of Emitters.
Emitters contain a heap of Particles, which are the objects that actually get drawn.

Make sure to include these packages so that we can create and access our particle engine objects:

using TACParticleEngine;
using TACParticleEngine.Particles;

Inside the class declaration make these global variables:

ParticleManager mParticleManager;
ParticleEngine mTestEffect;

Since the TACParticleEngine makes use of the Camera class from the AC_GraphicsEngine, we will need to create and initialize an instance of the Camera class if we are to render our particles, so let's get our camera set before we initialize the ParticleManager.

Add the following line to the list of global variables at the beginning of the class:

Camera mActiveCamera;

This will be whatever kind of camera we are currently using for drawing. (We may want other cameras, too, for whatever reason.)

Next we need to initialize the camera to any specific type of camera that derives from class Camera. At the time of this writing (January 2009) these types are limited to FollowCamera, OrthographicCamera, PerspectiveCamera2D, and PerspectiveCamera3D. For now we'll use a PerspectiveCamera3D as our active camera.

mActiveCamera = new Perspective3DCamera(new Vector3(0, 0, -5), Vector3.Zero, Vector3.Up, MathHelper.Pi/5, 1, 1, 100);

If we ever need to change the camera, be certain to update the active camera for the particle manager by calling
mParticleManager.SetActiveCamera(newActiveCamera);
where newActiveCamera is the camera that has just been changed to.

Now that we have a camera, make sure to initialize the particle manager (and optionally, some particle effects) in the class's initialize method:

mParticleManager = new ParticleManager(Game, mActiveCamera); // Initialize the particle manager object with a reference to the current
// game and to the current active camera
mTestEffect = mParticleManager.Load("ParticleEffects/Explosion"); // Load in the given particle effect file by giving the
// location at which it is compiled

Once this has been done, you'll have an effect loaded into the Particle Engine object '''mTestEffect''' via the Particle Manager. However the Particle Engine isn't worth much if it's never called on to do anything, so let's set up the rest of the code that's needed for updating and drawing:

To accomplish this, all we need to do is add the particle manager to the Game's list of components. This is done as follows:

AddComponent(mParticleManager);

Aside from this we need to set the draw order of the effects, at least generally by calling

mParticleManager.DrawOrder = DrawOrder; // The second DrawOrder being whatever draw order is desired

This will draw and update any particles that have been loaded by the Particle Manager and have been set active. However, the particle engine that we just created hasn't yet been set active, so do that now.

This is done by calling the following line whenever you would want drawing of that Particle Engine to occur.

mTestEffect.SetActive(true);

The particle engine instance '''mTestEffect''' is now active. If it were already active, its lifetime would have been reset to 0. (The lifetime of a particle engine starts at zero and increases until its maximum lifetime is reached, in which case the particle engine "dies" and becomes inactive.)

This same method can be used to stop the particle engine from creating any more particles, by supplying '''false''' as its parameter instead:

mTestEffect.SetActive(false);

A series of methods allow us to modify the drawing of the ParticleEngine:

SetSplineScale(float scale) // Given a float, scales the spline around the origin by the given amount every 1/10 of a second. Note that this only
// applies for all spline emitters in the engine.

SetEnginePositions(Vector3[] Positions) // Given an array of 3D vectors, we can change the shape of all spline emitters in the particle engine.

SetEnginePosition(Vector3 Position) // Given a 3D vector, we can move the whole particle engine to the desired position.

SetEngineColor(Vector4 Color) // Given a 4D vector of float values 0-1 in the form of RGBA, we can change the coloring of the whole particle engine
// Keep in mind that this applies that much of the emitters' texture for each value, so a black picture with 1,0,0,1 as
// its value will not be red but still black.

SetEngineSize(Vector2 Size) // Given a 2D vector, we can modify the dimensions of the particle image, this is always 2D since particles in 3D are
// simply billboard sprites.

SetEngineSpeed(float Speed) // Given a float, changes the speed at which particles initially move at.

SetEngineDirection(Vector3 Direction) // Given a 3D vector, changes the direction in which particles move at. This does not apply to point emitters.

SetEngineParticlesPerSec(float NumPerSec) // Given a float, sets the number of particles created in a second. Note that this value times particle
// lifetime should not exceed the amount of particles in order to insure consistent effects.

SetEngineParticleLifetime(float Lifetime) // Given a float, sets how long a particle lives for in seconds. Note that this should never be changed
// while an effect is active, otherwise inconsistencies in the effect will most likely occur.

SetRandomDirection(bool Random) // Given a boolean, sets whether or not to make particles move in a random direction.

Also, if needed you can change the draw order of each engine individually by calling

mTestEffect.DrawOrder = DrawOrder; // The second DrawOrder is whatever draw order desired

Whenever a game object that uses a particle effect is being disposed, make sure to call

mTestEffect.SetActive(false); // Making sure to set the effect to no longer being active

on any effect with infinite life span and make sure to call

mTestEffect.ToDestroy = true; // Making sure to set the effect to no longer being alive

so that the particle manager knows that it can clean up the effect.

===Create a New Particle Effect===

To create a new particle effect, start the TACParticleEditor program. This program presents two windows, one containing a Windows form displaying information about the current particle effect, and the other displaying the particle effect.

There are four main areas of the particle editor form:

List of emitters - The list of all the emitters in the particle effect.

Emitter type - Contains all the different types of emitters that exist in the particle engine.

Row of buttons - Each having a functionality expected from their name:

Add - Adds an emitter of the chosen type from the list of emitter types to the particle effect's emitter list.

Remove - Removes the currently selected emitter in the particle effect's emitter list from the list.

Save - Saves the current particle effect to a specified .particle xml file.

Load - Loads a particle effect from a selected .particle xml file.

Emitter Info Grid - Contains all the information that can be modified for whichever emitter in the list of emitters is currently selected.

The modifiable parameters of the emitters are as follows:

For all emitters:

textureName - The file path name of the texture to render the particles with. In order to load texture names correctly, there
must exist a texture folder in the current project's compiled content folder. The default starting directory is the TACParticleEditor.
Whenever a new particle effect is loaded, the current directory is switched to that project's content directory. Anytime a new
texture is desired, it must be added manually to the appropriate project.

blendEffect - The sprite blend to use when rendering the particles. Can be either None, AlphaBlend, or Additive.
The various blend modes work as follows:

None - every particle draws exactly as how the texture appears and no alpha values are used. Therefore there will be no transparency.
For visual purposes it is highly suggested to not use this mode.

AlphaBlend - Averages all of the particles alpha values up to the max value assigned to any particle. This effect is useful in creating
effects such as dust, smoke, or gas clouds.

Additive - Sums up the colors of all the particles to the maximum value of 1.0 for all values (r,g,b, and a). This effect is useful
in creating effects such as fire, lasers, or shields.

emitLifetime - The duration of time the emitter continues to emit new particles for in seconds. This can be any duration of time. A negative
value denotes that the emitter never dies.

particlesPerSec - The amount of particles that are created every second. This can be any nonzero positive integer.

particleAmount - The total amount of particles that can appear on screen at one time. This can be any nonzero positive integer.

particleLifetime - The amount of time a particle lives for in seconds. This can be any nonzero positive number.

minStartSpeed - The slowest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxStartSpeed - The fastest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minEndSpeed - The slowest possible speed at which a particle can end moving . This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxEndSpeed - The fastest possible speed at which a particle can end moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minStartColor - The minimum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxStartColor - The maximum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minEndColor - The minimum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxEndColor - The maximum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minstartSize - The smallest size that a particle can start at in width,height form. These values can be any nonzero positive number.

maxStartSize - The largest size that a particle can start at in width,height form. These values can be any nonzero positive number.

minEndSize - The smallest size that a particle can end at in width,height form. These values can be any nonzero positive number.

maxEndSize - The largest size that a particle can end at in width,height form. These values can be any nonzero positive number.

isActive - Whether or not the emitter is currently spawning/updating/drawing particles. You can quickly activate all emitters
of the loaded/created particle effect by hitting enter while having focus on the particle effect visualization window.

For directional emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

minVel - The minimum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

maxVel - The maximum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

For point emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

For spline emitters:

positions - The positions at/between which particles will spawn in x,y,z form (aka list of 3-dimensional points). These values can be
any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

scale - The amount of scaling that occurs every time the spline emitter is scaled, that is to say, how much all positions
close in/expand from the origin (0,0,0) before any position offset is applied essentially creating an explosion or implosion
effect. This value can be any nonzero positive number. 1.5 represents 150% current size, 0.5 represents 50% current size, etc.

scaleSpeed - How quickly the scaling occurs in seconds. This can be any nonzero positive number. 1 is a scaling occurs once every second,
0.5 is a scaling occurs every half second, etc.

For spray emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

sprayRange - The area in which particles can spawn with the center at the set position in +/-x,+/-y,+/-z form. That is to say a cubic area
with dimensions width, height, and depth and its origin at the given position. These values be any nonzero positive number.

====Quick Reference Table====

'''Parameter''' '''Parameter type''' '''Unit type''' '''Range'''
''For all emitters:''
textureName String N/A Any valid path name works.
blendEffect SpriteBlendMode N/A None, AlphaBlend, or Additive.
emitLifetime floating-point Seconds Any value. Negative value denotes emitter never dies.
particlesPerSec integer Per Second Any nonzero positive number.
particleAmount integer N/A Any nonzero positive number.
particleLifetime floating-point Seconds Any nonzero positive number.
minStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
minEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
isActive boolean N/A True or False.
minVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
maxVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
positions (x,y,z) vector Arbitrary Any number.
direction (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
''For spline emitters:''
scale floating-point % of size Any nonzero positive number. < 1 denotes decrease, > 1 denotes increase.
scaleSpeed floating-point Seconds Any nonzero positive number.
''For spray emitters:''
sprayRange (width,height,depth) Arbitrary Any nonzero positive number.

*Note that all arbitrary values are based on the current camera space.

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

**Note: The code provided here is very subject to change as this section is under development.

==Write to the Experiment Log==

As the game runs, certain actions are recorded and written to a file (My Documents\Autism Collaborative\Users\DefaultUser\LogFiles\ExperimentLog.txt or as specified). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed. (That's the whole point of this game!)

First define the necessary game codes. This is done to ensure consistency across each mini-game.

* Open EventCodes.cs, or wherever you store the enum for your project.
* Codes in the range 1 - 255 are valid and can be written to the parallel port.
** The name of the code should be chosen at your convenience, and may be included to make the text log file more readable.
* Codes may be assigned outside this range, both positive and negative; these codes may be used in the same way, but will be logged only to the text log file and not to the parallel port.
** Codes in the negative range are considered debugging codes, and can be omitted from the log file by setting the writeDebugEvents property on the logger.

Now those codes are available for logging, thus:

Logger logger = new Logger("ExampleLogFile.txt");
logger.LogCode( (int)Minigame.EventCode.WeaponFiredEvent, "WeaponFired" );

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputHandler inputHandler = new InputHandler(true);
inputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)Minigame.Eventcode.PressedAEvent);

As these assigned events are local to each InputHandler object, your mini-game's event code assignments will not interact with the event code assignments of other mini-games.

Every mini-game should start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes should have an identifier such as "DEBUG_" and will not be logged unless writeDebugEvents is set to true on the logger. (writeDebugEvents is true by default only when the game is running in Debug mode.) All new DEBUG tags must be explicitly assigned a value less than 0.

===Event Code Summary===

Event Codes may be any integer value.
* Less than 0 : Debug events, will only be written in Debug Mode.
* 0 : Null, no event.
* 1 - 255 : Experimentation event, will be written to the log and the parallel port.
* Greater then 255 : Cannot be written to the parallel port, will be written to log only.

==Use the Game Script==
*Note: The LUA scripts are not universally compatible and have been known to crash on some machines. It is highly recommended that C# scripts are used.

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

===Creating Scripts in C# Code===

Alternatively, scripts can created using C# code rather than Lua. A C# script either be object oriented or imperative. They are able to both take in objects and return values. The CSharpHelper class can be called to run these scripts using its DoSimpleFile method. This will simply run all the code in the script. The value of this is that commonly edited code, such as configuration files, can be saved in a convenient separate location. The methods for CSharpHelper are well documented within the file itself. An example of a basic call to a C# script is as follows:

CSharpHelper.doSimpleFile(Environment.CurrentDirectory + @"\Configs\DebugConfig.script", this, "game");

This starts a C# file called "DebugConfig.script" which is located in the Configs directory. The second parameter is a Game object. The object passed in can be of any type. The third parameter is the identifier of the object within the script. In this case the identifier is "game". This means that inside the script, lines such as:

game.Update();

will execute the passed-in object's Update function.

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
* Compile the game
** In the second menu bar (immediately below the top menu bar) within Visual Studio, change "Debug" to "Release". (In the box to the right, leave the default "Mixed Platforms".)
** Select Build->Build Solution
* Compile the installer script
** Open Autism Collaborative\Game\Installer\Installer.iss with InnoSetup
** Select Build->Compile
*** This creates the file Autism Collaborative\Game\Game\Output\AstropolisSetupLite.exe
*** When the compilation is finished, it will ask if you want to test the installer. It is recommended to test it, but not required.
* Repeat the last step with InstallerFull.iss if desired, this will generate AstropolisSetup.exe, which contains the full offline installers for the dependencies.

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* To transfer the file, use an SSH client such as WinSCP (for a graphical interface) or PuTTY's PSCP (from the command line)
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Log in to AutismCollaborative.org (port 22)
* Upload AstropolisSetup.exe to your home directory (for example /home/zinsser)
** Do not overwrite the existing installer (/home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe) since that would delete the installer from the web site until the new installer finishes uploading
* Once the upload is complete, ssh into a shell and enter the command "mv /home/{$user}/tAC_Installer.exe /home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe" (you may have to open a terminal first, depending on your SSH client)
** If there is a permissions problem, contact Matthew to make certain that your user ID has write and search permission for the autismcollaborative.org/downloads directory.

==Use the ErrorLog==

When the game encounters an Unhandled Exception (such as when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so that we can locate the problem. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line).

We do, however, have the ability to log any custom information from a mini-game. This ability may prove invaluable in debugging based on end-user error reports. All that you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

==Testing Procedure==

This is a list of recommended tests to be performed on a regular basis to ensure that the major functionality of the program is intact.

Maritime Defender

*Play through tutorial
Things to Note:
**Text does not run off screen
**Dialog boxes wait for the space bar to be pressed before disappearing
**During the navigation-phase tutorial, input is registered correctly

*Play through main game
Things to Note:
**Collision detection is correct
**Phases are in the correct order
**Navigation phase looks correct: Dots are the correct size and dot correlation fits PEST data. Look for any slowdown or loss of frames.
**Boss fight is correct. Boss takes damage and causes the player damage.
**Player Health is displayed correctly on taking damage.

Colony Simulator

*Check GUI
Things to Note:
**Each button is clickable and causes the appropriate event to occur.
**Make sure that you cannot click through things
**Select each type of building and make sure the pop-up information is appropriate

*Check building placement
**Place each type of building
**Connect a mining building to a factory through a tube
**Connect a residential building to a factory through a road
**Once this is done, resources should increase.

**Connect a residential building to a commercial building
**Once this is done, the player's money should start increasing

**Check the building log to make sure that the build order is correct

*Check that mini-games can be accessed
**Attempt to play each mini-game through the colony simulator, executing all of their tests and checkin their appropriate logs

Stellar Prospector

*Play through the tutorial
Things to Note:
*Make sure that event codes are properly logged.
**Tasks match up with the specified text.
**Text does not run off the display.
**Input events still work when the player is prompted for them.
**Automated events such as energy drain and automatic grab still work.
**Tutorial returns to the main screen after ending.
**Make sure all graphical effects work correctly, i.e. tractor beam, explosion, and flickering.
**Player does not get locked in the game; player remains able to exit through the game menu if ESC is pressed.

*Play through the main game
Things to note:
**Make sure event codes are properly logged.
**Make sure input works correctly
**Phase changes occur correctly and at the right times.
**Energy draining and filling works correctly.
**Pause menu works correctly
**Game ends once energy bar is filled, and returns to the main menu
**Make certain that all graphical effects work correctly, i.e tractor beam, explosion, and flickering.

Code How To's

2009-01-28T20:24:12Z

Belmonte: moved details on lab and home config files from "Code How To's" to "End-user Setup"

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Go to http://www.AutismCollaborative.org/bugs/
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are used by only one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declarations or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

For a step by step tutorial with code examples, see [[How_to_Make_a_Mini-Game]]

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewMiniame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from GameScreen
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = gameTime.ElapsedGameTime;
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
** Be sure to call each entity's Draw and Update methods. Optional: Register all entities with the XNA game object.
This will have XNA automatically call their Draw and Update functions at appropriate times.
** Consider using a generalized render-queue such as GenericWorldSpace '''(not yet implemented as of October 2007)'''
** Use the Raise function to place the minigame gamescreen on the stack based game system.
* End the mini-game using Done function. This will pop the mini-game off the game stack, returning the game to the previous state.
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Show the score

==Use Images==

XNA supports most common types of images, including JPEG, GIF, DDS, etc.

===Load a Texture===

Before you can load a texture in code, though, you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right-click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory using the XNA content manager:

Texture2D myTexture = Content.Load(@"General\myTexture");

The XNA content manager defaults to the content folder of the project, so all addresses can be relative from there. Also, the name of the image should be the same as the asset name. This can be set in the properties window.

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are created using the AnimatedSprite class. Here's an example:

//Declare Animated Sprite
//Parameters: Game object, SpriteSheet as a Texture2D object, Position as Vector2, FrameSize as Vector2, Number of Frames
AnimatedSprite testAnimation = new AnimatedSprite(this, Content.Load<Texture2D>("TestSpriteSheet"), new Vector2(200, 300), new Vector2(64, 64), 16);
//Pass a reference to the SpriteBatch that the AnimatedSprite will use
testAnimation.SpriteBatch = spriteBatch;
//Turn on the Animation
testAnimation.Animate(true);
//Turn off the Animation
testAnimation.Animate(false);

*Do not forget to call the draw and update methods of the AnimatedSprite explicitly, or to add them to the XNA game.components array so as to allow XNA to call them.

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.Mouse) because tAC_Engine does a lot of caching and logging behind the scenes. Use the InputHandler instead.

===Keyboard Example===

// Bind the 'A' Key to the event 'PressedA'
mInputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)EventCodes.PressedA);
...
InputEvent inputEvent = mInputHandler.GetNextEvent();
if (inputEvent.EventCode == (int)EventCodes.PressedA)
{
// The A key was pressed
}

===Loading Keybinds from a file===

// Load Bindings from 'keybindings.dat'
mInputHandler.LoadBindings(typeof(EventCodes), RootDirectory + @"\keybindings.dat");

The Bindings file is a plain text, human-editable file that takes the following form:

"Event Name" (tab*) "Key Name" (tab*) (flags*)

====Keybinding Examples====

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text==

First you must import the desired font:

* Create an xml spritefont file for the new font called FontName.spritefont and set the desired values.

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
SpriteFont = cm.Load<SpriteFont>(@"FontName");

sb.Begin();
sb.DrawString(SpriteFont, "Some Text!", new Vector2(10.0F, 10.0F), Color.Azure);
sb.End();

==Use Sound==

===Import a new Audio File===

** Run the XACT tool from Microsoft DirectX SDK
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open AudioProject.xap file for the Minigame to which you wish to add a sound.
* Expand Wave Banks and double-click Wave Bank in the panel on the left
* Expand Sound Banks and double-click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import i.e."@/MiniGame/Content/Audio/MySound.wav" and click OK.
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Assign the audio file to be either a Music or Effect sound
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right-click the Sounds folder and select Add->Existing Item...
* Select "MySound.wav" and click OK

=== Load an Audio Project ===
This needs to be done before you play any sound or effect.
SoundManager.LoadAudioProject("AudioProject.xgs");

===Play an Effect===

SoundManager.PlayEffect("Pew"); // No file extension

===Play Music ===

SoundManager.PlayMusic("MyMusic");

==Use the Particle Engine==

Particles are handled by the TACParticleEngine, a separate library that uses the AC_GraphicsEngine that has been modified to better fit the needs of the Autism Game. Features are added to it on an as-needed basis so if a new feature needs to be added and any problems arise in its integration into the current particle engine contact Brian Murphy.

Quick layout of TACParticleEngine:

The ParticleManager contains references to all loaded ParticleEngines.
ParticleEngines contain a series of Emitters.
Emitters contain a heap of Particles, which are the objects that actually get drawn.

Make sure to include these packages so that we can create and access our particle engine objects:

using TACParticleEngine;
using TACParticleEngine.Particles;

Inside the class declaration make these global variables:

ParticleManager mParticleManager;
ParticleEngine mTestEffect;

Since the TACParticleEngine makes use of the Camera class from the AC_GraphicsEngine, we will need to create and initialize an instance of the Camera class if we are to render our particles, so let's get our camera set before we initialize the ParticleManager.

Add the following line to the list of global variables at the beginning of the class:

Camera mActiveCamera;

This will be whatever kind of camera we are currently using for drawing. (We may want other cameras, too, for whatever reason.)

Next we need to initialize the camera to any specific type of camera that derives from class Camera. At the time of this writing (January 2009) these types are limited to FollowCamera, OrthographicCamera, PerspectiveCamera2D, and PerspectiveCamera3D. For now we'll use a PerspectiveCamera3D as our active camera.

mActiveCamera = new Perspective3DCamera(new Vector3(0, 0, -5), Vector3.Zero, Vector3.Up, MathHelper.Pi/5, 1, 1, 100);

If we ever need to change the camera, be certain to update the active camera for the particle manager by calling
mParticleManager.SetActiveCamera(newActiveCamera);
where newActiveCamera is the camera that has just been changed to.

Now that we have a camera, make sure to initialize the particle manager (and optionally, some particle effects) in the class's initialize method:

mParticleManager = new ParticleManager(Game, mActiveCamera); // Initialize the particle manager object with a reference to the current
// game and to the current active camera
mTestEffect = mParticleManager.Load("ParticleEffects/Explosion"); // Load in the given particle effect file by giving the
// location at which it is compiled

Once this has been done, you'll have an effect loaded into the Particle Engine object '''mTestEffect''' via the Particle Manager. However the Particle Engine isn't worth much if it's never called on to do anything, so let's set up the rest of the code that's needed for updating and drawing:

To accomplish this, all we need to do is add the particle manager to the Game's list of components. This is done as follows:

AddComponent(mParticleManager);

Aside from this we need to set the draw order of the effects, at least generally by calling

mParticleManager.DrawOrder = DrawOrder; // The second DrawOrder being whatever draw order is desired

This will draw and update any particles that have been loaded by the Particle Manager and have been set active. However, the particle engine that we just created hasn't yet been set active, so do that now.

This is done by calling the following line whenever you would want drawing of that Particle Engine to occur.

mTestEffect.SetActive(true);

The particle engine instance '''mTestEffect''' is now active. If it were already active, its lifetime would have been reset to 0. (The lifetime of a particle engine starts at zero and increases until its maximum lifetime is reached, in which case the particle engine "dies" and becomes inactive.)

This same method can be used to stop the particle engine from creating any more particles, by supplying '''false''' as its parameter instead:

mTestEffect.SetActive(false);

A series of methods allow us to modify the drawing of the ParticleEngine:

SetSplineScale(float scale) // Given a float, scales the spline around the origin by the given amount every 1/10 of a second. Note that this only
// applies for all spline emitters in the engine.

SetEnginePositions(Vector3[] Positions) // Given an array of 3D vectors, we can change the shape of all spline emitters in the particle engine.

SetEnginePosition(Vector3 Position) // Given a 3D vector, we can move the whole particle engine to the desired position.

SetEngineColor(Vector4 Color) // Given a 4D vector of float values 0-1 in the form of RGBA, we can change the coloring of the whole particle engine
// Keep in mind that this applies that much of the emitters' texture for each value, so a black picture with 1,0,0,1 as
// its value will not be red but still black.

SetEngineSize(Vector2 Size) // Given a 2D vector, we can modify the dimensions of the particle image, this is always 2D since particles in 3D are
// simply billboard sprites.

SetEngineSpeed(float Speed) // Given a float, changes the speed at which particles initially move at.

SetEngineDirection(Vector3 Direction) // Given a 3D vector, changes the direction in which particles move at. This does not apply to point emitters.

SetEngineParticlesPerSec(float NumPerSec) // Given a float, sets the number of particles created in a second. Note that this value times particle
// lifetime should not exceed the amount of particles in order to insure consistent effects.

SetEngineParticleLifetime(float Lifetime) // Given a float, sets how long a particle lives for in seconds. Note that this should never be changed
// while an effect is active, otherwise inconsistencies in the effect will most likely occur.

SetRandomDirection(bool Random) // Given a boolean, sets whether or not to make particles move in a random direction.

Also, if needed you can change the draw order of each engine individually by calling

mTestEffect.DrawOrder = DrawOrder; // The second DrawOrder is whatever draw order desired

Whenever a game object that uses a particle effect is being disposed, make sure to call

mTestEffect.SetActive(false); // Making sure to set the effect to no longer being active

on any effect with infinite life span and make sure to call

mTestEffect.ToDestroy = true; // Making sure to set the effect to no longer being alive

so that the particle manager knows that it can clean up the effect.

===Create a New Particle Effect===

To create a new particle effect, start the TACParticleEditor program. This program presents two windows, one containing a Windows form displaying information about the current particle effect, and the other displaying the particle effect.

There are four main areas of the particle editor form:

List of emitters - The list of all the emitters in the particle effect.

Emitter type - Contains all the different types of emitters that exist in the particle engine.

Row of buttons - Each having a functionality expected from their name:

Add - Adds an emitter of the chosen type from the list of emitter types to the particle effect's emitter list.

Remove - Removes the currently selected emitter in the particle effect's emitter list from the list.

Save - Saves the current particle effect to a specified .particle xml file.

Load - Loads a particle effect from a selected .particle xml file.

Emitter Info Grid - Contains all the information that can be modified for whichever emitter in the list of emitters is currently selected.

The modifiable parameters of the emitters are as follows:

For all emitters:

textureName - The file path name of the texture to render the particles with. In order to load texture names correctly, there
must exist a texture folder in the current project's compiled content folder. The default starting directory is the TACParticleEditor.
Whenever a new particle effect is loaded, the current directory is switched to that project's content directory. Anytime a new
texture is desired, it must be added manually to the appropriate project.

blendEffect - The sprite blend to use when rendering the particles. Can be either None, AlphaBlend, or Additive.
The various blend modes work as follows:

None - every particle draws exactly as how the texture appears and no alpha values are used. Therefore there will be no transparency.
For visual purposes it is highly suggested to not use this mode.

AlphaBlend - Averages all of the particles alpha values up to the max value assigned to any particle. This effect is useful in creating
effects such as dust, smoke, or gas clouds.

Additive - Sums up the colors of all the particles to the maximum value of 1.0 for all values (r,g,b, and a). This effect is useful
in creating effects such as fire, lasers, or shields.

emitLifetime - The duration of time the emitter continues to emit new particles for in seconds. This can be any duration of time. A negative
value denotes that the emitter never dies.

particlesPerSec - The amount of particles that are created every second. This can be any nonzero positive integer.

particleAmount - The total amount of particles that can appear on screen at one time. This can be any nonzero positive integer.

particleLifetime - The amount of time a particle lives for in seconds. This can be any nonzero positive number.

minStartSpeed - The slowest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxStartSpeed - The fastest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minEndSpeed - The slowest possible speed at which a particle can end moving . This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxEndSpeed - The fastest possible speed at which a particle can end moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minStartColor - The minimum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxStartColor - The maximum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minEndColor - The minimum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxEndColor - The maximum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minstartSize - The smallest size that a particle can start at in width,height form. These values can be any nonzero positive number.

maxStartSize - The largest size that a particle can start at in width,height form. These values can be any nonzero positive number.

minEndSize - The smallest size that a particle can end at in width,height form. These values can be any nonzero positive number.

maxEndSize - The largest size that a particle can end at in width,height form. These values can be any nonzero positive number.

isActive - Whether or not the emitter is currently spawning/updating/drawing particles. You can quickly activate all emitters
of the loaded/created particle effect by hitting enter while having focus on the particle effect visualization window.

For directional emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

minVel - The minimum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

maxVel - The maximum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

For point emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

For spline emitters:

positions - The positions at/between which particles will spawn in x,y,z form (aka list of 3-dimensional points). These values can be
any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

scale - The amount of scaling that occurs every time the spline emitter is scaled, that is to say, how much all positions
close in/expand from the origin (0,0,0) before any position offset is applied essentially creating an explosion or implosion
effect. This value can be any nonzero positive number. 1.5 represents 150% current size, 0.5 represents 50% current size, etc.

scaleSpeed - How quickly the scaling occurs in seconds. This can be any nonzero positive number. 1 is a scaling occurs once every second,
0.5 is a scaling occurs every half second, etc.

For spray emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

sprayRange - The area in which particles can spawn with the center at the set position in +/-x,+/-y,+/-z form. That is to say a cubic area
with dimensions width, height, and depth and its origin at the given position. These values be any nonzero positive number.

====Quick Reference Table====

'''Parameter''' '''Parameter type''' '''Unit type''' '''Range'''
''For all emitters:''
textureName String N/A Any valid path name works.
blendEffect SpriteBlendMode N/A None, AlphaBlend, or Additive.
emitLifetime floating-point Seconds Any value. Negative value denotes emitter never dies.
particlesPerSec integer Per Second Any nonzero positive number.
particleAmount integer N/A Any nonzero positive number.
particleLifetime floating-point Seconds Any nonzero positive number.
minStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
minEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
isActive boolean N/A True or False.
minVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
maxVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
positions (x,y,z) vector Arbitrary Any number.
direction (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
''For spline emitters:''
scale floating-point % of size Any nonzero positive number. < 1 denotes decrease, > 1 denotes increase.
scaleSpeed floating-point Seconds Any nonzero positive number.
''For spray emitters:''
sprayRange (width,height,depth) Arbitrary Any nonzero positive number.

*Note that all arbitrary values are based on the current camera space.

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

**Note: The code provided here is very subject to change as this section is under development.

==Write to the Experiment Log==

As the game runs, certain actions are recorded and written to a file (My Documents\Autism Collaborative\Users\DefaultUser\LogFiles\ExperimentLog.txt or as specified). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed. (That's the whole point of this game!)

First define the necessary game codes. This is done to ensure consistency across each mini-game.

* Open EventCodes.cs, or wherever you store the enum for your project.
* Codes in the range 1 - 255 are valid and can be written to the parallel port.
** The name of the code should be chosen at your convenience, and may be included to make the text log file more readable.
* Codes may be assigned outside this range, both positive and negative; these codes may be used in the same way, but will be logged only to the text log file and not to the parallel port.
** Codes in the negative range are considered debugging codes, and can be omitted from the log file by setting the writeDebugEvents property on the logger.

Now those codes are available for logging. Like so:

Logger logger = new Logger("ExampleLogFile.txt");
logger.LogCode( (int)Minigame.EventCode.WeaponFiredEvent, "The weapon was fired." );

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputHandler inputHandler = new InputHandler(true);
inputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)Minigame.Eventcode.PressedAEvent);

As these assigned events are local to each InputHandler object, your mini-game's event code assignments will not interact with the event code assignments of other mini-games.

Every mini-game should start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes should have an identifier such as "DEBUG_" and will not be logged unless writeDebugEvents is set to true on the logger. (writeDebugEvents is true by default only when the game is running in Debug mode.) All new DEBUG tags must be explicitly assigned a value less than 0.

===Event Code Summary===

Event Codes may be any integer value.
* Less than 0 : Debug events, will only be written in Debug Mode.
* 0 : Null, no event.
* 1 - 255 : Experimentation event, will be written to the log and the parallel port.
* Greater then 255 : Cannot be written to the parallel port, will be written to log only.

==Use the Game Script==
*Note: The LUA scripts are not universally compatible and have been known to crash on some machines. It is highly recommended that C# scripts are used.

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

===Creating Scripts in C# Code===

Alternatively, scripts can created using C# code rather than Lua. A C# script either be object oriented or imperative. They are able to both take in objects and return values. The CSharpHelper class can be called to run these scripts using its DoSimpleFile method. This will simply run all the code in the script. The value of this is that commonly edited code, such as configuration files, can be saved in a convenient separate location. The methods for CSharpHelper are well documented within the file itself. An example of a basic call to a C# script is as follows:

CSharpHelper.doSimpleFile(Environment.CurrentDirectory + @"\Configs\DebugConfig.script", this, "game");

This starts a C# file called "DebugConfig.script" which is located in the Configs directory. The second parameter is a Game object. The object passed in can be of any type. The third parameter is the identifier of the object within the script. In this case the identifier is "game". This means that inside the script, lines such as:

game.Update();

will execute the passed-in object's Update function.

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
* Compile the game
** In the second menu bar (immediately below the top menu bar) within Visual Studio, change "Debug" to "Release". (In the box to the right, leave the default "Mixed Platforms".)
** Select Build->Build Solution
* Compile the installer script
** Open Autism Collaborative\Game\Installer\Installer.iss with InnoSetup
** Select Build->Compile
*** This creates the file Autism Collaborative\Game\Game\Output\AstropolisSetupLite.exe
*** When the compilation is finished, it will ask if you want to test the installer. It is recommended to test it, but not required.
* Repeat the last step with InstallerFull.iss if desired, this will generate AstropolisSetup.exe, which contains the full offline installers for the dependencies.

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* To transfer the file, use an SSH client such as WinSCP (for a graphical interface) or PuTTY's PSCP (from the command line)
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Log in to AutismCollaborative.org (port 22)
* Upload AstropolisSetup.exe to your home directory (for example /home/zinsser)
** Do not overwrite the existing installer (/home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe) since that would delete the installer from the web site until the new installer finishes uploading
* Once the upload is complete, ssh into a shell and enter the command "mv /home/{$user}/tAC_Installer.exe /home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe" (you may have to open a terminal first, depending on your SSH client)
** If there is a permissions problem, contact Matthew to make certain that your user ID has write and search permission for the autismcollaborative.org/downloads directory.

==Use the ErrorLog==

When the game encounters an Unhandled Exception (such as when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so that we can locate the problem. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line).

We do, however, have the ability to log any custom information from a mini-game. This ability may prove invaluable in debugging based on end-user error reports. All that you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

==Testing Procedure==

This is a list of recommended tests to be performed on a regular basis to ensure that the major functionality of the program is intact.

Maritime Defender

*Play through tutorial
Things to Note:
**Text does not run off screen
**Dialog boxes wait for the space bar to be pressed before disappearing
**During the navigation-phase tutorial, input is registered correctly

*Play through main game
Things to Note:
**Collision detection is correct
**Phases are in the correct order
**Navigation phase looks correct: Dots are the correct size and dot correlation fits PEST data. Look for any slowdown or loss of frames.
**Boss fight is correct. Boss takes damage and causes the player damage.
**Player Health is displayed correctly on taking damage.

Colony Simulator

*Check GUI
Things to Note:
**Each button is clickable and causes the appropriate event to occur.
**Make sure that you cannot click through things
**Select each type of building and make sure the pop-up information is appropriate

*Check building placement
**Place each type of building
**Connect a mining building to a factory through a tube
**Connect a residential building to a factory through a road
**Once this is done, resources should increase.

**Connect a residential building to a commercial building
**Once this is done, the player's money should start increasing

**Check the building log to make sure that the build order is correct

*Check that mini-games can be accessed
**Attempt to play each mini-game through the colony simulator, executing all of their tests and checkin their appropriate logs

Stellar Prospector

*Play through the tutorial
Things to Note:
*Make sure that event codes are properly logged.
**Tasks match up with the specified text.
**Text does not run off the display.
**Input events still work when the player is prompted for them.
**Automated events such as energy drain and automatic grab still work.
**Tutorial returns to the main screen after ending.
**Make sure all graphical effects work correctly, i.e. tractor beam, explosion, and flickering.
**Player does not get locked in the game; player remains able to exit through the game menu if ESC is pressed.

*Play through the main game
Things to note:
**Make sure event codes are properly logged.
**Make sure input works correctly
**Phase changes occur correctly and at the right times.
**Energy draining and filling works correctly.
**Pause menu works correctly
**Game ends once energy bar is filled, and returns to the main menu
**Make certain that all graphical effects work correctly, i.e tractor beam, explosion, and flickering.

End-user Setup

2009-01-28T20:23:10Z

Belmonte: /* Lab, Home and Debug configurations */

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

===Lab, Home and Debug configurations===

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

(When the game is being run from within the debugger, a third configuration script, DebugConfig.script, is used.)

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

End-user Setup

2009-01-28T20:22:04Z

Belmonte: moved details on lab and home config files from "Code How To's" to "End-user Setup"

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

==Lab, Home and Debug configurations==

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

(When the game is being run from within the debugger, a third configuration script, DebugConfig.script, is used.)

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

Code How To's

2009-01-28T19:50:24Z

Belmonte: /* Run the Game in the Lab */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Go to http://www.AutismCollaborative.org/bugs/
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are used by only one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declarations or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

For a step by step tutorial with code examples, see [[How_to_Make_a_Mini-Game]]

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewMiniame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from GameScreen
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = gameTime.ElapsedGameTime;
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
** Be sure to call each entity's Draw and Update methods. Optional: Register all entities with the XNA game object.
This will have XNA automatically call their Draw and Update functions at appropriate times.
** Consider using a generalized render-queue such as GenericWorldSpace '''(not yet implemented as of October 2007)'''
** Use the Raise function to place the minigame gamescreen on the stack based game system.
* End the mini-game using Done function. This will pop the mini-game off the game stack, returning the game to the previous state.
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Show the score

==Use Images==

XNA supports most common types of images, including JPEG, GIF, DDS, etc.

===Load a Texture===

Before you can load a texture in code, though, you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right-click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory using the XNA content manager:

Texture2D myTexture = Content.Load(@"General\myTexture");

The XNA content manager defaults to the content folder of the project, so all addresses can be relative from there. Also, the name of the image should be the same as the asset name. This can be set in the properties window.

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are created using the AnimatedSprite class. Here's an example:

//Declare Animated Sprite
//Parameters: Game object, SpriteSheet as a Texture2D object, Position as Vector2, FrameSize as Vector2, Number of Frames
AnimatedSprite testAnimation = new AnimatedSprite(this, Content.Load<Texture2D>("TestSpriteSheet"), new Vector2(200, 300), new Vector2(64, 64), 16);
//Pass a reference to the SpriteBatch that the AnimatedSprite will use
testAnimation.SpriteBatch = spriteBatch;
//Turn on the Animation
testAnimation.Animate(true);
//Turn off the Animation
testAnimation.Animate(false);

*Do not forget to call the draw and update methods of the AnimatedSprite explicitly, or to add them to the XNA game.components array so as to allow XNA to call them.

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.Mouse) because tAC_Engine does a lot of caching and logging behind the scenes. Use the InputHandler instead.

===Keyboard Example===

// Bind the 'A' Key to the event 'PressedA'
mInputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)EventCodes.PressedA);
...
InputEvent inputEvent = mInputHandler.GetNextEvent();
if (inputEvent.EventCode == (int)EventCodes.PressedA)
{
// The A key was pressed
}

===Loading Keybinds from a file===

// Load Bindings from 'keybindings.dat'
mInputHandler.LoadBindings(typeof(EventCodes), RootDirectory + @"\keybindings.dat");

The Bindings file is a plain text, human-editable file that takes the following form:

"Event Name" (tab*) "Key Name" (tab*) (flags*)

====Keybinding Examples====

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text==

First you must import the desired font:

* Create an xml spritefont file for the new font called FontName.spritefont and set the desired values.

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
SpriteFont = cm.Load<SpriteFont>(@"FontName");

sb.Begin();
sb.DrawString(SpriteFont, "Some Text!", new Vector2(10.0F, 10.0F), Color.Azure);
sb.End();

==Use Sound==

===Import a new Audio File===

** Run the XACT tool from Microsoft DirectX SDK
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open AudioProject.xap file for the Minigame to which you wish to add a sound.
* Expand Wave Banks and double-click Wave Bank in the panel on the left
* Expand Sound Banks and double-click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import i.e."@/MiniGame/Content/Audio/MySound.wav" and click OK.
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Assign the audio file to be either a Music or Effect sound
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right-click the Sounds folder and select Add->Existing Item...
* Select "MySound.wav" and click OK

=== Load an Audio Project ===
This needs to be done before you play any sound or effect.
SoundManager.LoadAudioProject("AudioProject.xgs");

===Play an Effect===

SoundManager.PlayEffect("Pew"); // No file extension

===Play Music ===

SoundManager.PlayMusic("MyMusic");

==Use the Particle Engine==

Particles are handled by the TACParticleEngine, a separate library that uses the AC_GraphicsEngine that has been modified to better fit the needs of the Autism Game. Features are added to it on an as-needed basis so if a new feature needs to be added and any problems arise in its integration into the current particle engine contact Brian Murphy.

Quick layout of TACParticleEngine:

The ParticleManager contains references to all loaded ParticleEngines.
ParticleEngines contain a series of Emitters.
Emitters contain a heap of Particles, which are the objects that actually get drawn.

Make sure to include these packages so that we can create and access our particle engine objects:

using TACParticleEngine;
using TACParticleEngine.Particles;

Inside the class declaration make these global variables:

ParticleManager mParticleManager;
ParticleEngine mTestEffect;

Since the TACParticleEngine makes use of the Camera class from the AC_GraphicsEngine, we will need to create and initialize an instance of the Camera class if we are to render our particles, so let's get our camera set before we initialize the ParticleManager.

Add the following line to the list of global variables at the beginning of the class:

Camera mActiveCamera;

This will be whatever kind of camera we are currently using for drawing. (We may want other cameras, too, for whatever reason.)

Next we need to initialize the camera to any specific type of camera that derives from class Camera. At the time of this writing (January 2009) these types are limited to FollowCamera, OrthographicCamera, PerspectiveCamera2D, and PerspectiveCamera3D. For now we'll use a PerspectiveCamera3D as our active camera.

mActiveCamera = new Perspective3DCamera(new Vector3(0, 0, -5), Vector3.Zero, Vector3.Up, MathHelper.Pi/5, 1, 1, 100);

If we ever need to change the camera, be certain to update the active camera for the particle manager by calling
mParticleManager.SetActiveCamera(newActiveCamera);
where newActiveCamera is the camera that has just been changed to.

Now that we have a camera, make sure to initialize the particle manager (and optionally, some particle effects) in the class's initialize method:

mParticleManager = new ParticleManager(Game, mActiveCamera); // Initialize the particle manager object with a reference to the current
// game and to the current active camera
mTestEffect = mParticleManager.Load("ParticleEffects/Explosion"); // Load in the given particle effect file by giving the
// location at which it is compiled

Once this has been done, you'll have an effect loaded into the Particle Engine object '''mTestEffect''' via the Particle Manager. However the Particle Engine isn't worth much if it's never called on to do anything, so let's set up the rest of the code that's needed for updating and drawing:

To accomplish this, all we need to do is add the particle manager to the Game's list of components. This is done as follows:

AddComponent(mParticleManager);

Aside from this we need to set the draw order of the effects, at least generally by calling

mParticleManager.DrawOrder = DrawOrder; // The second DrawOrder being whatever draw order is desired

This will draw and update any particles that have been loaded by the Particle Manager and have been set active. However, the particle engine that we just created hasn't yet been set active, so do that now.

This is done by calling the following line whenever you would want drawing of that Particle Engine to occur.

mTestEffect.SetActive(true);

The particle engine instance '''mTestEffect''' is now active. If it were already active, its lifetime would have been reset to 0. (The lifetime of a particle engine starts at zero and increases until its maximum lifetime is reached, in which case the particle engine "dies" and becomes inactive.)

This same method can be used to stop the particle engine from creating any more particles, by supplying '''false''' as its parameter instead:

mTestEffect.SetActive(false);

A series of methods allow us to modify the drawing of the ParticleEngine:

SetSplineScale(float scale) // Given a float, scales the spline around the origin by the given amount every 1/10 of a second. Note that this only
// applies for all spline emitters in the engine.

SetEnginePositions(Vector3[] Positions) // Given an array of 3D vectors, we can change the shape of all spline emitters in the particle engine.

SetEnginePosition(Vector3 Position) // Given a 3D vector, we can move the whole particle engine to the desired position.

SetEngineColor(Vector4 Color) // Given a 4D vector of float values 0-1 in the form of RGBA, we can change the coloring of the whole particle engine
// Keep in mind that this applies that much of the emitters' texture for each value, so a black picture with 1,0,0,1 as
// its value will not be red but still black.

SetEngineSize(Vector2 Size) // Given a 2D vector, we can modify the dimensions of the particle image, this is always 2D since particles in 3D are
// simply billboard sprites.

SetEngineSpeed(float Speed) // Given a float, changes the speed at which particles initially move at.

SetEngineDirection(Vector3 Direction) // Given a 3D vector, changes the direction in which particles move at. This does not apply to point emitters.

SetEngineParticlesPerSec(float NumPerSec) // Given a float, sets the number of particles created in a second. Note that this value times particle
// lifetime should not exceed the amount of particles in order to insure consistent effects.

SetEngineParticleLifetime(float Lifetime) // Given a float, sets how long a particle lives for in seconds. Note that this should never be changed
// while an effect is active, otherwise inconsistencies in the effect will most likely occur.

SetRandomDirection(bool Random) // Given a boolean, sets whether or not to make particles move in a random direction.

Also, if needed you can change the draw order of each engine individually by calling

mTestEffect.DrawOrder = DrawOrder; // The second DrawOrder is whatever draw order desired

Whenever a game object that uses a particle effect is being disposed, make sure to call

mTestEffect.SetActive(false); // Making sure to set the effect to no longer being active

on any effect with infinite life span and make sure to call

mTestEffect.ToDestroy = true; // Making sure to set the effect to no longer being alive

so that the particle manager knows that it can clean up the effect.

===Create a New Particle Effect===

To create a new particle effect, start the TACParticleEditor program. This program presents two windows, one containing a Windows form displaying information about the current particle effect, and the other displaying the particle effect.

There are four main areas of the particle editor form:

List of emitters - The list of all the emitters in the particle effect.

Emitter type - Contains all the different types of emitters that exist in the particle engine.

Row of buttons - Each having a functionality expected from their name:

Add - Adds an emitter of the chosen type from the list of emitter types to the particle effect's emitter list.

Remove - Removes the currently selected emitter in the particle effect's emitter list from the list.

Save - Saves the current particle effect to a specified .particle xml file.

Load - Loads a particle effect from a selected .particle xml file.

Emitter Info Grid - Contains all the information that can be modified for whichever emitter in the list of emitters is currently selected.

The modifiable parameters of the emitters are as follows:

For all emitters:

textureName - The file path name of the texture to render the particles with. In order to load texture names correctly, there
must exist a texture folder in the current project's compiled content folder. The default starting directory is the TACParticleEditor.
Whenever a new particle effect is loaded, the current directory is switched to that project's content directory. Anytime a new
texture is desired, it must be added manually to the appropriate project.

blendEffect - The sprite blend to use when rendering the particles. Can be either None, AlphaBlend, or Additive.
The various blend modes work as follows:

None - every particle draws exactly as how the texture appears and no alpha values are used. Therefore there will be no transparency.
For visual purposes it is highly suggested to not use this mode.

AlphaBlend - Averages all of the particles alpha values up to the max value assigned to any particle. This effect is useful in creating
effects such as dust, smoke, or gas clouds.

Additive - Sums up the colors of all the particles to the maximum value of 1.0 for all values (r,g,b, and a). This effect is useful
in creating effects such as fire, lasers, or shields.

emitLifetime - The duration of time the emitter continues to emit new particles for in seconds. This can be any duration of time. A negative
value denotes that the emitter never dies.

particlesPerSec - The amount of particles that are created every second. This can be any nonzero positive integer.

particleAmount - The total amount of particles that can appear on screen at one time. This can be any nonzero positive integer.

particleLifetime - The amount of time a particle lives for in seconds. This can be any nonzero positive number.

minStartSpeed - The slowest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxStartSpeed - The fastest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minEndSpeed - The slowest possible speed at which a particle can end moving . This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxEndSpeed - The fastest possible speed at which a particle can end moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minStartColor - The minimum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxStartColor - The maximum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minEndColor - The minimum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxEndColor - The maximum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minstartSize - The smallest size that a particle can start at in width,height form. These values can be any nonzero positive number.

maxStartSize - The largest size that a particle can start at in width,height form. These values can be any nonzero positive number.

minEndSize - The smallest size that a particle can end at in width,height form. These values can be any nonzero positive number.

maxEndSize - The largest size that a particle can end at in width,height form. These values can be any nonzero positive number.

isActive - Whether or not the emitter is currently spawning/updating/drawing particles. You can quickly activate all emitters
of the loaded/created particle effect by hitting enter while having focus on the particle effect visualization window.

For directional emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

minVel - The minimum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

maxVel - The maximum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

For point emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

For spline emitters:

positions - The positions at/between which particles will spawn in x,y,z form (aka list of 3-dimensional points). These values can be
any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

scale - The amount of scaling that occurs every time the spline emitter is scaled, that is to say, how much all positions
close in/expand from the origin (0,0,0) before any position offset is applied essentially creating an explosion or implosion
effect. This value can be any nonzero positive number. 1.5 represents 150% current size, 0.5 represents 50% current size, etc.

scaleSpeed - How quickly the scaling occurs in seconds. This can be any nonzero positive number. 1 is a scaling occurs once every second,
0.5 is a scaling occurs every half second, etc.

For spray emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

sprayRange - The area in which particles can spawn with the center at the set position in +/-x,+/-y,+/-z form. That is to say a cubic area
with dimensions width, height, and depth and its origin at the given position. These values be any nonzero positive number.

====Quick Reference Table====

'''Parameter''' '''Parameter type''' '''Unit type''' '''Range'''
''For all emitters:''
textureName String N/A Any valid path name works.
blendEffect SpriteBlendMode N/A None, AlphaBlend, or Additive.
emitLifetime floating-point Seconds Any value. Negative value denotes emitter never dies.
particlesPerSec integer Per Second Any nonzero positive number.
particleAmount integer N/A Any nonzero positive number.
particleLifetime floating-point Seconds Any nonzero positive number.
minStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
minEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
isActive boolean N/A True or False.
minVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
maxVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
positions (x,y,z) vector Arbitrary Any number.
direction (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
''For spline emitters:''
scale floating-point % of size Any nonzero positive number. < 1 denotes decrease, > 1 denotes increase.
scaleSpeed floating-point Seconds Any nonzero positive number.
''For spray emitters:''
sprayRange (width,height,depth) Arbitrary Any nonzero positive number.

*Note that all arbitrary values are based on the current camera space.

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

**Note: The code provided here is very subject to change as this section is under development.

==Write to the Experiment Log==

As the game runs, certain actions are recorded and written to a file (My Documents\Autism Collaborative\Users\DefaultUser\LogFiles\ExperimentLog.txt or as specified). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed. (That's the whole point of this game!)

First define the necessary game codes. This is done to ensure consistency across each mini-game.

* Open EventCodes.cs, or wherever you store the enum for your project.
* Codes in the range 1 - 255 are valid and can be written to the parallel port.
** The name of the code should be chosen at your convenience, and may be included to make the text log file more readable.
* Codes may be assigned outside this range, both positive and negative; these codes may be used in the same way, but will be logged only to the text log file and not to the parallel port.
** Codes in the negative range are considered debugging codes, and can be omitted from the log file by setting the writeDebugEvents property on the logger.

Now those codes are available for logging. Like so:

Logger logger = new Logger("ExampleLogFile.txt");
logger.LogCode( (int)Minigame.EventCode.WeaponFiredEvent, "The weapon was fired." );

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputHandler inputHandler = new InputHandler(true);
inputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)Minigame.Eventcode.PressedAEvent);

As these assigned events are local to each InputHandler object, your mini-game's event code assignments will not interact with the event code assignments of other mini-games.

Every mini-game should start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes should have an identifier such as "DEBUG_" and will not be logged unless writeDebugEvents is set to true on the logger. (writeDebugEvents is true by default only when the game is running in Debug mode.) All new DEBUG tags must be explicitly assigned a value less than 0.

===Event Code Summary===

Event Codes may be any integer value.
* Less than 0 : Debug events, will only be written in Debug Mode.
* 0 : Null, no event.
* 1 - 255 : Experimentation event, will be written to the log and the parallel port.
* Greater then 255 : Cannot be written to the parallel port, will be written to log only.

==Use the Game Script==
*Note: The LUA scripts are not universally compatible and have been known to crash on some machines. It is highly recommended that C# scripts are used.

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

===Creating Scripts in C# Code===

Alternatively, scripts can created using C# code rather than Lua. A C# script either be object oriented or imperative. They are able to both take in objects and return values. The CSharpHelper class can be called to run these scripts using its DoSimpleFile method. This will simply run all the code in the script. The value of this is that commonly edited code, such as configuration files, can be saved in a convenient separate location. The methods for CSharpHelper are well documented within the file itself. An example of a basic call to a C# script is as follows:

CSharpHelper.doSimpleFile(Environment.CurrentDirectory + @"\Configs\DebugConfig.script", this, "game");

This starts a C# file called "DebugConfig.script" which is located in the Configs directory. The second parameter is a Game object. The object passed in can be of any type. The third parameter is the identifier of the object within the script. In this case the identifier is "game". This means that inside the script, lines such as:

game.Update();

will execute the passed-in object's Update function.

==Run the Game in the Lab==

The only difference between the lab and the home versions of the game is the config file that is used. The program will automatically use the LabConfig.script file if it exists; otherwise it will use Config.script. To run the program in the lab, simply make certain that the LabConfig.script file is present.

These config files will be found in "[Game Install Directory]\Configs\" (Default: "C:\Program Files\Autism Collaborative\Configs\")

See also: [[Differences in Home vs Lab Configuration]]

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
* Compile the game
** In the second menu bar (immediately below the top menu bar) within Visual Studio, change "Debug" to "Release". (In the box to the right, leave the default "Mixed Platforms".)
** Select Build->Build Solution
* Compile the installer script
** Open Autism Collaborative\Game\Installer\Installer.iss with InnoSetup
** Select Build->Compile
*** This creates the file Autism Collaborative\Game\Game\Output\AstropolisSetupLite.exe
*** When the compilation is finished, it will ask if you want to test the installer. It is recommended to test it, but not required.
* Repeat the last step with InstallerFull.iss if desired, this will generate AstropolisSetup.exe, which contains the full offline installers for the dependencies.

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* To transfer the file, use an SSH client such as WinSCP (for a graphical interface) or PuTTY's PSCP (from the command line)
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Log in to AutismCollaborative.org (port 22)
* Upload AstropolisSetup.exe to your home directory (for example /home/zinsser)
** Do not overwrite the existing installer (/home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe) since that would delete the installer from the web site until the new installer finishes uploading
* Once the upload is complete, ssh into a shell and enter the command "mv /home/{$user}/tAC_Installer.exe /home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe" (you may have to open a terminal first, depending on your SSH client)
** If there is a permissions problem, contact Matthew to make certain that your user ID has write and search permission for the autismcollaborative.org/downloads directory.

==Use the ErrorLog==

When the game encounters an Unhandled Exception (such as when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so that we can locate the problem. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line).

We do, however, have the ability to log any custom information from a mini-game. This ability may prove invaluable in debugging based on end-user error reports. All that you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

==Testing Procedure==

This is a list of recommended tests to be performed on a regular basis to ensure that the major functionality of the program is intact.

Maritime Defender

*Play through tutorial
Things to Note:
**Text does not run off screen
**Dialog boxes wait for the space bar to be pressed before disappearing
**During the navigation-phase tutorial, input is registered correctly

*Play through main game
Things to Note:
**Collision detection is correct
**Phases are in the correct order
**Navigation phase looks correct: Dots are the correct size and dot correlation fits PEST data. Look for any slowdown or loss of frames.
**Boss fight is correct. Boss takes damage and causes the player damage.
**Player Health is displayed correctly on taking damage.

Colony Simulator

*Check GUI
Things to Note:
**Each button is clickable and causes the appropriate event to occur.
**Make sure that you cannot click through things
**Select each type of building and make sure the pop-up information is appropriate

*Check building placement
**Place each type of building
**Connect a mining building to a factory through a tube
**Connect a residential building to a factory through a road
**Once this is done, resources should increase.

**Connect a residential building to a commercial building
**Once this is done, the player's money should start increasing

**Check the building log to make sure that the build order is correct

*Check that mini-games can be accessed
**Attempt to play each mini-game through the colony simulator, executing all of their tests and checkin their appropriate logs

Stellar Prospector

*Play through the tutorial
Things to Note:
*Make sure that event codes are properly logged.
**Tasks match up with the specified text.
**Text does not run off the display.
**Input events still work when the player is prompted for them.
**Automated events such as energy drain and automatic grab still work.
**Tutorial returns to the main screen after ending.
**Make sure all graphical effects work correctly, i.e. tractor beam, explosion, and flickering.
**Player does not get locked in the game; player remains able to exit through the game menu if ESC is pressed.

*Play through the main game
Things to note:
**Make sure event codes are properly logged.
**Make sure input works correctly
**Phase changes occur correctly and at the right times.
**Energy draining and filling works correctly.
**Pause menu works correctly
**Game ends once energy bar is filled, and returns to the main menu
**Make certain that all graphical effects work correctly, i.e tractor beam, explosion, and flickering.

End-user Setup

2009-01-28T19:45:36Z

Belmonte: /* Location */

Each Minigame has a variety of settings that can be configured individually.

==Config==

The Config.script file holds general settings. It can be opened with any general text editor, such as Notepad or Vim. Each line ending with a semicolon (;) indicates a command for the game to follow. Lines beginning with two forward slashes (//) are considered comments, and will not be processed. A block comment is a section beginning with (/*) and ending at (*/).

===Location===

[Installation Directory]\Configs\Config.script (Default: "C:\Program Files\Autism Collaborative\Configs\")

The Global Config.script can be found in the Configs folder under the Autism Collaborative folder -- typically C:\Program Files\Autism Collaborative\Configs\Config.script. This holds global settings that will be applied automatically when the game starts. Individual minigames may have individual configurations specific to those minigames. This individual config file is also called Config.script, and can be found in the Configs folder under the minigame's folder -- typically C:\Program Files\Autism Collaborative\Minigames\[MiniGameName]\Configs\Config.script.

===Global===

Util.Settings.SetResolution([horizontal],[vertical]);
* Set the screen resolution this game will be played at, for example, Util.Settings.SetResolution(1024,768);

Util.Settings.FullScreen = [true/false];
* Set whether the game window will be fullscreen, for example, Util.Settings.FullScreen = true;

Util.Settings.ParallelPortEnabled = [true/false];
* Set whether codes should be written out the Parallel Port, for example, Util.Settings.ParallelEnabled = true; If not specified, this will default to False.

Util.Settings.ParallelPort = ParallelPort.Port1;
* Set which Parallel Port codes should be written to, if enabled. Valid values are Port1, Port2, and Port3. Defaults to Port1.

Util.Settings.SetScreenDimensions([Width], [Height], [Distance]);
* Width is the width of the display, in centimeters. Height is as height of the display, in centimeters. Distance is the distance between the display and the viewer's eyes, in centimeters. For the dot coherence phase of Maritime Defender, the dots are based on the size of the visual display as it appears to the player. For example, Util.Settings.SetScreenDimensions(8.5, 6.25, 24.0);

===Maritime Defender===

MaritimeDefender.Settings.DotsPerSquareRadian = [Number];
MaritimeDefender.Settings.DotsPerSquareDegree = [Number];
* For the dot coherence phase, the dots are based on the size of the visual display as it appears to the player. This sets the density of the dots as they appear on the screen. Either measure, radians or degrees, may be used. For example, MaritimeDefender.Settings.DotsPerSquareRadian = 10000.0;

MaritimeDefender.Settings.DotsPerRadian = [Number];
MaritimeDefender.Settings.DotsPerDegree = [Number];
* Specify the dot density as the number of dots within a circular patch of screen space with a diameter of one radian or degree of visual angle as it appears to the user.

MaritimeDefender.Settings.NumberDots = [Number];
* Override the above settings, specifying exactly the number of dots that should be drawn on the screen. This setting is optional.

MaritimeDefender.Settings.DotDiameter = System.Math.PI / 1028;
* Affects the average size of the coherence dots in terms of radians.

MaritimeDefender.Settings.DotSpeed = System.Math.PI / 16;
* Affects how fast the coherence dots appear to move across the screen in terms of radians per second.

MaritimeDefender.Settings.DotLifeSpan = 4 / 60.0;
* How long each dot exists on the screen. 4 / 60.0 reflects 4 frames on a 60 hertz display.

MaritimeDefender.Settings.DotRefreshDelay = 1;
* Additional Delay in seconds between each dot test, for the EEG readings. This is in addition to a random jitter of, by default, between 0 and 150ms; this jitter is controlled by the DotRefreshDelayJitter.

MaritimeDefender.Settings.DotRefreshDelayJitter = 0.15;
* A random amount of jitter between 0 and [value] seconds will added to the DotRefreshDelay so that the time between two successive coherence trials is not constant. The default is 0.15 of a second, or 150 milliseconds.

MaritimeDefender.Settings.DotResponseWait = 0.5;
* The duration of time in seconds immediately after a trial with no response in which late responses can be excepted.

MaritimeDefender.Settings.DotTrialLength = 2;
* The average duration of a dot test trial in seconds.

MaritimeDefender.Settings.SetPhaseQueue(2, "IdentityTest, 1, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 3, DotTest, 140, Shooter, 1, Boss, 0");
* The game phases for Maritime Defender. A list of pairs, a name and a value. Currently, the Game must start with an IdentityTest phase. The Shooter value is how many wormholes must be opened and ships identified in order to move on to the next Phase. The DotTest value is how many dot trials will take place during that phase, where a trial may be a motion of dots, or an absence of motion.

MaritimeDefender.Settings.HaveNonCoherentTrials = false;
* Whether NonCoherentTrials should be included. If false, there will be coherent motion to the left or right for every trial.

===Stellar Prospector===

StellarProspector.Settings.StimulusWaitMax = 1500f;
* The maximum amount of time in milliseconds before a stimulus must appear after the offset of the previous stimulus.

StellarProspector.Settings.StimulusWaitMin = 500f;
* The minimum amount of time in milliseconds before a stimulus can appear after the offset of the previous stimulus.

StellarProspector.Settings.DistractorWaitMax = 10000f;
* The maximum amount of time in milliseconds before a distractor must appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorWaitMin = 2000f;
* The minimum amount of time in milliseconds before a distractor can appear after the offset of the previous distractor.

StellarProspector.Settings.DistractorLifeMax = 10000f;
* The maximum amount of time in milliseconds that a distractor can live for after it has been created.

StellarProspector.Settings.DistractorLifeMin = 2000f;
* The minimum amount of time in milliseconds that a distactor must live for after it has been created.

StellarProspector.Settings.StimulusLifeMax = 6000f;
* The maximum time in milliseconds that a stimulus can be displayed.

StellarProspector.Settings.StimuliPerCueMin = 1;
* The minimum number of stimuli that must appear before the cued sector can change.

StellarProspector.Settings.StimuliPerCueMax = 1;
* The maximum number of stimuli that can appear before the cued sector must change.

StellarProspector.Settings.MaxProgress = 100;
* The amount of progress needed to completely finish the game. This is in arbitrary units.

StellarProspector.Settings.PeripheralProgress = 5;
* The maximum amount of progress the player can receive from correctly responding to peripheral stimuli. In the same arbitrary units as max progress.

StellarProspector.Settings.ProgressLostPerMiss = 1;
* The amount of progress lost anytime an incorrect response is given

StellarProspector.Settings.CentralStimulusProgressDrain = 1;
* Amount of progress drained every 2 seconds during a central stimulus

StellarProspector.Settings.AutoCalculateFlickering = true;
* Whether the frames on/off and intensities of the flickering effect are automatically calculated by the frequency or are just taken from the manually set values.

StellarProspector.Settings.CenterHertz = 6.67;
* The rate at which the center sector flickers per second

StellarProspector.Settings.CenterOnFrames = 4;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered on

StellarProspector.Settings.CenterOffFrames = 5;
* How many frames (out of 60 frames per second) in a row does the center sector remain flickered off

StellarProspector.Settings.CenterIntensity = 1.25;
* The percentage of intensity of the center sector when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector1Hertz = 8.57;
* The rate at which sector one flickers per second

StellarProspector.Settings.Sector1OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered on

StellarProspector.Settings.Sector1OffFrames = 4;
* How many frames (out of 60 frames per second) in a row does sector one remain flickered off

StellarProspector.Settings.Sector1Intensity = 1.33;
* The percentage of intensity of sector one when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector2Hertz = 10;
* The rate at which sector two flickers per second

StellarProspector.Settings.Sector2OnFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered on

StellarProspector.Settings.Sector2OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector two remain flickered off

StellarProspector.Settings.Sector2Intensity = 1.0;
* The percentage of intensity of sector two when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector3Hertz = 12;
* The rate at which sector three flickers per second

StellarProspector.Settings.Sector3OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered on

StellarProspector.Settings.Sector3OffFrames = 3;
* How many frames (out of 60 frames per second) in a row does sector three remain flickered off

StellarProspector.Settings.Sector3Intensity = 1.5;
* The percentage of intensity of sector three when it is flickered on. 1.0 denotes 100% intensity.

StellarProspector.Settings.Sector4Hertz = 15;
* The rate at which sector four flickers per second

StellarProspector.Settings.Sector4OnFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered on

StellarProspector.Settings.Sector4OffFrames = 2;
* How many frames (out of 60 frames per second) in a row does sector four remain flickered off

StellarProspector.Settings.Sector4Intensity = 1.0;
* The percentage of intensity of sector four when it is flickered on. 1.0 denotes 100% intensity.

==Keyboard Configuration==

Keyboard bindings are stored in a separate file, also specific to each minigame. For example, the keyboard bindings for the ColonySim could be found at [Installation Directory]\testkeybindings.txt (Default: "C:\Program Files\Autism Collaborative\testkeybindings.txt"). It is stored as a list of in-game events, each followed by the action that triggers it.

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Logging==

The current default path for the log file is in the Application Data folder. The exact location will vary depending on the operating system installed.

Vista: C:\Users\[WindowsLoginName]\Documents\Roaming\Autism Collaborative\

XP: C:\Documents and Settings\[WindowsLoginName]\My Documents\Autism Collaborative\

The documentation for the building placement log for the Colony Simulation can be found here -> [[Building_Placement_Log_Specification]].

2009-01-09T05:02:32Z

Belmonte:

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Go to http://www.AutismCollaborative.org/bugs/
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are used by only one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declarations or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from GameScreen
class NewGame : Gamescreen {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(GameTime gameTime){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = gameTime.ElapsedGameTime;
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Be sure to call each entity's Draw and Update methods. Optional: Register all entities with the XNA game object.
This will have XNA automatically call their Draw and Update functions at appropriate times.
** Consider using a generalized render-queue such as GenericWorldSpace '''(not yet implemented as of October 2007)'''
** Use the Raise function to place the minigame gamescreen on the stack based game system.
* End the mini-game using Done function. This will pop the mini-game off the game stack, returning the game to the previous state.
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Show the score

==Use Images==

XNA supports most common types of images, including JPEG, GIF, DDS, etc.

===Load a Texture===

Before you can load a texture in code, though, you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right-click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory using the XNA content manager:

Texture2D myTexture = Content.Load(@"General\myTexture");

The XNA content manager defaults to the content folder of the project, so all addresses can be relative from there. Also, the name of the image should be the same as the asset name. This can be set in the properties window.

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are created using the AnimatedSprite class. Here's an example:

//Declare Animated Sprite
//Parameters: Game object, SpriteSheet as a Texture2D object, Position as Vector2, FrameSize as Vector2, Number of Frames
AnimatedSprite testAnimation = new AnimatedSprite(this, Content.Load<Texture2D>("TestSpriteSheet"), new Vector2(200, 300), new Vector2(64, 64), 16);
//Pass a reference to the SpriteBatch that the AnimatedSprite will use
testAnimation.SpriteBatch = spriteBatch;
//Turn on the Animation
testAnimation.Animate(true);
//Turn off the Animation
testAnimation.Animate(false);

*Do not forget to call the draw and update methods of the AnimatedSprite explicitly, or to add them to the XNA game.components array so as to allow XNA to call them.

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.Mouse) because tAC_Engine does a lot of caching and logging behind the scenes. Use the InputHandler instead.

===Keyboard Example===

// Bind the 'A' Key to the event 'PressedA'
mInputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)EventCodes.PressedA);
...
InputEvent inputEvent = mInputHandler.GetNextEvent();
if (inputEvent.EventCode == (int)EventCodes.PressedA)
{
// The A key was pressed
}

===Loading Keybinds from a file===

// Load Bindings from 'keybindings.dat'
mInputHandler.LoadBindings(typeof(EventCodes), RootDirectory + @"\keybindings.dat");

The Bindings file is a plain text, human-editable file that takes the following form:

"Event Name" (tab*) "Key Name" (tab*) (flags*)

====Keybinding Examples====

Quit Escape
* Trigger the Quit event when Escape is pressed.

PlaceBuilding Left mouse
* Trigger the PlaceBuilding event when the Left ''Mouse Button'' is pressed.

ZoomInStop OemPlus released
* Trigger the ZoomInStop event when the Plus Key is ''released''.

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text==

First you must import the desired font:

* Create an xml spritefont file for the new font called FontName.spritefont and set the desired values.

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
SpriteFont = cm.Load<SpriteFont>(@"FontName");

sb.Begin();
sb.DrawString(SpriteFont, "Some Text!", new Vector2(10.0F, 10.0F), Color.Azure);
sb.End();

==Use Sound==

===Import a new Audio File===

** Run the XACT tool from Microsoft DirectX SDK
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open AudioProject.xap file for the Minigame you wish to add a sound to.
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import i.e."@/MiniGame/Content/Audio/MySound.wav" and click OK.
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Assign the audio file to be either a Music or Effect sound
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select "MySound.wav" and click OK

=== Load an Audio Project ===
This needs to be done before you play any sound or effect.
SoundManager.LoadAudioProject("AudioProject.xgs");

===Play an Effect===

SoundManager.PlayEffect("Pew"); // No file extension

===Play Music ===

SoundManager.PlayMusic("MyMusic");

==Use the Particle Engine==

Particles are handled by the TACParticleEngine, a separate library that uses the AC_GraphicsEngine that has been modified to better fit the needs of the Autism Game. Features are added to it on an as-needed basis so if a new feature needs to be added and any problems arise in its integration into the current particle engine contact Brian Murphy.

Quick layout of TACParticleEngine:

The ParticleManager contains references to all loaded ParticleEngines.
ParticleEngines contain a series of Emitters.
Emitters contain a heap of Particles, which are the objects that actually get drawn.

Make sure to include these packages so that we can create and access our particle engine objects:

using TACParticleEngine;
using TACParticleEngine.Particles;

Inside the class declaration make these global variables:

ParticleManager mParticleManager;
ParticleEngine mTestEffect;

Since the TACParticleEngine makes use of the Camera class from the AC_GraphicsEngine, we will need to create and initialize an instance of the Camera class if we are to render our particles, so let's get our camera set before we initialize the ParticleManager.

Add the following line to the list of global variables at the beginning of the class:

Camera mActiveCamera;

This will be whatever kind of camera we are currently using for drawing in case we may want other cameras for whatever reason.

Next we need to initialize the camera to any specific type of camera that derives from Camera. As of now this is limited to FollowCamera, OrthographicCamera, PerspectiveCamera2D, and PerspectiveCamera3D. For now well us a PerspectiveCamera3D as our active camera.

mActiveCamera = new Perspective3DCamera(new Vector3(0, 0, -5), Vector3.Zero, Vector3.Up, MathHelper.Pi/5, 1, 1, 100);

If we ever need to change the camera make sure to update the active camera for the particle manager by calling
mParticleManager.SetActiveCamera(newActiveCamera);
where newActiveCamera is the camera that has just been changed to.

Now that we have a camera, make sure to initialize the particle manager (and optionally, some particle effects) in the class' initialize method:

mParticleManager = new ParticleManager(Game, mActiveCamera); // Initialize the particle manager object with a reference to the current
// game and to the current active camera
mTestEffect = mParticleManager.Load("ParticleEffects/Explosion"); // Load in the given particle effect file by giving the
// location at which it is compiled to

After this has been done, you'll now have an effect loaded into a Particle Engine object via the Particle Manager. However the Particle Engine doesn't mean anything if it doesn't do anything so let's set up the rest of the code we need for updating and drawing:

To do this, all we need to do is add the particle manager to the Game's list of components. This is done as follows:

AddComponent(mParticleManager);

Aside from this we need to set the draw order of the effects, at least generally by calling

mParticleManager.DrawOrder = DrawOrder; // The second DrawOrder being whatever draw order desired

This will now draw and update any particles that have been loaded by the Particle Manager and have been set active, however the current particle engine we created hasn't been set active yet so do that now.

This is done by calling the following line whenever you would want drawing of that Particle Engine to occur.

mTestEffect.SetActive(true);

This particle engine is now active, and if it had been previously active, its lifetime would have been reset to 0 (the lifetime for a particle engine starts at zero and increases until its max lifetime is reached in which case the particle engine "dies" and becomes inactive). Using this call, we can also turn off the particle engine from creating anymore particles by giving it false as its parameter instead.

Besides this method, there are a series of methods that allow us to modify the drawing of the ParticleEngine itself. These are as followed:

SetSplineScale(float scale) // Given a float, scales the spline around the origin by the given amount every 1/10 of a second. Note that this only
// applies for all spline emitters in the engine.

SetEnginePositions(Vector3[] Positions) // Given an array of 3D vectors, we can change the shape of all spline emitters in the particle engine.

SetEnginePosition(Vector3 Position) // Given a 3D vector, we can move the whole particle engine to the desired position.

SetEngineColor(Vector4 Color) // Given a 4D vector of float values 0-1 in the form of RGBA, we can change the coloring of the whole particle engine
// Keep in mind that this applies that much of the emitters' texture for each value, so a black picture with 1,0,0,1 as
// its value will not be red but still black.

SetEngineSize(Vector2 Size) // Given a 2D vector, we can modify the dimensions of the particle image, this is always 2D since particles in 3D are
// simply billboard sprites.

SetEngineSpeed(float Speed) // Given a float, changes the speed at which particles initially move at.

SetEngineDirection(Vector3 Direction) // Given a 3D vector, changes the direction in which particles move at. This does not apply to point emitters.

SetEngineParticlesPerSec(float NumPerSec) // Given a float, sets the number of particles created in a second. Note that this value times particle
// lifetime should not exceed the amount of particles in order to insure consistent effects.

SetEngineParticleLifetime(float Lifetime) // Given a float, sets how long a particle lives for in seconds. Note that this should never be changed
// while an effect is active, otherwise inconsistencies in the effect will most likely occur.

SetRandomDirection(bool Random) // Given a boolean, sets whether or not to make particles move in a random direction.

Also, if needed you can change the draw order of each engine individually by calling

mTestEffect.DrawOrder = DrawOrder; // The second DrawOrder is whatever draw order desired

Whenever a game object that uses a particle effect is being disposed, make sure to call

mTestEffect.SetActive(false); // Making sure to set the effect to no longer being active

on any effect with infinite life span and make sure to call

mTestEffect.ToDestroy = true; // Making sure to set the effect to no longer being alive

so that the particle manager knows that it can clean up the effect.

===Create a New Particle Effect===

To create a new particle effect, start up the TACParticleEditor program. In this program there are two windows, one containing a windows form displaying information about the current particle effect, and the other displaying the particle effect.

There are four main areas of the particle editor form:

List of emitters - The list of all the emitters in the particle effect.

Emitter type - Contains all the different types of emitters that exist in the particle engine.

Row of buttons - Each having a functionality expected from their name:

Add - Adds an emitter of the chosen type from the list of emitter types to the particle effect's emitter list.

Remove - Removes the currently selected emitter in the particle effect's emitter list from the list.

Save - Saves the current particle effect to a specified .particle xml file.

Load - Loads a particle effect from a selected .particle xml file.

Emitter Info Grid - Contains all the information that can be modified for whatever emitter in the list of emitters is currently selected.

The modifiable parameters of the emitters are as follows:

For all emitters:

textureName - The file path name of the texture to render the particles with. In order to load texture names in correctly, there
must exist a texture folder in the current project's compiled content folder. The default starting directory is the TACParticleEditor.
Whenever a new particle effect is loaded in, the current directory is then switched to that project's content directory. Anytime a new
texture is desired, it must manually be added into the appropriate project.

blendEffect - The sprite blend to use when rendering the particles. Can be either None, AlphaBlend, or Additive.
The various blend modes work as follows:

None - every particle draws exactly as how the texture appears and no alpha values are used. Therefore there will be no transparency.
For visual purposes it is highly suggested to not use this mode.

AlphaBlend - Averages all of the particles alpha values up to the max value assigned to any particle. This effect is useful in creating
effects such as dust, smoke, or gas clouds.

Additive - Sums up the colors of all the particles to the maximum value of 1.0 for all values (r,g,b, and a). This effect is useful
in creating effects such as fire, lasers, or shields.

emitLifetime - The duration of time the emitter continues to emit new particles for in seconds. This can be any duration of time. A negative
value denotes that the emitter never dies.

particlesPerSec - The amount of particles that are created every second. This can be any nonzero positive integer.

particleAmount - The total amount of particles that can appear on screen at one time. This can be any nonzero positive integer.

particleLifetime - The amount of time a particle lives for in seconds. This can be any nonzero positive number.

minStartSpeed - The slowest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxStartSpeed - The fastest possible speed at which a particle can start moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minEndSpeed - The slowest possible speed at which a particle can end moving . This can be any number, since a negative value just means
that the particle will move in the opposite direction.

maxEndSpeed - The fastest possible speed at which a particle can end moving. This can be any number, since a negative value just means
that the particle will move in the opposite direction.

minStartColor - The minimum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxStartColor - The maximum color values that a particle can start at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minEndColor - The minimum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

maxEndColor - The maximum color values that a particle can end at in r,g,b,a form (i.e. red, green, blue, alpha). These values can be any
number between 0.0 and 1.0.

minstartSize - The smallest size that a particle can start at in width,height form. These values can be any nonzero positive number.

maxStartSize - The largest size that a particle can start at in width,height form. These values can be any nonzero positive number.

minEndSize - The smallest size that a particle can end at in width,height form. These values can be any nonzero positive number.

maxEndSize - The largest size that a particle can end at in width,height form. These values can be any nonzero positive number.

isActive - Whether or not the emitter is currently spawning/updating/drawing particles. You can quickly activate all emitters
of the loaded/created particle effect by hitting enter while having focus on the particle effect visualization window.

For directional emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

minVel - The minimum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

maxVel - The maximum velocity direction in which particles can move at in x,y,z form (aka a 3-dimensional vector going outward from the
position point). These numbers can range from -1.0 to 1.0.

For point emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

For spline emitters:

positions - The positions at/between which particles will spawn in x,y,z form (aka list of 3-dimensional points). These values can be
any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

scale - The amount of scaling that occurs every time the spline emitter is scaled, that is to say, how much all positions
close in/expand from the origin (0,0,0) before any position offset is applied essentially creating an explosion or implosion
effect. This value can be any nonzero positive number. 1.5 represents 150% current size, 0.5 represents 50% current size, etc.

scaleSpeed - How quickly the scaling occurs in seconds. This can be any nonzero positive number. 1 is a scaling occurs once every second,
0.5 is a scaling occurs every half second, etc.

For spray emitters:

positions - The position in which particles will spawn in x,y,z form (aka a 3-dimensional point). These values can be any number.

direction - The velocity direction in which particles will move in x,y,z form (aka a 3-dimensional point). (aka a 3-dimensional vector
going outward from the position point). These numbers can range from -1.0 to 1.0.

sprayRange - The area in which particles can spawn with the center at the set position in +/-x,+/-y,+/-z form. That is to say a cubic area
with dimensions width, height, and depth and its origin at the given position. These values be any nonzero positive number.

====Quick Reference Table====

'''Parameter''' '''Parameter type''' '''Unit type''' '''Range'''
''For all emitters:''
textureName String N/A Any valid path name works.
blendEffect SpriteBlendMode N/A None, AlphaBlend, or Additive.
emitLifetime floating-point Seconds Any value. Negative value denotes emitter never dies.
particlesPerSec integer Per Second Any nonzero positive number.
particleAmount integer N/A Any nonzero positive number.
particleLifetime floating-point Seconds Any nonzero positive number.
minStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxStartSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
minEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
maxEndSpeed floating-point Arbitrary Any number. Negative value denotes movement in opposite direction.
isActive boolean N/A True or False.
minVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
maxVel (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
positions (x,y,z) vector Arbitrary Any number.
direction (x,y,z) vector Arbitrary Any number within -1.0 to 1.0.
''For spline emitters:''
scale floating-point % of size Any nonzero positive number. < 1 denotes decrease, > 1 denotes increase.
scaleSpeed floating-point Seconds Any nonzero positive number.
''For spray emitters:''
sprayRange (width,height,depth) Arbitrary Any nonzero positive number.

*Note that all arbitrary values are based on the current camera space.

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

**Note: The code provided here is very subject to change as this section is under development.

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (LogFiles\ExperimentalLog.txt or as specified). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes. This is done to ensure consistency across each Mini game.

* Open EventCodes.cs, or wherever you store the enum for your project.
* Codes in the range 1 - 255 are valid and can be written out to the parallel port.
** The name of the code should be chosen at your convenience, and may be included to make the text log file more readable.
* Codes may be assigned outside of this range, both positive and negative; These codes may be used in the same way, but will only be logged to the text log file.
** Codes in the negative range are considered to be debug codes, and can be omitted from the resulted log file by setting the writeDebugEvents property on the logger.

Now those codes are available for logging. Like so:

Logger logger = new Logger("ExampleLogFile.txt");
logger.LogCode( (int)Minigame.EventCode.WeaponFiredEvent, "The weapon was fired." );

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputHandler inputHandler = new InputHandler(true);
inputHandler.writeToParallel = true;
inputHandler.Bind(Keys.A, InputHandler.Trigger.Pressed, (int)Minigame.Eventcode.PressedAEvent);

These assigned events are local to each InputHandler object, so assigning your events will not interact with the events of other mini games.

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes should have an identifier such as "DEBUG_" and will not be logged unless writeDebugEvents is set to true on the logger. (writeDebugEvents is only true by default when the game is running in Debug mode.) All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==
*Note: The LUA scripts are not universally compatible and have been known to crash on some machines. It is highly recommended that C# scripts are used.

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

===Creating Scripts in C# Code===

Alternatively, scripts can created using C# code rather than Lua. A C# script either be object oriented or imperative. They are able to both take in objects and return values. The CSharpHelper class can be called to run these scripts using its DoSimpleFile method. This will simply run all the code in the script. The value of this is that commonly edited code, such as configuration files, can be saved in a convenient separate location. The methods for CSharpHelper are well documented within the file itself. An example of a basic call to a C# script is as follows:

CSharpHelper.doSimpleFile(Environment.CurrentDirectory + @"\Configs\Debug.confcss", this, "game");

This starts a C# file called "Debug.confcss" which is located in the Configs directory. The second parameter is a Game object. The object passed in can be of any type. The third parameter is the identifier of the object within the script. In this case the identifier is "game". This means that inside the script, lines such as:

game.Update();

will execute the passed-in object's Update function.

==Run the Game in the Lab==

The only difference between the lab and the home versions of the game is the config file that is used. This can be manually edited before the build is made of the program. The program will automatically use the LabConfig.config file if it exists, otherwise it will use Default.config. To run the program in the lab, simply make sure the LabConfig.config file is present.

==Publish the Installer==
*Note: This section is in development and subject to change.

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
** Run Autism Collaborative\Utilities\Installer Installer\isetup-5.2.2.exe
* Compile the game
** In the second menu bar (immediately below the top menu bar) within Visual Studio, change "Debug" to "ReleasePub" or "ReleaseLab". (In the box to the right, leave the default "Mixed Platforms".)
*** ReleasePub is for our releases to the general public. This will usually be the correct configuration.
*** ReleaseLab is for builds to be used in the lab. This will create the config file to run the game in "lab mode." The resulting exe file will actually be the same as ReleasePub, but constd.tac will be replaced with conlab.tac.
*** Debug mode is used while developing, so do not build the game in debug mode when creating the installer.
*** For the exact effects of the different build configurations on the game flow, unit stats, etc. see the config files in Autism Collaborative\Game\Game\Configs
** Goto Build->Build Solution
* Compile the installer script
** Open Autism Collaborative\Game\Game\Installer.iss with InnoSetup
** Goto Build->Compile
** Goto Run->Run
*** This creates the file Autism Collaborative\Game\Game\Output\tAC_Installer.exe

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* Use a secure FTP client to login, such as WinSCP
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Login to autismcollaborative.org (port 22)
* Upload tAC_Installer.exe to your home directory (for example /home/zinsser)
** Do not overwrite the existing installer (/home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe) since that would delete the installer from the website until the new installer finishes uploading (usually over an hour!)
* Once the upload is complete, enter the command "mv /home/zinsser/tAC_Installer.exe /home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe" (you may have to open a terminal first, depending on your SFTP client)
** In the above command, substitute your username for "zinsser", but keep "belmonte" as the destination user directory
** If there is a permissions problem, contact Matthew to make sure your user has permission to the autismcollaborative.org directory!

==Use the ErrorLog==

*Note: This section is in development and subject to change.

When the game encounters an Unhandled Exception (like when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so we can locate the problem they ran into. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line!).

We do, however, have the ability to log any custom information from a MiniGame. This may prove invaluable in debugging based on end-user error reports. All you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

==Testing Procedure==

This is a list of recommended tests to be performed on a regular basis to ensure that the major functionality of the program is intact.

Meteor Madness

*Play through tutorial
Things to Note:
**Text does not run off screen
**Dialog boxes wait for spacebar to be pressed before disappearing
**On space drift tutorial, input is registered correctly

*Play through main game
Things to Note:
**Collision detection is correct
**Phases are in the correct order
**Dot coherence phase looks correct . Dots are the correct size and dot correlation fits with PEST data. Look for any slowdown and loss of frames.
**Boss fight is correct. Boss takes damage and causes the player damage.
**Player Health is displayed correctly upon taking damage.

Colony Sim

*Check GUI
Things to Note:
**Each button is clickable and causes the appropriate event to occur.
**Make sure you can not click through things
**Select each type of building and make sure the pop up info is appropriate

*Check building placement
**Place each type of building
**Connect a mining building to a factory through a tube
**Connect a residential building to a factory through a road
**Once this is done, resources should increase.

**Connect a residential building to a commercial building
**Once this is done, players money should start increasing

**Check the building log to make sure the build order is correct

*Check that minigames can be accessed
**Attempt to play each minigame through the colony sim, executing all of their tests and checkin their appropriate logs

Stellar Prospector

*Play through tutorial
Things to Note:
*Make sure event codes are properly logged.
**Tasks match up with the specified text.
**Text does not run off screen.
**Input events still work when prompted for them.
**Automated events such as energy drain and automatic grab still work.
**Tutorial returns to main screen after ending.
**Make sure all graphical effects work correctly, i.e tractor beam, explosion, and flickering.
**Player does not get locked in game by still being able to exit out through game menu if ESC was pressed.

*Play through main game
Things to note:
**Make sure event codes are properly logged.
**Make sure input works correctly
**Phase changes occur correctly and at the right times.
**Energy draining and filling works correctly.
**Pause menu works correctly
**Game ends once energy bar is filled and when it has, returns to main menu
**Make sure all graphical effects work correctly, i.e tractor beam, explosion, and flickering.