# qweribot

## Concepts

### Admins

Admins are defined by the streamer and can use special administrative commands on the bot.
Admins don't need to have moderator status in the channel.
The chatterbot and streamer always have admin status and cannot be stripped of admin powers.
Only the streamer and chatterbot have the power to add and remove admins.
Admins have the power to destroy the item economy. Be very careful with admin powers.

### Invulns

Invulns, or invulnerable chatters cannot be shot with items and cannot get hit by explosives.
When an invuln uses an item or a lootbox they lose their invuln status.
The intended use for invulns is for when a chatter doesn't want to participate in pvp or for when you need to talk to someone.
Invulns don't need moderator or vip status in the channel.
The chatterbot and streamer always are invuln and cannot be stripped of this status.
Moderators can add and remove invulns.
On your first message in chat you will recieve 10 minutes of invuln status.
When a moderator adds you as invuln you will lose all items and qbucks.

### Bots

Bots are ignored by the program.
Bots cannot be timed out.
Bots don't need moderator or vip status.

### Commands

Commands are functions that are triggered by typing an instruction in the chat.

All commands need a prefix. By default this is `!`.

Arguments like `[this]` are optional.  
Arguments like `{this}` are required.

Commands and items can be disabled and enabled by admins with the [`enable` and `disable` commands](#administrative-commands).
Not all Commands can be disabled, the `DISABLEABLE` field below shows if they can or can't. Items can always be disabled.

Commands can have special aliases, these don't require the prefix. Special aliases have curly brackets around them in this document. For example: `{blastin}` on silver bullets.

A full list of Commands can be found [here](#commands-1)

### Whisper commands

Whisper commands use the same prefix as regular commands, but are whispered to the bot instead.
Whisper commands can be found [here](#whisper-commands-1).
Unlike regular commands, whisper commands cannot be disabled. This is fine as they don't bother anyone.

### Ghost whispers

If you've been timed out, you can ghost whisper a message to the chatterbot and it will relay your message to the chat.
You can only send one message every 5 minutes. 
Try to bargain for your release with the chatter that shot you, or just call them names.

### Aniv timeouts

When chatter `a_n_i_v` (a_normal_imyt_viewer) or `a_n_e_e_v` sends a message it's stored in the database.
If then someone copies them, they might get timed out.
These timeouts and dodges are stored. You can get your stats with the `anivtimeouts` command.
The current dodge rate is `1/2`, and the timeout duration range is between `30` and `60` seconds.

### Leaderboards

There are 3 types of leaderboards: monthlyKD, alltimeKD and qbucks.
- The monthlyKD leaderboard (command: `monthlyleaderboard`) gives you the leaderboard of the top 10 user Kill/Death ratios for the current month.
- The alltimeKD leaderboard (command: `alltimeleaderboard`) gives you the leaderboard of the top 10 user Kill/Death ratios of all time in the channel.
- The qbucks leaderboard (command: `qbucksleaderboard`) gives you the current leaderboard of the top 10 qbucks havers.

To appear on the KD leaderboards you need to have been timed out 5 times, in the specified timeframe.
Blasters, Grenade explosions and TNT explosions all count for the KD, Silver bullets do not.

### Items and Itemlock

Items are commands that can only be used when the chatter has them in their inventory.

Every user has a wallet with qweribucks, and an inventory. There is no limit to how many items each chatter can have.

When using/giving an item or qbucks the itemlock will be set at the start of the transaction and cleared when it ends. This is to prevent items being duplicated.
Admins can toggle the itemlock on chatters with the [`itemlock`](#administrative-commands) command. This will stop a chatter from giving, receiving and using items and qweribucks.
It will NOT stop them from using items by cheering, but if that cheer item usage fails, they will not be given an equivalent item as compensation.

The only ways to get items is through the `getloot` command or by buying them with qbucks.

Items can be used with the alias as a command (example: `blast qwerinope`) or with the [`use` command](#qweribucksitem-commands).

When an Item is used it is removed from the inventory of the chatter.

### Lootbox

There is no lootbox item, you just get loot when using the [`getloot` command](#qweribucksitem-commands). The cooldown is 10 minutes. You can't get loot if your itemlock is set.
Each loot drop has between 50 and 150 qbucks. Here is the drop table for items with chances.

ITEM|RATE
-|-
`grenade`|`1/5`
`blaster`|`1/5`
`tnt`|`1/50`
`silver bullet`|`1/50`

Each of these rates get pulled 3 times, then the result is added to your inventory.
It's theoretically possible to get 3 of each item.

As for superloot through the cheer, the qbucks range is 150-400.
Also the lootbox rates are the same, but pulled 15 times instead of 3.

The chance for superloot to fail is 50%.
There is no cooldown on superloot.

Any kind of loot is only obtainable while the stream is live.

### Redeems

Redeems will be created automatically when the bot starts.

Redeems or Pointredeems are events/commands triggered when a chatter uses their channel points.
Redeems can be enabled and disabled by moderators using the [`enableredeem` and `disableredeem` commands](#administrative-commands).
Note: The commands mentioned above require the internal name. For example, to disable the free money redeem, you do `disableredeem qbucksredeem` and not `disableredeem FREE MONEY`.
The enable and disable redeem commands have a way to enable/disable all sound alert redeems at one by specifying the redeem as `sfx` or `sound`.

When running the development database and twitch api application, the redeems will not get created. This is because twitch only allows editing or deleting rewards when the same application created the reward. (fucking stupid)

### Welcome message

Welcome message in the context of this project means 2 things:
- The message the bot says when it's the first time you're chatting in the channel.
- The personalized message the bot says when you chat for the first time during a stream.

The personalized message can be set by using the channel point redemption. The message cannot be longer than 200 characters.

### TTS

There are 2 types of TTS supported:

- Microsoft Sam
- DecTalk

Microsoft s(c)am is currently only used by `a_n_i_v` and `a_n_e_e_v`. Whenever the aniv clankers say something MS Sam will pronounce their message.

Dectalk is available for 25k channel points. If your message is longer than 2 minutes your message will get scammed. I'm not sorry, 100% deserved.

### Chatterbot/streamerbot

This depends on if the `CHATTER_IS_STREAMER` environment variable is set.
If it's `true`, the chatterbot and streamerbot are the same account.

The chatterbot is the user that types in chat. They have very minimal required scopes as interacting with the stream is always done by the streamerbot. Only things the chatterbot does is relay whispers and send chat messages.

The streamerbot (not that streamerbot) is the broadcaster. This bot needs them to authenticate as well. This account will be used to perform moderation and watch the chat.

Using one account as both chatterbot and streamerbot hasn't been tested in a long time. There may be broken features.

## Commands

### Fun commands

COMMAND|FUNCTION|USER|ALIASES|DISABLEABLE
-|-|-|-|-
`yabai`|Get a yabai rating|anyone|`yabai` `goon`|:white_check_mark:
`seiso`|Get a seiso rating|anyone|`seiso`|:white_check_mark:
`backshot`|'Backshot' a random previous chatter|anyone|`backshot`|:white_check_mark:
`roulette`|Play russian roulette for a 5 minute timeout|anyone|`roulette`|:white_check_mark:
`stats [target]`|Get timeout and some item stats for yourself or specified user this month|anyone|`stats` `monthlystats`|:white_check_mark:
`alltime [target]`|Get timeout and some item stats for yourself or specified user of all time|anyone|`alltime` `alltimestats`|:white_check_mark:
`monthlyleaderboard`|Get the K/D leaderboard for this month [(info)](#leaderboards)|anyone|`monthlyleaderboard` `kdleaderboard` `leaderboard`|:white_check_mark:
`alltimeleaderboard`|Get the K/D leaderboard of all time [(info)](#leaderboards)|anyone|`alltimeleaderboard` `alltimekdleaderboard`|:white_check_mark:
`qbucksleaderboard`|Get the current qbucks leaderboard [(info)](#leaderboards)|anyone|`qbucksleaderboard` `moneyleaderboard` `baltop`|:white_check_mark:
`anivtimeouts`|Get the amount of timeouts, dodges and dodge percentage from aniv timeouts [(info)](#aniv-timeouts)|anyone|`anivtimeouts` `anivtimeout`|:white_check_mark:
`racetime`|Get the racetime.gg room the streamer is currently in. Needs to have twitch linked to racetime account|anyone|`racetime` `raceroom`|:white_check_mark:
`randomchatter`|Get a random chatter for whatever reason|moderators|`randomchatter`|:white_check_mark:

### Qweribucks/Item commands

COMMAND|FUNCTION|USER|ALIASES|DISABLEABLE
-|-|-|-|-
`getloot`|Get a random assortment of items and qbucks every 10 minutes. [(drop rates)](#lootbox)|anyone|`getloot` `loot` `dig` `mine`|:white_check_mark:
`iteminfo {item}`|Get item function and aliases|anyone|`iteminfo` `itemhelp` `info`|:white_check_mark:
`inventory [target]`|Get inventory contents of target or self|anyone|`inventory` `inv` `pocket`|:white_check_mark:
`getprices`|Get the current price of items in the shop|anyone|`getprices` `prices` `shop`|:white_check_mark:
`buyitem {item} [amount]`|Buy one or more items for some qbucks. Prices are [here](#items)|anyone|`buyitem` `buy` `purchase`|:white_check_mark:
`getbalance [target]`|Get balance of target or self|anyone|`getbalance` `balance` `qbucks` `qweribucks` `wallet` `getwallet`|:white_check_mark:
`give {target} {item} {amount}`|Give targeted user amount of items|anyone|`give`|:white_check_mark:
`donate {target} {amount}`|Give the targeted user some or all of your qweribucks|anyone|`donate`|:white_check_mark:
`use {item} ...`|Use item. More info at [The items section](#items)|anyone|`use` `{i}`|:x:
`admindonate {target} {amount}`|Gives the targeted user amount of qweribucks|admins|`admindonate`|:white_check_mark:
`admingive {target} {item} {amount}`|Give targeted user amount of new items|admins|`admingive`|:white_check_mark:

### Administrative commands

COMMAND|FUNCTION|USER|ALIASES|DISABLEABLE
-|-|-|-|-
`getcommands [enabled/disabled]`|Get a list of all, enabled or disabled commands|anyone|`commands` `getcommands` `getc`|:x:
`getcheers [enabled/disabled]`|Get a list of all, enabled or disabled cheers|anyone|`getcheers` `getcheer`|:x:
`gettimeout {target}`|Get the remaining timeout duration of targeted user|anyone|`gettimeout` `gett` `releasetime`|:white_check_mark:
`stacking [on/off]`|Check/set if timeouts are stacking. Only admins can set the stacking state|anyone/admins|`stacking`|:x:
`vulnchatters`|Get amount of chatters vulnerable to explosives|anyone|`vulnchatters` `vulnc` `vc`|:white_check_mark:
`disablecommand {command/item}`|Disable a specific command/item|moderator|`disablecommand`|:x:
`enablecommand {command/item}`|Re-enable a specific command/item|moderator|`enablecommand`|:x:
`disablecheer {cheer}`|Disable a specific cheer event|moderator|`disablecheer`|:x:
`enablecheer {cheer}`|Re-enable a specific cheer event|moderator|`enablecheer`|:x:
`disableredeem {internalredeemname}`|Disable a specific channel point redemption [(info)](#redeems)|moderator|`disableredeem`|:x:
`enableredeem {internalredeemname}`|Enable a specific channel point redemption [(info)](#redeems)|moderator|`enableredeem`|:x:
`getinvulns`|Get a list of every invulnerable chatter in the channel|anyone|`getinvulns`|:x:
`getadmins`|Get a list of every admin in the channel|anyone|`getadmins`|:x:
`itemlock {target}`|Toggle the itemlock on the specified target|moderator|`itemlock`|:x:
`testcheer {amount} [args]`|Create a fake cheering event|streamer/chatterbot|`testcheer`|:x:
`addinvuln {target}`|Adds an invuln user and wipes the user's inventory and wallet|moderator|`addinvuln`|:x:
`removeinvuln {target}`|Removes an invuln user|moderator|`removeinvuln`|:x:
`addbot {target}`|Adds bot status to a specific chatter|streamer/chatterbot|`addbot`|:x:
`removebot {target}`|Removes bot status from a specific chatter|streamer/chatterbot|`removebot`|:x:
`addadmin {target}`|Adds an admin|streamer/chatterbot|`addadmin`|:x:
`removeadmin {target}`|Removes an admin|streamer/chatterbot|`removeadmin`|:x:

## Whisper commands

COMMAND|FUNCTION|ALIASES
-|-|-
`ghostwhisper`|Sends a ghost whisper [(explanation)](#ghost-whispers)|`ghostwhisper` `ghost` `g`

## Items

NAME|COMMAND|FUNCTION|ALIASES|COST
-|-|-|-|-
Blaster|`blaster {target}`|Times targeted user out for 60 seconds|`blaster` `blast`|100
Grenade|`grenade`|Times a random vulnerable chatter out for 60 seconds|`grenade`|99
Silver Bullet|`silverbullet [target]`|Times targeted or random vulnerable user out for 30 minutes|`silverbullet` `execute` `{blastin}`|666
TNT|`tnt`|Give 5-10 random chatters 60 second timeouts|`tnt`|1000

## Cheers

NAME|AMOUNT|USAGE|FUNCTION
-|-|-|-
`grenade`|99|`cheer99`|Times a random vulnerable chatter out for 60 seconds. Of failure gives cheerer a grenade
`timeout`|100|`cheer100 {target}`|Times specified user out for 1 minute. On failure gives cheerer a blaster
`superloot`|150|`cheer150`|Get superloot. Details and drop rates can be found [(here)](#lootbox).
`execute`|666|`cheer666 [target]`|Times specified or random vulnerable user out for 30 minutes. On failure gives cheerer a silver bullet
`tnt`|1000|`cheer1000`|Gives 5-10 random vulnerable chatters 60 second timeouts. On failure gives cheerer a TNT
`realsilverbullet`|6666|`cheer6666 [target]`|Times specified or random vulnerable chatter out for 24 hours. On failure gives the user nothing. Get scammed.

## Point Redeems

NAME|COST|DESCRIPTION|INTERNALNAME
-|-|-|-
`Dectalk TTS`|25000|Play a custom dectalk TTS. If the sound is too long you WILL get scammed.|`dectalk`
`Set welcome message`|15000|Set the message the bot will say when you first chat during a stream (character limit is 200)|`setwelcomemsg`
`FREE MONEY`|1000|Get 100 qbucks|`qbucksredeem`
`RIPBOZO`|500|Sound: Coffeezilla calls me a conman [(source)](https://www.youtube.com/watch?v=QRvEGn7i-wM)|`sfxripbozo`
`Welcome to the Madhouse`|100|Sound: mrockstar20 says: "Welcome to the Madhouse"|`sfxmrockmadhouse`
`Eddie Scream`|100|Sound: Eddie screams|`sfxeddiescream`
`Factorio Building Destroyed`|100|Sound: Factorio Building Destroyed alert|`sfxfactorioalert`
`Fail`|100|Sound: Either the sad trumpet or trombone meme sound|`sfxfail`
