## 1.1 Purpose
This document establishes the requirements for the software product named Qheadache. The intended audience for this document is the analyst, programmer, and tester of Qheadache.

## 1.2 Scope
The software product to be produced is named Qheadache.

Qheadache is a computerized puzzle game. The software will provide an interface for a user to solve a specific puzzle, referred to as a "headache," by moving blocks on a game board.

The application's primary objective is to provide entertainment to a single user. The game will track user performance, such as the time taken and the number of moves, and maintain a list of high scores to provide a challenge.

### 1.3.1 Product perspective
The product is a stand-alone computerized game application.

#### System interfaces
[N/A]

#### User interfaces
The product's user interface uses menus, graphics, and sounds. Sound is not required to play the game.

#### Hardware interfaces
The product requires the following hardware interfaces:
*   A graphical display with a minimum resolution of 800x600.
*   A keyboard and a mouse for user input. Other pointing and input devices are allowable if they provide similar functions, such as moving a cursor and typing names.

#### Software interfaces
The product uses the Qt graphical library. It must run on all operating systems that Qt supports, including the Windows OS.

#### Communications interfaces
[N/A]

#### Memory constraints
[N/A]

#### Operations
[N/A]

#### Site adaptation requirements
[N/A]

#### Interfaces with services
[N/A]

### 1.3.2 Product functions
The software provides the following major functions:
*   **Game Play:** The user can interact with a game board by selecting and moving blocks to solve a puzzle.
*   **Action Management:** The user can undo and redo up to one thousand of their previous actions.
*   **Performance Tracking:** The system counts and displays the number of actions taken by the user and the elapsed time during a game.
*   **Score Management:** The system records and displays a list of the top scores, which include the player's name, time, and action count. Users can also erase all recorded scores.
*   **Game State Persistence:** The user can save the current state of a game to a file and later open a saved game to continue playing.

### 1.3.3 User characteristics
The intended users are anyone who wants to play a simple game and knows how to operate a computer. No specific qualifications are necessary. The user's age can range from 8 years old for a beginner to an adult for an advanced player.

### 1.3.4 Limitations
*   The product is a stand-alone application.
*   The product requires a graphical display with a minimum resolution of 800x600 pixels.
*   The product requires a keyboard and a mouse or equivalent input devices.
*   The product uses the Qt graphical library and must run on an operating system that Qt supports.
*   Only one user can play on a single machine at a time.

## 1.4 Definitions
[N/A]

# 2 References
[N/A]

## 3.1 Functions
### 3.1.1 Game Session Management
#### 3.1.1.1 Open Game
The user shall be able to open a previously saved game.
*   **Input:** The user selects "Open game..." from the "Game" menu.
*   **Processing:** A dialog box shall be displayed, allowing the user to select a game file. The system shall load the game state from the selected file.
*   **Output:** The game board and player statistics (move count, time) shall be updated to the state from the loaded file.

#### 3.1.1.2 Save Game
The user shall be able to save the current game.
*   **Input:** The user selects "Save Game..." from the "Game" menu.
*   **Processing:**
    *   If the game has been saved before, the system shall overwrite the previously used file with the current game state.
    *   If the game has not been saved before, this action shall be identical to "Save Game As".
    *   The saved data shall include the current positions of all blocks, their last 1000 previous positions, the current move count, and the elapsed time.
*   **Output:** [N/A]

#### 3.1.1.3 Save Game As
The user shall be able to save the current game to a new file.
*   **Input:** The user selects "Save Game As..." from the "Game" menu.
*   **Processing:** A dialog box shall be displayed, allowing the user to choose a file name and location. The system shall save the current game state to that file.
*   **Output:** [N/A]

#### 3.1.1.4 Exit Game
The user shall be able to exit the application.
*   **Input:** The user selects "Exit" from the "Game" menu.
*   **Processing:**
    *   The system shall check if the game has been modified since the last save.
    *   If the game is unsaved, a dialog box shall ask the user if they want to save the game.
    *   If the user selects "Yes", the "Save Game" function shall be performed before the application closes.
    *   If the user selects "No", the application shall close without saving.
*   **Output:** The main window is closed.

### 3.1.2 Gameplay Mechanics
#### 3.1.2.1 Block Selection and Movement
The user shall be able to select and move blocks on the board.
*   **Input:**
    *   Selection: The user presses the left mouse button on a block.
    *   Movement: The user moves the mouse while the left button is held down.
    *   Deselection: The user releases the left mouse button.
*   **Processing:**
    *   When a block is selected, it shall follow the mouse cursor's movement.
    *   The block cannot be moved such that it overlaps another block.
    *   The block cannot be moved outside of the game board's boundaries.
    *   A minimum margin of 0.05x (where x is the base unit of measurement) must be maintained between blocks.
*   **Output:** The position of the selected block is updated on the screen.

#### 3.1.2.2 Undo Action
The user shall be able to undo their last action.
*   **Input:** The user selects "Undo" from the "Action" menu.
*   **Processing:** The system shall revert the positions of all blocks to their state before the last movement. This action is counted as a movement. The "Undo" function shall be unavailable if no movements have been made. The system must store up to 1000 previous actions to be undone.
*   **Output:** The game board display is updated to the previous state.

#### 3.1.2.3 Redo Action
The user shall be able to redo an action that was just undone.
*   **Input:** The user selects "Redo" from the "Action" menu.
*   **Processing:** The system shall restore the block positions to the state they were in before the "Undo" action was performed. This action is counted as a movement. The "Redo" function shall be unavailable if the previous action was not an "Undo".
*   **Output:** The game board display is updated to the state before the undo.

### 3.1.3 Game Progression and Statistics
#### 3.1.3.1 Track Player Statistics
The system shall track the player's performance during a game.
*   **Input:** A block movement is completed.
*   **Processing:** The system shall increment the block movement counter by one. The system shall continuously track the total time elapsed since the start of the game.
*   **Output:** The current move count and elapsed time shall be displayed to the user.

#### 3.1.3.2 End of Game
The system shall detect when the game has been won.
*   **Input:** The large square block (2x2) is moved to the designated exit position at the bottom of the board.
*   **Processing:** All player statistics (time, move count) are frozen. The system compares the player's move count to the scores recorded in the statistics file.
*   **Output:**
    *   If the player's score qualifies for the top 10 leaderboard, a "Finish Window with Statistics" shall be displayed, prompting the user to enter their name.
    *   Otherwise, a "Simple Finish Window" shall be displayed.

### 3.1.4 Score Management
#### 3.1.4.1 Record High Scores
The system shall record high scores when a game is won.
*   **Input:** The user enters a name (up to 20 characters) and clicks "OK" in the "Finish Window with Statistics".
*   **Processing:** The player's name, move count, and time are saved to the statistics file. If the file already contains 10 scores, the entry with the highest (worst) number of block movements is replaced by the new score.
*   **Error Handling:** If the statistics file cannot be updated (e.g., due to incorrect permissions or a full disk), an error message shall be displayed.
*   **Output:** The "Finish Window" is closed and the "Statistic Window" is displayed.

#### 3.1.4.2 Display Scores
The user shall be able to view the high scores.
*   **Input:** The game ends, or the user selects "Display" from the "Statistics" menu.
*   **Processing:** The system reads the high scores from the statistics file.
*   **Output:** A "Statistic Window" is displayed, showing a list of up to 10 scores. Each entry shall contain the player's name, move count, and time.

#### 3.1.4.3 Erase Scores
The user shall be able to erase all recorded scores.
*   **Input:** The user selects "Erase" from the "Statistics" menu.
*   **Processing:** All data stored in the statistics file is deleted.
*   **Error Handling:** If the statistics file cannot be modified, an error message shall be displayed.
*   **Output:** [N/A]

## 3.2 Performance requirements
*   The system shall support only one user per machine.
*   The system shall store the last 1,000 user actions to support the undo and redo functions.
*   The system shall store game statistics for up to 10 players.

## 3.3 Usability requirements
The system shall be usable by anyone who knows how to operate a computer, with an intended user age range from 8 years old to adult. No specific qualifications are necessary.

*   **User Feedback:**
    *   The system shall continuously display the elapsed time and the number of user actions.
    *   The system shall display a "You win!" message upon successful completion of the game.
    *   The system shall display an error message if it fails to save statistics due to issues like incorrect permissions or a full disk.
*   **Error Tolerance and Recovery:**
    *   The user shall be able to undo and redo their last thousand actions.
    *   The system shall prompt the user to save the game if they attempt to exit without saving.
*   **Interface Clarity:**
    *   Menu items for actions that are not currently available, such as "Undo" when no moves have been made or "Redo" when the last action was not an "Undo", shall be disabled.

## 3.5 Logical database requirements
The system shall persist two types of information in files: game statistics and saved game states.

The game statistics file stores high scores.
*   **Types of Information:** Each record consists of a player's name (up to 20 characters), the total number of block movements, and the time taken to finish the game.
*   **Frequency of Use:** The statistics file is read when the user chooses to display the statistics window. It is written to when a user finishes a game with a score that qualifies for the top 10. All statistics are deleted when the user selects the erase option from the menu.
*   **Accessing Capabilities:** The system shall be able to create, read, update, and delete the statistics file.
*   **Data Entities and Relationships:** The primary data entity is a Player Score. The statistics file is a collection of up to 10 Player Score entities.
*   **Integrity Constraints:** The file shall contain a maximum of 10 player scores. If the file is full and a new high score is achieved, the score with the greatest number of block movements is replaced.
*   **Data Retention:** The statistics are retained indefinitely unless explicitly erased by the user.

The saved game file stores the state of a game in progress.
*   **Types of Information:** A saved game file contains the current positions of all blocks, the history of the last 1000 block positions for undo/redo functionality, the current number of movements, and the current elapsed time.
*   **Frequency of Use:** A saved game file is written when the user selects "Save" or "Save As". It is read when the user selects "Open".
*   **Accessing Capabilities:** The system shall be able to create, read, and overwrite saved game files as directed by the user.
*   **Data Entities and Relationships:** The primary data entity is a Saved Game State with attributes for block positions, move history, move count, and elapsed time.
*   **Integrity Constraints:** The move history must be sufficient to support up to 1000 undo actions.
*   **Data Retention:** Saved game files are retained indefinitely until manually deleted by the user from the file system.

Security requirements for data files are not specified.
*   **Security:** [N/A]

## 3.6 Design constraints
- The product shall be a stand-alone application.
- The product shall use the Qt graphical library.
- The product shall be compatible with all operating systems supported by the Qt library.
- The product shall require a minimum screen resolution of 800x600 pixels.

## 3.7 Software system attributes
### Reliability
[N/A]

### Availability
[N/A]

### Security
[N/A]

### Maintainability
[N/A]

### Portability
*   The product must be portable to the Windows OS.
*   The product uses the Qt graphical library and must run on all operating systems that Qt supports.

## 3.8 Supporting information
[N/A]

## 4.1 Functions
[N/A]

## 4.2 Performance requirements
[N/A]

## 4.3 Usability requirements
[N/A]

## 4.5 Logical database requirements
Verification of the statistics file shall be performed by testing and inspection.
*   Verify that the statistics file correctly stores the player's name (up to 20 characters), the number of block movements, and the time elapsed when a game is won and a score is submitted.
*   Verify that the statistics file stores a maximum of 10 player scores.
*   Verify that when an 11th score is recorded, it replaces the existing score with the greatest number of block movements.
*   Verify that the "Display" statistics function correctly reads and shows all saved scores.
*   Verify that the "Erase" statistics function correctly deletes all data from the statistics file.
*   Verify that saved scores persist after the application is closed and reopened.
*   Verify that an error message is displayed if the statistics file cannot be written to (e.g., due to wrong permissions or a full disk).

Verification of the saved game file shall be performed by testing.
*   Verify that loading a saved game correctly restores the board state, the number of movements, and the elapsed time to the values they had when the game was saved.
*   Verify that after loading a saved game, the history of the last 10,000 block positions is also restored, allowing the undo function to work as specified.
*   Verify that the "Save game as" function creates a new file containing the complete current game state.
*   Verify that the "Save game" function updates the existing file with the complete current game state.
*   Verify that the "Open game" function successfully loads a game state from a user-selected file.
*   Verify that attempting to exit with unsaved changes prompts the user to save the game, and that the subsequent action ("Yes" or "No") is performed correctly.

Verification of frequency of use requirements:
*   [N/A]

Verification of data security requirements:
*   [N/A]

## 4.6 Design constraints
[N/A]

## 4.7 Software system attributes
[N/A]

## 5.1 Assumptions and dependencies
*   The product's ability to run on multiple operating systems is dependent on the cross-platform support provided by the Qt graphical library.
*   It is assumed that the application will have the necessary permissions to write to the local file system in order to save game state and player statistics.

## 5.2 Acronyms and abbreviations
[N/A]