facundolano/rpg-cli: Your filesystem as a dungeon!

rpg-cli is a minimalist RPG on the computer written in Rust. Its command-line interface can be used as a cd alternate where you randomly encounter enemies as you change directories.

Features:

• Character stats and leveling system.
• Automatic turn-based combat.
• Material and equipment support.
• Warrior, thief and mage player classes.
• 15+ Enemy classes.
• Extensible player and enemy types by configuration.
• Permadeath with item recovery.
• List of search tasks.
• Chests hidden in directories.

Just download the binary for your platform (linux/macOS/windows) from GitHub releases the page.

Assuming you have it Installed Rust and Cargo:

$ cargo install --git https://github.com/facundoolano/rpg-cli --force --tag 1.2.0

The binary should be available as rpg-cli (assuming you have ~/.cargo/bin in your $PATH).

# emerge -av games-rpg/rpg-cli

The game is designed to integrate with common file system operations, such as changing directories or deleting files. The most basic type of integration consists of wrapping rpg-cli in a shell function, such that the working directory is updated to match the progress of the hero, effectively working as a cd alternative:

rpg () {
    rpg-cli "$@"
    cd "$(rpg-cli pwd)"
}

If you want to go all the way and Granted use it instead of cd:

cd () {
    rpg-cli cd "$@"
    builtin cd "$(rpg-cli pwd)"
}

Some commands like rm, mkdir, touchetc. can also be aliased. Search this example and the shell integration guide for more sophisticated examples, as well as their fish-shell equivalents.

This sample session has the basics rpg function as described in the previous section.

The first time you run the program, a new hero is created in the user’s home directory.

~ $ rpg
 warrior(1)@home
    hp:(xxxxxxxxxx) 48/48
    mp:(----------) 0/0
    xp:(----------) 0/30
    att:10   mag:0   def:0   spd:10
    equip:{}
    item:{}
    0g

When running without parameters, as above, the hero’s status is printed (health points, accumulated experience, etc.). The stats are randomized: if you run rpg reset you get a slightly different character each time:

~ $ rpg reset; rpg
 warrior(1)@home
    hp:(xxxxxxxxxx) 50/50
    mp:(----------) 0/0
    xp:(----------) 0/30
    att:13   mag:0   def:0   spd:12
    equip:{}
    item:{}
    0g

You can also choose a different type (the default options are warrior, thief and mageBUT more can be added). For example, the mage The class allows magic attacks:

~ $ rpg class mage; rpg
    mage(1)@home
    hp:(xxxxxxxxxx) 32/32
    mp:(xxxxxxxxxx) 12/12
    xp:(----------) 0/30
    att:3   mag:27   def:0   spd:9
    equip:{}
    item:{}
    0g

If you use the cd subcommand with path as parameter, it will instruct the hero to move:

~ $ rpg cd dev/
~/dev $ rpg
    warrior(1)@~/dev
    hp:(xxxxxxxxxx) 47/47
    mp:(----------) 0/0
    xp:(----------) 0/30
    att:10   mag:0   def:0   spd:12
    equip:{}
    item:{}
    0g

In this case, the warrior moved to ~/dev. Sometimes enemies will appear as you move through the directories, and both characters will join the battle:

~/dev $ rpg cd facundoolano/
   snake(3)(xxxx)(----)@~/dev/facundoolano
   snake(3)(xxx-) -10hp
 warrior(1)(xxxx) -8hp
   snake(3)(xxx-) -9hp
 warrior(1)(xxx-) -10hp
   snake(3)(x---) -12hp
 warrior(1)(xx--) -9hp
   snake(3)(----) -14hp
 warrior(3)(xxx-) +117xp ++level +275g
 warrior(3)(xxx-)(----)(x---)@~/dev/facundoolano

Each character attacks in turn (the frequency determined by their spd statistics). Every time you win a battle, your hero will gain experience points and eventually increase its level, along with its other statistics.

When you return to the home directory, the hero’s health points are restored and status effects are removed:

~/dev/facundoolano/rpg-cli $ rpg cd ~
    warrior(3)(xxxx)(----)(x---)@home +27hp

The farther from the house you move the hero, the stronger the enemies will get. If you go too far or take too long without restoring your health, your hero will likely die in battle, causing the game to restart in the home directory.

~ $ rpg cd ~/dev/facundoolano/rpg-cli/target/debug/examples/
  zombie(3)(xxxx)(----)@~/dev/facundoolano/rpg-cli/target/debug
  zombie(3)(xxxx) -14hp
 warrior(1)(xxx-) -14hp
  zombie(3)(xxx-) -16hp
 warrior(1)(xxx-) -11hp
  zombie(3)(xx--) -16hp
 warrior(1)(xx--) -9hp
  zombie(3)(xx--) -15hp
 warrior(1)(x---) -9hp
  zombie(3)(x---) -12hp
 warrior(1)(----) -20hp critical!
 warrior(1)(----) 💀

Death is permanent: you can’t save your progress and reload after dying, but if you take your new hero to the location of the previous one’s death, you can get gold, items and equipment:

~ $ rpg cd ~/dev/facundoolano/rpg-cli/target/debug/
🪦 +potionx1 +275g

In addition to winning items as battle rewards, some directories have hidden treasure chests for you to find. rpg ls:

~ $ rpg ls
📦  +potionx2

Finally, some items can be purchased in the running game directory rpg buy:

~ $ rpg buy
    sword(1)    500g
    shield(1)   500g
    potion(1)   200g
    remedy      400g
    escape      1000g

    funds: 275g
~ $ rpg buy potion
   -200g +potionx1

The shortcut rpg b p also work on the surface. An object can be described by stat subcommand and used with use:

~ $ rpg stat potion
potion(1): restores 25hp
~ $ rpg use potion
 warrior(3)(xxxx) +25hp potion

the rpg todo The command will display a search list for your hero:

~ $ rpg todo
  □ buy a sword
  ✔ use a potion
  ✔ reach level 2
  ✔ win a battle

Each time you complete an item on the list, you will receive a reward. Quests change as you level up, so be sure to check back often!

The difficulty of the game increases as you go deeper into the dungeon; to increase your level, meet stronger enemies, find the most rare items and complete all the quests, it is necessary to go as far as possible from $HOME directory. An option to ease the gameplay is use the shell function which creates directories “on-demand”.

Try rpg --help for more options and check the shell integration guide for ideas to customize the game to your liking.

Character class determines a character’s initial stats and how quickly they increase when leveling up. By default, rpg-cli uses the classes defined in the this filebut these definitions can be overridden by placing a YAML file with the same structure in the ~/.local/share/rpg/classes.yaml. Check the dirs crate doc to find the data path of your OS.

the category field is used to distinguish between player and enemy types, and in the latter case how likely a given enemy type is to appear (eg legendary the classes are not seen very often, and only when they are far from home).

The hero class can be changed in the home directory using rpg-cli class . If the hero is at level 1 it effectively acts as a re-roll character with new stats; at higher levels the stats are preserved and the class change starts to take effect at the next level up.

• The release binary is for macOS not signed. To open it for the first time, right click on the binary and select “Open” from the menu.

If you find any issues, have feature ideas, game suggestions or example shell scripts, don’t hesitate raise an issue to start a conversation.