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:

python3 -m lvpwb

Install

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

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:

python3 -m pip install Pillow

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