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

## 1.2 Scope
The software product to be produced is a computerized puzzle game named Qheadache.

The product will provide a graphical user interface for a game where the user solves a puzzle by moving various blocks within a rectangular board. The software will track the time taken and the number of moves made by the user. It will also allow the user to undo and redo moves, save and load game progress, and view a list of high scores.

The application is a single-player game intended for entertainment. The objective is to solve the puzzle by moving a specific block to a designated location on the board. The goal is to achieve a high score by minimizing the time and number of moves required to solve the puzzle.

### 1.3.1 Product perspective
The product is a stand-alone application and does not interface with any larger systems.

The software provides a graphical user interface that includes menus, graphics, and sounds.

The product interfaces with computer hardware, requiring a keyboard and a mouse for input and a graphical display with a minimum resolution of 800x600. Other pointing and input devices are allowable if they provide similar functionality.

The product uses the Qt graphical library and must be compatible with all operating systems that Qt supports.

The product does not require any communications interfaces.

There are no specific memory constraints for the product.

The software is an interactive game operated by a single user. Operations are user-initiated and include game play, saving the game state, and loading a previously saved game.

The product has no site adaptation requirements.

[N/A]

### 1.3.2 Product functions

The product 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 History:** The user can undo and redo up to their last thousand actions.
*   **Performance Tracking:** The system counts and displays the elapsed time and the number of actions the user has taken during a game.
*   **Score Management:** The system records player scores, consisting of the player's name, time, and action count. It can also display a window listing all recorded scores.
*   **Game State Management:** The user can save the current game state to a file and load a previously saved game.

### 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 Board
The game is played on a rectangular board with a black background. The board's height is 5x and its width is 4x, where x is a unit of measure between 50 and 100 pixels.

The board contains the following yellow blocks:
*   Four square blocks with a side of x.
*   Four rectangular blocks with a height of 2x and a width of x.
*   One rectangular block with a height of x and a width of 2x.
*   One square block with a side of 2x.

Blocks on the board are separated by a margin of 0.1x.

### 3.1.2 Game Play
#### 3.1.2.1 Block Movement
A user can move a block by performing the following sequence:
1.  **Selection:** The user presses the left mouse button while the cursor is over a block.
2.  **Movement:** While holding the mouse button down, the user moves the mouse. The selected block follows the cursor. Blocks cannot overlap other blocks or move outside the board. A minimum margin of 0.05x must be maintained between the moving block and other blocks.
3.  **Deselection:** The user releases the left mouse button to place the block.

#### 3.1.2.2 Undo and Redo
The user must be able to undo and redo their last thousand actions.
*   **Undo:** The user can cancel the last movement by selecting the "Undo" menu option. This action reverts the blocks to their positions before the last movement and is counted as a movement itself. The undo option is unavailable if no movements have been made.
*   **Redo:** The user can re-apply a movement that was just canceled by selecting the "Redo" menu option. This action is counted as a movement itself. The redo option is only available if the immediately preceding action was an "Undo".

### 3.1.3 Game Completion
The game is finished when the large 2x by 2x square block is moved to the bottom of the board. Upon completion, the player's statistics (move count and time) are frozen.

The system's response depends on the player's score:
*   If the player's move count is low enough to qualify for the high score list, a "Finish Window with Statistics" is displayed. This window prompts the user to enter a name (up to 20 characters) and click "OK". Upon clicking "OK", the score is saved and the "Statistic Window" is displayed.
*   If the player's score does not qualify for the high score list, a "Simple Finish Window" is displayed with a "You win!" message and an "OK" button. Upon clicking "OK", the "Statistic Window" is displayed.

### 3.1.4 Statistics Management
#### 3.1.4.1 Statistics Tracking
The system shall track and display the following statistics during gameplay:
*   The total number of block movements made by the user.
*   The total time elapsed since the game started.

#### 3.1.4.2 High Score List
The system shall maintain a high score list of the top 10 player statistics, stored in a file. Each entry consists of a player's name, their final move count, and the time taken.
*   **Recording:** When a player achieves a score that qualifies for the list, their statistics are recorded. If the list is already full (contains 10 entries), the entry with the highest number of block movements is replaced by the new score.
*   **Displaying:** The "Statistic Window" displays the high score list. This window can be opened via a menu option or is shown automatically at the end of a game.
*   **Erasing:** The user can erase all data from the statistics file via a menu option.

### 3.1.5 File Management
#### 3.1.5.1 Open Game
The user can open a previously saved game. A dialog box allows the user to select a game file, which restores the game board and player statistics to their saved state.

#### 3.1.5.2 Save Game
The user can save the current game state.
*   If the game has been saved before, the system overwrites the existing file with the current state.
*   If the game has not been saved before, this action functions identically to "Save Game As...".
*   The saved data includes the current positions of the blocks, their last 10000 previous positions, the move count, and the elapsed time.

#### 3.1.5.3 Save Game As
The user can save the current game state to a new file. A dialog box allows the user to specify a file name and location.

#### 3.1.5.4 Exit
The user can exit the application. If the current game has not been saved, a dialog box prompts the user to save their progress. If the user chooses "Yes", the "Save Game" action is performed before the application closes. If the user chooses "No", the application closes without saving.

### 3.1.6 Menu System
The main window shall provide a menu bar with the following menus and items:
*   **Game Menu:** "Open game...", "Save Game...", "Save Game As...", "Exit".
*   **Action Menu:** "Undo", "Redo". These items are disabled when the corresponding action is unavailable.
*   **Statistics Menu:** "Display", "Erase".
*   **Help Menu:** "About", which displays a window with product and author information.

### 3.1.7 Error Handling and Abnormal Situations
*   **File Operations:** If saving the game or erasing statistics fails (e.g., due to incorrect file permissions or a full disk), an error message shall be displayed.
*   **Validity Checks on Inputs:** [N/A]

## 3.2 Performance requirements
*   The system shall support one simultaneous user per machine.
*   The system shall store the last 1,000 user actions to support the undo and redo functions.
*   The system shall store statistics for the top 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 software must be portable to the Windows operating system. It must run on all operating systems that the Qt graphical library 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]