Balance simulator
bjsim plays thousands of rounds and whole runs with scripted bots to measure house edge, the impact of each chaos rule, item value, shop pricing and run length. It lives in its own repository (black-jack-sim); the game never imports it and it never changes the game. Measured results are on the Balance data page.
How it stays honest
- One seam. Only the simulator's
bjsim/adapter.pyimports the game. When the game's API changes, that file is updated and nothing else. - Visible state only. Bots see what a player sees, with two documented exceptions: the cards an information item has just revealed, and rewritten shop prices for pricing experiments.
- No billing. The Chaos AI is always a scripted stand-in; no real model is called.
- Reproducible. Same seed, same results, whatever the number of worker processes. By default it simulates the game's shipped balance values, not your local database.
Running it
Python 3.10+, no extra packages. Run inside black-jack-sim/, next to a game checkout.
| Command | Usage |
|---|---|
career | python -m bjsim career --policy mixed --careers 200 --length 40 [run options] |
check | python -m bjsim check [--bands bands.json] regression gate (exit 1 if out of band) |
edge | python -m bjsim edge [--rules all|none|<name>,...] EV per chaos rule |
items | python -m bjsim items [--rules none,...] [--items ...] EV gain per item use |
runs | python -m bjsim runs [--chaos off|stub|mix|<rule>] [--bet pct25] [--shop never] [--prices game] |
sweep | python -m bjsim sweep --param prices --values game,scaled:3,scaled:5 [run options] |
upgrades | python -m bjsim upgrades [run options] value and payback of every meta upgrade |
Common options: --profile NAME (simulate a balance profile from the game's database), --rounds N, --runs N, --seed N, --jobs N (processes; never changes results), --out FILE (.md or .json).
| Option | Values |
|---|---|
--chaos | off, stub, mix, mix:a+b, modify_card_value-1, modify_card_value+1, reverse_bust, great_crash, odd_even_chaos, suit_power, fragile_bust, tiebreaker_dealer, tiebreaker_player |
--bet | flat10, pct10, pct25, max, pct25_max_with_item |
--shop | never, eager, value |
--prices | game, fixed:<factor>, scaled:<pct> |
--chaos stubis the game's own offline Chaos AI as the balance profile sets it;mixpicks uniformly from all rules.--shop eagerbuys anything useful (keeping a reserve);--shop valuebuys one item when it is worth it at a maximum bet.--prices fixed:<factor>multiplies the game's prices;scaled:<pct>makes peek cost that share of the bankroll and the others proportionally.upgradesmeasures upgrade levels on matched deals, reporting changes in win rate and tokens per run, plus token payback time.careersimulates repeated runs and meta purchases with--policy none|permanent|consumable|mixed,--careers Nand--length N; comma-separated policies can be compared in one report.
Bots
Bots play classic basic strategy without splitting, shifted when a rule moves the bust line, but they do not otherwise adapt to chaos rules. Results under chaos are therefore a "naive player" view: someone who exploits a rule does better.
Regression bands
The simulator keeps a list of key metrics with allowed ranges (bands.json). python -m bjsim check measures them; a value outside its band means a game change moved the balance. When that is intended, the band is re-measured and updated in the same change.
The current report has out-of-band measurements, shown below. The wiki preserves them; updating the simulator's regression bands belongs in its separate repository. The stub metric's label still describes the earlier value-shift-only setup, while the current profile draws a weighted mix including calm rounds.
python -m bjsim check · seed 1 · balance default@b574fce2d1a5 · game 108b5e1 · simulator d11d84e · Balance bands
| Metric | Sample | Measured | Allowed band | In band |
|---|---|---|---|---|
| EV, no chaos | 50000 rounds | +0.0000 | [-0.020, +0.020] | yes |
| EV, offline stub chaos (values -1) | 50000 rounds | -0.0239 | [-0.120, -0.075] | no |
| EV, uniform mix of all rules | 50000 rounds | -0.0117 | [-0.015, +0.025] | yes |
| EV with one peek per hand | 50000 rounds | +0.1309 | [+0.110, +0.150] | yes |
| Win rate, no chaos, bet 25% | 2000 runs | +0.2570 | [+0.165, +0.235] | no |
| Win rate, offline stub chaos, bet 25% | 2000 runs | +0.2340 | [+0.075, +0.130] | no |
How the wiki uses it
On every python -m wiki sync the wiki runs the simulator from a clean checkout of its main against a clean checkout of the game's main, and stores the results as facts. Results are reused while neither commit changes, so the numbers on this wiki always say which game and simulator commits they come from.