Metadata-Version: 2.4
Name: chess-opening-tool
Version: 0.1.0
Summary: Build, explore, and train your chess opening repertoire.
Keywords: chess
Author: Moritz R. Schäfer
Author-email: Moritz R. Schäfer <moritz.schaefer-f91@rub.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Requires-Dist: chess>=1.11.1
Requires-Dist: kivy>=2.3.1
Requires-Dist: kivy-chess-board>=1.0.3
Requires-Dist: logdecorator>=2.5
Requires-Dist: sqlite-bytes-store>=0.1.0
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: xfilepy>=0.5.2
Requires-Dist: pyinstaller>=6.0 ; extra == 'packaging'
Maintainer: Moritz R. Schäfer
Maintainer-email: Moritz R. Schäfer <moritz.schaefer-f91@rub.de>
Requires-Python: >=3.11, <3.14
Project-URL: Repository, https://gitlab.com/M0M097/chess-opening-tool
Project-URL: Documentation, https://gitlab.com/M0M097/chess-opening-tool/-/wikis/Usage
Project-URL: Issues, https://gitlab.com/M0M097/chess-opening-tool/-/issues
Provides-Extra: packaging
Description-Content-Type: text/markdown

# Chess Opening Tool

**Chess Opening Tool** helps you **build, explore, and train your chess opening
repertoire**. It’s free, open-source, and designed to run on all
platforms — including desktop, Android, and iOS.

---

## Overview

Unlike most chess software, Chess Opening Tool is **transposition-aware**:  it
automatically recognizes when the same position is reached through different
move orders and merges them into a single entry in your opening tree.

All moves played on the board are recorded in a position tree. From any
position, you can view possible continuations and quickly cycle through them.

---

## Organizing Your Openings

### Using PGN Files
Each opening tree is stored as a **standard PGN file**.
You can:
- **Import** existing PGNs to merge them into your current tree (transpositions
  are resolved automatically).
- **Open** a PGN to make it your active tree — saving will overwrite that file.
- **Export** your current tree to share or back it up.

**Importing vs Opening:**
- *Import* adds the content of a PGN into your current tree.
- *Opening* replaces the current tree with the selected PGN.

---

### Tabias (Tagged Positions)

A **tabia** is a named reference to a specific position — like a **bookmark**
or **key opening branch**.
You can:
- Assign a name to any position.
- Jump directly to it from the **Tabia menu** (`m` key).

Tabias are saved automatically inside the PGN (as game entries using the tabia
name as the event).  When saved, the main game and each tabia start where
another tabia ends — forming a clear, connected structure.

---

## Training Mode

Training mode lets you **test yourself** on your repertoire:
you’re shown a position and must find the correct move(s).

- Toggle it at any point with `t`.
- Training starts from the current position.
- Once you find all correct moves in a position, it moves deeper into the tree.
- It first goes through all **main lines**, then the **sub-variations**.

This feature is designed for focused, manual training — it doesn’t track
progress or use spaced repetition.

---

## Usage / Keyboard Shortcuts

On desktop, the interface is **fully keyboard-driven** for a clean,
distraction-free experience.  Once you get used to it, this allows for an fast
workflow. Of course, moves can also be played with the mouse.

| Key / Combination               | Action                                 |
|---------------------------------|----------------------------------------|
| **space**, **→**, **l**         | Next move                              |
| **Shift + space**, **←**, **h** | Previous move                          |
| **↑**, **k**                    | Cycle variants backward                |
| **↓**, **j**                    | Cycle variants forward                 |
| **+**, **-**                    | Promote/Demote selected variant        |
| **f**                           | Flip board                             |
| **i**                           | Import PGN(s)                          |
| **o**                           | Open PGN                               |
| **p**                           | Move menu / peak moves during training |
| **e**                           | Export PGN                             |
| **c**                           | Copy FEN to clipboard                  |
| **d**                           | Delete last move                       |
| **s**                           | Save current tree                      |
| **Shift + s**                   | Save as...                             |
| **t**                           | Toggle training mode                   |
| **m**                           | Open Tabia menu                        |
| **p**                           | Open Move menu                         |
| **n**                           | New opening                            |
| **q**                           | Quit application                       |

You can also hover over the top or bottom edges of the board to reveal
on-screen controls for navigation and other actions on desktop. On mobile, all
controls are always visible.

---

## Notes
- Your work is stored in standard PGN format, so it’s always portable and
  editable in other chess software.
- All positions and tabias are preserved between sessions.
- On mobile, equivalent actions are accessible via on-screen controls.
- Packaged release downloads are described in [INSTALL.md](INSTALL.md).

---

## Licensing

Chess Opening Tool is free and open source software licensed under the [**GNU
General Public License v3.0**](LICENSE).

This project includes third-party components:

- DejaVu Sans (DejaVuSans.ttf)
  - License: [DejaVu Fonts License](src/chess_opening_tool/gui/fonts/LICENSE-DejaVuFonts)
  - Applies to: src/chess_opening_tool/gui/fonts/DejaVuSans.ttf

Packaged releases bundle further third-party components including chess board
and piece artwork; see THIRD_PARTY_LICENSES.json in packaged releases.
