diff --git a/content/Ellie/Guides/windows-guide.md b/content/Ellie/Guides/windows-guide.md index 5e3fb4c..25f3e8b 100644 --- a/content/Ellie/Guides/windows-guide.md +++ b/content/Ellie/Guides/windows-guide.md @@ -4,8 +4,10 @@ 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 style="note" title="Notice on windows installer" %}} +~~There is an easier way in the works but this will take time to make, sorry about that. - Toastie~~ + +This way of installing and using Ellie is nearly ready so keep and eye out for that part of the guide. - Toastie {{% /notice %}} ### Windows From Source diff --git a/content/Ellie/Marmalade/_index.md b/content/Ellie/Marmalade/_index.md index 6ce3493..9f3bbfd 100644 --- a/content/Ellie/Marmalade/_index.md +++ b/content/Ellie/Marmalade/_index.md @@ -7,12 +7,10 @@ weight = 7 Under this category you can find guides about EllieBot's Marmalade system. - {{%children containerstyle="div" style="h2" description="true" %}} \ No newline at end of file diff --git a/content/Ellie/Marmalade/creating-a-marmalade.md b/content/Ellie/Marmalade/creating-a-marmalade.md index c1efc5b..770e0c8 100644 --- a/content/Ellie/Marmalade/creating-a-marmalade.md +++ b/content/Ellie/Marmalade/creating-a-marmalade.md @@ -4,9 +4,179 @@ description = "This will hopefully guide you on how to create a marmalade" weight = 1 +++ -## Theory +## Practice -### Introduction +This section will guide you through how to create a simple custom marmalade. You can find the entirety of this code hosted [here](https://toastielab.dev/ellie/example_marmalade) + +#### Prerequisite +- [.net8 sdk](https://dotnet.microsoft.com/en-us/download) installed +- Optional: use [vscode](https://code.visualstudio.com/download) to write code + +#### There are currently two ways of creating a marmalade and you can view both of them using the tabs below. + +{{}} +{{% tab title="Using our template" %}} +#### Prerequisite +- [git](https://git-scm.com/downloads) installed + +#### Guide + +- Open your favorite terminal and navigate to a folder where you will keep your project . + +- Install the ellie-marmalade template + - `git clone https://toastielab.dev/Emotions-stuff/ellie-marmalade` + - `cd ellie-marmalade` + - `dotnet new install .\` + +- Create a new folder and move into it + - `mkdir example_marmalade ` + - `cd example_marmalade` + +- Make a new Ellie Marmalade project + - `dotnet new ellie-marmalade` + - This can be any name you want you just have to specify `-n ` after the first part of the command + - Here is an example `dotnet new ellie-marmalade -n my-cool-marmalade` + - This will create a marmalade project with the name my-cool-marmalade + +Now follow the instructions below and you should be good to go. +{{% /tab %}} +{{% tab title="Building from scratch" %}} +#### Guide + +{{%notice style="info"%}} +This requires writing a little bit of code but we will help you through it as much as we can. +{{%/notice%}} + +#### Without any further issues we shall now begin + +- 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 + + + net8.0 + + + enable + + + preview + true + true + + + true + + + + + + + all + + + + + + + + + PreserveNewest + + + + +``` +- Create a `MyCanary.cs` file and add the following contents +```cs +using EllieBot.Marmalade; +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 + + + + + + +``` +{{% /tab %}} +{{}} + +### 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 @` + +- Check its information with + - `.mainfo example_marmalade` + +- Unload it + - `.maunload example_marmalade` + +- 🎉 Congrats! You've just made your first marmalade! 🎉 + +## Theory 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. @@ -101,7 +271,7 @@ If you don't want any auxiliary files, and you don't want to bother making new . 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 +#### Bot marmalade config file - 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) @@ -115,140 +285,4 @@ To make sure your marmalade can be properly unloaded/reloaded you must: - 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://toastielab.dev/ellie/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 - - - net6.0 - - - enable - - - preview - true - true - - - true - - - - - - - all - - - - - - - - - PreserveNewest - - - - -``` -- Create a `MyCanary.cs` file and add the following contents -```cs -using EllieBot.Marmalade; -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 - - - - - - -``` - -### 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 @` - -- Check its information with - - `.mainfo example_marmalade` - -- Unload it - - `.maunload example_marmalade` - -- Congrats! You've just made your first marmalade! \ No newline at end of file +- 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) \ No newline at end of file