LVPWB/README.md

# LVPWB — Light Virtual Pro-Wrestling Booker

LVPWB is an interactive Python 3 booking companion for wrestling games. Build
three-match cards and seasons, then play the booked matches in a separate game
and record the results here for a more hands-on experience. A separate game or
emulator is optional: you can simulate results and let the season progress
entirely in LVPWB.

Requires Python 3.10 or later. Run from the project directory with:

```sh
python3 -m lvpwb
```

### Install

Install a user-level `lvpwb` command under `~/.local`:

```sh
make install
make verify
```

Set `PREFIX` to use another installation prefix, or `PYTHON` to select the
interpreter. If `~/.local/bin` is not on your `PATH`, add it as instructed by
the installer. Uninstall with `make uninstall`; saved cards, seasons, and BYOG
profiles are kept under `~/.local/share/lvpwb/`.

Cards are saved as Markdown in `cards/`. Load a card to view it, record results,
edit unfinished matches, or add a randomized promo before the next match. A card
is saved after each edit or result, so you can stop and resume later.

The main menu also has a fully randomized one-off show (choose a game first) and
Season Mode. Seasons save separately under `seasons/` and book Raw → Thursday
Night SmackDown! → WWF PPV repeatedly. New season champions can be selected,
randomized, or left vacant. Built-in seasons ask which wrestlers are eligible
for the Light-Heavyweight division; that selection is saved with the season.
Semi-random cards use division rankings and repeat-match rivalries;
title defenses are possible on any show and are weighted more heavily on PPVs.
PPV cards may feature up to two title defenses, while weekly shows may feature
one. Mark each season match with a ranking division, and separately mark title
defenses. Results update division records; only marked defenses can change the
champion. Successful defenses are tracked by champion across reigns. The
“Others” pool contains wrestlers not currently involved in title divisions; it
is not a championship.

Season Mode offers **Booker** control (full card control) and **Wrestler**
control. In Wrestler control, choose one roster member: you record results only
for matches featuring that wrestler, while the remaining matches are simulated.
The booker may leave your wrestler off a show, in which case the entire card is
simulated. Rankings and booking still progress, and control mode can be toggled
from the Season action menu.

After all matches on a season card are complete, choose **Advance to Next Show**
to return to the season hub. From there you can inspect power rankings, exit, or
book the next show. While matches remain, the card menu offers **Return to Season
Menu**. Use **Auto-simulate all remaining matches** to finish a card without
entering each result; simulated season results favor higher-ranked competitors,
but upsets remain possible.

Manual and simulated results respect match finishes: Ladder/TLC require item
retrieval, Tables require a table break, Battle Royals require a last-survivor
win, and Cage matches require escape. Other listed match types use pinfall or
submission. Ranking-based non-title matches are not labeled as contender matches.

### BYOG — Bring Your Own Game

**BYOG / Manage Games** on the main menu lets you run cards and seasons for any
federation, not just the built-in WWF games:

- **Create a new game and federation** — name the game, pick the federation and
  platform (PlayStation 1, PlayStation 2, or other), name the federation's
  three shows, list the roster, edit the suggested match types, and add any
  championship/ranking divisions (singles, tag team, women's, or
  Light-Heavyweight). Restricted divisions let you choose eligible wrestlers.
- **Copy a built-in WWF game to edit** — clones any built-in game into your own
  editable profile; the built-in games themselves stay unchanged.
- **Edit a custom game** — reopen any saved profile.

The Edit roster menu offers a read-only **View roster** option that prints the
full roster alphabetically without prompting for changes.

Show names are WWE branding, so custom federations name their own three shows
during creation (or later via **Show names** in the BYOG editor). The three
slots match the season cycle — the first weekly show, the second weekly show,
and the big event — and default to neutral placeholders ("Weekly Show #1",
"Weekly Show #2", "Big Pay-Per-View") when left untouched. Booked season cards
and random one-off shows use those names, and an event card titled with the
third slot's name counts as a PPV for title weighting and the event rating.

Profiles are stored under `edit/games/<game id>.json` and are validated on
save/launch; invalid files are skipped with a console message so one typo cannot
break the menu. Every custom game is listed alongside the built-ins whenever a
card or season asks for a game, including its federation name. Custom games on
the PlayStation 1 and PlayStation 2 platforms use the corresponding emulator's
screenshot directory by default. Set a custom screenshot directory in the
BYOG identity editor to override that default (or enable screenshots for another
platform). Overrides expand `~`; relative paths resolve from the LVPWB data
directory. Saved cards and seasons record the game identity and title divisions
they were created with, so old saves keep working (and keep their own divisions)
after you edit a profile. Bases for custom match types default sensibly; enter an
explicit base rating per match type when you want a different number.

When recording a match result, enter its duration in minutes, near-fall count,
and finishers executed. Match ratings use fixed match-type bases, +0.1 points
per full minute (up to +5), +0.2 per near fall, and +0.5 per finisher. The
combined live bonus is capped at +10; title matches then receive a ×1.5
multiplier, with the final rating capped at 100%. WWF PPV cards calculate their
event rating as Match 1 × 20% + Match 2 × 30% + Match 3 × 50%, once all three
matches have ratings. Match and event ratings are saved in the Markdown card.

When creating a show, enter a city and attendance or press `r` to randomize
both; entering `r` at the attendance prompt after typing a city randomizes only
the attendance. Venues span the US, Canada, Europe, and Japan. The location is
stored in the card and listed next to the show name in the card header and the
saved-card listing.

The promo generator gives selected wrestlers distinct voices and uses a generic
style for wrestlers without a dedicated profile. Roster files share the schema
`{"game_id": "sd1", "game": "...", "wrestlers": ["..."]}`.

Each match can store an accompanying screenshot path in the Markdown
(`- Image: "..."`). The card view never renders the image; the Markdown is there
for anyone who wants to open it later. When creating a match, answer `y` at the
screenshot prompt, or use the "Attach/edit a match image" action in the card
menu later, including for completed matches. SmackDown! 1 and 2 use
DuckStation's `~/.local/share/duckstation/screenshots`; SmackDown! Just Bring It
uses PCSX2's `~/.config/PCSX2/snaps/`. Custom PS1/PS2 games use the matching
default, and a custom game can specify its own screenshot directory in BYOG.
The picker lists PNGs whose filename timestamp (`GameTitle yyyy-mm-dd-hh-mm-ss.png`,
mtime fallback) is newer than the moment the app was opened, newest first. A
manual path is also accepted; blank cancels.

Completed match results flash in place; the logos and card header are drawn once
and stay stationary during the animation.

The WWF.com logo remains at top left on shows run by the World Wrestling
Federation (any card from the built-in games, clones of them, or a BYOG
federation named WWF/"World Wrestling Federation"). Federations with any other
name get no corner logo, and their centered show logo is truly centered. The
centered logo follows the show name: SmackDown shows use the SmackDown logo, Raw
shows use the Raw logo, and other shows display no centered show logo.

In the card view, use ↑/↓ (or `j`/`k`) to highlight a promo, press Enter to
expand or collapse it, and use Page Up/Page Down to scroll while the header
stays pinned. Press `q` or Escape to return.

Wrestler choices are listed alphabetically. When recording a result, choose
`1` for manual entry or `2` to auto-simulate the selected match; the card menu
also lets you auto-simulate every remaining match.

The UI uses ANSI colors and true-color terminal output. Install Pillow if you
want the WWF.com and SmackDown! image assets rendered in the terminal; without
it, the app uses text branding instead:

```sh
python3 -m pip install Pillow
```

Run the built-in tests with `python3 -m unittest -v`.