Gaming Backlog Randomizer With Rules

⭐ Gold Star Project I consider this project complete. Fixes, maintenance and good new ideas are still welcome. About Gold Stars

Choose a game from your backlog using your own rules and weights, with an optional stable-ID mode that keeps seeded draws consistent when you reorder the list.

Current release 1.3.1

Numeric fields reject values outside the finite float range with a normal input error, including JSON integers such as 10**400. Values are never clamped or silently replaced. Wheels and source distributions include the README, changelog, development/testing instructions, license and runnable examples.

Hours, weights and max_hours are checked before preview or draw. Eligible weight totals must also remain finite; ordinary seeded draws keep their existing behavior.

Updates in 1.3.0

Apply a reusable JSON rule object to a CSV or JSON backlog:

backlog-randomizer games.csv --rules rules.json --seed weekend --preview --format json

For example, rules.json can contain {"platforms":["PC"],"owned_only":true,"max_hours":5}. This replaces embedded rules for the primary backlog. A file supplied to --compare keeps its own rules, so you can compare a different configuration. Existing rule validation, stable-ID identities and source/output protections apply.

Every supplied history entry is validated before a preview, draw or output, even when cooldown filtering is off. Entries require string IDs and valid YYYY-MM-DD dates. Additional history metadata is preserved when a new file is written.

Updates in 1.2.2

Preview and draw both reject an eligible pool whose positive finite weights sum beyond the supported finite total, with an instruction to use smaller weights. This prevents false zero probabilities without changing ordinary seeded draws. Dates supplied for --as-of and cooldown history require exact YYYY-MM-DD calendar form across supported Python versions. Stable input identity excludes unknown rule metadata as well as unused game metadata; only rules that affect eligibility enter that identity.

Output recovery in 1.2.1

Recover cleanly when writing a report and its companion file fails.

Reports and history files are prepared together. If an ordinary write fails, the command removes only unchanged files it created, so you can fix the destination and retry. Existing files, source inputs and files changed by another process are preserved. Outputs are UTF-8 with LF endings. This handles ordinary write failures; it does not promise a multi-file transaction through power loss or recall text already read from stdout.

Updates in 1.2.0

Keep a seeded draw consistent when the same backlog is reordered.

Use backlog-randomizer backlog.json --seed weekend --stable-ids --count 2 --format json. Keep IDs attached to the same games when editing or reordering. stable-id-v1 sorts IDs by Unicode code point before the existing Python weighted draw. The same seed, effective metadata/rules and supported runtime reproduce selections despite array reordering. Identity excludes titles and unused metadata; it is an audit aid, not proof of play or a cryptographic random draw. Changes to weights, eligibility or cooldown history may change results. The default input-order-v1 mode retains earlier behavior.

Updates in 1.1.1

Reject non-finite hard duration limits before making a draw.

max_hours must be a finite nonnegative number. Seeded draws are reproducible for the same input ordering, rule values, seed and runtime contract; this patch does not silently change the draw ordering algorithm.

Gaming Backlog Randomizer chooses from a supplied backlog only after applying explicit platform, genre, mood, length, ownership, recent-play, and ID exclusions. Weighted selection is reproducible from a seed, and every rejected game keeps its reasons.

Three-minute start

python -m pip install .
backlog-randomizer examples/backlog.json --seed weekend-26
backlog-randomizer examples/backlog.json --seed weekend-26 --count 2 --format json

Games can carry multiple genres and moods plus a positive selection weight. Rules are optional and conjunctive: a game must satisfy every supplied hard rule before it enters the weighted draw.

The tool does not query storefronts, recommend purchases, infer mood, or guarantee enjoyment. Estimated hours and metadata are supplied by the user. A seed reproduces a draw only for identical input and rules. Requires Python 3.10 or newer.

Part of the Logan Pendragon Forge open-source collection. Licensed under the MIT License.

Version 1.1.0: reviewed improvements

Repair the two-game example and add eligibility previews, CSV input, decision history, cooldowns and pool comparisons.

backlog-randomizer examples/backlog.json --seed weekend --preview --format json

--preview explains eligibility and first-draw probabilities without choosing a game. CSV accepts pipe-separated genres/moods, true/false ownership, numeric hours and weights. Use --history history.json --cooldown-days 7 --as-of 2026-09-07 for explicit dated cooldowns, and --history-output new-history.json to write a new decision log after a draw. Entries record decisions, not proof of play. --compare alternative.json shows how changed rules or weights affect the pool; it does not claim improved recommendations. Original files and existing outputs are protected.