ai-dungeon-cli

AI Dungeon CLI

This is basically a cli client to play.aidungeon.io.

This allows playing AI Dungeon 2 inside a terminal.

I primarily did this to play the game on a DEC VT320 hardware terminal for a more faithful experience.

For more context, read the accompanying blog post.

Installation

pip

$ python3 -m pip install ai-dungeon-cli

Or for unstable release from the source code:

$ python3 -m pip install .

Arch Linux

Package is on AUR.

Using trizen:

$ trizen -S ai-dungeon-cli-git

Old school way:

$ git clone https://aur.archlinux.org/ai-dungeon-cli-git.git
$ cd ai-dungeon-cli-git
$ makepkg -si

Playing

Unless specified, all user inputs are considered Do actions.

Quoted input entries are automatically interpreted as Say actions, e.g.:

> "Hey dragon! You didn't invite me to the latest BBQ party!"

Do be explicit about the action type, prefix your input with a command:

• /do
• /say
• /story
• /remember

For example, the previous Say prompt could also be written:

> /say Hey dragon! You didn't invite me to the latest BBQ party!

To quit, either press Ctrl-C, Ctrl-D or type in the special /quit command.

Running

In any case, you first need to create a configuration file.

Installed

$ ai-dungeon-cli

From source

With a conda env (assuming you're using anaconda):

$ cd ai-dungeon-cli
$ conda env create
$ conda activate ai-dungeon-cli-env
$ ./ai_dungeon_cli/__init__.py

With a viltualenv:

$ cd ai-dungeon-cli
$ virtualenv -p $(command -v python3) ai-dungeon-cli-venv
$ source ai-dungeon-cli-venv/bin/activate
$ python3 -m pip install -r requirements.txt
$ ./ai_dungeon_cli/__init__.py

Please note that all those examples use a virtual env in order to not mess up with the main Python env on your system.

Configuration (optional)

Several things can be tuned by resorting to a config file.

Create a file config.yml either:

• in the same folder in your home folder: $HOME/.config/ai-dungeon-cli/config.yml
• in the same folder as the sources: ./ai-dungeon-cli/ai_dungeon_cli/config.yml

Authentication

By default, if no authentication configuration is provided, an anonymous session is created.

ai-dungeon-cli supports 2 ways to configure user authentication.

Either precise a couple of credentials in conf:

email: '<MY-USER-EMAIL>'
password: '<MY-USER-PASSWORD>'

Or sniff a Authentication Token and use it directly:

auth_token: '<MY-AUTH-TOKEN>'

To get this token, you need to first login in a web browser to play.aidungeon.io.

Then you can find the token either in your browser localStorage or in the content of the connection_init message of the websocket communication (first sent message).

Either way, developer tools (F12) is your friend.

Slow Typing Animation

By default, responses are printed to the screen instantly.

To enable a fun "slow" typing animation, use:

slow_typing_effect: True

Prompt

The default user prompt is '> '.

You can customize it with e.g. :

prompt: 'me: '

Command-line arguments

All configuration options are mapped to command-line arguments.

Additionally, some features (such as multi-player support) are only available through those arguments.

The list of all arguments can be retrieved by calling ai-dungeon-cli with either -h of --help.

Authentication

One can use either the --auth-token <token> or --email <email> --password <password> arguments to authenticate.

Slow Typing Animation

Just append --slow-typing to your execution call to enable this fancy effect.

Prompt

The custom prompt can be set with --prompt '<prompt>'.

Multi-player

To join an existing multi-player adventure, use arguments --adventure <public-adventure-id> --name <character-name>.

Debug

TO enable debug mode and see the responses from the play.aidungeon.io API, use --debug. This option is mainly useful for developers.

Dependencies

Please have a look at requirements.txt.

Limitations and future improvements

Right now, the code is over-optimistic: we don't catch cleanly when the backend is down.

A better user experience could be achieved with the use of the curses library.

For now /revert and /alterspecial actions are not supported.

It would also be nice to add support for browsing other players' stories (Explore menu).

Implementation details

We fallback to a pure ASCII version of the splash logo if we detect an incompatible locale / terminal type.

Support

As you might have heard, hosting AI Dungeon costs a lot of money.

This cli client relies on the same infrastructure as the online version (play.aidungeon.io).

So don't hesitate to help support the hosting fees to keep the game up and running.

Author

Jordan Besly @p3r7 (blog).

Contributors & acknowledgements

Major contributions:

• Idan Gur @idangur: OOP rewrite of game logic
• Alberto Oporto Ames @otreblan: packaging, submission to AUR
• @jgb95: slow typing effect
• Alexander Batyrgariev @sasha00123: help on porting to new websocket/gql-based version of the API

Minor contributions:

• Robert Davis @bdavs: pip requirements
• @Jezza: suggested login using creds

Code for slow typing effect inspired by this message from Magnus Lycka on the Python Tutor mailing list.

Similar projects

• sasha00123/ai-dungeon-bot, a bot for Telegram & VK, written in python
• SoptikHa2/aidungeon2-cli, written in Rust (unmaintained)