Dice game

author: Jakub Łabuz (jakseluz)

Project focuses on a Dice game implementation using the Python library Gymnasium. This enables the possibility to be used for reinforcement learning projects - if properly adjusted (reward values etc. - check gymnasium docs). Each player is identified by an id number in the observation space, so it is not problem that I used gymnasium for a multiplayer game.

In fact, I treat the game GUI as an addition to the module mentioned above, remembering that the way of presenting the game is defined as free.

Dice rules (look for the section with the most default variant):

• in Polish
• in English

🚀 Modules

Module	Status	Description
envs/dice (Game Logic)	🟢 Feature-Complete (0.9.9)	All game rules, state management, and mechanics are implemented.
backend/server (Backend)	🟡 Basic Implementation	Core networking functions are up. #TODO: Essential reliability features (e.g. connection monitoring)
graphics/client (GUI / Frontend)	🔴 Prototype / Mockup	The visual layout and design are implemented, but elements are not yet clickable or bound to the game logic.
analytics	⚪ Roadmap	Future module designed to train agents etc. - not planned at the moment, but could be.

Requirements

• Python
  details inside the configuration file (pyproject.toml)

Usage

Preparation

1. Clone the repository:

   git clone https://github.com/jakseluz/Dice.git
   cd Dice

2. Install project and its dependencies with:

   pip install -e .

   (in the project root directory, which is Dice/ by default)

a) researcher usage

3. Check the gymnasium docs introducing to environments usage

4. You can import the Dice environment into your project by the code:

   import gymnasium as gym
   import dice # not necessarily needed, but it may not install properly in your gym envs, so it is better to keep it
   env = gym.make(id="Dice-v0", num_players=4)
   # then use my env as you want

5. Simple example available here:
   ./notebooks/main.ipynb.

b) player usage

Note: GUI client is not finished (#TODO) - the graphical part, in fact, is - but it lacks the clickability (I do not want to vibe code this logic and ruin the fun)

3. To run the game server:

   python -m dice.backend.server

   with two optional parameters:

   • the first indicates the port number (default: 8000)
   • the second is number of players (e.g. 2-4, but should work with more; default: 4)

4. Run {number of players} terminals with the command:

   python -m dice.graphics.client

   with an optional parameter:

   • the port number (by default: 8000, but you need to provide the same as the above - in the server)

5. Play the game, knowing the rules.

Decisions and functionalities

• I selected tools which are helpful in creating a fully functional, simple game.
• The complexity of tools is adapted to the project size.
• I thought it would be good to make the game useful in some sense, other than just entertainment, so I used Gymnasium (formerly OpenAI Gym) and developed a full-fledged environment for agent training. That is also why I made it in the desktop form, not web or mobile.

Modules are quite separate from each other:

• dice.py (env module) can be used as any other gymnasium environment, so it is not dependent of the server or the GUI.
• server.py can be used together with curl command or any other tool using REST API. Its implementation is not complete - it can be improved by adding e.g. heartbeat mechanism to check players availability etc. Notwithstanding the main part in the main scenario should work.
• GUI does not require other modules. It can work via network, not knowing them.

Used tools

1. GIT + GitHub - to keep the clean version history, branches etc. (quite obvious) - repo currently private (published on May 20, 2026)

2. Python with additional libraries:

   gymnasium - to pack the game logic into an environment that can be used for agents training

   numpy - for better calculation tools, types etc. (library quite obvious for Python users)

   fastapi - it is fast to create own API in the server module

   requests - for easier API requests etc.

   uvicorn - for the server engine - it is really easy to run the server using it

   arcade - GUI library, uses OpenGL, leverages the GPU (good to know), faster and maybe easier than pygame

3. Python tools for maintaining the clean code and respecting types:

   • Ruff - formatter and linter
   • mypy - static type checker
   • Pydantic - for payload data validation

Used resources

• readme dice image
• gitignore
• dice in-game images
• point tables in arcade - LLM generated (I think that such things are not especially interesting to write manually)
• LLMs for debugging and looking for inconsistencies, as well as for fast research etc.

---

For questions or contributions, please open an issue or submit a pull request!