• 🚀 My first OOP Python project, as well as my first GitHub repository! (ignoring config repo)
• 🎮 Singleplayer turn-based card game with AI opponents.
• 📟 Runs within the terminal, is lightweight in code, and uses a CLI combined with a TUI.
• 🐍 Made with Python (version 3.12).

Note

Despite the name, UNO.py isn't actually a single file, but I've titled it this since the very beginning of its development, and don't feel the need to change it.

How to run?

Enter the following command in your terminal, in order to clone the repository and run UNO.py:

curl -fsSL "https://raw.githubusercontent.com/theSanguss/UNO.py/main/install.sh" | bash

To rerun UNO.py, just open the folder of the repository in the terminal and enter the following command:

python main.py

If you want a portable and easy-to-run version of the game, just download and run one of the two Windows EXE files available in this repository – UNO.py.exe or UNO-WOE.py.exe (WOE stands for Windows-Optimised Edition). While the former has been created using the same code you see in this repository, the latter uses a slightly different version of cli_tools.py, making use of the keyboard and mouse libraries as a replacement to PyAutoGUI, as these two libraries are significantly more lightweight, reducing the time it takes to load UNO.py. Click here to see the code that was modified.

If you are not a Windows user, but still wish to get an executable file version of UNO.py, you can use PyInstaller to make it yourself. For more info on how to use this tool to make an UNO.py executable, refer to the last question in the FAQ section.

Note

This program has been tested to work on MacOS and Linux, but certain issues like the the automatic toggling of fullscreen-mode still persist. So for the time being, users on systems hostile to PyAutoGUI (one example being Linux users using Wayland instead of X11) will have to make do with toggling fullscreen-mode manually.

Please do file an issue if you encounter anything unexpected or problematic, especially if you're not a Windows user.

How to operate?

This is a CLI-based application, so entering in inputs as you normally would in a terminal is pretty much all you need to do.

Most inputs are intuitive and self-explanatory, and those that aren't are specified and detailed in-game.

Warning

If your system has a custom keybind for toggling fullscreen mode, that isn't F11 (or Control+Command+F if you're using MacOS), make sure to revert it back to the default keybind when running this program, or at least modify the toggleFullscreen function in cli_tools.py. Unexpected things may occur if the F11 key/Control+Command+F key combination is modified to serve a different purpose.

FAQs :

1. Are the rules the same as normal UNO?

Yes, except for two things - viewing the cards of the player you challenge (isn't necessary here, cuz this ain't IRL), and the score system (cuz literally no one cares about that). Stacking, 'jump-in's and other such house rules haven't been implemented, but if you wish to contribute to this project, I highly suggest starting with adding the functionality in the game loop for some of these to be available as custom rules during setup.

2. Does this support local multiplayer?

No. It wouldn't be all too hard to implement by just adding multiple Player objects, but from a gameplay standpoint, it would be annoying to manange. Feel free to fork this project and try implementing a Local Multiplayer system you think would work well. Again, contributions are welcome.

3. How does the UI work?

This project makes extensive use of the wonderful Rich library for its UI, so much so that it can serve as a showcase for several of Rich's versatile components and how they can be meshed together! It is still fundamentally text-based though, so maybe take a look at some of the tips below for better UI rendering:

Tip

For optimal results, ensure that the terminal you're using isn't overly customised and doesn't make use of custom fonts, especially if it's not Windows PowerShell. Background themes as well as custom text colouring have no impact on the UI.

Windows Powershell's default font size (12pt), or anything lower, is enough to get the proper UI experience, as it eliminates the need to ever scroll the UI on a standard display (16:9). If you are not using Windows Powershell, or have increased the font size, you may have to reduce it. However, you might only have to do this to make the setup UI fit in one screen, so another thing you can do is to replace line 30 of the file uno.py with self.setup(show_instructions = False), so that the long instructions list will be hidden.

4. How does the AI in this work?

The AI players in this are biased by a numerical property called their 'intellect'. I say 'biased', as a large part of their logic is based on random chance, and intellect mostly serves to vary this chance. This intellect comes in use for the AI in nearly all aspects of play. In some cases, AIs with the lowest intellect are barred or dissuaded from making intelligent decisions, while those with the highest intellect can perform certain advanced strategies that lower intellect AIs cannot. Looking at the code in player.py should give you a good idea of exactly how the AI players function and what the different tactics they can employ are.

5. How can I convert this into an executable file myself using PyInstaller?

If you're not already familiar with PyInstaller, it's a CLI tool that helps bundle Python scripts, modules and libraries into executable files. If you don't already have PyInstaller, run the following command to install it (make sure you have Python installed so that pip is recognised by your system):

pip install pyinstaller

Then, after cloning this repository and opening UNO.py's folder in the terminal, run the command below to generate the executable (make sure to replace [insert filepath here] with the filepath to Python's site-packages folder on your system):

pyinstaller --onefile --name="UNO.py" --icon="UNO_icon_new.ico" --add-data "[insert filepath here]\site-packages\pyfiglet\fonts;.\pyfiglet\fonts" main.py

After this, two new folders will be generated inside UNO.py - build and dist. build can be ignored, but it is within dist that the executable will be stored. The --onefile parameter in the above command creates a standalone executable file, which can be moved to any location in your system.

If you don't want the libraries to be bundled with the executable, and would prefer to run the executable from within the dist directory, rather than having it as a portable standalone, you can remove the --onefile parameter. This will also improve the executable's startup speed by some amount.

Note

The --add-data parameter is mandatory to include, as Pyfiglet, a font library used with this project, requires a filepath to be specified for it to be able to access its font files.

.ico files are not supported as file icons on systems other than Windows, so you'll have to convert UNO-icon-new.ico to a different file format (like .icns for MacOS and .png for Linux) in order to use it in the --icon parameter.

Warning

This command hasn't been tested on other systems, and there is no guarantee that it will work for all users. However, this is the easiest method I know of which also resolves all issues with Pyfiglet, and has worked flawlessly for me, which is why I recommend using it.

6. What code was modified in UNO-WOE.py.exe, aside from the new imports?

As you can see, this code is incredibly simple as compared to what is used in the standard version of UNO.py, so it's rather unfortunate that these libs aren't well-compatible with non-Windows systems.

(￣ o ￣) . z Z