roulette-game 2.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ # Debian build artifacts
2
+ debian/roulette/
3
+ debian/.debhelper/
4
+ debian/files
5
+ debian/*.substvars
6
+ debian/debhelper-build-stamp
7
+ ../roulette_*.deb
8
+ ../roulette_*.buildinfo
9
+ ../roulette_*.changes
10
+
11
+ # Local build output
12
+ dist/
13
+ *.deb
14
+
15
+ # Python
16
+ __pycache__/
17
+ *.pyc
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 roulette contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,368 @@
1
+ Metadata-Version: 2.4
2
+ Name: roulette-game
3
+ Version: 2.5.1
4
+ Summary: A roulette game for the terminal, with a croupier you can bribe
5
+ Project-URL: Homepage, https://github.com/Henshall/roulette
6
+ Project-URL: Issues, https://github.com/Henshall/roulette/issues
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: casino,cli,game,roulette,terminal
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: MacOS
13
+ Classifier: Operating System :: POSIX :: Linux
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Games/Entertainment
16
+ Requires-Python: >=3.6
17
+ Description-Content-Type: text/markdown
18
+
19
+ # 🎰 roulette
20
+
21
+ **The house has no edge. Your croupier, on the other hand, can be bribed.**
22
+
23
+ <p align="center">
24
+ <img src="https://raw.githubusercontent.com/Henshall/roulette/main/demo/demo.gif" alt="A game of roulette in the terminal: tip the croupier, a near miss on 17, then a rigged straight-up win" width="748">
25
+ </p>
26
+
27
+ A real roulette table in your terminal: a single-zero wheel, the full betting
28
+ layout, and a payout rule that makes every bet worth **exactly zero** on
29
+ average. Start with 100 🪙 and try to break the bank at 1,000.
30
+
31
+ You can't beat a fair wheel. You *can* slip the croupier a few chips to rig
32
+ your losing spins, as long as the pit boss doesn't notice. Go broke and you can
33
+ [**beg**](#-broke) for more, twice. The third time, security walks you out.
34
+
35
+ ```bash
36
+ pipx install roulette-game # Linux or macOS, with Python 3
37
+ brew install henshall/tap/roulette # macOS
38
+ ```
39
+
40
+ Or grab the [`.deb`](#1-debian--ubuntu-package-deb) for Debian and Ubuntu. Then just type `roulette`.
41
+
42
+ ## Play
43
+
44
+ ```bash
45
+ roulette # sit down at the table (interactive)
46
+ roulette --bet 10 --on red # one spin, one bet
47
+ roulette --bet 5 --on 17 # straight up on 17
48
+ roulette --spin # just watch the wheel spin, no bets
49
+ roulette --table # the layout and every payout
50
+ roulette --stats # bankroll, record, recent numbers
51
+ ```
52
+
53
+ At the table, type a target and a chip count in either order — `red 10` or
54
+ `10 red`, `2 90` or `90 2` (there's no pocket 90, so that's 90 chips on 2) —
55
+ then press **Enter** to spin. When both readings are legal, like `5 17`, it
56
+ asks you to say `5 on 17` or `17 on 5`. Enter with no bets is a free spin
57
+ (just watch, no chips move); `rebet` puts your last bets back on the table.
58
+ `bets`, `undo`, `clear`, `tip`, `swap_table`, `pray`, `table`, `history`,
59
+ `stats`, `beg`, `help` and `quit` do what they say, and a typo like `spinn`
60
+ gets a "did you mean `spin`?".
61
+
62
+ Spins too slow? Press **Enter** during a spin to skip to the result, or type
63
+ `fast` for quicker spins (it's remembered between games; `fast` again turns
64
+ it off). The full command list shows on your first game; after that the table
65
+ just reminds you that `help` exists. Long lines wrap to fit your terminal, and
66
+ narrow terminals get a compact felt.
67
+
68
+ | Bet | Example | Pays |
69
+ | --- | --- | --- |
70
+ | Straight | `17` | 35:1 |
71
+ | Split | `17/18`, `17/20` | 17:1 |
72
+ | Street | `7-9` | 11:1 |
73
+ | Corner | `1/2/4/5` | 8:1 |
74
+ | Six line | `1-6` | 5:1 |
75
+ | Dozen / column | `d1` `d2` `d3`, `col1` `col2` `col3` | 2:1 |
76
+ | Even money | `red` `black` `odd` `even` `low` `high` | 1:1 |
77
+ | Zero | `0` (or `green`) | **36:1** |
78
+
79
+ ## ⚖️ Zero edge: the 0 is a ✨ SUPER SPIN
80
+
81
+ On a casino wheel the 0 is how the house wins: every bet pays as if there were
82
+ 36 pockets, but there are 37. Here, landing on **0** is never a dead loss:
83
+
84
+ - bets **on 0** pay **36:1** instead of 35:1, and
85
+ - **every other bet rides a SUPER SPIN** — the table lights up, the zero
86
+ vanishes, and the wheel re-spins on 1–36 only to settle them.
87
+
88
+ So a bet on *k* of the numbers 1–36 wins with probability exactly *k*/36 at
89
+ the standard 36/*k* − 1 payout, and a bet on 0 wins 1/37 of the time at 36:1.
90
+ **Every bet has an expected value of exactly zero** — `--stats` shows your
91
+ realized return alongside it. (Streaks are tracked for bragging rights but pay
92
+ no bonus, which would tip the odds.)
93
+
94
+ ## 🏦 Break the bank (how you win)
95
+
96
+ Every run starts with **100 🪙**. Reach **1,000 🪙** and you **break the bank**:
97
+ fireworks, a victory screen, and the win is recorded (`--stats` shows banks
98
+ broken and your fastest run). Then the house restocks and run #2 begins with
99
+ 100 🪙 and a new croupier. Go broke and you can beg, but every beg goes on the
100
+ run's record.
101
+
102
+ On a fair table your chance of breaking the bank is exactly **10%** (100 ÷
103
+ 1,000), *whatever* strategy you use. To do better, you need a friend on the
104
+ inside…
105
+
106
+ ## 🎩 Your croupier (and accomplice)
107
+
108
+ Each run you're dealt a croupier from a roster of very fancy people — Gaston,
109
+ Céleste, Lorenzo, Valentina, Maximilian, Anastasia, Reginald, Penelope,
110
+ Thaddeus, Octavia, Dmitri, Séraphine, Astrid, Rodrigo and more (21 in all) — each with their own language to swear in. They
111
+ have opinions about your bets, your wins and (especially) your losses.
112
+
113
+ **They can also be bribed.** Croupiers remember who tipped *recently*. `tip 2`
114
+ at the table (or `roulette --tip 2`) buys luck, shown in your prompt as `🍀 +5%`:
115
+
116
+ - **Every chip you tip is `🍀 +2.5%` luck**, up to **+30%** (12 chips). Luck is the
117
+ chance the croupier rigs a losing spin your way. When they do, the ball
118
+ simply lands on your bet. No cut, no catch, except…
119
+ - **Luck fades a little every spin.** A tip loses a tenth of its strength per
120
+ betting spin and is gone after 10: tip 4 and you'll see +10%, +9%, +8%… down
121
+ to +0%. Free spins (no bet) don't count. What you see is exactly what you
122
+ have; past +30% your tips are just gifts.
123
+ - **The pit boss is watching.** The bigger the rigged win, the likelier they
124
+ spot it (1% per 3 🪙 won). Get caught and your bets are seized, your recent
125
+ tips are wasted, and an **honest** croupier takes over. **Every bust doubles
126
+ the pit boss's suspicion for the rest of the run** (×2, ×4, ×8…), whichever
127
+ table you're at. They know your face now.
128
+ Bribing your croupier while betting tiny amounts makes them nervous, and
129
+ they'll tell you so: small bets mean long runs, and long runs mean busts.
130
+ - **Want someone else?** `swap_table` (or `roulette --swap-table`) moves you to
131
+ another table with a different croupier. Your luck starts over at `🍀 +0%`.
132
+ Right after a bust, the pit boss won't let you move for 5 spins.
133
+ - **Tip `0` and your luck goes down** — each zero tip is `🍀 -2.5%`. With negative
134
+ luck, an offended croupier spoils that share of your *winning* spins ("Oops.
135
+ My hand slipped."). It fades over 10 spins like any tip, or tip for real to
136
+ make amends (1 🪙 cancels one zero tip).
137
+
138
+ How much it helps, measured over 10,000 simulated runs each (betting on red,
139
+ `swap_table` after each bust):
140
+
141
+ | How you tip | Chance to break the bank |
142
+ | --- | --- |
143
+ | Never | 10% |
144
+ | 1 🪙 every spin, betting 10s | ~5% (the tips cost more than the help) |
145
+ | **1 🪙 every spin, betting 25s** | **~30%** |
146
+ | 2 🪙 every spin, betting 25s | ~30% (the best we've found) |
147
+ | 3 🪙 every spin, betting 25s | ~22% |
148
+ | Keep +30%, betting 50s | ~30% |
149
+
150
+ Those odds are for a single bankroll. With the two bailouts begging allows,
151
+ your chance of winning a whole game is roughly 28% without tipping and about
152
+ 50% if you tip steadily and bet 25s.
153
+
154
+ The wheel itself still has **no house edge**. You're the one cheating.
155
+
156
+ Other antics (all cosmetic):
157
+
158
+ - **Your croupier talks.** Straight-up on 17 is "romantic", red is "the beige
159
+ cardigan of bets", and going all in makes them slide the tissues closer.
160
+ - **Martingale detector.** Double your bet after a loss a few times in a row
161
+ and the croupier calls it out, with the pit boss bringing popcorn by double #4.
162
+ - **The ball misbehaves.** About once in 200 spins it escapes — into a martini,
163
+ under table six, or toward the exit — before the croupier re-throws it.
164
+ - **Fireworks.** Hit a straight-up number (or break the bank) for a tiny ASCII
165
+ show. 🎆
166
+ - **Near misses.** When the ball lands one pocket away from your number on the
167
+ wheel, the croupier takes it personally. On your behalf. Mostly.
168
+ - **Pattern spotting.** Streaks of one colour, alternating colours and repeat
169
+ numbers all get noticed, and so does betting that a colour is "due".
170
+ - **Meanwhile…** About once every 50 spins, something happens elsewhere in the
171
+ casino. There are 20 of these, and you'll see every one before any repeats.
172
+ - **Leaving.** `quit` gets a send-off that depends on how your night went, and
173
+ on whether your croupier misses your bribes.
174
+ - **Pray.** `pray` at the table (or `roulette --pray`) asks the roulette gods
175
+ for help. They have opinions, not powers, and they know whether you've been
176
+ tipping, whether you're broke, and whether you're one spin from glory. Pray
177
+ too many times without betting and they put you on mute.
178
+
179
+ ## 🙏 Broke?
180
+
181
+ Your bankroll (100 🪙 to start) lives in `~/.roulette/state.json` and is shared
182
+ by every mode. The only way to earn chips back is to **beg**:
183
+
184
+ ```bash
185
+ roulette --beg
186
+ ```
187
+
188
+ Beg while **broke** and the house grudgingly spots you 100 🪙, with a
189
+ sassier line the second time and a running count of your bailouts this run
190
+ (`stats` also tallies how many times you've gone broke across all runs). Beg
191
+ with **money in hand** and you just get mocked for it. `roulette --reset` wipes everything back to 100.
192
+
193
+ **Three strikes.** The house only bails you out **twice per run**. Beg a
194
+ **third** time and security throws you out of the casino (one of ten
195
+ different scenes, picked at random) — **game over**. The game then starts
196
+ over with a fresh run: 100 🪙, a new croupier, and a clean beg count. Your
197
+ lifetime stats are kept, including how many times you've been kicked out.
198
+ Begging while you still have chips is just mocked; it doesn't count.
199
+
200
+ ## 🖥️ Command wheel (`--command` / `--russian`)
201
+
202
+ The original game is still here: a reel of **harmless, read-only shell
203
+ commands** scrolls past a pointer, slows to a stop, and the one it lands on
204
+ runs.
205
+
206
+ ```bash
207
+ roulette --command # spin and run the winning command
208
+ roulette --command --dry-run # spin, but don't run anything
209
+ roulette --list # show every command on the wheel
210
+ roulette --russian # command wheel + the russian slot (below)
211
+ ```
212
+
213
+ Every command on that wheel is read-only and non-destructive (listing files,
214
+ showing the date, reporting disk usage, memory, processes, and so on). It works
215
+ on **Linux and macOS** — a shared portable set plus platform-specific commands
216
+ (`/proc`, `free`, `lscpu` on Linux; `sysctl`, `vm_stat`, `sw_vers` on macOS).
217
+
218
+ You can bet on it too — every command is a colored pocket:
219
+
220
+ ```bash
221
+ roulette --command --bet 10 --on red # even money
222
+ roulette --command --bet 10 --on green # land on a "loser" command
223
+ roulette --command --bet 20 --on jackpot # land on a marquee pocket
224
+ ```
225
+
226
+ The green "loser" commands are the house pockets — but in keeping with the
227
+ zero-edge table, a red/black bet that lands on one isn't lost: you watch the
228
+ fake self-destruct, then get a **second-chance super spin**.
229
+
230
+ ### ✨ Super spins
231
+
232
+ The command wheel also has **5 "super spin" wildcard pockets** (magenta). Land
233
+ on one and it runs a high-entropy command, turns that **output into red or
234
+ black** (by the parity of the number it produces), **lights up the wheel**, and
235
+ declares that color the winner, settling any red/black bet.
236
+
237
+ ### 💀 Russian roulette (opt-in)
238
+
239
+ `roulette --russian` adds an extra slot to the command wheel. If the spin lands
240
+ on it, **every file and folder in the current directory is deleted**.
241
+
242
+ Guardrails, because random file deletion is no joke:
243
+
244
+ - **Opt-in only.** Without `--russian`, nothing can ever be deleted.
245
+ - **Recoverable.** Everything is moved to the **trash** (`gio trash`, restorable
246
+ from your file manager), not wiped with `rm`. If no desktop trash is
247
+ available it falls back to `~/.local/share/roulette-trash/<timestamp>/`.
248
+ - **Confirmed.** When it lands on the skull it lists every item and makes you
249
+ type `bang` before anything is deleted. It also refuses to delete when run
250
+ non-interactively (e.g. in a pipe or script).
251
+
252
+ Preview the odds without risk: `roulette --russian --dry-run`.
253
+
254
+ ## All options
255
+
256
+ | Option | Description |
257
+ | --- | --- |
258
+ | `--spin` | Spin the real wheel once, just to watch (no bets, nothing saved) |
259
+ | `--command` | Spin the wheel of harmless commands instead of the table (`--commands` works too) |
260
+ | `--russian` | Command wheel plus the russian roulette slot |
261
+ | `--table` | Show the betting layout and payouts |
262
+ | `--bet CHIPS` | Wager on a single spin |
263
+ | `--on TARGET` | What to bet on (default `red`) |
264
+ | `-n`, `--dry-run` | Spin, but move no chips / run nothing |
265
+ | `-p`, `--pick`, `-f`, `--fast` | Skip the animations |
266
+ | `-l`, `--list` | List every command on the command wheel |
267
+ | `--keep-wheel` | Command mode: keep the reel on screen after it lands |
268
+ | `--timeout SECS` | Command mode: time the winning command may run (default 15) |
269
+ | `--tip CHIPS` | Tip the croupier — recent tips get losing spins rigged your way |
270
+ | `--swap-table` | Move to another table with a new croupier (luck resets to 0) |
271
+ | `--pray` | Pray to the roulette gods (no effect on the odds) |
272
+ | `--beg` / `--stats` / `--reset` | Bankroll management |
273
+ | `--seed N` | Reproducible spin |
274
+ | `--no-color` | Disable ANSI colors (also honors `NO_COLOR`) |
275
+ | `-V`, `--version` | Print version |
276
+
277
+ ## Install
278
+
279
+ Four ways: the prebuilt **`.deb`** (Debian/Ubuntu), **pipx** (any Linux or
280
+ macOS), **Homebrew** (macOS), or **from source**. roulette is a single Python 3 script (3.6 or newer)
281
+ with no third-party dependencies, just `python3` and `bash`, which ship with
282
+ every Linux distro and with Apple's Command Line Tools on macOS. Every change is
283
+ tested on both Linux and macOS.
284
+
285
+ ### 1. Debian / Ubuntu package (`.deb`)
286
+
287
+ Download the `.deb` from the
288
+ [latest release](https://github.com/Henshall/roulette/releases/latest) and
289
+ install it — apt pulls in `python3`/`bash` automatically:
290
+
291
+ ```bash
292
+ wget https://github.com/Henshall/roulette/releases/download/v2.5.1/roulette_2.5.1_all.deb
293
+ sudo apt install ./roulette_2.5.1_all.deb
294
+ ```
295
+
296
+ Remove it with `sudo apt remove roulette`.
297
+
298
+ <details>
299
+ <summary>Build the <code>.deb</code> yourself</summary>
300
+
301
+ Only `dpkg-deb` is needed (already on every Debian system):
302
+
303
+ ```bash
304
+ ./build-deb.sh # produces dist/roulette_2.5.1_all.deb
305
+ sudo apt install ./dist/roulette_2.5.1_all.deb
306
+ ```
307
+
308
+ Or with the full Debian toolchain:
309
+ `sudo apt-get install -y devscripts debhelper && make deb` (produces
310
+ `../roulette_2.5.1_all.deb`).
311
+ </details>
312
+
313
+ ### 2. Any Linux or macOS (pipx)
314
+
315
+ ```bash
316
+ pipx install roulette-game
317
+ ```
318
+
319
+ Installs the `roulette` command into its own environment. Upgrade with
320
+ `pipx upgrade roulette-game`, remove with `pipx uninstall roulette-game`.
321
+ (Plain `pip install --user roulette-game` works too.) The man page is
322
+ only included in the `.deb`, Homebrew and from-source installs.
323
+
324
+ ### 3. macOS (Homebrew)
325
+
326
+ ```bash
327
+ brew install henshall/tap/roulette
328
+ ```
329
+
330
+ Upgrade with `brew upgrade roulette`, remove with `brew uninstall roulette`.
331
+ It runs on the `python3` that comes with Apple's Command Line Tools (Homebrew
332
+ already needs those). Without Homebrew, use the from-source install below.
333
+
334
+ ### 4. From source
335
+
336
+ Works on **Linux and macOS** (the `.deb` above is Debian/Ubuntu only):
337
+
338
+ ```bash
339
+ git clone https://github.com/Henshall/roulette.git
340
+ cd roulette
341
+ sudo make install # installs to /usr/local/bin/roulette (+ man page)
342
+ ```
343
+
344
+ Prefer no sudo? Install into your home directory with
345
+ `make install PREFIX=~/.local` (then make sure `~/.local/bin` is on your `PATH`).
346
+ Or skip installing and just run it in place: `./roulette`.
347
+
348
+ Uninstall with `sudo make uninstall` (or `make uninstall PREFIX=~/.local`).
349
+
350
+ ## How it works
351
+
352
+ `roulette` is a single, dependency-free Python 3 script (standard library only).
353
+ In command mode the winning command is executed with `bash -c`, which allows the wheel's
354
+ commands to use pipes and fallbacks (e.g. `lsb_release -a 2>/dev/null || cat
355
+ /etc/os-release`) and caps noisy output with `| head`. Commands that may be
356
+ missing on a minimal system degrade gracefully.
357
+
358
+ Run `make check` for a quick sanity test that never executes a random command.
359
+
360
+ ## Releases
361
+
362
+ Tagged versions are published on the
363
+ [releases page](https://github.com/Henshall/roulette/releases) with a prebuilt
364
+ `.deb` attached (built with `./build-deb.sh`).
365
+
366
+ ## License
367
+
368
+ MIT — see [LICENSE](LICENSE).