azuyamat / mccollector

Securely and efficiently prompt players for input in Minecraft

MCCollector 📜

Made with ❤️ by Azuyamat

Consider adding a star ⭐ if you find this project useful!

Details

MCCollector is a library which replicates the functionality Discord.js message collectors into Minecraft. It allows you to collect messages from players in a similar way to how you would with Discord.js. Collectors are useful for creating secure and efficient prompts. They allow you to inquire information from players in a controlled manner.

Some examples of what you can do with collectors:

• Prompt player for username that respects a certain format
• Prompt certainty with a yes/no question before proceeding (I.e "Are you sure you want to delete this?")
• Prompt player for a number within a certain range
• Ask moderator for a reason before banning a player

Installation

Gradle

repositories {
    maven { url = "https://jitpack.io" }
}

dependencies {
    implementation "com.github.Azuyamat:MCCollector:VERSION"
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.Azuyamat</groupId>
    <artifactId>MCCollector</artifactId>
    <version>VERSION</version>
</dependency>

Features

• Chat message collectors (I.e. player types a message)
• Location collector (I.e. player clicks on a block)
• Inventory collector (I.e. player clicks an item in their inventory)
• Entity collector (I.e. player clicks on an entity)

Let me know if you have any other ideas for collectors! 😄

Usage

Warning

If you are placing blocks in any of the callbacks, make sure to run them on the main thread. You can use Bukkit.getScheduler().runTask(plugin, runnable) to run code on the main thread. This limitation is not one of MCCollector, but rather Bukkit's API.

Initialization

class MyPlugin : JavaPlugin() {
    override fun onEnable() {
        CollectorRegistry.init(this)
    }
}

Basic Example

Note

onCommand is used as an example, you would have you own method to handle commands.

fun onCommand(...) {
    val collector = ChatCollectorBuilder {
        player.sendMessage("Type 'hello' to continue.")
    }.applyPrefab(MessagesPrefab(player)) // Apply default messages (Ex: "Invalid input" in red)
    .buildAndRegister(player) // Build and register the collector to the player
}

Advanced Example

fun onCommand(...) {
    val collector = ChatCollectorBuilder {
        player.sendMessage("Provide a name for your island.")
    }.withTimeout(10000)
        .onCollect {
            player.sendMessage("Creating island: $it")
        }
        .onCancel {
            player.sendMessage("Island creation cancelled.")
        }
        .onTimeout {
            player.sendMessage("Island creation timed out.")
        }
        .verifyValue {
            if (it.length > 3) {
                Verifiable.ValidationResult.valid()
            } else {
                Verifiable.ValidationResult.invalid("Island name must be longer than 3 characters.")
            }
        }
        .build(player).register() // Or use .buildAndRegister(player)
}

For more examples, check out the wiki. (Coming soon)

Contributing

If this projects interests you, feel free to contribute! You can do so by forking the repository and submitting a pull request. If you have any questions or concerns, feel free to open an issue.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.