# Texventure
A text-based adventure game. It allows you to create and play interactive stories using a command-line interface.
## Installation
Clone the repository and install with `pip install .` from within the repo
## Requirements
texventure relies on openai for dynamic event generation, so you need to have an OpenAI API key. You can set it as an environment variable:
```bash
export OPENAI_API_KEY="your_api_key_here"
```
You can optionally choose the model to use for dynamic event generation by passing the `--model` argument when running the game. The default model is `gpt-4.1-nano`, but you can change it to any other OpenAI model that suits your needs.
## Creating a story
To create a story, you need to write a TOML file that defines the structure of your adventure. The file should include the following sections:
- `title`: The title of your story.
- `setting`: A description of the world where the story takes place.
- `outline`: A brief overview of the main plot points.
- `n_acts`: The number of acts in your story.
- `n_scenes`: The number of scenes in each act.
- `n_npcs`: The number of non-player characters (NPCs) in your story.
You can optionall also provide the acts and scenes in the TOML file, or you can let the game generate them dynamically based on your outline.
With a template complete, generate a story file with the following command:
```bash
texventure-generate your_story_template.toml -o your_story_file.json
```
See `template.toml` as an example.
## Playing a texventure game
To play a game, run the following command:
```bash
texventure-play your_story_file.json
```
## Commands
Within the game, you are presented with events in the narrative, and you must make choices to progress the story. Additionally, you can use the following commands:
- `look`: Look around the current scene.
- `history`: View the history of your actions.
- `inventory`: Check your inventory for items you have collected.
- `save`: Save your current game state.
- `status`: Check your current status, scene, and other relevant information.
- `choice <choice_number>`: Make a choice based on the available options presented in the current scene.
- `exit`: Exit the game.
The save command will produce a `your_story_file-savegame.json`. To continue your progress where you left off, run the play command with the save file:
```bash
texventure your_story_file-savegame.json
```
Raw data
{
"_id": null,
"home_page": null,
"name": "texventure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "adventure, game, interactive-fiction, text-adventure",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/fc/37/5161c13f02345b11e07e85501213945c044c6b987036473ff20a3527fde9/texventure-0.1.0.tar.gz",
"platform": null,
"description": "# Texventure\n\nA text-based adventure game. It allows you to create and play interactive stories using a command-line interface.\n\n## Installation\n\nClone the repository and install with `pip install .` from within the repo \n\n## Requirements\n\ntexventure relies on openai for dynamic event generation, so you need to have an OpenAI API key. You can set it as an environment variable:\n\n```bash\nexport OPENAI_API_KEY=\"your_api_key_here\"\n```\nYou can optionally choose the model to use for dynamic event generation by passing the `--model` argument when running the game. The default model is `gpt-4.1-nano`, but you can change it to any other OpenAI model that suits your needs.\n\n## Creating a story\n\nTo create a story, you need to write a TOML file that defines the structure of your adventure. The file should include the following sections:\n\n- `title`: The title of your story.\n- `setting`: A description of the world where the story takes place.\n- `outline`: A brief overview of the main plot points.\n- `n_acts`: The number of acts in your story.\n- `n_scenes`: The number of scenes in each act.\n- `n_npcs`: The number of non-player characters (NPCs) in your story.\n\nYou can optionall also provide the acts and scenes in the TOML file, or you can let the game generate them dynamically based on your outline.\n\nWith a template complete, generate a story file with the following command:\n\n```bash\ntexventure-generate your_story_template.toml -o your_story_file.json\n```\nSee `template.toml` as an example.\n\n## Playing a texventure game\nTo play a game, run the following command:\n\n```bash\ntexventure-play your_story_file.json\n```\n## Commands\n\nWithin the game, you are presented with events in the narrative, and you must make choices to progress the story. Additionally, you can use the following commands:\n- `look`: Look around the current scene.\n- `history`: View the history of your actions.\n- `inventory`: Check your inventory for items you have collected.\n- `save`: Save your current game state.\n- `status`: Check your current status, scene, and other relevant information.\n- `choice <choice_number>`: Make a choice based on the available options presented in the current scene.\n- `exit`: Exit the game.\n\nThe save command will produce a `your_story_file-savegame.json`. To continue your progress where you left off, run the play command with the save file:\n\n```bash\ntexventure your_story_file-savegame.json\n```",
"bugtrack_url": null,
"license": null,
"summary": "A text-based adventure game generator and engine",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/texventure",
"Issues": "https://github.com/yourusername/texventure/issues",
"Repository": "https://github.com/yourusername/texventure"
},
"split_keywords": [
"adventure",
" game",
" interactive-fiction",
" text-adventure"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a1fbbdb17011c3b9fce16662c54e3b5db97387b0c332c44853f15e46d42b1a17",
"md5": "cf4dcb9e506127b74704eb3babce3508",
"sha256": "f466b51eaf34359cde75018067863301cab128da5a0f1892babfb2798189d5db"
},
"downloads": -1,
"filename": "texventure-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf4dcb9e506127b74704eb3babce3508",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 21019,
"upload_time": "2025-07-27T18:07:32",
"upload_time_iso_8601": "2025-07-27T18:07:32.183068Z",
"url": "https://files.pythonhosted.org/packages/a1/fb/bdb17011c3b9fce16662c54e3b5db97387b0c332c44853f15e46d42b1a17/texventure-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fc375161c13f02345b11e07e85501213945c044c6b987036473ff20a3527fde9",
"md5": "3ae372b91d874e29ffd16c59b7f70d60",
"sha256": "144f86f0f2dabb24b0f060bdfec7a6b2b1b76af28975af31aa4c80a1ff865c85"
},
"downloads": -1,
"filename": "texventure-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3ae372b91d874e29ffd16c59b7f70d60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 50895,
"upload_time": "2025-07-27T18:07:35",
"upload_time_iso_8601": "2025-07-27T18:07:35.562594Z",
"url": "https://files.pythonhosted.org/packages/fc/37/5161c13f02345b11e07e85501213945c044c6b987036473ff20a3527fde9/texventure-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 18:07:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "texventure",
"github_not_found": true,
"lcname": "texventure"
}
JSON
