{"id":29953734,"url":"https://github.com/bocaletto-luca/textquestengine","last_synced_at":"2025-08-03T15:11:09.205Z","repository":{"id":305254975,"uuid":"1022391711","full_name":"bocaletto-luca/TextQuestEngine","owner":"bocaletto-luca","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-19T01:48:42.000Z","size":40,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-19T06:13:21.545Z","etag":null,"topics":["bocaletto-luca","engine","engine-development","engine-videogames","python","terminal-engine","videogames-engine"],"latest_commit_sha":null,"homepage":"https://bocaletto-luca.github.io/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bocaletto-luca.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,"zenodo":null}},"created_at":"2025-07-19T01:33:55.000Z","updated_at":"2025-07-19T01:48:45.000Z","dependencies_parsed_at":"2025-07-19T06:14:11.355Z","dependency_job_id":"c0118f81-0732-4b0e-8981-1df6910f722c","html_url":"https://github.com/bocaletto-luca/TextQuestEngine","commit_stats":null,"previous_names":["bocaletto-luca/textquestengine"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bocaletto-luca/TextQuestEngine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bocaletto-luca%2FTextQuestEngine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bocaletto-luca%2FTextQuestEngine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bocaletto-luca%2FTextQuestEngine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bocaletto-luca%2FTextQuestEngine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bocaletto-luca","download_url":"https://codeload.github.com/bocaletto-luca/TextQuestEngine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bocaletto-luca%2FTextQuestEngine/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268563848,"owners_count":24270656,"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","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bocaletto-luca","engine","engine-development","engine-videogames","python","terminal-engine","videogames-engine"],"created_at":"2025-08-03T15:10:58.711Z","updated_at":"2025-08-03T15:11:09.197Z","avatar_url":"https://github.com/bocaletto-luca.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TextQuestEngine\n\n**Author**: Luca Bocaletto (bocaletto-luca)  \n**Repository**: https://github.com/bocaletto-luca/TextQuestEngine  \n**License**: GNU GPL v3.0\n\nA Python engine for creating modular, extensible, and standalone text adventures. This repository includes:\n\n- Core engine: parser, dispatcher, loader, plugin system  \n- A complete demo: “The Lost Cave”  \n- CLI tools to scaffold, run, test, lint, build and package your adventure  \n\n---\n\n## Table of Contents\n\n- [Features](#features)  \n- [Prerequisites](#prerequisites)  \n- [Installation](#installation)  \n- [Usage](#usage)  \n  - [CLI Commands](#cli-commands)  \n  - [Demo Walkthrough](#demo-walkthrough)  \n- [Project Structure](#project-structure)  \n- [Demo “The Lost Cave”](#demo-the-lost-cave)  \n  - [world.yaml](#worldyaml)  \n  - [items.json](#itemsjson)  \n  - [Plugin: light_plugin.py](#plugin-light_pluginpy)  \n- [Packaging](#packaging)  \n- [Contributing](#contributing)  \n- [License](#license)  \n\n---\n\n## Features\n\n- Multilingual parser (Italian/English) with synonyms  \n- Event-driven dispatcher \u0026 plugin hooks (`pre_action`, `command_\u003ccmd\u003e`, `post_action`)  \n- World loader from YAML + JSON (`world.yaml` + `items.json`)  \n- Built-in support for rooms, items, NPCs, missions, game time  \n- Intuitive CLI: `init`, `run`, `test`, `lint`, `build`, `package`  \n- Standalone packaging via PyInstaller  \n\n---\n\n## Prerequisites\n\n- Python 3.8+  \n- pip  \n- (optional) PyInstaller for standalone packaging  \n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/bocaletto-luca/TextQuestEngine.git\ncd TextQuestEngine\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\npip install pyinstaller       # only if you intend to use `tqe package`\n```\n\n---\n\n## Usage\n\n### CLI Commands\n\nAfter installation, the `tqe` command (alias for `python3 -m engine.utils.cli`) provides:\n\n```bash\ntqe init \u003cproject_name\u003e            # Scaffold a new adventure project\ntqe run --world \u003cpath/world.yaml\u003e  # Launch the interactive game\ntqe test                           # Run unit \u0026 integration tests (pytest)\ntqe lint                           # Check code style \u0026 quality\ntqe build                          # Build sdist \u0026 wheel packages\ntqe package                        # Create a standalone executable (PyInstaller)\n```\n\n### Demo Walkthrough\n\nThe demo “The Lost Cave” is in `demo_adventure/`. To try it:\n\n```bash\ncd demo_adventure\ntqe run\n```\n\nSample commands:\n\n```txt\n\u003e look\n\u003e take torch\n\u003e move inside\n\u003e use torch\n\u003e look\n\u003e take gem\n\u003e missions\n```\n\n---\n\n## Project Structure\n\n```\nTextQuestEngine/\n├── engine/                   # Core engine code\n│   ├── core/\n│   │   ├── dispatcher.py\n│   │   ├── game.py\n│   │   ├── parser.py\n│   │   └── cli_commands.py\n│   ├── data/\n│   │   ├── loader.py\n│   │   └── models.py\n│   ├── plugins/\n│   │   └── base.py\n│   └── utils/\n│       └── cli.py\n├── demo_adventure/           # “The Lost Cave” demo\n│   ├── config/\n│   │   ├── world.yaml\n│   │   └── items.json\n│   ├── plugins/\n│   │   └── light_plugin.py\n│   └── assets/\n│       └── map.txt\n├── src/                      # PyInstaller entrypoint\n│   └── main.py\n├── setup.py\n└── README.md\n```\n\n---\n\n## Demo “The Lost Cave”\n\n### world.yaml\n\n```yaml\n# demo_adventure/config/world.yaml\n\nconfig:\n  start_room: house\n  start_time: 0\n  intro_text: \u003e\n    You are an explorer seeking epic adventures… and epically bad jokes.\n    If you can keep a grin while risking life and limb, you’re in the right place!\n  initial_missions:\n    - mission_gem\n    - mission_beer\n\nrooms:\n\n  house:\n    name: Abandoned House\n    desc: \u003e\n      A dusty little house filled with creaky furniture and mysterious\n      oddities. A torch glints on the table like a miniature sun.\n    connections:\n      outside: forest\n    items:\n      - torch\n\n  forest:\n    name: Messy Forest\n    desc: \u003e\n      Trees look like they’ve given each other bad haircuts. A winding path\n      leads deeper, where a mysterious cave yawns in darkness.\n    connections:\n      back: house\n      inside: cave\n    items: []\n\n  cave:\n    name: Dark (and Witty) Cave\n    desc: \u003e\n      It’s so dark even your brightest ideas struggle to stand out.\n      Maybe you need something to light the way… or at least a comedian.\n    connections:\n      exit: forest\n    items: []\n\n  tavern:\n    name: Tavern of the Dozy Gnome\n    desc: \u003e\n      A humble tavern where every patron snores into their pint.\n      The bar is lined with bottles—most as empty as your wallet.\n    connections:\n      outside: house\n    items:\n      - beer\n\nnpcs:\n\n  lazy_gnome:\n    name: Lazy Gnome\n    location: tavern\n    dialogues:\n      - text: \"Oh, traveler! If you have a beer, we can call it ‘friendship’.\"\n        options:\n          - reply: \"Here’s a beer\"\n            text: \"Ah, finally! *sneeze*\"\n            next: end\n          - reply: \"I have a gem\"\n            text: \"A gem? I prefer frothy mugs, but sure…\"\n            next: end\n      - text: \"end\"\n        options: []\n\nmissions:\n\n  mission_gem:\n    title: \"The Shiny Gem\"\n    description: \u003e\n      Legend speaks of a precious gem hidden in the dark depths of the cave.\n      Find it and bring it back… and maybe entertain a gnome!\n    requirements:\n      have_item: [\"gem\"]\n    steps:\n      - \"Enter the cave\"\n      - \"Light the torch\"\n      - \"Take the gem\"\n      - \"Return to the Lazy Gnome\"\n    rewards:\n      xp: 50\n      message: \"You lit up the cave… and one gnome’s spirits!\"\n\n  mission_beer:\n    title: \"Bring the Beer\"\n    description: \u003e\n      The Lazy Gnome is parched. Fetch a cold beer and present it with flair.\n    requirements:\n      have_item: [\"beer\"]\n    steps:\n      - \"Find a beer\"\n      - \"Go to the tavern\"\n      - \"Give the beer to the Lazy Gnome\"\n    rewards:\n      xp: 20\n      message: \"The gnome now sleeps soundly. Mission accomplished!\"\n```\n\n### items.json\n\n```json\n{\n  \"torch\": {\n    \"names\": [\"torch\", \"lantern\"],\n    \"description\": \"A battery-powered torch that shines brightly—perfect for caves.\",\n    \"weight\": 1.0,\n    \"usable_on\": [\"cave\"]\n  },\n  \"gem\": {\n    \"names\": [\"gem\", \"precious stone\"],\n    \"description\": \"A sparkling gem embedded in the cave wall—brighter than your wits.\",\n    \"weight\": 0.2,\n    \"usable_on\": []\n  },\n  \"beer\": {\n    \"names\": [\"beer\", \"pint\", \"bottle\"],\n    \"description\": \"A frothy pint of beer: liquid consolation for any gnome.\",\n    \"weight\": 0.5,\n    \"usable_on\": [\"lazy_gnome\"]\n  }\n}\n```\n\n### Plugin: `light_plugin.py`\n\n```python\n# demo_adventure/plugins/light_plugin.py\n\nfrom engine.plugins.base import PluginBase\nfrom types import SimpleNamespace\n\nclass LightPlugin(PluginBase):\n    \"\"\"\n    Handles darkness in the cave and torch usage:\n    - Blocks vision until the torch is lit\n    - Spawns the gem once lit\n    \"\"\"\n\n    def on_pre_action(self, action: SimpleNamespace, state, world):\n        if action.command == \"look\" and state[\"current_room\"] == \"cave\":\n            if not state.get(\"torch_lit\", False):\n                return \"It’s too dark to see. Maybe a torch would help!\"\n        return None\n\n    def on_command_use(self, action: SimpleNamespace, state, world):\n        if action.target == \"torch\":\n            state[\"torch_lit\"] = True\n            cave = world.rooms[\"cave\"]\n            if \"gem\" not in cave.items:\n                cave.items.append(\"gem\")\n            return \"You light the torch! Warm glow reveals a shiny gem.\"\n        return None\n```\n\n---\n\n## Packaging\n\nTo build a standalone executable:\n\n```bash\npip install pyinstaller\ntqe package\n```\n\nThe binary (plus `config/` and `assets/`) will appear in `dist/`. Rename it to `tqe` and distribute!\n\n---\n\n## Contributing\n\n1. Fork the repository  \n2. Create a feature branch (`feature/your-feature`)  \n3. Make changes, run `tqe test` \u0026 `tqe lint`  \n4. Submit a Pull Request  \n\n---\n\n## License\n\nThis project is licensed under **GNU GPL v3.0**.  \nSee [LICENSE](LICENSE) for details.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbocaletto-luca%2Ftextquestengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbocaletto-luca%2Ftextquestengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbocaletto-luca%2Ftextquestengine/lists"}