{"id":13465087,"url":"https://github.com/facundoolano/rpg-cli","last_synced_at":"2025-10-22T10:55:13.096Z","repository":{"id":37481205,"uuid":"361019889","full_name":"facundoolano/rpg-cli","owner":"facundoolano","description":"Your filesystem as a dungeon!","archived":false,"fork":false,"pushed_at":"2025-05-03T00:15:57.000Z","size":3182,"stargazers_count":1617,"open_issues_count":6,"forks_count":37,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-14T09:05:12.297Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://olano.dev/blog/deconstructing-the-role-playing-videogame/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facundoolano.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-04-23T22:29:19.000Z","updated_at":"2025-05-12T12:55:29.000Z","dependencies_parsed_at":"2025-02-27T18:06:51.774Z","dependency_job_id":"c7c1b480-9085-437e-b82d-51a73af55494","html_url":"https://github.com/facundoolano/rpg-cli","commit_stats":{"total_commits":280,"total_committers":16,"mean_commits":17.5,"dds":0.06428571428571428,"last_synced_commit":"6090c8855db8df8b39c2eb172f9803ee6d9f4411"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facundoolano%2Frpg-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facundoolano%2Frpg-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facundoolano%2Frpg-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facundoolano%2Frpg-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facundoolano","download_url":"https://codeload.github.com/facundoolano/rpg-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"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","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":[],"created_at":"2024-07-31T14:00:58.533Z","updated_at":"2025-10-22T10:55:08.060Z","avatar_url":"https://github.com/facundoolano.png","language":"Rust","funding_links":[],"categories":["Rust","\u003ca name=\"games\"\u003e\u003c/a\u003eGames"],"sub_categories":[],"readme":"# rpg-cli — your filesystem as a dungeon!\n\nrpg-cli is a minimalist [computer RPG](https://en.wikipedia.org/wiki/Role-playing_video_game) written in Rust. Its command-line interface can be used as a `cd` replacement where you randomly encounter enemies as you change directories.\n\n![](rpg-cli.png)\n\nFeatures:\n\n* Character stats and leveling system.\n* Automatic turn-based combat.\n* Item and equipment support.\n* Warrior, thief and mage player classes.\n* 15+ Enemy classes.\n* Extensible player and enemy classes via configuration.\n* Permadeath with item recovering.\n* Quests to-do list.\n* Chests hidden in directories.\n\nSee [this blog post](https://olano.dev/blog/deconstructing-the-role-playing-videogame/) for background on the development process.\n\n## Installation\n\n### From binary\n\nJust download the binary for your platform (linux/macOS/windows) from the [GitHub releases page](https://github.com/facundoolano/rpg-cli/releases/latest).\n\n### Using Cargo\nAssuming you have [Rust and Cargo installed](https://doc.rust-lang.org/cargo/getting-started/installation.html#install-rust-and-cargo):\n\n    $ cargo install --git https://github.com/facundoolano/rpg-cli --force --tag 1.2.0\n\nThe binary should be available as `rpg-cli` (assuming you have `~/.cargo/bin` in your `$PATH`).\n\n### Other installation methods\n\u003cdetails\u003e\n  \u003csummary\u003eShow details\u003c/summary\u003e\n\n#### Homebrew (macOS)\nYou can use homebrew to install the binary on macOS::\n\n    $ brew install rpg-cli\n\n#### Nixpkgs\nIf you use Nix/NixOS you can get rpg-cli from nixpkgs, either install it by adding it to your system config, with `nix-env -i rpg-cli`/`nix profile install nixpkgs#rpg-cli` or try it in a ephemeral shell with `nix-shell -p rpg-cli`/`nix shell nixpkgs#rpg-cli`.\n\n#### Portage (Gentoo)\nIf you use Gentoo, you can get rpg-cli from portage:\n\n    # emerge -av games-rpg/rpg-cli\n\n#### Pacman (Arch Linux)\n\nrpg-cli can be installed from the [extra repository](https://archlinux.org/packages/extra/x86_64/rpg-cli/) for Arch Linux:\n\n    $ pacman -S rpg-cli\n\u003c/details\u003e\n\n## Shell integration\n\nThe game is designed to integrate with common file system operations, such as changing directories or deleting files.\nThe most basic type of integration consists in wrapping rpg-cli in a shell function, such that the working directory is updated to match the hero's progress, effectively working as a `cd` alternative:\n\n```sh\nrpg () {\n    rpg-cli \"$@\"\n    cd \"$(rpg-cli pwd)\"\n}\n```\n\nIf you want to go all the way and *really* use it in place of `cd`:\n\n```sh\ncd () {\n    rpg-cli cd \"$@\"\n    builtin cd \"$(rpg-cli pwd)\"\n}\n```\n\nOther commands like `rm`, `mkdir`, `touch`, etc. can also be aliased. Check [this example](shell/example.sh) and the [shell integration guide](shell/README.md) for more sophisticated examples, as well as their fish shell equivalents.\n\n## Gameplay\n\nThis example session assumes a basic `rpg` function as described in the previous section.\n\n### Character setup\nThe first time you run the program, a new hero is created at the user's home directory.\n\n    ~ $ rpg\n     warrior[1]@home\n        hp:[xxxxxxxxxx] 48/48\n        mp:[----------] 0/0\n        xp:[----------] 0/30\n        att:10   mag:0   def:0   spd:10\n        equip:{}\n        item:{}\n        0g\n\nWhen running without parameters, as above, the hero status is printed (health points, accumulated experience, etc.).\nThe stats are randomized: if you run `rpg reset` you will get a slightly different character every time:\n\n    ~ $ rpg reset; rpg\n     warrior[1]@home\n        hp:[xxxxxxxxxx] 50/50\n        mp:[----------] 0/0\n        xp:[----------] 0/30\n        att:13   mag:0   def:0   spd:12\n        equip:{}\n        item:{}\n        0g\n\nYou can also pick a different class (default options are `warrior`, `thief` and `mage`, but [more can be added](#customize-character-classes)).\nFor example, the `mage` class enables magic attacks:\n\n    ~ $ rpg class mage; rpg\n        mage[1]@home\n        hp:[xxxxxxxxxx] 32/32\n        mp:[xxxxxxxxxx] 12/12\n        xp:[----------] 0/30\n        att:3   mag:27   def:0   spd:9\n        equip:{}\n        item:{}\n        0g\n\n### Movement and battles\nIf you use the `cd` subcommand with a path as parameter, it will instruct the hero to move:\n\n    ~ $ rpg cd dev/\n    ~/dev $ rpg\n        warrior[1]@~/dev\n        hp:[xxxxxxxxxx] 47/47\n        mp:[----------] 0/0\n        xp:[----------] 0/30\n        att:10   mag:0   def:0   spd:12\n        equip:{}\n        item:{}\n        0g\n\nIn this case, the warrior moved to `~/dev`. Sometimes enemies will appear as you move through the directories,\nand both characters will engage in battle:\n\n    ~/dev $ rpg cd facundoolano/\n       snake[3][xxxx][----]@~/dev/facundoolano\n       snake[3][xxx-] -10hp\n     warrior[1][xxxx] -8hp\n       snake[3][xxx-] -9hp\n     warrior[1][xxx-] -10hp\n       snake[3][x---] -12hp\n     warrior[1][xx--] -9hp\n       snake[3][----] -14hp\n     warrior[3][xxx-] +117xp ++level +275g\n     warrior[3][xxx-][----][x---]@~/dev/facundoolano\n\nEach character attacks in turn (the frequency being determined by their `spd` stat).\nWhenever you win a fight, your hero gains experience points and eventually raises its level, along with its other stats.\n\nWhen you return to the home directory, the hero's health points are restored and status effects are removed:\n\n    ~/dev/facundoolano/rpg-cli $ rpg cd ~\n        warrior[3][xxxx][----][x---]@home +27hp\n\nThe further from home you move the hero, the tougher the enemies will get. If you go to far or too long without restoring your health, your hero is likely to die in battle, causing the game to restart at the home directory.\n\n    ~ $ rpg cd ~/dev/facundoolano/rpg-cli/target/debug/examples/\n      zombie[3][xxxx][----]@~/dev/facundoolano/rpg-cli/target/debug\n      zombie[3][xxxx] -14hp\n     warrior[1][xxx-] -14hp\n      zombie[3][xxx-] -16hp\n     warrior[1][xxx-] -11hp\n      zombie[3][xx--] -16hp\n     warrior[1][xx--] -9hp\n      zombie[3][xx--] -15hp\n     warrior[1][x---] -9hp\n      zombie[3][x---] -12hp\n     warrior[1][----] -20hp critical!\n     warrior[1][----] 💀\n\nDeath 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,\nyou can recover gold, items and equipment:\n\n    ~ $ rpg cd ~/dev/facundoolano/rpg-cli/target/debug/\n    🪦 +potionx1 +275g\n\n### Items and equipment\n\nIn addition to winning items as battle rewards, some directories have hidden treasure chests that you can find with `rpg ls`:\n\n    ~ $ rpg ls\n    📦  +potionx2\n\nFinally, some items can be bought at the game directory running `rpg buy`:\n\n    ~ $ rpg buy\n        sword[1]    500g\n        shield[1]   500g\n        potion[1]   200g\n        remedy      400g\n        escape      1000g\n\n        funds: 275g\n    ~ $ rpg buy potion\n       -200g +potionx1\n\nThe shortcut `rpg b p` would also work above. An item can be described with the `stat` subcommand and used with `use`:\n\n    ~ $ rpg stat potion\n    potion[1]: restores 25hp\n    ~ $ rpg use potion\n     warrior[3][xxxx] +25hp potion\n\n### Quests and late game\n\nThe `rpg todo` command will display a list of quest for your hero:\n\n    ~ $ rpg todo\n      □ buy a sword\n      ✔ use a potion\n      ✔ reach level 2\n      ✔ win a battle\n\nEach time you complete an item on the list, you will receive a reward. The quests renew as your level raises, so be sure to check often!\n\nThe game difficulty increases as you go deeper in the dungeon; to raise your level, encounter the tougher enemies, find the rarest items\nand complete all the quests, it's necessary to go as far as possible from the `$HOME` directory. One option to ease the gameplay\nis to [use a shell function](https://github.com/facundoolano/rpg-cli/blob/main/shell/README.md#arbitrary-dungeon-levels) that creates directories \"on-demand\".\n\nTry `rpg --help` for more options and check the [shell integration guide](shell/README.md) for ideas to adapt the game to your preferences.\n\n## Customize character classes\n\nThe character class determines a character's initial stats and at what pace they increase when leveling up. By default, rpg-cli will use classes as defined by [this file](src/character/classes.yaml), but these definitions can be overridden by placing a YAML file with that same structure at `~/.local/share/rpg/classes.yaml`. Check the [dirs crate doc](https://docs.rs/dirs/3.0.2/dirs/fn.data_dir.html) to find the data path on your OS.\n\nThe `category` field is used to distinguish between player and enemy classes, and in the latter case how likely a given enemy class is likely to appear (e.g. `legendary` classes will appear less frequently, and only when far away from home).\n\nThe hero's class can be changed at the home directory using `rpg-cli class \u003cname\u003e`. If the hero is at level 1 it will effectively work as a character re-roll with fresh stats; at higher levels the stats are preserved and the class change will start taking effect on the next level increment.\n\n## Troubleshooting\n\n* The release binary for macOS [is not signed](https://github.com/facundoolano/rpg-cli/issues/27). To open it for the first time, right click on the binary and select \"Open\" from the menu.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacundoolano%2Frpg-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacundoolano%2Frpg-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacundoolano%2Frpg-cli/lists"}