## 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 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 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 their last thousand actions.
*   **Game Progress Tracking:** The system counts and displays the elapsed time and the number of actions the user has taken.
*   **Score Management:** The system records player scores (time and action count) associated with a player name. It can display a window of all recorded scores and allows for the erasure of all score data.
*   **Game State Management:** The user can save the current game state to a file, load a previously saved game, and exit the application.

### 1.3.3 User characteristics
The intended users are anyone who wants to play a simple game and knows how to operate a computer. The user's age can range from a beginning level player starting at age 8, up to an advanced level player who is an adult. No specific qualifications are necessary.

### 1.3.4 Limitations
*   The product is a stand-alone application.
*   The product supports only one user per machine.
*   The product requires a graphical display with a minimum resolution of 800x600.
*   The product requires a keyboard and a mouse or equivalent input devices.
*   The product is dependent on the Qt graphical library and must run on operating systems supported by Qt.

## 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 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. The target audience ranges from a beginning player starting at age 8 to an advanced adult player. No special qualifications are necessary to play the game.

To support usability, the system shall provide the following:
*   The ability for a user to undo and redo their last thousand actions.
*   A Help menu containing an "About" window.

Measurable objectives for effectiveness, efficiency, and user satisfaction are not specified in the original document.

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

The following types of information shall be stored:
*   **Saved Game State:**
    *   The current positions of all blocks on the board.
    *   The positions of blocks for the last 1000 movements to support the undo/redo feature.
    *   The current number of movements.
    *   The current elapsed time.
*   **Game Statistics:**
    *   A collection of up to 10 player statistic records.
    *   Each record consists of a player's name (up to 20 characters), the total number of movements, and the time taken to solve the puzzle.

Data shall be accessed as follows:
*   A saved game state file is created or updated when the user saves a game.
*   A saved game state file is read when the user opens a previously saved game.
*   The game statistics file is read when the statistics window is displayed.
*   The game statistics file is updated at the end of a game if the player's score qualifies for the top 10.
*   The game statistics file is erased when the user selects the option to erase statistics.

The following data integrity constraints shall be enforced:
*   The game statistics file shall store a maximum of 10 player records.
*   If the statistics file is full and a new high score is achieved, the record with the greatest number of block movements shall be replaced.
*   The system shall display an error message upon failure to write to a file due to issues such as incorrect permissions or a full disk.

Data retention requirements are as follows:
*   Saved game files are retained until manually deleted by the user.
*   The game statistics file is retained until the user explicitly erases it via the corresponding menu option.

[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 OS.
*   The software 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 logical database requirements shall be performed by testing.

*   **Game State Save/Load:**
    *   **Test:** Save a game in progress. Close and restart the application. Load the saved game.
    *   **Expected Result:** The game shall be restored to the exact state it was in when saved, including all block positions, the current move count, the elapsed time, and the undo/redo history.

*   **Statistics Recording:**
    *   **Test:** Complete a game with a score that qualifies for the top 10 list. Enter a player name when prompted.
    *   **Expected Result:** The player's name, move count, and time shall be correctly recorded in the statistics file and displayed in the statistics window.

*   **Statistics Integrity:**
    *   **Test:** Fill the statistics list with 10 scores. Achieve a new score that is better (fewer moves) than the worst score on the list.
    *   **Expected Result:** The new score shall be added to the list, and the score with the highest number of moves shall be removed.
    *   **Test:** Fill the statistics list with 10 scores. Achieve a new score that is worse than any score on the list.
    *   **Expected Result:** The statistics list shall remain unchanged.

*   **Statistics Deletion:**
    *   **Test:** Select the option to erase all statistics.
    *   **Expected Result:** The statistics file shall be cleared of all entries.

*   **File I/O Error Handling:**
    *   **Test:** Attempt to save a game or record a high score when the target file is read-only or the disk is full.
    *   **Expected Result:** An error message shall be displayed to the user.

## 4.6 Design constraints
[N/A]

## 4.7 Software system attributes
[N/A]

## 5.1 Assumptions and dependencies
*   The product is dependent on the Qt graphical library. The product's ability to run on various operating systems is contingent upon the operating systems supported by the Qt library.

## 5.2 Acronyms and abbreviations
[N/A]