DOCSEARCHbyAlgolia
Submit Docs

Kord Extensions Documentation

website·Indexed 32 days ago

https://docs.kordex.dev

A framework for building Discord bots with Kord, featuring extensible bot builders, command frameworks, i18n translation support, and event handlers. Includes documentation for the ExtensibleBot builder, component registries, sharding configuration, and associated Gradle plugins.

Tokens
46.8K
Snippets
170
Records
378
Agent score
58%

What's inside Kord Extensions

  1. Overview of Kord Extensions licensing

    Kord Extensions utilizes a specific set of open and public source licenses depending on the project type. The primary licenses used are:

    • Creative Commons Zero (CC0): Used for documentation (public domain dedication).
    • European Public Licence (EUPL): An open-source license positioned between LGPL and AGPL.
    • Mozilla Public Licence (MPL): A less-restrictive license primarily applied to library projects.
    • The Unlicense: A public domain dedication specifically for software projects.

  2. Overview of the Kord Extensions i18n Framework approach

    The Kord Extensions i18n framework provides an object-oriented approach to internationalization, designed to avoid the pitfalls of traditional tools. Key architectural features include:

    • Immutable Key Objects: Translation keys are represented by Key objects that can be cloned to include contextual data, such as pre-filled placeholders, post-processors, and target locales.
    • Immutable Bundle Objects: Bundle objects manage references to resource bundles, including information on file/message formats and the specific classloader used for loading.
    • Non-Annotation Based Code Generation: The framework provides code generators that read translation files directly to provide compile-time safety in Kotlin, rather than relying on opaque annotation processors.
    • Flexible Format Support: Supports arbitrary file and message formats via service providers, with first-party support for Properties, YAML, and ICU v1 and v2 messages.
    • ICU4J Integration: ICU4J is provided as an api dependency, making its tools directly available to developers.

  3. Overview of Discord Context Commands in Kordex

    Context commands are a special type of application command invoked by users via a right-click or tap-and-hold "Apps" menu in the Discord client. Unlike slash commands, they do not take arguments; instead, they receive the object (message or user) the user was targeting when the menu was opened. There are two types: message and user commands.

  4. Overview of the Kord Extensions i18n Framework

    The Kord Extensions Internationalisation (i18n) Framework provides a type-safe, object-oriented approach to adding translations to Kotlin/JVM applications. Unlike traditional frameworks, it utilizes code generation based on translation source files, allowing developers to use immutable references to translation keys. It supports pluggable file and message formats, ensuring compatibility with existing tooling and preferred translation formats.

  5. Overview of Kordex i18n translation code generation

    The Kordex i18n framework provides a code generator that produces 'translations classes'. These classes are Kotlin objects containing a nested tree of Key objects (representing individual translations) and a Bundle object (referencing the source bundle). This system ensures a type-safe translations API, allowing the Kotlin compiler to verify that translation keys exist at compile-time, reducing errors associated with manual key string management.

  6. Understand Kordex Command Converters

    Converters in Kordex are used to handle individual command arguments. They are responsible for parsing and validating input and converting those arguments into rich types using a type-safe, reflection-free API.

  7. Update the 'about' builder in KordEx v2.2.0-SNAPSHOT

    In v2.2.0-SNAPSHOT, the about { } builder for extensions was rewritten. The default 'general' information command and mandatory footer were removed. Developers can now create fully custom commands, though a default configurable 'copyright' subcommand is still provided.

  8. Configure the bot about command

    The about { } builder is used to configure the bot's about command. This command includes a mandatory copyright section (required by the EUPL license) and allows for the addition of custom informational sections as subcommands. You can set a global ephemeral property to determine if the command responses are hidden from other users by default.
    about {
    ephemeral = true  // Global default for all about subcommands

    general {
        ephemeral = false  // Override for this specific section
        message { locale ->
            content = "General message content goes here!"
        }
    }

    section(
        Translations.About.Sections.Secondary.name,
        Translations.About.Sections.Secondary.description
    ) {
        message { locale ->
            content = "More content here!"
            embed {
                description = "Maybe even an embed?"
            }
        }
    }
}

  9. Understand Kordex project licensing with MPL 2.0

    Kordex uses the Mozilla Public License (MPL) version 2.0 for specific projects, including their Gradle plugins and internationalisation framework. The MPL 2.0 is a simple copyleft license applied to individual files, allowing developers to combine MPL-licensed code with code under other licenses with minimal restrictions. It is used for projects where a more permissive license than the EUPL is appropriate to maintain developer freedom.

  10. Add copyright notices from a custom module

    When developing a module, library, or meta-framework, you can programmatically add copyright information to the bot's about command by accessing the aboutBuilder within the bot settings during the extension's setup phase.
    private var copyrightAdded = false

internal fun AboutBuilder.addCopyright() {
    if (!copyrightAdded) {
        copyright(
            "Time4J",
            "LGPL-2.1",
            CopyrightType.Library,
            "http://time4j.net/"
        )
    }
    copyrightAdded = true
}

class MyExtension : Extension() {
    override fun setup() {
        bot.settings.aboutBuilder.addCopyright()
    }
}

  11. ApplicationCommand base class overview

    The ApplicationCommand abstract class is the base type for all application commands. It extends the basic Command type and provides common APIs for registration, scoping, and execution. It uses a type parameter E (of type InteractionCreateEvent) to represent the events that trigger the command.

  12. Understand Kord Extensions Command Converters

    Converters transform command arguments from basic representations (typically Strings) into rich types. They are implemented as classes extending the Converter type and annotated with @Converter. Converters can parse string-based values, transform Discord entities/Snowflakes, or wrap other converters to modify their behavior.