{"id":24165966,"url":"https://github.com/leoleman555/board_game_duckquest","last_synced_at":"2026-05-06T09:39:19.032Z","repository":{"id":270733849,"uuid":"901871502","full_name":"LeoLeman555/Board_Game_DuckQuest","owner":"LeoLeman555","description":"An educational game on the Raspberry Pi that teaches children about graph algorithms.","archived":false,"fork":false,"pushed_at":"2025-02-18T11:22:22.000Z","size":13240,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-18T12:29:10.999Z","etag":null,"topics":["board-game","duck","for-children","fun","github","graphs","python","raspberry-pi","shortest-path-algorithm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LeoLeman555.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-11T13:24:30.000Z","updated_at":"2025-02-18T11:22:25.000Z","dependencies_parsed_at":"2025-01-02T18:39:31.732Z","dependency_job_id":"03c7b91b-c1b3-4d11-9648-325fd1e860ec","html_url":"https://github.com/LeoLeman555/Board_Game_DuckQuest","commit_stats":null,"previous_names":["leoleman555/board_game_duckquest"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoLeman555%2FBoard_Game_DuckQuest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoLeman555%2FBoard_Game_DuckQuest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoLeman555%2FBoard_Game_DuckQuest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoLeman555%2FBoard_Game_DuckQuest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeoLeman555","download_url":"https://codeload.github.com/LeoLeman555/Board_Game_DuckQuest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241476435,"owners_count":19968916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["board-game","duck","for-children","fun","github","graphs","python","raspberry-pi","shortest-path-algorithm"],"created_at":"2025-01-12T20:13:26.718Z","updated_at":"2026-05-06T09:39:19.027Z","avatar_url":"https://github.com/LeoLeman555.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Duck Quest - Board Game\n\n![Logo](./duckquest/assets/images/logo.png)\n\n[![Version](https://img.shields.io/github/v/release/LeoLeman555/Board_Game_DuckQuest)](https://github.com/LeoLeman555/Board_Game_DuckQuest/releases)\n[![License](https://img.shields.io/github/license/LeoLeman555/Board_Game_DuckQuest)](LICENSE)\n[![Status](https://img.shields.io/badge/status-prototype--stable-brightgreen)]()\n![Code style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)\n[![CI Tests](https://github.com/LeoLeman555/Board_Game_DuckQuest/actions/workflows/tests.yml/badge.svg)](https://github.com/LeoLeman555/Board_Game_DuckQuest/actions/workflows/tests.yml)\n\nDuckQuest is an educational game created within a school project. It is aimed at young children and allows them to learn to think like an algorithm in order to understand how these work. We achieve this by asking them to find the shortest route through a graph, just as a Dijkstra algorithm would.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Hardware Requirements](#hardware-requirements)\n- [Execution Modes](#execution-modes)\n- [Installation](#installation)\n- [Run](#run)\n- [Project Structure](#project-structure)\n- [Logging](#logging)\n- [Tests](#tests)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Overview\n\n### Game Concept\nIn DuckQuest, the graph is represented as a network of routes around a pond. Children guide a duck along the shortest path using physical buttons for graph nodes and LED strips for graph edges. A Raspberry Pi powers and controls the setup. \n\n### Example Visualization\nThe following graph represents the playground used in DuckQuest.\n\nEach node is a possible location for the duck, and each edge represents a path with a specific weight, visualized by its color.\n\nThe goal is to help the duck travel from A1 (start) to Q2 (goal) by choosing the shortest path — just like Dijkstra's algorithm would do.\n\n![Sample graph](./duckquest/assets/images/sample_graph.png)\n\nEdge color legend:\n| Weight |    Color   | Meaning                    |\n|--------|------------|----------------------------|\n|    1   |    Green   | Fastest, most optimal path |\n|    2   | Bright-Green | Still efficient            |\n|    3   |   Yellow   |\tModerate path              |\n|    4   |   Orange   |\tSlower                     |\n|    5   |     Red    |\tLongest, to be avoided     |\n\n## Dependencies\n\nThe project uses the following main libraries:\n\n- `matplotlib` – for visualizing the graph\n- `networkx` – for graph logic and shortest path calculations\n- `pygame` – for background music\n- `RPi.GPIO` – for button input (Raspberry Pi only)\n- `rpi_ws281x` – for controlling addressable LEDs (Raspberry Pi only)\n- `tkinter` – for GUI (included with Python)\n\n## Hardware Requirements\nTo build the DuckQuest board game, you need the following components:\n\n- Complete Raspberry Pi kit\n- Push buttons for nodes\n- Addressable RGB strips for edges (like WS2812)\n- 5V Power Supply for powering the LED strip\n- Jumper wires\n\n## Execution Modes\n\nDuckQuest can run in two modes:\n\n- **Hardware mode (Raspberry Pi)**  \n  Real GPIO pins control the LED strips and buttons.\n\n- **Mock mode (Windows/macOS/Linux)**  \n  The hardware is replaced with mock interfaces and visual output.\n\nThe system auto-detects the environment at runtime.\n\n## Installation\n\n### Prerequisites\n\nIf you run in Hardware Mode ensure you have the following software installed on your raspberry:\n\n- [Python 3.11+](https://www.python.org/)\n- [Git](https://git-scm.com/)\n- An active graphical interface (like X11) – **required for running the game UI**\n\nTo run the game locally, you have two options: installing it via pip or cloning the repository manually.\n\n### Install via pip\n\nThe game is published on PyPI, you can install it directly with:\n   ```bash\n   pip install duckquest\n   ```\n\n### Clone the repository\n\n1. Clone the repository on your Raspberry Pi:\n   ```bash\n   git clone https://github.com/LeoLeman555/Board_Game_DuckQuest.git\n   ```\n\n2. Navigate to the project directory:\n   ```bash\n   cd ./Board_Game_DuckQuest/\n   ```\n\n3. Create a virtual environment (recommended):\n   ```bash\n   python -m venv venv\n   ```\n\n4. Activate the virtual environment:\n   - **Linux**:\n   ```bash\n   source venv/bin/activate\n   ```\n   - **Windows**:\n   ```powershell\n   venv\\Scripts\\activate\n   ```\n\n5. Installing dependencies with a Python script:\n   ```bash\n   python install.py\n   ```\n\n\u003e **Why use `install.py` instead of `requirements.txt`?**  \n\u003e The `RPi.GPIO` module is specifically designed for Raspberry Pi and does not work on Windows or non-Raspberry Pi Linux systems.  \n\u003e If included directly in `requirements.txt`, installation would fail on unsupported platforms. \n\u003e Additionally, the `rpi_ws281x` module, which is used to control the WS281x LED strips, is also Raspberry Pi-specific. Just like `RPi.GPIO`, it doesn't function on other platforms.\n\u003e  \n\u003e The `install.py` script ensures that both `RPi.GPIO` and `rpi_ws281x` are installed only if the script detects a Raspberry Pi. This makes the installation process more flexible and prevents errors on unsupported platforms.\n\n## Run\n\nAfter installing the package, you can launch the game with:\n\n```bash\nduck-quest\n```\n\nOn Raspberry Pi, if you're using GPIO and LED hardware, you may need to run with elevated privileges:\n```bash\nsudo -E $(which python) -m duckquest.main\n```\n\n\u003e `sudo` is required to access GPIO and PWM devices on Raspberry Pi.\n\n## Project Structure\n\n```plaintext\nduckquest/\n├── graph/         # Graph logic, UI components, and Matplotlib rendering\n├── hardware/      # GPIO control for buttons and LED strips (with mocks)\n├── audio/         # Background music and sound effects manager\n├── utils/         # Helper functions and centralized logging system\n├── main.py        # Main entry point to launch the game\n\ndocs/              # Technical documentation\nlogs/              # Generated logs (console + file logging system)\nscripts/           # Manual testing tools for hardware (GPIO, LEDs)\ntests/             # Unit and manual tests using Pytest\n```\n\n## Logging\n\nAll modules use structured logging, with outputs going to the console and into a file. See [`docs/logging.md`](./docs/logging.md) for details.\n\n## Tests\n\nAll test instructions (unit, UI, and hardware) are documented in [`docs/tests.md`](./docs/tests.md).\n\n## Contributing\n\nWant to help improve DuckQuest? Contributions are welcome!\n\n- Fork the repository\n- Create a feature branch (`feat/your-feature`)\n- Make sure tests pass (`pytest`)\n- Open a Pull Request\n\nIf you like the project, consider giving it a ⭐️ on GitHub — it really helps!\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Contact\n\nFor any questions or feedback, feel free to contact me:\n\n- GitHub: [LeoLeman555](https://github.com/LeoLeman555)\n- Email: leo.leman555@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoleman555%2Fboard_game_duckquest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleoleman555%2Fboard_game_duckquest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoleman555%2Fboard_game_duckquest/lists"}