{"id":15713633,"url":"https://github.com/vllur/shroom","last_synced_at":"2025-05-12T22:55:01.325Z","repository":{"id":179503474,"uuid":"609981664","full_name":"vllur/shroom","owner":"vllur","description":"General purpose Discord bot.","archived":false,"fork":false,"pushed_at":"2024-10-12T16:49:48.000Z","size":185,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-12T22:54:56.877Z","etag":null,"topics":["bot","crystal","crystal-lang","discord","discord-bot","discordcr"],"latest_commit_sha":null,"homepage":"","language":"Crystal","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/vllur.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}},"created_at":"2023-03-05T19:59:56.000Z","updated_at":"2024-10-12T16:49:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"d772aea7-d562-4bce-a071-696af18d59ec","html_url":"https://github.com/vllur/shroom","commit_stats":null,"previous_names":["vllur/shroom"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vllur%2Fshroom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vllur%2Fshroom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vllur%2Fshroom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vllur%2Fshroom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vllur","download_url":"https://codeload.github.com/vllur/shroom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253837400,"owners_count":21971982,"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":["bot","crystal","crystal-lang","discord","discord-bot","discordcr"],"created_at":"2024-10-03T21:32:33.887Z","updated_at":"2025-05-12T22:55:01.304Z","avatar_url":"https://github.com/vllur.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"left\" height=\"120px\" width=\"80px\" src=\"/logo.svg\"\u003e\n\n\u003ch1\u003eshroom\u003c/h1\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://github.com/crystal-lang/crystal\"\u003e\u003cimg src=\"https://img.shields.io/badge/language-crystal-776791.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/vllur/shroom/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-%20GPL--3.0-blue\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\nGeneral purpose Discord bot, focused on bringing functionality to your server. Ask about anything, let it remind you about scheduled tasks or check currency exchanges.\n\u003c/p\u003e\n\u003cp\u003e\u003c/p\u003e\n\n\u003cimg src=\"screenshot.png\"\u003e\n\n\u003c!-- TOC --\u003e\n\n- [Installation](#installation)\n  - [Configuration](#configuration)\n  - [Running with Docker](#running-with-docker)\n  - [Running with Crystal](#running-with-crystal)\n- [Usage](#usage)\n  - [Customization](#customization)\n  - [Commands](#commands)\n    - [help](#help)\n    - [shitpost](#shitpost)\n    - [drunksay](#drunksay)\n    - [eight_ball](#eight_ball)\n    - [exchange](#exchange)\n    - [classify](#classify)\n    - [remind](#remind)\n    - [or](#or)\n- [Development](#development)\n  - [Project structure](#project-structure)\n  - [Adding a command](#adding-a-command)\n  - [Making a Pull Request](#making-a-pull-request)\n- [FAQ](#faq)\n- [Contributors](#contributors)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n\n### Configuration\n\nFirst, you need to obtain [Discord API](https://discord.com/developers/applications) token and [ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-) of main (or #random, etc.) channel in your Discord server. You will also need to add a bot to your application and get its Application ID.\n\nThen click `Download` and `Download ZIP` at the top of this page, or type `git clone https://github.com/vllur/shroom.git` in terminal.\n\nNow you can copy Discord API token and channel ID to `_config.yml`:\n\n```yaml\n# Discord token\ntoken: \"TOKEN\"\n\n# Channel ID \nchannel: 123\n```\n\nNext, to add your bot to server go to \u003ca href=\"https://discord.com/oauth2/authorize?client_id=APPLICATION-ID\u0026scope=bot\u0026permissions=8\"\u003ehttps://discord.com/oauth2/authorize?client_id=APPLICATION-ID\u0026scope=bot\u0026permissions=8\u003c/a\u003e address in your browser, substituting APPLICATION-ID with your bot's Application ID.\n\nYou probably want to further edit `_config.yml` to configure the bot to your liking.\n\n### Running with Docker\n\nYou only need to have `docker` and `docker-compose` commands available. Then simply:\n\n```sh\ndocker-compose up --build\n```\n\n### Running with Crystal\n\nIf you have Crystal installed:\n\n```sh\nshards install\nshards build\n./bin/shroom\n```\n\nOptimized binary can be produced by adding `--release` and `--no-debug` flags to build command. This is a good method for smaller servers, as ~30 MB will be sufficient for the bot process.\n\nAlternatively:\n\n```sh\nshards install\ncrystal ./src/shroom.cr\n```\n\n## Usage\n\n### Customization\n\nBot reacts on every chat it sees and have write access to, if message begins with `prefix`. Names of commands are customizable.\n\nConfiguration in `_config.yml`:\n\n```yml\nprefixes:\n- \"!shroom\"\n- \"shroom\"\n\ncommands:\n  help: \"help\"\n  shitpost: \"shitpost\"\n  drunksay: \"drunksay\"\n  exchange: \"exchange\"\n  eight_ball: \"8ball\"\n  classify: \"classify\"\n  remind: \"remind\"\n  or: \"or\"\n```\n\nYou can add or remove prefixes, and customize or translate the commands names. For example, whenever this documentation refers to `shroom help`, if you set `help: \"pomoc\"`, bot will react to `shroom pomoc`. Similarly, by adding `- \"bot\"` to `prefixes`, you can use `bot pomoc`.\n\nEvery configuration change needs a bot restart.\n\n### Commands\n\nCurrently available commands:\n\n- `help` - writes a brief help message\n- `shitpost` - generates a random shitpost\n- `drunksay` - generates a shuffled shitpost\n- `eight_ball` - answers given question with configured answers\n- `exchange` - converts between currencies and crypto\n- `classify` - decides which configured answers suit the input best\n- `remind` - reminds you about something after a specified amount of time\n\n#### help\n\nUsage example:\n\n```\nshroom help\n```\n\nConfiguration in `_config.yml`:\n\n```yml\nhelp: \"**Commands**:\\n\n- `help`: Displays this message\\n\n- `shitpost`: Generates a random shitpost\\n\n- `drunksay`: Generates a drunk shitpost\\n\n- `eight_ball`: Answers given question\\n\n- `exchange`: Convert between currencies and crypto\\n\n- `classify`: Picks best way to describe your input\\n\n- `remind`: Reminds you about something after a specified amount of time\\n\n\\n\n**Features**:\\n\n- `or`: Chooses between two or more options\\n\n\\n\n**Code and documentation:**\\n\nhttps://github.com/vllur/shroom\"\n```\n\nCustomizing this string will alter the help message. You can add additional information or entirely replace it.\n\n#### shitpost\n\nUsage example:\n\n```\nshroom shitpost\n```\n\nConfiguration in `_config.yml`:\n\n```yml\nshitpost:\n-\n  - \"Gentelmen,\"\n  - \"*EKHEM*!\"\n-\n  - \"someone once said something about\"\n  - \"Sun Tzu wrote in Art of War, that\"\n-\n  - \"mushrooms being better than animals\"\n  - \"I don't know what I'm talking about\"\n-\n  - \"and thats an undeniable fact.\"\n  - \"which even can be seen in the wall paintings in Lasco!\"\n```\n\nTable of String tables. From each table one random element is picked, space is glued and next one is added.\n\n#### drunksay\n\nUsage example:\n\n```\nshroom drunksay\n```\n\nSame as [shitpost](#shitpost), but the order is random.\n\n#### eight_ball\n\nUsage example:\n\n```\nshroom eight_ball should I practice today?\n```\n\nConfiguration in `_config.yml`:\n\n```yml\nresponses:\n- \"Yes\"\n- \"No\"\n- \"Maybe\"\n- \"Ask me later\"\n- \"I don't know\"\n```\n\nTable of Strings. One random element is choosen as the answer.\n\n#### exchange\n\nUsage example:\n\n```\nshroom exchange\nshroom exchange pln\nshroom exchange 2 eur\nshroom exchange 4 eur to usd\n```\n\nConfiguration in `_config.yml`:\n\n```yml\nexchange:\n  to: \"to\"\n  input_amount: 1\n  input_currency: \"EUR\"\n  output_currency: \"USD\"\n```\n\n`to` parameter is a separator in command. Rest are default values to send to API when user have't passed them.\n\nThe command utilizes [https://api.exchangerate.host/](https://api.exchangerate.host) API. It supports conventional currencies and crypto. If output amount is greater or equals `0.01`, it is rounded to 2 decimal places. Otherwise full answer is given.\n\n#### classify\n\nUsage example:\n\n```\nshroom classify likes milk and warm places\n```\n\nConfiguration in `_config.yml`:\n\n```yml\nclassifiers:\n- \"cat\"\n- \"dog\"\n```\n\nTable of Strings. [Maschine](https://github.com/gundy818/maschine) shard is used for the algorithm. On every message sent to channel the bot can see, it associates content with one of classifiers, if present. Then you can ask what the bot associates it with.\n\n#### remind\n\nUsage example:\n\n```\nshroom remind 2 h Go excercise\nshroom remind me in 2 minutes Make tea \n```\n\nConfiguration in `_config.yml`:\n\n```yml\nremind:\n  omit:\n    - \"me\"\n    - \"in\"\n  confirmation:\n    - \"OK\"\n  seconds:\n    - \"seconds\"\n    - \"sec\"\n    - \"s\"\n  minutes:\n    - \"minutes\"\n    - \"min\"\n    - \"m\"\n  hours:\n    - \"hours\"\n    - \"h\"\n```\n\n`omit` words are completely ignored. `confirmation` takes one response at random to indicate successful set of the timer. `seconds`, `minutes` and `hours` are localizations and abbreviations of time units. Bot will spawn a new process, which waits for specified amount of time and pings you with your message.\n\n### or\n\nUsage example:\n\n```\nshroom one or two\nshroom one or two or three or four\n```\n\nThis command is meant to be in the middle of a message without command. It will separate the message and return one choice as an answer.\n\n## Development\n\nIssues and pull requests are welcome! Make sure to first post an issue to discuss your ideas before commiting to fully making a feature.\n\n### Project structure\n\n```\n├── _config.yml\n├── shard.lock\n├── shard.yml\n├── spec\n│   └── [...]\n└── src\n    ├── shroom\n    │   ├── actions\n    │   │   ├── act_on_message.cr\n    │   │   ├── act_on_ready.cr\n    │   │   └── [...]\n    │   ├── commands\n    │   │   ├── help.cr\n    │   │   └── [...]\n    │   └── config.cr\n    └── shroom.cr\n```\n\n- `_config.yml` - holds all configuration, translatable strings and messages\n- `src/shroom.cr` - main file, holds `Bot` class and runs the bot\n- `src/config.cr` - `Config` class is responsible for loading configuration\n- `src/actions/*` - each file represents actions to be taken on certain event, exposed by `Discordcr`\n- `src/commands/*` - one bot command per file\n\n### Adding a command\n\nAdding new command is quite simple. First, think about a name and configuration options your command might want to have. For example, in `config_yml`:\n\n```yaml\ncommands:\n  [...]\n  my_command: \"my_command\"\n\n[...]\n\nmy_command: \"test!\"\n```\n\nNext, lets load the configuration. Open `shroom/config.cr` and add following to the rest of getters:\n\n```crystal\ngetter my_command : String\n```\n\nIn the `initialize` function declaration also add the parameter:\n\n```crystal\n[...], @my_command : String, [...]\n```\n\nNext, register your command in `shroom/actions/act_on_message.cr`:\n\n```crystal\nwhen config.commands[\"my_command\"]\n  Shroom.my_command()\n```\n\nYou can pass anything your command will need to this function. For example, `client`, `config` or `message`.\n\nNow to create the file to hold your code - `shroom/commands/my_command.cr`:\n\n```crystal\nmodule Shroom\n  def self.my_command()\n    puts \"Test!\"\n  end\nend\n```\n\nAnd if you rerun (or recompile), you will notice that writing `shroom my_command` in Discord chat results in `Test!` in terminal output.\n\n### Making a Pull Request\n\n1. Make a fork (\u003chttps://github.com/vllur/shroom/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new pull request\n\n## FAQ\n\n- `Q`: Configuration file is present, but the bot can't find it, what's wrong?\n- `A`: Configurations location is relative to current working directory, so `cd` first to where your configuration is.\n\n## Contributors\n\n- [vllur](https://github.com/vllur) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvllur%2Fshroom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvllur%2Fshroom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvllur%2Fshroom/lists"}