4.7 KiB
Correctness and limitations
The engine ports Balatro and Immolate RNG constants, item tables, seed iteration, shops, packs, tags, vouchers, bosses, Soul, Wraith, editions, stickers, and standard cards. Tests cover deterministic behavior, pool validity, serial/parallel result ordering, filters, and the CLI.
The friendly find-jokers command searches modeled shop draws,
--pack-joker searches Buffoon-pack contents, and --legendary searches Soul
resolutions. Jokers produced by Wraith still require the relevant
advanced JSON clause. The default any-slot shop search
covers the first 16 modeled queue draws.
Shop reference contract
The shop targets the post-1.0.1c pools (1.0.1f reference), with Vampire in
Uncommon and Stuntman in Rare. Rarity keys are rarity{ante}{source}, while
identity and edition keys put the source before the ante. Hash arithmetic
preserves the original operation order; stream state is rounded to 13 decimal
places with ties to even, matching decimal formatting of the binary float.
tests/fixtures/shop_reference.json contains 1,024 externally generated card
identities, from eight seeds over eight antes and sixteen draws each. The
reference is TheSoul commit 780c1c2,
configured as version 10106, Red Deck, White Stake, with unrestricted pools.
tests/reference/shop_oracle.cpp documents how to reproduce the TSV output
against that checkout without executing the Rust implementation. Only display
spellings for Driver's License and Mail-In Rebate are normalized in the fixture.
The regression covers positive Blueprint results and rejects the old false hit
at seed 11111125, ante 2, queue card 4 (Castle).
Search and inspection apply Magic, Nebula, and Zodiac starting vouchers. However, each clause is an independent query: there is no chronological purchase, ownership, deck-enhancement, or unlock-state simulation. Conditional jokers remain in the unrestricted pools, and matching several clauses does not prove they are all obtainable along one gameplay route. This policy matches the fixture's explicit settings, not every online analyzer configuration.
Queue positions do not uniquely identify shop visits. Later visits and rerolls
both consume the same ante queue. --max-rerolls is a first-visit cutoff with
two cards per shop, not a budget for all visits; it rejects Zodiac Deck.
Overstock purchases, tags, and other gameplay changes require a route-aware
simulator. Edition voucher effects after purchases are not modeled either.
Shared RNG and pools also affect Buffoon/Wraith contents. Existing Soul and spectral-pack regression fixtures are checked alongside the shop fixtures; passing them is not a claim that every pack on every seed is externally proven.
The regression suite establishes deterministic self-consistency and published-pool sanity. It is not a complete external, bit-for-bit oracle for every Balatro version. Do not treat undocumented game-version behavior as verified parity, and verify important results in the relevant game version.
Deterministic RNG and spectral retries
The engine's random operation is deterministic despite its conventional
name. It never reads operating-system entropy or thread-local random state.
Each value comes from the run seed plus a named stream key, and repeated calls
advance only that key's cached state. Independent instances given the same seed
and the same ordered operations therefore produce identical results, including
when seeds are evaluated on different Rayon workers.
Spectral packs first use the keyed soul_Spectral{ante} stream for the special
The Soul and Black Hole checks. An ordinary spectral draw then selects from 18
slots: 16 cards and two retry sentinels. A sentinel or an already-selected card
uses deterministic _resample2, _resample3, and later keys. Retry traversal
is capped at 80 attempts, matching the safety budget used by other locked item
pools. If that bound is exhausted, the engine picks the first unlocked ordinary
spectral in table order. The fallback is deterministic; it exists to guarantee
that one pathological seed cannot freeze progress or prevent Ctrl-C handling.
The retry cap is a safety policy, not evidence of full game parity. Seeds that reach it should be retained as explicit regressions and compared with the chosen external version before stronger parity claims are made.
The planned weighted-ranking mode has additional state and obtainability
requirements. Its current design and unresolved legality work are tracked in
TASK.md; those planned capabilities are not yet CLI features.
See the acceptance record for tested workflows and the search guide for user-facing semantics.