Creating A Marmalade¶
Getting Started¶
This section will guide you through how to create a simple custom marmalade. The project template, with its example commands, is here.
Prerequisite¶
- .NET 9 SDK installed
- EllieBot 7.x
- Optional: use vscode to write code
Guide¶
-
Open your favorite terminal and navigate to a folder where you will keep your project.
-
Create a new folder and move into it
mkdir example_marmaladecd example_marmalade
-
Install the ellie-marmalade template from the EllieBot Toastielab feed:
sh
dotnet new install ellie-marmalade --nuget-source https://toastielab.dev/api/packages/EllieBotDevs/nuget/index.json
- Make a new Ellie Marmalade project:
sh
dotnet new ellie-marmalade
- The project uses the newest
Ellie.Marmalade7 package. To use the package version of your bot, openexample_marmalade.csprojand change7.*to your bot version, for example7.8.0.
Build and load the marmalade¶
-
Build the marmalade:
dotnet publish -o bin/marmalades/example_marmalade -
Copy the folder
bin/marmalades/example_marmaladeinto thedata/marmaladesfolder of your bot. The folder and the.dllfile must have the same name:data/marmalades/example_marmalade/example_marmalade.dll. - In Discord, type
.maload example_marmalade. - Try the example commands:
.hello.hello @someone.info John,24
- Type
.mainfo example_marmaladeto see its sneks and its number of commands. - Type
.maunload example_marmaladeto unload it.
Parts of a marmalade¶
| Part | What it is |
|---|---|
| Marmalade | The project. It builds into one .dll file, with optional extra files. It can have sneks, param parsers and services. |
| Snek | A class which becomes one module of the bot. Each snek has one instance while the marmalade is loaded. |
| Snek command | A method with the [cmd] attribute. It works like a normal bot command. |
| Param parser | A class which turns the text of an argument into your own type. |
| Service | A class with the [svc] attribute, which you can inject into sneks and commands. |
The base classes are open source in Ellie.Marmalade.
Snek¶
- A snek can have one level of sub-sneks. A sub-snek is a nested class in the snek class. It cannot have more sneks in it.
- A snek can have a prefix. If the prefix is
test, the commandcmdbecomes.test cmd.
Snek command¶
- The first parameter is the context. It sets where the command works:
AnyContext: in servers and in direct messagesGuildContext: only in serversDmContext: only in direct messages
- Parameters with the
[inject]attribute come after the context and before the normal parameters. The bot puts services in them. - Commands support default values,
[leftover]andparams. [user_perm]and[bot_perm]set the permissions which a command needs.[bot_owner_only]makes a command owner-only.- A command can return
ValueTask,Task,Task<T>orvoid. The bot does not load a command which returnsValueTask<T>.
Param parser¶
A param parser inherits from ParamParser<T>. The template has EmployeeInfoParser, which turns John,24 into an EmployeeInfo. The bot keeps its own parsers. If your parser is for a type which the bot already parses (for example IGuildUser), the bot ignores your parser. Use your own types.
Service¶
Most marmalades do not need services. Mark a class with [svc(Lifetime.Singleton)] or [svc(Lifetime.Transient)], then inject it with [inject].
Strings¶
Keep the response strings and the command descriptions in one of three places:
res.ymlandcmds.ymlin the project folder. Use this if you do not need translations now. The build copies the files to the output.- The
stringsfolder, for translations:strings/res/en-us.ymlandstrings/cmds/en-us.yml, and one more file in each folder for each language, for examplestrings/res/ru-ru.yml. - In the code. Put the command description in the
[cmd]attribute, and send text which is not translated.
If res.yml exists, the bot ignores the strings/res folder. If cmds.yml exists, the bot ignores the strings/cmds folder. The template has both files, so delete them when you change to the strings folder.
When you change a response file of a loaded marmalade, type .stringsreload. The bot loads the new strings without a reload of the marmalade.
Lifecycle¶
A snek can override these methods:
| Method | When the bot calls it |
|---|---|
InitializeAsync |
When the bot loads the marmalade. |
DisposeAsync |
When the bot unloads the marmalade. |
ExecOnMessageAsync |
First, for each message. Return true to stop the bot from processing the message. |
ExecInputTransformAsync |
Next. Return the new text of the message, or null to keep it. The bot looks for a command in the new text. |
ExecPreCommandAsync |
After the bot finds a command (of any module), before it runs. Return true to stop the command. |
ExecPostCommandAsync |
After a command runs without an error. |
ExecOnNoCommandAsync |
When no command runs: the bot finds no command, or a check stops the command. The bot calls this method or ExecPostCommandAsync, never both. |
Unload problems¶
The bot can unload a marmalade only when nothing holds a reference to its code. To keep your marmalade unloadable:
- In
DisposeAsync, remove each reference which the bot or its services have to your objects (for example event handlers). - Keep commands short. A long task holds a reference to your code.
If a marmalade does not unload, type .meunload, then restart the bot. To find the cause, read the .NET guide to assembly unloadability.
If a marmalade breaks the bot and you cannot unload it, remove its name from the loaded list in data/marmalades/marmalade.yml, then restart the bot.