Metadata-Version: 2.4
Name: bop-chess
Version: 0.1.1
Summary: Balance of Power Chess - a CLI strategy card game (BoP) where chess flavor meets a 52-card deck.
Author-email: SilverSummitCo LLC <silversummitco@proton.me>
License-Expression: CC-BY-NC-ND-4.0
Project-URL: Homepage, https://github.com/silversummitco/balance-of-power-chess
Project-URL: Source, https://github.com/silversummitco/balance-of-power-chess
Project-URL: Issues, https://github.com/silversummitco/balance-of-power-chess/issues
Keywords: card-game,cli,chess,strategy,balance-of-power,bop
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Games/Entertainment :: Turn Based Strategy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# Balance of Power Chess (`bop`)

> *"King is the father, Queen the mother, the two is the child — and the child
> grows into a King. So the cycle of power begins again."*

**Balance of Power Chess** (BoP Chess, or just **`bop`**) is a two-player
trick-taking card game that maps a 52-card deck onto chess pieces and a
"balance of power" cycle in which even the smallest card can topple the King
under the right conditions. This package is the free, open-source
command-line implementation of the game by its designer, **SilverSummitCo LLC**,
intended as a strategy sandbox for testing lines of play before they reach
the kitchen-table or commercial versions.

---

## Install

### From PyPI (when published)

```sh
pipx install bop-chess          # recommended
# or
pip install --user bop-chess
```

After installation, the `bop` console script is on your `$PATH`:

```sh
bop
```

> The PyPI package name is **`bop-chess`** (`bop` was taken). The `bop`
> console script command is unchanged — you still just type `bop` to play.
> See the [publish runbook](docs/HOWTO_PUBLISH.md) for the full release steps.

### From source (development install)

```sh
git clone https://github.com/silversummitco/balance-of-power-chess.git
cd balance-of-power-chess/BalanceOfPowerGame
python3 -m venv .venv
.venv/bin/pip install -e .[dev]
.venv/bin/bop                      # or:  .venv/bin/python -m bop
```

### Optional: desktop launcher (Linux)

```sh
bop --install-desktop
```

Writes a `.desktop` file under `~/.local/share/applications/` so the game
shows up in your applications menu. macOS / Windows print a graceful
message instead — launch the game from a terminal on those platforms.

---

## Usage

```sh
bop                         # Play a Game to 64 cumulative Procession points.
bop --exhibition            # Play a single Match.
bop --difficulty easy|hard  # Set the AI strength up front.
bop --target-score N        # Custom target score (default 64).
bop --seed N                # Reproducible shuffle - same N gives the same deal.
bop --name LEE              # Skip the name/color/icon setup wizard.
bop --no-intro              # Skip the opening lore crawl.

bop --rules                 # Print the full canonical rules and exit.
bop --credits               # Author, license, tip-jar.
bop --leaderboard           # Show local stats (per-name win/loss tracking).
bop --install-desktop       # Add an applications-menu launcher (Linux).
bop --version
bop --help                  # Full command sitemap.
```

While playing, at any "Play number" prompt you can also type:

| Token             | What it does                                  |
|-------------------|-----------------------------------------------|
| `<number>`        | Play the listed card with that number         |
| `h`, `help`       | Show in-game help                             |
| `r`, `rules`      | Show the full rules without leaving the game  |
| `t`, `tricks`     | Show the full Trick History played so far     |
| `q`, `quit`       | Exit cleanly                                  |

---

## Environment variables

| Var                | Effect                                                       |
|--------------------|--------------------------------------------------------------|
| `NO_COLOR`         | Disable all ANSI colors (per the [no-color.org][nc] convention). |
| `BOP_FORCE_COLOR`  | Force colors on even when stdout isn't a TTY.                |
| `BOP_NO_STATS`     | Skip leaderboard persistence for this run.                   |
| `BOP_STATS_PATH`   | Override the leaderboard file location.                      |
| `BOP_NO_SOUND`     | Silence the intro chime (terminal bell).                     |

[nc]: https://no-color.org/

---

## The game in 30 seconds

* **Chess flavor.** King = K, Queen = Q, **Bishop = A**, **Knight = J**,
  **Rook = 10**. Cards 3-9 are pawns. The 2 is the special "en-passant pawn."
* **Two phases per match.**
  * **Battle Round** — classic trick-taking. Each trick has a *Board Card*
    drawn from the deck which sets the round suit. Must follow suit if
    able. Higher suit beats lower suit; same suit, higher rank wins.
    Special plays: *en passant* (a declared 2 of same-or-higher suit
    beats a King) and *castle* (10 + K of the same suit played together,
    supreme within its suit).
  * **Procession Round** — the final battle. Captured face/10/2 cards from
    the Battle become each player's "power-card" hand. Players play their
    cards in their own ascending order (suit ladder ♣ → ♦ → ♠ → ♥). A
    standing card on the Battle Board stays until outranked. Any **Queen**
    entering the board (natural or a kept 2 played as a *pseudo-Queen*)
    wins the slot — the **Stop Run** rule.
* **Cycle of power.** King beats Queen; Queen beats pseudo-Queen / 2;
  declared 2 beats King. Every card has a vulnerability.
* **Goal.** First player to **64 cumulative Procession points** wins.
  (One point per square on a chess board.)

The complete rules are bundled with the install — run `bop --rules` or read
[`docs/rules.md`](docs/rules.md).

---

## Tip the designer

If you're enjoying the game and want to throw a coin to the author, the
addresses are also listed under `bop --credits`:

- **BTC:** `bc1qc7fp9cjww0ju03v9lyekkce44wfr3zyt6rud6x`
- **DOGE:** `DJDqBvbDjZfZTF3k4d2p7PfZbsJGfPTHKV`

**Contact:** silversummitco@proton.me

---

## Project layout

```
bop/                  ← installable Python package
├── card.py
├── deck.py
├── trick.py
├── battle_round.py
├── transition.py
├── procession.py
├── match.py
├── game.py
├── ai.py
├── stats.py          ← leaderboard persistence
├── install.py        ← desktop-launcher installer
├── cli.py            ← `bop` entry point
└── ui/
    ├── colors.py     ← ANSI palette + helpers
    ├── intro.py      ← Block-letter CHESS splash + rules
    ├── render.py     ← All card / table / frame rendering
    ├── prompts.py    ← HumanPlayer + in-game commands
    └── setup.py      ← Name / color / icon / difficulty wizard
tests/                ← ~220 pytest cases
docs/
├── rules.md          ← Canonical ruleset
└── HOWTO_PUBLISH.md  ← Release runbook
LICENSE               ← CC BY-NC-ND 4.0 © SilverSummitCo LLC
CHANGELOG.md
pyproject.toml
```

---

## Status

Alpha. The game is feature-complete from a play standpoint; the next
publication step is on PyPI. See [`CHANGELOG.md`](CHANGELOG.md) for the
unreleased feature list and [`docs/HOWTO_PUBLISH.md`](docs/HOWTO_PUBLISH.md)
for the publish runbook.

---

## License

**CC BY-NC-ND 4.0** — Copyright © 2024-2026 SilverSummitCo LLC. All rights reserved.

Free to share (unmodified) for personal and educational use.
**No modifications. No commercial use.** Both require the prior written
permission of SilverSummitCo LLC.

Contact: silversummitco@proton.me · See [`LICENSE`](LICENSE) for full terms.
