Metadata-Version: 2.4
Name: meaningull
Version: 1.0.0
Summary: A gamified command-line vocabulary builder designed for young children and early readers.
Author: Kedar Page
License-Expression: MIT
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: release
Requires-Dist: twine>=4.0.0; extra == "release"
Requires-Dist: build>=1.0.0; extra == "release"
Dynamic: license-file

<div style="text-align: center; margin-bottom:30px">
  <img width="300" src="https://gitlab.com/kpcreatr/meaningull/-/raw/486788931b1239dc14540be6a9f15b52acd41193/logo.png" alt="Logo Image">
</div>

# Meaningull
Meaningull (pronounced mean-in-gull) is a Command Line Interface (CLI) based quiz style educational word game designed young children (~ 6-9 yrs.) to help in learning English words and their meanings. The name is a combination of 'meanining' and 'gull' as in a seagull.

The game generates a quiz with a chosen number of questions, with each question following the format 'which is the correct meaning of a certain word?', with muliple choices for answers. If the player chooses the correct answer, they score points. The quiz tells them what is their score after each question and also lets them know the right answer immediately if they were incorrect. The words and the language used to describe what they mean have been chosen based on the difficulty and exposure for the intended ages.

## Installation

### Requirements

- `Python 3.14` or newer.
- A terminal emulator (Terminal on MacOS & linux / Windows terminal on Windows)

### How to install the game
Currently this game is distributed as a python package available through Python Package Index (PyPI) package server. It can be installed like most python packages through your favourite package manager. For example, with pip:

```bash
$ pip install meaningull
```

To upgrade:

```bash
$ pip install --upgrade meaningull 
```

## Usage

Start quiz with default settings (ten questions of any difficulty):
```bash
$ meaningull
```

CLI command help. Use CLI help to see which game settings can be changed preferences set:
```bash
$ meaningull --help
```

Start quiz with part-of-speech and difficulty preference for words:
```bash
$ meaningull --pos-preference adjective --difficulty-preference medium
```

Start quiz with five questions:
```bash
$ meaningull --num-questions 5
```

Answer questions in the quiz by entering your choice and press the 'Enter' key:
```
Question number (1):
Which is the correct meaning of 'beautiful'?
	(a) having a rough texture
	(b) very nice to look at
	(c) soft white ice from the sky
	(d) something given to someone

Enter your choice (a, b, c or d) > b
```
## FAQ

### Why does this exist, and in this form?
This game was built as an exercise in learning to produce and distribute python software, as well as to build something fun and useful to children. It hopefully provides an option for fun and educational screen-time. A python package is almost certainly not the best way to distribute an educational game for kids. That choice was more for convenience and for the author's understanding of python packaging. If the game turns out of interest to more than a handful of people, it may be re-packaged in more suitable way.

### Can I get help if I run into issues?
Yes! While this is an independent hobby project maintained on a best-effort basis, bug reports and feedback are always welcome. Feel free to open an issue on the repository, and it will be reviewed and addressed as time permits. Inlcude "Unexpected Behavior" for issues and bugs, "Suggesting Enhancement" for improvements in the title, include screenshots, error messages and information about your operating system and python version where appropriate.

### Can I contribute to this project?
This is currently structured as an independent hobby project, so external contributions aren't being accepted right now. However, if you are eager to contribute, please open or comment on an issue titled "Allow Contributions" to express your interest!

## Roadmap
Here's what's on the roadmap in roughly the order listed.
1. Add more words to the database.
2. Provide users the ability to add or delete words from the dictionary.
3. Provide users the ability to save their scores and view them later (maybe).
4. Provide users the ability to view their player stats (maybe).

## Authors and acknowledgments
Author: [kpcreatr](https://gitlab.com/kpcreatr)

Acknowledgements:

This list is not exhaustive but, captures the main ones.

- Referred for game design patterns: [Discover Python and Patterns](https://www.patternsgameprog.com/)
- Referred for Class design: [Python Crash Course 3rd Edition](https://ehmatthes.github.io/pcc_3e/)
- Project Logo (seagull made of words) was created using Gemini/NanoBanana with a customized prompt.
- ASCII game banner was created using [Coddy tool](https://coddy.tech/tools/ascii-art-generator).
- Words and meanings generated with specific criteria using ChatGPT mini with human verification.
- The Gitlab CI configuration, integration test, the repository design pattern, metadata and runtime asset imports, and some parts of this document were developed or improved with the help of one or more of Mistral Vibe, Gemini Flash-Lite or ChatGPT mini models, along with significant input, modification, review and testing by the author.

## License
[MIT LICENSE](LICENSE)

## Project status
**v1.0.0 released**. This project will be developed and refined as a hobby project with sporadic periods development based on interest and time availability.
