-
Notifications
You must be signed in to change notification settings - Fork 4
Conversation API
Conversations can be used to get larger inputs from players than we can from other methods like Anvil GUI inputs.
KtGUI brings a robust and adaptable yet lightweight api to the table.
To start a conversation:
// `plugin` arg is optional, by default, KtGUI will use `GuiManager.owningPlugin`
conversation(plugin) {
}.begin(conversable)
Please Note
By default, when a conversation begins, KtGUI will attempt to close the current GUI that the user has open. You can disable this by changing closeGuiOnStart
to false
.
Additionally, KtGUI will attempt to re-open the previously open GUI once the conversation has ended. You can disable this by changing openGuiOnEnd
to false
.
KtGUI comes built-in with the following inputs:
-
getString
Gets a simple string -
getChoice
Gets a string input, from a specified choice of strings -
getRegExp
Gets a string that matches a given regex -
getEnum
Gets an enum value by name getInteger
getLong
getDouble
getFloat
To create your own options, you can extend the class RawConversationStep<T, C>
where T
is the variable class, and C
is the Conversable
provided by the Conversation builder.
For example, here is a JSON conversation step.
class JsonConversationStep<C : Conversable> : RawConversationStep<JsonElement, C>() {
override fun validate(input: String?): Optional<JsonElement> {
if (input == null) return Optional.empty()
val jsonResult = runCatching {
JsonParser.parseString(input)
}
return Optional.ofNullable(jsonResult.getOrNull())
}
}
For simple options, you should override the validate
method, which takes in a nullable string, and returns an Optional
containing an instance of your class T
after being parsed or handled. Returning an empty optional will cause the input to be seen as invalid.
conversation<Player> {
// Exit if the user types 'cancel'
exitOn = "cancel"
getString {
message = !"&7Please input a username"
matches { result.isPresent && result.get().length in (3..16) }
runs {
conversable.sendMessage(!"&7Your username is now ${result}")
}
invalid {
conversable.sendMessage(!"&cThat username is invalid!")
}
}
getInteger {
title = !"&aInput your age"
range = (0..99)
repeatIfInvalid = false
runs {
conversable.sendMessage(!"&7You will be ${result.get() + 1} years old next year")
}
invalid {
conversable.sendMessage(!"&cYou can't be that old!")
}
}
}