Skip to content

Getting Started

Jump to bottom
Gabriel Souza edited this page Jun 25, 2023 · 14 revisions

Guides and instructions

Project structure

Modules

WIP

Plugin Main.

KotlinBukkitAPI works the same as work with any plugin, is not required a new type of definition, you can go just with JavaPlugin.

However, we have a custom Plugin definition called KotlinPlugin, this allows more features for your plugin using KotlinBukkitAPI, like Lifecycles, and we STRONG RECOMMEND to you it. You can check more about the KotlinPlugin here.

class MyTestPlugin : KotlinPlugin() {
  override fun onPluginEnable() {
    println("Hello World!")
  }
  override fun onPluginDisable() {
    println("Goodbye!")
  }
}

Setup with IntelliJ Plugin

Download the KotlinBukkitAPI Tooling plugin in IntelliJ [2020.1..2020.2].

  • Go to File -> Settings -> Plugins -> Marketplace
  • Search for KotlinBukkitAPI Tooling
  • Install it

  • Create new project by going File -> New Project
  • Select the KotlinBukkitAPI Section and setup your plugin.

More about KotlinBukkitAPI Tooling

  • It provides a KotlinBukkitAPI Menu DSL preview.

  • Bukkript script auto resolving.

Setup dependencies manually

Gradle Kotlin DSL

repositories {
  maven("https://raw.githubusercontent.com/KotlinMinecraft/KotlinBukkitAPI-Repository/main")
}

dependencies {
  implementation("br.com.devsrsouza.kotlinbukkitapi:architecture:1.0.0-SNAPSHOT")
}

Toml

[versions]
kotlinbukkitapi = "1.0.0-SNAPSHOT"

[libraries]
kotlinbukkitapi-architecture = { module = "br.com.devsrsouza.kotlinbukkitapi:architecture", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-extensions = { module = "br.com.devsrsouza.kotlinbukkitapi:extensions", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-serialization = { module = "br.com.devsrsouza.kotlinbukkitapi:serialization", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-exposed = { module = "br.com.devsrsouza.kotlinbukkitapi:exposed", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-coroutines = { module = "br.com.devsrsouza.kotlinbukkitapi:coroutines", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-scoreboardLegacy = { module = "br.com.devsrsouza.kotlinbukkitapi:scoreboard-legacy", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-commandLegacy = { module = "br.com.devsrsouza.kotlinbukkitapi:command-legacy", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-menu = { module = "br.com.devsrsouza.kotlinbukkitapi:menu", version.ref = "kotlinbukkitapi" }
kotlinbukkitapi-utility = { module = "br.com.devsrsouza.kotlinbukkitapi:utility", version.ref = "kotlinbukkitapi" }

The recommendation is to go with Gradle Kotlin DSL.

Setup plugin.yml configuration

Your plugin should depend on KotlinBukkitAPI, in this case, you should add it at your plugin.yml.

Your recommendation is that you use Minecrell Gradle Plugin called plugin-yml for auto create the plugin.yml directly from your Gradle script.

bukkit {
    main = "${project.group}.${project.name.toLowerCase()}.${project.name}Plugin"
    author = "Your Name"
    website = "yourwebsite.com"
    depend = listOf("KotlinBukkitAPI")

    description = "The plugin description."
}

This snippet configuration will use your gradle project group + project name for the package and for the Main Class ProjectName + Plugin at the end.

External Dependencies

KotlinBukkitAPI ships with it a couple Kotlin libraries, because of that, you do not need to shade it inside your jar, you can and you should let this to KotlinBukkitAPI provide in the runtime (in the server).

Letting KotlinBukkitAPI take care of these libraries will prevent runtime version conflits with other plugins.

  • Kotlin STD Lib JDK 8
  • Kotlinx.Coroutines
  • Kotlinx.Serialization (runtime)
  • Kaml
  • Skedule

Starter Project

We have a starter project for you with all things configured in Gradle, just clone/download and open in your IntelliJ.

KotlinMinecraft/KBAPI-StarterProject

Preventing conflicts [IMPORTANT]

After you know the External Dependencies that KotlinBukkitAPI provides, now we need to know about your project external dependencies.

If you want to use an external Kotlin library that is not embedded by the KotlinBukkitAPI we recommend you to Shade and relocate or use PDM gradle plugin.

But you need to be careful, if the library depend on Kotlin (if is a library for Kotlin) you should ALWAYS exclude kotlin to prevent conflit version with the KotlinBukkitAPI version.

You should add the following configuration to your library dependency in Gradle build.

dependencies {
   implementation("your-library") {
      exclude(module = "kotlin-stdlib")
      exclude(module = "kotlin-reflect")
      exclude(module = "kotlinx-coroutines-core")
      exclude(module = "kotlinx-serialization-core")
   }
}

If you have multiple libraries this could get big

dependencies {
   fun ExternalModuleDependency.excluding() {
      exclude(module = "kotlin-stdlib")
      exclude(module = "kotlin-reflect")
      exclude(module = "kotlinx-coroutines-core")
      exclude(module = "kotlinx-serialization-core")
   }
   
   implementation("first-library", ::excluding)
   implementation("second-library", ::excluding)
   implementation("third-library") {
     excluding()
     exclude(module = "your own exclude for or third library")
   }

This is all common cases, but KotlinBukkitAPI embedded more libraris inside it, you can check all here Dep.kt.

KotlinBukkitAPI Tooling auto generates the gradle with this excluding function to you use in your dependencies.

Setup in existent Kotlin project

After we know about all dependencies that KotlinBukkitAPI ships on it and how to prevent conflicts with your project dependencies, now, we can setup KotlinBukkitAPI in an existent project.

First steps

  • Add KotlinBukkitAPI to depend in plugin.yml
Clone this wiki locally