Hikari + Lightbulb Get Started Guide

By Neon

Warning

This guide is not complete, and will not be complete. The GitHub repository has been archived, and my GitHub account is inactive.

Intro

This tutorial assumes that you have some previous knowledge of making Discord bots, though most things complete beginners should be able to understand fairly well

Throughout this tutorial you will see links like Read the docs which go to either the Hikari docs or Lightbulb docs. I try to put them in useful places where people might need them to modify their code to suit a different purpose

The GitHub Repository for this guide is located here

This should really only be used as an assist to the guide, and not to just copy and paste :<

If you notice any issues with code and/or grammar please let me know on Discord @NeonJonn#1650

This tutorial was last updated on 19 December 2021

A Special Thanks

A special thanks goes to thommo and Dav, for answering my endless stream of questions, and to Jonxslays for being cool and helping me work with dicts in the animal command.

And lastly thanks to thommo again, for supporting this little guide, and for making lightbulb such an amazing library, it really wouldn’t be the same without such a cool owner ❤️

Making your Discord Bot Application

Carberra Tutorials made a video on Creating a bot on the Developer Portal which you can follow to do this

Setting up the files

Make a folder for your bot:

mkdir my_bot
cd my_bot

Then, make 3 files: - bot.py - requirements.txt - .env

After all that, your file structure should look like this:

my_bot
│ bot.py
│ requirements.txt
│ .env

Make a virtual environment (optional but recommended)

Windows:

python -m venv .venv
.\.venv\Scripts\activate

Linux:

python -m venv .venv
source .venv/bin/activate

Installing requirements

In requirements.txt paste the following

hikari>=2.0.0.dev104
hikari-lightbulb>=2.1.1
python-dotenv>=0.19.2
uvloop>=0.16; sys_platform != "win32"

And run

python -m pip install -r requirements.txt

Note

• This guide will not work with hikari-lightbulb 2.0.2 due to a bug with BotApp.load_extensions_from in that version.

Please ensure you’re using the latest version - Uvloop is not supported on Windows, but is optional so you can still do this tutorial on a Windows machine

Lightbulb - a “simple and easy to use command framework for Hikari”

uvloop - optional dependency for additional performance benefits on UNIX-like systems

So now, let’s begin!

Hikari Bot

First, grab your bot’s token from the Discord Developer Portal (refer to Part 1 - Making your Discord Bot Application) and put it in the .env file, like so:

BOT_TOKEN=your_bot_token

Next, in bot.py paste the following

import os

import dotenv
import hikari

dotenv.load_dotenv()

bot = hikari.GatewayBot(
    os.environ["BOT_TOKEN"],
    intents=hikari.Intents.ALL,
)


@bot.listen()
async def on_message_create(event: hikari.GuildMessageCreateEvent) -> None:
    if event.is_bot or not event.content:
        return

    if event.content.strip() == "+ping":
        await event.message.respond(
            f"Pong! Latency: {bot.heartbeat_latency*1000:.2f}ms"
        )

if __name__ == "__main__":
    if os.name != "nt":
        import uvloop

        uvloop.install()

    bot.run()

Now save bot.py and run it

python bot.py

You should see an output similar to the following

oooo         o8o  oooo                            o8o       光 2.0.0.dev104 [79548984]
`888         `"'  `888                            `"'       © 2021 davfsa - MIT license
 888 .oo.   oooo   888  oooo   .oooo.   oooo d8b oooo       interpreter:   CPython 3.10.1
 888P"Y88b  `888   888 .8P'   `P  )88b  `888""8P `888       running on:    AMD64 Windows 10
 888   888   888   888888.     .oP"888   888      888       installed at:  C:\Users\Neon\Documents\my_bot\.venv\lib\site-packages\hikari
 888   888   888   888 `88b.  d8(  888   888      888       documentation: https://hikari-py.dev/hikari
o888o o888o o888o o888o o888o `Y888""8o d888b    o888o      support:       https://discord.gg/Jx4cNGG

I 2021-12-19 18:58:07,535 hikari.bot: you can start 999 sessions before the next window which starts at 2021-12-20 12:06:04.514319+00:00; planning to start 1 session...
I 2021-12-19 18:58:07,995 hikari.gateway.0: shard is ready: 2 guilds, Hikari Guides#9057 (873205092923355136), session '14007c7e88f1d714b1612798165d35d4' on v8 gateway
I 2021-12-19 18:58:08,824 hikari.bot: started successfully in approx 0.81 seconds

Now go into the server you invited your bot to, and send +ping

The bot should respond with Pong! and it’s heartbeat latency, like so

Congratulations, you’ve just run your first Hikari bot!

Now let’s go through what everything does

• Line 1-4 - Import the os, dotenv and hikari modules

• Line 6 - Load the .env file

• Line 8-11 - Create a bot using that token, and all Discord intents

• Line 14-22 - The bot listens for messages sent in guilds (servers)

  • If the message author is a bot or the message has no content (though it may have attachments), it ignores it

  • Otherwise, it checks if the message content is +ping and if it is, the bot responds with Pong! and it’s heartbeat latency

• Line 24-30

  • If we’re on a non-Windows machine, import uvloop and install it

  • And finally, run the bot!

This bot works, but to add more commands other than +ping would be a huge hassle, so this is where lightbulb comes in

Lightbulb Bot

Lightbulb is a command handler for Hikari, making it easy to create commands and slash commands, handle interactions and more

So to start, let’s change our bot.py a little

import os

import dotenv
import hikari
import lightbulb

dotenv.load_dotenv()

bot = lightbulb.BotApp(
    os.environ["BOT_TOKEN"],
    prefix="+",
    banner=None,
    intents=hikari.Intents.ALL,
)


@bot.command
@lightbulb.command("ping", description="The bot's ping")
@lightbulb.implements(lightbulb.PrefixCommand)
async def ping(ctx: lightbulb.Context) -> None:
    await ctx.respond(f"Pong! Latency: {bot.heartbeat_latency*1000:.2f}ms")



if __name__ == "__main__":
    if os.name != "nt":
        import uvloop

        uvloop.install()

    bot.run()

• Line 5 - We’ve imported lightbulb now too

• Line 9-14 - We’ve used lightbulb to create the bot now adding

  • a prefix kwarg set to "+"

  • a banner kwarg set to None, disabling the hikari banner that appears when the bot starts

    This isn’t necessary, but the banner can get a little annoying after a while

• Line 17-21 - Creates a command with the lightbulb bot named ping which works the same as the old ping command,

responding with Pong! and the bot’s heartbeat latency

Now let’s run the bot again!

You should see a slightly different output this time, like so

I 2021-12-19 19:15:37,068 hikari.bot: you can start 998 sessions before the next window which starts at 2021-12-20 12:06:04.517957+00:00; planning to start 1 session...
I 2021-12-19 19:15:37,513 hikari.gateway.0: shard is ready: 2 guilds, Hikari Guides#9057 (873205092923355136), session '69407e13f93111d66206b909af1c1567' on v8 gateway
I 2021-12-19 19:15:38,026 lightbulb.internal: Processing global commands
I 2021-12-19 19:15:38,287 lightbulb.internal: Command processing completed
I 2021-12-19 19:15:38,290 hikari.bot: started successfully in approx 1.52 seconds

Again, if you run the command +ping in your server, the bot should respond with it’s heartbeat latency

Making a lightbulb extension

Extensions are a useful way of separating parts of your bot into different files, making it easier to manage

So, let’s create an extension!

In your my_bot folder make a new folder named extensions

Then in that folder create a file named info.py

Your file structure should look like this now

my_bot
│ bot.py
│ requirements.txt
│ .env
│
└── extensions
│ │ info.py

In info.py paste the following

from datetime import datetime

import hikari
import lightbulb

info_plugin = lightbulb.Plugin("Info")


@info_plugin.command
@lightbulb.option(
    "target", "The member to get information about.", hikari.User, required=False
)
@lightbulb.command(
    "userinfo", "Get info on a server member."
)
@lightbulb.implements(lightbulb.PrefixCommand, lightbulb.SlashCommand)
async def userinfo(ctx: lightbulb.Context) -> None:
    target = ctx.get_guild().get_member(ctx.options.target or ctx.user)

    if not target:
        await ctx.respond("That user is not in the server.")
        return

    created_at = int(target.created_at.timestamp())
    joined_at = int(target.joined_at.timestamp())

    roles = (await target.fetch_roles())[1:]  # All but @everyone

    embed = (
        hikari.Embed(
            title=f"User Info - {target.display_name}",
            description=f"ID: `{target.id}`",
            colour=0x3B9DFF,
            timestamp=datetime.now().astimezone(),
        )
        .set_footer(
            text=f"Requested by {ctx.member.display_name}",
            icon=ctx.member.avatar_url or ctx.member.default_avatar_url,
        )
        .set_thumbnail(target.avatar_url or target.default_avatar_url)
        .add_field(
            "Bot?",
            str(target.is_bot),
            inline=True,
        )
        .add_field(
            "Created account on",
            f"<t:{created_at}:d>\n(<t:{created_at}:R>)",
            inline=True,
        )
        .add_field(
            "Joined server on",
            f"<t:{joined_at}:d>\n(<t:{joined_at}:R>)",
            inline=True,
        )
        .add_field(
            "Roles",
            ", ".join(r.mention for r in roles),
            inline=False,
        )
    )

    await ctx.respond(embed)

def load(bot: lightbulb.BotApp) -> None:
    bot.add_plugin(info_plugin)

Next, in bot.py we’ll need to make two little changes:

After intents=hikari.Intents.ALL, add

default_enabled_guilds=(123456,)

replacing 123456 with the ID of your guild.

Note

Explanation:

By default, slash commands are global but can take up to an hour to appear after registering with Discord.

Setting default guild(s) means that slash commands will only appear in those guild(s), but will appear and update instantly when running the bot

And on line 23, add:

bot.load_extensions_from("./extensions/", must_exist=True)

So, now let’s run the bot with our new userinfo slash command!

You should see a new line in your output similar to this:

I 2021-12-19 19:32:11,853 lightbulb.app: Extension loaded 'extensions.info'

If all went okay, our slash command userinfo was successfully created!

Now let’s go and try it out:

And there we go, our first slash command!

Now to go through what everything does…

• Line 6 - Create a plugin named Info, which will be used to add our new slash command

  Read the docs - Creating plugins

• Line 19 - Decorator to attach the following command to the plugin

• Line 10-12 - Add a command option named target with a type of hikari.User that is not required and a description of The member to get information about

  Read the docs - Converters and Slash Command Options Types

• Line 13-15 - Decorator to create the command, setting the name to userinfo and the description to Get info on a server member.

• Line 16 - Converts the decorated function to a prefix command and slash command

• Line 17 - The command’s function, which takes the parameter ctx (Read the docs - Context)

• Line 18 - Get the guild (ctx.get_guild()) and then the member of that guild using ctx.options.target or, if target wasn’t passed and is None, ctx.user (the user who ran the command)

  Note: This will return None if the target is not found in the guild

• Line 20-22 - Check if target is None, and then let the user know if it is. The return statement stops any code after it running, but this will only happen if target is None

• Line 24-25 - Get the UNIX Timestamps for when the member created their account and joined the guild, and round them to the nearest integer

  The rounding is necessary, as Discord timestamps only work with integers, not floats

• Line 27 - Get the member’s list of roles excluding @everyone

• Line 30-35 - Make a Discord embed setting the title, description, colour and timestamp

• Line 36-40 - Set the embed’s footer and thumbnail

• Line 41-60 - Add fields to the embed, stating

  • whether the user is a bot or not

  • when their account was created & when they joined the server, using Discord Timestamps and

  • a list of roles the member has

• Line 63 - respond to the interaction with the embed (Read the docs - Context.respond)

• Line 65-66 - the load function to load the extension when the bot starts. This is required in each extension.

BotApp.d - a built in DataStore

This is preparation for the next section (Command Groups & Subcommands), but also just to show off a new feature of BotApp in lightbulb v2, the built in DataStore.

In our bot.py file, we’ll need to add some “listeners”

Add

import aiohttp

just above import dotenv

Then, put the following code at the end of the file, just above bot.load_extensions_from("./extensions/")

@bot.listen()
async def on_starting(event: hikari.StartingEvent) -> None:
    bot.d.aio_session = aiohttp.ClientSession()

@bot.listen()
async def on_stopping(event: hikari.StoppingEvent) -> None:
    await bot.d.aio_session.close()

This creates 2 listeners, one for when the bot is starting, and one for when the bot is stopping.

• When the bot is starting, it creates a new aiohttp.ClientSession named aio_session and stores it in the bot.d data store

• When the bot is stopping, it closes the aio_session

Read the docs - aiohttp

Command Groups & Subcommands

Create a new file named fun.py in the extensions folder - this will contain our new lightbulb extension

In fun.py paste the following

import hikari
import lightbulb

fun_plugin = lightbulb.Plugin("Fun")


@fun_plugin.command
@lightbulb.command("fun", "All the entertainment commands you'll ever need")
@lightbulb.implements(lightbulb.SlashCommandGroup, lightbulb.PrefixCommandGroup)
async def fun_group(ctx: lightbulb.Context) -> None:
    pass  # as slash commands cannot have their top-level command ran, we simply pass here


@fun_group.child
@lightbulb.command("meme", "Get a meme")
@lightbulb.implements(lightbulb.SlashSubCommand, lightbulb.PrefixSubCommand)
async def meme_subcommand(ctx: lightbulb.Context) -> None:
    async with ctx.bot.d.aio_session.get(
        "https://meme-api.herokuapp.com/gimme"
    ) as response:
        res = await response.json()

        if response.ok and res["nsfw"] != True:
            link = res["postLink"]
            title = res["title"]
            img_url = res["url"]

            embed = hikari.Embed(colour=0x3B9DFF)
            embed.set_author(name=title, url=link)
            embed.set_image(img_url)

            await ctx.respond(embed)

        else:
            await ctx.respond(
                "Could not fetch a meme :c", flags=hikari.MessageFlag.EPHEMERAL
            )


def load(bot: lightbulb.BotApp) -> None:
    bot.add_plugin(fun_plugin)

• Line 4 - Create a new plugin named Fun

• Line 7 - Decorator to attach the following command to the plugin

• Line 8 - Decorator to create the command, setting the name to fun and adding a description

• Line 9 - Converts the decorated function to a PrefixCommandGroup and SlashCommandGroup

• Line 10 - The command’s function

• Line 11 - pass the function, as slash commands cannot have their top-level command ran

• Line 14 - attach the decorated function to the fun_group command

• Line 15 - Decorator to create the subcommand, setting the name to meme and adding a description

• Line 16 - Converts the decorated function to a PrefixSubCommand and SlashSubCommand

• Line 17 - The subcommand’s function

• Line 18-21 - Using the aio_session from the bot.d data store that we created in the previous section, get a meme from the API

  Read the docs - aiohttp.ClientSession

• Line 23 - If the response is successful and the meme is not NSFW (Not Safe For Work), then

  • Line 24-26 - Get the meme’s link, title and image url

  • Line 28 - Create an embed

  • Line 29 - Set the embed’s author to the meme’s title and link

  • Line 30 - Set the embed’s image to the meme’s image url

  • Line 32 - Respond to the interaction with the embed

• Line 34 - Otherwise, if the response was not successful or the meme was NSFW, then

  • Line 35-37 - Respond to the interaction with an ephemeral message, stating that we could not fetch a meme

Now, let’s test it!

and if we can’t fetch a meme:

Note

Ephemeral response only work with slash commands, not prefix commands

Components - Dropdown Menus

Message components are relatively new features on Discord, allowing you to attach buttons and select menus to messages!

Let’s add some new code to fun.py

This should be inserted after the meme command, but above the load function

ANIMALS = {
    "Dog": "🐶",
    "Cat": "🐱",
    "Panda": "🐼",
    "Fox": "🦊",
    "Red Panda": "🐼",
    "Koala": "🐨",
    "Bird": "🐦",
    "Racoon": "🦝",
    "Kangaroo": "🦘",
}


@fun_group.child
@lightbulb.command("animal", "Get a fact + picture of a cute animal :3")
@lightbulb.implements(lightbulb.SlashSubCommand, lightbulb.PrefixSubCommand)
async def animal_subcommand(ctx: lightbulb.Context) -> None:
    select_menu = (
        ctx.bot.rest.build_action_row()
        .add_select_menu("animal_select")
        .set_placeholder("Pick an animal")
    )

    for name, emoji in ANIMALS.items():
        select_menu.add_option(
            name,  # the label, which users see
            name.lower().replace(" ", "_"),  # the value, which is used by us later
        ).set_emoji(emoji).add_to_menu()

    resp = await ctx.respond(
        "Pick an animal from the dropdown :3",
        component=select_menu.add_to_container(),
    )
    msg = await resp.message()

    try:
        event = await ctx.bot.wait_for(
            hikari.InteractionCreateEvent,
            timeout=60,
            predicate=lambda e:
                isinstance(e.interaction, hikari.ComponentInteraction)
                and e.interaction.user.id == ctx.author.id
                and e.interaction.message.id == msg.id
                and e.interaction.component_type == hikari.ComponentType.SELECT_MENU
            )
    except asyncio.TimeoutError:
        await msg.edit("The menu timed out :c", components=[])
    else:
        animal = event.interaction.values[0]
        async with ctx.bot.d.aio_session.get(
            f"https://some-random-api.ml/animal/{animal}"
        ) as res:
            if res.ok:
                res = await res.json()
                embed = hikari.Embed(description=res["fact"], colour=0x3B9DFF)
                embed.set_image(res["image"])

                animal = animal.replace("_", " ")

                await msg.edit(
                    f"Here's a {animal} for you! :3", embed=embed, components=[]
                )
            else:
                await msg.edit(
                    f"API returned a {res.status} status :c", components=[]
                )

• Line 1-11 - Create a dict containing all the possible endpoints of some-random-api.ml/animal/

• Line 14-16 - Set up prefix and slash sub commands

• Line 18-22

  • Create an action row, which returns an ActionRowBuilder

  • Add a select menu to the action row, with animal_select as the custom ID

  • Set the placeholder (the text that is seen when no option is picked) to Pick an animal

• Line 24-28 - For all the items in the ANIMALS dict, add an option to the select menu Read the docs - SelectMenuBuilder.add_option with

  • The name and

  • The value, which is the name of the animal, but lowercased and with spaces replaced with underscores

  • Setting the emoji to the value of the animal in the ANIMALS dict

• Line 30-34

  • Respond to the context with the select menu

  • Fetch the message from the response (in lightbulb V2, Context.respond returns a ResponseProxy, not a Message)

• Line 37-45 - Wait for an interaction to be created and

  • Check if the interaction is a component interaction

  • Check that the interaction user is the same who ran the command

  • Check that the interaction message is the same as the message we sent

  • Check that the interaction component type is a select menu

• Line 46-47 - If the interaction times out, an asyncio.TimeoutError will be raised, and so we can use that to handle the timeout by editing the message and removing the components

• Line 49 - Get the value of the interaction (the selected option) - Read the docs - ComponentInteraction.values

• Line 50-52 - Make a GET request to some-random-api.ml with the selected animal as the option

• Line 53 - If the response has an ok status, then

  • Line 54 - Get the response’s json

  • Line 55 - Create an embed, setting its title to the animal fact

  • Line 56 - Set the embed’s image to the animal image

  • Line 58 - Replace the underscore in animal with a space

  • Line 60-62 - Edit the message to contain the embed, and remove the select menu component

• Line 63 - Otherwise, if the response was not successful, then

  • Line 64-66 - Edit the message to say what status code the API responded with, and remove the select menu component

And at the very top of the file, don’t forget to import asyncio!

import asyncio

And if the menu times out:

Command Checks

We’ll be making a purge command, which will delete messages in bulk to demonstrate how to use command checks.

So, create a new file named mod.py in the extensions folder

In it paste the following

import asyncio

import hikari
import lightbulb
from lightbulb import errors

mod_plugin = lightbulb.Plugin("Mod")


@mod_plugin.command
@lightbulb.option(
    "messages", "The number of messages to purge.", type=int, required=True
)
@lightbulb.command("purge", "Purge messages.", aliases=["clear"])
@lightbulb.implements(lightbulb.PrefixCommand, lightbulb.SlashCommand)
async def purge_messages(ctx: lightbulb.Context) -> None:
    num_msgs = ctx.options.messages
    channel = ctx.channel_id

    # If the command was invoked using the PrefixCommand, it will create a message
    # before we purge the messages, so you want to delete this message first
    if isinstance(ctx, lightbulb.PrefixContext):
        await ctx.event.message.delete()

    msgs = await ctx.bot.rest.fetch_messages(channel).limit(num_msgs)
    await ctx.bot.rest.delete_messages(channel, msgs)

    resp = await ctx.respond(f"{len(msgs)} messages deleted")

    await asyncio.sleep(5)
    await resp.delete()


def load(bot: lightbulb.BotApp) -> None:
    bot.add_plugin(mod_plugin)

• Line 25 - Fetch the most recent messages in the channel (Read the docs - fetch_messages),

limiting it to num_msgs (Read the docs - LazyIterator.limit()) - Line 26 - Delete the messages that we fetched

Note: ctx.respond() returns a ResponseProxy, not a Message. If you want to get the message, you can use ResponseProxy.message.

Now this command works fine, but now everyone can delete messages using the bot. We only want people with the manage messages permission to do this, so this is where checks come in.

Just above line 11 (@lightbulb.option), add the following

@lightbulb.add_checks(
    lightbulb.has_guild_permissions(hikari.Permissions.MANAGE_MESSAGES),
    lightbulb.bot_has_guild_permissions(hikari.Permissions.MANAGE_MESSAGES)
)

This checks if the both the user who ran the command and the bot has the manage messages permission in the guild

If the both the user and bot have permission to run the command, it will work. If they don’t, the command will raise CheckFailure.

But raising an error and the command failing isn’t that useful, we want to tell the user what happened

So, onto error handling!

Error Handling

raise NotImplementedError("This part hasn't been written yet!")

The End, for now…

Unfortunately this is where the guide ends for now, but fear not because I’ll be updating this regularly!

What I’ll be adding next:

• Checks & Cooldowns for commands

• Error handling

My new testing server, Gamma Rays, is open! Join it here!

If you need help or want to receive Hikari + Lightbulb updates, why not join the Hikari server