Metadata-Version: 2.4
Name: arcade-games
Version: 3.1.0
Summary: A terminal arcade collection: 18 games to play while you wait, including Wordplay and a virtual-chip casino
Author: keerti
License-Expression: MIT
Project-URL: Homepage, https://github.com/kirti34n/arcade-games
Project-URL: Repository, https://github.com/kirti34n/arcade-games
Keywords: games,arcade,terminal,cli,snake,tetris,2048,curses,shooter,pong,flappy,minesweeper,pacman,connect4,sokoban,reversi,frogger,multiplayer,wordplay,blackjack,roulette,slots,casino
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Games/Entertainment :: Arcade
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: windows-curses; platform_system == "Windows"
Dynamic: license-file

<div align="center">

# arcade

**Eighteen terminal games, and a friend to beat.**

One command. No setup. Runs on Linux, macOS, WSL, and Windows.

<p>
<img src="https://img.shields.io/badge/python-3.8+-3776AB.svg?logo=python&logoColor=white" alt="Python 3.8+">
<img src="https://img.shields.io/badge/games-18-3fb950.svg" alt="18 games">
<img src="https://img.shields.io/badge/multiplayer-LAN-8884ff.svg" alt="LAN multiplayer">
<img src="https://img.shields.io/badge/license-MIT-eab308.svg" alt="MIT">
</p>

<br>

<table>
<tr>
<td align="center"><img src="assets/pacman.gif" width="340" alt="Pac-Man"></td>
<td align="center"><img src="assets/tetris.gif" width="340" alt="Tetris"></td>
</tr>
</table>

</div>

<br>

> **The hardest part of vibe coding is the waiting.** Your agents are off doing
> their thing, you have nothing to do, and the office laptop is locked down.
> So run a game in the terminal you already have open, and pull in a coworker
> over the LAN.

<br>

## Quick start

```bash
pip install arcade-games
```

```bash
arcade                 # open the menu
arcade snake           # jump straight into a game
arcade mp              # play a friend over the network
arcade list            # every game, with your high scores
```

That is the whole story. The games use Python's built-in `curses`; on Windows
the install adds `windows-curses` for you. Nothing else to install.

`play` still works too, as an alias for `arcade`, kept around for anyone
already used to it.

<br>

## Play with a friend

Three games go two-player over a local network, one hosts and the other joins
by IP. No account, no server, no configuration.

<div align="center">
<img src="assets/multiplayer-pong.gif" width="660" alt="Networked Pong, host and guest views side by side">
<br>
<sub>The same Pong rally, from each player's screen</sub>
</div>

```bash
arcade mp            # or press M in the menu
```

Pick **Reversi**, **Connect Four**, or **Pong**, then **Host** or **Join**. The
host reads out an address like `192.168.1.5 : 8765`; the other player types it
in. Reversi and Connect Four are turn-based and rock-solid at any latency; Pong
is real-time and best on the same Wi-Fi.

<br>

## The games

<h3>Arcade</h3>
<table>
<tr>
<td width="50%" align="center"><img src="assets/snake.gif" width="380" alt="Snake"><br><b>Snake</b> &nbsp;·&nbsp; <code>arcade snake</code><br><sub>Eat, grow, and don't bite your tail.</sub></td>
<td width="50%" align="center"><img src="assets/pacman.gif" width="380" alt="Pac-Man"><br><b>Pac-Man</b> &nbsp;·&nbsp; <code>arcade pacman</code><br><sub>Clear the dots, dodge four hunting ghosts.</sub></td>
</tr>
<tr>
<td width="50%" align="center"><img src="assets/dino.gif" width="380" alt="Dino Runner"><br><b>Dino Runner</b> &nbsp;·&nbsp; <code>arcade dino</code><br><sub>Jump the cacti, run forever.</sub></td>
<td width="50%" align="center"><img src="assets/breakout.gif" width="380" alt="Breakout"><br><b>Breakout</b> &nbsp;·&nbsp; <code>arcade breakout</code><br><sub>Bounce the ball, break every brick.</sub></td>
</tr>
<tr>
<td width="50%" align="center"><img src="assets/shooter.gif" width="380" alt="Space Shooter"><br><b>Space Shooter</b> &nbsp;·&nbsp; <code>arcade shooter</code><br><sub>Waves, power-ups, and bosses.</sub></td>
<td width="50%" align="center"><img src="assets/flappy.gif" width="380" alt="Flappy Bird"><br><b>Flappy Bird</b> &nbsp;·&nbsp; <code>arcade flappy</code><br><sub>Flap through the gaps.</sub></td>
</tr>
<tr>
<td colspan="2" align="center"><img src="assets/frogger.gif" width="380" alt="Frogger"><br><b>Frogger</b> &nbsp;·&nbsp; <code>arcade frogger</code><br><sub>Cross the traffic and the river to the home bays.</sub></td>
</tr>
</table>

<h3>Puzzle</h3>
<table>
<tr>
<td width="50%" align="center"><img src="assets/tetris.gif" width="380" alt="Tetris"><br><b>Tetris</b> &nbsp;·&nbsp; <code>arcade tetris</code><br><sub>Stack, clear lines, level up. Ghost piece included.</sub></td>
<td width="50%" align="center"><img src="assets/2048.gif" width="380" alt="2048"><br><b>2048</b> &nbsp;·&nbsp; <code>arcade 2048</code><br><sub>Slide and merge to the big tile.</sub></td>
</tr>
<tr>
<td width="50%" align="center"><img src="assets/minesweeper.gif" width="380" alt="Minesweeper"><br><b>Minesweeper</b> &nbsp;·&nbsp; <code>arcade mines</code><br><sub>Read the numbers, flag the mines. Three sizes.</sub></td>
<td width="50%" align="center"><img src="assets/sokoban.gif" width="380" alt="Sokoban"><br><b>Sokoban</b> &nbsp;·&nbsp; <code>arcade sokoban</code><br><sub>Push each box onto a target. Undo freely.</sub></td>
</tr>
</table>

<h3>Head to head <sub>(vs AI or a friend)</sub></h3>
<table>
<tr>
<td width="33%" align="center"><img src="assets/pong.gif" width="330" alt="Pong"><br><b>Pong</b> &nbsp;·&nbsp; <code>arcade pong</code></td>
<td width="33%" align="center"><img src="assets/reversi.gif" width="330" alt="Reversi"><br><b>Reversi</b> &nbsp;·&nbsp; <code>arcade reversi</code></td>
<td width="33%" align="center"><img src="assets/connect4.gif" width="330" alt="Connect Four"><br><b>Connect Four</b> &nbsp;·&nbsp; <code>arcade connect4</code></td>
</tr>
</table>

<h3>Word & casino</h3>
<table>
<tr>
<td width="50%" align="center"><b>Wordplay</b> &nbsp;·&nbsp; <code>arcade wordplay</code> <sub>(also <code>word</code>, <code>wp</code>)</sub><br><sub>One 5-letter word a day. 6 guesses, a keyboard that remembers, and a streak to protect.</sub></td>
<td width="50%" align="center"><b>Blackjack</b> &nbsp;·&nbsp; <code>arcade blackjack</code> <sub>(also <code>bj</code>, <code>21</code>)</sub><br><sub>6-deck shoe, dealer stands on soft 17, blackjack pays 3:2, split up to 3 times.</sub></td>
</tr>
<tr>
<td width="50%" align="center"><b>Roulette</b> &nbsp;·&nbsp; <code>arcade roulette</code><br><sub>The European wheel (single zero, 2.70% house edge). Straight up, splits, dozens, and every even-money bet.</sub></td>
<td width="50%" align="center"><b>Slots</b> &nbsp;·&nbsp; <code>arcade slots</code> <sub>(also <code>slot</code>)</sub><br><sub>3 reels, a real paytable, and a computed payout rate in the 92-96% band.</sub></td>
</tr>
</table>

> **The chips are not real money.** Blackjack, Roulette, and Slots share a
> virtual, in-app points balance (starts at 1000, with a small once-a-day
> top-up if you ever hit zero). There is no purchase, no deposit, no
> cash-out, and no way to turn a chip into anything of real-world value,
> anywhere in this codebase. It is a toy, on purpose.

<br>

## Controls

```
 WASD / Arrows   Move, aim, navigate
 Space           Jump · Hard drop · Launch · Fire · Serve · Place · Reveal
 W               Rotate (Tetris)
 F               Flag a cell (Minesweeper)
 U               Undo (Sokoban)
 R               Reset level (Sokoban) · Retry after game over
 P               Pause
 ? / H           In-game controls
 M               Multiplayer (menu) · T  Theme (menu)
 ESC / Q         Quit (progress is saved)
```

Space Shooter, Pong, and Minesweeper ask for a difficulty. Snake, Dino, and
Flappy speed up as you go; Tetris levels up. Quit any game and it resumes next
time you open it.

Wordplay and the casino games are turn-based and use their own keys instead of
WASD: type letters and press Enter in Wordplay; H)it, S)tand, D)ouble, and
X)split in Blackjack; arrows to pick a bet and F to spin in Roulette; Left/
Right to set your bet and Space to pull the lever in Slots. Press `?` in any
game for the full list.

<br>

## Turn-based mode

For playing a move at a time in a chat or an editor, `arcade cli` runs the
games as plain text, no full-screen UI and no curses required.

<div align="center">
<img src="assets/cli-connect4.gif" width="300" alt="Connect Four in the CLI mode">
</div>

```bash
arcade cli start connect4    # also: snake, 2048, minesweeper
arcade 4                     # drop a disc in column 4
arcade show                  # reprint the board
arcade quit                  # end the game
```

<br>

## Built honestly

A small shared core plus one file per game, with a dependency-free test suite
you can run yourself:

```
arcade_games/
├── game.py         # the Game base class every game subclasses
├── config.py        # save files, high scores, config migration
├── currency.py        # the shared virtual chip balance (casino games only)
├── menu.py               # the curses main menu
├── cli.py                 # the plain-text `arcade cli` front-end
├── net.py                   # LAN multiplayer
├── render.py, theme.py, terminal.py    # drawing, color themes, terminal launch
└── games/
    ├── snake.py, tetris.py, g2048.py, dino.py, breakout.py,
    │   shooter.py, pong.py, flappy.py, minesweeper.py, pacman.py,
    │   sokoban.py, reversi.py, frogger.py, connect4.py,
    │   wordplay.py, blackjack.py, roulette.py, slots.py
```

```bash
python tests/test_games.py     # a headless fuzz, save/load, network, and a
                               # regression test behind every fix
```

Every GIF in this README is rendered straight from the game code, so what you
see is what you get.

<br>

## Contributing

Pull requests welcome. A new game is a subclass of `Game` in its own file
under `arcade_games/games/`, added to `_GAMES` in `arcade_games/registry.py`;
a new level or theme is a few lines. Please run the tests first.

## License

[MIT](LICENSE)
