Utilities

Kord Extensions provides many utilities that can make writing checks easier and simpler.

Event Entities

You can use the following functions to retrieve entities contained within any generic event, which makes it much easier to write all kinds of code. These functions are essentially giant when {} blocks, checking against all possible basic event types.

If you're writing custom events, remember to extend the relevant generic event types to make sure these functions work with your event.

All the below functions take one argument — the event to retrieve an entity from. They all return null when the event doesn't contain the relevant entity type, and try to avoid making any REST requests.

channelFor(...)Returns:ChannelBehavior?

This function may make REST requests for ThreadMemberUpdateEvent events if the current thread isn't in the cache!

guildFor(...)Returns:GuildBehavior?

Note: This function can't retrieve a guild for GuildAuditLogEntryCreateEvent events, due to an oversight in how both Kord and Discord treat this event.

This function may make REST requests for ThreadMemberUpdateEvent events if the current thread isn't in the cache!

interactionFor(...)Returns:Interaction?

memberFor(...)Returns:MemberBehavior?

messageFor(...)Returns:MessageBehavior?

Note: For ThreadChannelCreateEvent events, this function retrieves the last message in the thread.

This function may make REST requests for MessageUpdateEvent events if the current message isn't in the cache, or for ThreadChannelCreateEvent events if the current thread isn't in the cache!

roleFor(...)Returns:RoleBehavior?

threadFor(...)Returns:ThreadChannelBehavior?

Note: This uses channelFor(), returning null if the current channel isn't a thread.

topChannelFor(...)Returns:ChannelBehavior?

Note: This uses channelFor(), resolving to the parent channel if the current one is a thread.

This function may make REST requests if the current channel isn't in the cache!

userFor(...)Returns:UserBehavior?

Note: Bots can't be in group DMs, so this always uses the first recipient in all DM-specific events.

This function may make REST requests for MessageUpdateEvent events if the current message isn't in the cache!

Logging

The below functions are extension functions against the Kotlin Logging KLogger type.

KLogger.failed(...)

Log that the current check failed, with the given reason.

Arguments

reasonType: String

Reason the check failed.

KLogger.passed(...)

Log that the current check passed, optionally with the given reason.

Arguments

reasonType: String

Reason the check passed. You can omit this if needed.

---

---

KLogger.noCategoryId(...)

Log that the check failed because a category with the given doesn't exist.

Arguments

idType: Snowflake

Category ID.

KLogger.noChannelId(...)

Log that the check failed because a channel with the given ID doesn't exist.

Arguments

idType: Snowflake

Channel ID.

KLogger.noGuildId(...)

Log that the check failed because a guild with the given ID doesn't exist.

Arguments

idType: Snowflake

Guild ID.

KLogger.noRoleId(...)

Log that the check failed because a role with the given ID doesn't exist.

Arguments

idType: Snowflake

Role ID.

KLogger.nullChannel(...)

Log that the channel for the current event is null, and that it may not be supported by this check.

KLogger.nullGuild(...)

Log that the guild for the current event is null, and that it may not be supported by this check.

KLogger.nullMember(...)

Log that the member for the current event is null, and that it may not be supported by this check.

KLogger.nullMessage(...)

Log that the message for the current event is null, and that it may not be supported by this check.

Misc

The below functions can make combining checks easier.

or { ... }Receiver: CheckContext

Acts as an "or" conditional, allowing the current check context to pass if the checks defined in this builder pass, even if the current check context is failing.

If the current check context is still failing after the function runs the provided lambda, it will combine their failure messages with a pipe character (|), assuming both failures generated a message. If the current check context doesn't have a message set but the provided lambda sets one, it will use that instead.

If the current check context is passing, this builder does nothing.

silence(...)

If the current check has a message set, clear it.