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.

Getting inputs

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.

Example

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!")
    }
  }
}