Metadata-Version: 2.1
Name: cursed-2048
Version: 0.1.2
Summary: Curses-based 2048 game
Author-Email: Chip Hollingsworth <cholling@gmail.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# cursed-2048

This is a simple clone of the game [2048](https://en.wikipedia.org/wiki/2048_(video_game)) in Python.  It is designed to run in a console or terminal, and (apart from a dev-only dependency on `pytest`) has no dependencies apart from the Python standard library.  In particular, the [`curses`](https://docs.python.org/3/library/curses.html#module-curses) module is used to create the text display.  This does mean that the program will not work under Windows, though in the future I might add an OS-specific dependency on [`windows-curses`](https://pypi.org/project/windows-curses/) to allow it to work there.

## Installation

If you just want to play the game, you can install it in a virtual environment via `pip install cursed-2048`, or globally via `pipx install cursed-2048` (requires that you already have [`pipx`](https://pipx.pypa.io/latest/index.html) installed.)

For development, you can clone this repository and run `pdm install` to create a virtual environment with an editable install, then `pdm run c2048` to run the version installed in that venv.  This of course requires the [`pdm`](https://pdm-project.org/en/latest/) package manager to be installed already.

Then again, since this program doesn't have any non-standard-library dependencies, you should be able to run it without installing anything.  Just run `python cursed-2048/main.py` or `python -m cursed_2048.main` from the root directory of this repository.  The PDM install is convenient, however, because it automatically adds the `c2048` command.

## Running

Once the game has been installed, you can play by typing `c2048` from the command line.  There is also an optional command line argument, `-d` (or `--difficulty`), which takes an integer between 0 and 100.  This sets the difficulty by determining what percent of new tiles are 2 tiles instead of 4 tiles.  The default is 60% 2-tiles.

## Gameplay

The game is played on a 4 x 4 board.  When the game starts, the board will be empty save for two random cells, which will each be populated with either a 2 or a 4 tile.  Each turn, you play by selecting a direction in which to shift the board.  This "smooshes" all of the tiles toward the edge of the board in that direction, so that no empty cells remain between populated cells.  Additionally, if the smooshing would result in two adjacent cells along the direction of travel containing tiles of the same number, those two will be replaced with one tile having double that number, and your score will increase by that doubled amount.  After the tiles have been smooshed, one random empty cell will be randomly populated with either a 2 or a 4, according to the probability set by the `--difficulty` option.

If the board reaches a state where all cells are populated, and there are no adjacent identical tiles that could be merged, the game is over.

The object of the game is to obtain the 2048 tile.  At this point, you can either call yourself a winner and end the game, or keep going to try to reach the coveted 4096 tile.  Once that has been reached, the game is over and you have won for real.

If you make a mistake at any point, you can hit `u` to undo your last move.  There is, however, only one move's worth of memory, so once you undo a move you cannot undo again until you make another move.

## Contributing

This game was really intended as a solo hobby project to get more practice with `curses` programming, and to implement a fun, fully playable game using only the Python standard library.  While I might decide to add some features to it later, I consider it a completed project.

That said, I welcome bug reports and feature requests, as long as you understand that I am under no obligation to respond to any of them.  Additionally, pull requests are welcome, though I can't say how quickly I'll address them.  Again, this is a solo hobby project.

I do, however, have one strict rule:  **No large language models or AI code assistants may be used in this project.**  This means don't contribute any AI-generated code, don't submit any AI-generated bug reports, don't even ask Copilot for help understanding my code.  Pretend it's 2019 and nobody's heard of Claude.  If the thought of approaching a piece of software without your Big Tech-funded resource hog of a pair programmer fills you with trepidation, why not give real programming a try?  You might like it, and you might learn something!  If you're hopping mad at my strict anti-LLM stance, this project isn't for you, and any complaints may be directed to the nearest brick wall.

And before anyone asks:  yes, local models still count as LLMs.
