EllieBotDevs/EllieBot-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Updated the documentation

Browse source 
This took way too long
This commit is contained in:
Toastie 2024-06-25 23:22:36 +12:00
parent b798bd0d43
commit 4dc93e5871
Signed by: toastie_t0ast
GPG key ID: 27F3B6855AFD40A4
19 changed files with 1364 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
content/supportchild/_index.md → content/Ellie/Features/_index.md
View file

@ -1,9 +1,10 @@
+++
archetype = "chapter"
title = "SupportChild"
title = "EllieBot Features"
description = "Under this category you can find guides on how to use some of EllieBot's features."
weight = 2
+++
Under this category you can find guides on how to do some things with SupportChild.
Under this category you can find guides on how to do some things with EllieBot.
{{%children containerstyle="div" style="h2" description="true" %}}

75
content/Ellie/Features/config-guide.md Normal file
View file

@ -0,0 +1,75 @@
+++
title = "Config"
description = "How to use Ellie's config command"
weight = 6
+++
`.config` gives you a fast and easy way to edit most bot settings/values. Use `.h .config` for explanation.
Use `.config` to see the list of editable config files
Use `.config <config-name>` to see the list of settable properties on that config
Use `.config <config-name> <setting>` to see the current value and description
Use `.config <config-name> <setting> value` to set a new value
All settings are only available if you edit `data/[config-name].yml` files manually.
If you edit the files manually, you can reload configuration with `.configreload <config-name>`
The list below is not complete. Use commands above to see up-to-date list for your version.
## XP
`txt.cooldown` - Sets a timeout value in which a user cannot gain any more xp from sent messages. ( Value is in minutes )
`txt.per_msg` - Sets a value for the amount of xp a user will receive from sending a message.
`voice.per_minute` - Sets how much xp a user will receive from being active in a voice channel.
`voice.max_minutes` - Restricts a users xp gain to a certain amount of time spent in a voice channel.
*more settings may be available in `data/xp.yml` file*
## Games
`trivia.min_win_req` - Restricts a user's ability to make a trivia game with a win requirement less than the set value.
`trivia.currency_reward` - Sets the amount of currency a user will win if they place first in a completed trivia game.
`hangman.currency_reward` - Sets the amount of currency a user will win if they win a game of hangman.
`chatbot` - Sets which chatbot API the bot should use, values: `gpt3`, `cleverbot`.
`gpt.model` - Sets which GPT-3 model the bot should use, values: `ada001`, `babbage001`, `curie001`, `davinci003`.
`gpt.max_tokens` - Sets the limit of tokens GPT-3 can use per call. Find out more about tokens [here](https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them).
*more settings may be available in `data/games.yml` file*
## Bot
`color.ok` - Sets a hex color that will be shown on the side bar of a successful command.
`color.error` - Sets a hex color that will be shown on the side bar of an unsuccessful command.
`color.pending` - Sets a hex color that will be shown on the side bar of a command that is currently in progress.
`help.text` - The text a user is DM'd when they invoke the `.h` command.
`help.dmtext` - The text a user will receive when they DM the bot directly.
`console.type` - Sets the style in which commands will show up in your console, values: `Simple`, `Normal`, `None`.
`locale` - Sets your native bot language, run the `.langli` command in a Discord channel for a full list of language options.
`prefix` - Sets default prefix for your bot.
*more settings may be available in `data/bot.yml` file*
## Gambling
`currency.name` - Sets the name for your bot's currency.
`currency.sign` - Sets the icon for your currency.
`minbet` - Minimum amount users can bet
`maxbet` - Maximum amount users can bet. Set 0 for unlimited
`gen.min` - Sets the minimum amount that can be spawned with `.gc` active.
`gen.max` - Sets the maximum amount that can be spawned with `.gc` active.
`gen.cd` - Sets a cooldown on how often a flower can spawn with `.gc` active ( Value is in seconds ).
`gen.chance` - Sets the likelihood that flowers will spawn with `.gc`. Value: ( 0.02 = 2% | 1 + 100% ).
`gen.has_pw` - Toggles wether the generated flowers will have a password at the top left of the image. Value: `true` or `false`
`bf.multi` - Sets the amount fo currency a user will win off of a winning a bet flip.
`waifu.min_price` - Sets the minimum price a user must pay to claim a user as their waifu.
`waifu.multi.reset` - Sets a multiplier for the `.waifureset` command.
`waifu.multi.crush_claim` - Sets a discount for a user that is claiming another user that has their affinity set to them.
`waifu.multi.normal_claim` - Amount a user would have to spend to claim a waifu with no affinity set.
`waifu.multi.divorce_value` - Sets how much a user would get if they divorce a waifu.
`waifu.multi.all_gifts` - Sets how much of a gifts value will be added to the value of the gifted waifu.
`waifu.multi.gift_effect` - Sets a bonus amount that a waifu will receive if they have their affinity set to the gifter.
`decay.percent` - Sets the percentage to decay all users currency daily.
`decay.maxdecay` - Sets the maximum a amount that a user's currency can decay in a day.
`decay.threshold` - Sets the minimum amount that a user must have to be eligible to receive a decay.
*more settings may be available in `data/gambling.yml` file*

70
content/Ellie/Features/creds-guide.md Normal file
View file

@ -0,0 +1,70 @@
+++
title = "Basic Creds"
description = "How to configure EllieBot using the creds.yml file"
weight = 1
+++
## Creds Guide
This document aims to guide you through the process of creating a Discord account for your bot
(the Discord Bot application), and inviting that account into your Discord server.
![Create a bot application and copy token to creds.yml file](https://cdn.elliebot.net/bot-creds-guide.gif)
- Go to [the Discord developer application page][DiscordApp].
- Log in with your Discord account.
- Click **New Application**.
- Fill out the `Name` field however you like.
- Go to the **Bot** tab on the left sidebar.
- Click on the `Add a Bot` button and confirm that you do want to add a bot to this app.
- **Optional:** Add bot's avatar and description.
- Copy your Token to `creds.yml` as shown above.
- Scroll down to the **`Privileged Gateway Intents`** section
- **Enable the following:**
- **PRESENCE INTENT**
- **SERVER MEMBERS INTENT**
- **MESSAGE CONTENT INTENT**
These are required for a number of features to function properly, and all should be on.
##### Getting Owner ID*(s)*:
- Go to your Discord server and attempt to mention yourself, but put a backslash at the start
*(to make it slightly easier, add the backslash after the mention has been typed)*.
- For example, the message `\@toastie_t0ast` will appear as `<@234542843732033537>` after you send the message.
- The message will appear as a mention if done correctly. Copy the numbers from it **`234542843732033537`** and replace the big number on the `OwnerIds` section with your user ID.
- Save the `creds.yml` file.
- If done correctly, you should now be the bot owner. You can add multiple owners by adding them below the first one. Indentation matters.
For a single owner, it should look like this:
```yml
OwnerIds:
- 105635576866156544
```
For multiple owners, it should look like this:
```yml
OwnerIds:
- 105635123466156544
- 234542843732033537
- 341420590009417729
```
#### Inviting your bot to your server
![Invite the bot to your server](https://cdn.elliebot.net/bot-invite-guide.gif)
- On the **General Information** tab, copy your `Application ID` from your [applications page][DiscordApp].
- Replace the `YOUR_CLIENT_ID_HERE` in this link:
`https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID_HERE&scope=bot&permissions=66186303` with your `Client ID`
- The link should now look something like this:
`https://discord.com/oauth2/authorize?client_id=123123123123&scope=bot&permissions=66186303`
- Access that newly created link, pick your Discord server, click `Authorize` and confirm with the captcha at the end
- The bot should now be in your server
That's it! You may now go back to the installation guide you were following before 🎉
[DiscordApp]: https://discordapp.com/developers/applications/me

6
content/Ellie/expressions.md → content/Ellie/Features/expressions.md
View file

@ -1,14 +1,14 @@
+++
title = "Ellie Expressions"
description = "How to use Ellie's expressions system"
weight = 1
weight = 4
+++
### Important
- For modifying **global** custom reactions, the ones which will work across all the servers Ellie is connected to, you **must** be a Bot Owner.
- For modifying **global** custom reactions, the ones which will work across all the servers Ellie is connected to, you **must** be a Bot Owner.
You must also use the commands for adding, deleting and listing these reactions in a direct message with the bot.
- For modifying **local** custom reactions, the ones which will only work on the server that they are added on, it is required to have the **Administrator** permission.
- For modifying **local** custom reactions, the ones which will only work on the server that they are added on, it is required to have the **Administrator** permission.
You must also use the commands for adding, deleting and listing these reactions in the server you want the custom reactions to work on.
### Commands and Their Use

0
content/Ellie/permissions-system.md → content/Ellie/Features/permissions-system.md
View file

28
content/Ellie/placeholders.md → content/Ellie/Features/placeholders.md
View file

@ -1,7 +1,7 @@
+++
title = "Ellie Placeholders"
description = "How to use Ellie's placeholders system"
weight = 2
weight = 5
+++
Placeholders are used in Quotes, Expressions, Greet/Bye messages, playing statuses, and a few other places.
@ -62,21 +62,21 @@ Some features have their own specific placeholders which are noted in that featu
- `%user.joined_time%` - Account join time (local time)
- `%user.joined_date%` - Account join date
### Ban message placeholders
### Ban message placeholders
- `%ban.mod%` - Full name of the moderator who performed the ban
- `%ban.mod.fullname%` - Full name of the moderator who performed the ban
- `%ban.mod.mention%` - Moderator's mention
- `%ban.mod.name%` - Name of the moderator - Admin
- `%ban.mod.discrim%` - Discriminator of the moderator - 1234
- `%ban.user%` - Full name of the banned user
- `%ban.user.fullname%` - Full name of the banned user
- `%ban.user.name%` - Name of the banned user
- `%ban.user.discrim%` - Discriminator of the banned user
- `%ban.reason%` - Reason for the ban, if provided
- `%ban.duration%` - Duration of the ban in the form Days.Hours:Minutes (6.05:04)
- `%ban.mod%` - Full name of the moderator who performed the ban
- `%ban.mod.fullname%` - Full name of the moderator who performed the ban
- `%ban.mod.mention%` - Moderator's mention
- `%ban.mod.name%` - Name of the moderator - Admin
- `%ban.mod.discrim%` - Discriminator of the moderator - 1234
- `%ban.user%` - Full name of the banned user
- `%ban.user.fullname%` - Full name of the banned user
- `%ban.user.name%` - Name of the banned user
- `%ban.user.discrim%` - Discriminator of the banned user
- `%ban.reason%` - Reason for the ban, if provided
- `%ban.duration%` - Duration of the ban in the form Days.Hours:Minutes (6.05:04)
### Shard stats placeholders
### Shard stats placeholders
- `%shard.servercount%` - Server count on current shard
- `%shard.usercount%` - Combined user count on current shard

239
content/Ellie/Features/yml-explained.md Normal file
View file

@ -0,0 +1,239 @@
+++
title = "Advanced Creds"
description = "Setting up your API keys"
weight = 2
+++
## Setting up your API keys
This part is completely optional, **however it's necessary for music and a few other features to work properly**.
- **GoogleAPIKey**
- Required for Youtube Song Search, Playlist queuing, and a few more things.
- Follow these steps on how to setup Google API keys:
- Go to [Google Console][Google Console] and log in.
- Create a new project (name does not matter).
- Once the project is created, go into `Library`
- Under the `YouTube APIs` section
- Select `YouTube Data API v3`,
- Click enable.
- Search for `Custom Search API`
- Select `Custom Search API`,
- Click enable.
- Open up the `Navigation menu` on the top right with the three lines.
- select `APIs & Services`, then select `Credentials`,
- Click `Create Credentials` button,
- Click on `API Key`
- A new window will appear with your `Google API key`
*NOTE: You don't really need to click on `RESTRICT KEY`, just click on `CLOSE` when you are done.*
- Copy the key.
- Open up `creds.yml` and look for `GoogleAPIKey`, paste your API key after the `:`.
- It should look like this:
```yml
GoogleApiKey: 'AIzaSyDSci1sdlWQOWNVj1vlXxxxxxbk0oWMEzM'
```
- **MashapeKey**
- Required for Hearthstone cards.
- Api key obtained on https://rapidapi.com (register -> go to MyApps -> Add New App -> Enter Name -> Application key)
- Copy the key and paste it into `creds.yml`
- **OsuApiKey**
- Required for Osu commands
- You can get this key [here](https://osu.ppy.sh/p/api).
- **CleverbotApiKey**
- Required if you want to use Cleverbot. It's currently a paid service.
- You can get this key [here](http://www.cleverbot.com/api/).
- **PatreonAccessToken**
- For Patreon creators only.
- **PatreonCampaignId**
- For Patreon creators only. Id of your campaign.
- **TwitchClientId and TwitchClientSecret**
- Mandatory for following twitch streams with `.twitch` (or `.stadd` with twitch link)
- Go to [apps page](https://dev.twitch.tv/console) on twitch and register your application.
- You need 2FA enabled on twitch in order to create an application
- You can set `http://localhost` as the OAuth Redirect URL (and press Add button)
- Select `Chat Bot` from the Category dropdown
- Once created, `click Manage`
- Click `New Secret` and select `OK` in the popup
**Note: You will need to generate a new Client Secret everytime you exit the page**
- Copy both to your creds.yml as shown below
```yml
twitchClientId: 516tr61tr1qweqwe86trg3g
twitchClientSecret: 16tr61tr1q86tweqwe
```
- **LocationIqApiKey**
- Optional. Used only for the `.time` command. https://locationiq.com api key (register and you will receive the token in the email).
- **TimezoneDbApiKey**
- Optional. Used only for the `.time` command. https://timezonedb.com api key (register and you will receive the token in the email **YOU HAVE TO ACTIVEATE IT AFTER YOU GET IT**).
- **CoinmarketcapApiKey**
- Optional. Used only for the `.crypto` command. You can use crypto command without it, but you might get ratelimited from time to time, as all self-hosters share the default api key. https://pro.coinmarketcap.com/
##### Additional Settings
- **TotalShards**
- Required if the bot will be connected to more than 2500 servers.
- Most likely unnecessary to change until your bot is added to more than 2500 servers.
- **RedisOptions**
- Required if the Redis instance is not on localhost or on non-default port.
- You can find all available options [here](https://stackexchange.github.io/StackExchange.Redis/Configuration.html).
- **RestartCommand**
- Required if you want to be able to use the `.restart` command
- If you're using the CLI installer or Linux/OSX, it's easier and more reliable setup Ellie with auto-restart and just use `.die`
For Windows (Updater), add this to your `creds.yml`
```yml
RestartCommand:
Cmd: "EllieBot.exe"
args: "{0}"
```
For Windows (Source), Linux or OSX, add this to your `creds.yml`
```yml
RestartCommand:
Cmd: dotnet
Args: "EllieBot.dll -- {0}"
```
---
#### End Result
**This is an example of how the `creds.yml` looks like with multiple owners, the restart command (optional) and some of the API keys (also optional):**
```yml
# DO NOT CHANGE
version: 4
# Bot token. Do not share with anyone ever -> https://discordapp.com/developers/applications/
token: 'MTE5Nzc3MDIxMzE5NTc3NjEw.VlhNCw.BuqJFyzdIUAK1PRf1eK1Cu89Jew'
# List of Ids of the users who have bot owner permissions
# **DO NOT ADD PEOPLE YOU DON'T TRUST**
ownerIds:
- 105635123466156544
- 145521851676884992
- 341420590009417729
# The number of shards that the bot will running on.
# Leave at 1 if you don't know what you're doing.
totalShards: 1
# Login to https://console.cloud.google.com, create a new project, go to APIs & Services -> Library -> YouTube Data API and enable it.
# Then, go to APIs and Services -> Credentials and click Create credentials -> API key.
# Used only for Youtube Data Api (at the moment).
googleApiKey: 'AIzaSyDScfdfdfi1sdlWQOWxxxxxbk0oWMEzM'
# Settings for voting system for discordbots. Meant for use on global Ellie.
votes:
url: ''
key: ''
# Patreon auto reward system settings.
# go to https://www.patreon.com/portal -> my clients -> create client
patreon:
# Access token. You have to manually update this 1st of each month by refreshing the token on https://patreon.com/portal
accessToken: ''
# Unused atm
refreshToken: ''
# Unused atm
clientSecret: ''
# Campaign ID of your patreon page. Go to your patreon page (make sure you're logged in) and type "prompt('Campaign ID', window.patreon.bootstrap.creator.data.id);" in the console. (ctrl + shift + i)
campaignId: ''
# Api key for sending stats to DiscordBotList.
botListToken: ''
# Official cleverbot api key.
cleverbotApiKey: ''
# Redis connection string. Don't change if you don't know what you're doing.
redisOptions: localhost:6379,syncTimeout=30000,responseTimeout=30000,allowAdmin=true,password=
# Database options. Don't change if you don't know what you're doing. Leave null for default values
db:
# Database type. Only sqlite supported atm
type: sqlite
# Connection string. Will default to "Data Source=data/EllieBot.db"
connectionString: Data Source=data/EllieBot.db
# Address and port of the coordinator endpoint. Leave empty for default.
# Change only if you've changed the coordinator address or port.
coordinatorUrl: http://localhost:3442
# Api key obtained on https://rapidapi.com (go to MyApps -> Add New App -> Enter Name -> Application key)
rapidApiKey: 4UrKpcWXcxxxxxxxxxxxxxxp1Q8kI6jsn32xxxoVWiY7
# https://locationiq.com api key (register and you will receive the token in the email).
# Used only for .time command.
locationIqApiKey:
# https://timezonedb.com api key (register and you will receive the token in the email).
# Used only for .time command
timezoneDbApiKey:
# https://pro.coinmarketcap.com/account/ api key. There is a free plan for personal use.
# Used for cryptocurrency related commands.
coinmarketcapApiKey:
# Api key used for Osu related commands. Obtain this key at https://osu.ppy.sh/p/api
osuApiKey: 4c8c8fdffdsfdsfsdfsfa33f3f3140a7d93320d6
# Optional Trovo client id.
# You should use this if Trovo stream notifications stopped working or you're getting ratelimit errors.
trovoClientId:
# Obtain by creating an application at https://dev.twitch.tv/console/apps
twitchClientId: jf2w6kkyrlzfl6mp1b4k25h4jr6b2o
# Obtain by creating an application at https://dev.twitch.tv/console/apps
twitchClientSecret: 16tr61tr1q86tweqwe
# Command and args which will be used to restart the bot.
# Only used if bot is executed directly (NOT through the coordinator)
# placeholders:
# {0} -> shard id
# {1} -> total shards
# Linux default
# cmd: dotnet
# args: "EllieBot.dll -- {0}"
# Windows default
# cmd: "EllieBot.exe"
# args: "{0}"
restartCommand:
cmd:
args:
```
---
## Database
Ellie saves all settings and data in the database file `EllieBot.db`, located in:
- Windows (Updater): `system/data` (can be easily accessed through the `Data` button on the updater)
- Windows (Source), Linux and OSX: `elliebot/output/data/EllieBot.db`
In order to open it you will need [SQLite Browser](http://sqlitebrowser.org/).
*NOTE: You don't have to worry if you don't have the `EllieBot.db` file, it gets automatically created once you successfully run the bot for the first time.*
**To make changes to the database on windows:**
- Shut your bot down.
- Copy the `EllieBot.db` file to someplace safe. (Back up)
- Open it with SQLite Browser.
- Go to the **Browse Data** tab.
- Click on the **Table** drop-down list.
- Choose the table you want to edit.
- Click on the cell you want to edit.
- Edit it on the right-hand side.
- Click on **Apply**.
- Click on **Write Changes**.
---
## Sharding your bot
To run a sharded bot, you will want to run `src/EllieBot.Coordinator` project.
Shards communicate with the coordinator using gRPC
To configure your Coordinator, you will need to edit the `src/EllieBot.Coordinator/coord.yml` file
```yml
# total number of shards
TotalShards: 3
# How often do shards ping their state back to the coordinator
RecheckIntervalMs: 5000
# Command to run the shard
ShardStartCommand: dotnet
# Arguments to run the shard
# {0} = shard id
# {1} = total number of shards
ShardStartArgs: ../../output/EllieBot.dll -- {0} {1}
# How long does it take for the shard to be forcefully restarted once it stops reporting its state
UnresponsiveSec: 30
```
[Google Console]: https://console.developers.google.com
[DiscordApp]: https://discordapp.com/developers/applications/me
[Invite Guide]: https://tukimoop.pw/s/guide.html

10
content/Ellie/Guides/_index.md Normal file
View file

@ -0,0 +1,10 @@
+++
archetype = "chapter"
title = "EllieBot Install guides"
description = "Under this category you can find guides on how to host your own EllieBot."
weight = 1
+++
Under this category you can find guides on how to host your own EllieBot.
{{%children containerstyle="div" style="h2" description="true" %}}

378
content/Ellie/Guides/linux-guide.md Normal file
View file

@ -0,0 +1,378 @@
+++
title = "Linux Guide"
description = "How to set up EllieBot on Linux"
weight = 4
+++
# Setting up EllieBot on Linux
| Table of Contents |
| :-------------------------------------------------- |
| [Linux From Source] |
| [Source Update Instructions] |
| [Linux Release] |
| [Release Update Instructions] |
| [Tmux (Preferred Method)] |
| [Systemd] |
| [Systemd + Script] |
| [Setting up Ellie on a VPS (Digital Ocean)] |
#### Operating System Compatibility
##### Compatible operating systems:
- Ubuntu: 20.04, 22.04, 24.04
- Mint: 19, 20, 21
- Debian: 10, 11, 12
- RockyLinux: 8, 9
- AlmaLinux: 8, 9
- openSUSE Leap: 15.5, 15.6 & Tumbleweed
- Fedora: 38, 39, 40, 41, 42
## Linux From Source
##### Migration from v3 -> v5
Follow the following few steps only if you're migrating from v3. If not, skip to installation instructions.
Use the new installer script: `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
> - Install prerequisites (type `1` and press `enter`)
> - Download (type `2` and press `enter`)
> - Run (type `3` and press `enter`)
> - Done
##### Installation Instructions
Open Terminal (if you're on an installation with a window manager) and navigate to the location where you want to install the bot (for example `cd ~`)
1. Download and run the **new** installer script `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
2. Install prerequisites (type `1` and press enter)
3. Download the bot (type `2` and press enter)
4. Exit the installer (type `6` and press enter)
5. Copy the creds.yml template `cp elliebot/output/creds_example.yml elliebot/output/creds.yml`
6. Open `elliebot/output/creds.yml` with your favorite text editor. We will use nano here
- `nano elliebot/output/creds.yml`
7. [Click here to follow creds guide](../Features/creds-guide)
- After you're done, you can close nano (and save the file) by inputting, in order
- `CTRL` + `X`
- `Y`
- `Enter`
8. Run the installer script again `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
9. Run the bot (type `3` and press enter)
##### Source Update Instructions
1. ⚠ Stop the bot ⚠
2. Update and run the **new** installer script `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
3. Update the bot (type `2` and press enter)
4. Run the bot (type `3` and press enter)
5. 🎉
## **⚠ IF YOU ARE FOLLOWING THE GUIDE ABOVE, IGNORE THIS SECTION ⚠**
## Linux Release
###### Prerequisites
1. (Optional) Installing Redis
- ubuntu installation command: `sudo apt-get install redis-server`
2. Playing music requires `ffmpeg`, `libopus`, `libsodium` and `yt-dlp` (which in turn requires python3)
- Ubuntu installation command: `sudo apt-get install ffmpeg libopus0 opus-tools libopus-dev libsodium-dev -y`
- yt-dlp installation command: `sudo wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp && sudo chmod a+rx /usr/local/bin/yt-dlp`
3. Make sure your python is version 3+ with `python --version`
- if it's not, you can install python 3 and make it the default with: `sudo apt-get install python3.8 python-is-python3`
*You can use ellie bash script [prerequisites installer](https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/e-prereq.sh) as a reference*
##### Installation Instructions
1. Download the latest release from <https://toastielab.dev/Emotions-stuff/elliebot/releases>
- Look for the file called "X.XX.X-linux-x64-build.tar" (where X.XX.X is a series of numbers) and download it
2. Untar it
- ⚠ Make sure that you change X.XX.X to the same series of numbers as in step 1!
- `tar xf X.XX.X-linux-x64-build.tar`
3. Rename the `elliebot-linux-x64` to `elliebot`
- `mv elliebot-linux-x64 elliebot`
4. Move into elliebot directory and make EllieBot executable
- `cd elliebot && chmod +x EllieBot`
5. Copy the creds.yml template
- `cp creds_example.yml creds.yml`
6. Open `creds.yml` with your favorite text editor. We will use nano here
- `nano elliebot/output/creds.yml`
8. [Click here to follow creds guide](../Features/creds-guide)
- After you're done, you can close nano (and save the file) by inputting, in order
- `CTRL` + `X`
- `Y`
- `Enter`
9. Run the bot
- `./EllieBot`
##### Release Update Instructions
1. Stop the bot
2. Download the latest release from <https://toastielab.dev/Emotions-stuff/elliebot/releases>
- Look for the file called "x.x.x-linux-x64-build.tar" (where `X.X.X` is a version, for example 3.0.4) and download it
3. Untar it
- ⚠ Make sure that you change `X.X.X` to the same series of numbers as in step 2!
- `tar xf x.x.x-linux-x64-build.tar`
4. Rename the old elliebot directory to elliebot-old (remove your old backup first if you have one, or back it up under a different name)
- `rm -rf elliebot-old 2>/dev/null`
- `mv elliebot elliebot-old`
5. Rename the new elliebot directory to elliebot
- `mv elliebot-linux-x64 elliebot`
6. Remove old strings and aliases to avoid overwriting the updated versions of those files
- ⚠ If you've modified said files, back them up instead
- `rm elliebot-old/data/aliases.yml`
- `rm -r elliebot-old/data/strings`
7. Copy old data
- `cp -RT elliebot-old/data/ elliebot/data`
8. Copy creds.yml
- `cp elliebot-old/creds.yml elliebot/`
9. Move into elliebot directory and make the EllieBot executable
- `cd elliebot && chmod +x EllieBot`
10. Run the bot
- `./EllieBot`
🎉 Enjoy
##### Steps 3 - 9 as a single command
Don't forget to change X.XX.X to match step 2.
```sh
tar xf X.XX.X-linux-x64-build.tar && \
rm -rf elliebot-old 2>/dev/null && \
mv elliebot elliebot-old && \
mv elliebot-linux-x64 elliebot && \
rm elliebot-old/data/aliases.yml && \
rm -r elliebot-old/data/strings && \
cp -RT elliebot-old/data/ elliebot/data && \
cp elliebot-old/creds.yml elliebot/ && \
cd elliebot && chmod +x EllieBot
```
## Running Ellie
While there are two run modes built into the installer, these options only run Ellie within the current session. Below are 3 methods of running Ellie as a background process.
### Tmux Method (Preferred)
Using `tmux` is the simplest method, and is therefore recommended for most users.
**Before proceeding, make sure your bot is not running by either running `.die` in your Discord server or exiting the process with `Ctrl+C`.**
If you are presented with the installer main menu, exit it by choosing Option `8`.
1. Create a new session: `tmux new -s ellie`
The above command will create a new session named **ellie** *(you can replace “ellie” with anything you prefer, it's your session name)*.
2. Run the installer: `bash linuxAIO.sh`
3. There are a few options when it comes to running Ellie.
- Run `3` to *Run the bot normally*
- Run `4` to *Run the bot with Auto Restart* (This is may or may not work)
4. If option `4` was selected, you have the following options
```
1. Run Auto Restart normally without updating EllieBot.
2. Run Auto Restart and update EllieBot.
3. Exit
Choose:
[1] to Run EllieBot with Auto Restart on "die" command without updating.
[2] to Run with Auto Updating on restart after using "die" command.
```
- Run `1` to restart the bot without updating. (This is done using the `.die` command)
- Run `2` to update the bot upon restart. (This is also done using the `.die` command)
5. That's it! to detatch the tmux session:
- Press `Ctrl` + `B`
- Then press `D`
Now check your Discord server, the bot should be online. Ellie should now be running in the background of your system.
To re-open the tmux session to either update, restart, or whatever, execute `tmux a -t ellie`. *(Make sure to replace "ellie" with your session name. If you didn't change it, leave it as it.)*
### Systemd
Compared to using tmux, this method requires a little bit more work to set up, but has the benefit of allowing Ellie to automatically start back up after a system reboot or the execution of the `.die` command.
1. Navigate to the project's root directory
- Project root directory location example: `/home/user/elliebot/`
2. Use the following command to create a service that will be used to start Ellie:
```bash
echo "[Unit]
Description=EllieBot service
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=2
[Service]
Type=simple
User=$USER
WorkingDirectory=$PWD/output
# If you want Ellie to be compiled prior to every startup, uncomment the lines
# below. Note that it's not neccessary unless you are personally modifying the
# source code.
#ExecStartPre=/usr/bin/dotnet build ../src/EllieBot/EllieBot.csproj -c Release -o output/
ExecStart=/usr/bin/dotnet EllieBot.dll
Restart=on-failure
RestartSec=5
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=EllieBot
[Install]
WantedBy=multi-user.target" | sudo tee /etc/systemd/system/ellie.service
```
3. Make the new service available:
- `sudo systemctl daemon-reload`
4. Start Ellie:
- `sudo systemctl start ellie.service && sudo systemctl enable ellie.service`
### Systemd + Script
This method is similar to the one above, but requires one extra step, with the added benefit of better error logging and control over what happens before and after the startup of Ellie.
1. Locate the project and move to its parent directory
- Project location example: `/home/user/elliebot/`
- Parent directory example: `/home/user/`
2. Use the following command to create a service that will be used to execute `EllieRun.sh`:
```bash
echo "[Unit]
Description=EllieBot service
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=2
[Service]
Type=simple
User=$USER
WorkingDirectory=$_WORKING_DIR
ExecStart=/bin/bash EllieRun.sh
Restart=on-failure
RestartSec=5
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=EllieBot
[Install]
WantedBy=multi-user.target" | sudo tee /etc/systemd/system/ellie.service
```
3. Make the new service available:
- `sudo systemctl daemon-reload`
4. Use the following command to create a script that will be used to start Ellie:
```bash
{
echo '#!/bin/bash'
echo ""
echo "echo \"Running EllieBot in the background with auto restart\"
yt-dlp -U
# If you want Ellie to be compiled prior to every startup, uncomment the lines
# below. Note that it's not necessary unless you are personally modifying the
# source code.
#echo \"Compiling EllieBot...\"
#cd \"$PWD\"/elliebot
#dotnet build src/EllieBot/EllieBot.csproj -c Release -o output/
echo \"Starting EllieBot...\"
while true; do
if [[ -d $PWD/elliebot/output ]]; then
cd $PWD/elliebot/output || {
echo \"Failed to change working directory to $PWD/elliebot/output\" >&2
echo \"Ensure that the working directory inside of '/etc/systemd/system/ellie.service' is correct\"
echo \"Exiting...\"
exit 1
}
else
echo \"$PWD/elliebot/output doesn't exist\"
exit 1
fi
dotnet EllieBot.dll || {
echo \"An error occurred when trying to start NadekBot\"
echo \"Exiting...\"
exit 1
}
echo \"Waiting for 5 seconds...\"
sleep 5
yt-dlp -U
echo \"Restarting EllieBot...\"
done
echo \"Stopping EllieBot...\""
} > EllieRun.sh
```
5. Start Ellie:
- `sudo systemctl start ellie.service && sudo systemctl enable ellie.service`
### Setting up Ellie on a Linux VPS (Digital Ocean Droplet)
If you want Ellie to play music for you 24/7 without having to hosting it on your PC and want to keep it cheap, reliable and convenient as possible, you can try Ellie on Linux Digital Ocean Droplet using the link [DigitalOcean](https://m.do.co/c/1bb1db830f41) (by using this link, you will get **$10 credit** and also support Ellie)
To set up the VPS, please select the options below
```
These are the min requirements you must follow:
OS: Any between Ubuntu, Fedora, and Debian
Plan: Basic
CPU options: regular with SSD
1 GB / 1 CPU
25 GB SSD Disk
1000 GB transfer
Note: You can select the cheapest option with 512 MB /1 CPU but this has been a hit or miss.
Datacenter region: Choose one depending on where you are located.
Authentication: Password or SSH
(Select SSH if you know what you are doing, otherwise choose password)
```
**Setting up EllieBot**
Assuming you have followed the link above to setup an account and a Droplet with a 64-bit operational system on Digital Ocean and got the `IP address and root password (in your e-mail)` to login, it's time to get started.
**This section is only relevant to those who want to host Ellie on DigitalOcean. Go through this whole section before setting the bot up.**
#### Prerequisites
- Download [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
- Download [WinSCP](https://winscp.net/eng/download.php) *(optional)*
- [Create and invite the bot](../Features/creds-guide).
#### Starting up
- **Open PuTTY** and paste or enter your `IP address` and then click **Open**.
If you entered your Droplets IP address correctly, it should show **login as:** in a newly opened window.
- Now for **login as:**, type `root` and press enter.
- It should then ask for a password. Type the `root password` you have received in your e-mail address, then press Enter.
If you are running your droplet for the first time, it will most likely ask you to change your root password. To do that, copy the **password you've received by e-mail** and paste it on PuTTY.
- To paste, just right-click the window (it won't show any changes on the screen), then press Enter.
- Type a **new password** somewhere, copy and paste it on PuTTY. Press Enter then paste it again.
**Save the new password somewhere safe.**
After that, your droplet should be ready for use. [Follow the guide from the beginning](#linux-from-source) to set Ellie up on your newly created VPS.
[Linux From Source]: #linux-from-source
[Source Update Instructions]: #source-update-instructions
[Linux Release]: #linux-release
[Release Update Instructions]: #release-update-instructions
[Tmux (Preferred Method)]: #tmux-preferred-method
[Systemd]: #systemd
[Systemd + Script]: #systemd-script
[Setting up Ellie on a VPS (Digital Ocean)]: #setting-up-ellie-on-a-linux-vps-digital-ocean-droplet

131
content/Ellie/Guides/osx-guide.md Normal file
View file

@ -0,0 +1,131 @@
+++
title = "MacOS Guide"
description = "How to set up EllieBot on MacOS"
weight = 5
+++
## MacOS From Source
Open Terminal (if you don't know how to, click on the magnifying glass on the top right corner of your screen and type **Terminal** on the window that pops up) and navigate to the location where you want to install the bot (for example `cd ~`)
##### Installing Homebrew, wget and dotnet
###### Homebrew/wget
*Skip this step if you already have homebrew installed*
- Copy and paste this command, then press Enter:
- `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
- Install wget
- `brew install wget`
###### Dotnet
- Download [.net8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- Open the `.pkg` file you've downloaded and install it.
- Run this command in Terminal. There might be output. If there is, disregard it. (copy-paste the entire block)
```bash
sudo mkdir /usr/local/bin
sudo mkdir /usr/local/lib
```
- Run this command in Terminal. There won't be any output. (copy-paste the entire block):
```bash
sudo ln -s /usr/local/share/dotnet/dotnet /usr/local/bin
sudo ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
sudo ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/
```
##### Installation Instructions
1. Download and run the **new** installer script `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
2. Install prerequisites (type `1` and press enter)
3. Download the bot (type `2` and press enter)
4. Exit the installer in order to set up your `creds.yml`
5. Copy the creds.yml template
`cp elliebot/output/creds_example.yml elliebot/output/creds.yml`
6. Open `elliebot/output/creds.yml` with your favorite text editor. We will use nano here
- `nano elliebot/output/creds.yml`
7. [Enter your bot's token](#creds-guide)
- After you're done, you can close nano (and save the file) by inputting, in order
- `CTRL`+`X`
- `Y`
- `Enter`
8. Run the bot (type `3` and press enter)
##### Update Instructions
1. ⚠ Stop the bot
2. Update and run the **new** installer script `cd ~ && wget -N https://toastielab.dev/Emotions-stuff/ellie-bash-installer/raw/branch/v5/linuxAIO.sh && bash linuxAIO.sh`
3. Update the bot (type `2` and press enter)
4. Run the bot (type `3` and press enter)
5. 🎉
## MacOS Manual Release installation instructions
⚠ IF YOU ARE FOLLOWING THE GUIDE ABOVE, IGNORE THIS SECTION ⚠
##### Installation Instructions
1. Download the latest release from <https://toastielab.dev/Emotions-stuff/elliebot/releases>
- Look for the file called "X.XX.X-linux-x64-build.tar" (where X.XX.X is a series of numbers) and download it
2. Untar it
⚠ Make sure that you change X.XX.X to the same series of numbers as in step 1!
- `tar xf X.XX.X-linux-x64-build.tar`
3. Rename the `elliebot-linux-x64` to `elliebot`
- `mv elliebot-linux-x64 elliebot`
4. Move into elliebot directory and make EllieBot executable
- `cd elliebot && chmod +x EllieBot`
5. Copy the creds.yml template
- `cp creds_example.yml creds.yml`
6. Open `creds.yml` with your favorite text editor. We will use nano here
- `nano elliebot/output/creds.yml`
8. [Enter your bot's token](#creds-guide)
- After you're done, you can close nano (and save the file) by inputting, in order
- `CTRL`+`X`
- `Y`
- `Enter`
9. Run the bot
- `./EllieBot`
##### Update Instructions
1. Stop the bot
2. Download the latest release from <https://toastielab.dev/Emotions-stuff/elliebot/releases>
- Look for the file called "X.XX.X-linux-x64-build.tar" (where X.XX.X is a series of numbers) and download it
3. Untar it
⚠ Make sure that you change X.XX.X to the same series of numbers as in step 2!
- `tar xf 2.99.8-linux-x64-build.tar`
4. Rename the old elliebot directory to elliebot-old (remove your old backup first if you have one, or back it up under a different name)
- `rm -rf elliebot-old 2>/dev/null`
- `mv elliebot elliebot-old`
5. Rename the new elliebot directory to elliebot
- `mv elliebot-linux-x64 elliebot`
6. Remove old strings and aliases to avoid overwriting the updated versions of those files
⚠ If you've modified said files, back them up instead
- `rm elliebot-old/data/aliases.yml`
- `rm -r elliebot-old/data/strings`
7. Copy old data
- `cp -RT elliebot-old/data/ elliebot/data/`
8. Copy creds.yml
- `cp elliebot-old/creds.yml elliebot/`
9. Move into elliebot directory and make the EllieBot executable
- `cd elliebot && chmod +x EllieBot`
10. Run the bot
- `./EllieBot`
🎉 Enjoy
##### Steps 3 - 9 as a single command
Don't forget to change X.XX.X to match step 2.
```sh
tar xf X.XX.X-linux-x64-build.tar && \
rm -rf elliebot-old 2>/dev/null && \
mv elliebot elliebot-old && \
mv elliebot-linux-x64 elliebot && \
rm elliebot-old/data/aliases.yml && \
rm -r elliebot-old/data/strings && \
cp -RT elliebot-old/data/ elliebot/data/ && \
cp elliebot-old/creds.yml elliebot/ && \
cd elliebot && chmod +x EllieBot
```

79
content/Ellie/Guides/windows-guide.md Normal file
View file

@ -0,0 +1,79 @@
+++
title = "Windows Guide"
description = "How to set up EllieBot on Windows"
weight = 3
+++
{{% notice style="note" %}}
There is an easier way in the works but this will take time to make, sorry about that. - Toastie
{{% /notice %}}
### Windows From Source
##### Prerequisites
**Install these before proceeding or your bot will not work!**
- [.net 8](https://dotnet.microsoft.com/en-us/download) - needed to compile and run the bot
- [git](https://git-scm.com/downloads) - needed to clone the repository (you can also download the zip manually and extract it, but this guide assumes you're using git)
- [Redis] (OPTIONAL)- to cache things needed by some features and persist through restarts
##### Installation Instructions
Open PowerShell (press windows button on your keyboard and type powershell, it should show up; alternatively, right click the start menu and select Windows PowerShell), and navigate to the location where you want to install the bot (for example `cd ~/Desktop/`)
1. `git clone https://toastielab.dev/Emotions-stuff/EllieBot -b v5 --depth 1`
2. `cd EllieBot`
3. `dotnet publish -c Release -o output/ src/EllieBot/`
4. `cd output`
5. `cp creds_example.yml creds.yml`
6. Open `creds.yml` with your favorite text editor (Please don't use Notepad or WordPad. You can use Notepad++, VSCode, Atom, Sublime, or something similar)
7. [Enter your bot's token](../Features/creds-guide)
8. Run the bot `dotnet EllieBot.dll`
9. 🎉
##### Update Instructions
Open PowerShell as described above and run the following commands:
1. Stop the bot
- ⚠️ Make sure you don't have your database, credentials or any other EllieBot folder open in some application, this might prevent some of the steps from executing succesfully
2. Navigate to your bot's folder, example:
- `cd ~/Desktop/EllieBot`
3. Pull the new version, and make sure you're on the v5 branch
- *⚠️ the first 3 lines can be omitted if you're already on v5. If you're updating from v4, you must run them*
- `git remote set-branches origin '*'`
- `git fetch -v --depth=1`
- `git checkout v5`
- `git pull`
- ⚠️ If this fails, you may want to stash or remove your code changes if you don't know how to resolve merge conflicts
4. **Backup** old output in case your data is overwritten
- `cp -r -fo output/ output-old`
5. Build the bot again
- `dotnet publish -c Release -o output/ src/EllieBot/`
6. Remove old strings and aliases to avoid overwriting the updated versions of those files
- ⚠ If you've modified said files, back them up instead
- `rm output-old/data/aliases.yml`
- `rm -r output-old/data/strings`
7. Copy old data
- `cp -Recurse .\output-old\data\ .\output\ -Force`
8. Copy creds.yml
- `cp output-old/creds.yml output/`
9. Run the bot
- `cd output`
- `dotnet EllieBot.dll`
🎉 Enjoy
#### Music prerequisites
In order to use music commands, you need ffmpeg and yt-dlp installed.
- [ffmpeg-32bit] | [ffmpeg-64bit] - Download the **appropriate version** for your system (32 bit if you're running a 32 bit OS, or 64 if you're running a 64bit OS). Unzip it, and move `ffmpeg.exe` to a path that's in your PATH environment variable. If you don't know what that is, just move the `ffmpeg.exe` file to `EllieBot/output`.
- [youtube-dlp] - Click to download the `yt-dlp.exe` file, then move `yt-dlp.exe` to a path that's in your PATH environment variable. If you don't know what that is, just move the `yt-dlp.exe` file to `EllieBot/system`.
[Notepad++]: https://notepad-plus-plus.org/
[.net]: https://dotnet.microsoft.com/download/dotnet/8.0
[Redis]: https://github.com/MicrosoftArchive/redis/releases/download/win-3.0.504/Redis-x64-3.0.504.msi
[Visual C++ 2010 (x86)]: https://download.microsoft.com/download/1/6/5/165255E7-1014-4D0A-B094-B6A430A6BFFC/vcredist_x86.exe
[Visual C++ 2017 (x64)]: https://aka.ms/vs/15/release/vc_redist.x64.exe
[ffmpeg-32bit]: https://ellie.gcoms.xyz/dl/ffmpeg-32.zip
[ffmpeg-64bit]: https://ellie.gcoms.xyz/dl/ffmpeg-64.zip
[youtube-dlp]: https://github.com/yt-dlp/yt-dlp/releases

18
content/Ellie/Marmalade/_index.md Normal file
View file

@ -0,0 +1,18 @@
+++
archetype = "chapter"
title = "Ellie Marmalade"
description = "Under this category you can find guides about EllieBot's Marmalade system."
weight = 7
+++
Under this category you can find guides about EllieBot's Marmalade system.
<!--
{{% notice style="note" title="Advanced topic" %}}
This potion of the guides is more advanced than the rest of EllieBot.
This requires knowledge of C#, please proceed with caution.
{{% /notice %}}
-->
{{%children containerstyle="div" style="h2" description="true" %}}

24
content/Ellie/Marmalade/canary-lifecycle.md Normal file
View file

@ -0,0 +1,24 @@
+++
title = "Canary lifecycle!"
description = "This documents the lifecycle of canaries"
weight = 3
+++
# Canary Lifecycle
*You can override several methods to hook into command handler's lifecycle.
These methods start with `Exec*`*
- `ExecOnMessageAsync` runs first right after any message was received
- `ExecInputTransformAsync` runs after ExecOnMessageAsync and allows you to transform the message content before the bot looks for the matching command
- `ExecPreCommandAsync` runs after a command was found but not executed, allowing you to potentially prevent command execution
- `ExecPostCommandAsync` runs if the command was successfully executed
- `ExecOnNoCommandAsync` runs instead of ExecPostCommandAsync if no command was found for a message
*Besides that, canaries have 2 methods with which you can initialize and cleanup your canary*
- `InitializeAsync` Runs when the marmalade which contains this canary is being loaded
- `DisposeAsync` Runs when the marmalade which contains this canary is being unloaded

254
content/Ellie/Marmalade/creating-a-marmalade.md Normal file
View file

@ -0,0 +1,254 @@
+++
title = "Creating a marmalade!"
description = "This will hopefully guide you on how to create a marmalade"
weight = 1
+++
## Theory
### Introduction
Marmalade system allows you to write independent marmalades (known as "modules", "cogs" or "plugins" in other software) which you can then load, unload and update at will without restarting the bot.
The marmalade base classes used for development are open source [here](https://toastielab.dev/Emotions-stuff/elliebot/src/branch/v5/src/Ellie.Marmalade) in case you need reference, as there is no generated documentation at the moment.
### Term list
#### Marmalade
- The project itself which compiles to a single `.dll` (and some optional auxiliary files), it can contain multiple [Canaries](#canary), [Services](#service), and [ParamParsers](#param-parser)
#### Canary
- A class which will be added as a single Module to EllieBot on load. It also acts as a [lifecycle handler](canary-lifecycle.md) and as a singleton service with the support for initialize and cleanup.
- It can contain a Canary (called SubCanary) but only 1 level of nesting is supported (you can only have a canary contain a subcanary, but a subcanary can't contain any other canaries)
- Canaries can have their own prefix
- For example if you set this to 'test' then a command called 'cmd' will have to be invoked by using `.test cmd` instead of `.cmd`
#### Canary Command
- Acts as a normal command
- Has context injected as a first argument which controls where the command can be executed
- `AnyContext` the command can be executed in both DMs and Servers
- `GuildContext` the command can only be executed in Servers
- `DmContext` the command can only be executed in DMs
- Support the usual features such as default values, leftover, params, etc.
- It also supports dependency injection via `[inject]` attribute. These dependencies must come after the context and before any input parameters
- Supports `ValueTask`, `Task`, `Task<T>` and `void` return types
#### Param Parser
- Allows custom parsing of command arguments into your own types.
- Overriding existing parsers (for example for IGuildUser, etc...) can cause issues.
#### Service
- Usually not needed.
- They are marked with a `[svc]` attribute, and offer a way to inject dependencies to different parts of your marmalade.
- Transient and Singleton lifetimes are supported.
### Localization
Response and command strings can be kept in one of three different places based on whether you plan to allow support for localization
option 1) `res.yml` and `cmds.yml`
If you don't plan on having your app localized, but you just *may* in the future, you should keep your strings in the `res.yml` and `cmds.yml` file the root folder of your project, and they will be automatically copied to the output whenever you build your marmalade.
##### Example project folder structure:
- uwu/
- uwu.csproj
- uwu.cs
- res.yml
- cmds.yml
##### Example output folder structure:
- marmalades/uwu/
- uwu.dll
- res.yml
- cmds.yml
option 2) `strings` folder
If you plan on having your app localized (or want to allow your consumers to easily add languages themselves), you should keep your response strings in the `strings/res/en-us.yml` and your command strings in `strings/cmds/en-us.yml` file. This will be your base file, and from there you can make support for additional languages, for example `strings/res/ru-ru.yml` and `strings/cmds/ru-ru.yml`
##### Example project folder structure:
- uwu/
- uwu.csproj
- uwu.cs
- strings/
- res/
- en-us.yml
- ru-ru.yml
- cmds/
- en-us.yml
- ru-ru.yml
##### Example output folder structure:
- marmalades/uwu/
- uwu.dll
- strings/
- res/
- en-us.yml
- ru-ru.yml
- cmds/
- en-us.yml
- ru-ru.yml
option 3) In the code
If you don't want any auxiliary files, and you don't want to bother making new .yml files to keep your strings in, you can specify the command strings directly in the `[cmd]` attribute itself, and use non-localized methods for message sending in your commands.
If you update your response strings .yml file(s) while the marmalade is loaded and running, running `.stringsreload` will reload the responses without the need to reload the marmalade or restart the bot.
#### Config
- Marmalade config is kept in `marmalades/marmalade.yml` file
- At the moment this config only keeps track of which marmalades are currently loaded (they will also be always loaded at startup)
- If a marmalade is causing issues and you're unable to unload it, you can remove it from the `loaded:` list in this config file and restart the bot. It won't be loaded next time the bot is started up
#### Unloadability issues
To make sure your marmalade can be properly unloaded/reloaded you must:
- Make sure that none of your types and objects are referenced by the Bot or Bot's services after the DisposeAsync is called on your Canary instances.
- Make sure that all of your commands execute quickly and don't have any long running tasks, as they will hold a reference to a type from your assembly
- If you are still having issues, you can always run `.maunload` followed by a bot restart, or if you want to find what is causing the marmalade unloadability issues, you can check the [microsoft's assembly unloadability debugging guide](https://docs.microsoft.com/en-us/dotnet/standard/assembly/unloadability)
## Practice
This section will guide you through how to create a simple custom marmalade. You can find the entirety of this code hosted [here](https://gitlab.com/nadeko/example_marmalade)
#### Prerequisite
- [.net6 sdk](https://dotnet.microsoft.com/en-us/download) installed
- Optional: use [vscode](https://code.visualstudio.com/download) to write code
#### Guide
- Open your favorite terminal and navigate to a folder where you will keep your project .
- Create a new folder
- `mkdir example_marmalade`
- Create a new .net class library
- `dotnet new classlib`
- Open the current folder with your favorite editor/IDE. In this case we'll use VsCode
- `code .`
- Remove the `Class1.cs` file
- Replace the contents of the `.csproj` file with the following contents
```xml
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<!-- Reduces some boilerplate in your .cs files -->
<ImplicitUsings>enable</ImplicitUsings>
<!-- Use latest .net features -->
<LangVersion>preview</LangVersion>
<EnablePreviewFeatures>true</EnablePreviewFeatures>
<GenerateRequiresPreviewFeaturesAttribute>true</GenerateRequiresPreviewFeaturesAttribute>
<!-- tell .net that this library will be used as a plugin -->
<EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>
<ItemGroup>
<!-- Base marmalade package. You MUST reference this in order to have a working marmalade -->
<!-- Also, this package comes from Toastielab, which requires you to have a NuGet.Config file next to your .csproj -->
<PackageReference Include="Ellie.Marmalade" Version="4.3.9">
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<!-- Note: If you want to use EllieBot services etc... You will have to manually clone
the https://toastielab.dev/Emotions-stuff/elliebot repo locally and reference the EllieBot.csproj because there is no EllieBot package atm.
It is strongly recommended that you checkout a specific tag which matches your version of nadeko,
as there could be breaking changes even between minor versions of EllieBot.
For example if you're running EllieBot 4.1.0 locally for which you want to create a marmalade for,
you should do "git checkout 4.1.0" in your EllieBot solution and then reference the EllieBot.csproj
-->
</ItemGroup>
<!-- Copy shortcut and full strings to output (if they exist) -->
<ItemGroup>
<None Update="res.yml;cmds.yml;strings/**">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
</Project>
```
- Create a `MyCanary.cs` file and add the following contents
```cs
using Ellie.Canary;
using EllieBot;
using Discord;
public sealed class MyCanary : Canary
{
[cmd]
public async Task Hello(AnyContext ctx)
{
await ctx.Channel.SendMessageAsync($"Hello everyone!");
}
[cmd]
public async Task Hello(AnyContext ctx, IUser target)
{
await ctx.ConfirmLocalizedAsync("hello", target);
}
}
```
- Create `res.yml` and `cmds.yml` files with the following contents
`res.yml`
```yml
marmalade.description: "This is my marmalade's description"
hello: "Hello {0}, from res.yml!"
```
`cmds.yml`
```yml
hello:
desc: "This is a basic hello command"
args:
- ""
- "@Someone"
```
- Add `NuGet.Config` file which will let you use the base Ellie.Marmalade package. This file should always look like this and you shouldn't change it
```xml
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="toastielab.dev" value="https://toastielab.dev/api/packages/ellie/nuget/index.json" protocolVersion="3" />
</packageSources>
</configuration>
```
### Build it
- Build your Marmalade into a dll that Ellie can load. In your terminal, type:
- `dotnet publish -o bin/marmalades/example_marmalade /p:DebugType=embedded`
- Done. You can now try it out in action.
### Try it out
- Copy the `bin/marmalades/example_marmalade` folder into your EllieBot's `data/marmalades/` folder. (Ellie version 4.1.0+)
- Load it with `.maload example_marmalade`
- In the channel your bot can see, run the following commands to try it out
- `.hello` and
- `.hello @<someone>`
- Check its information with
- `.mainfo example_marmalade`
- Unload it
- `.maunload example_marmalade`
- Congrats! You've just made your first marmalade!

36
content/Ellie/Marmalade/getting-started.md Normal file
View file

@ -0,0 +1,36 @@
+++
title = "Getting started!"
description = "This guide on getting started with the marmalade system"
weight = 2
+++
## Getting Started
### What is the Marmalade system?
- It is a dynamic module/plugin/cog system for EllieBot introduced in **EllieBot 4.1.0**
- Allows developers to add custom functionality to Ellie without modifying the original code
- Allows for those custom features to be updated during bot runtime (if properly written), without the need for bot restart.
- They are added to `data/marmalades` folder and are loaded, unloaded and handled through discord commands.
- `.maload` Loads the specified marmalade (see `.h .maload`)
- `.maunload` Unloads the specified marmalade (see `.h .maunload`)
- `.mainfo` Checks marmalades information (see `.h .mainfo`)
- `.malist` Lists the available marmalades (see `.h .malist`)
### How to make one?
Marmalades are written in [C#](https://docs.microsoft.com/en-us/dotnet/csharp/tour-of-csharp/) programming language, so you will need at least low-intermediate knowledge of it in order to make a useful Marmalade.
Follow the [creating a marmalade guide](creating-a-marmalade.md)
### Where to get marmalades other people made?
⚠ *It is EXTREMELY, and I repeat **EXTREMELY** dangerous to run marmalades of strangers or people you don't FULLY trust.* ⚠
⚠ *It can not only lead to your bot being stolen, but it also puts your entire computer and personal files in jeopardy.* ⚠
**It is strongly recommended to run only the marmalades you yourself wrote, and only on a hosted VPS or dedicated server which ONLY hosts your bot, to minimize the potential damage caused by bad actors.**
No easy way at the moment, except asking in the `#dev-and-modding` chat in [#Ellie's Home server](https://discord.gg/etQdZxSyEH)

2
content/Ellie/_index.md
View file

@ -4,6 +4,6 @@ title = "EllieBot"
weight = 1
+++
Under this category you can find guides on how to do some things with EllieBot.
Welcome to the category containing guides about EllieBot.
{{%children containerstyle="div" style="h2" description="true" %}}

28
content/Ellie/commands.md Normal file
View file

@ -0,0 +1,28 @@
+++
title = "Commands Readme"
description = "Readme for Commands List"
weight = 3
+++
## Bot Owner Only
- *Bot Owner Only* commands refer to the commands only the **owner** of the bot can use.
- *Bot Owner Only* commands do **not** refer to the owner of the **server**, just the owner of the **bot**.
- *Owner of the bot* is a person who is **hosting** their own bot, and their **ID** is inside of **creds.yml** file.
## Music on the public Ellie
- In case you got Ellie in your server by the invitation from our **Toastielab** invite or **help (.h)**, music is disabled.
- Music is **disabled** due to large maintenance expenses
- If you want to have music module on your server, you will have to **host** the bot on your PC, or any of the external servers.
- How to **host** the bot, check the **guides** on the left side.
## EllieMoney
- EllieMoney is the **currency** of the public Ellie.
- EllieMoney can be `.pick`ed after Ellie drops a dollar randomly after `.gc` has been enabled on a channel
- You can give EllieMoney to other users, using the command `.give X @person`.
- You can only give money you **own**.
- If you want to have **unlimited** number of money, you will have to **host** the bot.
- Commands `.award X @person` and `.take X @person` can only be used by the *bot owner*.
- If you `.plant` the money, money will be avaliable for everyone to `.pick` it. In that case you will **lose** the money.

39
content/supportchild/commands.md
View file

@ -1,39 +0,0 @@
+++
title = "SupportChild Commands"
description = "Here is the full command list for SupportChild"
weight = 1
+++
| Command | Description |
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `/add <user>` | Add users to the ticket. |
| `/addcategory <title> <category>` | Adds a category for users to open tickets in. The title is what will be used on buttons and in selection menus. |
| `/addmessage <identifier> <message>` | Adds a new message for the `say` command. The identifier is one word used in the say command and the message is what the bot prints. |
| `/addstaff <user>` | Registers a user as a staff member for ticket assignment. |
| `/assign (user)` | Assigns a ticket to a staff member, themself if no mention or id is provided. |
| `/blacklist <user>` | Blacklists users from opening tickets. |
| `/close` | Closes a ticket channel and posts a ticket transcript in the log channel. |
| `/createbuttonpanel` | Creates a panel of buttons for users to open tickets with, one for each saved category. |
| `/createselectionbox (message)` | Creates a selection menu for users to open tickets with. Message is the placeholder shown on the selection menu before anything is selected. |
| `/list (user)` | Lists a user's open and closed tickets. |
| `/listassigned (user)` | Lists all of a staff member's assigned tickets. |
| `/listopen` | Lists a number of the oldest still open tickets, default is 20. |
| `/listunassigned` | Lists all unassigned tickets. |
| `/move <category>` | Moves a ticket to a specific category by partial name. |
| `/new` | Opens a new ticket channel. |
| `/rassign (role)` | Randomly assigns a ticket to an active staff member. If a role is provided only staff member with that role are considered. |
| `/removecategory <category>` | Removes a category from the bot. |
| `/removemessage <identifier>` | Removes message from the database. |
| `/removestaff <user>` | Removes a user from staff. |
| `/say (identifier)` | Prints a message with information from staff. Use with no arguments to list ids. |
| `/setsummary <summary>` | Sets a summary for a ticket which can be viewed using the `summary` command. |
| `/status` | Shows a status message about the bot with info such as number of tickets and which version is running. |
| `/summary` | Shows some information about a ticket and its summary if set. |
| `/toggleactive (user)` | Toggles whether a staff member counts as active or not. |
| `/transcript (ticket id) ` | Generates a ticket transcript as an html file. |
| `/unassign` | Unassigns a ticket from the currently assigned staff member. |
| `/unblacklist <user>` | Un-blacklists users from opening tickets. |
| `/admin listinvalid` | Lists tickets which channels have been deleted, you can use the `/admin unsetticket` command to remove them from the ticket system. |
| `/admin reload` | Reloads the config. |
| `/admin setticket (channel)` | Makes the current channel a ticket. |
| `/admin unsetticket (ticket id)` | Removes a ticket without deleting the channel. |

2
hugo.toml
View file

@ -6,7 +6,7 @@ title = 'The documentation site for EllieBot'
[markup.tableOfContents]
# Some relatively important headers, like cc triggers, are on level 4;
# we want to have those in our table of contents, so we need to set this to 4.
endLevel = 4
endLevel = 10
[markup.goldmark]
[markup.goldmark.renderer]
# Enable HTML tags in Markdown