Skip to content

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

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_marmalade
    • cd 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.Marmalade 7 package. To use the package version of your bot, open example_marmalade.csproj and change 7.* to your bot version, for example 7.8.0.

Build and load the marmalade

  1. Build the marmalade:

    dotnet publish -o bin/marmalades/example_marmalade
    
  2. Copy the folder bin/marmalades/example_marmalade into the data/marmalades folder of your bot. The folder and the .dll file must have the same name: data/marmalades/example_marmalade/example_marmalade.dll.

  3. In Discord, type .maload example_marmalade.
  4. Try the example commands:
    • .hello
    • .hello @someone
    • .info John,24
  5. Type .mainfo example_marmalade to see its sneks and its number of commands.
  6. Type .maunload example_marmalade to 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 command cmd becomes .test cmd.

Snek command

  • The first parameter is the context. It sets where the command works:
    • AnyContext: in servers and in direct messages
    • GuildContext: only in servers
    • DmContext: 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] and params.
  • [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> or void. The bot does not load a command which returns ValueTask<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.yml and cmds.yml in the project folder. Use this if you do not need translations now. The build copies the files to the output.
  • The strings folder, for translations: strings/res/en-us.yml and strings/cmds/en-us.yml, and one more file in each folder for each language, for example strings/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.