Design Document

# Design Document ## For The G-ScalE Mini-Game Battery Project Version 0.1.25 Prepared by Team Ludus [Alice Ip](@ipa1) - 400078727 [Jack Buckley](@bucklj4) - 400144747 [Meijing Li](@lim147) - 400110713 [Shuo He](@hes11) - 400023520 [Yunfei Yang](@yangy113) - 400049426 Instructor: [Dr. Jacques Carette](@carette) Course: [COMPSCI 4ZP6: Capstone Project](https://www.cas.mcmaster.ca/~carette/CS4ZP6/2020_21/index.html) Date: 2020-11-09 Table of Contents ================= [[_TOC_]] # Table of Contents * Revised History * 1 [Likely Changes] (done) * 2 [Unlikely Changes] (done) * 3 [Concepts] (done) * Module Notation (Jack) * 4 [Module Secrets] (~ 20 pages) * MIS Diagram * Module Lists (ALL)  * Backend Database (Jack) * Data transformation  * Visualization (done)  * Controller (done):   * 5 [Module Interface] (~ 20 pages) (Jack) * 5.1 Game Interface ADTs * Image Hit (Yunfei) * Catch the Thief (done) * Ball (Shuo) * Circles (Alice) * Squares (Jack) * 5.2 Abiliy Measurement ADTs (each person does the ability(s) that his/her game measures) * Object Recognition * Inhibition (already exists a template) * Selective Visual (already exists a template) * Time to contact * Visuospatial Sketchpad * Flicking * 5.3 Overall System Management: * BatterySessionManagement Module (Sure) * Player ADT * MiniGame Interface Module (Yunfei) * Ability ADT * 5.4 Helper modules / Backend glue (Jack) * CountDownTimer (done) * Counter (done) * Position2D * Image * Target * Point * RamGenerator(done) * Cell(done) * SquareCanvas * 5.5 Controller Module (Meijing) * 6 [SRS Changes] (~ 5 pages) (Yunfei) (Alice) * 7 [Dependency Diagram] (3 ~ 5 pages) (Complete at the end) * 8 [Significant Design] (5 pages) (Discuss on Friday) * 9 [Traceability Table] (~ 2 pages) (all complete together) * 10 [Milestone] ## Revision History | Name | Date | Reason For Changes | Version | | ---- | ------- | ------------------- | --------- | | ALL | Nov 13 | First Script | 1.0 | | ALL | Nov 15 | Revised Script | 1.1 | | | | | | ## 1. Likely Changes  The following is a list of software aspects for which our product anticipates possible change in the future: * Mini-game compatibility with alternative hardware interface devices - One of the requirements of our product is to have the option to take in game input using various external devices, as necessary for the measurement of target cognitive abilities. [Team Ludus was assigned the task of designing mini-games with the input of just the keyboard and mouse](TODO: Link to AVL-3 in SRS and update AVL-3 (and other mentions of just using the keyboard) to keyboard and mouse). However, as can be seen by [the list of identified motor abilities link to the appendix with the motor abilities chart](TODO: Link to Appendix 12.1), there still remain a large number of identified key motor abilities that require other interface devices to gather data. For example, the shaking motor ability requires the user to move or sway the input hardware using the wrist. For obvious reasons, the keyboard is unable to detect such a movement and, as a result, cannot be used to measure this motor ability. Instead, a hand-held game controller such as a Wii remote that has movement detection hardware/software that is capable of detecting wrist-shaking movements should be used for this specific motor ability measurement. As well, test results for two different hardware interface devices for the same motor ability measurement can be analyzed for differences in performance that may be related to the interface device itself. Other examples of hardware interface devices include Android and other smartphone devices, general game controllers, and VR headsets. * User interface - Possible changes include visual/interface elements and instructional elements that are related to user experience of the product. Such elements include Unity assets, bitmaps, and typography. Requirements such as those pertaining to [ease of use](TODO: link to EU-1), [learning](TODO: link to LR-1), and [usability](TODO: link to UP-2) are verified through formal usability testing and beta testing with external users. As a result, feedback related to necessary user interface changes will not known until a later time and so these elements may undergo significant changes during project implementation. Examples of changes include aspects such as the format, breadth, and quantity of instructions or guidance that the subject requires in order to understand and navigate through each mini game. * Cognitive/motor ability analysis functions - The field of cognitive psychology is a popular and intricate subject of research. As use of technology is further integrated within our society, human-computer interaction in relation to cognitive psychology may reveal new measurement methods and relations between cognitive abilities that can be applied to the analysis of cognitive/motor abilities in our product. It is necessary to update our product in order to ensure that the product provides relevant and accurate information. Changes to the application resulting from novel measurement techniques or advancements in the domain of cognitive psychology allow us to comply with our reliability requirement which mandates that [we measure cognitive and motor abilities in an objective manner that conforms with existing and accepted best practices for measurement](TODO: Link to REL-1). * Data measurement methods - Currently, our data collection and measurement methods are closely related to the input given by the subject using the hardware interface device. For example, the amount of time between the appearance of the stimulus and the user key press/click may be a factor of the player's aptitude in a particular cognitive ability. However, currently accessible hardware interface devices are incapable of capturing other movement specific details. For example, for the selective visual cognitive ability, and related mini-games, the addition of an eye movement tracking software could provide a very large amount of information about visual processing, by a key press or even the movement of the mouse. For the purposes of [Sasha's research and analysis of cognitive abilities related to video games](TODO: link to the part where we talk about her research), such extensive user data that is only possible with software can be used in fields such as human computer interaction, video game/software development, and cognitive psychology. * Addition of new mini-games - For the scope of our project, [we have decided to focus on a small subset of the total identified cognitive and motor abilities](https://gitlab.cas.mcmaster.ca/bucklj4/capstone-mini-game-battery-project/-/wikis/Software-Requirements-Specification#final-product-constraints). However, in the future, Sasha may desire to analyze and measure the aptitude of users in the other abilities. Due to the modular design of our software, it will be possible to design, develop, and add new mini-games to measure and analyze the remaining cognitive and motor abilities, as necessary. ## 2. Unlikely Changes  The following is a list of software aspects for which our product will be unlikely to change in the future: * Development environment - [The interface of our project will be developed on Unity. All the code for each mini-game will be written in C#](TODO: <link to the Mandated Constraints>). The design and implementation of the functionality in the mini-games will be achieved using the current Unity libraries. There might be some new technologies that could be used to develop games. However, as our project supervisor, Sasha, imposed [the constraint of using Unity from our very first meeting](https://gitlab.cas.mcmaster.ca/bucklj4/capstone-mini-game-battery-project/-/wikis/meetings_with_supervisor/2_october#detailed-notes), we believe it to be unlikely that these core technologies will change in the further design and implementation process. * The selected cognitive and motor ability subset - Currently we have six selected cognitive and motor abilities: [object recognition, inhibition, selective/focused visual attention, time to contact, flicking, and visuospatial sketchpad](TODO: link to 1.5 and update abilities in SRS). The focus of the measurement and analysis will be on these six abilities in this project. The design and implementation of the mini-game will also aim to measure these abilities. Although it is only a subset of the [46 identified cognitive and motor abilities](TODO: Link to Appendix 12.1), and there will be more abilities that need to be measured while we are testing the above abilities, the main focus of our project will not likely to expand broader and [we have long established that our work will only deal with a subset of the abilities](https://gitlab.cas.mcmaster.ca/bucklj4/capstone-mini-game-battery-project/-/wikis/meetings_with_supervisor/2_october#meeting-summary). * Measurement interface - The interface or the application of our measurement will be conducted as a series of mini-games. The abilities of subjects will be tested and measured during the time that they are playing the mini-games. The challenges in the mini-games will be used to record the behaviour of players. The game data from the players will be sent to the back-end. Such data will be analyzed to generate a score that should reflect the ability level for the tested ability. Of course the way to measure these abilities may vary in the future, however, in the further development of the project, we will be using mini-games as a tool of measurement.(TODO: Need a link for this sectio) * Constraints (TODO: Link to 1.3) - We have an additional number of contraints that we have previously enumerated in our SRS. These contraints are also long standing and unlikely to change. ## 3. Concepts  ### Introduction (SRS 1.1a) Our capstone group is developing the G-ScalE Mini-Game Battery Project, a project composed of five single-player mini games designed in Unity, to measure six out of 46 identified human cognitive and psychomotor skills. Each game will take players approximately 30 - 50 seconds to play, and will be used to establish player competencies in a specific cognitive or psychomotor group. The games will be accessible by the players through a web application that runs on a web server, and collects input through the keyboard and mouse. ### Background (SRS 1.1a) The G-ScalE Mini-Game Battery Project is a capstone project for COMPSCI 4ZP6 at McMaster University. This project is developed by Team Ludus, a team that consists of five fourth-year Computer Science students from McMaster University under the supervision of Sasha Soraine. Completion of this capstone project is a mandatory requirement for graduation and also a process for students to apply their knowledge in a year long project. This project is part of the McMaster Gaming Scalability Environment (G-ScalE) research lab, specifically correlates to the research that Sasha Soraine has been conducting. The results of the project will contribute to the work of testing that Sasha has been doing in her PhD research to develop her hypotheses regarding the outcome of mechanical experiences given identified atomic challenges. ### Measurement Mechanism Description The G-ScalE Mini-Game Battery Project is made up of six different short games, and each game can measure one to three different motor and cognitive abilities. The keyboard and mouse are needed for players to complete all ability tests and accurately reflect their actual competency in the tested abilities. In order to successfully measure the abilities, the player will be asked to fill out a questionnaire before the games begin to specify if they have a keyboard and a mouse. The players can still play most of the games if they do not have access to the mouse, and the results will still be generated for the covered abilities, leaving the result of uncovered abilities empty. However, the players cannot play all the games if they do not have access to the keyboard, as the majority of the abilities will be measured through the keyboard input. The G-ScalE Mini-Game Battery Project, during the questionnaire, will record the answers and during the gameplay, will measure the results based on variables like time, accuracy, and distance (including the physical distance between two key strokes and virtual distance between two in-game objects. Multiple types of variables are calculated through the games. When the user completes a game, the program sends a series of previously calculated variables to create numeric data. Once the game set is completed, measurement algorithms will calculate the user's results. These results are captured in an automated and detailed report, compiling the user’s cognitive strengths and weaknesses. ### Characteristics Of Project * The games are designed for users of all ages, however a minimum age of 7 is required so that [the players are able to read and understand the game instructions and correctly interact with the games](TODO: link to EU-2). * The games are free resources and could be accessible online, whereas [the collected data and measurement results will belong to each participate and will be stored in secure fashion](TODO: link to SEC-4). * Testing results will be influenced by players' physical, mental, or sociocultural conditions. Therefore the results only reveal ability levels among a [general population(generic able-bodied neurotypical persons)](TODO: link to 2.4), not in a specific condition group. ### Key Features Of Implementation * The game interfaces will be designed using Unity. * The scripts will be developed using C#. * The backend framework will be driven by Elasticsearch for data storage, analysis and visualization. - The data will be stored in a JSON-like fashion. - Advanced queries over relational databases are supported in processing the database. - Build-in libraries are available for analysis and visualization. - A simple and secured API for C# will be used to transform the gameplay data between game interface and backend in real time. * The game set will be exported as a web application in the WebGL format, available on a public website hosted by a free web server 000Webhost. > TODO: Do we really need to (and should we) include the below section? ### Abilities Battery (SRS 1.5.1) The G-ScalE Mini-Game Battery Project by our team measures the following six abilities: Cognitive Ability: - **Object recognition**: is the cognitive ability for an individual to identify the objects in their view based on visual input. It requires a person to perceive an object's physical properties, such as shape, colour and texture, and apply semantic attributes to the object, which include the understanding of its use, previous experience with the object, and how it relates to others. (link later) - **Inhibition**: is the cognitive ability to tune out stimuli that are irrelevant to the task. - **Selective/Focused visual**: is the cognitive ability that has to do with the focus of vision on an area or object in the field of vision. - **Time to contact**: is the cognitive ability that predicts the moment there is going to be contact between a person and some object, including ones in which the individual is moving towards some object (e.g., a wall) and those in which an object (e.g., a ball) is approaching the individual (Eysenck, 1257). (link) - **Visuospatial Sketchpad**: is a component of working memory model which stores and processes information in a visual or spatial form. Fine Motor Ability: - **Flicking**: as a wrist action, is the rapid movement of the controller from one point to another. The motion used to complete this action is also lateral movements of the wrist. The following is table to match each ability with the device required: | Ability | Device | |--------------|-----------| | Object recognition | Keyboard | | Inhibition | Keyboard | | Selective/Focused visual | Keyboard | | Time to contact | Keyboard | | Visuospatial Sketchpad | Mouse/Keyboard (Use the mouse by default. If the player does not have a mouse, could still use the keyboard. ) | | Flicking | Mouse | ### Game-Ability Matching Table: (SRS ) The following is a table to match each game to tested ability(s): | Game Name | Evaluated ability(s) | |--------------|---------------| | Image Hit | Object Recognition, Inhibition | | Catch The Thief | Selective/Focused Visual, Inhibition | | Ball | Time To Contact | | Circles | Flicking, Object recognition, Selective visual | | Squares | Visuospatial Sketchpad | > TODO: Is this is what is meant by design and run time concepts? ### Design Time ![](https://i.imgur.com/cbnLja8.png) Note: - The inner cycles indicates that the parts were sent for client review and refined based on the feedback. - Touchpoint document is a short document(within 10 pages) that provides high-level key points of design decisions. It is sent to Sasha to gather feedback before expanding on it and making it formal in our official design document. The touchpoint document could be found [here](https://docs.google.com/document/d/1z5ArBJVRzXONMq-AhfL-B4Y7H9EhDYsFcpcD75kgmJI/edit). ### Run Time ![](https://i.imgur.com/bGYhALl.png) Note: - The Questionnaire Page requires the users to fill their accessible devices(keyboard, mouse), age, name. - The duration of reading instruction for each game is no more than 10 seconds; the duration of playing each round of the game is 20 to 40 seconds. - The duration of generating the results of ability battery in the Result Page is no more than 5 seconds. ### Module Interface Specification Notation The notation used in describing the modules' functionality is quite similar to that used in the course COMPSCI 2ME3. We have made some modifications where we saw fit to best describe the syntax and semantics of the interfaces underlying the modules. We describe the notation now: #### Types - $`\mathbb{N}`$: the set of natural numbers - $`\{0, 1, 2, ... \}`$ - $`\mathbb{N}^+`$: the set of *positive* natural numbers - $`\{1, 2, ... \}`$ - $`\mathbb{R}`$: the set of real numbers - $`\mathbb{R}^+`$: the set of *positive* real numbers - $`\{x \in \mathbb{R} | x > 0 \}`$ - $`\mathbb{B}`$: the set of booleans - $`\{\mathtt{True}, \mathtt{False}\}`$ - `[T]`: A sequence of type `T` - i.e. all elements of type `T`, order matters, duplicate elements allowed #### Methods - TODO #### Definition - `:=`: the assignment operator - `x := y` means `x` is assigned the value of `y` - $x := \begin{cases} E_0 &\text{if $B$ } \\ E_1 &\text{otherwise} \end{cases}$: Expression definition by cases - $`x := E_0`$ if the boolean expression $`B`$ is true; $`x := E_1`$ if the boolean expression $`B`$ is false. - $`E_0`$ and $`E_1`$ are of the same type. - Imperative definition: TODO ## 4. Module Secrets     ### MIS Diagram: [To Do] ### List Of Modules: #### Modules for Abilities - **SelectiveVisualMeasure**: this module is for measuring the Selective/Focused Visual ability. It contains the methods that evaluate the score and ability level of the user for the ability. - This module should be hidden from the clients because the clients do not need this information to play the game. - Methods .... are accessible in the modules ... because - ... - **Circles Module Flicking Motor Ability Measurement** - The flicking motor ability module for the Circles game counts the number of successful clicks that the subject completed in relation to the range of the circle, as well as the time of click, using the information given by the Circles module. The number of successful clicks of a range of circle sizes will be counted and the number of successful clicks within a range of times will be used in determining the average time and size that the subject is able to perform the flicking ability. These values will then be quantified into a flicking ability level. If the subject does not click in time, the `MousePositions` list has record of the cursor placement before the end of the level, and can be used as an indicator for how off the subject was. - **Circles Selective Visual and Inhibition Ability Measurement** - The Circles game has minor elements that indicate visual and inhibition ability levels. Such elements include the amount of time it takes for the subject to react to the appearance of the new circle. The `MoveTime` measurement given by the Circles Module will be used for this. - **Circles Pressing Motor Ability Measurement** - The Circles game requires the subject to left-click to indicate confirmation and preciseness on their flicking movement. However this confirmation can be affected by whether the player presses at the right time of their flicking movement. As a result, their ability to press the key is a factor that can be measured. If the subject's cursor is within the range of the circle, and the subject does not press, then it indicates a delay or lower level of pressing. - **Time To Contact Ability Measurement** - The Ball require the players to make reaction of a disappear moving target and predict the estimated time that it will arrive a ceartain contact point, this is measuring the coincidence anticipation which is under the time to contact ability. Also, this game is asking players to indicate and compare two approaching target and tell which one is first. This is measuring the ability of relative judgment under time to contact ability. Such mesurement could reflect the time to contact ability of players. #### Modules for Games - **CatchTheThief**: this module is for setting up the front-end of the `Catch The Thief` game. It contains the variables and methods that set up the game state and capture raw gameplay data. - In the module, the screen displaying objects(cells) should be available to the clients as they need to see the objects on the screen to interact with game. All other parts are hidden from the clients because they do not need the information to play the game. - Methods `getGamePlayData` are accessable in the modules`SelectiveVisualMeasure` and `InhibitionMeasure` because the players apply Selective Visual and Inhibition abilities in the game, thus the gameplay data contains the raw data used for the ability measurement. We need to create a method to provide such kind of data in this game module. - **Module Name: Circles Module** - **Circles**: this module is for setting up the front-end of the the `Circles` mini-game that captures data for the flicking, clicking, object recognition, and selective visual cognitive ability It contains the variables and methods that set up the game state and capture raw gameplay data - In the module, the screen displaying objects(circles) should be available to the clients as they need to see the objects on the screen to interact with game. All other parts are hidden from the clients because they do not need the information to play the game. - Methods `getGamePlayData` are accessable in the modules`SelectiveVisualMeasure`,`InhibitionMeasure`,`FlickingMeasure`, because the players apply selective visual, inhibition, and flicking abilities in the game, thus the gameplay data contains the raw data used for the ability measurement. - The module has a function for calculating the change in the level(`level`), the amount of time between clicks (`levelClickTime`), and levelCircleSize (`levelCircleSize`), which is a main point of interest in testing player ability given changes in click range and time alloted for a click for the flicking ability. The size of the circle and the amount of time to click starts at a standard value. As the player successfully clicks on the circles, the size of the circles decrease and the amount of time allowed decreases as well, to further test the player's abilities. If the player consistently misses the circles at a level, the size and time values stay the same, so that a consistent level can be calculated. The size and time values are recorded for analysis. - The module uses an timer instance to measure and store the time when the destination point was generated(`DestinationTime`) and when the player started to move after the destination point appeared (`MoveTime`) using information given by the controller. The module also keeps track of the sequence of clicks done in the game, and positions of the mouse at various points in time including when the round ends, for further flicking measurement, and passes all relevant captured information to the appropriate ability measure module. #### Modules for Overall System: #### Helper Modules: - **Cell**: this object module is for cerating a cell object that will be used as a helper module for `CatchTheThef` game module. It contains the position, size, image and status information of each cell. - `Catch The Thief` game requires multiple cells showing on the screen. That's where this object module comes from. - This objects created by the module are visiable to the users, as the users need to see them on the creen in the gameplay. - The methods for creating new `Cell` object as well as `setupImage`, `appearOnScreen`, `disappearFromScreen` can be accessed in the module `CatchTheThef` for setting up and changing the cell information. - **RamGenerator**: this module is for generating random numbers and boolean values. - Multiple game modules ask for generating random values in setting up the states, that's where the module comes from. - The module should be hidden from the clients. - The methods `generateARamBool`, `generateARamNum`, `generateARamNumExcludePoint` could be accessed in the module(s) `CatchTheThief`, ... - `CatchTheThief` requires to generate ramdon bool values to specify if the thief and police images will appear in the current bout; as well as to generate random cell numbers on which the police and thief images appear. #### Controller Module: - **Controller**: is a module for mapping specific input events to the trigger variables `press` and `click`. - In different games, the specified input events could be different. For example, one game requires the players to press the SPACEBAR to interact with the game, whereas another game does not not necessarily require the same button for players to interact. Therefore we need an abstraction layer which we can freely refer different inputs to the same trigger variables in different games. That's where the module comes from. - This whole module should be hidden from the clients. - The methods in this module for mapping input events to the trigger variables (`pressTrigger `, `clickTrigger`) as well as changing states of trigger variables (`pressKey`, `releaseKey`, `clickMoseButton`, `releaseMouseButton`) could be accessed by all game modules. However all remaining parts should remain secrete from the entire module system. ### Backend Database ### Data transformation ### Data Visualization and Storage **[ElasticsearchThe Elk Stack](https://www.elastic.co/what-is/elk-stack)** The visualization and storage of the data collected by our mini-games will be done using ELK stack, otherwise known as Elasticsearch. The ELK stack describes a combination of three popular open-source projects: Elasticsearch, Logstash and Kibana. **[Amazon Elasticsearch Service](https://aws.amazon.com/elasticsearch-service/features/?nc=sn&loc=2)** The Amazon Elasticsearch Service can be used for free with the Amazon Web Services (AWS) Free Tier, to manage setup, deployment, configuration, patching and monitoring of the Elasticsearch clusters. The AWS console allows creation of scalable secure and available Elasticsearch clusters with open source Elasticsearch APIs, Kibana compatability, and integration of Logstash. **[Elasticsearch](https://www.elastic.co/elasticsearch/)** Elasticsearch is a highly scalable and open source search and analytics engine that allows storing, searching, and analyzation of data in a JSON-like fashion. This engine supports advanced queries over relational databases, allowing for greater control over our data analysis. Our data be analyzed to show cognitive ability results using aggregations such as averages, percentiles, and deviations. **Logstash** Logstash is an open source, server-side data processing pipeline used for collecting data from a variety of sources, and loading data into Elasticsearch **[Kibana](https://www.elastic.co/kibana)** Using queries from Elasticsearch, Kibana can be used to visualize data. Kibana offers the ability to represent the data in forms such as histograms, line graphs, pie charts, sunburts, and more, depending on our needs, for each cognitive ability, or for the competency profile as a whole. As of right now, a bar graph will be used to represent the player's competency in the measured cognitive ability. ### Controller **Unity Action** The input trigger in each mini-game will be abstracted as controller layer. For different controller, such layer will be bounded with different concrete method of inputs. The players will not be limited with their hardware device to finish the test. For this abstraction of controller, it could be done with Unity Actions framework which is already been built. The control system of user input detection and game status change will be implemented using `Unity Action` framework as well as the `Controller` Module. ## 5. Module Interface  ### 5.1 Game Interface ADTs #### `ImageHit` ADT Module (Yunfei) ---- **Uses** MiniGame Timer RamGenerator Counter Image **Syntax** **Exported Constants**: None **Exported Types**: None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | ImageHit_init | | | | | GetGameplayData | | Seq | | **Semantics** **State Variables** SpecifiedType: `string`  ImageList: `Seq` of `Image`  SerialNumber: $\mathbb{N}$  AdditionalList: `Seq` of `Image`  GameplayData: `Seq` **State Invariant** (Image of ImageList & AdditionalList).ImageTime <= 3.00 **Assumptions and Design Decisions** - `SpecifiedType`is the specified category of images. - `ImageList` is list of images displayed on the screen. - `SerialNumber` is the serial numer of the current image. - `AdditionalList` is a list of images for the second part of the game. - `GameplayData` is all the needed gameplay data. **Access Routine Semantics** - ImageHit_init(): - transition: Genarete_type(); Generate_list(); SerialNumber = 0; AdditionalList = [] - output: None - Generate_type(): - transition: Use the RamGenerator to select an id from all of the images, and the type of this image is t, SpecifiedType = t  - output: None - Display_type(): - transition: Display the type of specified images on the top of the screen. - output: None - Generate_list(): - transition: Use the RamGenerator to select 3 or 4 ids of images under SpecifiedType, add them in ImageList. Use the Random Generator to select (10 - the amount of images of specifiedType selected before) ids of images under types that are not SpecifiedType, add them in ImageList. $\mathbb{forall}$ i in ImageList, if (i.ImageType = SpecifiedType) => i.ImageMark = `False`; else i.ImageMark =`True`. RandomList(ImageList). - output: None - Display_image(Image): - transition: Display the image on the center of the screen. - output: None - Set_additonal_game() - transition:If (SerialNumber = 9) ($\mathbb{forall}$ item in ImageList: If (item.ImageMark = `False`) => AdditionalList.Add(item). If (count ($\mathbb{forall}$ item in ImageList: item.ImageMark = `True`) > 3) => (i = 0, while i < 3) $\mathbb{forall}$ item in ImageList: If (item.ImageMark = `True`) => (AdditionalList.Add(item), i+1) ; else => $\mathbb{forall}$ item in ImageList: If (item.ImageMark = `True`) => AdditionalList.Add(item). RandomList(AdditionalList)). ImageList += AdditonalList - output: None - Update_image() - transition: If ((The current time of (Trigger.Active("Space") = `True` ) - The current time of the image appears) < 3. | variables | := | | -------------- | ---- | | ImageList[SerialNumber].ImageTime | (The current time of (Trigger.Active("Space") = `True` ) - The current time of the image appears | | ImageList[SerialNumber].ImageMark | bool (1 - ImageList[SerialNumber].ImageMark) | | ImageList[SerialNumber] | += 1 | Display_image(ImageList[SerialNumber]) else | variables | := | | -------------- | ---- | | ImageList[SerialNumber].ImageTime | 3.00 | | ImageList[SerialNumber] | += 1 | Display_image(ImageList[SerialNumber]) - output: None - End_game(): - transition: The game will end once the SerialNumber = the length of ImageList - 1 if SerialNumber > 9. - output: None - GetGameplayData(): - transistion: Once the game ends, the necessary data will be gotten. - output: out := GameplayData **Local Functions** RandomList: `Seq` -> `Seq` RandomList(l) == newList that random = new Random(); newList = new `Seq`; $\mathbb{forall}$ (item in l) => newList.Insert(random.Next(newList.Count), item) #### `CatchTheThief` ADT Module (Meijing) ---- **Uses** Controller Cell **Syntax** **Exported Constants**: None **Exported Types**: None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | | ----------------- | ------ | -------- | --------------- | | CatchTheThief_init | | | | | getGamePlayData | | Seq | **Semantics** **State Variables** - DeckLength: $`\mathbb{N}^+`$ - Deck: [`Cell`] - BoutId: $`\mathbb{N}`$ - IfThiefAppears: $`\mathbb{B}`$ - IfPoliceAppears: $`\mathbb{B}`$ - ThiefPos: $`\mathbb{N}`$ - PolicePos: $`\mathbb{N}`$ - ImageLatingTime: $`\mathbb{R}`$ - ImageAppearGap: $`\mathbb{R}`$ - IsPressed: $`\mathbb{B}`$ - ReactionTime: $`\mathbb{R}`$ - GamePlayData: `Seq` of ($`\mathbb{N}`$, $`\mathbb{B}`$, $`\mathbb{B}`$, $`\mathbb{N}`$, $`\mathbb{N}`$, $`\mathbb{R}`$ , $`\mathbb{R}`$ , $`\mathbb{B}`$, $`\mathbb{R}`$ ) **State Invariant** - `ThiefPos` $`\not=`$ `PolicePos`: the thief image and police should not appear on the same cell - `PolicePos` $`\in`$ [0, 9) - `ThiefPos` $`\in`$ [0, 9) - 0 $`\leq`$ `BoutId` $`\leq`$ 8: there will be total of 8 bouts in the game **Assumptions and Design Decisions** - `Deck` represents the multiple cells. - `DeckLength` represents the number of cells in a deck. - `BoutId` represents the id of current bout. It start from 1, increased by 1 as a new bout starts. - `IfThiefAppears` represents if the theif image appears in the current bout. - `IfPoliceAppears` represents if the police image appears in the current bout. - `ThiefPos` represents on which cell the thief image appears in the current. - `PolicePos` represents on which cell the police images appears in the current round. - `ImageLatingTime` represents the amount of time that the image remains on the screen - `ImageAppearGap` represents the amount of time between when previous image(s) disappears and when the image(s) in current bout appears on the screen - `IsPressed` represents if the player presses the SPACEBAR in the current bout. - `ReactionTime` represents the time between when image(s) appears and when the user presses the SPACEBAR in the current bout - `GamePlayData` represents all above gameplay data in all bouts - In this game, the players press the SPACEBAR to interact with the game. Thus we need to map SPACEBAR to the trigger variable `press`. **Access Routine Semantics** - CatchTheThief_init(): - transition: - DecLength, Deck , BoutId, GamePlayData:= 9, new Cell[DecLength], 0, [] - Controller.pressTrigger(SPACEBAR) - output: out := self - newBout(): - transition: | variables | := | | -------------- | ---- | | RoundId | RoundId + 1 | | IfThiefAppears | RamGenerator.generateARam<`Bool`>() | | IfPoliceAppears | RamGenerator.generateARam<`Bool`>() | | ThiefPos | if (IfThiefAppears = `True`) $`\Rightarrow`$ RamGenerator.generateARam<`Int`>(1, 9) ; else $`\Rightarrow`$ Null | | PolicePos | if (IfPoliceAppears = `True`) $`\Rightarrow`$ RamGenerator.generateARamExcludePoint<`Int`>(1, 9, ThiefPos); else $`\Rightarrow`$ Null | | ImageLatingTime | RamGenerator.generateARam<`Float`>(3, 5) | | ImageAppearGap | RamGenerator.generateARam<`Float`>(1, 2) | - captureUserReaction(): - transition: | variables | := | | -------------- | ---- | | IsPressed | If (Trigger.Active("Space") = `True`) $`\Rightarrow`$ `True`; else $`\Rightarrow`$ `False` | | ReactionTime | The current time of PRESS - The current time of images appear | - UpdateGamePlayData() - transition: GamePlayData.Insert((`BoutId`, `IfThiefAppears`, `IfPoliceAppears`, `ThiefPos`, `PolicePos`, `ImageLatingTime`, `ImageAppearGap`, `IsPressed`, `ReactionTime`)) - getGamePlayData(): - pre-conditions: BoutId = 8 - output: out := GamePlayData #### Ball Module (Shuo) ---- **Uses** MiniGame Timer Counter Controller **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Ball_init | | | | | getGamePlayData | | Seq | | **Semantics** **State Variables**: Round: $\mathbb{N}$  Trial: $\mathbb{N}$  TargetR1: `Target`  TargetR2A: `Target`  TargetR2B: `Target`  TargetR3: `Target`  ReferenceTime `float`  RespondTime: `float`  PickedTarget: `Target`  ActualTarget: `Target`  TargetEarlier: $\mathbb{B}$  IsPressed : Sequence of {$\mathbb{B}$, $\mathbb{B}$, $\mathbb{B}$}  GameplayData: Sequence of($\mathbb{N}$, $\mathbb{N}$, `Target`, `Target`, `Target`, `Target`, `float`, `float`, `Target`, `Target`, $\mathbb{B}$, Sequence of {$\mathbb{B}$, $\mathbb{B}$, $\mathbb{B}$}) **State Invariant**: `TargetAInRoundTwo.GetSpeed()` $\neq$ `TargetBInRoundTwo.GetSpeed()` : The speed of two targets in round two should be different. **Assumptions and Design Decisions**: - Ball_init() is called before any other methods - `Round`: The round in the Ball game - `Trial`: The trial in the Ball game, range in (1,3) - `TargetR1`: The speed of the target in round one - `TargetR2A`: The speed of the target A in round two - `TargetR2B`: The speed of the target B in round two - `TargetR3`: Tbe speed of the trial target in round three - `ReferenceTime`: The reference time of the complete set of stimult - `RespondTime`: The time when the player respond to the assumed arrival - `PickedTarget`: The first arrive target that player picked - `ActualTarget`: The actual target that will arrive first - `TargetEarlier`: Whether the target arrive earlier than reference time - `IsPressed` : Whether the player respond in each round.each round - `GameplayData`: The all gameplay data above **Access Routine Semantics**: - Ball_init(): - transition: | Variables | := | | -------------- | ---- | | Round, Trial, ReferenceTime,RespondTime | 0 | | TargetR1, TargetR2A, TargetR2B, TargetR3| new Target | | PickedTarget, ActualTarget| new Target | | TargetEarlier | False | | IsPressed, GameplayData | [] | - output: self - exception: None - getGamePlayData(): - pre-conditions: Round = 3 - output: out := GamePlayData **Local Function**: - StartGame(): - transition: | Variables | := | | -------------- | ---- | | Round | 1 | | TargetR1| new Target(1,RamGenerator.generateARam<`Float`>(3, 5),RamGenerator.generateARam<`Float`>(3, 5)) | | GameTime | Timer | - output: None - exception: None - NextRound(): - transition: if round = 1, then | Variables | := | | -------------- | ---- | | Round | 2 | | TargetR2A TargetR2B|new Target(2,RamGenerator.generateARam<`Float`>(3, 5),RamGenerator.generateARam<`Float`>(3, 5)| if round = 2, then | Variables | := | | -------------- | ---- | | Round | 3 | | TargetR3 |new Target(3,RamGenerator.generateARam<`Float`>(3, 5),0)| | Trial | 1| |ReferenceTime| ramdomTimeer | - output: None - exception: None - RespondToAssumedTime(): - pre-conditions: Round = 1 - transition: | Variables | := | | -------------- | ---- | | isPressed | If (Trigger.Active("A") = `True`) => isPressed.append(true) | | GameTime | Timer.stop | | RespondTime | GameTime - TargetR1.GetDisppearTime() | - output: None - exception: None - ChooseTarget(): - pre-conditions: Round = 2 - transition: | Variables | := | | -------------- | ---- | | isPressed | If (Trigger.Active("A") = `True`) or If (Trigger.Active("B") = `True`) => isPressed.append(true) | | PickedTarget | If (Trigger.Active("A") = `True`) => `TargetR2A`; If (Trigger.Active("b") = `True`) => `TargetR2A` | - output: None - exception: None - NextTrial(): - pre-conditions: Round = 3 - transition: | Variables | := | | -------------- | ---- | | Trial | Trial + 1 | | TargetR3 |new Target(3,randomSpeed,randomDisappearTIme)| |ReferenceTime| ramdomTimeer | - output: None - exception: None - IndicateOrder(): - pre-conditions: Round = 3 - transition: | Variables | := | | -------------- | ---- | | isPressed | If (Trigger.Active("E") = `True`) or If (Trigger.Active("L") = `True`) => isPressed.append(true) | | EarlyOrLater | If (Trigger.Active("E") = `True`) => `True`; If (Trigger.Active("L") = `True`) => `False` | - output: None - exception: None #### Circles Module (Alice) **Uses** MiniGame Timer Counter Controller **Syntax** **Exported Constants:** None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| |Circles_init | | | | |getGameplaydata | |Seq | | **Semantics** **State Variables**: Level: $\mathbb{N}$  LevelClickTime: `Float`  LevelCircleSize: `Float`  OriginPoint: `Point`  DestinationPoint: `Point`  DestinationTime: `Float`  MoveTime: `Float`  Clicks: Seq of (`Float`,`Float`, Seq of (Float,`Point`))  EndPoint: `Point`  MousePositions: Seq of (level, Seq of (Float,`Point`))  GameplayData: Seq of [(`Point`, `Point`, Float, Float, Seq of (level, Seq of (Float,`Point`)), Seq of (level, Seq of (Float,`Point`)))]  GTimer: `Timer`  LTimer: `Timer`  ClickTime: `Float` HitCount: ℕ  TotalCount: ℕ  MaxClickTime: `Float` WaitTime: `Float` MINX: `Float` MAXX: `Float` MINY: `Float` MAXY: `Float` **State Invariant:** - GameTimer < 60, game is less than a minute - MaxClickTime = 60 - MINX $\leq$ 200 - MAXX $\leq$ 200 - MINY $\leq$ 200 - MAXY $\leq$ 200 **Assumptions and Design Decisions:** - `Level` represents Difficulty level of the destination point. - `LevelClickTime` represents the duration that destination point remains on the screen. - `LevelCircleSize` represents the radius of the destination point - `OriginPoint` represents x,y of mouse position when destination point appear - `DestinationPoint` represents x,y of destination circle - `DestinationTime` represents the time when the destination point appeared - `MoveTime` represents the time when player started to move after destination point appeared - `Clicks` represents the sequence of clicks that the player makes within a level, including the time when the click was done, and the position of the click - `EndPoint` represents the x,y of mouse at the end of the level - `MousePositions` represents the Sequence of mouse positions that the player is in within a level, including the record time, and the position - `GameplayData` - represents all above gameplay data in mini-game - `GTimer` - GameTimer Instance for mini-game - `GTimer` - GameTimer Instance for level - `WaitTime` - Amount of time that game waits before moving to the next level - To ensure there is meaningful and complete data about the flicking motor ability, the locations of the circles are not completely random. First, the player must click the circle in the middle of the screen, then another circle will be generated at a random position. The third circle will be generated in the middle of the screen. - As a result of the previous point, starting from level 0, every even numbered level consists of a circle in the center of the screen. **Access Routine Semantics:** Circle_init(): - transition: | Variables | := | | -------------- | ---- | | Level, DestinationTime, MoveTime | 0 | | LevelClickTime | 5 | | LevelCircleSize | 10 | | Clicks, MousePositions, GameplayData | [] | | OriginPoint, DestinationPoint, EndPoint | new Point| | GTimer,LTimer | new Timer| - output: self - exception: None **Local Functions:** StartGame(): - transition: GTimer.Start() - output: displayLevel() - exception: None NextLevel(): - transition: | Variables | := | | -------------- | ---- | | Level | CalculateNextLevel() | | OriginPoint | Controller.getCursorPos() | | DestinationTime| GameTimer.getTime()| | GameTimer| GameTimer.getTime()| - output: displayLevel() - exception: None FirstMove(): - transition: MoveTime=GameTimer.getTime() - output: None - exception: None OnClick(): * transition: Clicks = Clicks.insert(LevelClickTime, levelCircleSize,[GameTimer,getTime(), Controller.getCursorPos()] ) * output: None * exception: None RecordPosition(): * transition: MousePositions = MousePositions.insert(LevelClickTime, levelCircleSize,[GameTimer,getTime(), Controller.getCursorPos()] ) * output: None * exception: None EndLevel(): * transition:GameplayData.insert(OriginPoint, DestinationPoint, DestinationPoint, DestinationTime, MoveTime, Clicks, MousePositions) * output: None * exception: None DisplayCircle(x,y,s): * transition: displays a circle at the x,y position of size s * output: None * exception: None SuccessfulClick(): - transition: - output: $`\forall click: \mathtt{Clicks} | \exists click`$ - exception: CalculateNextLevel(): - transition: | Condition | Variable Assignment | | -------------- | ---- | | 0 |WaitTime = MaxClickTime | | 1 |LevelClickTime = LevelClickTime - 0.25 first, then WaitTime = LevelClickTime | | 2 |WaitTime = MaxClickTime | | 3 |LevelCircleSize = LevelCircleSize - 1 first, then WaitTime = LevelClickTime | - output: None - exception: None QualifyNextLevel(): - transition: | Condition | Condition 1 |Condition 2 | | -------------- | ---- | | $SuccessfulClick() = True$ |Level = (Level + 1)%3 | | | $SuccessfulClick() = False$ |Level = 1, |Level = Level - 1 then LevelClickTime = LevelClickTime + 0.25 | | $SuccessfulClick() = False$ |Level = 3, |Level = Level - 1 then LevelClickTime = LevelClickTime - 0.25 first, then WaitTime = LevelClickTime | - output: None - exception: None GeneratePosition(): - transition: | Variables | := | | -------------- | ---- | | DestinationPoint.x | generateARam<`Float`>(MINX, MAXX) | | DestinationPoint.y | generateARam<`Float`>(MINY, MAXY) | - output: None - exception: None PlayLevel(): - transition: - output: Use GeneratePosition() to randomize the destination point coordinates then use DisplayCircle(DestinationPoint.x,DestinationPoint.y, LevelCircleSize) to show the Circle on the screen. Then set LTimer to be LevelClickTime. When LTimer reaches 0 or subject clicks on the circle, then execute QualifyNextLevel() then NextLevel() - exception: None #### `Square` ADT Module ----- **Uses** - TODO **Syntax** **Imported Constants** - `SQUARE_CANVAS_WIDTH`: $`\mathbb{R}^+`$ - `SQUARE_CANVAS_HEIGHT`: $`\mathbb{R}^+`$ **Imported Types** - `Position2D` **Exported Constants** - `SQUARE_WIDTH`: $`\mathbb{R}^+ = TODO`$ - `SQUARE_UNHIGHLIGHTED_COLOUR`: `SquareColour` = `SquareColour.PURPLE` - `SQUARE_HIGHLIGHTED_COLOUR`: `SquareColour` = `SquareColour.YELLOW` **Exported Types** - `Square` - `SquareColour` = {`PURPLE`, `YELLOW`} **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Square_init | `Position2D` | | | | Square_flipHighlight | | | | | Square_isHighlighted | | $`\mathbb{B}`$ | | | Square_getPosition | | `Position2D` | | **Semantics** **State Variables** - `currentColour`: `SquareColour` - `position`: `Position2D` **State Invariant** - (`currentColour` = `SQUARE_UNHIGHLIGHTED_COLOUR`) $`\lor`$ (`currentColour` = `SQUARE_HIGHLIGHTED_COLOUR`) **Assumptions and Design Decisions** - `Square_init` is called before any other method. - `position` gives the position of the top left corner of the square. **Access Routine Semantics** - `Square_init(p)` - Transition: (`position`, `currentColour`) := (`p`, `SQUARE_UNHIGHLIGHTED_COLOUR`) - Exception: None - `Square_flipHighlight()` - Transition: $\mathtt{currentColour} := \begin{cases} \mathtt{SQUARE\_UNHIGHLIGHTED\_COLOUR} &\text{if $\mathtt{currentColour} = \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR} $} \\ \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR} &\text{otherwise} \end{cases}$ - Exception: None - `Square_isHighlighted()` - Output: $`\mathtt{currentColour} = \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR}`$ - Exception: None - `Square_getPosition()` - Output: `position` - Exception: None ### 5.2 Ability Measurement ADTs #### `SelectiveVisualMeasure` ADT Module ------ **Uses** CatchTheThief Circles **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** - `Position2D` **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | getScore | | $`\mathbb{N}`$ | | | getLevel | | `AbilityLevelSet` | | **Semantics** **State Variables** - `cd`: `Seq` - `circlesd`: `Seq` - `score`: $`\mathbb{N}`$ - `level` : AbilityLevelSet **State Invariant** None **Assumptions and Design Decisions** - $`0 \leq score \leq 100`$: the score is evaluated over 100 - In the measurement based on Catch The Thief game, a correct press in a short amount of time will result in a higher `score`. **Access Routine Semantics** - getGamePlayData() - Transition: | **Variable** | **:=** | |--------------|----| | cd | CatchTheThief.getGamePlayData() | | circlesd | Circles.getGamePlayData() | - evaluateThiefScore() - Transition: | | **:=** | |--------------|----| | score | <ul>$`\forall cd.BouId: `$<li>$`cd.IfThiefAppears \land \lnot cd.IfPoliceAppears \land IsPressed \Rightarrow score + 5`$</li> <li>$`cd.IfThiefAppears \land IsPressed \land cd.ReactionTime < 2 \Rightarrow score + (2-cd.ReactionTime)*5`$</li> | - evaluateLevel() - Transition: | | **:=** | |--------------|----| | score | <ul><li>$`90 < score \leq 100 \Rightarrow Excellent`$</li> <li>$`75 < score \leq 90 \Rightarrow Good`$</li> <li>$`50 < score \leq 75 \Rightarrow Okay`$</li> <li>$`25 < score \leq 50 \Rightarrow Poor`$</li><li>$`0 \leq score \leq 25 \Rightarrow Very Poor`$</li>| - getScore() - Output: out := score - Exception: None - getLevel() - Output: out = level - Exception: None **Local Types** - AbilityLevelSet = {Excellent, Good, Okay, Poor, Very Poor} #### `InhibitionMeasure` Module ---- **Uses** CatchTheThief **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** None **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | getScore | | $`\mathbb{N}`$ | | | getLevel | | `AbilityLevelSet` | | **Semantics** **State Variables** - `circlesd`: `Seq` - `cd`: `Seq` - `score`: $`\mathbb{N}`$ - `level` : AbilityLevelSet **State Invariant** None **Assumptions and Design Decisions** - $`0 \leq score \leq 100`$: the score is evaluated over 100 - In the measurement based on Catch The Thief game, a success void of pressing when the Police appears will result in a higher `score`. **Access Routine Semantics** - getGamePlayData() - Transition: |Variable | **:=** | |--------------|----| | cd |CatchTheThief.getGamePlayData() | | circlesd | Circles.getGamePlayData() - evaluateThiefScore() - Transition: | | **:=** | |--------------|----| | score | <ul>$`\forall cd.BoutId: `$ <li>$`cd.IfThiefAppears \land cd.IfPoliceAppears \land \lnot IsPressed \Rightarrow score + 5`$</li> <li>$`cd.IfThiefAppears \land cd.IfPoliceAppears \land IsPressed \Rightarrow score - 5`$</li> <li>$`\lnot cd.IfThiefAppears \land cd.IfPoliceAppears \land \lnot IsPressed \Rightarrow score + 5`$</li> <li>$`\lnot cd.IfThiefAppears \land cd.IfPoliceAppears \land IsPressed \Rightarrow score - 5`$</li> | - evaluateLevel() - Transition: | | **:=** | |--------------|----| | score | <ul><li>$`90 < score \leq 100 \Rightarrow Excellent`$</li> <li>$`75 < score \leq 90 \Rightarrow Good`$</li> <li>$`50 < score \leq 75 \Rightarrow Okay`$</li> <li>$`25 < score \leq 50 \Rightarrow Poor`$</li><li>$`0 \leq score \leq 25 \Rightarrow Very Poor`$</li>| - getScore() - Output: out := score - Exception: None - getLevel() - Output: out = level - Exception: None **Local Types** - AbilityLevelSet = {Excellent, Good, Okay, Poor, Very Poor} #### `ObjectRecognition` Module ---- **Uses** ImageHit **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** None **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | getScore | | $\mathbb{N}$ | | | getLevel | | `AbilityLevelSet` | | **Semantics** **State Variables** - `GameData`: `Seq` - `Score`: $\mathbb{N}$ - `Level` : AbilityLevelSet **State Invariant** None **Assumptions and Design Decisions** - 0 <= score <= 100: the score is evaluated over 100 - **Access Routine Semantics** - getGamePlayData() - transition: GameData = ImageHit.GetGameplayData() - output: None - evaluateScore() - Transition: - evaluateLevel() - Transition: - getScore() - Output: out := score - Exception: None - getLevel() - Output: out = level - Exception: None **Local Types** - AbilityLevelSet = {Excellent, Good, Okay, Poor, Very Poor} #### `TimeToContact` Module **Uses** CatchTheThief **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** None **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| |init | | | | getScore | | $`\mathbb{N}`$ | | | getLevel | | `AbilityLevelSet` | | **Semantics** **State Variables** - `GameData` : `Seq` - `score`: $`\mathbb{N}`$ - `level` : AbilityLevelSet **Assumptions and Design Decisions** - Init is called before any other method - $`0 \leq score \leq 100`$: the score is evaluated over 100 - In the Ball game round one, the more accurate that estimated time of the target to arrive at contact point would result in higher score. - In the Ball game round two, the short time for player to pick the correct target will result in higher score. - In the Ball game round three, the more correct trials will result in higher score. **Access Routine Semantics** - Init() - Transition: | | **:=** | |--------------|----| |GameData |Ball.getGamePlayData()| |score | 0| |level | NotTested | - getScore() - Output: out := score - Exception: None - getLevel() - Output: out = level - Exception: None - evaluateScore() - Transition: | | **:=** | |--------------|----| |score | <ul><li>if `GameData.RespondTime` = `GameData.DistanceR1` /`GameData.TargetR1.GetSpeed()` => score + 5; </li> <li>if `GameData.RespondTime` in range( `GameData.DistanceR1` /`GameData.TargetR1.GetSpeed()`+-1) => score + 3;</li> <li>if `GameData.RespondTime` in range( `GameData.DistanceR1` /`GameData.TargetR1.GetSpeed()`+-2) => score + 1;</li> <li>if `GameData.PickedTarget` = `GameData.TargetR2A` and `GameData.TargetR2B.GetSpeed()` <`GameData.TargetR2A.GetSpeed()` => score +5; </li> <li>if `GameData.PickedTarget` = `GameData.TargetR2B` and `GameData.TargetR2B.GetSpeed()` >`GameData.TargetR2A.GetSpeed()` => score +5; </li> <li>if `GameData.DistanceR3`/`GameData.TargetR3.GetSpeed()` > `GameData.ReferenceTime` and `GameData.TargetEarlier` = `False` => score +5; </li> <li>if `GameData.DistanceR3`/`GameData.TargetR3.GetSpeed()` < `GameData.ReferenceTime` and `GameData.TargetEarlier` = `True` => score +5; | - evaluateLevel() - Transition: | | **:=** | |--------------|----| | score | <ul><li>$`90 < score \leq 100 \Rightarrow Excellent`$</li> <li>$`75 < score \leq 90 \Rightarrow Good`$</li> <li>$`50 < score \leq 75 \Rightarrow Okay`$</li> <li>$`25 < score \leq 50 \Rightarrow Poor`$</li><li>$`0 \leq score \leq 25 \Rightarrow Very Poor`$</li>| **Local Types** - AbilityLevelSet = {Excellent, Good, Okay, Poor, Very Poor, NotTested} ### 5.3 Overall System Management: #### `BatterySessionManagement` Module ---- **Uses**:N/A Storage **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Init | | | | **Semantics** **State Variables**: usr: User sessionId: ℕ games: [MiniGame] gameData: [GameData] batteryStartTime: `Float` batteryEndtime: `Float` **State Invariant**: **Access Routine Semantics**: Init(): - transition: batteryStartTime = Timer.getTime(), Storage.store(usr,sessionId) - output:None - exception:None Storedata(): - transition: $\forall$ m : MiniGame | m $\in$ games : { m.init() m.play() } Storage.store(sessionId, (user, sessionId, games, m.getGamePlayData()) - output: None - exception: None C#: Battery Module (user, sessionId, games) Elasticsearch: [{sessionId: sessionId, }, ] 1. get user information 2. data1 <- mini game 1 4. mini game 2 5. submit mini game 2 data 6. mini game 3 7. 3. submit(data1) 8. calculate abilities 9. data visualization **Local Functions**: #### `Player` ADT Module ---- **Uses**:N/A **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Initialize |string, ℕ | | | | UpdateScore |String,float,float | | | | getScore | | float | | **Semantics** **State Variables**: name: string userId: ℕ **State Invariant**: **Access Routine Semantics**: Initialize(s,n): * transition: name = s, id = n * output: None * exception: None **Local Functions**: #### `MiniGame` Interface Module ---- **Uses**:N/A **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Init | | | | | Play | | | | | GetGameplayData | | `Dictionary`<`Object`, `Object`> | | | DisplayInstructions| | | | **Semantics** **State Variables**: **State Invariant**: **Access Routine Semantics**: Init(): * transition: None * output: None * exception: None **Local Functions**: DisplayInstructions(): * transition: Move to instruction scene * output: Displays instructions for game on screen * exception: None #### `Ability` ADT Module ---- **Uses**:N/A **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Initialize |string | | | | UpdateScore |String,float,float | | | | getScore | | float | | **Semantics** **State Variables**: name: string results: list of tuples, where the tuple has the game name, the score of the ability in that game, and the weightage of that game in terms of the cognitive ability **State Invariant**: **Access Routine Semantics**: Initialize(s): * transition: name = s, results = [] * output: None * exception: None UpdateScore(game,newScore,weightage): * transition: results = results || (game,newScore,weightage) * output: None * exception: newScore > 100 ∨ newScore < 0 ⇒ invalid_argument getScore(): * transition: None * output: calculateScore() * exception: None **Local Functions**: calculateScore(): * transition: None * output: ∀ s ∈ results • (∑ score * weightage)/ (∑ weightage) *  * exception: None ### 5.4 Helper modules / Backend glue #### `CountDownTimer` Module ---- **Uses**:N/A **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Start |float | | | | GetTime | | float | | | DisplayTime | | | | **Semantics** **State Variables**: currentTime:float startingTime: float timerText: string **State Invariant**: currentTime ≥ 0 startingTime ≥ 0 **Access Routine Semantics**: Start(i): * transition: startingTime = i * output: None * exception: i < 0 ⇒ IndexOutOfBoundsException GetTime(): * transition: none * output: out := currentTime * exception: None DisplayTime(): * transition: | Conditon 1 | Condition 2 | Output | |------------------|--------------------|--------------------------------------------------------------------------| | currentTime > 5 | True | window := displays timerText ^ timerText.colour = black | | currentTime ≤ 5 | currentTime ≥ 0.1 | window := displays timerText ^ timerText.colour = red | | | currentTime < 0.1 | window := displays timerText ^ currentTime = 0 ^ timerText.colour = red | **Local Functions**: Update(): * transition: currentTime decreases by 0.1 after 0.1 seconds * output: None * exception: None #### `Counter` Type Module ---- **Uses**:N/A **Syntax** **Exported Constants**: None **Exported Types** : None **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Initialize | | | | | GetCounter | | ℕ | | | Increment | | | | **Semantics** **State Variables**: value:ℕ **State Invariant**: value ≥ 0 **Access Routine Semantics**: Initialize(): * transition: value = 0 * output: None * exception: None GetCounter(): * transition: none * output: out := value * exception: None Increment(): * transition: value += 1 * output: None * exception: None **Local Functions**: Update(): * transition: currentTime decreases by 0.1 after 0.1 seconds * output: None * exception: None #### `Position2D` ADT Module ---- **Uses** None **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** - `Position2D` **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Position2D_init | ($`\mathbb{R}`$, $`\mathbb{R}`$) | | | | Position2D_getX | | $`\mathbb{R}`$ | | | Position2D_getY | | $`\mathbb{R}`$ | | **Semantics** **State Variables** - `x`: $`\mathbb{R}`$ - `y`: $`\mathbb{R}`$ **State Invariant** None **Assumptions and Design Decisions** - The first argument is the `x` position, and the second argument is the `y` position **Access Routine Semantics** - `Position2D_init(x', y')` - Transition: (`x`, `y`) := (`x'`, `y'`) - Exception: None - `Position2D_getX()` - Output: `x` - Exception: None - `Position2D_getY()` - Output: `y` - Exception: None #### `Image` Module ---- **Uses** N/A **Syntax** **Exported Constants**: None **Exported Types**: Image = `Seq` of (Url, ImageType, ImageId, ImageMark, ImageTime) **Exported Access Programs**: | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Get_type | | string | | | Get_id | | $\mathbb{N}$ | | | Get_mark | | $\mathbb{B}$ | | | Get_time | | float | | **Semantics** **State Variables** Url: `string`  ImageType: `string`  ImageId: $\mathbb{N}$  ImageMark: $\mathbb{B}$  ImageTime: `float`  **State Invariant**: **Assumptions and Design Decisions** - This type is about the information of an image we need for the game Image Hit. - Assume each image has the attributes url, type, and id in our database. - `ImageType`is the category of the image. - `ImageId` is the id of the image. - `ImageTime` represents the time that one image remains on the screen - `ImageMark` represents the mark that whether an image is misrecognived by the player. **Access Routine Semantics** - Get_type(): - transition: none - output: out := ImageType - Get_id(): - transition: none - output: out := ImageId - Get_mark(): - transition: none - output: out := ImageMark - Get_time(): - transition: none - output: out := ImageTime #### `Target` ADT module ---- **Use** **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** - `Target` **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Target_init | (float, float, float) | | Speed >0 | | Target_GetRound | | float | | | Target_GetSpeed | | float | | | Target_GetDisappearTime | | float | | **Semantics** **State Variables** Round: $\mathbb{N}$ Speed: float DisappearTime: float **State Invariant** `Speed` > 0 **Assumptions and Design Decisions** - The first argument is the `Round` that the target is used - The second argument is the `Speed` of the moving target - The third arugument is the `DisappearTime` of the moving target **Access Routine Semantics** - `Target_init(Round', Speed', DisppearTime')` - Transition: (`Round`, `Speed`, `DisppearTime`) := (`Round'`, `Speed'`, `DisppearTime'`) - Exception: `Speed` > 0 - `Target_GetRound()` - Output: `Round` - Exception: None - `Target_GetSpeed()` - Output: `Speed` - Exception: None - `Target_GetDisappearTime()` - Output: `DisppearTime` - Exception: None #### `Point` ADT Module ---- **Uses** **Syntax** **Imported Constants** **Imported Types** - `Position2D` **Exported Constants** - `SQUARE_WIDTH`: $`\mathbb{R}^+ = TODO`$ - `SQUARE_UNHIGHLIGHTED_COLOUR`: `SquareColour` = `SquareColour.PURPLE` - `SQUARE_HIGHLIGHTED_COLOUR`: `SquareColour` = `SquareColour.YELLOW` **Exported Types** - `Square` - `SquareColour` = {`PURPLE`, `YELLOW`} **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | Square_init | `Position2D` | | | | Square_flipHighlight | | | | | Square_isHighlighted | | $`\mathbb{B}`$ | | | Square_getPosition | | `Position2D` | | **Semantics** **State Variables** - `currentColour`: `SquareColour` - `position`: `Position2D` **State Invariant** - (`currentColour` = `SQUARE_UNHIGHLIGHTED_COLOUR`) $`\lor`$ (`currentColour` = `SQUARE_HIGHLIGHTED_COLOUR`) **Assumptions and Design Decisions** - `Square_init` is called before any other method. - `position` gives the position of the top left corner of the square. **Access Routine Semantics** - `Square_init(p)` - Transition: (`position`, `currentColour`) := (`p`, `SQUARE_UNHIGHLIGHTED_COLOUR`) - Exception: None - `Square_flipHighlight()` - Transition: $\mathtt{currentColour} := \begin{cases} \mathtt{SQUARE\_UNHIGHLIGHTED\_COLOUR} &\text{if $\mathtt{currentColour} = \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR} $} \\ \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR} &\text{otherwise} \end{cases}$ - Exception: None - `Square_isHighlighted()` - Output: $`\mathtt{currentColour} = \mathtt{SQUARE\_HIGHLIGHTED\_COLOUR}`$ - Exception: None - `Square_getPosition()` - Output: `position` - Exception: None #### `RamGenerator` ADT Module ------ **Uses** None **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** None **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | generateARamBool | | $`\mathbb{B}`$ | | | generateARamNum | (`T`, `T`) | `T` | | | generateARamNumExcludePoint | (`T`, `T`, `T`) | `T` | | **Semantics** **State Variables - `from` : `T` - `to`: `T` - `excludedP` : `T` **State Invariant** None **Assumptions and Design Decisions** - T specifies a numeric data type, including $`\mathbb{N}`$, $`\mathbb{R}`$ - `from` < `to` **Access Routine Semantics** - `generateARamBool()`: - output: out := randomly pick a boolean from {`True`, `False`} - Exception: None - `generateARam<T>(from, to)` - Output: out := randomly pick a value `r` such that: $`r : T | r \in [from, to]`$ - Exception: None - `generateARamExcludePoint<T>(from, to, excludedP)` - Output: out := randomly pick a value `r` such that: $`r : T | r \in [from, to] \land r \neq excludedP`$ - Exception: None #### `Cell` ADT Module ---- **Uses** Position2D **Syntax** **Imported Constants** None **Imported Types** None **Exported Constants** None **Exported Types** - `Cell` **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | init | (Position2D, $`\mathbb{N}`$, $`\mathbb{N}`$) | | | | setupImage | `ImagetSet` | | | | appearOnScreen | | Screen Display Change | | | disappearFromScreen | | Screen Display Change | | **Semantics** **State Variables** - `p`: Position2D - `width`: $`\mathbb{N}`$ - `height`: $`\mathbb{N}`$ - `image`: ImageSet - `status`: StatusSet **State Invariant** None **Assumptions and Design Decisions** - `width` and `height` should be in appropriate values such that that nine cells could be displayed nicely on the screen. **Access Routine Semantics** - `init(point, w, h)` - Transition: p, width, height, status := point, w, h, Off - Exception: None - `setupImage(img)` - Transition: image := img - Exception: None - `appearOnScreen()` - Transition: status = On - Output: the cell displays on the screen with the image shown on position `p` with `width` and `height`. - Exception: None - `disappearFromScreen()` - Transition: status = "Off" - Output: the cell disappears from the screen - Exception: None **Local Types** - ImageSet = {Police, Thief, Empty} - StatusSet = {On, Off} #### `SquareCanvas` ADT Module ---- **Uses** - `Square` **Syntax** **Imported Constants - `SQUARE_WIDTH` **Imported Types** - `SquareColour` **Exported Constants** - `SQUARE_CANVAS_WIDTH`: $`\mathbb{R}^+`$ = TODO - `SQUARE_CANVAS_HEIGHT`: $`\mathbb{R}^+`$ = TODO - `SQUARE_HIGHLIGHT_INTERVAL`: $`\mathbb{R}^+`$ = TODO - `SQUARE_HIGHLIGHT_DURATION`: $`\mathbb{R}^+`$ = TODO **Exported Types** - `SquareCanvas` **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | SquareCanvas_init | `[Position2D]` | | `X_OUT_OF_BOUNDS`, `Y_OUT_OF_BOUNDS` | | SquareCanvas_highlightSquares | `[Position2D]` | | `NO_MATCHING_SQUARE` | | Square_isHighlighted | | $`\mathbb{B}`$ | | **Semantics** **State Variables** - `squares`: `[Square]` **State Invariant** - $`\forall s: \mathtt{Square} | s \in \mathtt{squares} \land 0 \le \mathtt{s.getPosition().getX()} \le \mathtt{SQUARE\_CANVAS\_WIDTH} - \mathtt{SQUARE\_WIDTH} \land 0 \le \mathtt{s.getPosition().getY()} \le \mathtt{SQUARE\_CANVAS\_HEIGHT} - \mathtt{SQUARE\_WIDTH}`$ **Assumptions and Design Decisions** - `SquareCanvas_init` is called before any other method. **Access Routine Semantics** - `SquareCanvas_init(ps)` - Transition: $`\mathtt{squares} := [p: \mathtt{Position2D} | p \in ps : \mathtt{Square\_init}(p)]`$ - Exception: - $`(\exists p: \mathtt{Position2D} | p \in ps \land 0 \le \mathtt{p.getX()} \le \mathtt{SQUARE\_CANVAS\_WIDTH} - \mathtt{SQUARE\_WIDTH}) \Rightarrow \mathtt{X\_OUT\_OF\_BOUNDS}`$ - $`(\exists p: \mathtt{Position2D} | p \in ps \land 0 \le \mathtt{p.getY()} \le \mathtt{SQUARE\_CANVAS\_HEIGHT} - \mathtt{SQUARE\_WIDTH}) \Rightarrow \mathtt{Y\_OUT\_OF\_BOUNDS}`$ - `Square_highlightSquares(ps)` - Operation: $`\forall p : \mathtt{Position2D} | p \in ps : \begin{cases} \mathtt{getSquare}(p).\mathtt{flipHighlight()} \\ \mathtt{Timer.wait(SQUARE\_HIGHLIGHT\_DURATION)} \\ \mathtt{getSquare}(p).\mathtt{flipHighlight()} \\ \mathtt{Timer.wait(SQUARE\_HIGHLIGHT\_INTERVAL)} \\ \end{cases} `$ - Exception: Possible `NO_MATCHING_SQUARE` exception propagation from `getSquare`. **Local functions** - `getSquare(p)` : $`\mathtt{Position2D} \rightarrow \mathtt{Square}`$ - Output: $`[s : \mathtt{Square} | s \in \mathtt{squares} \land p = s.\mathtt{getPosition()} : s][0]`$ - Exception: $`\lnot (\exists s: \mathtt{Square} | s \in \mathtt{squares} \land p = s.\mathtt{getPosition()}) \Rightarrow \mathtt{NO\_MATCHING\_SQUARE}`$ ### 5.5 Controller Module (Meijing) #### `Controller` ADT Module **Uses** None **Syntax** **Imported Constants** None **Imported Types** Key MouseButton **Exported Constants** None **Exported Types** None **Exported Access Programs** | **Routine Name** | **In** | **Out** | **Exceptions** | |--------------|----|-----|------------| | pressTrigger | `Key` | | | | clickTrigger | `MouseButton` | | | | pressKey | | | | | releaseKey | | | | | clickMouseBotton | | | | | releaseMouseButton | | | | **Semantics** **State Variables** - `press`: Key - `click`: MouseBotton - `isPressing`: $`\mathbb{B}`$ - `isClicking`: $`\mathbb{B}`$ **State Invariant** None **Assumptions and Design Decisions** - `press` and `click` are two input triggers that would be applied in the Unity Action Framework. - `pressTrigger` method must be called before `pressKey` and `releaseKey` called. - `clickTrigger` method must be called before `clickMouseButton` and `releaseMouseButton` called. **Access Routine Semantics** - pressTrigger(key): - Transition: `press` := key - Exception: None - clickTrigger(mouseButtom): - Transition: `click` = mouseButton - Exception: None - pressKey() - Transition: `isPressing` := `True` - releaseKey() - Transition: `isPressing` := `False` - clickMouseButton() - Transition: `isClicking` := `True` - releaseMouseButton() - Transition: `isClicking` := `False` **Local Types** - Key = a set of name of keys on keyboard - MouseButton = {Right Button, Left Button} ## 6. SRS Changes   For all the content mentioned in this section, please refer to our SRS document. The URL is: https://gitlab.cas.mcmaster.ca/bucklj4/capstone-mini-game-battery-project/-/wikis/Software-Requirements-Specification * 1.2 Stakeholders: The wider McMaster and academic audience for video game research should be added to the subsection **Others**. * 1.5 Product Scope: Since we decided to change some games, this part needs a significant revision. * Product Boundary The cognitive abilities we focus on now are: **Object Recognition**, **Time To Contact**, **Selective/focused Visual**, **Inhibition**, and **Visuospatial Sketchpad**. The motor ability we focus on is **Flicking**. * Game 1: The first game now is **Image Hit**. The cognitive abilities about this game now are **Object Recognition** and **Inhibition**. The way we gamify our measurement of those abilities changes accordingly. Instruction: Ten different images will be shown on the screen one by one and 3-4 images will belong to the same image type. When the user sees an image from the specified type, they should press the SPACEBAR as quickly as possible. When the user sees an image not from the specified type, they shouldn’t press any key. A set of three random images will be shown a second time. The wrongly identified card will also be shown a second time. * Game 2: The second game now is **Catch The Thief**. The cognitive abilities about this game now are **Selective/focused visual**, **Inhibition**. The way we gamify our measurement of those abilities changes accordingly. Instruction: There are nine squares on the screen in a 3x3 array. Every 2 seconds, on these squares, a thief image or a police image may appear (images should not appear on the same square) for a short period before disappearing again. If the thief image appears on a square, the player must press SPACEBAR as fast as possible, If the police image appears, the player must refrain from pressing SPACEBAR until only the thief image is on the screen. * Game 3 The third game now is **Ball**. Compared with the former **Ball** game, the motor ability, **Pressing**, is now not under our consideration. Instruction: Round 1: moving target disappears from view before it reaches the contact point. The subject is then required to make a response that coincides temporally with the target’s assumed arrival at the contact point (CA task). Round 2: Subjects indicate which of two approaching targets will arrive first after they disappear (RJ task). Round 3: Observers indicate on each trial whether a single target would arrive at a contact point earlier or later than the the mean time of arrival for the complete set of stimuli, which served as a form of internalized reference time (RJ task. * Game 4 The fourth game now is **Circles**. The cognitive abilities about this game now are **Object recognition** and **Selective visual**. The motor abilities about this game now are **Flicking**. The way we gamify our measurement of those abilities changes accordingly. Instruction: A 3D screen is shown with a circle on the screen. The player must click on the center of the circle. After each click (regardless of whether it was in the circle), another circle is generated on the screen, and the player must move the mouse to click on the next circle. As the round continues, the game begins to generate smaller and smaller circles. * Game 5 The fifth game now is **Squares**. The cognitive abilities about this game now is **Visuospatial Sketchpad**. The way we gamify our measurement of this ability changes accordingly. Instruction: Squares on the screen are shown in some order.Player then must reproduce the placement of the squares in the same order that it was lit up. There are several rounds, where in the later rounds, the block position and order is shown at a faster speed. Mouse version: the user taps on the square to indicate which square is selected. Keyboard version: map each square to a unique key on the keyboard. * Product Use Case Use cases should be modified to adapt new games. Cases about previous games should be removed. Cases need to be removed include PUC 8 to 11, 15 to 19, 30 to 34, and potentially more. Necessary cases about new games should be added. * 1.6 Definitions, Acronyms and Abbreviations: Abilities which not considered in our previous games should be listed in the subsection **Domain-specific terminology**. * 2.5 Assumptions and Dependencies: More assumptions should be stated. * 3.2 Functional: Due to significant changes to games, functional requirements need to be rewritten mostly. Functional requirements need to be changed include FCS-1 to 4, FM-1 to 9, FB-1, FHS-1 to 6, FFC-1 to 6, and potentially more. Accordingly, necessary functional requirements on our new games should be added. ## 7. Dependency Diagram  ## 8. Significant Design  ## 9.Traceability Table A table for matching the sections of design doc to SRS.  ## 10. Milestone | Meeting Agenda | Time | | ---- | ------- | | Collaborate with group to go over the first version of scripts | Friday 5:30pm | | Second meeting with group | Sunday 12:00pm | | Third meeting with group | Monday morning 8:00am, Lunch(time to be discussed on msger) | | Send the doc to TA & Prof to review | Next Monday afternoon at 3:00 |