dingenskirchen.org

BLIMP Manual

the BLIMP is a multipurpose utility Discord Bot. This is its manual, to help you use it effectively. the documentation for the actual commands is not included here, because it is accessible from the bot already: just type help! and BLIMP itself will be delighted to assist you.

Arguments

Most BLIMP commands accept arguments. They’re separated by spaces, like this:

choose! Option Choice

This will make the bot see both Option and Choice as separate words. Sadly, sometimes one is forced to use a language that doesn’t have the near-miraculous ability to merge concepts into single, beautiful, words like Kommunal­investitions­förderungs­fonds¹. BLIMP is, of course, prepared for this eventuality. Use quotes to indicate that multiple words belong together:

choose! "Butter Pecan" Chocolate

Here, the bot sees Butter Pecan and Chocolate as two separate phrases.

In some cases, you have to adhere to a certain syntax to make BLIMP understand what you mean. The important cases are described in the following sections:

Durations

Durations, for e.g. slowmode! set or remindme!, are written as a group of numbers suffixed with units. The available units are s, sec, secs, second, seconds; m, min, mins, minute, minutes; h, hour, hours; d, day, and days. A day is always assumed to last 24 hours. You can combine units as you like:

remindme! 1min30s check the printer
remindme! 1h drink some water
remindme! "85 days, 12 hours" listen to Everywhere At The End Of Time

It’s important to note that BLIMP only understands each unit, in all of its spellings, the first time it’s mentioned: 1h3hours is parsed the same as just 1h.

Timestamps

You can write timestamps, e.g. for remindme!, in the ISO 8601 format, which looks like this:

remindme! 2019-06-17T09:00:00-05:00 last mail about tupac

This full format is, obviously, very unwieldy.
You can simplify it by leaving out any of the timezone (-5:00), second (:00) or entire time (9:00:00) parts out. Everything you don’t specify defaults to zero, which is UTC midnight. You can also replace the T with any character, but keep in mind that replacing it with a space means you will need to wrap the timestamp in quotes.

Messages

Referring to messages is important for e.g. editing post!s, or creating role kiosks and triggers. You can do this using a link to the message, a pair of IDs like channelid-messageid, which you can get from shift-clicking the “copy ID” button from developer mode, or just the message ID if the message is in the current channel.

post! https://discord.com/channels/@me/128158151145472020/768474412092489748 Hi! :)
post! 128158151145472020-768474412092489748 embed = { color = "GOOD", title = "Hello." }
post! 768474412092489748 embed = { title = "Greetings, citizen." }

If you need further help on getting IDs, take a look at this Discord help article.

Channels/Categories

You’ll want to refer to channels or categories often when working with Tickets or other server-management aspects of BLIMP. To refer to either, you can use a channel mention, the ID, or the channel’s/category’s name.

post! #general Hello world!
post! 530451814942453588 Hello world!
post! general Hello world!

Users

To refer to a user, to e.g. channel-ban them, use either a mention, their ID, Discord Tag#1234, Discord Tag, or nickname in your current server. The last two options are discouraged, as they’re not necessarily unique.

Roles

You can refer to roles using a mention (probably ill-advised if you can ping the role), its ID, or its name.

Aliasing

If you find yourself referring to a certain message, channel or category often, you can use the alias! make command to assign them a common name in your server:

alias! make #channel-with-long-name 'thatchannel
post! 'thatchannel This is an aliased hello!

For more details on that, see the BLIMP help entry on alias!.

Advanced Message Formatting

In most areas where you can provide text for BLIMP to repost at a later point, e.g. the post! command, welcome greetings or ticket class descriptions, you can write either plain text, which just gets posted verbatim as the normal message content, as if you were typing it yourself, or instead use the following extended TOML syntax to control more aspects of the message:

content = "Standard Message Content"
reference = 12345678901234 # message ID of the message you're replying to

[embed]

# either "GOOD", "I_GUESS", "BAD", "AUTOMATIC_BLUE" for standard BLIMP colors
# or a hex color prefixed with 0x like 0x4A412A
color = "I_GUESS"

title = "The Embed's Title Text"

# URL the title will link to
url = "https://example.com"

# note the multi-line string syntax in TOML
description = """
This is the content that will appear inside the embed. You can write
quite a lot here — at most 2048 characters are allowed as written in
https://discord.com/developers/docs/resources/channel#embed-limits.
"""

# image_url is the "big" image at the bottom of the embed
image_url = "https://i.ytimg.com/vi/NAh9oLs67Cw/hqdefault.jpg"

# thumbnail_url is the "small" image at the right border of the embed
thumbnail_url = "https://i.ytimg.com/vi/NAh9oLs67Cw/hqdefault.jpg"

[embed.author]
name = "The author is displayed at the top of an embed"
icon_url = "https://i.ytimg.com/vi/NAh9oLs67Cw/hqdefault.jpg"

[embed.footer]
text = "The footer is displayed at the bottom of an embed"
icon_url = "https://i.ytimg.com/vi/NAh9oLs67Cw/hqdefault.jpg"

[[embed.fields]]
name = "A field must have a nonempty title"
value = "as well as non-empty content"

# inline defaults to false. if true, up to three consecutive inline fields get
# smushed into one layout row. 
inline = true

# you can have at most 25 fields, though you probably want *way* less.
[[embed.fields]]
name = ":rock:"
value = "fig. 1, my pet rock"
inline = true

Self-Hosting

To self-host BLIMP, you need both the source code and the Nix Package Manager. First, open a terminal and clone the repository:

$ git clone https://github.com/the-valley-discord/blimp

If you don’t have git installed, you can also download a zip archive of the code on the page linked above (currently the option is hidden behind a big green button) and unzip it into a directory.
Next, enter that directory.

$ cd blimp

Now you need to edit the configuration file. Open blimp.cfg.example with your text editor of choice and update it as instructed by the comments inside. To get the bot running immediately, you only need to insert a valid token, which you can get here under “New Application”→“Bot”.
Now we can build BLIMP:

$ nix build

This will print a bunch of useful information and hopefully succeed. You now should have a symlink called result lying around in your folder that points to the build output. You can run BLIMP using this command:

$ ./result/bin/blimp

If you want to self-host it on a VPS or similar, you probably want to create a systemd service for BLIMP to have it start automatically and provide better logging. This is not detailed here, just search the term and you should find a bunch of up-to-date tutorials.