{"id":13758519,"url":"https://github.com/NMisko/monkalot","last_synced_at":"2025-05-10T08:30:30.358Z","repository":{"id":23011158,"uuid":"97942639","full_name":"NMisko/monkalot","owner":"NMisko","description":"A Twitch Bot for maximum user interaction and chat spam induction.","archived":false,"fork":false,"pushed_at":"2022-05-05T16:53:21.000Z","size":659,"stargazers_count":17,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-16T15:37:41.194Z","etag":null,"topics":["bot","chat-games","chatbot","game","games","moderation-bot","moderator-commands","python","ranking","twitch","twitch-bot","twitch-tv","twitch-users"],"latest_commit_sha":null,"homepage":"","language":"Python","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/NMisko.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}},"created_at":"2017-07-21T11:51:01.000Z","updated_at":"2023-10-16T02:03:07.000Z","dependencies_parsed_at":"2022-08-08T11:30:17.189Z","dependency_job_id":null,"html_url":"https://github.com/NMisko/monkalot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NMisko%2Fmonkalot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NMisko%2Fmonkalot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NMisko%2Fmonkalot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NMisko%2Fmonkalot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NMisko","download_url":"https://codeload.github.com/NMisko/monkalot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253389418,"owners_count":21900757,"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","chat-games","chatbot","game","games","moderation-bot","moderator-commands","python","ranking","twitch","twitch-bot","twitch-tv","twitch-users"],"created_at":"2024-08-03T13:00:31.671Z","updated_at":"2025-05-10T08:30:29.824Z","avatar_url":"https://github.com/NMisko.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Python"],"readme":"**Monkalot**\n===============\n\nSubjectively the best twitch bot. \n\nEasy to get running, highly modular and [fast to extend](#adding-a-new-custom-command), \nmonkalot is almost fully configurable on a channel by channel basis. \nFully modifiable texts allow for full localization on each channel (if you have the patience to translate).\nThese configurations can also be controlled via [REST api](#rest-api) or through a [Web Interface](https://github.com/NMisko/monkalot-ui).\n\n## Quick Start\nClone this project.  \n`$ git clone https://github.com/NMisko/monkalot.git`\n\nSwitch into it.  \n`$ cd monkalot`\n\nInstall all necessary packages.  \n`$ pip install -r requirements.txt`\n\nCopy the `template` folder in `channels`, rename it to whatever channel \nthe bot needs to run on.  \n`$ cp -r channels/template channels/\u003cyour_channel\u003e`\n\nSet the configuration parameters in `channels/\u003cyour_channel/configs/bot_config.json` (see configuration section).\n\nThen start the bot.  \n`$ python3 monkalot.py`\n\nMultiple bots can be started by adding more folders with different configurations to `channels`.\n\n#### Configuration:\nMake sure to modify the following values in `bot_config.json`:\n- `channel`: Twitch channel which the bot will run on\n- `username`: The bot's Twitch user\n- `clientID`: Twitch ClientID for API calls.\n- `oauth_key`: IRC oauth_key for the bot user (from [here](http://twitchapps.com/tmi/))\n- `access_token`: access token for the bot user (see [here](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth#oauth-client-credentials-flow))\n- `owner_list`: List of Twitch users which have admin powers on bot\n- `ignore_list`: List of Twitch users which will be ignored by the bot\n\n**Warning**: Make sure all channel and user names above are in lowercase.\n\n#### Additional Configuration Parameters:\n- `points`: Various parameters that balance point-distribution for the different games.\n- `ranking`: Ranking System Point Distribution -\u003e Rank_n = base * factor^n\n- `auto_game_interval`: Time between automaticly started games while AutoGames are on.\n- `pleb_cooldown`: Time between normal chat user commands.\n- `pleb_gametimer`: Time between games started by normal chat users.\n- `EmoteGame`: Preset of emotes used in the `!estart`- command.\n\n\n# Commands\n\nAll commands that can be called from chat via different calls. Note that some commands can only be called by Moderators, Trusted-Moderators or Bot-Admins. Chat games can also be started by regular users, if they have spam points to pay for it.\n\n### All-User commands:\n\n| Command               | Description           | Examples  |\n| --------------------- | --------------------- | --------- |\n| `!any \u003cemote\u003e \u003ctext\u003e` | Sends out any sentence interlaced by an emote. All Twitch- and BTTV-emotes and emojis are supported. | `!any Jebaited Long have we waited, now we Jebaited` |\n| `!bttv`               | Returns all bttv emotes on this channel (messy) | - |\n| `!calc \u003cformula\u003e`     | A chat calculator that can do some pretty advanced stuff like sqrt and trigonometry. | `!calc (5+7)/2` , \u003cbr\u003e`!calc log(5^2) + sin(pi/4)` |\n| `!call \u003cemote\u003e \u003ctext\u003e`| Sends a call interlaced by an emote. All Twitch- and BTTV-emotes and emojis are supported. | `!call Kappa a nice stream` |\n| `!fps`                | Returns the fps of the stream | - |\n| `!hug \u003cuser\u003e`         | Sends a hug to another user. | `!hug Monkalot` |\n| `!kpm`                | Returns the amount of Kappas per minute in channel. | - |\n| `!minute \u003cemote\u003e`     | Returns the amount of a specific emote per minute in channel. All Twitch- and BTTV-emotes and emojis are supported. | `!minute BabyRage` |\n| `!oralpleasure on/off`| Turns oralpleasure on or off. | - |\n| `!penta \u003cemote\u003e`      | Quintuples an emote | `!penta PunOko` |\n| `!pjsalt`             | Sends a pjsalt pyramid in chat.      | - |\n| `!quote [\u003cnumber\u003e]`   | Returns a random quote. Optional a number can be given to call a specific quote. | `!quote` , `!quote 2` |\n| `!rank [\u003cusername\u003e]`  | Returns the current spam-rank and -points for the chatter or optional for a specific \u003cusername\u003e. | `!rank` , `!rank monkalot` |\n| `!slap \u003cuser\u003e`        | Sends a slap to another user. | `!slap Monkalot` |\n| `!smorc`              | Returns a random SMOrc quote. | - |\n| `!tenta \u003cemote\u003e`      | Gives an emote some tentacles | `!tenta WutFace` |\n| `!tip \u003cuser\u003e \u003camount\u003e`| Transfers an amount of channel points to another user. | `!tip Keepo 500` |\n| `!tkp`                | Returns the total amount of Kappas in channel. | - |\n| `!topspammers`        | Returns the five highest ranked spammers. | - |\n| `!total \u003cemote\u003e`      | Returns the total amount of a specific emote in channel. All Twitch- and BTTV-emotes and emojis are supported. | `!total EleGiggle` |\n| `!uptime`             | Returns how long this stream has been on | - | \n| `!word \u003cemote\u003e \u003ctext\u003e`| Sends a word with an emote interlaced between letters. All Twitch- and BTTV-emotes and emojis are supported. | `!word monkaS dragons` |\n| `\u003cbotname\u003e \u003ctext\u003e`    | Talk to the bot. Questions can be asked or a conversation can be started with the native speech engine. | `Hey Monkalot, how are you doing?`, `What's 2Head + 2Head? @Monkalot` |\n| `@monkalot ban me`    | Users can ask the bot to get banned (they will get banned and unbanned immediately) | `@monkalot ban me please :)` |\n| `[\u003chearthstone card\u003e]`| Get some information about a hearthstone card. Allows up to two spelling mistakes. | `[Malganis]` |\n\n\n### Chat games:\n\n| Command               | Description           | Examples  |\n| --------------------- | --------------------- | --------- |\n| `!estart`, `[!estop]`, `[!emotes]`| Starts the *GuessEmoteGame*. Guess the right emote from the list. Type emotes to start playing. While the game is active `!emotes` shows all possible emotes. | - |\n| `!kstart`, `[!pstop]` | Starts the *KappaGame*. Guess the right amount of Kappas to win. Type Kappas to start playing. | - |\n| `!mstart`, `[!mstop]` | Starts the *GuessMinionGame*. Guess the right minion card. Type minion names to play. After a short time the game will give clues to the chat. | - |\n| `!pstart`, `[!pstop]` | Starts the *MonkalotParty*. A Minigames tournament with 7 games by default. | - |\n| `\u003cemote\u003e-pyramids`    | Build emote pyramids to gain spampoints. All Twitch- and BTTV-emotes and emojis are supported. | `Kappa`\u003cbr/\u003e`Kappa`\u0026nbsp;`Kappa`\u003cbr/\u003e`Kappa` |\n\nAll games can be canceled by their respected `!stop` command.\n\n### Moderator commands:\n\n| Command               | Description           | Examples  |\n| --------------------- | --------------------- | --------- |\n| `!addnotification \u003cmsg\u003e` | Adds a message to the notification message rotation | `!addnotification Please remember to drink water. :)` |\n| `!delnotification \u003cmsg\u003e` | Removes a message from the notification message rotation | `!delnotification wheeeeee` |\n| `!addquote \u003cquote\u003e`   | Adds a quote to the *quotelist*. | `!addquote \"Priest in 2k17 LUL\"` |\n| `!delquote \u003cquote\u003e`   | Deletes a quote from the *quotelist*. | `!delquote \"Priest in 2k17 LUL\"` |\n| `!block on/off`       | Turns pyramidblock on or off. If on, pyramids will be interupted by the bot. | - |\n| `!games on/off`       | Turns automatic games on or off. If on, *chatgames* will start automaticly after a certain amount of time. | - |\n| `!notifications on/off`   | Enables or disables notifications. Notifications are messages that get sent out in regular intervals. | - |\n\n### Trusted-Moderator commands:\n\n| Command               | Description           | Examples  |\n| --------------------- | --------------------- | --------- |\n| `!addcommand \u003ccommand\u003e \u003cresponse\u003e` | Adds a command to the *simplereply*-list. | `!addcommand !ping pong` |\n| `!clearcache`         | Clears the cache. Use this e.g. to load newly released twitch emotes | - |\n| `!delcommand \u003ccommand\u003e`| Deletes a command from the *simplereply*-list. | `!delcommand !ping` |\n| `!ignore \u003cuser\u003e`      | Makes the bot ignore a user. Please enter the username in lowercase. | - |\n| `!unignore \u003cuser\u003e`    | Makes the bot no longer ignore a user. Please enter the username in lowercase. | - |\n| `!replylist`          | Returns all available commands from the *simplereply*-list. | - |\n| `!sleep`    \t\t\t| Puts the bot in *sleepmode*. All games will be disabled and the bot only responses to admins | - |\n| `!wakeup`    \t\t\t| Puts the in normal mode again. | - |\n\n\n### Admin commands:\n\n| Command               | Description           | Examples  |\n| --------------------- | --------------------- | --------- |\n| `!addmod \u003cusername\u003e`  | Adds a mod to the list of *trusted mods*. | `!addmod Monkalot` |\n| `!delmod \u003cusername\u003e`  | Deletes a mod from the list of *trusted mods*. | `!delmod Monkalot` |\n| `!g \u003cusername\u003e \u003cpronouns\u003e` | Allows changing gender pronouns for a user. Three pronouns have to be given. | `!g monkalot she her hers` |\n\n\n# Adding a new custom command\nCreate a command which inherits from [command.py](/bot/commands/abstract/command.py) in a new file and add it to the [commands](/bot/commands/) folder.\nThen import your new class into [\\_\\_init\\_\\_.py](/bot/commands/__init__.py) and add it to one of the command arrays, depending on its priority.\n\n# REST Api\nThe REST Api allows to control the bot via POST requests. It must be enabled by setting the port using the `-p` flag. You can set a password using the `-s` flag. Using a password gives access to all the bots. Alternatively pass a twitch id token, which gives access to the bots of the owner of the id token.\n\nExample:\nRun bot with: `./monkalot.py -p 8080 -s Kappa`. Assume there is one bot called *Monkalot*, owned by *Alice*.\n\n---\n\n```bash\ncurl --data 'user=alice\u0026auth=Kappa' localhost:8080/bots\n```\n\nReturns every bot *Alice* is admin of.\n\n\\=\\\u003e `[\"monkalot\"]`\n\n---\n\n```bash\ncurl --data 'user=alice\u0026bot=monkalot\u0026auth=Kappa' localhost:8080/files\n```\n\nReturns all configurable files of *Monkalot*.\n\n\\=\\\u003e `\\[\"ignored_users.json\", \"sreply_cmds.json\", \"quotes.json\", \"pronouns.json\", \"smorc.json\", \"notifications.json\", \"emote_stats.json\", \"monkalot_party.json\", \"slaphug.json\", \"trusted_mods.json\", \"bot_config.json\", \"responses.json\"]`\n\n---\n\n```bash\ncurl --data 'user=alice\u0026bot=monkalot\u0026file=ignored_users.json\u0026auth=Kappa' localhost:8080/file\n```\n\nReturns the content of *ignored_users.json*.\n\n\\=\\\u003e `{\"content\": ['bob']}`\n\n---\n\n```bash\ncurl --data 'user=alice\u0026bot=monkalot\u0026file=ignored_users.json\u0026content=[\"Bob\",\"Carl\"]\u0026auth=Kappa' localhost:8080/setfile```\n```\n\nSets the content of *ignored_users.json* to *[\"Bob\",\"Carl\"]*.\n\n---\n\n\n```bash\ncurl --data 'auth=xyz' localhost:8080/getTwitchUsername\n```\n\nUtility function. Takes a twitch id token and returns the username associated to it. Also ensures the token is valid.\n\n---\n\n```bash\ncurl --data 'user=alice\u0026bot=monkalot\u0026pause=True\u0026auth=Kappa' localhost:8080/pause\n```\n\nPauses the bot. Set pause = false to unpause the bot.\n\n---\n\n*(Based on [SimpleTwitchBot](https://github.com/EhsanKia/SimpleTwitchBot) by [EhsanKia](https://github.com/EhsanKia/).)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNMisko%2Fmonkalot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNMisko%2Fmonkalot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNMisko%2Fmonkalot/lists"}