# 1 Introduction

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

## 1.2 Scope
Qheadache is a standalone computerized puzzle game. The software provides a graphical interface in which the user moves blocks on a board to solve a specific puzzle by achieving a defined end state. The product:
- enables moving blocks within a constrained board,
- supports undo/redo of movements,
- tracks and displays elapsed play time and number of moves,
- manages player statistics and a leaderboard of best results,
- supports saving and loading game state, and
- provides a simple menu-driven user interface.

The primary objective is to provide a simple, accessible game experience with basic performance tracking and persistence of top results.

## 1.3 Product overview

### 1.3.1 Product perspective

#### System interfaces
- [N/A] (The game is a standalone application and is not defined as a component within a larger system.)

#### User interfaces
- The game runs as a standalone application using menus, graphics, and sounds.
- Main window includes:
  - A board where blocks can be moved.
  - A menu bar with the following menus:
    - Game: Open Game…, Save Game…, Save Game As…, Exit.
    - Action: Undo, Redo.
    - Statistics: Display, Erase.
    - Help: About.
- Windows and dialogs:
  - Finish Window with Statistics: displays “You win! Enter your name:” with an edit box (max 20 characters) and an OK button.
  - Simple Finish Window: displays “You win!” with an OK button.
  - Statistics Window: list of up to 10 player statistics entries (name, move count, time).
  - About Window: displays “Qheadache 1.0 by Jean-Philippe Brossat jp_brossat@yahoo.fr”.
- Visuals:
  - Board is black; blocks are yellow.

#### Hardware interfaces
- Input: keyboard and mouse. Other pointing/input devices are allowable if they provide equivalent functionality (cursor movement and text entry).
- Display: graphical display supporting at least 800×600 resolution.
- Sound: used by the UI but not required to play the game.

#### Software interfaces
- Uses the Qt graphical library.
- Must run on all operating systems supported by Qt.

#### Communications interfaces
- Not applicable.

#### Memory constraints
- Not applicable.

#### Operations
- Interactive operation with a single user per machine.
- User-initiated operations via menus and mouse interactions.
- Save/load operations:
  - Open Game to resume a previously saved game.
  - Save Game / Save Game As to persist the current game.
- Exit operation prompts to save if there are unsaved changes.

#### Site adaptation requirements
- Not applicable.

#### Interfaces with services
- Not applicable.

### 1.3.2 Product functions
- Board and blocks:
  - Provide a rectangular game board (5x high by 4x wide, with x between 50 and 100 pixels) and a set of blocks of specified sizes and colors, with defined spacing and non-overlap constraints.
- Interaction:
  - Select, drag, and drop blocks within the board while enforcing boundaries and spacing.
  - Undo and redo movements (up to the last thousand actions).
- Game flow:
  - Detect end-of-game condition when the large square block reaches the bottom of the board.
  - Present appropriate finish window and process player input.
- Statistics:
  - Track per-game statistics (move count, elapsed time).
  - Persist top results (up to 10 entries) with player name, move count, and time.
  - Display and erase statistics.
- File management:
  - Open, Save, and Save As for game state (including current and previous block positions, move count, and elapsed time).
  - Exit with save prompt if needed.
- Help:
  - Display About information.

### 1.3.3 User characteristics
- No specific qualification is necessary.
- Intended for anyone who wants to play a simple game and knows how to operate a computer, from beginning-level players starting at age 8 to advanced-level players (including adults).

### 1.3.4 Limitations
- Single user per machine.
- Requires keyboard/mouse (or equivalent pointing and typing input).
- Requires at least 800×600 display resolution.
- No communications/network interfaces.
- Must run on operating systems supported by Qt; software must be portable to Windows OS.
- Sound is not required to play the game.

## 1.4 Definitions
- [N/A]

# 2 References
- [N/A]

# 3 Requirements

## 3.1 Functions

- Board presentation and constraints
  - Description:
    - The board is a rectangular zone where the user can move blocks.
    - Let x be the measurement unit; x is in pixels and must be between 50 and 100 inclusive.
    - Board dimensions: height 5x, width 4x.
    - Block spacing: blocks are separated by a margin of 0.1x; during movement, blocks cannot approach other blocks closer than 0.05x.
    - Blocks:
      - Four square blocks of side x.
      - Four rectangular blocks of size 2x by x.
      - One block of size x by 2x.
      - One square block of side 2x (the “great square”).
    - Colors: board is black; blocks are yellow.

- Block selection
  - Inputs: left mouse button down on a block.
  - Processing: game state transitions to “Block movement” (dragging).
  - Outputs: none.

- Block deselection
  - Inputs: left mouse button up on the selected block.
  - Processing: game state transitions to “Block selection” (not dragging).
  - Outputs: none.

- Block movement
  - Inputs: mouse movement while in the “Block movement” state (dragging).
  - Processing:
    - The selected block follows the mouse movement.
    - The block must not overlap other blocks.
    - The block must not exit the board boundaries.
    - The block must maintain at least 0.05x clearance from other blocks.
  - Outputs: none.

- Undo action
  - Description: the user can cancel a movement.
  - Inputs: menu selection (Action → Undo).
  - Processing:
    - The game restores block positions to those before the last movement.
    - This undo operation is itself considered a movement.
    - Undo is unavailable if there was no previous movement.
  - Outputs: updated game board display.

- Redo action
  - Description: the user can redo a movement that has been canceled.
  - Inputs: menu selection (Action → Redo).
  - Processing:
    - The game restores block positions to those prior to the cancellation of the last movement.
    - This redo operation is itself considered a movement.
    - Redo is unavailable if the previous action was not an Undo.
  - Outputs: updated game board display.

- Time and move counting
  - Description: track and display elapsed play time and number of moves.
  - Inputs: each block movement.
  - Processing:
    - Increment move count by 1 per movement (including undo/redo as movements).
    - Record the time difference since the last recorded time.
  - Outputs: updated counters (display of time used and number of movements).

- End-of-game detection and finish windows
  - End condition:
    - Inputs: the great square is moved to the bottom of the board.
    - Processing: all player statistics are frozen.
    - Outputs:
      - If the current player’s number of block movements is lower than the highest number of block movements recorded in the statistics file, display the Finish Window with Statistics; otherwise, display the Simple Finish Window.
  - Finish Window with Statistics:
    - Inputs: game is over; player clicks OK after entering a name (up to 20 characters).
    - Processing: record player statistics (name, move count, time) into the statistics file per game statistics management.
    - Outputs: close the finish window; display the Statistics Window.
  - Simple Finish Window:
    - Inputs: game is over; player clicks OK.
    - Processing: close the window.
    - Outputs: close the finish window; display the Statistics Window.

- Statistics management
  - Player statistics during play:
    - Description: the following are recorded during the game: number of block movements since start and time since start.
    - Inputs: a block movement.
    - Processing: increment move count; record elapsed time since last record.
    - Outputs: none.
  - Game statistics persistence:
    - Description: the statistics file contains up to 10 player statistics entries.
    - Inputs: completion of Finish Window with Statistics.
    - Processing:
      - Record the player’s name, number of movements, and time used.
      - If 10 entries are already recorded, erase the entry with the greatest number of block movements before adding the new one.
    - Outputs:
      - If the file is updated correctly, no output.
      - If updating fails (e.g., wrong permissions or disk full), display an error message.
  - Statistics erasing:
    - Inputs: menu selection (Statistics → Erase).
    - Processing: erase all data stored in the statistics file.
    - Outputs:
      - If updated correctly, no output.
      - If erasure fails (e.g., wrong permissions or disk full), display an error message.
  - Statistics Window display:
    - Description: shows a list of up to 10 entries; each line contains player name, number of movements, and time used (read from the statistics file).
    - Inputs: end of game or menu selection (Statistics → Display).
    - Processing: display the statistics window.
    - Outputs: none.

- File management
  - Open Game
    - Inputs: menu selection (Game → Open Game…).
    - Processing: open a file selection dialog; user chooses a previously saved game file.
    - Outputs: redraw the board from the file data; set player statistics to those from the file.
  - Save Game
    - Inputs: menu selection (Game → Save Game…).
    - Processing:
      - If the game was never saved, perform Save Game As.
      - Otherwise, save to the previously used file the following internal data: current positions of the blocks, their last 10,000 previous positions, the number of previous movements, and the elapsed time.
    - Outputs: none.
  - Save Game As
    - Inputs: menu selection (Game → Save Game As…).
    - Processing:
      - Open a file selection dialog; user chooses a destination file.
      - Save the following internal data: current positions of the blocks, their previous positions, the number of previous movements, and the elapsed time.
    - Outputs: none.
  - Exit
    - Inputs: menu selection (Game → Exit).
    - Processing:
      - If the game is not saved, display a dialog asking if the player wants to save the game with “Yes” and “No” options.
      - If “Yes” is selected, perform Save and then close the main window.
      - If “No” is selected, close the main window.
    - Outputs: none.

- Menu bar behavior
  - Game menu:
    - Order: Open Game…, Save Game…, Save Game As…, Exit.
    - Inputs: menu selection.
    - Processing: perform the corresponding action as specified above.
    - Outputs: menu closes; subsequent behavior per the selected action.
  - Action menu:
    - Order: Undo, Redo.
    - Availability: a menu item is unavailable if the associated action is unavailable.
    - Inputs: menu selection.
    - Processing: perform Undo or Redo as specified above.
    - Outputs: menu closes; subsequent behavior per the selected action.
  - Statistics menu:
    - Order: Display, Erase.
    - Inputs: menu selection.
    - Processing: display the Statistics Window or erase statistics as specified above.
    - Outputs: menu closes; subsequent behavior per the selected action.
  - Help menu:
    - Item: About.
    - Inputs: menu selection.
    - Processing: display the About Window with the specified text.
    - Outputs: menu closes; About Window displayed.

## 3.2 Performance requirements
- Capacity:
  - Only one user per machine.
  - Undo/redo shall support the last 1,000 actions.
  - Save Game shall persist up to the last 10,000 previous block positions.
- Display:
  - The system shall operate with a minimum display resolution of 800×600.
- Dynamic performance targets:
  - [N/A]

## 3.3 Usability requirements
- The user interface shall be menu-driven with graphical interaction suitable for beginning-level players aged 8 and above.
- Sound is not required to play the game.
- Specific measurable usability criteria:
  - [N/A]

## 3.5 Logical database requirements
- Data entities:
  - PlayerStatistic:
    - name (string, up to 20 characters),
    - moveCount (integer),
    - timeElapsed (time).
  - GameStatistics:
    - a collection of up to 10 PlayerStatistic entries persisted in a statistics file.
- Integrity and policies:
  - When adding a new entry and the file is full (10 entries), remove the entry with the greatest number of block movements before adding the new one.
- Accessing capabilities:
  - Display statistics via the Statistics Window.
  - Erase all statistics via menu selection.
- Frequency of use:
  - Display at end of game and on demand; updates occur at end of game when the Finish Window with Statistics is completed.
- Security:
  - On file update failures (e.g., wrong permissions, disk full), the system shall display an error message.
- Data retention:
  - Statistics persist across sessions until erased by the user.

## 3.6 Design constraints
- The software uses the Qt graphical library.
- The software must run on all operating systems supported by Qt.
- The software must be portable to the Windows OS.
- Input devices: keyboard and mouse (or equivalent).
- Minimum display resolution: 800×600.
- No communications interfaces are required.

## 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 supported by Qt.

## 3.8 Supporting information
- [N/A]

# 4 Verification

## 4.1 Functions
- [N/A]

## 4.2 Performance requirements
- [N/A]

## 4.3 Usability requirements
- [N/A]

## 4.5 Logical database requirements
- [N/A]

## 4.6 Design constraints
- [N/A]

## 4.7 Software system attributes
- [N/A]

# 5 Appendices

## 5.1 Assumptions and dependencies
- A keyboard and mouse (or equivalent input devices) are available.
- A graphical display with at least 800×600 resolution is available.
- The operating system used is supported by Qt.
- File system permissions and disk space are sufficient to save game state and statistics; otherwise, error messages will be shown.
- Sound capability is optional and not required to play the game.
- Only a single user will use the application on a single machine at a time.

## 5.2 Acronyms and abbreviations
- [N/A]