search

Kord-Extensions / ext-mappings

Minecraft mappings extension
MIT License
0 stars 2 forks source link

readme

Mappings Extension

Discord: Click here Release Snapshot

This module contains an extension written to provide Minecraft mappings information on Discord. It makes heavy use of linkie-core, which (as of this writing) supports MCP, Mojang and Yarn mappings.

If you're looking for older versions (and older tags), you can find them in the now-archived kordex-modules repository.

Getting Started

At its simplest, you can add this extension directly to your bot with no further configuration. For example:

suspend fun main() {
    val bot = ExtensibleBot(System.getenv("TOKEN")) {
        commands {
            defaultPrefix = "!"
        }

        extensions {
            extMappings { }
        }
    }

    bot.start()
}

This will install the extension using its default configuration, which enables all mappings namespaces and does not restrict the commands in any manner. Additional options are available in the extMappings builder for you to use - they're detailed below.

Usage

This extension provides a number of commands for use on Discord.

Configuration

This extension makes use of the Konf library for configuration. Included in the JAR is a default configuration file, kordex/mappings/default.toml. You may configure the extension in one of the following ways:

For an example, feel free to read the included default.toml. The following configuration keys are available:

Please note: Mappings commands will always function when sent to the bot via a private message. However, only the configured namespaces will be available - the user will not be able to query disabled namespaces.

Customisation

This extension supports two primary methods of customization: Replacing the config adapter, and registering custom checks. While the options do require some programming, they should help you to customize its behaviour to suit your bot's needs.

Custom Checks

As described in the Kord Extensions documentation, Kord Extensions provides a system of checks that can be applied to commands and other event handlers. Checks essentially allow you to prevent execution of a command depending on the context it was executed within.

This extension allows you to register custom checks by calling the commandCheck() and namespaceCheck() functions in the builder, as follows:

val gdudeSnowflake = Snowflake("109040264529608704")
val yarrnChannelId = Snowflake("...")

suspend fun main() {
    val bot = ExtensibleBot(System.getenv("TOKEN")) {
        commands {
            defaultPrefix = "!"
        }

        extensions {
            extMappings {
                commandCheck { command ->  // This is the command name
                    { event -> 
                        if (command == "yarn") { // Only limit usage of the `yarn` command
                            event.message.author?.id != gdudeSnowflake  // We don't want gdude using this
                        } else {
                            true
                        }
                    }
                }

                namespaceCheck { namespace ->  // This is the Linkie namespace in use
                    { event ->
                        // If it's not a Yarrn command, or it is a Yarrn command and we're in the Yarrn channel, it's OK
                        namespace != YarrnNamespace || event.channel.id == yarrnChannelId
                    }
                }
            }
        }
    }

    bot.start()
}

You can also write this using functions instead of lambdas, of course.

val gdudeSnowflake = Snowflake("109040264529608704")

suspend fun mappingsCheck(namespace: Namespace): suspend (MessageCreateEvent) -> Boolean {
    suspend fun inner(event: MessageCreateEvent): Boolean =
        if (namespace == YarnNamespace) {  // Only limit usage of the `yarn` commands
            event.message.author?.id != gdudeSnowflake  // We don't want gdude using this
        } else {
            true
        }

    return ::inner
}

suspend fun main() {
    val bot = ExtensibleBot(System.getenv("TOKEN")) {
        commands {
            defaultPrefix = "!"
        }

        extensions {
            extMappings {
              namespaceCheck(::mappingsCheck)
            }
        }
    }

    bot.start()
}

The approach you take is up to you!

Replacing the Config Adapter

If you need some other form of configuration - for example, from a database - you can implement the MappingsConfigAdapater interface in your own classes and store an instance of it in the config variable in the builder. While going into detail on each function is a little out of scope for this document, you can find more information in the following places:

suspend fun main() {
    val bot = ExtensibleBot(System.getenv("TOKEN")) {
        commands {
            defaultPrefix = "!"
        }

        extensions {
            extMappings {
                config = CustomMappingsConfig()
            }
        }
    }

    bot.start()
}

Licensing & Attribution

This extension makes use of linkie-core, and contains code adapted from linkie-discord. Both projects are licensed under the Apache License 2.0, which you can find in LICENSE-linkie.md, distributed within the ext-mappings JAR, on the linkie-core GitHub or on the linkie-discord GitHub. Both linkie-core and linkie-discord are property of shedaniel.