335 lines
7.4 KiB
Markdown
335 lines
7.4 KiB
Markdown
Twitch chat bot written in rust
|
|
|
|
# Quick Start
|
|
|
|
Run a Simple bot with Built in functionality
|
|
|
|
1. Generate a twitch access token
|
|
|
|
- Get a Bot Chat Token here - https://twitchtokengenerator.com
|
|
- More Info - https://dev.twitch.tv/docs/authentication
|
|
|
|
2. Define an `.env` file with the following
|
|
|
|
```
|
|
login_name=BOTNAME
|
|
access_token=ACCESS_TOKEN
|
|
bot_channels=BOTNAME
|
|
prefix=`
|
|
bot_admins=ADMIN
|
|
```
|
|
|
|
3. Build & run
|
|
|
|
```
|
|
cargo run
|
|
```
|
|
|
|
# Example Bots
|
|
|
|
Use the following commands to build and run built-in bots. No coding required!
|
|
|
|
## New Bot
|
|
Run an empty simple bot that logs into chat and has minimum built in functions
|
|
|
|
```
|
|
cargo run --bin new_bot
|
|
```
|
|
|
|
## WIP Customized Fun Bot
|
|
|
|
Run a forcebot with fun catered customizations
|
|
|
|
*ongoing work in progress*
|
|
|
|
```
|
|
cargo run --bin fun_bot
|
|
```
|
|
|
|
|
|
## Simple Debug Listener
|
|
Run a bot that listens to all messages and output to console
|
|
|
|
```
|
|
cargo run --bin simple_debug_listener
|
|
```
|
|
|
|
## Simple Command Bot
|
|
Run a bot that uses the `test` chat `Command` . `Commands` are prefixed and must be ran by a chatter with a `vip` badge or above
|
|
|
|
```
|
|
cargo run --bin simple_command_bot
|
|
```
|
|
|
|
## Moderator Reactor
|
|
Run a bot that listens for messages with the `moderator` badge, and replies to that mod with an emote
|
|
|
|
```
|
|
cargo run --bin moderator_reactor
|
|
```
|
|
|
|
## Module loaded Bot
|
|
Run a bot that has a `test` chat `Command`. As the command was loaded through a module, moderators or broadcastors can `enable` or `disable` the module through chat commands
|
|
|
|
```
|
|
cargo run --bin simple_module
|
|
```
|
|
|
|
|
|
# Example Code
|
|
|
|
## New Bot
|
|
|
|
Uses Env defined variables to create and run the bot
|
|
|
|
```rust
|
|
use forcebot_rs_v2::Bot;
|
|
|
|
#[tokio::main]
|
|
pub async fn main() {
|
|
|
|
/* 1. Create the bot using env */
|
|
let bot = Bot::new();
|
|
|
|
/* 2. Run the bot */
|
|
bot.run().await;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
## Customize with Modules
|
|
|
|
A `Module` is a group of bot objects (eg `Command`) that elevated users can manage through built in `disable` and `enable` commands
|
|
|
|
Create a custom `Module` by :
|
|
|
|
1. Defining Functions that create the Custom Bot Objects (eg `Command`)
|
|
|
|
2. Define a function that creates a `Module` with the Custom Bot Objects loaded
|
|
|
|
|
|
```rust
|
|
use forcebot_rs_v2::Bot;
|
|
|
|
#[tokio::main]
|
|
pub async fn main() {
|
|
|
|
/* Create the bot using env */
|
|
let mut bot = Bot::new();
|
|
|
|
/* load the Module */
|
|
bot.load_module(custom_mod::new());
|
|
|
|
/* Run the bot */
|
|
bot.run().await;
|
|
|
|
}
|
|
|
|
|
|
pub mod custom_mod {
|
|
use std::sync::Arc;
|
|
|
|
use forcebot_rs_v2::{asyncfn_box, Badge, Bot, Command, Module};
|
|
use twitch_irc::message::ServerMessage;
|
|
|
|
|
|
/// Module with a loaded command
|
|
pub fn new() -> Module {
|
|
/* 1. Create a new module */
|
|
let mut custom_mod = Module::new("test".to_string(), "".to_string());
|
|
|
|
/* 2. Load the cmd into a new module */
|
|
custom_mod.load_command(cmd_test());
|
|
|
|
custom_mod
|
|
|
|
}
|
|
|
|
pub fn cmd_test() -> Command {
|
|
/* 1. Create a new cmd */
|
|
let mut cmd = Command::new("test".to_string(),"".to_string());
|
|
|
|
/* 2. Define exec callback */
|
|
async fn execbody(bot:Arc<Bot>,message:ServerMessage) -> Result<String,String> {
|
|
if let ServerMessage::Privmsg(msg) = message {
|
|
let _= bot.client.say_in_reply_to(
|
|
&msg, "test return".to_string()).await;
|
|
}
|
|
Result::Err("Not Valid message type".to_string())
|
|
}
|
|
|
|
/* 3. Set Command flags */
|
|
cmd.set_exec_fn(asyncfn_box(execbody));
|
|
cmd.set_admin_only(false);
|
|
cmd.set_min_badge(Badge::Moderator);
|
|
|
|
cmd
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
## Simple Debug Listener
|
|
Bot with a simple listener that listens for all messages and prints in output
|
|
|
|
```rust
|
|
use std::sync::Arc;
|
|
|
|
use forcebot_rs_v2::{asyncfn_box, Bot, Listener};
|
|
use twitch_irc::message::ServerMessage;
|
|
|
|
#[tokio::main]
|
|
pub async fn main() {
|
|
|
|
/* 1. Create the bot using env */
|
|
let mut bot = Bot::new();
|
|
|
|
/* 2a. Create a new blank Listener */
|
|
let mut listener = Listener::new();
|
|
|
|
/* 2b. Set a trigger condition function for listener */
|
|
listener.set_trigger_cond_fn(
|
|
|_:Arc<Bot>,_:ServerMessage| true
|
|
);
|
|
|
|
/* 2c. Define an async fn callback execution */
|
|
async fn execbody(_:Arc<Bot>,message:ServerMessage) -> Result<String,String> {
|
|
dbg!(message);
|
|
Result::Ok("Success".to_string())
|
|
}
|
|
|
|
/* 2d. Set and Store the execution body using `async_box()` */
|
|
listener.set_exec_fn(asyncfn_box(execbody));
|
|
|
|
/* 3. Load the listener into the bot */
|
|
bot.load_listener(listener);
|
|
|
|
/* 4. Run the bot */
|
|
bot.run().await;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
## Moderator Reactor
|
|
|
|
Example listener listens for a moderator badge and reply in chat
|
|
|
|
```rust
|
|
use std::sync::Arc;
|
|
|
|
use forcebot_rs_v2::Bot;
|
|
use forcebot_rs_v2::asyncfn_box;
|
|
use forcebot_rs_v2::Listener;
|
|
use twitch_irc::message::ServerMessage;
|
|
|
|
|
|
#[tokio::main]
|
|
pub async fn main() {
|
|
|
|
/* Create the bot using env */
|
|
let mut bot = Bot::new();
|
|
|
|
/* 1. Create a new blank Listener */
|
|
let mut listener = Listener::new();
|
|
|
|
/* 2. Set a trigger condition function for listener */
|
|
listener.set_trigger_cond_fn(
|
|
|_:Arc<Bot>,message:ServerMessage|
|
|
if let ServerMessage::Privmsg(msg) = message {
|
|
|
|
for badge in msg.badges {
|
|
if matches!(badge, x if x.name == "moderator") {
|
|
// dbg!("moderator found");
|
|
return true;
|
|
}
|
|
}
|
|
false
|
|
} else { false }
|
|
);
|
|
|
|
/* 3. Define an async fn callback execution */
|
|
async fn execbody(bot:Arc<Bot>,message:ServerMessage) -> Result<String,String> {
|
|
if let ServerMessage::Privmsg(msg) = message {
|
|
let _ = bot.client.say_in_reply_to(&msg, "pepeKneel".to_string()).await ;
|
|
return Result::Ok("Success".to_string()) ;
|
|
}
|
|
Result::Err("Not Valid message type".to_string())
|
|
}
|
|
|
|
/* 4. Set and Store the execution body using `async_box()` */
|
|
listener.set_exec_fn(asyncfn_box(execbody));
|
|
|
|
/* 5. Load the listener into the bot */
|
|
bot.load_listener(listener);
|
|
|
|
/* Run the bot */
|
|
bot.run().await;
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
## Simple Test Command
|
|
|
|
```rust
|
|
use std::sync::Arc;
|
|
|
|
use forcebot_rs_v2::Bot;
|
|
use forcebot_rs_v2::asyncfn_box;
|
|
use forcebot_rs_v2::Command;
|
|
use twitch_irc::message::ServerMessage;
|
|
|
|
|
|
#[tokio::main]
|
|
pub async fn main() {
|
|
|
|
/* Create the bot using env */
|
|
let mut bot = Bot::new();
|
|
|
|
/* 1. Create a new blank cmd */
|
|
let mut cmd = Command::new("test".to_string(),"".to_string());
|
|
|
|
/* 2. Define an async fn callback execution */
|
|
async fn execbody(bot:Arc<Bot>,message:ServerMessage) -> Result<String,String> {
|
|
if let ServerMessage::Privmsg(msg) = message {
|
|
let _ = bot.client.say_in_reply_to(&msg, String::from("test success")).await;
|
|
return Result::Ok("Success".to_string()) ;
|
|
}
|
|
Result::Err("Not Valid message type".to_string())
|
|
}
|
|
|
|
/* 3. Set and Store the execution body using `async_box()` */
|
|
cmd.set_exec_fn(asyncfn_box(execbody));
|
|
|
|
/* 4. optionally, remove admin only default flag */
|
|
cmd.set_admin_only(false);
|
|
|
|
/* 5. optionally, set min badge*/
|
|
cmd.set_min_badge("broadcaster".to_string());
|
|
//
|
|
/* 6. Load the cmd into the bot */
|
|
bot.load_command(cmd);
|
|
|
|
/* Run the bot */
|
|
bot.run().await;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
# Crate Rust Documentation
|
|
|
|
Create Crate documentation
|
|
|
|
Clean Build Documentation
|
|
```
|
|
cargo clean && cargo doc
|
|
```
|
|
|
|
Open Crate Doc
|
|
```
|
|
cargo doc --open
|
|
```
|